path: root/bsp-howto/miscellanous_support.rst
diff options
Diffstat (limited to 'bsp-howto/miscellanous_support.rst')
1 files changed, 364 insertions, 0 deletions
diff --git a/bsp-howto/miscellanous_support.rst b/bsp-howto/miscellanous_support.rst
new file mode 100644
index 0000000..4a487ee
--- /dev/null
+++ b/bsp-howto/miscellanous_support.rst
@@ -0,0 +1,364 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+Miscellaneous Support Files
+GCC Compiler Specifications File
+The file ``bsp_specs`` defines the start files and libraries that are always
+used with this BSP. The format of this file is admittedly cryptic and this
+document will make no attempt to explain it completely. Below is the
+``bsp_specs`` file from the PowerPC psim BSP:
+.. code-block:: c
+ %rename endfile old_endfile
+ %rename startfile old_startfile
+ %rename link old_link
+ *startfile:
+ %{!qrtems: %(old_startfile)} \
+ %{!nostdlib: %{qrtems: ecrti%O%s rtems_crti%O%s crtbegin.o%s start.o%s}}
+ *link:
+ %{!qrtems: %(old_link)} %{qrtems: -Qy -dp -Bstatic -e _start -u __vectors}
+ *endfile:
+ %{!qrtems: %(old_endfile)} %{qrtems: crtend.o%s ecrtn.o%s}
+The first section of this file renames the built-in definition of some
+specification variables so they can be augmented without embedded their
+original definition. The subsequent sections specify what behavior is expected
+when the ``-qrtems`` option is specified.
+The ``*startfile`` section specifies that the BSP specific file ``start.o``
+will be used instead of ``crt0.o``. In addition, various EABI support files
+(``ecrti.o`` etc.) will be linked in with the executable.
+The ``*link`` section adds some arguments to the linker when it is invoked by
+GCC to link an application for this BSP.
+The format of this file is specific to the GNU Compiler Suite. The argument
+used to override and extend the compiler built-in specifications is available
+in all recent GCC versions. The ``-specs`` option is present in all ``egcs``
+distributions and ``gcc`` distributions starting with version 2.8.0.
+Most BSPs provide one or more ``README`` files. Generally, there is a
+``README`` file at the top of the BSP source. This file describes the board
+and its hardware configuration, provides vendor information, local
+configuration information, information on downloading code to the board,
+debugging, etc.. The intent of this file is to help someone begin to use the
+BSP faster.
+A ``README`` file in a BSP subdirectory typically explains something about the
+contents of that subdirectory in greater detail. For example, it may list the
+documentation available for a particular peripheral controller and how to
+obtain that documentation. It may also explain some particularly cryptic part
+of the software in that directory or provide rationale on the implementation.
+This file contains the results of the RTEMS Timing Test Suite. It is in a
+standard format so that results from one BSP can be easily compared with those
+of another target board.
+If a BSP supports multiple variants, then there may be multiple ``times``
+files. Usually these are named ``times.VARIANTn``.
+Tools Subdirectory
+Some BSPs provide additional tools that aid in using the target board. These
+tools run on the development host and are built as part of building the BSP.
+Most common is a script to automate running the RTEMS Test Suites on the BSP.
+Examples of this include:
+- ``powerpc/psim`` includes scripts to ease use of the simulator
+- ``m68k/mvme162`` includes a utility to download across the VMEbus into target
+ memory if the host is a VMEbus board in the same chasis.
+bsp.h Include File
+The file ``include/bsp.h`` contains prototypes and definitions specific to this
+board. Every BSP is required to provide a ``bsp.h``. The best approach to
+writing a ``bsp.h`` is copying an existing one as a starting point.
+Many ``bsp.h`` files provide prototypes of variables defined in the linker
+script (``linkcmds``).
+tm27.h Include File
+The ``tm27`` test from the RTEMS Timing Test Suite is designed to measure the
+length of time required to vector to and return from an interrupt handler. This
+test requires some help from the BSP to know how to cause and manipulate the
+interrupt source used for this measurement. The following is a list of these:
+- ``MUST_WAIT_FOR_INTERRUPT`` - modifies behavior of ``tm27``.
+- ``Install_tm27_vector`` - installs the interrupt service routine for the
+ Interrupt Benchmark Test (``tm27``).
+- ``Cause_tm27_intr`` - generates the interrupt source used in the Interrupt
+ Benchmark Test (``tm27``).
+- ``Clear_tm27_intr`` - clears the interrupt source used in the Interrupt
+ Benchmark Test (``tm27``).
+- ``Lower_tm27_intr`` - lowers the interrupt mask so the interrupt source used
+ in the Interrupt Benchmark Test (``tm27``) can generate a nested interrupt.
+All members of the Timing Test Suite are designed to run *WITHOUT* the Clock
+Device Driver installed. This increases the predictability of the tests'
+execution as well as avoids occassionally including the overhead of a clock
+tick interrupt in the time reported. Because of this it is sometimes possible
+to use the clock tick interrupt source as the source of this test interrupt.
+On other architectures, it is possible to directly force an interrupt to occur.
+Calling Overhead File
+The file ``include/coverhd.h`` contains the overhead associated with invoking
+each directive. This overhead consists of the execution time required to
+package the parameters as well as to execute the "jump to subroutine" and
+"return from subroutine" sequence. The intent of this file is to help separate
+the calling overhead from the actual execution time of a directive. This file
+is only used by the tests in the RTEMS Timing Test Suite.
+The numbers in this file are obtained by running the "Timer
+Overhead"``tmoverhd`` test. The numbers in this file may be 0 and no overhead
+is subtracted from the directive execution times reported by the Timing Suite.
+There is a shared implementation of ``coverhd.h`` which sets all of the
+overhead constants to 0. On faster processors, this is usually the best
+alternative for the BSP as the calling overhead is extremely small. This file
+is located at:
+.. code-block:: c
+ c/src/lib/libbsp/shared/include/coverhd.h
+sbrk() Implementation
+Although nearly all BSPs give all possible memory to the C Program Heap at
+initialization, it is possible for a BSP to configure the initial size of the
+heap small and let it grow on demand. If the BSP wants to dynamically extend
+the heap used by the C Library memory allocation routines (i.e. ``malloc``
+family), then the``sbrk`` routine must be functional. The following is the
+prototype for this routine:
+.. code-block:: c
+ void * sbrk(size_t increment)
+The ``increment`` amount is based upon the ``sbrk_amount`` parameter passed to
+the ``bsp_libc_init`` during system initialization.
+If your BSP does not want to support dynamic heap extension, then you do not
+have to do anything special. However, if you want to support ``sbrk``, you
+must provide an implementation of this method and define
+``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` in ``bsp.h``. This informs
+``rtems/confdefs.h`` to configure the Malloc Family Extensions which support
+bsp_fatal_extension() - Cleanup the Hardware
+The ``bsp_fatal_extension()`` is an optional BSP specific initial extension
+invoked once a fatal system state is reached. Most of the BSPs use the same
+shared version of ``bsp_fatal_extension()`` that does nothing or performs a
+system reset. This implementation is located in the following file:
+.. code-block:: c
+ c/src/lib/libbsp/shared/bspclean.c
+The ``bsp_fatal_extension()`` routine can be used to return to a ROM monitor,
+insure that interrupt sources are disabled, etc.. This routine is the last
+place to ensure a clean shutdown of the hardware. The fatal source, internal
+error indicator, and the fatal code arguments are available to evaluate the
+fatal condition. All of the non-fatal shutdown sequences ultimately pass their
+exit status to ``rtems_shutdown_executive`` and this is what is passed to this
+routine in case the fatal source is ``RTEMS_FATAL_SOURCE_EXIT``.
+On some BSPs, it prints a message indicating that the application completed
+execution and waits for the user to press a key before resetting the board.
+The PowerPC/gen83xx and PowerPC/gen5200 BSPs do this when they are built to
+support the FreeScale evaluation boards. This is convenient when using the
+boards in a development environment and may be disabled for production use.
+Configuration Macros
+Each BSP can define macros in bsp.h which alter some of the the default
+configuration parameters in ``rtems/confdefs.h``. This section describes those
+- ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` must be defined if the BSP has proper
+ support for ``sbrk``. This is discussed in more detail in the previous
+ section.
+.. index:: BSP_IDLE_TASK_BODY
+- ``BSP_IDLE_TASK_BODY`` may be defined to the entry point of a BSP specific
+ IDLE thread implementation. This may be overridden if the application
+ provides its own IDLE task implementation.
+- ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired default stack size
+ for the IDLE task as recommended when using this BSP.
+- ``BSP_INTERRUPT_STACK_SIZE`` may be defined to the desired default interrupt
+ stack size as recommended when using this BSP. This is sometimes required
+ when the BSP developer has knowledge of stack intensive interrupt handlers.
+- ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined when the BSP requires that
+ RTEMS zero out the RTEMS C Program Heap at initialization. If the memory is
+ already zeroed out by a test sequence or boot ROM, then the boot time can be
+ reduced by not zeroing memory twice.
+- ``BSP_DEFAULT_UNIFIED_WORK_AREAS`` is defined when the BSP recommends that
+ the unified work areas configuration should always be used. This is
+ desirable when the BSP is known to always have very little RAM and thus
+ saving memory by any means is desirable.
+set_vector() - Install an Interrupt Vector
+On targets with Simple Vectored Interrupts, the BSP must provide an
+implementation of the ``set_vector`` routine. This routine is responsible for
+installing an interrupt vector. It invokes the support routines necessary to
+install an interrupt handler as either a "raw" or an RTEMS interrupt handler.
+Raw handlers bypass the RTEMS interrupt structure and are responsible for
+saving and restoring all their own registers. Raw handlers are useful for
+handling traps, debug vectors, etc.
+The ``set_vector`` routine is a central place to perform interrupt controller
+manipulation and encapsulate that information. It is usually implemented as
+.. code-block:: c
+ rtems_isr_entry set_vector( /* returns old vector */
+ rtems_isr_entry handler, /* isr routine */
+ rtems_vector_number vector, /* vector number */
+ int type /* RTEMS or RAW intr */
+ )
+ {
+ if the type is RAW
+ install the raw vector
+ else
+ use rtems_interrupt_catch to install the vector
+ perform any interrupt controller necessary to unmask the interrupt source
+ return the previous handler
+ }
+.. note::
+ The i386, PowerPC and ARM ports use a Programmable Interrupt Controller
+ model which does not require the BSP to implement ``set_vector``. BSPs for
+ these architectures must provide a different set of support routines.
+Interrupt Delay Profiling
+The RTEMS profiling needs support by the BSP for the interrupt delay times. In
+case profiling is enabled via the RTEMS build configuration option
+``--enable-profiling`` (in this case the pre-processor symbol
+``RTEMS_PROFILING`` is defined) a BSP may provide data for the interrupt delay
+times. The BSP can feed interrupt delay times with the
+``_Profiling_Update_max_interrupt_delay()`` function (``#include
+<rtems/score/profiling.h>``). For an example please have a look at
+Programmable Interrupt Controller API
+A BSP can use the PIC API to install Interrupt Service Routines through a set
+of generic methods. In order to do so, the header files
+libbsp/shared/include/irq-generic.h and ``libbsp/shared/include/irq-info.h``
+must be included by the bsp specific irq.h file present in the include/
+directory. The irq.h acts as a BSP interrupt support configuration file which
+is used to define some important MACROS. It contains the declarations for any
+required global functions like bsp_interrupt_dispatch(). Thus later on, every
+call to the PIC interface requires including ``<bsp/irq.h>``
+The generic interrupt handler table is intitalized by invoking the
+``bsp_interrupt_initialize()`` method from bsp_start() in the bspstart.c file
+which sets up this table to store the ISR addresses, whose size is based on the
+definition of macros, ``BSP_INTERRUPT_VECTOR_MIN`` and
+``BSP_INTERRUPT_VECTOR_MAX`` in include/bsp.h
+For the generic handler table to properly function, some bsp specific code is
+required, that should be present in ``irq/irq.c``. The bsp-specific functions
+required to be writen by the BSP developer are :
+.. index:: bsp_interrupt_facility_initialize()
+- ``bsp_interrupt_facility_initialize()`` contains bsp specific interrupt
+ initialization code(Clear Pending interrupts by modifying registers, etc.).
+ This method is called from ``bsp_interrupt_initialize()`` internally while
+ setting up the table.
+.. index:: bsp_interrupt_handler_default()
+- ``bsp_interrupt_handler_default()`` acts as a fallback handler when no ISR
+ address has been provided corresponding to a vector in the table.
+.. index:: bsp_interrupt_dispatch()
+- ``bsp_interrupt_dispatch()`` service the ISR by handling any bsp specific
+ code & calling the generic method ``bsp_interrupt_handler_dispatch()`` which
+ in turn services the interrupt by running the ISR after looking it up in the
+ table. It acts as an entry to the interrupt switchboard, since the bsp
+ branches to this function at the time of occurrence of an interrupt.
+.. index:: bsp_interrupt_vector_enable()
+- ``bsp_interrupt_vector_enable()`` enables interrupts and is called in
+ irq-generic.c while setting up the table.
+.. index:: bsp_interrupt_vector_disable()
+- ``bsp_interrupt_vector_disable()`` disables interrupts and is called in
+ irq-generic.c while setting up the table & during other important parts.
+An interrupt handler is installed or removed with the help of the following functions :
+.. code-block:: c
+ rtems_status_code rtems_interrupt_handler_install( /* returns status code */
+ rtems_vector_number vector, /* interrupt vector */
+ const char *info, /* custom identification text */
+ rtems_option options, /* Type of Interrupt */
+ rtems_interrupt_handler handler, /* interrupt handler */
+ void *arg /* parameter to be passed
+ to handler at the time of
+ invocation */
+ )
+ rtems_status_code rtems_interrupt_handler_remove( /* returns status code */
+ rtems_vector_number vector, /* interrupt vector */
+ rtems_interrupt_handler handler, /* interrupt handler */
+ void *arg /* parameter to be passed to handler */
+ )