source: rtems-docs/c-user/config/device-driver.rst @ 88dd013

5
Last change on this file since 88dd013 was 41ac3da, checked in by Sebastian Huber <sebastian.huber@…>, on 03/09/20 at 07:56:19

c-user: Move "Device Driver Configuration"

Update #3836.
  • Property mode set to 100644
File size: 13.9 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
4
5Device Driver Configuration
6===========================
7
8This section defines the configuration parameters related to the automatic
9generation of a Device Driver Table.  As ``<rtems/confdefs.h>`` only is aware
10of a small set of standard device drivers, the generated Device Driver Table is
11suitable for simple applications with no custom device drivers.
12
13Note that network device drivers are not configured in the Device Driver Table.
14
15.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
16
17.. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER:
18
19CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
20------------------------------------------------
21
22CONSTANT:
23    ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``
24
25DATA TYPE:
26    Boolean feature macro.
27
28RANGE:
29    Defined or undefined.
30
31DEFAULT VALUE:
32    This is not defined by default.
33
34DESCRIPTION:
35    ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the
36    application does *NOT* want the Clock Device Driver and is *NOT* using the
37    Timer Driver.  The inclusion or exclusion of the Clock Driver must be
38    explicit in user applications.
39
40NOTES:
41    This configuration parameter is intended to prevent the common user error
42    of using the Hello World example as the baseline for an application and
43    leaving out a clock tick source.
44
45.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS
46
47.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS:
48
49CONFIGURE_APPLICATION_EXTRA_DRIVERS
50-----------------------------------
51
52CONSTANT:
53    ``CONFIGURE_APPLICATION_EXTRA_DRIVERS``
54
55DATA TYPE:
56    device driver entry structures
57
58RANGE:
59    Undefined or set of device driver entry structures
60
61DEFAULT VALUE:
62    This is not defined by default.
63
64DESCRIPTION:
65    ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has
66    device drivers it needs to include in the Device Driver Table.  This should
67    be defined to the set of device driver entries that will be placed in the
68    table at the *END* of the Device Driver Table.
69
70NOTES:
71    None.
72
73.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
74
75.. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER:
76
77CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
78----------------------------------------
79
80CONSTANT:
81    ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``
82
83DATA TYPE:
84    Boolean feature macro.
85
86RANGE:
87    Defined or undefined.
88
89DEFAULT VALUE:
90    This is not defined by default.
91
92DESCRIPTION:
93    ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application
94    wishes to include the Clock Device Driver.
95
96NOTES:
97    This device driver is responsible for providing a regular interrupt which
98    invokes a clock tick directive.
99
100    If neither the Clock Driver not Benchmark Timer is enabled and the
101    configuration parameter
102    ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a
103    compile time error will occur.
104
105.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
106
107.. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER:
108
109CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
110------------------------------------------
111
112CONSTANT:
113    ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
114
115DATA TYPE:
116    Boolean feature macro.
117
118RANGE:
119    Defined or undefined.
120
121DEFAULT VALUE:
122    This is not defined by default.
123
124DESCRIPTION:
125    ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the
126    application wishes to include the Console Device Driver.
127
128NOTES:
129    This device driver is responsible for providing the :file:`/dev/console`
130    device file.  This device is used to initialize the standard input, output,
131    and error file descriptors.
132
133    BSPs should be constructed in a manner that allows ``printk()`` to work
134    properly without the need for the console driver to be configured.
135
136    The
137
138    * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
139
140    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
141
142    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
143
144    configuration options are mutually exclusive.
145
146.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
147
148.. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER:
149
150CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
151-----------------------------------------------
152
153CONSTANT:
154    ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER``
155
156DATA TYPE:
157    Boolean feature macro.
158
159RANGE:
160    Defined or undefined.
161
162DEFAULT VALUE:
163    This is not defined by default.
164
165DESCRIPTION:
166    ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the
167    application wishes to include the BSP's Frame Buffer Device Driver.
168
169NOTES:
170    Most BSPs do not include support for a Frame Buffer Device Driver. This is
171    because many boards do not include the required hardware.
172
173    If this is defined and the BSP does not have this device driver, then the
174    user will get a link time error for an undefined symbol.
175
176.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
177.. index:: /dev/null
178
179.. _CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER:
180
181CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
182---------------------------------------
183
184CONSTANT:
185    ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER``
186
187DATA TYPE:
188    Boolean feature macro.
189
190RANGE:
191    Defined or undefined.
192
193DEFAULT VALUE:
194    This is not defined by default.
195
196DESCRIPTION:
197    This configuration variable is specified to enable ``/dev/null`` device driver.
198
199NOTES:
200    This device driver is supported by all BSPs.
201
202.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
203
204.. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER:
205
206CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
207--------------------------------------
208
209CONSTANT:
210    ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER``
211
212DATA TYPE:
213    Boolean feature macro.
214
215RANGE:
216    Defined or undefined.
217
218DEFAULT VALUE:
219    This is not defined by default.
220
221DESCRIPTION:
222    ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application
223    wishes to include the Real-Time Clock Driver.
224
225NOTES:
226    Most BSPs do not include support for a real-time clock. This is because
227    many boards do not include the required hardware.
228
229    If this is defined and the BSP does not have this device driver, then the
230    user will get a link time error for an undefined symbol.
231
232.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
233
234.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER:
235
236CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
237-------------------------------------------------
238
239CONSTANT:
240    ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``
241
242DATA TYPE:
243    Boolean feature macro.
244
245RANGE:
246    Defined or undefined.
247
248DEFAULT VALUE:
249    This is not defined by default.
250
251DESCRIPTION:
252    ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` is defined if the
253    application wishes to include the Simple Console Device Driver.
254
255NOTES:
256    This device driver is responsible for providing the :file:`/dev/console`
257    device file.  This device is used to initialize the standard input, output,
258    and error file descriptors.
259
260    This device driver reads via ``getchark()``.
261
262    This device driver writes via ``rtems_putc()``.
263
264    The Termios framework is not used.  There is no support to change device
265    settings, e.g. baud, stop bits, parity, etc.
266
267    The
268
269    * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
270
271    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
272
273    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
274
275    configuration options are mutually exclusive.
276
277.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER
278
279.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER:
280
281CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER
282------------------------------------------------------
283
284CONSTANT:
285    ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
286
287DATA TYPE:
288    Boolean feature macro.
289
290RANGE:
291    Defined or undefined.
292
293DEFAULT VALUE:
294    This is not defined by default.
295
296DESCRIPTION:
297    ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` is defined if
298    the application wishes to include the Simple Task Console Device Driver.
299
300NOTES:
301    This device driver is responsible for providing the :file:`/dev/console`
302    device file.  This device is used to initialize the standard input, output,
303    and error file descriptors.
304
305    This device driver reads via ``getchark()``.
306
307    This device driver writes into a write buffer.  The count of characters
308    written into the write buffer is returned.  It might be less than the
309    requested count, in case the write buffer is full.  The write is
310    non-blocking and may be called from interrupt context.  A dedicated task
311    reads from the write buffer and outputs the characters via
312    ``rtems_putc()``.  This task runs with the least important priority.  The
313    write buffer size is 2047 characters and it is not configurable.
314
315    Use ``fsync(STDOUT_FILENO)`` or ``fdatasync(STDOUT_FILENO)`` to drain the
316    write buffer.
317
318    The Termios framework is not used.  There is no support to change device
319    settings, e.g.  baud, stop bits, parity, etc.
320
321    The
322
323    * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
324
325    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
326
327    * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
328
329    configuration options are mutually exclusive.
330
331.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
332
333.. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER:
334
335CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
336---------------------------------------
337
338CONSTANT:
339    ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER``
340
341DATA TYPE:
342    Boolean feature macro.
343
344RANGE:
345    Defined or undefined.
346
347DEFAULT VALUE:
348    This is not defined by default.
349
350DESCRIPTION:
351    ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application
352    wishes to include the Stub Device Driver.
353
354NOTES:
355    This device driver simply provides entry points that return successful and
356    is primarily a test fixture. It is supported by all BSPs.
357
358.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
359
360.. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER:
361
362CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
363----------------------------------------
364
365CONSTANT:
366    ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``
367
368DATA TYPE:
369    Boolean feature macro.
370
371RANGE:
372    Defined or undefined.
373
374DEFAULT VALUE:
375    This is not defined by default.
376
377DESCRIPTION:
378    ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the application
379    wishes to include the Timer Driver.  This device driver is used to
380    benchmark execution times by the RTEMS Timing Test Suites.
381
382NOTES:
383    If neither the Clock Driver not Benchmark Timer is enabled and the
384    configuration parameter
385    ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a
386    compile time error will occur.
387
388.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
389
390.. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER:
391
392CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
393-------------------------------------------
394
395CONSTANT:
396    ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
397
398DATA TYPE:
399    Boolean feature macro.
400
401RANGE:
402    Defined or undefined.
403
404DEFAULT VALUE:
405    This is not defined by default.
406
407DESCRIPTION:
408    ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the
409    application wishes to include the Watchdog Driver.
410
411NOTES:
412    Most BSPs do not include support for a watchdog device driver. This is
413    because many boards do not include the required hardware.
414
415    If this is defined and the BSP does not have this device driver, then the
416    user will get a link time error for an undefined symbol.
417
418.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
419.. index:: /dev/zero
420
421.. _CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER:
422
423CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
424---------------------------------------
425
426CONSTANT:
427    ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER``
428
429DATA TYPE:
430    Boolean feature macro.
431
432RANGE:
433    Defined or undefined.
434
435DEFAULT VALUE:
436    This is not defined by default.
437
438DESCRIPTION:
439    This configuration variable is specified to enable ``/dev/zero`` device driver.
440
441NOTES:
442    This device driver is supported by all BSPs.
443
444.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
445
446.. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS:
447
448CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
449------------------------------------------
450
451CONSTANT:
452    ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS``
453
454DATA TYPE:
455    device driver entry structures
456
457RANGE:
458    Undefined or set of device driver entry structures
459
460DEFAULT VALUE:
461    This is not defined by default.
462
463DESCRIPTION:
464    ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the
465    application has device drivers it needs to include in the Device Driver
466    Table.  This should be defined to the set of device driver entries that
467    will be placed in the table at the *FRONT* of the Device Driver Table and
468    initialized before any other drivers *EXCEPT* any BSP prerequisite drivers.
469
470NOTES:
471    In some cases, it is used by System On Chip BSPs to support peripheral
472    buses beyond those normally found on the System On Chip. For example, this
473    is used by one RTEMS system which has implemented a SPARC/ERC32 based board
474    with VMEBus. The VMEBus Controller initialization is performed by a device
475    driver configured via this configuration parameter.
476
477.. index:: CONFIGURE_MAXIMUM_DRIVERS
478
479.. _CONFIGURE_MAXIMUM_DRIVERS:
480
481CONFIGURE_MAXIMUM_DRIVERS
482-------------------------
483
484CONSTANT:
485    ``CONFIGURE_MAXIMUM_DRIVERS``
486
487DATA TYPE:
488    Unsigned integer (``uint32_t``).
489
490RANGE:
491    Zero or positive.
492
493DEFAULT VALUE:
494    This is computed by default, and is set to the number of device drivers
495    configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER``
496    configuration parameters.
497
498DESCRIPTION:
499    ``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers
500    per node.
501
502NOTES:
503    If the application will dynamically install device drivers, then this
504    configuration parameter must be larger than the number of statically
505    configured device drivers. Drivers configured using the
506    ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are
507    statically installed.
Note: See TracBrowser for help on using the repository browser.