From 420525079c4b66025b1a924be13f29f54d288942 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 4 Feb 2020 09:06:35 +0100 Subject: 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 `_ -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 `_ -.. 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 `_. +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 `_ -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 `_ - 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 ``. - -- 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 ``. +The BSP may use BSP-specific fatal error codes, see +` `_. -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 `_ -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_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 +` `_ and +`bspfatal-default.c `_. +If the default implementation is used, the BSP must implement a +:c:func:`bsp_reset()` function which should reset the platform. -- cgit v1.2.3