From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- bsp_howto/miscellanous_support.rst | 364 ------------------------------------- 1 file changed, 364 deletions(-) delete mode 100644 bsp_howto/miscellanous_support.rst (limited to 'bsp_howto/miscellanous_support.rst') diff --git a/bsp_howto/miscellanous_support.rst b/bsp_howto/miscellanous_support.rst deleted file mode 100644 index 4a487ee..0000000 --- a/bsp_howto/miscellanous_support.rst +++ /dev/null @@ -1,364 +0,0 @@ -.. 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. - -README Files -============ - -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. - -times -===== - -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. - -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -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 -``sbrk``. - -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 -macros: - -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -- ``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. - -.. index:: BSP_IDLE_TASK_STACK_SIZE - -- ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired default stack size - for the IDLE task as recommended when using this BSP. - -.. index:: BSP_INTERRUPT_STACK_SIZE - -- ``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. - -.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY - -- ``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. - -.. index:: BSP_DEFAULT_UNIFIED_WORK_AREAS - -- ``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 -follows: - -.. 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 -``). For an example please have a look at -``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``. - -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 ```` - -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 */ - ) -- cgit v1.2.3