[rtems-central commit] spec: Update /rtems/init/* and /rtems/fatal/* docs

Sebastian Huber sebh at rtems.org
Thu Apr 22 05:15:37 UTC 2021


Module:    rtems-central
Branch:    master
Commit:    4c96de52ff404a83979c34d38d96e4042ee81879
Changeset: http://git.rtems.org/rtems-central/commit/?id=4c96de52ff404a83979c34d38d96e4042ee81879

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Apr 21 09:52:14 2021 +0200

spec: Update /rtems/init/* and /rtems/fatal/* docs

---

 spec/bsp/if/boot-card.yml                         | 12 ++++++
 spec/bsp/if/domain.yml                            | 11 ++++++
 spec/bsp/if/header.yml                            | 13 ++++++
 spec/c/if/atexit.yml                              | 12 ++++++
 spec/c/if/exit.yml                                | 12 ++++++
 spec/c/if/on-exit.yml                             | 12 ++++++
 spec/constraint/directive-no-return.yml           | 10 +++++
 spec/constraint/extensions-fatal.yml              | 11 ++++++
 spec/constraint/no-atexit.yml                     | 11 ++++++
 spec/constraint/terminate.yml                     | 10 +++++
 spec/rtems/fatal/if/assert-context.yml            | 24 +++++++-----
 spec/rtems/fatal/if/error-occurred.yml            | 30 +++++++++++---
 spec/rtems/fatal/if/exception-frame-print.yml     | 13 ++++--
 spec/rtems/fatal/if/exception-frame.yml           |  5 ++-
 spec/rtems/fatal/if/fatal.yml                     | 32 +++++++++++----
 spec/rtems/fatal/if/group.yml                     | 18 ++++++++-
 spec/rtems/fatal/if/internal-error-text.yml       | 22 ++++++++---
 spec/rtems/fatal/if/panic.yml                     | 31 ++++++++++++---
 spec/rtems/fatal/if/shutdown-executive.yml        | 48 +++++++++++++++++++++++
 spec/rtems/fatal/if/source-text.yml               | 24 ++++++++----
 spec/rtems/init/constraint/directive-ctx-boot.yml | 10 +++++
 spec/rtems/init/if/group.yml                      | 16 ++++----
 spec/rtems/init/if/initialize-executive.yml       | 14 ++++---
 spec/rtems/init/if/shutdown-executive.yml         | 37 -----------------
 spec/score/interr/if/internal-error-rtems-api.yml | 12 ++++++
 spec/score/interr/if/source-exit.yml              | 12 ++++++
 spec/score/interr/if/source-panic.yml             | 12 ++++++
 27 files changed, 375 insertions(+), 99 deletions(-)

diff --git a/spec/bsp/if/boot-card.yml b/spec/bsp/if/boot-card.yml
new file mode 100644
index 0000000..f33061f
--- /dev/null
+++ b/spec/bsp/if/boot-card.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: header
+name: boot_card
+reference: null
+type: interface
diff --git a/spec/bsp/if/domain.yml b/spec/bsp/if/domain.yml
new file mode 100644
index 0000000..fe3d022
--- /dev/null
+++ b/spec/bsp/if/domain.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+description: |
+  This interface domain contains interfaces used by ${/glossary/bsp:/plural}.
+enabled-by: true
+index-entries: []
+interface-type: domain
+links: []
+name: BSP
+type: interface
diff --git a/spec/bsp/if/header.yml b/spec/bsp/if/header.yml
new file mode 100644
index 0000000..b810985
--- /dev/null
+++ b/spec/bsp/if/header.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: This header file defines interfaces to boot the system.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: header-file
+links:
+- role: interface-placement
+  uid: domain
+path: bsp/bootcard.h
+prefix: bsps/include
+type: interface
diff --git a/spec/c/if/atexit.yml b/spec/c/if/atexit.yml
new file mode 100644
index 0000000..0464ec9
--- /dev/null
+++ b/spec/c/if/atexit.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: stdlib
+name: atexit
+reference: null
+type: interface
diff --git a/spec/c/if/exit.yml b/spec/c/if/exit.yml
new file mode 100644
index 0000000..c0434c5
--- /dev/null
+++ b/spec/c/if/exit.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: stdlib
+name: exit
+reference: null
+type: interface
diff --git a/spec/c/if/on-exit.yml b/spec/c/if/on-exit.yml
new file mode 100644
index 0000000..65e2acf
--- /dev/null
+++ b/spec/c/if/on-exit.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: stdlib
+name: on_exit
+reference: null
+type: interface
diff --git a/spec/constraint/directive-no-return.yml b/spec/constraint/directive-no-return.yml
new file mode 100644
index 0000000..7566acd
--- /dev/null
+++ b/spec/constraint/directive-no-return.yml
@@ -0,0 +1,10 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive will not return to the caller.
+type: constraint
diff --git a/spec/constraint/extensions-fatal.yml b/spec/constraint/extensions-fatal.yml
new file mode 100644
index 0000000..759ef11
--- /dev/null
+++ b/spec/constraint/extensions-fatal.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive invokes the fatal error extensions in
+  ${/glossary/extension-forward-order:/term}.
+type: constraint
diff --git a/spec/constraint/no-atexit.yml b/spec/constraint/no-atexit.yml
new file mode 100644
index 0000000..d4d848d
--- /dev/null
+++ b/spec/constraint/no-atexit.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive does not invoke handlers registered by ${/c/if/atexit:/name}
+  or ${/c/if/on-exit:/name}.
+type: constraint
diff --git a/spec/constraint/terminate.yml b/spec/constraint/terminate.yml
new file mode 100644
index 0000000..4002ba8
--- /dev/null
+++ b/spec/constraint/terminate.yml
@@ -0,0 +1,10 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive may terminate the system.
+type: constraint
diff --git a/spec/rtems/fatal/if/assert-context.yml b/spec/rtems/fatal/if/assert-context.yml
index 2b882b5..a82625c 100644
--- a/spec/rtems/fatal/if/assert-context.yml
+++ b/spec/rtems/fatal/if/assert-context.yml
@@ -1,38 +1,42 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This structure provides the context in which an assertion failed.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
 - default:
     brief: |
-      This member is
+      This member provides the file name of the source code file containing the
+      failed assertion statement.
     definition: const char *${.:name}
-    description: '%'
+    description: null
     kind: member
     name: file
   variants: []
 - default:
     brief: |
-      This member is
+      This member provides the line number in the source code file containing
+      the failed assertion statement.
     definition: int ${.:name}
-    description: '%'
+    description: null
     kind: member
     name: line
   variants: []
 - default:
     brief: |
-      This member is
+      This member provides the function name containing the failed assertion
+      statement.
     definition: const char *${.:name}
-    description: '%'
+    description: null
     kind: member
     name: function
   variants: []
 - default:
     brief: |
-      This member is
+      This member provides the expression of the failed assertion statement.
     definition: const char *${.:name}
-    description: '%'
+    description: null
     kind: member
     name: failed_expression
   variants: []
diff --git a/spec/rtems/fatal/if/error-occurred.yml b/spec/rtems/fatal/if/error-occurred.yml
index 0bd33d1..98da1cf 100644
--- a/spec/rtems/fatal/if/error-occurred.yml
+++ b/spec/rtems/fatal/if/error-occurred.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Invokes the fatal error handler.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,7 +12,10 @@ definition:
     - ${/c/if/uint32_t:/name} ${.:/params[0]/name}
     return: void
   variants: []
-description: null
+description: |
+  This directive processes fatal errors.  The fatal source is set to
+  ${/score/interr/if/internal-error-rtems-api:/name}.  The fatal code is set to
+  the value of the ${.:/params[0]/name} parameter.
 enabled-by: true
 index-entries: []
 interface-type: function
@@ -20,12 +24,26 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-return
+- role: constraint
+  uid: /constraint/extensions-fatal
+- role: constraint
+  uid: /constraint/no-atexit
+- role: constraint
+  uid: /constraint/terminate
 name: rtems_fatal_error_occurred
-notes: null
+notes: |
+  This directive is deprecated and should not be used in new code.  It is
+  recommended to not use this directive since error locations cannot be
+  uniquely identified.  A recommended alternative directive is ${fatal:/name}.
 params:
-- description: '%'
+- description: |
+    is the fatal code.
   dir: null
-  name: the_error
+  name: fatal_code
 return:
   return: null
   return-values: []
diff --git a/spec/rtems/fatal/if/exception-frame-print.yml b/spec/rtems/fatal/if/exception-frame-print.yml
index 2587482..653235d 100644
--- a/spec/rtems/fatal/if/exception-frame-print.yml
+++ b/spec/rtems/fatal/if/exception-frame-print.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Prints the exception frame.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,9 +13,12 @@ definition:
     - const ${exception-frame:/name} *${.:/params[0]/name}
     return: void
   variants: []
-description: null
+description: |
+  The exception frame is printed in an architecture-dependent format using
+  ${../../io/if/printk:/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- exception frame
 interface-type: function
 links:
 - role: interface-placement
@@ -24,7 +28,8 @@ links:
 name: rtems_exception_frame_print
 notes: null
 params:
-- description: '%'
+- description: |
+    is the reference to the exception frame to print.
   dir: null
   name: frame
 return:
diff --git a/spec/rtems/fatal/if/exception-frame.yml b/spec/rtems/fatal/if/exception-frame.yml
index 33bf0e4..0aaced3 100644
--- a/spec/rtems/fatal/if/exception-frame.yml
+++ b/spec/rtems/fatal/if/exception-frame.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This structure represents an architecture-dependent exception frame.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: ${/score/cpu/if/exception-frame:/name} ${.:/name}
diff --git a/spec/rtems/fatal/if/fatal.yml b/spec/rtems/fatal/if/fatal.yml
index e04bf62..57a0d92 100644
--- a/spec/rtems/fatal/if/fatal.yml
+++ b/spec/rtems/fatal/if/fatal.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Invokes the fatal error handler.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,24 +14,41 @@ definition:
     - ${../../userext/if/fatal-code:/name} ${.:/params[1]/name}
     return: void
   variants: []
-description: null
+description: |
+  This directive processes fatal errors.  The fatal source is set to the value
+  of the ${.:/params[0]/name} parameter.  The fatal code is set to the value of
+  the ${.:/params[1]/name} parameter.
 enabled-by: true
-index-entries: []
+index-entries:
+- announce fatal error
+- fatal error, announce
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-return
+- role: constraint
+  uid: /constraint/extensions-fatal
+- role: constraint
+  uid: /constraint/no-atexit
+- role: constraint
+  uid: /constraint/terminate
 name: rtems_fatal
 notes: null
 params:
-- description: '%'
+- description: |
+    is the fatal source.
   dir: null
   name: fatal_source
-- description: '%'
+- description: |
+    is the fatal code.
   dir: null
-  name: error_code
+  name: fatal_code
 return:
   return: null
   return-values: []
diff --git a/spec/rtems/fatal/if/group.yml b/spec/rtems/fatal/if/group.yml
index 550d45f..87b0046 100644
--- a/spec/rtems/fatal/if/group.yml
+++ b/spec/rtems/fatal/if/group.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
   The Fatal Error Manager processes all fatal or irrecoverable errors and other
-  sources of system termination (for example after ``exit()``).  Fatal errors
-  are identified by the fatal source and error code pair.
+  sources of system termination (for example after ${/c/if/exit:/name}).  Fatal
+  errors are identified by the fatal source and code pair.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -16,6 +16,20 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
+- role: placement-order
+  uid: fatal
+- role: placement-order
+  uid: panic
+- role: placement-order
+  uid: shutdown-executive
+- role: placement-order
+  uid: exception-frame-print
+- role: placement-order
+  uid: source-text
+- role: placement-order
+  uid: internal-error-text
+- role: placement-order
+  uid: error-occurred
 name: Fatal Error Manager
 text: |
   The Classic API shall provide an interface to the Fatal Error Manager.
diff --git a/spec/rtems/fatal/if/internal-error-text.yml b/spec/rtems/fatal/if/internal-error-text.yml
index faf56f8..6cec440 100644
--- a/spec/rtems/fatal/if/internal-error-text.yml
+++ b/spec/rtems/fatal/if/internal-error-text.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns a descriptive text for the internal error code.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -13,20 +14,29 @@ definition:
   variants: []
 description: null
 enabled-by: true
-index-entries: []
+index-entries:
+- fatal error
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
 name: rtems_internal_error_text
 notes: null
 params:
-- description: '%'
+- description: |
+    is the internal error code.
   dir: null
-  name: error
+  name: internal_error_code
 return:
-  return: null
-  return-values: []
+  return: |
+    Returns a descriptive text for the internal error code.  The text for the
+    internal error code is the enumerator constant name.
+  return-values:
+  - description: |
+      The ${.:/params[0]/name} parameter value was not an internal error code.
+    value: '"?"'
 type: interface
diff --git a/spec/rtems/fatal/if/panic.yml b/spec/rtems/fatal/if/panic.yml
index 112399c..931876b 100644
--- a/spec/rtems/fatal/if/panic.yml
+++ b/spec/rtems/fatal/if/panic.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Prints the message and invokes the fatal error handler.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,22 +14,40 @@ definition:
     - '...'
     return: void
   variants: []
-description: null
+description: |
+  This directive prints a message via ${../../io/if/printk:/name} specified by
+  the ${.:/params[0]/name} parameter and optional parameters and then invokes
+  the fatal error handler.  The fatal source is set to
+  ${/score/interr/if/source-panic:/name}.  The fatal code is set to the value
+  of the ${.:/params[0]/name} parameter value.
 enabled-by: true
-index-entries: []
+index-entries:
+- panic
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-return
+- role: constraint
+  uid: /constraint/extensions-fatal
+- role: constraint
+  uid: /constraint/no-atexit
+- role: constraint
+  uid: /constraint/terminate
 name: rtems_panic
 notes: null
 params:
-- description: '%'
+- description: |
+    is the message format.
   dir: null
   name: fmt
-- description: '%'
+- description: |
+    is a list of optional parameters required by the message format.
   dir: null
   name: '...'
 return:
diff --git a/spec/rtems/fatal/if/shutdown-executive.yml b/spec/rtems/fatal/if/shutdown-executive.yml
new file mode 100644
index 0000000..b66884f
--- /dev/null
+++ b/spec/rtems/fatal/if/shutdown-executive.yml
@@ -0,0 +1,48 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Invokes the fatal error handler.
+copyrights:
+- Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: ${../../basedefs/if/no-return:/name}
+    body: null
+    params:
+    - ${/c/if/uint32_t:/name} ${.:/params[0]/name}
+    return: void
+  variants: []
+description: |
+  This directive processes fatal errors.  The fatal source is set to
+  ${/score/interr/if/source-exit:/name}.  The fatal code is set to the value of
+  the ${.:/params[0]/name} parameter.
+enabled-by: true
+index-entries:
+- shutdown RTEMS
+interface-type: function
+links:
+- role: interface-placement
+  uid: ../../init/if/header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-return
+- role: constraint
+  uid: /constraint/extensions-fatal
+- role: constraint
+  uid: /constraint/no-atexit
+- role: constraint
+  uid: /constraint/terminate
+name: rtems_shutdown_executive
+notes: null
+params:
+- description: |
+    is the fatal code.
+  dir: null
+  name: fatal_code
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/fatal/if/source-text.yml b/spec/rtems/fatal/if/source-text.yml
index 751071c..cadc1fc 100644
--- a/spec/rtems/fatal/if/source-text.yml
+++ b/spec/rtems/fatal/if/source-text.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns a descriptive text for the fatal source.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,20 +14,29 @@ definition:
   variants: []
 description: null
 enabled-by: true
-index-entries: []
+index-entries:
+- fatal error
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
 name: rtems_fatal_source_text
 notes: null
 params:
-- description: '%'
+- description: |
+    is the fatal source.
   dir: null
-  name: source
+  name: fatal_source
 return:
-  return: null
-  return-values: []
+  return: |
+    Returns a descriptive text for the fatal source.  The text for the fatal
+    source is the enumerator constant name.
+  return-values:
+  - description: |
+      The ${.:/params[0]/name} parameter value was not a fatal source.
+    value: '"?"'
 type: interface
diff --git a/spec/rtems/init/constraint/directive-ctx-boot.yml b/spec/rtems/init/constraint/directive-ctx-boot.yml
new file mode 100644
index 0000000..f313b88
--- /dev/null
+++ b/spec/rtems/init/constraint/directive-ctx-boot.yml
@@ -0,0 +1,10 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive should be called by ${/bsp/if/boot-card:/name} only.
+type: constraint
diff --git a/spec/rtems/init/if/group.yml b/spec/rtems/init/if/group.yml
index a9b3996..2553737 100644
--- a/spec/rtems/init/if/group.yml
+++ b/spec/rtems/init/if/group.yml
@@ -1,10 +1,13 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  This group contains directives to initialize and shutdown the RTEMS
-  executive.
+  The Initialization Manager is responsible for initializing the system.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-description: null
+- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+description: |
+  The system initialization includes the initialization of the Board Support
+  Package, RTEMS, device drivers, the root filesystem, and the application.
+  The ${../../fatal/if/group:/name} is responsible for the system shutdown.
 enabled-by: true
 identifier: RTEMSAPIClassicInit
 index-entries: []
@@ -14,8 +17,7 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
-name: Initialization and Shutdown
+name: Initialization Manager
 text: |
-  The Classic API shall provide an interface to the Initialization and Shutdown
-  Manager.
+  The Classic API shall provide an interface to the Initialization Manager.
 type: interface
diff --git a/spec/rtems/init/if/initialize-executive.yml b/spec/rtems/init/if/initialize-executive.yml
index 3e0095b..158bb0f 100644
--- a/spec/rtems/init/if/initialize-executive.yml
+++ b/spec/rtems/init/if/initialize-executive.yml
@@ -14,19 +14,23 @@ description: |
   Iterates through the system initialization linker set and invokes the
   registered handlers.  The final step is to start multitasking.
 enabled-by: true
-index-entries: []
+index-entries:
+- initialize RTEMS
+- start multitasking
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: ../constraint/directive-ctx-boot
+- role: constraint
+  uid: /constraint/directive-no-return
 name: rtems_initialize_executive
 notes: |
-  This directive should be called by boot_card() only.
-
-  This directive does not return to the caller.  Errors in the initialization
-  sequence are usually fatal and lead to a system termination.
+  Errors in the initialization sequence are usually fatal and lead to a system
+  termination.
 params: []
 return:
   return: null
diff --git a/spec/rtems/init/if/shutdown-executive.yml b/spec/rtems/init/if/shutdown-executive.yml
deleted file mode 100644
index 7679b1a..0000000
--- a/spec/rtems/init/if/shutdown-executive.yml
+++ /dev/null
@@ -1,37 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: |
-  Shuts down the RTEMS environment.
-copyrights:
-- Copyright (C) 2015, 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR)
-definition:
-  default:
-    attributes: ${../../basedefs/if/no-return:/name}
-    body: null
-    params:
-    - ${/c/if/uint32_t:/name} ${.:/params[0]/name}
-    return: void
-  variants: []
-description: |
-  The invocation of this directive results in the RTEMS environment being
-  shutdown and multitasking halted.  The system is terminated with a fatal
-  source of RTEMS_FATAL_SOURCE_EXIT and the specified result code.
-enabled-by: true
-index-entries: []
-interface-type: function
-links:
-- role: interface-placement
-  uid: header
-- role: interface-ingroup
-  uid: group
-name: rtems_shutdown_executive
-notes: |
-  This directive does not return to the caller.
-params:
-- description: is the result code.
-  dir: null
-  name: result
-return:
-  return: null
-  return-values: []
-type: interface
diff --git a/spec/score/interr/if/internal-error-rtems-api.yml b/spec/score/interr/if/internal-error-rtems-api.yml
new file mode 100644
index 0000000..3f73fb4
--- /dev/null
+++ b/spec/score/interr/if/internal-error-rtems-api.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: INTERNAL_ERROR_RTEMS_API
+reference: null
+type: interface
diff --git a/spec/score/interr/if/source-exit.yml b/spec/score/interr/if/source-exit.yml
new file mode 100644
index 0000000..d94d2f4
--- /dev/null
+++ b/spec/score/interr/if/source-exit.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: RTEMS_FATAL_SOURCE_EXIT
+reference: null
+type: interface
diff --git a/spec/score/interr/if/source-panic.yml b/spec/score/interr/if/source-panic.yml
new file mode 100644
index 0000000..5fc4940
--- /dev/null
+++ b/spec/score/interr/if/source-panic.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: RTEMS_FATAL_SOURCE_PANIC
+reference: null
+type: interface



More information about the vc mailing list