[PATCH] c-user: Use new template for feature config opts
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Mar 18 15:52:18 UTC 2020
Try to bring all descriptions up to date. Add cross-references to
several options.
Update #3900.
---
c-user/config/bdbuf.rst | 21 ++-
c-user/config/classic-init-task.rst | 35 ++--
c-user/config/device-driver.rst | 278 +++++++++++++++--------------
c-user/config/event-record.rst | 22 ++-
c-user/config/filesystem.rst | 336 ++++++++++++++++++------------------
c-user/config/general.rst | 141 +++++++--------
c-user/config/idle-task.rst | 43 +++--
c-user/config/mpci.rst | 19 +-
c-user/config/posix-init-thread.rst | 36 ++--
c-user/config/scheduler-general.rst | 173 +++++++++----------
10 files changed, 539 insertions(+), 565 deletions(-)
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst
index 2aaa310..24261b9 100644
--- a/c-user/config/bdbuf.rst
+++ b/c-user/config/bdbuf.rst
@@ -18,22 +18,21 @@ CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the Block Device Cache is not
+ initialized during system initialization.
DESCRIPTION:
- Provides a Block Device Cache configuration.
+ In case this configuration option is defined, then the Block Device Cache is
+ initialized during system initialization.
NOTES:
- Each option of the Block Device Cache configuration can be explicitly set
- by the user with the configuration options below. The Block Device Cache
- is used for example by the RFS and DOSFS file systems.
+ Each option of the Block Device Cache (bdbuf) configuration can be explicitly
+ set by the user with the configuration options below. The Block Device Cache
+ is used for example by the RFS and DOSFS filesystems.
.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE
diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst
index 8eaafca..f56fd6e 100644
--- a/c-user/config/classic-init-task.rst
+++ b/c-user/config/classic-init-task.rst
@@ -206,28 +206,25 @@ CONFIGURE_RTEMS_INIT_TASKS_TABLE
CONSTANT:
``CONFIGURE_RTEMS_INIT_TASKS_TABLE``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Classic API initialization
+ task is configured.
DESCRIPTION:
- ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes to use a
- Classic RTEMS API Initialization Task Table. The table built by
- ``<rtems/confdefs.h>`` specifies the parameters for a single task. This is
- sufficient for applications which initialization the system from a single
- task.
-
- By default, this field is not defined as the user MUST select their own API
- for initialization tasks.
+ In case this configuration option is defined, then a Classic API
+ initialization task is configured.
NOTES:
- The application may choose to use the initialization tasks or threads table
- from another API.
+ The application must define exactly one of the following configuration
+ options
+
+ * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
+
+ * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or
+
+ * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`
- A compile time error will be generated if the user does not configure any
- initialization tasks or threads.
+ otherwise a compile time error will occur.
diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst
index 7a1196d..9710dba 100644
--- a/c-user/config/device-driver.rst
+++ b/c-user/config/device-driver.rst
@@ -18,26 +18,32 @@ CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then a clock driver may be
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the
- application does *NOT* want the Clock Device Driver and is *NOT* using the
- Timer Driver. The inclusion or exclusion of the Clock Driver must be
- explicit in user applications.
+ 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 must define exactly one of the following configuration options
+
+ * :ref:`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 will occur.
+
.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS
.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS:
@@ -76,27 +82,30 @@ CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Clock Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application
- wishes to include the Clock Device Driver.
+ In case this configuration option is defined, then the Clock Driver is
+ initialized during system initialization.
NOTES:
- This device driver is responsible for providing a regular interrupt which
- invokes a clock tick directive.
+ The Clock Driver is responsible for providing a regular interrupt
+ which invokes a clock tick directive.
- If neither the Clock Driver not Benchmark Timer is enabled and the
- configuration parameter
- ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a
- compile time error will occur.
+ The application must define exactly one of the following configuration options
+
+ * :ref:`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 will occur.
.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
@@ -108,34 +117,32 @@ CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Console Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the
- application wishes to include the Console Device Driver.
+ In case this configuration option is defined, then the Console Driver is
+ initialized during system initialization.
NOTES:
- This device driver is responsible for providing the :file:`/dev/console`
+ 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 ``printk()`` to work
- properly without the need for the console driver to be configured.
+ 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
- * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
configuration options are mutually exclusive.
@@ -149,25 +156,23 @@ CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Frame Buffer Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the
- application wishes to include the BSP's Frame Buffer Device Driver.
+ 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 Device Driver. This is
+ Most BSPs do not include support for a Frame Buffer 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.
+ 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
@@ -180,17 +185,16 @@ CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no :file:`/dev/null` Driver
+ is initialized during system initialization.
DESCRIPTION:
- This configuration variable is specified to enable ``/dev/null`` device driver.
+ 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.
@@ -205,21 +209,19 @@ CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Real-Time Clock Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application
- wishes to include the Real-Time Clock Driver.
+ 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. This is because
+ 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
@@ -235,38 +237,36 @@ CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Simple Console Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` is defined if the
- application wishes to include the Simple Console Device Driver.
+ 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 ``getchark()``.
+ This device driver reads via :c:func:`getchark`.
- This device driver writes via ``rtems_putc()``.
+ 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
- * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
configuration options are mutually exclusive.
@@ -280,33 +280,31 @@ CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Simple Task Console Driver
+ is initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` is defined if
- the application wishes to include the Simple Task Console Device Driver.
+ 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 ``getchark()``.
+ 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
- ``rtems_putc()``. This task runs with the least important priority. The
- write buffer size is 2047 characters and it is not configurable.
+ :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.
@@ -316,11 +314,11 @@ NOTES:
The
- * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``,
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`,
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and
- * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER``
+ * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`
configuration options are mutually exclusive.
@@ -334,18 +332,16 @@ CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Stub Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application
- wishes to include the Stub Device Driver.
+ 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
@@ -361,25 +357,30 @@ CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Benchmark Timer Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the application
- wishes to include the Timer Driver. This device driver is used to
- benchmark execution times by the RTEMS Timing Test Suites.
+ In case this configuration option is defined, then the Benchmark Timer Driver is
+ initialized during system initialization.
NOTES:
- If neither the Clock Driver not Benchmark Timer is enabled and the
- configuration parameter
- ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is not defined, then a
- compile time error will occur.
+ The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS
+ Testsuite. Applications should not use this driver.
+
+ The application must define exactly one of the following configuration options
+
+ * :ref:`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 will occur.
.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
@@ -391,18 +392,16 @@ CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no Watchdog Driver is
+ initialized during system initialization.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the
- application wishes to include the Watchdog Driver.
+ 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
@@ -422,17 +421,16 @@ CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
CONSTANT:
``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no :file:`/dev/zero` Driver
+ is initialized during system initialization.
DESCRIPTION:
- This configuration variable is specified to enable ``/dev/zero`` device driver.
+ 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.
diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst
index 01e9af2..7071c77 100644
--- a/c-user/config/event-record.rst
+++ b/c-user/config/event-record.rst
@@ -17,23 +17,21 @@ CONFIGURE_RECORD_EXTENSIONS_ENABLED
CONSTANT:
``CONFIGURE_RECORD_EXTENSIONS_ENABLED``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the event record extensions
+ are not enabled.
DESCRIPTION:
- If defined and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS
- <CONFIGURE_RECORD_PER_PROCESSOR_ITEMS>` is also defined properly, then the
- record extensions are enabled.
+ In case this configuration option is defined and
+ :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is also properly defined, the
+ event record extensions are enabled.
NOTES:
- The record extensions capture thread create, start, restart, delete,
- switch, begin, exitted and terminate events.
+ The record extensions capture thread create, start, restart, delete, switch,
+ begin, exitted and terminate events.
.. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS
diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst
index dee1bd3..4aaccf9 100644
--- a/c-user/config/filesystem.rst
+++ b/c-user/config/filesystem.rst
@@ -57,23 +57,21 @@ CONFIGURE_APPLICATION_DISABLE_FILESYSTEM
CONSTANT:
``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default. If no other root file system configuration
- parameters are specified, the IMFS will be used as the root file system.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the filesystems are
+ initialized during system initialization.
DESCRIPTION:
- This configuration parameter is defined if the application dose not intend
- to use any kind of filesystem support. This include the device
- infrastructure necessary to support ``printf()``.
+ In case this configuration option is defined, then the filesystems are
+ **not** initialized during system initialization.
NOTES:
- None.
+ Filesystems must be initialized to support file descriptor based device
+ drivers and basic input/output functions such as :c:func:`printf`.
+ Filesystems can be disabled to reduce the memory footprint of an application.
.. index:: CONFIGURE_IMFS_DISABLE_CHMOD
@@ -85,18 +83,16 @@ CONFIGURE_IMFS_DISABLE_CHMOD
CONSTANT:
``CONFIGURE_IMFS_DISABLE_CHMOD``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ changing the mode of a file.
DESCRIPTION:
- In case this configuration option is defined, then the support to change
- the mode is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support changing the mode of files (no support for :c:func:`chmod`).
NOTES:
None.
@@ -111,18 +107,16 @@ CONFIGURE_IMFS_DISABLE_CHOWN
CONSTANT:
``CONFIGURE_IMFS_DISABLE_CHOWN``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ changing the ownership of files.
DESCRIPTION:
- In case this configuration option is defined, then the support to change
- the owner is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support changing the ownership of files (no support for :c:func:`chown`).
NOTES:
None.
@@ -137,18 +131,16 @@ CONFIGURE_IMFS_DISABLE_LINK
CONSTANT:
``CONFIGURE_IMFS_DISABLE_LINK``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports hard
+ links.
DESCRIPTION:
- In case this configuration option is defined, then the support to create
- hard links is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support hard links (no support for :c:func:`link`).
NOTES:
None.
@@ -163,18 +155,16 @@ CONFIGURE_IMFS_DISABLE_MKNOD
CONSTANT:
``CONFIGURE_IMFS_DISABLE_MKNOD``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports making
+ files.
DESCRIPTION:
- In case this configuration option is defined, then the support to make
- directories, devices, regular files and FIFOs is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support making files (no support for :c:func:`mknod`).
NOTES:
None.
@@ -189,18 +179,16 @@ CONFIGURE_IMFS_DISABLE_MKNOD_FILE
CONSTANT:
``CONFIGURE_IMFS_DISABLE_MKNOD_FILE``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports making
+ regular files.
DESCRIPTION:
- In case this configuration option is defined, then the support to make
- regular files is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support making regular files.
NOTES:
None.
@@ -215,18 +203,16 @@ CONFIGURE_IMFS_DISABLE_MOUNT
CONSTANT:
``CONFIGURE_IMFS_DISABLE_MOUNT``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ mounting other filesystems.
DESCRIPTION:
- In case this configuration option is defined, then the support to mount
- other file systems is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support mounting other filesystems (no support for :c:func:`mount`).
NOTES:
None.
@@ -241,19 +227,17 @@ CONFIGURE_IMFS_DISABLE_READDIR
CONSTANT:
``CONFIGURE_IMFS_DISABLE_READDIR``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ reading directories.
DESCRIPTION:
- In case this configuration option is defined, then the support to read a
- directory is disabled in the root IMFS. It is still possible to open nodes
- in a directory.
+ In case this configuration option is defined, then the root IMFS does not
+ support reading directories (no support for :c:func:`readdir`). It is still
+ possible to open files in a directory.
NOTES:
None.
@@ -268,18 +252,16 @@ CONFIGURE_IMFS_DISABLE_READLINK
CONSTANT:
``CONFIGURE_IMFS_DISABLE_READLINK``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ reading symbolic links.
DESCRIPTION:
- In case this configuration option is defined, then the support to read
- symbolic links is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support reading symbolic links (no support for :c:func:`readlink`).
NOTES:
None.
@@ -294,18 +276,16 @@ CONFIGURE_IMFS_DISABLE_RENAME
CONSTANT:
``CONFIGURE_IMFS_DISABLE_RENAME``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ renaming files.
DESCRIPTION:
- In case this configuration option is defined, then the support to rename
- nodes is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support renaming files (no support for :c:func:`rename`).
NOTES:
None.
@@ -320,18 +300,16 @@ CONFIGURE_IMFS_DISABLE_RMNOD
CONSTANT:
``CONFIGURE_IMFS_DISABLE_RMNOD``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ removing files.
DESCRIPTION:
- In case this configuration option is defined, then the support to remove
- nodes is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support removing files (no support for :c:func:`rmnod`).
NOTES:
None.
@@ -346,18 +324,16 @@ CONFIGURE_IMFS_DISABLE_SYMLINK
CONSTANT:
``CONFIGURE_IMFS_DISABLE_SYMLINK``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ creating symbolic links.
DESCRIPTION:
- In case this configuration option is defined, then the support to create
- symbolic links is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support creating symbolic links (no support for :c:func:`symlink`).
NOTES:
None.
@@ -372,18 +348,16 @@ CONFIGURE_IMFS_DISABLE_UNMOUNT
CONSTANT:
``CONFIGURE_IMFS_DISABLE_UNMOUNT``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ unmounting other filesystems.
DESCRIPTION:
- In case this configuration option is defined, then the support to unmount
- file systems is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support unmounting other filesystems (no support for :c:func:`unmount`).
NOTES:
None.
@@ -398,18 +372,16 @@ CONFIGURE_IMFS_DISABLE_UTIME
CONSTANT:
``CONFIGURE_IMFS_DISABLE_UTIME``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS supports
+ changing file times.
DESCRIPTION:
- In case this configuration option is defined, then the support to change
- times is disabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS does not
+ support changing file times (no support for :c:func:`utime`).
NOTES:
None.
@@ -424,18 +396,16 @@ CONFIGURE_IMFS_ENABLE_MKFIFO
CONSTANT:
``CONFIGURE_IMFS_ENABLE_MKFIFO``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS does not
+ support making FIFOs (no support for :c:func:`mkfifo`).
DESCRIPTION:
- In case this configuration option is defined, then the support to make FIFOs
- is enabled in the root IMFS.
+ In case this configuration option is defined, then the root IMFS supports
+ making FIFOs.
NOTES:
None.
@@ -502,26 +472,51 @@ CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
CONSTANT:
``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default. If no other root file system configuration
- parameters are specified, the IMFS will be used as the root file system.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS has the full
+ feature set by default.
DESCRIPTION:
- This configuration parameter is defined if the application wishes to use
- the device-only filesytem as the root file system.
+ In case this configuration option is defined, then an IMFS with a reduced
+ feature set will be the base filesystem (also known as root filesystem).
NOTES:
- The device-only filesystem supports only device nodes and is smaller in
- executable code size than the full IMFS and miniIMFS.
+ In case this configuration option is defined, then the following
+ configuration options will be defined as well
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_LINK`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_READDIR`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_READLINK`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_RENAME`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`,
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`,
- The devFS is comparable in functionality to the pseudo-filesystem name
- space provided before RTEMS release 4.5.0.
+ - :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and
+
+ - :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`.
+
+ In addition, a simplified path evaluation is enabled. It allows only a look
+ up of absolute paths.
+
+ This configuration of the IMFS is basically a device-only filesystem. It is
+ comparable in functionality to the pseudo-filesystem name space provided
+ before RTEMS release 4.5.0.
.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM
@@ -533,34 +528,33 @@ CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM
CONSTANT:
``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the root IMFS has the full
+ feature set by default.
DESCRIPTION:
+ In case this configuration option is defined, then an IMFS with a reduced
+ feature set will be the base filesystem (also known as root filesystem).
+
+NOTES:
In case this configuration option is defined, then the following
configuration options will be defined as well
- - ``CONFIGURE_IMFS_DISABLE_CHMOD``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`,
- - ``CONFIGURE_IMFS_DISABLE_CHOWN``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`,
- - ``CONFIGURE_IMFS_DISABLE_UTIME``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_LINK`,
- - ``CONFIGURE_IMFS_DISABLE_LINK``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_READLINK`,
- - ``CONFIGURE_IMFS_DISABLE_SYMLINK``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_RENAME`,
- - ``CONFIGURE_IMFS_DISABLE_READLINK``,
+ - :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`,
- - ``CONFIGURE_IMFS_DISABLE_RENAME``, and
+ - :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and
- - ``CONFIGURE_IMFS_DISABLE_UNMOUNT``.
-
-NOTES:
- None.
+ - :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`.
diff --git a/c-user/config/general.rst b/c-user/config/general.rst
index 1ef1fe9..26755ef 100644
--- a/c-user/config/general.rst
+++ b/c-user/config/general.rst
@@ -17,26 +17,22 @@ CONFIGURE_DIRTY_MEMORY
CONSTANT:
``CONFIGURE_DIRTY_MEMORY``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- By default, the memory used by the RTEMS Workspace and the C Program Heap
- is uninitialized memory.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the memory areas used for the
+ RTEMS Workspace and the C Program Heap are not dirtied.
DESCRIPTION:
- This macro indicates whether RTEMS should dirty the memory used by the
- RTEMS Workspace and the C Program Heap as part of its initialization. If
- defined, the memory areas are dirtied with a ``0xCF`` byte pattern.
- Otherwise, they are not.
+ In case this configuration option is defined, then the memory areas used for
+ the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF` byte
+ pattern during system initialization.
NOTES:
- Dirtying memory can add significantly to system boot time. It may assist in
- finding code that incorrectly assumes the contents of free memory areas is
- cleared to zero during system initialization. In case
+ Dirtying memory can add significantly to system initialization time. It may
+ assist in finding code that incorrectly assumes the contents of free memory
+ areas is cleared to zero during system initialization. In case
:ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the
memory is first dirtied and then zeroed.
@@ -499,24 +495,23 @@ CONFIGURE_STACK_CHECKER_ENABLED
CONSTANT:
``CONFIGURE_STACK_CHECKER_ENABLED``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default, and thus stack checking is disabled.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the stack checker is
+ disabled.
DESCRIPTION:
- This configuration parameter is defined when the application wishes to
- enable run-time stack bounds checking.
+ In case this configuration option is defined, then the stack checker is
+ enabled.
NOTES:
- In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``.
+ The stack checker performs run-time stack bounds checking. This increases
+ the time required to create tasks as well as adding overhead to each context
+ switch.
- This increases the time required to create tasks as well as adding overhead
- to each context switch.
+ In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``.
.. index:: CONFIGURE_TICKS_PER_TIMESLICE
.. index:: ticks per timeslice
@@ -560,22 +555,16 @@ CONFIGURE_UNIFIED_WORK_AREAS
CONSTANT:
``CONFIGURE_UNIFIED_WORK_AREAS``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default, which specifies that the C Program Heap and
- the RTEMS Workspace will be separate.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then there will be separate memory
+ pools for the RTEMS Workspace and C Program Heap.
DESCRIPTION:
- When defined, the C Program Heap and the RTEMS Workspace will be one pool
- of memory.
-
- When not defined, there will be separate memory pools for the RTEMS
- Workspace and C Program Heap.
+ In case this configuration option is defined, then the RTEMS Workspace and
+ the C Program Heap will be one pool of memory.
NOTES:
Having separate pools does have some advantages in the event a task blows a
@@ -584,9 +573,9 @@ NOTES:
pool is very undesirable.
In high memory environments, this is desirable when you want to use the
- RTEMS "unlimited" objects option. You will be able to create objects until
- you run out of all available memory rather then just until you run out of
- RTEMS Workspace.
+ :ref:`ConfigUnlimitedObjects` option. You will be able to create objects
+ until you run out of all available memory rather then just until you run out
+ of RTEMS Workspace.
.. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE
@@ -630,24 +619,26 @@ CONFIGURE_UNLIMITED_OBJECTS
CONSTANT:
``CONFIGURE_UNLIMITED_OBJECTS``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no unlimited objects are used
+ by default.
DESCRIPTION:
- ``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited`` mode
- for Classic API and POSIX API objects that do not already have a specific
- maximum limit defined.
+ In case this configuration option is defined, then unlimited objects are used
+ by default.
NOTES:
When using unlimited objects, it is common practice to also specify
- ``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single pool
- of memory for both RTEMS and application memory allocations.
+ :ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool
+ of memory for both RTEMS Workspace and C Program Heap.
+
+ This option does not override an explicit configuration for a particular
+ object class by the user.
+
+ See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`.
.. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION
@@ -659,23 +650,20 @@ CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION
CONSTANT:
``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default, and thus the system initialization is
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the system initialization is
quiet.
DESCRIPTION:
- This configuration option enables to print some information during system
- initialization.
+ In case this configuration option is defined, then the system initialization
+ is verbose.
NOTES:
You may use this feature to debug system initialization issues. The
- printk() function is used to print the information.
+ :c:func:`printk` function is used to print the information.
.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
.. index:: clear C Program Heap
@@ -691,23 +679,20 @@ CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
CONSTANT:
``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default. The default is *NOT* to zero out the RTEMS
- Workspace or C Program Heap.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the memory areas used for the
+ RTEMS Workspace and the C Program Heap are not zeroed.
DESCRIPTION:
- This macro indicates whether RTEMS should zero the RTEMS Workspace and C
- Program Heap as part of its initialization. If defined, the memory regions
- are zeroed. Otherwise, they are not.
+ In case this configuration option is defined, then the memory areas used for
+ the RTEMS Workspace and the C Program Heap are zeroed with a ``0x0` byte
+ pattern during system initialization.
NOTES:
- Zeroing memory can add significantly to system boot time. It is not
- necessary for RTEMS but is often assumed by support libraries. In case
+ Zeroing memory can add significantly to the system initialization time. It is
+ not necessary for RTEMS but is often assumed by support libraries. In case
:ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first
dirtied and then zeroed.
diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst
index a39aaa1..7d598a8 100644
--- a/c-user/config/idle-task.rst
+++ b/c-user/config/idle-task.rst
@@ -44,29 +44,40 @@ CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
CONSTANT:
``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default, the user is assumed to provide one or more
- initialization tasks.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the user is assumed to
+ provide one or more initialization tasks.
DESCRIPTION:
- ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set to indicate that the
- user has configured *NO* user initialization tasks or threads and that the
- user provided IDLE task will perform application initialization and then
- transform itself into an IDLE task.
+ This configuration option is defined to indicate that the user has configured
+ **no** user initialization tasks or threads and that the user provided idle
+ task will perform application initialization and then transform itself into
+ an idle task.
NOTES:
- If you use this option be careful, the user IDLE task *CANNOT* block at all
+ If you use this option be careful, the user idle task **cannot** block at all
during the initialization sequence. Further, once application
- initialization is complete, it must make itself preemptible and enter an
- IDLE body loop.
+ initialization is complete, it must make itself preemptible and enter an idle
+ body loop.
+
+ The idle task must run at the lowest priority of all tasks in the system.
+
+ Configure a user idle task with the :ref:`CONFIGURE_IDLE_TASK_BODY`
+ configuration option.
+
+ The application must define exactly one of the following configuration
+ options
+
+ * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
+
+ * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or
+
+ * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`
- The IDLE task must run at the lowest priority of all tasks in the system.
+ otherwise a compile time error will occur.
.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE
diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst
index a3d0620..850c731 100644
--- a/c-user/config/mpci.rst
+++ b/c-user/config/mpci.rst
@@ -22,20 +22,17 @@ CONFIGURE_MP_APPLICATION
CONSTANT:
``CONFIGURE_MP_APPLICATION``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the multiprocessing services
+ are not initialized.
DESCRIPTION:
- This configuration parameter must be defined to indicate that the
- application intends to be part of a multiprocessing
- configuration. Additional configuration parameters are assumed to be
- provided.
+ This configuration option is defined to indicate that the application intends
+ to be part of a multiprocessing configuration. Additional configuration
+ parameters are assumed to be provided.
NOTES:
This has no impact unless RTEMS was built with the
diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst
index 50c86ee..10812fd 100644
--- a/c-user/config/posix-init-thread.rst
+++ b/c-user/config/posix-init-thread.rst
@@ -76,29 +76,25 @@ CONFIGURE_POSIX_INIT_THREAD_TABLE
CONSTANT:
``CONFIGURE_POSIX_INIT_THREAD_TABLE``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This field is not defined by default, as the user MUST select their own API
- for initialization tasks.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no POSIX initialization
+ thread is configured.
DESCRIPTION:
- ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes to use
- a POSIX API Initialization Threads Table. The table built by
- ``<rtems/confdefs.h>`` specifies the parameters for a single thread. This
- is sufficient for applications which initialization the system from a
- single task.
-
- By default, this field is not defined as the user MUST select their own API
- for initialization tasks.
+ In case this configuration option is defined, then a POSIX initialization
+ thread is configured.
NOTES:
- The application may choose to use the initialization tasks or threads table
- from another API.
+ The application must define exactly one of the following configuration
+ options
+
+ * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
+
+ * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or
+
+ * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`
- A compile time error will be generated if the user does not configure any
- initialization tasks or threads.
+ otherwise a compile time error will occur.
diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst
index ac0b713..427abb5 100644
--- a/c-user/config/scheduler-general.rst
+++ b/c-user/config/scheduler-general.rst
@@ -38,18 +38,18 @@ CONFIGURE_SCHEDULER_CBS
CONSTANT:
``CONFIGURE_SCHEDULER_CBS``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Constant Bandwidth Server (CBS) Scheduler <SchedulerCBS>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Constant Bandwidth Server (CBS) Scheduler
- <SchedulerCBS>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Constant Bandwidth Server (CBS) Scheduler <SchedulerCBS>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -69,18 +69,18 @@ CONFIGURE_SCHEDULER_EDF
CONSTANT:
``CONFIGURE_SCHEDULER_EDF``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Earliest Deadline First (EDF) Scheduler <SchedulerEDF>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Earliest Deadline First (EDF) Scheduler
- <SchedulerEDF>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Earliest Deadline First (EDF) Scheduler <SchedulerEDF>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -100,18 +100,18 @@ CONFIGURE_SCHEDULER_EDF_SMP
CONSTANT:
``CONFIGURE_SCHEDULER_EDF_SMP``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Earliest Deadline First (EDF) SMP Scheduler <SchedulerSMPEDF>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler
- <SchedulerSMPEDF>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Earliest Deadline First (EDF) SMP Scheduler <SchedulerSMPEDF>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -125,7 +125,7 @@ NOTES:
scheduler for up to 32 processors.
This scheduler algorithm is the default in SMP configurations if
- :ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>` is
+ :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is
greater than one.
.. index:: CONFIGURE_SCHEDULER_NAME
@@ -174,19 +174,18 @@ CONFIGURE_SCHEDULER_PRIORITY
CONSTANT:
``CONFIGURE_SCHEDULER_PRIORITY``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is defined by default. This is the default scheduler and specifying
- this configuration parameter is redundant.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Deterministic Priority Scheduler <SchedulerPriority>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Deterministic Priority Scheduler
- <SchedulerPriority>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Deterministic Priority Scheduler <SchedulerPriority>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -197,7 +196,7 @@ NOTES:
scheduler for exactly one processor.
This scheduler algorithm is the default when
- :ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>` is
+ :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is
exactly one.
The memory allocated for this scheduler depends on the
@@ -213,19 +212,18 @@ CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP
CONSTANT:
``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Arbitrary Processor Affinity SMP Scheduler <SchedulerSMPPriorityAffinity>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Arbitrary Processor Affinity SMP Scheduler
- <SchedulerSMPPriorityAffinity>` algorithm is made available to the
- application.
+ In case this configuration option is defined, then
+ :ref:`Arbitrary Processor Affinity SMP Scheduler <SchedulerSMPPriorityAffinity>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -251,18 +249,18 @@ CONFIGURE_SCHEDULER_PRIORITY_SMP
CONSTANT:
``CONFIGURE_SCHEDULER_PRIORITY_SMP``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Deterministic Priority SMP Scheduler
- <SchedulerSMPPriority>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -288,18 +286,18 @@ CONFIGURE_SCHEDULER_SIMPLE
CONSTANT:
``CONFIGURE_SCHEDULER_SIMPLE``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Simple Priority Scheduler <SchedulerPrioritySimple>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Simple Priority Scheduler
- <SchedulerPrioritySimple>` algorithm is made available to the application.
+ In case this configuration option is defined, then
+ :ref:`Simple Priority Scheduler <SchedulerPrioritySimple>`
+ algorithm is made available to the application.
NOTES:
This scheduler configuration option is an advanced configuration option.
@@ -319,18 +317,18 @@ CONFIGURE_SCHEDULER_SIMPLE_SMP
CONSTANT:
``CONFIGURE_SCHEDULER_SIMPLE_SMP``
-DATA TYPE:
- Boolean feature macro.
-
-RANGE:
- Defined or undefined.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then the
+ :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`
+ algorithm is not available to the application.
DESCRIPTION:
- If defined, then the :ref:`Simple Priority SMP Scheduler
- <SchedulerSMPPrioritySimple>` algorithm is made available to the
+ In case this configuration option is defined, then
+ :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`
+ algorithm is made available to the application.
application.
NOTES:
@@ -354,16 +352,21 @@ CONFIGURE_SCHEDULER_USER
CONSTANT:
``CONFIGURE_SCHEDULER_USER``
-DATA TYPE:
- Boolean feature macro.
+OPTION TYPE:
+ This configuration option is a boolean feature define.
-RANGE:
- Defined or undefined.
-
-DEFAULT VALUE:
- This is not defined by default.
+DEFAULT CONFIGURATION:
+ If this configuration option is undefined, then no user provided scheduler
+ algorithm is available to the application.
DESCRIPTION:
+ In case this configuration option is defined, then the user must provide a
+ scheduler algorithm to the application.
+
+NOTES:
+ This scheduler configuration option is an advanced configuration option.
+ Think twice before you use it.
+
RTEMS allows the application to provide its own task/thread scheduling
algorithm. In order to do this, one must define
``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own
@@ -379,10 +382,6 @@ DESCRIPTION:
- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of
the per-thread information of the user scheduler.
-NOTES:
- This scheduler configuration option is an advanced configuration option.
- Think twice before you use it.
-
At this time, the mechanics and requirements for writing a new scheduler
are evolving and not fully documented. It is recommended that you look at
the existing Deterministic Priority Scheduler in
--
2.16.4
More information about the devel
mailing list