1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | |
---|
4 | .. COMMENT: COPYRIGHT (c) 1988-2002. |
---|
5 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
6 | .. COMMENT: All rights reserved. |
---|
7 | |
---|
8 | Miscellaneous Support Files |
---|
9 | *************************** |
---|
10 | |
---|
11 | .. warning:: |
---|
12 | |
---|
13 | This chapter contains outdated and confusing information. |
---|
14 | |
---|
15 | GCC Compiler Specifications File |
---|
16 | ================================ |
---|
17 | |
---|
18 | The file ``bsp_specs`` defines the start files and libraries that are always |
---|
19 | used with this BSP. The format of this file is admittedly cryptic and this |
---|
20 | document will make no attempt to explain it completely. Below is the |
---|
21 | ``bsp_specs`` file from the PowerPC psim BSP: |
---|
22 | |
---|
23 | .. code-block:: c |
---|
24 | |
---|
25 | %rename endfile old_endfile |
---|
26 | %rename startfile old_startfile |
---|
27 | %rename link old_link |
---|
28 | *startfile: |
---|
29 | %{!qrtems: %(old_startfile)} \ |
---|
30 | %{!nostdlib: %{qrtems: ecrti%O%s rtems_crti%O%s crtbegin.o%s start.o%s}} |
---|
31 | *link: |
---|
32 | %{!qrtems: %(old_link)} %{qrtems: -Qy -dp -Bstatic -e _start -u __vectors} |
---|
33 | *endfile: |
---|
34 | %{!qrtems: %(old_endfile)} %{qrtems: crtend.o%s ecrtn.o%s} |
---|
35 | |
---|
36 | The first section of this file renames the built-in definition of some |
---|
37 | specification variables so they can be augmented without embedded their |
---|
38 | original definition. The subsequent sections specify what behavior is expected |
---|
39 | when the ``-qrtems`` option is specified. |
---|
40 | |
---|
41 | The ``*startfile`` section specifies that the BSP specific file ``start.o`` |
---|
42 | will be used instead of ``crt0.o``. In addition, various EABI support files |
---|
43 | (``ecrti.o`` etc.) will be linked in with the executable. |
---|
44 | |
---|
45 | The ``*link`` section adds some arguments to the linker when it is invoked by |
---|
46 | GCC to link an application for this BSP. |
---|
47 | |
---|
48 | The format of this file is specific to the GNU Compiler Suite. The argument |
---|
49 | used to override and extend the compiler built-in specifications is available |
---|
50 | in all recent GCC versions. The ``-specs`` option is present in all ``egcs`` |
---|
51 | distributions and ``gcc`` distributions starting with version 2.8.0. |
---|
52 | |
---|
53 | README Files |
---|
54 | ============ |
---|
55 | |
---|
56 | Most BSPs provide one or more ``README`` files. Generally, there is a |
---|
57 | ``README`` file at the top of the BSP source. This file describes the board |
---|
58 | and its hardware configuration, provides vendor information, local |
---|
59 | configuration information, information on downloading code to the board, |
---|
60 | debugging, etc.. The intent of this file is to help someone begin to use the |
---|
61 | BSP faster. |
---|
62 | |
---|
63 | A ``README`` file in a BSP subdirectory typically explains something about the |
---|
64 | contents of that subdirectory in greater detail. For example, it may list the |
---|
65 | documentation available for a particular peripheral controller and how to |
---|
66 | obtain that documentation. It may also explain some particularly cryptic part |
---|
67 | of the software in that directory or provide rationale on the implementation. |
---|
68 | |
---|
69 | Times |
---|
70 | ===== |
---|
71 | |
---|
72 | This file contains the results of the RTEMS Timing Test Suite. It is in a |
---|
73 | standard format so that results from one BSP can be easily compared with those |
---|
74 | of another target board. |
---|
75 | |
---|
76 | If a BSP supports multiple variants, then there may be multiple ``times`` |
---|
77 | files. Usually these are named ``times.VARIANTn``. |
---|
78 | |
---|
79 | Tools Subdirectory |
---|
80 | ================== |
---|
81 | |
---|
82 | Some BSPs provide additional tools that aid in using the target board. These |
---|
83 | tools run on the development host and are built as part of building the BSP. |
---|
84 | Most common is a script to automate running the RTEMS Test Suites on the BSP. |
---|
85 | Examples of this include: |
---|
86 | |
---|
87 | - ``powerpc/psim`` includes scripts to ease use of the simulator |
---|
88 | |
---|
89 | - ``m68k/mvme162`` includes a utility to download across the VMEbus into target |
---|
90 | memory if the host is a VMEbus board in the same chasis. |
---|
91 | |
---|
92 | bsp.h Include File |
---|
93 | ================== |
---|
94 | |
---|
95 | The file ``include/bsp.h`` contains prototypes and definitions specific to this |
---|
96 | board. Every BSP is required to provide a ``bsp.h``. The best approach to |
---|
97 | writing a ``bsp.h`` is copying an existing one as a starting point. |
---|
98 | |
---|
99 | Many ``bsp.h`` files provide prototypes of variables defined in the linker |
---|
100 | script (``linkcmds``). |
---|
101 | |
---|
102 | tm27.h Include File |
---|
103 | =================== |
---|
104 | |
---|
105 | The ``tm27`` test from the RTEMS Timing Test Suite is designed to measure the |
---|
106 | length of time required to vector to and return from an interrupt handler. This |
---|
107 | test requires some help from the BSP to know how to cause and manipulate the |
---|
108 | interrupt source used for this measurement. The following is a list of these: |
---|
109 | |
---|
110 | - ``MUST_WAIT_FOR_INTERRUPT`` - modifies behavior of ``tm27``. |
---|
111 | |
---|
112 | - ``Install_tm27_vector`` - installs the interrupt service routine for the |
---|
113 | Interrupt Benchmark Test (``tm27``). |
---|
114 | |
---|
115 | - ``Cause_tm27_intr`` - generates the interrupt source used in the Interrupt |
---|
116 | Benchmark Test (``tm27``). |
---|
117 | |
---|
118 | - ``Clear_tm27_intr`` - clears the interrupt source used in the Interrupt |
---|
119 | Benchmark Test (``tm27``). |
---|
120 | |
---|
121 | - ``Lower_tm27_intr`` - lowers the interrupt mask so the interrupt source used |
---|
122 | in the Interrupt Benchmark Test (``tm27``) can generate a nested interrupt. |
---|
123 | |
---|
124 | All members of the Timing Test Suite are designed to run *WITHOUT* the Clock |
---|
125 | Device Driver installed. This increases the predictability of the tests' |
---|
126 | execution as well as avoids occassionally including the overhead of a clock |
---|
127 | tick interrupt in the time reported. Because of this it is sometimes possible |
---|
128 | to use the clock tick interrupt source as the source of this test interrupt. |
---|
129 | On other architectures, it is possible to directly force an interrupt to occur. |
---|
130 | |
---|
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 | |
---|
154 | sbrk() Implementation |
---|
155 | ===================== |
---|
156 | |
---|
157 | Although nearly all BSPs give all possible memory to the C Program Heap at |
---|
158 | initialization, it is possible for a BSP to configure the initial size of the |
---|
159 | heap small and let it grow on demand. If the BSP wants to dynamically extend |
---|
160 | the heap used by the C Library memory allocation routines (i.e. ``malloc`` |
---|
161 | family), then the``sbrk`` routine must be functional. The following is the |
---|
162 | prototype for this routine: |
---|
163 | |
---|
164 | .. code-block:: c |
---|
165 | |
---|
166 | void * sbrk(size_t increment) |
---|
167 | |
---|
168 | The ``increment`` amount is based upon the ``sbrk_amount`` parameter passed to |
---|
169 | the ``bsp_libc_init`` during system initialization. |
---|
170 | |
---|
171 | .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK |
---|
172 | |
---|
173 | If your BSP does not want to support dynamic heap extension, then you do not |
---|
174 | have to do anything special. However, if you want to support ``sbrk``, you |
---|
175 | must provide an implementation of this method and define |
---|
176 | ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` in ``bsp.h``. This informs |
---|
177 | ``rtems/confdefs.h`` to configure the Malloc Family Extensions which support |
---|
178 | ``sbrk``. |
---|
179 | |
---|
180 | bsp_fatal_extension() - Cleanup the Hardware |
---|
181 | ============================================ |
---|
182 | |
---|
183 | The ``bsp_fatal_extension()`` is an optional BSP specific initial extension |
---|
184 | invoked once a fatal system state is reached. Most of the BSPs use the same |
---|
185 | 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 |
---|
191 | |
---|
192 | The ``bsp_fatal_extension()`` routine can be used to return to a ROM monitor, |
---|
193 | insure that interrupt sources are disabled, etc.. This routine is the last |
---|
194 | place to ensure a clean shutdown of the hardware. The fatal source, internal |
---|
195 | error indicator, and the fatal code arguments are available to evaluate the |
---|
196 | fatal condition. All of the non-fatal shutdown sequences ultimately pass their |
---|
197 | exit status to ``rtems_shutdown_executive`` and this is what is passed to this |
---|
198 | routine in case the fatal source is ``RTEMS_FATAL_SOURCE_EXIT``. |
---|
199 | |
---|
200 | On some BSPs, it prints a message indicating that the application completed |
---|
201 | execution and waits for the user to press a key before resetting the board. |
---|
202 | The PowerPC/gen83xx and PowerPC/gen5200 BSPs do this when they are built to |
---|
203 | support the FreeScale evaluation boards. This is convenient when using the |
---|
204 | boards in a development environment and may be disabled for production use. |
---|
205 | |
---|
206 | Configuration Macros |
---|
207 | ==================== |
---|
208 | |
---|
209 | Each BSP can define macros in bsp.h which alter some of the the default |
---|
210 | configuration parameters in ``rtems/confdefs.h``. This section describes those |
---|
211 | macros: |
---|
212 | |
---|
213 | .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK |
---|
214 | |
---|
215 | - ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` must be defined if the BSP has proper |
---|
216 | support for ``sbrk``. This is discussed in more detail in the previous |
---|
217 | section. |
---|
218 | |
---|
219 | .. index:: BSP_IDLE_TASK_BODY |
---|
220 | |
---|
221 | - ``BSP_IDLE_TASK_BODY`` may be defined to the entry point of a BSP specific |
---|
222 | IDLE thread implementation. This may be overridden if the application |
---|
223 | provides its own IDLE task implementation. |
---|
224 | |
---|
225 | .. index:: BSP_IDLE_TASK_STACK_SIZE |
---|
226 | |
---|
227 | - ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired default stack size |
---|
228 | for the IDLE task as recommended when using this BSP. |
---|
229 | |
---|
230 | .. index:: BSP_INTERRUPT_STACK_SIZE |
---|
231 | |
---|
232 | - ``BSP_INTERRUPT_STACK_SIZE`` may be defined to the desired default interrupt |
---|
233 | stack size as recommended when using this BSP. This is sometimes required |
---|
234 | when the BSP developer has knowledge of stack intensive interrupt handlers. |
---|
235 | |
---|
236 | .. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY |
---|
237 | |
---|
238 | - ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined when the BSP requires that |
---|
239 | RTEMS zero out the RTEMS C Program Heap at initialization. If the memory is |
---|
240 | already zeroed out by a test sequence or boot ROM, then the boot time can be |
---|
241 | reduced by not zeroing memory twice. |
---|
242 | |
---|
243 | .. index:: BSP_DEFAULT_UNIFIED_WORK_AREAS |
---|
244 | |
---|
245 | - ``BSP_DEFAULT_UNIFIED_WORK_AREAS`` is defined when the BSP recommends that |
---|
246 | the unified work areas configuration should always be used. This is |
---|
247 | desirable when the BSP is known to always have very little RAM and thus |
---|
248 | saving memory by any means is desirable. |
---|
249 | |
---|
250 | set_vector() - Install an Interrupt Vector |
---|
251 | ========================================== |
---|
252 | |
---|
253 | On targets with Simple Vectored Interrupts, the BSP must provide an |
---|
254 | implementation of the ``set_vector`` routine. This routine is responsible for |
---|
255 | installing an interrupt vector. It invokes the support routines necessary to |
---|
256 | install an interrupt handler as either a "raw" or an RTEMS interrupt handler. |
---|
257 | Raw handlers bypass the RTEMS interrupt structure and are responsible for |
---|
258 | saving and restoring all their own registers. Raw handlers are useful for |
---|
259 | handling traps, debug vectors, etc. |
---|
260 | |
---|
261 | The ``set_vector`` routine is a central place to perform interrupt controller |
---|
262 | manipulation and encapsulate that information. It is usually implemented as |
---|
263 | follows: |
---|
264 | |
---|
265 | .. code-block:: c |
---|
266 | |
---|
267 | rtems_isr_entry set_vector( /* returns old vector */ |
---|
268 | rtems_isr_entry handler, /* isr routine */ |
---|
269 | rtems_vector_number vector, /* vector number */ |
---|
270 | int type /* RTEMS or RAW intr */ |
---|
271 | ) |
---|
272 | { |
---|
273 | if the type is RAW |
---|
274 | install the raw vector |
---|
275 | else |
---|
276 | use rtems_interrupt_catch to install the vector |
---|
277 | perform any interrupt controller necessary to unmask the interrupt source |
---|
278 | return the previous handler |
---|
279 | } |
---|
280 | |
---|
281 | .. note:: |
---|
282 | |
---|
283 | The i386, PowerPC and ARM ports use a Programmable Interrupt Controller |
---|
284 | model which does not require the BSP to implement ``set_vector``. BSPs for |
---|
285 | these architectures must provide a different set of support routines. |
---|
286 | |
---|
287 | Interrupt Delay Profiling |
---|
288 | ========================= |
---|
289 | |
---|
290 | The RTEMS profiling needs support by the BSP for the interrupt delay times. In |
---|
291 | case profiling is enabled via the RTEMS build configuration option |
---|
292 | ``--enable-profiling`` (in this case the pre-processor symbol |
---|
293 | ``RTEMS_PROFILING`` is defined) a BSP may provide data for the interrupt delay |
---|
294 | times. The BSP can feed interrupt delay times with the |
---|
295 | ``_Profiling_Update_max_interrupt_delay()`` function (``#include |
---|
296 | <rtems/score/profiling.h>``). For an example please have a look at |
---|
297 | ``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``. |
---|
298 | |
---|
299 | Programmable Interrupt Controller API |
---|
300 | ===================================== |
---|
301 | |
---|
302 | A BSP can use the PIC API to install Interrupt Service Routines through a set |
---|
303 | 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`` |
---|
305 | must be included by the bsp specific irq.h file present in the include/ |
---|
306 | directory. The irq.h acts as a BSP interrupt support configuration file which |
---|
307 | is used to define some important MACROS. It contains the declarations for any |
---|
308 | required global functions like bsp_interrupt_dispatch(). Thus later on, every |
---|
309 | call to the PIC interface requires including ``<bsp/irq.h>`` |
---|
310 | |
---|
311 | The generic interrupt handler table is intitalized by invoking the |
---|
312 | ``bsp_interrupt_initialize()`` method from bsp_start() in the bspstart.c file |
---|
313 | which sets up this table to store the ISR addresses, whose size is based on the |
---|
314 | definition of macros, ``BSP_INTERRUPT_VECTOR_MIN`` and |
---|
315 | ``BSP_INTERRUPT_VECTOR_MAX`` in include/bsp.h |
---|
316 | |
---|
317 | For the generic handler table to properly function, some bsp specific code is |
---|
318 | required, that should be present in ``irq/irq.c``. The bsp-specific functions |
---|
319 | required to be writen by the BSP developer are : |
---|
320 | |
---|
321 | .. index:: bsp_interrupt_facility_initialize() |
---|
322 | |
---|
323 | - ``bsp_interrupt_facility_initialize()`` contains bsp specific interrupt |
---|
324 | initialization code(Clear Pending interrupts by modifying registers, etc.). |
---|
325 | This method is called from ``bsp_interrupt_initialize()`` internally while |
---|
326 | setting up the table. |
---|
327 | |
---|
328 | .. index:: bsp_interrupt_handler_default() |
---|
329 | |
---|
330 | - ``bsp_interrupt_handler_default()`` acts as a fallback handler when no ISR |
---|
331 | address has been provided corresponding to a vector in the table. |
---|
332 | |
---|
333 | .. index:: bsp_interrupt_dispatch() |
---|
334 | |
---|
335 | - ``bsp_interrupt_dispatch()`` service the ISR by handling any bsp specific |
---|
336 | code & calling the generic method ``bsp_interrupt_handler_dispatch()`` which |
---|
337 | in turn services the interrupt by running the ISR after looking it up in the |
---|
338 | table. It acts as an entry to the interrupt switchboard, since the bsp |
---|
339 | branches to this function at the time of occurrence of an interrupt. |
---|
340 | |
---|
341 | .. index:: bsp_interrupt_vector_enable() |
---|
342 | |
---|
343 | - ``bsp_interrupt_vector_enable()`` enables interrupts and is called in |
---|
344 | irq-generic.c while setting up the table. |
---|
345 | |
---|
346 | .. index:: bsp_interrupt_vector_disable() |
---|
347 | |
---|
348 | - ``bsp_interrupt_vector_disable()`` disables interrupts and is called in |
---|
349 | irq-generic.c while setting up the table & during other important parts. |
---|
350 | |
---|
351 | An interrupt handler is installed or removed with the help of the following functions : |
---|
352 | |
---|
353 | .. code-block:: c |
---|
354 | |
---|
355 | rtems_status_code rtems_interrupt_handler_install( /* returns status code */ |
---|
356 | rtems_vector_number vector, /* interrupt vector */ |
---|
357 | const char *info, /* custom identification text */ |
---|
358 | rtems_option options, /* Type of Interrupt */ |
---|
359 | rtems_interrupt_handler handler, /* interrupt handler */ |
---|
360 | void *arg /* parameter to be passed |
---|
361 | to handler at the time of |
---|
362 | invocation */ |
---|
363 | ) |
---|
364 | rtems_status_code rtems_interrupt_handler_remove( /* returns status code */ |
---|
365 | rtems_vector_number vector, /* interrupt vector */ |
---|
366 | rtems_interrupt_handler handler, /* interrupt handler */ |
---|
367 | void *arg /* parameter to be passed to handler */ |
---|
368 | ) |
---|