Changeset cb0f55a in rtems-docs
- Timestamp:
- Apr 26, 2018, 7:05:20 AM (3 years ago)
- Branches:
- 5, am, 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)
- Files:
-
- 1 deleted
- 13 edited
Legend:
- Unmodified
- Added
- Removed
-
bsp-howto/clock.rst
r676d3d5 rcb0f55a 24 24 The clock driver is usually located in the :file:`clock` directory of the BSP. 25 25 Clock drivers must use the :dfn:`Clock Driver Shell` available via the 26 `clock drv_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>`_ 27 27 include file. This include file is not a normal header file and instead 28 28 defines the clock driver functions declared in ``#include <rtems/clockdrv.h>`` … … 46 46 */ 47 47 48 #include "../../../shared/ clockdrv_shell.h"48 #include "../../../shared/dev/clock/clockimpl.h" 49 49 50 50 Depending on the hardware capabilities one out of three clock driver variants … … 86 86 87 87 For 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>`_. 89 89 90 90 .. code-block:: c … … 130 130 some_support_initialize_hardware() 131 131 132 #include "../../../shared/ clockdrv_shell.h"132 #include "../../../shared/dev/clock/clockimpl.h" 133 133 134 134 Simple Timecounter Variant … … 136 136 137 137 For 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>`_. 139 139 140 140 .. code-block:: c … … 194 194 some_tc_tick() 195 195 196 #include "../../../shared/ clockdrv_shell.h"196 #include "../../../shared/dev/clock/clockimpl.h" 197 197 198 198 Clock Tick Only Variant … … 200 200 201 201 For 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>`_. 203 203 204 204 .. code-block:: c … … 216 216 #define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER 217 217 218 #include "../../../shared/ clockdrv_shell.h"218 #include "../../../shared/dev/clock/clockimpl.h" 219 219 220 220 Install Clock Tick Interrupt Service Routine … … 249 249 some_support_install_isr( isr ) 250 250 251 #include "../../../shared/ clockdrv_shell.h"251 #include "../../../shared/dev/clock/clockimpl.h" 252 252 253 253 Support At Tick … … 267 267 some_support_at_tick() 268 268 269 #include "../../../shared/ clockdrv_shell.h"269 #include "../../../shared/dev/clock/clockimpl.h" 270 270 271 271 System Shutdown Support … … 293 293 some_support_shutdown_hardware() 294 294 295 #include "../../../shared/ clockdrv_shell.h"295 #include "../../../shared/dev/clock/clockimpl.h" 296 296 297 297 SMP Support … … 326 326 #define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123 327 327 328 #include "../../../shared/ clockdrv_shell.h"328 #include "../../../shared/dev/clock/clockimpl.h" 329 329 330 330 Clock Driver Ticks Counter -
bsp-howto/console.rst
r676d3d5 rcb0f55a 62 62 63 63 [...] 64 libbsp_a_SOURCES += ../../shared/ console-termios.c64 libbsp_a_SOURCES += ../../shared/dev/serial/console-termios.c 65 65 libbsp_a_SOURCES += console/console.c 66 66 [...] -
bsp-howto/getentropy.rst
r676d3d5 rcb0f55a 32 32 applications. That is the preferred source of entropy for most BSPs. For example 33 33 the 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>`_. 35 35 36 36 There 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>`_. 38 38 Due to the fact that it is a time based source, the values provided by 39 39 :c:func:`getentropy` are quite predictable. This implementation is not -
bsp-howto/i2c.rst
r676d3d5 rcb0f55a 10 10 `I2C bus framework <https://git.rtems.org/rtems/tree/cpukit/dev/include/dev/i2c/i2c.h>`_. 11 11 For 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>`_, 13 13 the 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>`_ 15 15 and the 16 16 `I2C framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/i2c01/init.c>`_. -
bsp-howto/ide_controller.rst
r676d3d5 rcb0f55a 30 30 31 31 The 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 libchip32 ``bsps/shared/dev/ide``. This driver is based on the libchip 33 33 concept and allows to work with any of the IDE Controller chips simply by 34 34 appropriate configuration of BSP. Drivers for a particular IDE Controller chips 35 35 locate 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 36 chips locate into ``bsps/shared/dev/ide`` 37 and drivers for custom IDE 39 38 Controller chips (for example, implemented on FPGA) locate into 40 `` $RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``. There is a README file in these39 ``bsps/${RTEMS_CPU}/${RTEMS_BSP/ata``. There is a README file in these 41 40 directories for each supported IDE Controller chip. Each of these README 42 41 explains how to configure a BSP for that particular IDE Controller chip. -
bsp-howto/index.rst
r676d3d5 rcb0f55a 44 44 preface 45 45 target_dependant_files 46 makefiles47 46 linker_script 48 47 miscellanous_support -
bsp-howto/initilization_code.rst
r676d3d5 rcb0f55a 25 25 Most of the examples in this chapter will be based on the SPARC/ERC32 and 26 26 m68k/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:27 these BSP is contained under the :file:`start` directory in the BSP source 28 directory. The BSP source code for these BSPs is in the following directories: 29 29 30 30 .. code-block:: shell 31 31 32 c/src/lib/libbsp/m68k/gen6834033 c/src/lib/libbsp/sparc/erc3232 bsps/m68k/gen68340 33 bsps/sparc/erc32 34 34 35 35 Both BSPs contain startup code written in assembly language and C. The … … 125 125 sequencing of initialization steps for the BSP, RTEMS and device drivers. All 126 126 BSPs 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>`_ 128 file. 132 129 133 130 The ``boot_card()`` routine performs the following functions: … … 138 135 for later use by the application. 139 136 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>`_ 143 144 should be sufficient. Custom implementations can use 144 145 ``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 - I t invokes the BSPspecific routine ``bsp_start()`` which is written in C and146 ``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 149 150 thus able to perform more advanced initialization. Often MMU, bus and 150 151 interrupt controller initialization occurs here. Since the RTEMS Workspace … … 152 153 ``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc. 153 154 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>``. 195 157 196 158 bsp_work_area_initialize() - BSP Specific Work Area Initialization … … 201 163 C Program Heap and RTEMS Workspace commonly referred to as the work areas. 202 164 Many 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 165 a 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>`_ 167 should 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 207 170 ``#include <bsp/bootcard.h>``. 208 171 … … 216 179 direct impact on whether or not C code can execute. The interrupt controllers 217 180 are 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`.181 found in the file ``bsps/${RTEMS_CPU}/${RTEMS_BSP}/start.c``. 219 182 It is not allowed to create any operating system objects, e.g. RTEMS 220 183 semaphores. … … 223 186 routine. In case of errors, the initialization should be terminated via 224 187 ``bsp_fatal()``. 225 226 bsp_predriver_hook() - BSP Specific Predriver Hook227 --------------------------------------------------228 229 The ``bsp_predriver_hook()`` method is the BSP specific routine that is invoked230 immediately before the the device drivers are initialized. RTEMS initialization231 is complete but interrupts and tasking are disabled.232 233 The BSP may use the shared version of this routine which is empty. Most BSPs234 do not provide a specific implementation of this callback.235 188 236 189 Device Driver Initialization … … 258 211 instance, we define only one major number for the serial driver, but two 259 212 minor numbers for channel A and B if there are two channels in the UART). 260 261 RTEMS Postdriver Callback262 -------------------------263 264 The ``bsp_postdriver_hook()`` BSP specific routine is invoked immediately after265 the the device drivers and MPCI are initialized. Interrupts and tasking are266 disabled.267 268 Most BSPs use the shared implementation of this routine which is responsible269 for opening the device ``/dev/console`` for standard input, output and error if270 the application has configured the Console Device Driver. This file is located271 at:272 273 .. code-block:: shell274 275 c/src/lib/libbsp/shared/bsppost.c276 213 277 214 The Interrupt Vector Table -
bsp-howto/miscellanous_support.rst
r676d3d5 rcb0f55a 129 129 On other architectures, it is possible to directly force an interrupt to occur. 130 130 131 Calling Overhead File132 =====================133 134 The file ``include/coverhd.h`` contains the overhead associated with invoking135 each directive. This overhead consists of the execution time required to136 package the parameters as well as to execute the "jump to subroutine" and137 "return from subroutine" sequence. The intent of this file is to help separate138 the calling overhead from the actual execution time of a directive. This file139 is only used by the tests in the RTEMS Timing Test Suite.140 141 The numbers in this file are obtained by running the "Timer142 Overhead"``tmoverhd`` test. The numbers in this file may be 0 and no overhead143 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 the146 overhead constants to 0. On faster processors, this is usually the best147 alternative for the BSP as the calling overhead is extremely small. This file148 is located at:149 150 .. code-block:: c151 152 c/src/lib/libbsp/shared/include/coverhd.h153 154 131 sbrk() Implementation 155 132 ===================== … … 184 161 invoked once a fatal system state is reached. Most of the BSPs use the same 185 162 shared 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 163 system 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>`_ 165 file. 191 166 192 167 The ``bsp_fatal_extension()`` routine can be used to return to a ROM monitor, … … 295 270 ``_Profiling_Update_max_interrupt_delay()`` function (``#include 296 271 <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>`_. 298 273 299 274 Programmable Interrupt Controller API … … 302 277 A BSP can use the PIC API to install Interrupt Service Routines through a set 303 278 of 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>`_ 280 and 281 `<bsp/irq-info.h> <https://git.rtems.org/rtems/tree/bsps/include/bsp/irq-info.h>`_ 305 282 must be included by the bsp specific irq.h file present in the include/ 306 283 directory. The irq.h acts as a BSP interrupt support configuration file which -
bsp-howto/networking.rst
r676d3d5 rcb0f55a 14 14 writing RTEMS network device drivers. The example code is taken from the 15 15 '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 the16 located in the ``bsps/m68k/gen68360/net`` directory in the 17 17 RTEMS source code distribution. Having a copy of this driver at hand when 18 18 reading the following notes will help significantly. -
bsp-howto/real_time_clock.rst
r676d3d5 rcb0f55a 29 29 30 30 The 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>`_. 32 This driver is based on the libchip concept and can be easily configured to 33 work with any of the RTC chips supported by the RTC chip drivers in the 34 directory 35 `bsps/shared/dev/rtc <https://git.rtems.org/rtems/tree/bsps/shared/dev/rtc>`_. 36 There is a README file in this directory for each supported RTC chip. Each of 37 these README explains how to configure the shared libchip implementation of the 38 RTC driver for that particular RTC chip. 37 39 38 40 The DY-4 DMV177 BSP used the shared libchip implementation of the RTC driver. -
bsp-howto/spi.rst
r676d3d5 rcb0f55a 12 12 For 13 13 example 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>`_ 15 15 and the 16 16 `SPI framework test <https://git.rtems.org/rtems/tree/testsuites/libtests/spi01/init.c>`_. -
bsp-howto/target_dependant_files.rst
r676d3d5 rcb0f55a 61 61 particular board. This code is represented by the Board Support Packages and 62 62 associated 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. 63 distribution are located in the directory 64 `bsps <https://git.rtems.org/rtems/tree/bsps>`_. The BSP source directory is 65 further subdivided based on the CPU family and BSP. 65 66 66 67 Some BSPs may support multiple board models within a single board family. This … … 81 82 82 83 The 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. 84 directory 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 87 source code is further divided based upon the class of hardware. Example 88 classes include serial communications controllers, real-time clocks, 89 non-volatile memory, and network controllers. 86 90 87 91 Questions to Ask … … 127 131 128 132 The 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 134 particular architecture, e.g. arm, powerpc, riscv, sparc, etc. 136 135 137 136 Within each CPU dependent directory inside the executive proper is a file named 138 ``<CPU>.h`` which contains information about each of the supported CPU models137 :file:`cpu.h` which contains information about each of the supported CPU models 139 138 within that family. 140 139 -
networking/networking_driver.rst
r676d3d5 rcb0f55a 15 15 writing RTEMS network device drivers. The example code is taken from the 16 16 '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 the17 located in the :file:`bsps/m68k/gen68360/net` directory in the 18 18 RTEMS source code distribution. Having a copy of this driver at hand when 19 19 reading the following notes will help significantly.
Note: See TracChangeset
for help on using the changeset viewer.