.. comment SPDX-License-Identifier: CC-BY-SA-4.0 .. 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 initializing the Board Support Package, RTEMS, device drivers, the root filesystem and the application. The :ref:`Fatal Error Manager ` is responsible for the system shutdown. The Initialization Manager provides only one directive: - rtems_initialize_executive_ - Initialize RTEMS Background ========== 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. 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 ========== Initializing RTEMS ------------------ The Initialization Manager :c:func:`rtems_initialize_executive()` directives is called by the :c:ref:`boot_card()` routine which 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, - an initialization stack large enough to initialize the rest of the Board Support Package, RTEMS and the device drivers, - all registers and components mandated by Application Binary Interface, and - disabled interrupts. The :c:func:`rtems_initialize_executive()` directive uses a system initialization :ref:`linker set ` to initialize only those parts of the overall RTEMS feature set that is necessary for a particular application. Each RTEMS feature used the application may optionally register an initialization handler. The system initialization API is available via :samp:`#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. 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. RTEMS_SYSINIT_BSP_START Basic initialization step provided by the Board Support Package. This step is mandatory. RTEMS_SYSINIT_INITIAL_EXTENSIONS Registers the initial extensions. This step is optional and depends on the application configuration. RTEMS_SYSINIT_MP_EARLY Early MPCI initialization. This step is mandatory on MPCI configurations. 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_CPU_SET Initialization of system CPU set. This step is optional and depends on the application configuration. RTEMS_SYSINIT_MP MPCI initialization. This step is mandatory on MPCI configurations. RTEMS_SYSINIT_USER_EXTENSIONS Initialization of the User Extensions object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_TASKS Initialization of the Classic Tasks object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_TIMER Initialization of the Classic Timer object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_SIGNAL Initialization of the Classic Signal support. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_EVENT Initialization of the Classic Event support. This step is optional and depends on the application configuration. This step is only used on MPCI configurations. RTEMS_SYSINIT_CLASSIC_MESSAGE_QUEUE Initialization of the Classic Message Queue object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_SEMAPHORE Initialization of the Classic Semaphore object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_PARTITION Initialization of the Classic Partition object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_REGION Initialization of the Classic Region object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_DUAL_PORTED_MEMORY Initialization of the Classic Dual-Ported Memory object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_RATE_MONOTONIC Initialization of the Classic Rate-Monotonic object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_CLASSIC_BARRIER Initialization of the Classic Barrier object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_SIGNALS Initialization of the POSIX Signals support. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_THREADS Initialization of the POSIX Threads object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_CONDITION_VARIABLE Initialization of the POSIX Condition Variable object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_MUTEX Initialization of the POSIX Mutex object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_MESSAGE_QUEUE Initialization of the POSIX Message Queue object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_SEMAPHORE Initialization of the POSIX Semaphore object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_TIMER Initialization of the POSIX Timer object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_BARRIER Initialization of the POSIX Barrier object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_RWLOCK Initialization of the POSIX Read-Write Locks object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_CLEANUP Initialization of the POSIX Cleanup support. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_KEYS Initialization of the POSIX Keys object class. This step is optional and depends on the application configuration. RTEMS_SYSINIT_IDLE_THREADS Initialization of idle threads. This step is mandatory. RTEMS_SYSINIT_LIBIO Initialization of IO library. This step is optional and depends on the application configuration. RTEMS_SYSINIT_ROOT_FILESYSTEM Initialization of the root filesystem. This step is optional and depends on the application configuration. RTEMS_SYSINIT_DRVMGR Driver manager initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled. RTEMS_SYSINIT_MP_SERVER MPCI server initialization. This step is mandatory on MPCI configurations. RTEMS_SYSINIT_BSP_PRE_DRIVERS Initialization step performed right before device drivers are initialized. This step is mandatory. RTEMS_SYSINIT_DRVMGR_LEVEL_1 Driver manager level 1 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled. 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_DRVMGR_LEVEL_2 Driver manager level 2 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled. RTEMS_SYSINIT_DRVMGR_LEVEL_3 Driver manager level 3 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled. RTEMS_SYSINIT_DRVMGR_LEVEL_4 Driver manager level 4 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled. RTEMS_SYSINIT_MP_FINALIZE Finalize MPCI initialization. This step is mandatory on MPCI configurations. RTEMS_SYSINIT_CLASSIC_USER_TASKS Creates and starts the Classic initialization tasks. This step is optional and depends on the application configuration. RTEMS_SYSINIT_POSIX_USER_THREADS Creates POSIX initialization threads. This step is optional and depends on the application configuration. RTEMS_SYSINIT_STD_FILE_DESCRIPTORS Open the standard input, output and error file descriptors. This step is optional and depends on the application configuration. The final action of the :c:func:`rtems_initialize_executive()` directive is to start multitasking and switch to the highest priority ready thread. 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 :ref:`Configuring a 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. .. raw:: latex \clearpage .. _rtems_initialize_executive: INITIALIZE_EXECUTIVE - Initialize RTEMS --------------------------------------- .. index:: initialize RTEMS .. index:: start multitasking .. index:: rtems_initialize_executive 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.