path: root/bsp-howto/initilization_code.rst
diff options
Diffstat (limited to 'bsp-howto/initilization_code.rst')
1 files changed, 382 insertions, 0 deletions
diff --git a/bsp-howto/initilization_code.rst b/bsp-howto/initilization_code.rst
new file mode 100644
index 0000000..a69731e
--- /dev/null
+++ b/bsp-howto/initilization_code.rst
@@ -0,0 +1,382 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+Initialization Code
+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
+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 divided into two subdirectories under the BSP source directory.
+The BSP source code for these BSPs is in the following directories:
+.. code-block:: shell
+ c/src/lib/libbsp/m68k/gen68340
+ c/src/lib/libbsp/sparc/erc32
+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.
+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
+```` explicitly references the following files for this
+.. code-block:: shell
+ ../../sparc/shared/start.S
+.. note::
+ In most BSPs, the directory named ``start340`` in the gen68340 BSP would be
+ simply named ``start`` or start followed by a BSP designation.
+Required Global Variables
+Although not strictly part of initialization, there are a few global variables
+assumed to exist by reusable device drivers. These global variables should
+only defined by the BSP when using one of these device drivers.
+The BSP author probably should be aware of the ``Configuration`` Table
+structure generated by ``<rtems/confdefs.h>`` during debug but should not
+explicitly reference it in the source code. There are helper routines provided
+by RTEMS to access individual fields.
+In older RTEMS versions, the BSP included a number of required global
+variables. We have made every attempt to eliminate these in the interest of
+Board Initialization
+This section describes the steps an application goes through from the time the
+first BSP code is executed until the first application task executes.
+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
+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
+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
+following file:
+.. code-block:: shell
+ c/src/lib/libbsp/shared/bootcard.c
+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 BSP specific routine ``bsp_work_area_initialize()`` which is
+ supposed to initialize the RTEMS Workspace and the C Program Heap. Usually
+ the default implementation in ``c/src/lib/libbsp/shared/bspgetworkarea.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>``.
+- It invokes 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.
+- It invokes the RTEMS directive ``rtems_initialize_data_structures()`` to
+ initialize the RTEMS executive to a state where objects can be created but
+ tasking is not enabled.
+- It invokes the BSP specific routine ``bsp_libc_init()`` to initialize the C
+ Library. Usually the default implementation in
+ ``c/src/lib/libbsp/shared/bsplibc.c`` should be sufficient.
+- It invokes the RTEMS directive ``rtems_initialize_before_drivers()`` to
+ initialize the MPCI Server thread in a multiprocessor configuration and
+ execute API specific extensions.
+- It invokes the BSP specific routine ``bsp_predriver_hook``. For most BSPs,
+ the implementation of this routine does nothing.
+- It invokes the RTEMS directive ``rtems_initialize_device_drivers()`` to
+ initialize the statically configured set of device drivers in the order they
+ were specified in the Configuration Table.
+- It invokes the BSP specific routine ``bsp_postdriver_hook``. For
+ most BSPs, the implementation of this routine does nothing. However, some
+ BSPs use this hook and perform some initialization which must be done at
+ this point in the initialization sequence. This is the last opportunity
+ for the BSP to insert BSP specific code into the initialization sequence.
+- It invokes the RTEMS directive ``rtems_initialize_start_multitasking()``
+ which initiates multitasking and performs a context switch to the first user
+ application task and may enable interrupts as a side-effect of that context
+ switch. The context switch saves the executing context. The application
+ runs now. The directive ``rtems_shutdown_executive()`` will return to the
+ saved context. The ``exit()`` function will use this directive. After a
+ return to the saved context a fatal system state is reached. The fatal
+ source is ``RTEMS_FATAL_SOURCE_EXIT`` with a fatal code set to the value
+ passed to rtems_shutdown_executive(). The enabling of interrupts during the
+ first context switch is often the source for fatal errors during BSP
+ development because the BSP did not clear and/or disable all interrupt
+ sources and a spurious interrupt will occur. When in the context of the
+ first task but before its body has been entered, any C++ Global Constructors
+ will be invoked.
+That's it. We just went through the entire sequence.
+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:file:`c/src/lib/libbsp/shared/bspgetworkarea.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 :file:`c/src/lib/libbsp/${CPU}/${BSP}/startup/bspstart.c`.
+It is not allowed to create any operating system objects, e.g. RTEMS
+After completing execution, this routine returns to the ``boot_card()``
+routine. In case of errors, the initialization should be terminated via
+bsp_predriver_hook() - BSP Specific Predriver Hook
+The ``bsp_predriver_hook()`` method is the BSP specific routine that is invoked
+immediately before the the device drivers are initialized. RTEMS initialization
+is complete but interrupts and tasking are disabled.
+The BSP may use the shared version of this routine which is empty. Most BSPs
+do not provide a specific implementation of this callback.
+Device Driver Initialization
+At this point in the initialization sequence, the initialization routines for
+all of the device drivers specified in the Device Driver Table are invoked.
+The initialization routines are invoked in the order they appear in the Device
+Driver Table.
+The Driver Address Table is part of the RTEMS Configuration Table. It defines
+device drivers entry points (initialization, open, close, read, write, and
+control). For more information about this table, please refer to the
+*Configuring a System* chapter in the *RTEMS Application C User's Guide*.
+The RTEMS initialization procedure calls the initialization function for every
+driver defined in the RTEMS Configuration Table (this allows one to include
+only the drivers needed by the application).
+All these primitives have a major and a minor number as arguments:
+- the major number refers to the driver type,
+- the minor number is used to control two peripherals with the same driver (for
+ instance, we define only one major number for the serial driver, but two
+ minor numbers for channel A and B if there are two channels in the UART).
+RTEMS Postdriver Callback
+The ``bsp_postdriver_hook()`` BSP specific routine is invoked immediately after
+the the device drivers and MPCI are initialized. Interrupts and tasking are
+Most BSPs use the shared implementation of this routine which is responsible
+for opening the device ``/dev/console`` for standard input, output and error if
+the application has configured the Console Device Driver. This file is located
+.. code-block:: shell
+ c/src/lib/libbsp/shared/bsppost.c
+The Interrupt Vector Table
+The Interrupt Vector Table is called different things on different processor
+families but the basic functionality is the same. Each entry in the Table
+corresponds to the handler routine for a particular interrupt source. When an
+interrupt from that source occurs, the specified handler routine is invoked.
+Some context information is saved by the processor automatically when this
+happens. RTEMS saves enough context information so that an interrupt service
+routine can be implemented in a high level language.
+On some processors, the Interrupt Vector Table is at a fixed address. If this
+address is in RAM, then usually the BSP only has to initialize it to contain
+pointers to default handlers. If the table is in ROM, then the application
+developer will have to take special steps to fill in the table.
+If the base address of the Interrupt Vector Table can be dynamically changed to
+an arbitrary address, then the RTEMS port to that processor family will usually
+allocate its own table and install it. For example, on some members of the
+Motorola MC68xxx family, the Vector Base Register (``vbr``) contains this base
+Interrupt Vector Table on the gen68340 BSP
+The gen68340 BSP provides a default Interrupt Vector Table in the file
+``$BSP_ROOT/start340/start340.s``. After the ``entry`` label is the definition
+of space reserved for the table of interrupts vectors. This space is assigned
+the symbolic name of ``__uhoh`` in the ``gen68340`` BSP.
+At ``__uhoh`` label is the default interrupt handler routine. This routine is
+only called when an unexpected interrupts is raised. One can add their own
+routine there (in that case there's a call to a routine -
+$BSP_ROOT/startup/dumpanic.c - that prints which address caused the interrupt
+and the contents of the registers, stack, etc.), but this should not return.
+Chip Select Initialization
+When the microprocessor accesses a memory area, address decoding is handled by
+an address decoder, so that the microprocessor knows which memory chip(s) to
+access. The following figure illustrates this:
+.. code-block:: c
+ +-------------------+
+ ------------| |
+ ------------| |------------
+ ------------| Address |------------
+ ------------| Decoder |------------
+ ------------| |------------
+ ------------| |
+ +-------------------+
+ CPU Bus Chip Select
+The Chip Select registers must be programmed such that they match the
+``linkcmds`` settings. In the gen68340 BSP, ROM and RAM addresses can be found
+in both the ``linkcmds`` and initialization code, but this is not a great way
+to do this. It is better to define addresses in the linker script.
+Integrated Processor Registers Initialization
+The CPUs used in many embedded systems are highly complex devices with multiple
+peripherals on the CPU itself. For these devices, there are always some
+specific integrated processor registers that must be initialized. Refer to the
+processors' manuals for details on these registers and be VERY careful
+programming them.
+Data Section Recopy
+The next initialization part can be found in
+``$BSP340_ROOT/start340/init68340.c``. First the Interrupt Vector Table is
+copied into RAM, then the data section recopy is initiated
+(``_CopyDataClearBSSAndStart`` in ``$BSP340_ROOT/start340/startfor340only.s``).
+This code performs the following actions:
+- copies the .data section from ROM to its location reserved in RAM (see
+ :ref:`Initialized Data` for more details about this copy),
+- clear ``.bss`` section (all the non-initialized data will take value 0).
+The RTEMS Configuration Table
+The RTEMS configuration table contains the maximum number of objects RTEMS can
+handle during the application (e.g. maximum number of tasks, semaphores,
+etc.). It's used to allocate the size for the RTEMS inner data structures.
+The RTEMS configuration table is application dependent, which means that one
+has to provide one per application. It is usually defined by defining macros
+and including the header file ``<rtems/confdefs.h>``. In simple applications
+such as the tests provided with RTEMS, it is commonly found in the main module
+of the application. For more complex applications, it may be in a file by
+The header file ``<rtems/confdefs.h>`` defines a constant table named
+``Configuration``. With RTEMS 4.8 and older, it was accepted practice for the
+BSP to copy this table into a modifiable copy named ``BSP_Configuration``.
+This copy of the table was modified to define the base address of the RTEMS
+Executive Workspace as well as to reflect any BSP and device driver
+requirements not automatically handled by the application. In 4.9 and newer,
+we have eliminated the BSP copies of the configuration tables and are making
+efforts to make the configuration information generated by
+``<rtems/confdefs.h>`` constant and read only.
+For more information on the RTEMS Configuration Table, refer to the *RTEMS
+Application C User's Guide*.