rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 19:52:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update due to BSP source reorganization

Browse Source 
This patch is a part of the BSP source reorganization.

Close #3285.
This commit is contained in:
Sebastian Huber 2018-04-26 09:05:20 +02:00
parent 676d3d5d28
commit cb0f55a4b8
14 changed files with 75 additions and 356 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
bsp-howto/clock.rst
View File

@ -23,7 +23,7 @@ system.
The clock driver is usually located in the :file:`clock` directory of the BSP.
Clock drivers must use the :dfn:`Clock Driver Shell` available via the
`clockdrv_shell.h <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/shared/clockdrv_shell.h>`_
`clockimpl.h <https://git.rtems.org/rtems/tree/bsps/shared/dev/clock/clockimpl.h>`_
include file. This include file is not a normal header file and instead
defines the clock driver functions declared in ``#include <rtems/clockdrv.h>``
which are used by RTEMS configuration file ``#include <rtems/confdefs.h>``. In
@ -45,7 +45,7 @@ A clock driver file looks in general like this.
* functions for the Clock Driver Shell.
*/
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Depending on the hardware capabilities one out of three clock driver variants
must be selected.
@ -85,7 +85,7 @@ fields of the ``struct timecounter`` must be zero initialized. Install the
initialized timecounter via ``rtems_timecounter_install()``.
For an example see the `QorIQ clock driver
<https://git.rtems.org/rtems/tree/c/src/lib/libbsp/powerpc/qoriq/clock/clock-config.c>`_.
<https://git.rtems.org/rtems/tree/bsps/powerpc/qoriq/clock/clock-config.c>`_.
.. code-block:: c
@ -129,13 +129,13 @@ For an example see the `QorIQ clock driver
#define Clock_driver_support_initialize_hardware() \
some_support_initialize_hardware()
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Simple Timecounter Variant
~~~~~~~~~~~~~~~~~~~~~~~~~~
For an example see the `ERC32 clock driver
<https://git.rtems.org/rtems/tree/c/src/lib/libbsp/sparc/erc32/clock/ckinit.c>`_.
<https://git.rtems.org/rtems/tree/bsps/sparc/erc32/clock/ckinit.c>`_.
.. code-block:: c
@ -193,13 +193,13 @@ For an example see the `ERC32 clock driver
#define Clock_driver_timecounter_tick() \
some_tc_tick()
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Clock Tick Only Variant
~~~~~~~~~~~~~~~~~~~~~~~
For an example see the `Motrola 68360 clock driver
<https://git.rtems.org/rtems/tree/c/src/lib/libbsp/m68k/gen68360/clock/clock.c>`_.
<https://git.rtems.org/rtems/tree/bsps/m68k/gen68360/clock/clock.c>`_.
.. code-block:: c
@ -215,7 +215,7 @@ For an example see the `Motrola 68360 clock driver
#define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Install Clock Tick Interrupt Service Routine
============================================
@ -248,7 +248,7 @@ macro. The default implementation will do nothing.
#define Clock_driver_support_install_isr( isr ) \
some_support_install_isr( isr )
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Support At Tick
===============
@ -266,7 +266,7 @@ The hardware-specific support at tick is specified by
#define Clock_driver_support_at_tick() \
some_support_at_tick()
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
System Shutdown Support
=======================
@ -292,7 +292,7 @@ overhead.
#define Clock_driver_support_shutdown_hardware() \
some_support_shutdown_hardware()
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
SMP Support
===========
@ -325,7 +325,7 @@ x86 and it hopefully remains that way.
/* Specifiy the clock driver ticks per clock tick value */
#define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123
#include "../../../shared/clockdrv_shell.h"
#include "../../../shared/dev/clock/clockimpl.h"
Clock Driver Ticks Counter
==========================

2
bsp-howto/console.rst
View File

@ -61,7 +61,7 @@ A new serial device driver should consist of three parts.
.. code-block:: makefile
[...]
libbsp_a_SOURCES += ../../shared/console-termios.c
libbsp_a_SOURCES += ../../shared/dev/serial/console-termios.c
libbsp_a_SOURCES += console/console.c
[...]

4
bsp-howto/getentropy.rst
View File

@ -31,10 +31,10 @@ that can only be reached with some extra hardware support. Some microcontrollers
integrate a true random number generator or something similar for cryptographic
applications. That is the preferred source of entropy for most BSPs. For example
the
`atsam BSP uses the TRNG for its entropy source <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/startup/getentropy-trng.c>`_.
`atsam BSP uses the TRNG for its entropy source <https://git.rtems.org/rtems/tree/bsps/arm/atsam/start/getentropy-trng.c>`_.
There is also a quite limited
`default implementation based on the CPU counter <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/shared/getentropy-cpucounter.c>`_.
`default implementation based on the CPU counter <https://git.rtems.org/rtems/tree/bsps/shared/dev/getentropy/getentropy-cpucounter.c>`_.
Due to the fact that it is a time based source, the values provided by
:c:func:`getentropy` are quite predictable. This implementation is not
appropriate for any cryptographic applications but it is good enough for some

4
bsp-howto/i2c.rst
View File

@ -9,9 +9,9 @@ I2C Driver
The Inter-Integrated Circuit (I2C, I²C, IIC) bus drivers should use the
`I2C bus framework <https://git.rtems.org/rtems/tree/cpukit/dev/include/dev/i2c/i2c.h>`_.
For example drivers see the
`Cadence I2C driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/xilinx-zynq/i2c/cadence-i2c.c>`_,
`Cadence I2C driver <https://git.rtems.org/rtems/tree/bsps/arm/xilinx-zynq/i2c/cadence-i2c.c>`_,
the
`Atmel SAM I2C driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/i2c/atsam_i2c_bus.c>`_
`Atmel SAM I2C driver <https://git.rtems.org/rtems/tree/bsps/arm/atsam/i2c/atsam_i2c_bus.c>`_
and the
`I2C framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/i2c01/init.c>`_.

9
bsp-howto/ide_controller.rst
View File

@ -29,15 +29,14 @@ Controller. The capabilities provided by this driver are:
- Write data block through IDE Controller Data Register
The reference implementation for an IDE Controller driver can be found in
``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver is based on the libchip
``bsps/shared/dev/ide``. This driver is based on the libchip
concept and allows to work with any of the IDE Controller chips simply by
appropriate configuration of BSP. Drivers for a particular IDE Controller chips
locate in the following directories: drivers for well-known IDE Controller
chips locate into ``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE
Controller chips integrated with CPU locate into
``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and drivers for custom IDE
chips locate into ``bsps/shared/dev/ide``
and drivers for custom IDE
Controller chips (for example, implemented on FPGA) locate into
``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``. There is a README file in these
``bsps/${RTEMS_CPU}/${RTEMS_BSP/ata``. There is a README file in these
directories for each supported IDE Controller chip. Each of these README
explains how to configure a BSP for that particular IDE Controller chip.

1
bsp-howto/index.rst
View File

@ -43,7 +43,6 @@ to the Community Project hosted at http://www.rtems.org/.
preface
target_dependant_files
makefiles
linker_script
miscellanous_support
initilization_code

111
bsp-howto/initilization_code.rst
View File

@ -24,13 +24,13 @@ 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:
these BSP is contained under the :file:`start` directory in 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
bsps/m68k/gen68340
bsps/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``
@ -124,11 +124,8 @@ 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
`bsps/shared/start/bootcard.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bootcard.c>`_
file.
The ``boot_card()`` routine performs the following functions:
@ -137,61 +134,26 @@ The ``boot_card()`` routine performs the following functions:
- 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``
- It invokes the routine ``rtems_initialize_executive()`` which never returns.
This routine will perform the system initialization through a linker set.
The important BSP-specific steps are outlined below.
- Initialization of the RTEMS Workspace and the C Program Heap. Usually the
default implementation in
`bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.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_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
- Invocation of 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.
- Specific initialization steps can be registered via the
``RTEMS_SYSINIT_ITEM()`` provided by ``#include <rtems/sysinit.h>``.
bsp_work_area_initialize() - BSP Specific Work Area Initialization
------------------------------------------------------------------
@ -200,10 +162,11 @@ 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
a requirement. Usually the default implementation in
`bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.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
@ -215,7 +178,7 @@ initialization. It is called right after ``bsp_work_area_initialize()``. The
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`.
found in the file ``bsps/${RTEMS_CPU}/${RTEMS_BSP}/start.c``.
It is not allowed to create any operating system objects, e.g. RTEMS
semaphores.
@ -223,16 +186,6 @@ 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
----------------------------
@ -258,22 +211,6 @@ All these primitives have a major and a minor number as arguments:
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
==========================

194
bsp-howto/makefiles.rst
View File

@ -1,194 +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.
.. _Makefiles:
Makefiles
*********
.. warning::
This chapter contains outdated and confusing information.
This chapter discusses the Makefiles associated with a BSP. It does not
describe the process of configuring, building, and installing RTEMS. This
chapter will not provide detailed information about this process. Nonetheless,
it is important to remember that the general process consists of four phases as
shown here:
- ``bootstrap``
- ``configure``
- ``build``
- ``install``
During the bootstrap phase, you are using the ``configure.ac`` and
``Makefile.am`` files as input to GNU autoconf and automake to generate a
variety of files. This is done by running the ``bootstrap`` script found at
the top of the RTEMS source tree.
During the configure phase, a number of files are generated. These generated
files are tailored for the specific host/target combination by the configure
script. This set of files includes the Makefiles used to actually compile and
install RTEMS.
During the build phase, the source files are compiled into object files and
libraries are built.
During the install phase, the libraries, header files, and other support files
are copied to the BSP specific installation point. After installation is
successfully completed, the files generated by the configure and build phases
may be removed.
Makefiles Used During The BSP Building Process
==============================================
RTEMS uses the *GNU automake* and *GNU autoconf* automatic configuration
package. Consequently, there are a number of automatically generated files in
each directory in the RTEMS source tree. The ``bootstrap`` script found in the
top level directory of the RTEMS source tree is executed to produce the
automatically generated files. That script must be run from a directory with a
``configure.ac`` file in it. The ``bootstrap`` command is usually invoked in
one of the following manners:
- ``bootstrap`` to regenerate all files that are generated by autoconf and
automake.
- ``bootstrap -c`` to remove all files generated by autoconf and automake.
- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
There is a file named ``Makefile.am`` in each directory of a BSP. This file is
used by *automake* to produce the file named ``Makefile.in`` which is also
found in each directory of a BSP. When modifying a ``Makefile.am``, you can
probably find examples of anything you need to do in one of the BSPs.
The configure process specializes the ``Makefile.in`` files at the time that
RTEMS is configured for a specific development host and target. Makefiles are
automatically generated from the ``Makefile.in`` files. It is necessary for
the BSP developer to provide the ``Makefile.am`` files and generate the
``Makefile.in`` files. Most of the time, it is possible to copy the
``Makefile.am`` from another similar directory and edit it.
The ``Makefile`` files generated are processed when configuring and building
RTEMS for a given BSP.
The BSP developer is responsible for generating ``Makefile.am`` files which
properly build all the files associated with their BSP. Most BSPs will only
have a single ``Makefile.am`` which details the set of source files to build to
compose the BSP support library along with the set of include files that are to
be installed.
This single ``Makefile.am`` at the top of the BSP tree specifies the set of
header files to install. This fragment from the SPARC/ERC32 BSP results in
four header files being installed.
.. code-block:: makefile
include_HEADERS = include/bsp.h
include_HEADERS += include/tm27.h
include_HEADERS += include/erc32.h
include_HEADERS += include/coverhd.h
When adding new include files, you will be adding to the set of
``include_HEADERS``. When you finish editing the ``Makefile.am`` file, do not
forget to run ``bootstrap -p`` to regenerate the ``preinstall.am``.
The ``Makefile.am`` also specifies which source files to build. By convention,
logical components within the BSP each assign their source files to a unique
variable. These variables which define the source files are collected into a
single variable which instructs the GNU autotools that we are building
``libbsp.a``. This fragment from the SPARC/ERC32 BSP shows how the startup
related, miscellaneous support code, and the console device driver source is
managed in the ``Makefile.am``.
.. code-block:: makefile
startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
../../shared/bsppredriverhook.c \
../../shared/bsppost.c ../../sparc/shared/bspstart.c \
../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
startup/spurious.c startup/erc32mec.c startup/boardinit.S
clock_SOURCES = clock/ckinit.c
...
noinst_LIBRARIES = libbsp.a
libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
When adding new files to an existing directory, do not forget to add the new
files to the list of files to be built in the corresponding ``XXX_SOURCES``
variable in the ``Makefile.am`` and run``bootstrap``.
Some BSPs use code that is built in ``libcpu``. If you BSP does this, then you
will need to make sure the objects are pulled into your BSP library. The
following from the SPARC/ERC32 BSP pulls in the cache, register window
management and system call support code from the directory corresponding to its
``RTEMS_CPU`` model.
.. code-block:: makefile
libbsp_a_LIBADD = ../../../libcpu/@RTEMS_CPU@/cache.rel \
../../../libcpu/@RTEMS_CPU@/reg_win.rel \
../../../libcpu/@RTEMS_CPU@/syscall.rel
.. note:
The ``Makefile.am`` files are ONLY processed by ``bootstrap`` and the resulting
``Makefile.in`` files are only processed during the configure process of a
RTEMS build. Therefore, when developing a BSP and adding a new file to a
``Makefile.am``, the already generated ``Makefile`` will not automatically
include the new references unless you configured RTEMS with the
``--enable-maintainer-mode`` option. Otherwise, the new file will not being be
taken into account!
Creating a New BSP Make Customization File
==========================================
When building a BSP or an application using that BSP, it is necessary to tailor
the compilation arguments to account for compiler flags, use custom linker
scripts, include the RTEMS libraries, etc.. The BSP must be built using this
information. Later, once the BSP is installed with the toolset, this same
information must be used when building the application. So a BSP must include
a build configuration file. The configuration file is ``make/custom/BSP.cfg``.
The configuration file is taken into account when building one's application
using the RTEMS template Makefiles (``make/templates``). These application
template Makefiles have been included with the RTEMS source distribution since
the early 1990's. However there is a desire in the RTEMS user community to
move all provided examples to GNU autoconf. They are included in the 4.9
release series and used for all examples provided with RTEMS. There is no
definite time table for obsoleting them. You are free to use these but be
warned they have fallen out of favor with many in the RTEMS community and may
disappear in the future.
The following is a slightly shortened version of the make customization file
for the gen68340 BSP. The original source for this file can be found in the
``make/custom`` directory.
.. code-block:: makefile
# The RTEMS CPU Family and Model
RTEMS_CPU=m68k
RTEMS_CPU_MODEL=m68340
include $(RTEMS_ROOT)/make/custom/default.cfg
# This is the actual bsp directory used during the build process.
RTEMS_BSP_FAMILY=gen68340
# This contains the compiler options necessary to select the CPU model
# and (hopefully) optimize for it.
CPU_CFLAGS = -mcpu=cpu32
# optimize flag: typically -O2
CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
The make customization files have generally grown simpler and simpler with each
RTEMS release. Beginning in the 4.9 release series, the rules for linking an
RTEMS application are shared by all BSPs. Only BSPs which need to perform a
transformation from linked ELF file to a downloadable format have any
additional actions for program link time. In 4.8 and older, every BSP specified
the "make executable" or ``make-exe`` rule and duplicated the same actions.
It is generally easier to copy a ``make/custom`` file from a BSP similar to the
one being developed.

37
bsp-howto/miscellanous_support.rst
View File

@ -128,29 +128,6 @@ 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
=====================
@ -183,11 +160,9 @@ 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
system reset. This implementation is located in the
`bsps/shared/start/bspfatal-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspfatal-default.c>`_
file.
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
@ -294,14 +269,16 @@ case profiling is enabled via the RTEMS build configuration option
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
``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``.
`bsps/sparc/leon3/clock/ckinit.c <https://git.rtems.org/rtems/tree/bsps/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``
`<bsp/irq-generic.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/irq-generic.h>`_
and
`<bsp/irq-info.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/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

2
bsp-howto/networking.rst
View File

@ -13,7 +13,7 @@ Introduction
This chapter is intended to provide an introduction to the procedure for
writing RTEMS network device drivers. The example code is taken from the
'Generic 68360' network device driver. The source code for this driver is
located in the ``c/src/lib/libbsp/m68k/gen68360/network`` directory in the
located in the ``bsps/m68k/gen68360/net`` directory in the
RTEMS source code distribution. Having a copy of this driver at hand when
reading the following notes will help significantly.

14
bsp-howto/real_time_clock.rst
View File

@ -28,12 +28,14 @@ an *RTC* device. The capabilities provided by this driver are:
In this chapter, the abbreviation `TOD` is used for *Time of Day*.
The reference implementation for a real-time clock driver can be found in
``c/src/lib/libbsp/shared/tod.c``. This driver is based on the libchip concept
and can be easily configured to work with any of the RTC chips supported by the
RTC chip drivers in the directory ``c/src/lib/lib/libchip/rtc``. There is a
README file in this directory for each supported RTC chip. Each of these
README explains how to configure the shared libchip implementation of the RTC
driver for that particular RTC chip.
`bsps/shared/dev/rtc/rtc-support.c <https://git.rtems.org/rtems/tree/bsps/shared/dev/rtc/rtc-support.c>`_.
This driver is based on the libchip concept and can be easily configured to
work with any of the RTC chips supported by the RTC chip drivers in the
directory
`bsps/shared/dev/rtc <https://git.rtems.org/rtems/tree/bsps/shared/dev/rtc>`_.
There is a README file in this directory for each supported RTC chip. Each of
these README explains how to configure the shared libchip implementation of the
RTC driver for that particular RTC chip.
The DY-4 DMV177 BSP used the shared libchip implementation of the RTC driver.
There were no DMV177 specific configuration routines. A BSP could use

2
bsp-howto/spi.rst
View File

@ -11,7 +11,7 @@ The Serial Peripheral Interface (SPI) bus drivers should use the
<https://git.rtems.org/rtems/tree/cpukit/dev/include/dev/spi/spi.h>`_.
For
example drivers see the
`Atmel SAM SPI driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/spi/atsam_spi_bus.c>`_
`Atmel SAM SPI driver <https://git.rtems.org/rtems/tree/bsps/arm/atsam/spi/atsam_spi_bus.c>`_
and the
`SPI framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/spi01/init.c>`_.

25
bsp-howto/target_dependant_files.rst
View File

@ -60,8 +60,9 @@ Board Dependent
This class of code provides the most specific glue between RTEMS and a
particular board. This code is represented by the Board Support Packages and
associated Device Drivers. Sources for the BSPs included in the RTEMS
distribution are located in the directory ``c/src/lib/libbsp``. The BSP source
directory is further subdivided based on the CPU family and BSP.
distribution are located in the directory
`bsps <https://git.rtems.org/rtems/tree/bsps>`_. The BSP source directory is
further subdivided based on the CPU family and BSP.
Some BSPs may support multiple board models within a single board family. This
is necessary when the board supports multiple variants on a single base board.
@ -80,9 +81,12 @@ designing a board, the goal of this library is to let the software engineer do
the same thing.
The source code for the reusable peripheral driver library may be found in the
directory ``c/src/lib/libchip``. The source code is further divided based upon
the class of hardware. Example classes include serial communications
controllers, real-time clocks, non-volatile memory, and network controllers.
directory
`cpukit/dev <https://git.rtems.org/rtems/tree/cpukit/dev>`_ or
`bsps/shared/dev <https://git.rtems.org/rtems/tree/bsps/shared/dev>`_. The
source code is further divided based upon the class of hardware. Example
classes include serial communications controllers, real-time clocks,
non-volatile memory, and network controllers.
Questions to Ask
================
@ -126,16 +130,11 @@ CPU Dependent Executive Files
=============================
The CPU dependent files in the RTEMS executive source code are found in the
following directory:
.. code-block:: c
cpukit/score/cpu/<CPU>
where <CPU> is replaced with the CPU family name.
``cpukit/score/cpu/${RTEMS_CPU}`` directories. The ``${RTEMS_CPU}`` is a
particular architecture, e.g. arm, powerpc, riscv, sparc, etc.
Within each CPU dependent directory inside the executive proper is a file named
``<CPU>.h`` which contains information about each of the supported CPU models
:file:`cpu.h` which contains information about each of the supported CPU models
within that family.
Board Support Package Structure

2
networking/networking_driver.rst
View File

@ -14,7 +14,7 @@ Introduction
This chapter is intended to provide an introduction to the procedure for
writing RTEMS network device drivers. The example code is taken from the
'Generic 68360' network device driver. The source code for this driver is
located in the :file:`c/src/lib/libbsp/m68k/gen68360/network` directory in the
located in the :file:`bsps/m68k/gen68360/net` directory in the
RTEMS source code distribution. Having a copy of this driver at hand when
reading the following notes will help significantly.