diff options
Diffstat (limited to 'bsp_howto/initilization_code.rst')
| -rw-r--r-- | bsp_howto/initilization_code.rst | 382 |
1 files changed, 0 insertions, 382 deletions
diff --git a/bsp_howto/initilization_code.rst b/bsp_howto/initilization_code.rst deleted file mode 100644 index a69731e..0000000 --- a/bsp_howto/initilization_code.rst +++ /dev/null @@ -1,382 +0,0 @@ -.. 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*. |