Changeset 4205250 in rtems-docs

Feb 4, 2020, 8:06:35 AM (5 months ago)
Sebastian Huber <sebastian.huber@…>
5, master
Sebastian Huber <sebastian.huber@…> (02/04/20 08:06:35)
Sebastian Huber <sebastian.huber@…> (02/04/20 08:56:46)

bsp-howto: Rework system initialization chapter

Update #2852.
Update #3838.

2 edited


  • bsp-howto/index.rst

    r928bf73 r4205250  
    1111    | |copy| 2017 Christian Mauderer
    12     | |copy| 2016, 2018 embedded brains GmbH
    13     | |copy| 2016, 2018 Sebastian Huber
     12    | |copy| 2016, 2020 embedded brains GmbH
     13    | |copy| 2016, 2020 Sebastian Huber
    1414    | |copy| 1988, 2017 On-Line Applications Research Corporation (OAR)
  • bsp-howto/initilization_code.rst

    r928bf73 r4205250  
    11.. SPDX-License-Identifier: CC-BY-SA-4.0
     3.. Copyright (C) 2020 embedded brains GmbH
     4.. Copyright (C) 2020 Sebastian Huber
    35.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    5 Initialization Code
    6 *******************
    8 .. warning::
    10    This chapter contains outdated and confusing information.
     7System Initialization
    15 The initialization code is the first piece of code executed when there's a
    16 reset/reboot. Its purpose is to initialize the board for the application.  This
    17 chapter contains a narrative description of the initialization process followed
    18 by a description of each of the files and routines commonly found in the BSP
    19 related to initialization.  The remainder of this chapter covers special issues
    20 which require attention such as interrupt vector table and chip select
    21 initialization.
     13The system initialization consists of a low-level initialization performed by
     14the start code in the start file (:file:`start.o`) and a high-level
     15initialization carried out by :c:func:`boot_card()`.  The final step of a
     16successful high-level initialization is to switch to the initialization task
     17and change into normal system mode with multi-threading enabled.  Errors during
     18system initialization are fatal and end up in a call to :c:func:`_Terminate()`.
    23 Most of the examples in this chapter will be based on the SPARC/ERC32 and
    24 m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization for
    25 these BSP is contained under the :file:`start` directory in the BSP source
    26 directory.  The BSP source code for these BSPs is in the following directories:
     20Low-Level Initialization via Start Code in the Start File (start.o)
    28 .. code-block:: shell
     23The start code in the start file (:file:`start.o`) must be provided by the BSP.
     24It is the first file presented to the linker and starts the process to link an
     25executable (application image).  It should contain the entry symbol of the
     26executable.  It is the responsibility of the linker script in conjunction with
     27the compiler specifications file or compiler options to put the start code in
     28the correct location in the executable.  The start code is typically written in
     29assembly language since it will tinker with the stack pointer.  The general
     30rule of thumb is that the start code in assembly language should do the minimum
     31necessary to allow C code to execute to complete the initialization sequence.
    30     bsps/m68k/gen68340
    31     bsps/sparc/erc32
     33The low-level system initialization may depend on a platform initialization
     34carried out by a boot loader.  The low-level system initialization may perform
     35the following steps:
    33 Both BSPs contain startup code written in assembly language and C.  The
    34 gen68340 BSP has its early initialization start code in the ``start340``
    35 subdirectory and its C startup code in the ``startup`` directory.  In the
    36 ``start340`` directory are two source files.  The file ``startfor340only.s`` is
    37 the simpler of these files as it only has initialization code for a MC68340
    38 board.  The file ``start340.s`` contains initialization for a 68349 based board
    39 as well.
     37* Initialize the initialization stack.  The initialization stack should use the
     38  ISR stack area.  The symbols :c:macro:`_ISR_Stack_area_begin`,
     39  :c:macro:`_ISR_Stack_area_end`, and :c:macro:`_ISR_Stack_size` should be used
     40  to do this.
    41 Similarly, the ERC32 BSP has startup code written in assembly language and C.
    42 However, this BSP shares this code with other SPARC BSPs.  Thus the
    43 ```` explicitly references the following files for this
    44 functionality.
     42* Initialize processor registers and modes.
    46 .. code-block:: shell
     44* Initialize pins.
    48     ../../sparc/shared/start.S
     46* Initialize clocks (PLLs).
    50 .. note::
     48* Initialize memory controllers.
    52    In most BSPs, the directory named ``start340`` in the gen68340 BSP would be
    53    simply named ``start`` or start followed by a BSP designation.
     50* Initialize instruction, data, and unified caches.
    55 Board Initialization
    56 ====================
     52* Initialize memory management or protection units (MMU).
    58 This section describes the steps an application goes through from the time the
    59 first BSP code is executed until the first application task executes.
     54* Initialize processor exceptions.
    61 The initialization flows from assembly language start code to the shared
    62 ``bootcard.c`` framework then through the C Library, RTEMS, device driver
    63 initialization phases, and the context switch to the first application task.
    64 After this, the application executes until it calls ``exit``,
    65 ``rtems_shutdown_executive``, or some other normal termination initiating
    66 routine and a fatal system state is reached.  The optional
    67 ``bsp_fatal_extension`` initial extension can perform BSP specific system
    68 termination.
     56* Copy the data sections from a read-only section to the runtime location.
    70 The routines invoked during this will be discussed and their location in the
    71 RTEMS source tree pointed out as we discuss each.
     58* Set the BSS (``.bss``) section to zero.
    73 Start Code - Assembly Language Initialization
    74 ---------------------------------------------
     60* Initialize the C runtime environment.
    76 The assembly language code in the directory ``start`` is the first part of the
    77 application to execute.  It is responsible for initializing the processor and
    78 board enough to execute the rest of the BSP.  This includes:
     62* Call :c:func:`boot_card()` to hand over to the high-level initialization.
    80 - initializing the stack
     64For examples of start file codes see:
    82 - zeroing out the uninitialized data section ``.bss``
     66* `bsps/arm/shared/start/start.S <>`_
    84 - disabling external interrupts
     68* `bsps/riscv/shared/start/start.S <>`_
    86 - copy the initialized data from ROM to RAM
     70High-Level Initialization via boot_card()
    88 The general rule of thumb is that the start code in assembly should do the
    89 minimum necessary to allow C code to execute to complete the initialization
    90 sequence.
     73The high-level initialization is carried out by :c:func:`boot_card()`.  For the
     74high-level initialization steps see the `Initialization Manager` chapter in the
     75RTEMS Classic API Guide.  There are several system initialization steps which
     76must be implemented by the BSP.
    92 The initial assembly language start code completes its execution by invoking
    93 the shared routine ``boot_card()``.
     78Early BSP Initialization
    95 The label (symbolic name) associated with the starting address of the program
    96 is typically called ``start``.  The start object file is the first object file
    97 linked into the program image so it is ensured that the start code is at offset
    98 0 in the ``.text`` section.  It is the responsibility of the linker script in
    99 conjunction with the compiler specifications file to put the start code in the
    100 correct location in the application image.
     81The BSP may provide a system initialization handler (order
     82:c:macro:`RTEMS_SYSINIT_BSP_EARLY`) to perform an early BSP initialization.
     83This handler is invoked before the memory information and high-level dynamic
     84memory services (workspace and C program heap) are initialized.
    102 boot_card() - Boot the Card
    103 ---------------------------
     86Memory Information
    105 The ``boot_card()`` is the first C code invoked.  This file is the core
    106 component in the RTEMS BSP Initialization Framework and provides the proper
    107 sequencing of initialization steps for the BSP, RTEMS and device drivers. All
    108 BSPs use the same shared version of ``boot_card()`` which is located in the
    109 `bsps/shared/start/bootcard.c <>`_
    110 file.
     89The BSP must provide the memory information to the system with an
     90implementation of the :c:func:`_Memory_Get()` function.  The BSP should use the
     91default implementation in
     92`bsps/shared/shared/start/bspgetworkarea-default.c <>`_.
     93The memory information is used by low-level memory consumers such as the
     94per-CPU data, the workspace, and the C program heap.  The BSP may use a system
     95initialization handler (order :c:macro:`RTEMS_SYSINIT_MEMORY`) to set up the
     96infrastructure used by :c:func:`_Memory_Get()`.
    112 The ``boot_card()`` routine performs the following functions:
     98BSP Initialization
    114 - It disables processor interrupts.
     101The BSP must provide an implementation of the :c:func:`bsp_start()` function.
     102This function is registered as a system initialization handler (order
     103:c:macro:`RTEMS_SYSINIT_BSP_START`) in the module implementing
     104:c:func:`boot_card()`.  The :c:func:`bsp_start()` function should perform a
     105general platform initialization.  The interrupt controllers are usually
     106initialized here.  The C program heap may be used in this handler.  It is not
     107allowed to create any operating system objects, e.g. RTEMS semaphores or tasks.
     108The BSP may register additional system initialization handlers in the module
     109implementing :c:func:`bsp_start()`.
    116 - It sets the command line argument variables
    117   for later use by the application.
     111Error Handling
    119 - It invokes the routine ``rtems_initialize_executive()`` which never returns.
    120   This routine will perform the system initialization through a linker set.
    121   The important BSP-specific steps are outlined below.
     114Errors during system initialization are fatal and end up in a call to
     115:c:func:`_Terminate()`.  See also the `Fatal Error Manager` chapter in the
     116RTEMS Classic API Guide.
    123 - Initialization of the RTEMS Workspace and the C Program Heap.  Usually the
    124   default implementation in
    125   `bsps/shared/start/bspgetworkarea-default.c <>`_
    126   should be sufficient.  Custom implementations can use
    127   ``bsp_work_area_initialize_default()`` or
    128   ``bsp_work_area_initialize_with_table()`` available as inline functions from
    129   ``#include <bsp/bootcard.h>``.
     118The BSP may use BSP-specific fatal error codes, see
     119`<bsp/fatal.h> <>`_.
    131 - Invocation of the BSP-specific routine ``bsp_start()`` which is written in C and
    132   thus able to perform more advanced initialization.  Often MMU, bus and
    133   interrupt controller initialization occurs here.  Since the RTEMS Workspace
    134   and the C Program Heap was already initialized by
    135   ``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
    137 - Specific initialization steps can be registered via the
    138   ``RTEMS_SYSINIT_ITEM()`` provided by ``#include <rtems/sysinit.h>``.
    140 bsp_work_area_initialize() - BSP Specific Work Area Initialization
    141 ------------------------------------------------------------------
    143 This is the first BSP specific C routine to execute during system
    144 initialization.  It must initialize the support for allocating memory from the
    145 C Program Heap and RTEMS Workspace commonly referred to as the work areas.
    146 Many BSPs place the work areas at the end of RAM although this is certainly not
    147 a requirement.  Usually the default implementation in
    148 `bsps/shared/start/bspgetworkarea-default.c <>`_
    149 should be sufficient.  Custom implementations can use
    150 ``bsp_work_area_initialize_default()`` or
    151 ``bsp_work_area_initialize_with_table()`` available as inline functions from
    152 ``#include <bsp/bootcard.h>``.
    154 bsp_start() - BSP Specific Initialization
    155 -----------------------------------------
    157 This is the second BSP specific C routine to execute during system
    158 initialization.  It is called right after ``bsp_work_area_initialize()``.  The
    159 ``bsp_start()`` routine often performs required fundamental hardware
    160 initialization such as setting bus controller registers that do not have a
    161 direct impact on whether or not C code can execute.  The interrupt controllers
    162 are usually initialized here.  The source code for this routine is usually
    163 found in the file ``bsps/${RTEMS_CPU}/${RTEMS_BSP}/start.c``.
    164 It is not allowed to create any operating system objects, e.g. RTEMS
    165 semaphores.
    167 After completing execution, this routine returns to the ``boot_card()``
    168 routine.  In case of errors, the initialization should be terminated via
    169 ``bsp_fatal()``.
     121The BSP should provide an initial extension which implements a fatal error
     122handler.  It should use the default implementation provided by
     123`<bsp/default-initial-extension.h> <>`_ and
     124`bspfatal-default.c <>`_.
     125If the default implementation is used, the BSP must implement a
     126:c:func:`bsp_reset()` function which should reset the platform.
Note: See TracChangeset for help on using the changeset viewer.