mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-02 10:03:09 +08:00
595 lines
18 KiB
ReStructuredText
595 lines
18 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
|
|
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
|
|
|
|
Device Driver Configuration
|
|
===========================
|
|
|
|
This section describes configuration options related to the device drivers.
|
|
Note that network device drivers are not covered by the following options.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
|
|
------------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then a Clock Driver may be
|
|
initialized during system initialization.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then **no** Clock Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
This configuration parameter is intended to prevent the common user error
|
|
of using the Hello World example as the baseline for an application and
|
|
leaving out a clock tick source.
|
|
|
|
The application shall define exactly one of the following configuration options
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`,
|
|
|
|
* `CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`,
|
|
|
|
otherwise a compile time error in the configuration file will occur.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS
|
|
|
|
.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS:
|
|
|
|
CONFIGURE_APPLICATION_EXTRA_DRIVERS
|
|
-----------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_EXTRA_DRIVERS``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is an initializer define.
|
|
|
|
DEFAULT VALUE:
|
|
The default value is the empty list.
|
|
|
|
VALUE CONSTRAINTS:
|
|
The value of this configuration option shall be a list of initializers for
|
|
structures of type :c:type:`rtems_driver_address_table`.
|
|
|
|
DESCRIPTION:
|
|
The value of this configuration option is used to initialize the Device
|
|
Driver Table.
|
|
|
|
NOTES:
|
|
The value of this configuration option is placed after the entries of other
|
|
device driver configuration options.
|
|
|
|
See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative
|
|
placement of application device driver initializers.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER
|
|
--------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the ATA Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
Most BSPs do not include support for an ATA Driver.
|
|
|
|
If this option is defined and the BSP does not have this device driver, then
|
|
the user will get a link time error for an undefined symbol.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
----------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Clock Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
The Clock Driver is responsible for providing a regular interrupt
|
|
which invokes a clock tick directive.
|
|
|
|
The application shall define exactly one of the following configuration options
|
|
|
|
* `CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`,
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`,
|
|
|
|
otherwise a compile time error in the configuration file will occur.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Console Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
The Console Driver is responsible for providing the :file:`/dev/console`
|
|
device file. This device is used to initialize the standard input, output,
|
|
and error file descriptors.
|
|
|
|
BSPs should be constructed in a manner that allows :c:func:`printk` to work
|
|
properly without the need for the Console Driver to be configured.
|
|
|
|
The
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
|
|
|
|
configuration options are mutually exclusive.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
|
|
-----------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Frame Buffer Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
Most BSPs do not include support for a Frame Buffer Driver. This is
|
|
because many boards do not include the required hardware.
|
|
|
|
If this option is defined and the BSP does not have this device driver, then
|
|
the user will get a link time error for an undefined symbol.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER
|
|
--------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the IDE Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
Most BSPs do not include support for an IDE Driver.
|
|
|
|
If this option is defined and the BSP does not have this device driver, then
|
|
the user will get a link time error for an undefined symbol.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
|
|
.. index:: /dev/null
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
|
|
---------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the :file:`/dev/null`
|
|
Driver is initialized during system initialization.
|
|
|
|
NOTES:
|
|
This device driver is supported by all BSPs.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
|
|
--------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Real-Time Clock Driver
|
|
is initialized during system initialization.
|
|
|
|
NOTES:
|
|
Most BSPs do not include support for a real-time clock (RTC). This is because
|
|
many boards do not include the required hardware.
|
|
|
|
If this is defined and the BSP does not have this device driver, then the
|
|
user will get a link time error for an undefined symbol.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
|
|
-------------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Simple Console Driver
|
|
is initialized during system initialization.
|
|
|
|
NOTES:
|
|
This device driver is responsible for providing the :file:`/dev/console`
|
|
device file. This device is used to initialize the standard input, output,
|
|
and error file descriptors.
|
|
|
|
This device driver reads via :c:func:`getchark`.
|
|
|
|
This device driver writes via :c:func:`rtems_putc`.
|
|
|
|
The Termios framework is not used. There is no support to change device
|
|
settings, e.g. baud, stop bits, parity, etc.
|
|
|
|
The
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
|
|
|
|
configuration options are mutually exclusive.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER
|
|
------------------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Simple Task Console
|
|
Driver is initialized during system initialization.
|
|
|
|
NOTES:
|
|
This device driver is responsible for providing the :file:`/dev/console`
|
|
device file. This device is used to initialize the standard input, output,
|
|
and error file descriptors.
|
|
|
|
This device driver reads via :c:func:`getchark`.
|
|
|
|
This device driver writes into a write buffer. The count of characters
|
|
written into the write buffer is returned. It might be less than the
|
|
requested count, in case the write buffer is full. The write is
|
|
non-blocking and may be called from interrupt context. A dedicated task
|
|
reads from the write buffer and outputs the characters via
|
|
:c:func:`rtems_putc`. This task runs with the least important priority.
|
|
The write buffer size is 2047 characters and it is not configurable.
|
|
|
|
Use ``fsync(STDOUT_FILENO)`` or ``fdatasync(STDOUT_FILENO)`` to drain the
|
|
write buffer.
|
|
|
|
The Termios framework is not used. There is no support to change device
|
|
settings, e.g. baud, stop bits, parity, etc.
|
|
|
|
The
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
|
|
|
|
configuration options are mutually exclusive.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
|
|
---------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Stub Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
This device driver simply provides entry points that return successful and
|
|
is primarily a test fixture. It is supported by all BSPs.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
|
|
----------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Benchmark Timer Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS
|
|
Testsuite. Applications should not use this driver.
|
|
|
|
The application shall define exactly one of the following configuration options
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`,
|
|
|
|
* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or
|
|
|
|
* `CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`,
|
|
|
|
otherwise a compile time error will occur.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
|
|
-------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the Watchdog Driver is
|
|
initialized during system initialization.
|
|
|
|
NOTES:
|
|
Most BSPs do not include support for a watchdog device driver. This is
|
|
because many boards do not include the required hardware.
|
|
|
|
If this is defined and the BSP does not have this device driver, then the
|
|
user will get a link time error for an undefined symbol.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
|
|
.. index:: /dev/zero
|
|
|
|
.. _CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER:
|
|
|
|
CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
|
|
---------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is a boolean feature define.
|
|
|
|
DEFAULT CONFIGURATION:
|
|
If this configuration option is undefined, then the described feature is not
|
|
enabled.
|
|
|
|
DESCRIPTION:
|
|
In case this configuration option is defined, then the :file:`/dev/zero`
|
|
Driver is initialized during system initialization.
|
|
|
|
NOTES:
|
|
This device driver is supported by all BSPs.
|
|
|
|
.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
|
|
|
|
.. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS:
|
|
|
|
CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
|
|
------------------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is an initializer define.
|
|
|
|
DEFAULT VALUE:
|
|
The default value is the empty list.
|
|
|
|
VALUE CONSTRAINTS:
|
|
The value of this configuration option shall be a list of initializers for
|
|
structures of type :c:type:`rtems_driver_address_table`.
|
|
|
|
DESCRIPTION:
|
|
The value of this configuration option is used to initialize the Device
|
|
Driver Table.
|
|
|
|
NOTES:
|
|
The value of this configuration option is placed after the entries defined by
|
|
:ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver
|
|
configuration options.
|
|
|
|
See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement
|
|
of application device driver initializers.
|
|
|
|
.. index:: CONFIGURE_ATA_DRIVER_TASK_PRIORITY
|
|
|
|
.. _CONFIGURE_ATA_DRIVER_TASK_PRIORITY:
|
|
|
|
CONFIGURE_ATA_DRIVER_TASK_PRIORITY
|
|
----------------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_ATA_DRIVER_TASK_PRIORITY``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is an integer define.
|
|
|
|
DEFAULT VALUE:
|
|
The default value is 140.
|
|
|
|
VALUE CONSTRAINTS:
|
|
The value of this configuration option shall be a valid Classic API task
|
|
priority. The set of valid task priorities is scheduler-specific.
|
|
|
|
DESCRIPTION:
|
|
The value of this configuration option defines the ATA task priority.
|
|
|
|
NOTES:
|
|
This configuration option is only evaluated if the configuration option
|
|
:ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined.
|
|
|
|
.. index:: CONFIGURE_MAXIMUM_DRIVERS
|
|
|
|
.. _CONFIGURE_MAXIMUM_DRIVERS:
|
|
|
|
CONFIGURE_MAXIMUM_DRIVERS
|
|
-------------------------
|
|
|
|
CONSTANT:
|
|
``CONFIGURE_MAXIMUM_DRIVERS``
|
|
|
|
OPTION TYPE:
|
|
This configuration option is an integer define.
|
|
|
|
DEFAULT VALUE:
|
|
This is computed by default, and is set to the number of device drivers
|
|
configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER``
|
|
configuration options.
|
|
|
|
VALUE CONSTRAINTS:
|
|
The value of this configuration option shall satisfy all of the following
|
|
constraints:
|
|
|
|
* It shall be less than or equal to ``SIZE_MAX``.
|
|
|
|
* It shall be greater than or equal than the number of statically configured
|
|
device drivers.
|
|
|
|
* It shall be less than or equal to a
|
|
BSP-specific and application-specific value which depends on the size of the
|
|
memory available to the application.
|
|
|
|
DESCRIPTION:
|
|
The value of this configuration option defines the number of device drivers.
|
|
|
|
NOTES:
|
|
If the application will dynamically install device drivers, then this
|
|
configuration parameter shall be larger than the number of statically
|
|
configured device drivers. Drivers configured using the
|
|
``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration options are
|
|
statically installed.
|