diff options
Diffstat (limited to 'bsp-howto/initilization_code.rst')
| -rw-r--r-- | bsp-howto/initilization_code.rst | 382 |
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 +################### + +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. + +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 +``Makefile.am`` explicitly references the following files for this +functionality. + +.. 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 +simplicity. + +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 +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 +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 +semaphores. + +After completing execution, this routine returns to the ``boot_card()`` +routine. In case of errors, the initialization should be terminated via +``bsp_fatal()``. + +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 +disabled. + +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 +at: + +.. 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 +address. + +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 +itself. + +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*. |