Changeset 29910dec in rtems


Ignore:
Timestamp:
Aug 22, 2008, 4:58:53 PM (11 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.9, master
Children:
192834e
Parents:
0eb595a8
Message:

2008-08-22 Joel Sherrill <joel.sherrill@…>

  • bsp_howto/init.t: Complete update.
Location:
doc
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/ChangeLog

    r0eb595a8 r29910dec  
     12008-08-22      Joel Sherrill <joel.sherrill@oarcorp.com>
     2
     3        * bsp_howto/init.t: Complete update.
     4
    152008-08-22      Joel Sherrill <joel.sherrill@oarcorp.com>
    26
  • doc/bsp_howto/init.t

    r0eb595a8 r29910dec  
    245245@end example
    246246
    247 This routine is also responsible for overriding the default settings
    248 in the CPU Configuration Table and setting port specific entries
    249 in this table.  This may include increasing the maximum number
    250 of some types of RTEMS system objects to reflect the needs of
    251 the BSP and the base set of device drivers. This routine will
    252 typically also install routines for one or more of the following
    253 initialization hooks:
    254 
    255 @itemize @bullet
    256 @item BSP Pretasking Hook
    257 @item BSP Predriver Hook
    258 @item BSP Postdriver Hook
    259 @end itemize
    260 
    261 One of the most important functions performed by this routine
    262 is determining where the RTEMS Workspace is to be
    263 located in memory.  All RTEMS objects and task stacks will be
    264 allocated from this Workspace.  The RTEMS Workspace is distinct
    265 from the application heap used for @code{malloc()}.  Many BSPs
    266 place the RTEMS Workspace area at the end of RAM although this is
    267 certainly not a requirement.
    268 
    269 After completing execution, this routine returns to the
    270 @code{boot_card()} routine.
    271 
    272 @subsection main() - C Main
    273 
    274 This routine is the C main entry point.  This is a special routine
    275 and the GNU Compiler Suite treats it as such.  The GNU C Compiler
    276 recognizes @code{main()} and automatically inserts a call to the
    277 compiler run-time support routine @code{__main()} as the first
    278 code executed in @code{main()}.
    279 
    280 The routine @code{__main()} initializes the compiler's basic run-time
    281 support library and, most importantly, invokes the C++ global
    282 constructors. 
    283 
    284 The precise placement of when @code{main()} is invoked in the
    285 RTEMS initialization sequence ensures that C Library and non-blocking
    286 calls can be made in global C++ constructors.
    287 
    288 The shared implementation of this routine is located in the following file:
    289 
    290 @example
    291 c/src/lib/libbsp/shared/main.c
    292 @end example
    293 
    294 In addition to the implicit invocation of @code{__main}, this
    295 routine performs some explicit initialization.  This routine
    296 sets the variable @code{rtems_progname} and initiates
    297 multitasking via a call to the RTEMS directive
    298 @code{rtems_initialize_executive_late}.  It is important to note
    299 that the executive does not return to this routine until the
    300 RTEMS directive @code{rtems_shutdown_executive} is invoked.
    301 
    302 The RTEMS initialization procedure is described in the @b{Initialization
    303 Manager} chapter of the @b{RTEMS Application C User's Guide}.
    304 Please refer to that manual for more information.
     247On older BSPs not using @code{boot_card()}'s support for allocating memory
     248to the C Program Heap and RTEMS Workspace, one of the most important
     249functions performed by this routine is determining where the RTEMS
     250Workspace is to be located in memory.  All RTEMS objects and task stacks
     251will be allocated from this Workspace.  The RTEMS Workspace is distinct
     252from the application heap used for @code{malloc()}.  Many BSPs place
     253the RTEMS Workspace area at the end of RAM although this is certainly
     254not a requirement.
     255
     256After completing execution, this routine returns to the @code{boot_card()}
     257routine.
    305258
    306259@subsection RTEMS Pretasking Callback
    307260
    308 The @code{pretasking_hook} entry in the RTEMS CPU Configuration
    309 Table may be the address of a user provided routine that is
     261The method @code{bsp_pretasking_hook()} is the BSP specific routine
    310262invoked once RTEMS API initialization is complete but before interrupts
    311263and tasking are enabled.  No tasks -- not even the IDLE task -- have
    312 been created when this hook is invoked.  The pretasking hook is optional.
    313 
    314 Although optional, most of the RTEMS BSPs provide a pretasking hook
    315 callback.  This routine is usually called @code{bsp_pretasking_hook}
    316 and is found in the file:
    317 
    318 @example
    319 c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
    320 @end example
     264been created when this hook is invoked.  The pretasking hook is optional
     265and the user may use the shared version.
    321266
    322267The @code{bsp_pretasking_hook()} routine is the appropriate place to
    323268initialize any support components which depend on the RTEMS APIs.
    324 Most BSPs set the debug level for the system and initialize the
    325 RTEMS C Library support in their
    326 implementation of @code{bsp_pretasking_hook()}.  This initialization
    327 includes the application heap used by the @code{malloc} family
    328 of routines as well as the reentrancy support for the C Library.
     269Older BSPs that do not take full advantage of @code{boot_card()}
     270may initialize the RTEMS C Library in their implementation of
     271@code{bsp_pretasking_hook()}.  This initialization includes the
     272application heap used by the @code{malloc} family of routines as well
     273as the reentrancy support for the C Library.
    329274
    330275The routine @code{bsp_libc_init} routine invoked from the
    331 @code{bsp_pretasking_hook()} routine is passed the starting
    332 address, length, and growth amount passed to @code{sbrk}. 
    333 This "sbrk amount" is only used if the heap runs out of
    334 memory.  In this case, the RTEMS malloc implementation will
    335 invoked @code{sbrk} to obtain more memory.  See
    336 @ref{Miscellaneous Support Files sbrk() Implementation} for more details.
     276either @code{boot_card()} or (less preferable) the BSP specific
     277@code{bsp_pretasking_hook()} routine is passed the starting address,
     278length, and growth amount passed to @code{sbrk}.  This "sbrk amount"
     279is only used if the heap runs out of memory.  In this case, the RTEMS
     280malloc implementation will invoked @code{sbrk} to obtain more memory.
     281See @ref{Miscellaneous Support Files sbrk() Implementation} for more
     282details.
    337283
    338284@subsection RTEMS Predriver Callback
    339285
    340 The @code{predriver_hook} entry in the RTEMS CPU Configuration
    341 Table may be the address of a user provided routine that is
    342 is invoked immediately before the the device drivers and MPCI
    343 are initialized. RTEMS
    344 initialization is complete but interrupts and tasking are disabled.
    345 This field may be NULL to indicate that the hook is not utilized.
    346 
    347 Most BSPs do not use this callback.
     286The @code{bsp_predriver_hook()} method is the BSP specific routine that
     287is is invoked immediately before the the device drivers and MPCI are
     288initialized. RTEMS initialization is complete but interrupts and tasking
     289are disabled.
     290
     291The BSP may use the shared version of this routine which is empty.
     292Most BSPs do not provide a specific implementation of this callback.
    348293
    349294@subsection Device Driver Initialization
     
    379324@subsection RTEMS Postdriver Callback
    380325
    381 The @code{postdriver_hook} entry in the RTEMS CPU Configuration
    382 Table may be the address of a user provided routine that is
    383 invoked immediately after the the device drivers and MPCI are initialized.
    384 Interrupts and tasking are disabled.  The postdriver hook is optional.
    385 
    386 Although optional, most of the RTEMS BSPs provide a postdriver hook
    387 callback.  This routine is usually called @code{bsp_postdriver_hook}
    388 and is found in the file:
    389 
    390 @example
    391 c/src/lib/libbsp/CPU/BSP/startup/bsppost.c
    392 @end example
    393 
    394 The @code{bsp_postdriver_hook()} routine is the appropriate place to
    395 perform initialization that must be performed before the first task
    396 executes but requires that a device driver be initialized.  The
    397 shared implementation of the postdriver hook opens the default
    398 standard in, out, and error files and associates them with
    399 @code{/dev/console}.
     326The @code{bsp_postdriver_hook()} BSP specific routine is invoked
     327immediately after the the device drivers and MPCI are initialized.
     328Interrupts and tasking are disabled.
     329
     330Most BSPs use the shared implementation of this routine which is responsible for opening the device @code{/dev/console} for standard input, output and error if the application has configured the Console Device Driver.  This file is located at:
     331
     332@example
     333c/src/lib/libbsp/shared/bsppost.c
     334@end example
    400335
    401336@section The Interrupt Vector Table
     
    501436
    502437The RTEMS configuration table is application dependent, which means that
    503 one has to provide one per application. It is usually defined
    504 by defining macros and including the header file @code{<rtems/confdefs.h>}.
    505 In simple applications such as the tests provided with RTEMS, it is
    506 commonly found in the main module of the application.  For more complex
    507 applications, it may be in a file by itself.
    508 
    509 The header file @code{<rtems/confdefs.h>} defines a constant table named
    510 @code{Configuration}.  With RTEMS 4.8 and older, it was
    511 accepted practice for the BSP to copy this table into a modifiable
    512 copy named @code{BSP_Configuration}.  This copy of the table was modified
    513 to define the base address of the RTEMS Executive Workspace as well as
    514 to reflect any BSP and device driver requirements not automatically
    515 handled by the application.  In 4.9 and newer, we have eliminated
    516 the BSP copies of the configuration tables and are making efforts
    517 to make the configuration information generated by @code{<rtems/confdefs.h>}
    518 constant and read only.
     438one has to provide one per application. It is usually defined by defining
     439macros and including the header file @code{<rtems/confdefs.h>}.  In simple
     440applications such as the tests provided with RTEMS, it is commonly found
     441in the main module of the application.  For more complex applications,
     442it may be in a file by itself.
     443
     444The header file @code{<rtems/confdefs.h>} defines a constant table
     445named @code{Configuration}.  With RTEMS 4.8 and older, it was accepted
     446practice for the BSP to copy this table into a modifiable copy named
     447@code{BSP_Configuration}.  This copy of the table was modified to define
     448the base address of the RTEMS Executive Workspace as well as to reflect
     449any BSP and device driver requirements not automatically handled by the
     450application.  In 4.9 and newer, we have eliminated the BSP copies of the
     451configuration tables and are making efforts to make the configuration
     452information generated by @code{<rtems/confdefs.h>} constant and read only.
    519453
    520454For more information on the RTEMS Configuration Table, refer to the
Note: See TracChangeset for help on using the changeset viewer.