From b8d3f6b3b7fd03102f8a06aaaec330a0293c95d2 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Sun, 24 Jan 2016 21:37:53 +1100 Subject: C user guide clean up. Up to timer manager. --- c_user/initialization.rst | 272 ++++++++++++++++++++++------------------------ 1 file changed, 127 insertions(+), 145 deletions(-) (limited to 'c_user/initialization.rst') diff --git a/c_user/initialization.rst b/c_user/initialization.rst index e2a823b..95c6e59 100644 --- a/c_user/initialization.rst +++ b/c_user/initialization.rst @@ -1,16 +1,19 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Initialization Manager ###################### Introduction ============ -The Initialization Manager is responsible for -initiating and shutting down RTEMS. Initiating RTEMS involves -creating and starting all configured initialization tasks, and -for invoking the initialization routine for each user-supplied -device driver. In a multiprocessor configuration, this manager -also initializes the interprocessor communications layer. The -directives provided by the Initialization Manager are: +The Initialization Manager is responsible for initiating and shutting down +RTEMS. Initiating RTEMS involves creating and starting all configured +initialization tasks, and for invoking the initialization routine for each +user-supplied device driver. In a multiprocessor configuration, this manager +also initializes the interprocessor communications layer. The directives +provided by the Initialization Manager are: - ``rtems_initialize_executive`` - Initialize RTEMS @@ -23,97 +26,85 @@ Initialization Tasks -------------------- .. index:: 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. +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. System Initialization --------------------- -System Initialization begins with board reset and continues -through RTEMS initialization, initialization of all device -drivers, and eventually a context switch to the first user -task. Remember, that interrupts are disabled during -initialization and the *initialization context* is not -a task in any sense and the user should be very careful -during initialization. - -The BSP must ensure that the there is enough stack -space reserved for the initialization context to -successfully execute the initialization routines for -all device drivers and, in multiprocessor configurations, the -Multiprocessor Communications Interface Layer initialization -routine. +System Initialization begins with board reset and continues through RTEMS +initialization, initialization of all device drivers, and eventually a context +switch to the first user task. Remember, that interrupts are disabled during +initialization and the *initialization context* is not a task in any sense and +the user should be very careful during initialization. + +The BSP must ensure that the there is enough stack space reserved for the +initialization context to successfully execute the initialization routines for +all device drivers and, in multiprocessor configurations, the Multiprocessor +Communications Interface Layer initialization routine. 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. This -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 the lowest priority task in a system and executes only when no +other task is ready to execute. This 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. +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 ------------------------------ -The ``rtems_fatal_error_occurred`` directive will -be invoked from ``rtems_initialize_executive`` -for any of the following reasons: +The ``rtems_fatal_error_occurred`` directive will be invoked from +``rtems_initialize_executive`` for any of the following reasons: -- If either the Configuration Table or the CPU Dependent - Information Table is not provided. +- If either the Configuration Table or the CPU Dependent Information Table is + not provided. -- If the starting address of the RTEMS RAM Workspace, - supplied by the application in the Configuration Table, is NULL - or is not aligned on a four-byte boundary. +- If the starting address of the RTEMS RAM Workspace, supplied by the + application in the Configuration Table, is NULL or is not aligned on a + four-byte boundary. -- If the size of the RTEMS RAM Workspace is not large - enough to initialize and configure the system. +- If the size of the RTEMS RAM Workspace is not large enough to initialize and + configure the system. - If the interrupt stack size specified is too small. -- If multiprocessing is configured and the node entry in - the Multiprocessor Configuration Table is not between one and - the maximum_nodes entry. +- If multiprocessing is configured and the node entry in the Multiprocessor + Configuration Table is not between one and the maximum_nodes entry. -- If a multiprocessor system is being configured and no - Multiprocessor Communications Interface is specified. +- If a multiprocessor system is being configured and no Multiprocessor + Communications Interface is specified. -- If no user initialization tasks are configured. At - least one initialization task must be configured to allow RTEMS - to pass control to the application at the end of the executive - initialization sequence. +- If no user initialization tasks are configured. At least one initialization + task must be configured to allow RTEMS to pass control to the application at + the end of the executive initialization sequence. -- If any of the user initialization tasks cannot be - created or started successfully. +- If any of the user initialization tasks cannot be created or started + successfully. -A discussion of RTEMS actions when a fatal error occurs -may be found `Announcing a Fatal Error`_. +A discussion of RTEMS actions when a fatal error occurs may be found +`Announcing a Fatal Error`_. Operations ========== @@ -121,10 +112,10 @@ Operations Initializing RTEMS ------------------ -The Initialization Manager ``rtems_initialize_executive`` -directives is called by the ``boot_card`` routine. The ``boot_card`` -routine is invoked by the Board Support Package once a basic C run-time -environment is set up. This consists of +The Initialization Manager ``rtems_initialize_executive`` directives is called +by the ``boot_card`` routine. The ``boot_card`` routine is invoked by the +Board Support Package once a basic C run-time environment is set up. This +consists of - a valid and accessible text section, read-only data, read-write data and zero-initialized data, @@ -136,85 +127,83 @@ environment is set up. This consists of - disabled interrupts. -The ``rtems_initialize_executive`` directive uses a system -initialization linker set to initialize only those parts of the overall RTEMS -feature set that is necessary for a particular application. See `Linker Sets`_. -Each RTEMS feature used the application may optionally register an -initialization handler. The system initialization API is available via``#included ``. +The ``rtems_initialize_executive`` directive uses a system initialization +linker set to initialize only those parts of the overall RTEMS feature set that +is necessary for a particular application. See `Linker Sets`_. Each RTEMS +feature used the application may optionally register an initialization handler. +The system initialization API is available via``#included ``. A list of all initialization steps follows. Some steps are optional depending on the requested feature set of the application. The initialization steps are execute in the order presented here. -:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS` +`RTEMS_SYSINIT_BSP_WORK_AREAS` The work areas consisting of C Program Heap and the RTEMS Workspace are initialized by the Board Support Package. This step is mandatory. -:dfn:`RTEMS_SYSINIT_BSP_START` - Basic initialization step provided by the Board Support Package. This step is - mandatory. - -:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES` - This directive is called when the Board Support Package has completed its basic - initialization and allows RTEMS to initialize the application environment based - upon the information in the Configuration Table, User Initialization Tasks - Table, Device Driver Table, User Extension Table, Multiprocessor Configuration - Table, and the Multiprocessor Communications Interface (MPCI) Table. - -:dfn:`RTEMS_SYSINIT_BSP_LIBC` - Depending on the application configuration the IO library and root filesystem - is initialized. This step is mandatory. - -:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS` - This directive performs initialization that must occur between basis RTEMS data - structure initialization and device driver initialization. In particular, in a - multiprocessor configuration, this directive will create the MPCI Server Task. - -:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS` +`RTEMS_SYSINIT_BSP_START` + Basic initialization step provided by the Board Support Package. This step + is mandatory. + +`RTEMS_SYSINIT_DATA_STRUCTURES` + This directive is called when the Board Support Package has completed its + basic initialization and allows RTEMS to initialize the application + environment based upon the information in the Configuration Table, User + Initialization Tasks Table, Device Driver Table, User Extension Table, + Multiprocessor Configuration Table, and the Multiprocessor Communications + Interface (MPCI) Table. + +`RTEMS_SYSINIT_BSP_LIBC` + Depending on the application configuration the IO library and root + filesystem is initialized. This step is mandatory. + +`RTEMS_SYSINIT_BEFORE_DRIVERS` + This directive performs initialization that must occur between basis RTEMS + data structure initialization and device driver initialization. In + particular, in a multiprocessor configuration, this directive will create + the MPCI Server Task. + +`RTEMS_SYSINIT_BSP_PRE_DRIVERS` Initialization step performed right before device drivers are initialized provided by the Board Support Package. This step is mandatory. -:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS` - This step initializes all statically configured device drivers and performs all - RTEMS initialization which requires device drivers to be initialized. This - step is mandatory. - In a multiprocessor configuration, this service will initialize the - Multiprocessor Communications Interface (MPCI) and synchronize with the other - nodes in the system. +`RTEMS_SYSINIT_DEVICE_DRIVERS` + This step initializes all statically configured device drivers and performs + all RTEMS initialization which requires device drivers to be initialized. + This step is mandatory. In a multiprocessor configuration, this service + will initialize the Multiprocessor Communications Interface (MPCI) and + synchronize with the other nodes in the system. -:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS` +`RTEMS_SYSINIT_BSP_POST_DRIVERS` Initialization step performed right after device drivers are initialized provided by the Board Support Package. This step is mandatory. -The final action of the ``rtems_initialize_executive`` directive -is to start multitasking. RTEMS does not return to the initialization context -and the initialization stack may be re-used for interrupt processing. +The final action of the ``rtems_initialize_executive`` directive is to start +multitasking. RTEMS does not return to the initialization context and the +initialization stack may be re-used for interrupt processing. -Many of RTEMS actions during initialization are based upon -the contents of the Configuration Table. For more information -regarding the format and contents of this table, please refer -to the chapter `Configuring a System`_. +Many of RTEMS actions during initialization are based upon the contents of the +Configuration Table. For more information regarding the format and contents of +this table, please refer to the chapter `Configuring a System`_. -The final action in the initialization sequence is the -initiation of multitasking. When the scheduler and dispatcher -are enabled, the highest priority, ready task will be dispatched -to run. Control will not be returned to the Board Support -Package after multitasking is enabled. The initialization stack may be re-used -for interrupt processing. +The final action in the initialization sequence is the initiation of +multitasking. When the scheduler and dispatcher are enabled, the highest +priority, ready task will be dispatched to run. Control will not be returned +to the Board Support Package after multitasking is enabled. The initialization +stack may be re-used for interrupt processing. Shutting Down RTEMS ------------------- -The ``rtems_shutdown_executive`` directive is invoked by the -application to end multitasking and terminate the system. +The ``rtems_shutdown_executive`` directive is invoked by the application to end +multitasking and terminate the system. 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. +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. INITIALIZE_EXECUTIVE - Initialize RTEMS --------------------------------------- @@ -256,7 +245,7 @@ SHUTDOWN_EXECUTIVE - Shutdown RTEMS .. code:: c void rtems_shutdown_executive( - uint32_t result + uint32_t result ); **DIRECTIVE STATUS CODES:** @@ -266,19 +255,12 @@ NONE **DESCRIPTION:** This directive is called when the application wishes to shutdown RTEMS. The -system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and -the specified ``result`` code. +system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and the +specified ``result`` code. **NOTES:** -This directive *must* be the last RTEMS directive -invoked by an application and it *does not return* to the caller. +This directive *must* be the last RTEMS directive invoked by an application and +it *does not return* to the caller. This directive may be called any time. - -.. COMMENT: COPYRIGHT (c) 1988-2014. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -- cgit v1.2.3