diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-04-21 09:19:27 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-04-21 09:35:58 +0200 |
commit | f3262d40745c4109f529e0456e011c85bf134917 (patch) | |
tree | 7da3f060070d6ec29616f92ae98ad90c60992445 /c-user | |
parent | c-user: Document rtems_semaphore_obtain() errors (diff) | |
download | rtems-docs-f3262d40745c4109f529e0456e011c85bf134917.tar.bz2 |
c-user: Split up initialization manager
This makes it easier to automatically generate parts of the module
documentation in the future.
Update #3993.
Diffstat (limited to 'c-user')
-rw-r--r-- | c-user/index.rst | 2 | ||||
-rw-r--r-- | c-user/initialization/background.rst | 48 | ||||
-rw-r--r-- | c-user/initialization/directives.rst | 41 | ||||
-rw-r--r-- | c-user/initialization/index.rst | 15 | ||||
-rw-r--r-- | c-user/initialization/introduction.rst | 15 | ||||
-rw-r--r-- | c-user/initialization/operations.rst (renamed from c-user/initialization.rst) | 98 |
6 files changed, 120 insertions, 99 deletions
diff --git a/c-user/index.rst b/c-user/index.rst index 2f8109a..0a05c75 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -29,7 +29,7 @@ RTEMS Classic API Guide (|version|). key_concepts rtems_data_types scheduling-concepts/index - initialization + initialization/index task/index interrupt/index clock/index diff --git a/c-user/initialization/background.rst b/c-user/initialization/background.rst new file mode 100644 index 0000000..36d8ebd --- /dev/null +++ b/c-user/initialization/background.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: initialization tasks + +Initialization Tasks +-------------------- + +Initialization task(s) are the mechanism by which RTEMS transfers initial +control to the user's application. Initialization tasks differ from other +application tasks in that they are defined in the User Initialization Tasks +Table and automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are scheduled using +the same algorithm as all other RTEMS tasks, they must be configured at a +priority and mode which will ensure that they will complete execution before +other application tasks execute. Although there is no upper limit on the +number of initialization tasks, an application is required to define at least +one. + +A typical initialization task will create and start the static set of +application tasks. It may also create any other objects used by the +application. Initialization tasks which only perform initialization should +delete themselves upon completion to free resources for other tasks. +Initialization tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and execution mode. +RTEMS does not automatically delete the initialization tasks. + +The Idle Task +------------- + +The Idle Task is the lowest priority task in a system and executes only when no +other task is ready to execute. The default implementation of this task +consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by +a CPU specific implementation, a BSP specific implementation or an application +specific implementation. + +The Idle Task is preemptible and *WILL* be preempted when any other task is +made ready to execute. This characteristic is critical to the overall behavior +of any application. + +Initialization Manager Failure +------------------------------ + +System initialization errors are fatal. See :ref:`internal_errors`. diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst new file mode 100644 index 0000000..97dea46 --- /dev/null +++ b/c-user/initialization/directives.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Directives +========== + +This section details the Initialization Manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. raw:: latex + + \clearpage + +.. index:: initialize RTEMS +.. index:: start multitasking +.. index:: rtems_initialize_executive + +.. _rtems_initialize_executive: + +INITIALIZE_EXECUTIVE - Initialize RTEMS +--------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + void rtems_initialize_executive(void); + +DIRECTIVE STATUS CODES: + NONE - This function will not return to the caller. + +DESCRIPTION: + Iterates through the system initialization linker set and invokes the + registered handlers. The final step is to start multitasking. + +NOTES: + This directive should be called by :c:func:`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. diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst new file mode 100644 index 0000000..b41fcdd --- /dev/null +++ b/c-user/initialization/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + +.. _RTEMSAPIClassicInit: + +Initialization Manager +********************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst new file mode 100644 index 0000000..ae14fb0 --- /dev/null +++ b/c-user/initialization/introduction.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +The Initialization Manager is responsible for initializing the Board Support +Package, RTEMS, device drivers, the root filesystem and the application. The +:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system +shutdown. + +The Initialization Manager provides only one directive: + +- :ref:`rtems_initialize_executive` diff --git a/c-user/initialization.rst b/c-user/initialization/operations.rst index fa7afb5..db5c94b 100644 --- a/c-user/initialization.rst +++ b/c-user/initialization/operations.rst @@ -2,66 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Initialization Manager -********************** - -Introduction -============ - -The Initialization Manager is responsible for initializing the Board Support -Package, RTEMS, device drivers, the root filesystem and the application. The -:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system -shutdown. - -The Initialization Manager provides only one directive: - -- rtems_initialize_executive_ - Initialize RTEMS - -Background -========== - -.. index:: initialization tasks - -Initialization Tasks --------------------- - -Initialization task(s) are the mechanism by which RTEMS transfers initial -control to the user's application. Initialization tasks differ from other -application tasks in that they are defined in the User Initialization Tasks -Table and automatically created and started by RTEMS as part of its -initialization sequence. Since the initialization tasks are scheduled using -the same algorithm as all other RTEMS tasks, they must be configured at a -priority and mode which will ensure that they will complete execution before -other application tasks execute. Although there is no upper limit on the -number of initialization tasks, an application is required to define at least -one. - -A typical initialization task will create and start the static set of -application tasks. It may also create any other objects used by the -application. Initialization tasks which only perform initialization should -delete themselves upon completion to free resources for other tasks. -Initialization tasks may transform themselves into a "normal" application task. -This transformation typically involves changing priority and execution mode. -RTEMS does not automatically delete the initialization tasks. - -The Idle Task -------------- - -The Idle Task is the lowest priority task in a system and executes only when no -other task is ready to execute. The default implementation of this task -consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by -a CPU specific implementation, a BSP specific implementation or an application -specific implementation. - -The Idle Task is preemptible and *WILL* be preempted when any other task is -made ready to execute. This characteristic is critical to the overall behavior -of any application. - -Initialization Manager Failure ------------------------------- - -System initialization errors are fatal. See :ref:`internal_errors`. - Operations ========== @@ -418,41 +358,3 @@ should output: c() b() A:A() - -Directives -========== - -This section details the Initialization Manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: initialize RTEMS -.. index:: start multitasking -.. index:: rtems_initialize_executive - -.. _rtems_initialize_executive: - -INITIALIZE_EXECUTIVE - Initialize RTEMS ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_initialize_executive(void); - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - Iterates through the system initialization linker set and invokes the - registered handlers. The final step is to start multitasking. - -NOTES: - This directive should be called by :c:func:`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. |