[rtems-docs commit] bsp-howto: Rework system initialization chapter
Sebastian Huber
sebh at rtems.org
Tue Feb 4 08:58:44 UTC 2020
Module: rtems-docs
Branch: master
Commit: 420525079c4b66025b1a924be13f29f54d288942
Changeset: http://git.rtems.org/rtems-docs/commit/?id=420525079c4b66025b1a924be13f29f54d288942
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Feb 4 09:06:35 2020 +0100
bsp-howto: Rework system initialization chapter
Update #2852.
Update #3838.
---
bsp-howto/index.rst | 4 +-
bsp-howto/initilization_code.rst | 253 ++++++++++++++++-----------------------
2 files changed, 107 insertions(+), 150 deletions(-)
diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst
index 67f64d8..e95c1b8 100644
--- a/bsp-howto/index.rst
+++ b/bsp-howto/index.rst
@@ -9,8 +9,8 @@ RTEMS BSP and Driver Guide (|version|).
.. topic:: Copyrights and License
| |copy| 2017 Christian Mauderer
- | |copy| 2016, 2018 embedded brains GmbH
- | |copy| 2016, 2018 Sebastian Huber
+ | |copy| 2016, 2020 embedded brains GmbH
+ | |copy| 2016, 2020 Sebastian Huber
| |copy| 1988, 2017 On-Line Applications Research Corporation (OAR)
.. include:: ../common/license.rst
diff --git a/bsp-howto/initilization_code.rst b/bsp-howto/initilization_code.rst
index 30c7537..38e7b3a 100644
--- a/bsp-howto/initilization_code.rst
+++ b/bsp-howto/initilization_code.rst
@@ -1,169 +1,126 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2020 embedded brains GmbH
+.. Copyright (C) 2020 Sebastian Huber
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-Initialization Code
-*******************
-
-.. warning::
-
- This chapter contains outdated and confusing information.
+System Initialization
+*********************
Introduction
============
-The initialization code is the first piece of code executed when there's a
-reset/reboot. Its purpose is to initialize the board for the application. This
-chapter contains a narrative description of the initialization process followed
-by a description of each of the files and routines commonly found in the BSP
-related to initialization. The remainder of this chapter covers special issues
-which require attention such as interrupt vector table and chip select
-initialization.
+The system initialization consists of a low-level initialization performed by
+the start code in the start file (:file:`start.o`) and a high-level
+initialization carried out by :c:func:`boot_card()`. The final step of a
+successful high-level initialization is to switch to the initialization task
+and change into normal system mode with multi-threading enabled. Errors during
+system initialization are fatal and end up in a call to :c:func:`_Terminate()`.
+
+Low-Level Initialization via Start Code in the Start File (start.o)
+===================================================================
+
+The start code in the start file (:file:`start.o`) must be provided by the BSP.
+It is the first file presented to the linker and starts the process to link an
+executable (application image). It should contain the entry symbol of the
+executable. It is the responsibility of the linker script in conjunction with
+the compiler specifications file or compiler options to put the start code in
+the correct location in the executable. The start code is typically written in
+assembly language since it will tinker with the stack pointer. The general
+rule of thumb is that the start code in assembly language should do the minimum
+necessary to allow C code to execute to complete the initialization sequence.
+
+The low-level system initialization may depend on a platform initialization
+carried out by a boot loader. The low-level system initialization may perform
+the following steps:
+
+* Initialize the initialization stack. The initialization stack should use the
+ ISR stack area. The symbols :c:macro:`_ISR_Stack_area_begin`,
+ :c:macro:`_ISR_Stack_area_end`, and :c:macro:`_ISR_Stack_size` should be used
+ to do this.
+
+* Initialize processor registers and modes.
+
+* Initialize pins.
+
+* Initialize clocks (PLLs).
+
+* Initialize memory controllers.
+
+* Initialize instruction, data, and unified caches.
+
+* Initialize memory management or protection units (MMU).
+
+* Initialize processor exceptions.
+
+* Copy the data sections from a read-only section to the runtime location.
+
+* Set the BSS (``.bss``) section to zero.
+
+* Initialize the C runtime environment.
+
+* Call :c:func:`boot_card()` to hand over to the high-level initialization.
+
+For examples of start file codes see:
+
+* `bsps/arm/shared/start/start.S <https://git.rtems.org/rtems/tree/bsps/arm/shared/start/start.S>`_
-Most of the examples in this chapter will be based on the SPARC/ERC32 and
-m68k/gen68340 BSP initialization code. Like most BSPs, the initialization for
-these BSP is contained under the :file:`start` directory in the BSP source
-directory. The BSP source code for these BSPs is in the following directories:
+* `bsps/riscv/shared/start/start.S <https://git.rtems.org/rtems/tree/bsps/riscv/shared/start/start.S>`_
-.. code-block:: shell
+High-Level Initialization via boot_card()
+=========================================
- bsps/m68k/gen68340
- bsps/sparc/erc32
+The high-level initialization is carried out by :c:func:`boot_card()`. For the
+high-level initialization steps see the `Initialization Manager` chapter in the
+RTEMS Classic API Guide. There are several system initialization steps which
+must be implemented by the BSP.
-Both BSPs contain startup code written in assembly language and C. The
-gen68340 BSP has its early initialization start code in the ``start340``
-subdirectory and its C startup code in the ``startup`` directory. In the
-``start340`` directory are two source files. The file ``startfor340only.s`` is
-the simpler of these files as it only has initialization code for a MC68340
-board. The file ``start340.s`` contains initialization for a 68349 based board
-as well.
+Early BSP Initialization
+------------------------
-Similarly, the ERC32 BSP has startup code written in assembly language and C.
-However, this BSP shares this code with other SPARC BSPs. Thus the
-``Makefile.am`` explicitly references the following files for this
-functionality.
+The BSP may provide a system initialization handler (order
+:c:macro:`RTEMS_SYSINIT_BSP_EARLY`) to perform an early BSP initialization.
+This handler is invoked before the memory information and high-level dynamic
+memory services (workspace and C program heap) are initialized.
-.. code-block:: shell
+Memory Information
+------------------
- ../../sparc/shared/start.S
+The BSP must provide the memory information to the system with an
+implementation of the :c:func:`_Memory_Get()` function. The BSP should use the
+default implementation in
+`bsps/shared/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.c>`_.
+The memory information is used by low-level memory consumers such as the
+per-CPU data, the workspace, and the C program heap. The BSP may use a system
+initialization handler (order :c:macro:`RTEMS_SYSINIT_MEMORY`) to set up the
+infrastructure used by :c:func:`_Memory_Get()`.
-.. note::
+BSP Initialization
+------------------
- In most BSPs, the directory named ``start340`` in the gen68340 BSP would be
- simply named ``start`` or start followed by a BSP designation.
+The BSP must provide an implementation of the :c:func:`bsp_start()` function.
+This function is registered as a system initialization handler (order
+:c:macro:`RTEMS_SYSINIT_BSP_START`) in the module implementing
+:c:func:`boot_card()`. The :c:func:`bsp_start()` function should perform a
+general platform initialization. The interrupt controllers are usually
+initialized here. The C program heap may be used in this handler. It is not
+allowed to create any operating system objects, e.g. RTEMS semaphores or tasks.
+The BSP may register additional system initialization handlers in the module
+implementing :c:func:`bsp_start()`.
-Board Initialization
-====================
+Error Handling
+==============
-This section describes the steps an application goes through from the time the
-first BSP code is executed until the first application task executes.
+Errors during system initialization are fatal and end up in a call to
+:c:func:`_Terminate()`. See also the `Fatal Error Manager` chapter in the
+RTEMS Classic API Guide.
-The initialization flows from assembly language start code to the shared
-``bootcard.c`` framework then through the C Library, RTEMS, device driver
-initialization phases, and the context switch to the first application task.
-After this, the application executes until it calls ``exit``,
-``rtems_shutdown_executive``, or some other normal termination initiating
-routine and a fatal system state is reached. The optional
-``bsp_fatal_extension`` initial extension can perform BSP specific system
-termination.
-
-The routines invoked during this will be discussed and their location in the
-RTEMS source tree pointed out as we discuss each.
-
-Start Code - Assembly Language Initialization
----------------------------------------------
-
-The assembly language code in the directory ``start`` is the first part of the
-application to execute. It is responsible for initializing the processor and
-board enough to execute the rest of the BSP. This includes:
-
-- initializing the stack
-
-- zeroing out the uninitialized data section ``.bss``
-
-- disabling external interrupts
-
-- copy the initialized data from ROM to RAM
-
-The general rule of thumb is that the start code in assembly should do the
-minimum necessary to allow C code to execute to complete the initialization
-sequence.
-
-The initial assembly language start code completes its execution by invoking
-the shared routine ``boot_card()``.
-
-The label (symbolic name) associated with the starting address of the program
-is typically called ``start``. The start object file is the first object file
-linked into the program image so it is ensured that the start code is at offset
-0 in the ``.text`` section. It is the responsibility of the linker script in
-conjunction with the compiler specifications file to put the start code in the
-correct location in the application image.
-
-boot_card() - Boot the Card
----------------------------
-
-The ``boot_card()`` is the first C code invoked. This file is the core
-component in the RTEMS BSP Initialization Framework and provides the proper
-sequencing of initialization steps for the BSP, RTEMS and device drivers. All
-BSPs use the same shared version of ``boot_card()`` which is located in the
-`bsps/shared/start/bootcard.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bootcard.c>`_
-file.
-
-The ``boot_card()`` routine performs the following functions:
-
-- It disables processor interrupts.
-
-- It sets the command line argument variables
- for later use by the application.
-
-- It invokes the routine ``rtems_initialize_executive()`` which never returns.
- This routine will perform the system initialization through a linker set.
- The important BSP-specific steps are outlined below.
-
-- Initialization of the RTEMS Workspace and the C Program Heap. Usually the
- default implementation in
- `bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.c>`_
- should be sufficient. Custom implementations can use
- ``bsp_work_area_initialize_default()`` or
- ``bsp_work_area_initialize_with_table()`` available as inline functions from
- ``#include <bsp/bootcard.h>``.
-
-- Invocation of the BSP-specific routine ``bsp_start()`` which is written in C and
- thus able to perform more advanced initialization. Often MMU, bus and
- interrupt controller initialization occurs here. Since the RTEMS Workspace
- and the C Program Heap was already initialized by
- ``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
-
-- Specific initialization steps can be registered via the
- ``RTEMS_SYSINIT_ITEM()`` provided by ``#include <rtems/sysinit.h>``.
+The BSP may use BSP-specific fatal error codes, see
+`<bsp/fatal.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/fatal.h>`_.
-bsp_work_area_initialize() - BSP Specific Work Area Initialization
-------------------------------------------------------------------
-
-This is the first BSP specific C routine to execute during system
-initialization. It must initialize the support for allocating memory from the
-C Program Heap and RTEMS Workspace commonly referred to as the work areas.
-Many BSPs place the work areas at the end of RAM although this is certainly not
-a requirement. Usually the default implementation in
-`bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.c>`_
-should be sufficient. Custom implementations can use
-``bsp_work_area_initialize_default()`` or
-``bsp_work_area_initialize_with_table()`` available as inline functions from
-``#include <bsp/bootcard.h>``.
-
-bsp_start() - BSP Specific Initialization
------------------------------------------
-
-This is the second BSP specific C routine to execute during system
-initialization. It is called right after ``bsp_work_area_initialize()``. The
-``bsp_start()`` routine often performs required fundamental hardware
-initialization such as setting bus controller registers that do not have a
-direct impact on whether or not C code can execute. The interrupt controllers
-are usually initialized here. The source code for this routine is usually
-found in the file ``bsps/${RTEMS_CPU}/${RTEMS_BSP}/start.c``.
-It is not allowed to create any operating system objects, e.g. RTEMS
-semaphores.
-
-After completing execution, this routine returns to the ``boot_card()``
-routine. In case of errors, the initialization should be terminated via
-``bsp_fatal()``.
+The BSP should provide an initial extension which implements a fatal error
+handler. It should use the default implementation provided by
+`<bsp/default-initial-extension.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/default-initial-extension.h>`_ and
+`bspfatal-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspfatal-default.c>`_.
+If the default implementation is used, the BSP must implement a
+:c:func:`bsp_reset()` function which should reset the platform.
More information about the vc
mailing list