Changeset d0c39838 in rtems for doc


Ignore:
Timestamp:
Sep 22, 2015, 2:21:12 PM (4 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
df55d07f
Parents:
d19d1c23
git-author:
Sebastian Huber <sebastian.huber@…> (09/22/15 14:21:12)
git-committer:
Sebastian Huber <sebastian.huber@…> (12/11/15 07:17:16)
Message:

Use linker set for system initialization

Make rtems_initialize_data_structures(),
rtems_initialize_before_drivers() and rtems_initialize_device_drivers()
static. Rename rtems_initialize_start_multitasking() to
rtems_initialize_executive() and call the registered system
initialization handlers in this function. Add system initialization API
available via #include <rtems/sysinit.h>. Update the documentation
accordingly.

This is no functional change, only the method to call the existing
initialization routines changes. Instead of direct function calls a
table of function pointers contained in the new RTEMS system
initialization linker set is used. This table looks like this (the
actual addresses depend on the target).

nm *.exe | grep _Linker | sort
0201a2d0 D _Linker_setSysinit_begin
0201a2d0 D _Linker_setSysinit_bsp_work_area_initialize
0201a2d4 D _Linker_setSysinit_bsp_start
0201a2d8 D _Linker_setSysinit_rtems_initialize_data_structures
0201a2dc D _Linker_setSysinit_bsp_libc_init
0201a2e0 D _Linker_setSysinit_rtems_initialize_before_drivers
0201a2e4 D _Linker_setSysinit_bsp_predriver_hook
0201a2e8 D _Linker_setSysinit_rtems_initialize_device_drivers
0201a2ec D _Linker_setSysinit_bsp_postdriver_hook
0201a2f0 D _Linker_setSysinit_end

Add test sptests/spsysinit01.

Update #2408.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/user/init.t

    rd19d1c23 rd0c39838  
    1717
    1818@itemize @bullet
    19 @item @code{@value{DIRPREFIX}initialize_data_structures} - Initialize RTEMS Data Structures
    20 @item @code{@value{DIRPREFIX}initialize_before_drivers} - Perform Initialization Before Device Drivers
    21 @item @code{@value{DIRPREFIX}initialize_device_drivers} - Initialize Device Drivers
    22 @item @code{@value{DIRPREFIX}initialize_start_multitasking} - Complete Initialization and Start Multitasking
     19@item @code{@value{DIRPREFIX}initialize_executive} - Initialize RTEMS
    2320@item @code{@value{DIRPREFIX}shutdown_executive} - Shutdown RTEMS
    2421@end itemize
    … …  
    5956drivers, and eventually a context switch to the first user
    6057task.  Remember, that interrupts are disabled during
    61 initialization and the @i{initialization thread} is not
     58initialization and the @i{initialization context} is not
    6259a task in any sense and the user should be very careful
    63 during initialzation.
     60during initialization.
    6461
    6562The BSP must ensure that the there is enough stack
    66 space reserved for the initialization "thread" to
     63space reserved for the initialization context to
    6764successfully execute the initialization routines for
    6865all device drivers and, in multiprocessor configurations, the
    … …  
    126123@subsection Initializing RTEMS
    127124
    128 The Initialization Manager directives are called by the
    129 Board Support Package framework as part of its initialization
    130 sequence.  RTEMS assumes that the Board Support Package
    131 successfully completed its initialization activities.  These
    132 directives initialize RTEMS by performing the following actions:
     125The Initialization Manager @code{@value{DIRPREFIX}initialize_executive}
     126directives is called by the @code{boot_card} routine.  The @code{boot_card}
     127routine is invoked by the Board Support Package once a basic C run-time
     128environment is set up.  This consists of
    133129
    134130@itemize @bullet
    135 @item Initializing internal RTEMS variables;
    136 @item Allocating system resources;
    137 @item Creating and starting the Idle Task;
    138 @item Initialize all device drivers;
    139 @item Creating and starting the user initialization task(s); and
    140 @item Initiating multitasking.
     131@item a valid and accessible text section, read-only data, read-write data and
     132zero-initialized data,
     133@item an initialization stack large enough to initialize the rest of the Board
     134Support Package, RTEMS and the device drivers,
     135@item all registers and components mandated by Application Binary Interface, and
     136@item disabled interrupts.
    141137@end itemize
    142138
    143 The initialization directives MUST be called in the proper
    144 sequence before any blocking directives may be used.  The services
    145 in this manager should be invoked just once per application
    146 and in precisely the following order:
    147 
    148 @itemize @bullet
    149 @item @code{@value{DIRPREFIX}initialize_data_structures}
    150 @item @code{@value{DIRPREFIX}initialize_before_drivers}
    151 @item @code{@value{DIRPREFIX}initialize_device_drivers}
    152 @item @code{@value{DIRPREFIX}initialize_start_multitasking}
    153 @end itemize
    154 
    155 It is recommended that the Board Support Package use the
    156 provided framework which will invoke these services as
    157 part of the executing the function @code{boot_card} in the
    158 file @code{c/src/lib/libbsp/shared/bootcard.c}.  This
    159 framework will also assist in allocating memory to the
    160 RTEMS Workspace and C Program Heap and initializing the
    161 C Library.
    162 
    163 The effect of calling any blocking RTEMS directives before
    164 @code{@value{DIRPREFIX}initialize_start_multitasking}
    165 is unpredictable but guaranteed to be bad.  After the
    166 directive @code{@value{DIRPREFIX}initialize_data_structures}
    167 is invoked, it is permissible to allocate RTEMS objects and
    168 perform non-blocking operations.  But the user should be
    169 distinctly aware that multitasking is not available yet
    170 and they are @b{NOT} executing in a task context.
     139The @code{@value{DIRPREFIX}initialize_executive} directive uses a system
     140initialization linker set to initialize only those parts of the overall RTEMS
     141feature set that is necessary for a particular application.  @xref{Linker
     142Sets}.  Each RTEMS feature used the application may optionally register an
     143initialization handler.  The system initialization API is available via
     144@code{#included <rtems/sysinit.h>}.
     145
     146A list of all initialization steps follows.  Some steps are optional depending
     147on the requested feature set of the application.  The initialization steps are
     148execute in the order presented here.
     149
     150@table @dfn
     151
     152@item RTEMS_SYSINIT_BSP_WORK_AREAS
     153The work areas consisting of C Program Heap and the RTEMS Workspace are
     154initialized by the Board Support Package.  This step is mandatory.
     155
     156@item RTEMS_SYSINIT_BSP_START
     157Basic initialization step provided by the Board Support Package.  This step is
     158mandatory.
     159
     160@item RTEMS_SYSINIT_DATA_STRUCTURES
     161This directive is called when the Board Support Package has completed its basic
     162initialization and allows RTEMS to initialize the application environment based
     163upon the information in the Configuration Table, User Initialization Tasks
     164Table, Device Driver Table, User Extension Table, Multiprocessor Configuration
     165Table, and the Multiprocessor Communications Interface (MPCI) Table.
     166
     167@item RTEMS_SYSINIT_BSP_LIBC
     168Depending on the application configuration the IO library and root filesystem
     169is initialized.  This step is mandatory.
     170
     171@item RTEMS_SYSINIT_BEFORE_DRIVERS
     172This directive performs initialization that must occur between basis RTEMS data
     173structure initialization and device driver initialization.  In particular, in a
     174multiprocessor configuration, this directive will create the MPCI Server Task.
     175
     176@item RTEMS_SYSINIT_BSP_PRE_DRIVERS
     177Initialization step performed right before device drivers are initialized
     178provided by the Board Support Package.  This step is mandatory.
     179
     180@item RTEMS_SYSINIT_DEVICE_DRIVERS
     181This step initializes all statically configured device drivers and performs all
     182RTEMS initialization which requires device drivers to be initialized.  This
     183step is mandatory.
     184
     185In a multiprocessor configuration, this service will initialize the
     186Multiprocessor Communications Interface (MPCI) and synchronize with the other
     187nodes in the system.
     188
     189@item RTEMS_SYSINIT_BSP_POST_DRIVERS
     190Initialization step performed right after device drivers are initialized
     191provided by the Board Support Package.  This step is mandatory.
     192
     193@end table
     194
     195The final action of the @code{@value{DIRPREFIX}initialize_executive} directive
     196is to start multitasking.  RTEMS does not return to the initialization context
     197and the initialization stack may be re-used for interrupt processing.
    171198
    172199Many of RTEMS actions during initialization are based upon
    … …  
    175202to the chapter @ref{Configuring a System}.
    176203
    177 The final step in the initialization sequence is the
     204The final action in the initialization sequence is the
    178205initiation of multitasking.  When the scheduler and dispatcher
    179206are enabled, the highest priority, ready task will be dispatched
    180207to run.  Control will not be returned to the Board Support
    181 Package after multitasking is enabled until the
    182 @code{@value{DIRPREFIX}shutdown_executive} directive is called.
    183 This directive is called as a side-effect of POSIX calls
    184 including @code{exit}.
     208Package after multitasking is enabled.  The initialization stack may be re-used
     209for interrupt processing.
    185210
    186211@subsection Shutting Down RTEMS
    187212
    188213The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
    189 application to end multitasking and return control to the board
    190 support package.  The board support package resumes execution at
    191 the code immediately following the invocation of the
    192 @code{@value{DIRPREFIX}initialize_start_multitasking} directive.
     214application to end multitasking and terminate the system.
    193215
    194216@section Directives
    … …  
    200222
    201223@page
    202 @subsection INITIALIZE_DATA_STRUCTURES - Initialize RTEMS Data Structures
    203 
    204 @cindex initialize RTEMS data structures
    205 
    206 @subheading CALLING SEQUENCE:
    207 
    208 @ifset is-C
    209 @findex rtems_initialize_data_structures
    210 @example
    211 void rtems_initialize_data_structures(void);
    212 @end example
    213 @end ifset
    214 
    215 @ifset is-Ada
    216 @example
    217 NOT SUPPORTED FROM Ada BINDING
    218 @end example
    219 @end ifset
    220 
    221 @subheading DIRECTIVE STATUS CODES:
    222 
    223 NONE
    224 
    225 @subheading DESCRIPTION:
    226 
    227 This directive is called when the Board Support
    228 Package has completed its basic initialization and
    229 allows RTEMS to initialize the application environment based upon the
    230 information in the Configuration Table, User Initialization
    231 Tasks Table, Device Driver Table, User Extension Table,
    232 Multiprocessor Configuration Table, and the Multiprocessor
    233 Communications Interface (MPCI) Table.  This directive returns
    234 to the caller after completing the basic RTEMS initialization.
    235 
    236 @subheading NOTES:
    237 
    238 The Initialization Manager directives must be used in the
    239 proper sequence and invokved only once in the life of an application.
    240 
    241 This directive must be invoked with interrupts disabled.
    242 Interrupts should be disabled as early as possible in
    243 the initialization sequence and remain disabled until
    244 the first context switch.
    245 
    246 @page
    247 @subsection INITIALIZE_BEFORE_DRIVERS - Perform Initialization Before Device Drivers
    248 
    249 @cindex initialize RTEMS before device drivers
    250 
    251 @subheading CALLING SEQUENCE:
    252 
    253 @ifset is-C
    254 @findex rtems_initialize_before_drivers
    255 @example
    256 void rtems_initialize_before_drivers(void);
    257 @end example
    258 @end ifset
    259 
    260 @ifset is-Ada
    261 @example
    262 NOT SUPPORTED FROM Ada BINDING
    263 @end example
    264 @end ifset
    265 
    266 @subheading DIRECTIVE STATUS CODES:
    267 
    268 NONE
    269 
    270 @subheading DESCRIPTION:
    271 
    272 This directive is called by the Board Support Package as the
    273 second step in initializing RTEMS.  This directive performs
    274 initialization that must occur between basis RTEMS data structure
    275 initialization and device driver initialization.  In particular,
    276 in a multiprocessor configuration, this directive will create the
    277 MPCI Server Task.  This directive returns to the caller after
    278 completing the basic RTEMS initialization.
    279 
    280 @subheading NOTES:
    281 
    282 The Initialization Manager directives must be used in the
    283 proper sequence and invokved only once in the life of an application.
    284 
    285 This directive must be invoked with interrupts disabled.
    286 Interrupts should be disabled as early as possible in
    287 the initialization sequence and remain disabled until
    288 the first context switch.
    289 
    290 @page
    291 @subsection INITIALIZE_DEVICE_DRIVERS - Initialize Device Drivers
    292 
    293 @cindex initialize device drivers
    294 
    295 @subheading CALLING SEQUENCE:
    296 
    297 @ifset is-C
    298 @findex rtems_initialize_device_drivers
    299 @example
    300 void rtems_initialize_device_drivers(void);
    301 @end example
    302 @end ifset
    303 
    304 @ifset is-Ada
    305 @example
    306 NOT SUPPORTED FROM Ada BINDING
    307 @end example
    308 @end ifset
    309 
    310 @subheading DIRECTIVE STATUS CODES:
    311 
    312 NONE
    313 
    314 @subheading DESCRIPTION:
    315 
    316 This directive is called by the Board Support Package as the
    317 third step in initializing RTEMS.  This directive initializes
    318 all statically configured device drivers and performs all RTEMS
    319 initialization which requires device drivers to be initialized.
    320 
    321 In a multiprocessor configuration, this service will initialize
    322 the Multiprocessor Communications Interface (MPCI) and synchronize
    323 with the other nodes in the system.
    324 
    325 After this directive is executed, control will be returned to
    326 the Board Support Package framework.
    327 
    328 @subheading NOTES:
    329 
    330 The Initialization Manager directives must be used in the
    331 proper sequence and invokved only once in the life of an application.
    332 
    333 This directive must be invoked with interrupts disabled.
    334 Interrupts should be disabled as early as possible in
    335 the initialization sequence and remain disabled until
    336 the first context switch.
    337 
    338 @page
    339 @subsection INITIALIZE_START_MULTITASKING - Complete Initialization and Start Multitasking
     224@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS
    340225
    341226@cindex initialize RTEMS
    … …  
    345230
    346231@ifset is-C
    347 @findex rtems_initialize_start_multitasking
    348 @example
    349 void rtems_initialize_start_multitasking(void);
     232@findex rtems_initialize_executive
     233@example
     234void rtems_initialize_executive(void);
    350235@end example
    351236@end ifset
    … …  
    363248@subheading DESCRIPTION:
    364249
    365 This directive initiates multitasking and performs a context switch to the
    366 first user application task and may enable interrupts as a side-effect of
    367 that context switch.  The context switch saves the executing context.  The
    368 application runs now.  The directive rtems_shutdown_executive() will return
    369 to the saved context.  The exit() function will use this directive.
    370 
    371 After a return to the saved context a fatal system state is reached.  The
    372 fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
    373 passed to rtems_shutdown_executive().
     250Iterates through the system initialization linker set and invokes the
     251registered handlers.  The final step is to start multitasking.
    374252
    375253@subheading NOTES:
    376254
    377 This directive @b{DOES NOT RETURN} to the caller.
    378 
    379 This directive causes all nodes in the system to
    380 verify that certain configuration parameters are the same as
    381 those of the local node.  If an inconsistency is detected, then
    382 a fatal error is generated.
     255This directive should be called by @code{boot_card} only.
     256
     257This directive @b{does not return} to the caller.  Errors in the initialization
     258sequence are usually fatal and lead to a system termination.
    383259
    384260@page
    … …  
    412288@subheading DESCRIPTION:
    413289
    414 This directive is called when the application wishes
    415 to shutdown RTEMS and return control to the board support
    416 package.  The board support package resumes execution at the
    417 code immediately following the invocation of the
    418 @code{@value{DIRPREFIX}initialize_executive} directive.
     290This directive is called when the application wishes to shutdown RTEMS.  The
     291system is terminated with a fatal source of @code{RTEMS_FATAL_SOURCE_EXIT} and
     292the specified @code{result} code.
    419293
    420294@subheading NOTES:
    421295
    422 This directive MUST be the last RTEMS directive
    423 invoked by an application and it DOES NOT RETURN to the caller.
    424 
    425 This directive should not be invoked until the
    426 executive has successfully completed initialization.
     296This directive @b{must} be the last RTEMS directive
     297invoked by an application and it @b{does not return} to the caller.
     298
     299This directive may be called any time.
Note: See TracChangeset for help on using the changeset viewer.