Changeset cb0f55a in rtems-docs


Ignore:
Timestamp:
Apr 26, 2018, 7:05:20 AM (15 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
06519a5
Parents:
676d3d5
git-author:
Sebastian Huber <sebastian.huber@…> (04/26/18 07:05:20)
git-committer:
Sebastian Huber <sebastian.huber@…> (04/27/18 10:49:57)
Message:

Update due to BSP source reorganization

This patch is a part of the BSP source reorganization.

Close #3285.

Files:
1 deleted
13 edited

Legend:

Unmodified
Added
Removed

  • bsp-howto/clock.rst

    r676d3d5 rcb0f55a  
    2424The clock driver is usually located in the :file:`clock` directory of the BSP.
    2525Clock drivers must use the :dfn:`Clock Driver Shell` available via the
    26 `clockdrv_shell.h <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/shared/clockdrv_shell.h>`_
     26`clockimpl.h <https://git.rtems.org/rtems/tree/bsps/shared/dev/clock/clockimpl.h>`_
    2727include file.  This include file is not a normal header file and instead
    2828defines the clock driver functions declared in ``#include <rtems/clockdrv.h>``
    … …  
    4646     */
    4747
    48     #include "../../../shared/clockdrv_shell.h"
     48    #include "../../../shared/dev/clock/clockimpl.h"
    4949
    5050Depending on the hardware capabilities one out of three clock driver variants
    … …  
    8686
    8787For an example see the `QorIQ clock driver
    88 <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/powerpc/qoriq/clock/clock-config.c>`_.
     88<https://git.rtems.org/rtems/tree/bsps/powerpc/qoriq/clock/clock-config.c>`_.
    8989
    9090.. code-block:: c
    … …  
    130130      some_support_initialize_hardware()
    131131
    132     #include "../../../shared/clockdrv_shell.h"
     132    #include "../../../shared/dev/clock/clockimpl.h"
    133133
    134134Simple Timecounter Variant
    … …  
    136136
    137137For an example see the `ERC32 clock driver
    138 <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/sparc/erc32/clock/ckinit.c>`_.
     138<https://git.rtems.org/rtems/tree/bsps/sparc/erc32/clock/ckinit.c>`_.
    139139
    140140.. code-block:: c
    … …  
    194194      some_tc_tick()
    195195
    196     #include "../../../shared/clockdrv_shell.h"
     196    #include "../../../shared/dev/clock/clockimpl.h"
    197197
    198198Clock Tick Only Variant
    … …  
    200200
    201201For an example see the `Motrola 68360 clock driver
    202 <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/m68k/gen68360/clock/clock.c>`_.
     202<https://git.rtems.org/rtems/tree/bsps/m68k/gen68360/clock/clock.c>`_.
    203203
    204204.. code-block:: c
    … …  
    216216    #define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER
    217217
    218     #include "../../../shared/clockdrv_shell.h"
     218    #include "../../../shared/dev/clock/clockimpl.h"
    219219
    220220Install Clock Tick Interrupt Service Routine
    … …  
    249249      some_support_install_isr( isr )
    250250
    251     #include "../../../shared/clockdrv_shell.h"
     251    #include "../../../shared/dev/clock/clockimpl.h"
    252252
    253253Support At Tick
    … …  
    267267      some_support_at_tick()
    268268
    269     #include "../../../shared/clockdrv_shell.h"
     269    #include "../../../shared/dev/clock/clockimpl.h"
    270270
    271271System Shutdown Support
    … …  
    293293      some_support_shutdown_hardware()
    294294
    295     #include "../../../shared/clockdrv_shell.h"
     295    #include "../../../shared/dev/clock/clockimpl.h"
    296296
    297297SMP Support
    … …  
    326326    #define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123
    327327
    328     #include "../../../shared/clockdrv_shell.h"
     328    #include "../../../shared/dev/clock/clockimpl.h"
    329329
    330330Clock Driver Ticks Counter

  • bsp-howto/console.rst

    r676d3d5 rcb0f55a  
    6262
    6363      [...]
    64       libbsp_a_SOURCES += ../../shared/console-termios.c
     64      libbsp_a_SOURCES += ../../shared/dev/serial/console-termios.c
    6565      libbsp_a_SOURCES += console/console.c
    6666      [...]

  • bsp-howto/getentropy.rst

    r676d3d5 rcb0f55a  
    3232applications. That is the preferred source of entropy for most BSPs. For example
    3333the
    34 `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>`_.
     34`atsam BSP uses the TRNG for its entropy source <https://git.rtems.org/rtems/tree/bsps/arm/atsam/start/getentropy-trng.c>`_.
    3535
    3636There is also a quite limited
    37 `default implementation based on the CPU counter <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/shared/getentropy-cpucounter.c>`_.
     37`default implementation based on the CPU counter <https://git.rtems.org/rtems/tree/bsps/shared/dev/getentropy/getentropy-cpucounter.c>`_.
    3838Due to the fact that it is a time based source, the values provided by
    3939:c:func:`getentropy` are quite predictable. This implementation is not

  • bsp-howto/i2c.rst

    r676d3d5 rcb0f55a  
    1010`I2C bus framework <https://git.rtems.org/rtems/tree/cpukit/dev/include/dev/i2c/i2c.h>`_.
    1111For example drivers see the
    12 `Cadence I2C driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/xilinx-zynq/i2c/cadence-i2c.c>`_,
     12`Cadence I2C driver <https://git.rtems.org/rtems/tree/bsps/arm/xilinx-zynq/i2c/cadence-i2c.c>`_,
    1313the
    14 `Atmel SAM I2C driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/i2c/atsam_i2c_bus.c>`_
     14`Atmel SAM I2C driver <https://git.rtems.org/rtems/tree/bsps/arm/atsam/i2c/atsam_i2c_bus.c>`_
    1515and the
    1616`I2C framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/i2c01/init.c>`_.

  • bsp-howto/ide_controller.rst

    r676d3d5 rcb0f55a  
    3030
    3131The reference implementation for an IDE Controller driver can be found in
    32 ``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver is based on the libchip
     32``bsps/shared/dev/ide``. This driver is based on the libchip
    3333concept and allows to work with any of the IDE Controller chips simply by
    3434appropriate configuration of BSP. Drivers for a particular IDE Controller chips
    3535locate in the following directories: drivers for well-known IDE Controller
    36 chips locate into ``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE
    37 Controller chips integrated with CPU locate into
    38 ``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and drivers for custom IDE
     36chips locate into ``bsps/shared/dev/ide``
     37and drivers for custom IDE
    3938Controller chips (for example, implemented on FPGA) locate into
    40 ``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``.  There is a README file in these
     39``bsps/${RTEMS_CPU}/${RTEMS_BSP/ata``.  There is a README file in these
    4140directories for each supported IDE Controller chip. Each of these README
    4241explains how to configure a BSP for that particular IDE Controller chip.

  • bsp-howto/index.rst

    r676d3d5 rcb0f55a  
    4444        preface
    4545        target_dependant_files
    46         makefiles
    4746        linker_script
    4847        miscellanous_support

  • bsp-howto/initilization_code.rst

    r676d3d5 rcb0f55a  
    2525Most of the examples in this chapter will be based on the SPARC/ERC32 and
    2626m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization for
    27 these BSP is divided into two subdirectories under the BSP source directory.
    28 The BSP source code for these BSPs is in the following directories:
     27these BSP is contained under the :file:`start` directory in the BSP source
     28directory.  The BSP source code for these BSPs is in the following directories:
    2929
    3030.. code-block:: shell
    3131
    32     c/src/lib/libbsp/m68k/gen68340
    33     c/src/lib/libbsp/sparc/erc32
     32    bsps/m68k/gen68340
     33    bsps/sparc/erc32
    3434
    3535Both BSPs contain startup code written in assembly language and C.  The
    … …  
    125125sequencing of initialization steps for the BSP, RTEMS and device drivers. All
    126126BSPs use the same shared version of ``boot_card()`` which is located in the
    127 following file:
    128 
    129 .. code-block:: shell
    130 
    131     c/src/lib/libbsp/shared/bootcard.c
     127`bsps/shared/start/bootcard.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bootcard.c>`_
     128file.
    132129
    133130The ``boot_card()`` routine performs the following functions:
    … …  
    138135  for later use by the application.
    139136
    140 - It invokes the BSP specific routine ``bsp_work_area_initialize()`` which is
    141   supposed to initialize the RTEMS Workspace and the C Program Heap.  Usually
    142   the default implementation in ``c/src/lib/libbsp/shared/bspgetworkarea.c``
     137- It invokes the routine ``rtems_initialize_executive()`` which never returns.
     138  This routine will perform the system initialization through a linker set.
     139  The important BSP-specific steps are outlined below.
     140
     141- Initialization of the RTEMS Workspace and the C Program Heap.  Usually the
     142  default implementation in
     143  `bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.c>`_
    143144  should be sufficient.  Custom implementations can use
    144145  ``bsp_work_area_initialize_default()`` or
    145   ``bsp_work_area_initialize_with_table()`` available as inline functions
    146   from``#include <bsp/bootcard.h>``.
    147 
    148 - It invokes the BSP specific routine ``bsp_start()`` which is written in C and
     146  ``bsp_work_area_initialize_with_table()`` available as inline functions from
     147  ``#include <bsp/bootcard.h>``.
     148
     149- Invocation of the BSP-specific routine ``bsp_start()`` which is written in C and
    149150  thus able to perform more advanced initialization.  Often MMU, bus and
    150151  interrupt controller initialization occurs here.  Since the RTEMS Workspace
    … …  
    152153  ``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
    153154
    154 - It invokes the RTEMS directive ``rtems_initialize_data_structures()`` to
    155   initialize the RTEMS executive to a state where objects can be created but
    156   tasking is not enabled.
    157 
    158 - It invokes the BSP specific routine ``bsp_libc_init()`` to initialize the C
    159   Library.  Usually the default implementation in
    160   ``c/src/lib/libbsp/shared/bsplibc.c`` should be sufficient.
    161 
    162 - It invokes the RTEMS directive ``rtems_initialize_before_drivers()`` to
    163   initialize the MPCI Server thread in a multiprocessor configuration and
    164   execute API specific extensions.
    165 
    166 - It invokes the BSP specific routine ``bsp_predriver_hook``. For most BSPs,
    167   the implementation of this routine does nothing.
    168 
    169 - It invokes the RTEMS directive ``rtems_initialize_device_drivers()`` to
    170   initialize the statically configured set of device drivers in the order they
    171   were specified in the Configuration Table.
    172 
    173 - It invokes the BSP specific routine ``bsp_postdriver_hook``. For
    174   most BSPs, the implementation of this routine does nothing.  However, some
    175   BSPs use this hook and perform some initialization which must be done at
    176   this point in the initialization sequence.  This is the last opportunity
    177   for the BSP to insert BSP specific code into the initialization sequence.
    178 
    179 - It invokes the RTEMS directive ``rtems_initialize_start_multitasking()``
    180   which initiates multitasking and performs a context switch to the first user
    181   application task and may enable interrupts as a side-effect of that context
    182   switch.  The context switch saves the executing context.  The application
    183   runs now.  The directive ``rtems_shutdown_executive()`` will return to the
    184   saved context.  The ``exit()`` function will use this directive.  After a
    185   return to the saved context a fatal system state is reached.  The fatal
    186   source is ``RTEMS_FATAL_SOURCE_EXIT`` with a fatal code set to the value
    187   passed to rtems_shutdown_executive().  The enabling of interrupts during the
    188   first context switch is often the source for fatal errors during BSP
    189   development because the BSP did not clear and/or disable all interrupt
    190   sources and a spurious interrupt will occur.  When in the context of the
    191   first task but before its body has been entered, any C++ Global Constructors
    192   will be invoked.
    193 
    194 That's it.  We just went through the entire sequence.
     155- Specific initialization steps can be registered via the
     156  ``RTEMS_SYSINIT_ITEM()`` provided by ``#include <rtems/sysinit.h>``.
    195157
    196158bsp_work_area_initialize() - BSP Specific Work Area Initialization
    … …  
    201163C Program Heap and RTEMS Workspace commonly referred to as the work areas.
    202164Many BSPs place the work areas at the end of RAM although this is certainly not
    203 a requirement.  Usually the default implementation
    204 in:file:`c/src/lib/libbsp/shared/bspgetworkarea.c` should be sufficient.
    205 Custom implementations can use ``bsp_work_area_initialize_default()``
    206 or``bsp_work_area_initialize_with_table()`` available as inline functions from
     165a requirement.  Usually the default implementation in
     166`bsps/shared/start/bspgetworkarea-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspgetworkarea-default.c>`_
     167should be sufficient.  Custom implementations can use
     168``bsp_work_area_initialize_default()`` or
     169``bsp_work_area_initialize_with_table()`` available as inline functions from
    207170``#include <bsp/bootcard.h>``.
    208171
    … …  
    216179direct impact on whether or not C code can execute.  The interrupt controllers
    217180are usually initialized here.  The source code for this routine is usually
    218 found in the file :file:`c/src/lib/libbsp/${CPU}/${BSP}/startup/bspstart.c`.
     181found in the file ``bsps/${RTEMS_CPU}/${RTEMS_BSP}/start.c``.
    219182It is not allowed to create any operating system objects, e.g. RTEMS
    220183semaphores.
    … …  
    223186routine.  In case of errors, the initialization should be terminated via
    224187``bsp_fatal()``.
    225 
    226 bsp_predriver_hook() - BSP Specific Predriver Hook
    227 --------------------------------------------------
    228 
    229 The ``bsp_predriver_hook()`` method is the BSP specific routine that is invoked
    230 immediately before the the device drivers are initialized. RTEMS initialization
    231 is complete but interrupts and tasking are disabled.
    232 
    233 The BSP may use the shared version of this routine which is empty.  Most BSPs
    234 do not provide a specific implementation of this callback.
    235188
    236189Device Driver Initialization
    … …  
    258211  instance, we define only one major number for the serial driver, but two
    259212  minor numbers for channel A and B if there are two channels in the UART).
    260 
    261 RTEMS Postdriver Callback
    262 -------------------------
    263 
    264 The ``bsp_postdriver_hook()`` BSP specific routine is invoked immediately after
    265 the the device drivers and MPCI are initialized.  Interrupts and tasking are
    266 disabled.
    267 
    268 Most BSPs use the shared implementation of this routine which is responsible
    269 for opening the device ``/dev/console`` for standard input, output and error if
    270 the application has configured the Console Device Driver.  This file is located
    271 at:
    272 
    273 .. code-block:: shell
    274 
    275     c/src/lib/libbsp/shared/bsppost.c
    276213
    277214The Interrupt Vector Table

  • bsp-howto/miscellanous_support.rst

    r676d3d5 rcb0f55a  
    129129On other architectures, it is possible to directly force an interrupt to occur.
    130130
    131 Calling Overhead File
    132 =====================
    133 
    134 The file ``include/coverhd.h`` contains the overhead associated with invoking
    135 each directive.  This overhead consists of the execution time required to
    136 package the parameters as well as to execute the "jump to subroutine" and
    137 "return from subroutine" sequence.  The intent of this file is to help separate
    138 the calling overhead from the actual execution time of a directive.  This file
    139 is only used by the tests in the RTEMS Timing Test Suite.
    140 
    141 The numbers in this file are obtained by running the "Timer
    142 Overhead"``tmoverhd`` test.  The numbers in this file may be 0 and no overhead
    143 is subtracted from the directive execution times reported by the Timing Suite.
    144 
    145 There is a shared implementation of ``coverhd.h`` which sets all of the
    146 overhead constants to 0.  On faster processors, this is usually the best
    147 alternative for the BSP as the calling overhead is extremely small.  This file
    148 is located at:
    149 
    150 .. code-block:: c
    151 
    152     c/src/lib/libbsp/shared/include/coverhd.h
    153 
    154131sbrk() Implementation
    155132=====================
    … …  
    184161invoked once a fatal system state is reached.  Most of the BSPs use the same
    185162shared version of ``bsp_fatal_extension()`` that does nothing or performs a
    186 system reset.  This implementation is located in the following file:
    187 
    188 .. code-block:: c
    189 
    190     c/src/lib/libbsp/shared/bspclean.c
     163system reset.  This implementation is located in the
     164`bsps/shared/start/bspfatal-default.c <https://git.rtems.org/rtems/tree/bsps/shared/start/bspfatal-default.c>`_
     165file.
    191166
    192167The ``bsp_fatal_extension()`` routine can be used to return to a ROM monitor,
    … …  
    295270``_Profiling_Update_max_interrupt_delay()`` function (``#include
    296271<rtems/score/profiling.h>``).  For an example please have a look at
    297 ``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``.
     272`bsps/sparc/leon3/clock/ckinit.c <https://git.rtems.org/rtems/tree/bsps/sparc/leon3/clock/ckinit.c>`_.
    298273
    299274Programmable Interrupt Controller API
    … …  
    302277A BSP can use the PIC API to install Interrupt Service Routines through a set
    303278of generic methods. In order to do so, the header files
    304 libbsp/shared/include/irq-generic.h and ``libbsp/shared/include/irq-info.h``
     279`<bsp/irq-generic.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/irq-generic.h>`_
     280and
     281`<bsp/irq-info.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/irq-info.h>`_
    305282must be included by the bsp specific irq.h file present in the include/
    306283directory. The irq.h acts as a BSP interrupt support configuration file which

  • bsp-howto/networking.rst

    r676d3d5 rcb0f55a  
    1414writing RTEMS network device drivers.  The example code is taken from the
    1515'Generic 68360' network device driver.  The source code for this driver is
    16 located in the ``c/src/lib/libbsp/m68k/gen68360/network`` directory in the
     16located in the ``bsps/m68k/gen68360/net`` directory in the
    1717RTEMS source code distribution.  Having a copy of this driver at hand when
    1818reading the following notes will help significantly.

  • bsp-howto/real_time_clock.rst

    r676d3d5 rcb0f55a  
    2929
    3030The reference implementation for a real-time clock driver can be found in
    31 ``c/src/lib/libbsp/shared/tod.c``.  This driver is based on the libchip concept
    32 and can be easily configured to work with any of the RTC chips supported by the
    33 RTC chip drivers in the directory ``c/src/lib/lib/libchip/rtc``.  There is a
    34 README file in this directory for each supported RTC chip.  Each of these
    35 README explains how to configure the shared libchip implementation of the RTC
    36 driver for that particular RTC chip.
     31`bsps/shared/dev/rtc/rtc-support.c <https://git.rtems.org/rtems/tree/bsps/shared/dev/rtc/rtc-support.c>`_.
     32This driver is based on the libchip concept and can be easily configured to
     33work with any of the RTC chips supported by the RTC chip drivers in the
     34directory
     35`bsps/shared/dev/rtc <https://git.rtems.org/rtems/tree/bsps/shared/dev/rtc>`_.
     36There is a README file in this directory for each supported RTC chip.  Each of
     37these README explains how to configure the shared libchip implementation of the
     38RTC driver for that particular RTC chip.
    3739
    3840The DY-4 DMV177 BSP used the shared libchip implementation of the RTC driver.

  • bsp-howto/spi.rst

    r676d3d5 rcb0f55a  
    1212For
    1313example drivers see the
    14 `Atmel SAM SPI driver <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/spi/atsam_spi_bus.c>`_
     14`Atmel SAM SPI driver <https://git.rtems.org/rtems/tree/bsps/arm/atsam/spi/atsam_spi_bus.c>`_
    1515and the
    1616`SPI framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/spi01/init.c>`_.

  • bsp-howto/target_dependant_files.rst

    r676d3d5 rcb0f55a  
    6161particular board.  This code is represented by the Board Support Packages and
    6262associated Device Drivers.  Sources for the BSPs included in the RTEMS
    63 distribution are located in the directory ``c/src/lib/libbsp``.  The BSP source
    64 directory is further subdivided based on the CPU family and BSP.
     63distribution are located in the directory
     64`bsps <https://git.rtems.org/rtems/tree/bsps>`_.  The BSP source directory is
     65further subdivided based on the CPU family and BSP.
    6566
    6667Some BSPs may support multiple board models within a single board family.  This
    … …  
    8182
    8283The source code for the reusable peripheral driver library may be found in the
    83 directory ``c/src/lib/libchip``.  The source code is further divided based upon
    84 the class of hardware.  Example classes include serial communications
    85 controllers, real-time clocks, non-volatile memory, and network controllers.
     84directory
     85`cpukit/dev <https://git.rtems.org/rtems/tree/cpukit/dev>`_ or
     86`bsps/shared/dev <https://git.rtems.org/rtems/tree/bsps/shared/dev>`_.  The
     87source code is further divided based upon the class of hardware.  Example
     88classes include serial communications controllers, real-time clocks,
     89non-volatile memory, and network controllers.
    8690
    8791Questions to Ask
    … …  
    127131
    128132The CPU dependent files in the RTEMS executive source code are found in the
    129 following directory:
    130 
    131 .. code-block:: c
    132 
    133     cpukit/score/cpu/<CPU>
    134 
    135 where <CPU> is replaced with the CPU family name.
     133``cpukit/score/cpu/${RTEMS_CPU}`` directories.  The ``${RTEMS_CPU}`` is a
     134particular architecture, e.g. arm, powerpc, riscv, sparc, etc.
    136135
    137136Within each CPU dependent directory inside the executive proper is a file named
    138 ``<CPU>.h`` which contains information about each of the supported CPU models
     137:file:`cpu.h` which contains information about each of the supported CPU models
    139138within that family.
    140139

  • networking/networking_driver.rst

    r676d3d5 rcb0f55a  
    1515writing RTEMS network device drivers.  The example code is taken from the
    1616'Generic 68360' network device driver.  The source code for this driver is
    17 located in the :file:`c/src/lib/libbsp/m68k/gen68360/network` directory in the
     17located in the :file:`bsps/m68k/gen68360/net` directory in the
    1818RTEMS source code distribution.  Having a copy of this driver at hand when
    1919reading the following notes will help significantly.
Note: See TracChangeset for help on using the changeset viewer.