diff options
Diffstat (limited to 'c-user/config')
| -rw-r--r-- | c-user/config/ada.rst | 15 | ||||
| -rw-r--r-- | c-user/config/bdbuf.rst | 533 | ||||
| -rw-r--r-- | c-user/config/classic-api.rst | 612 | ||||
| -rw-r--r-- | c-user/config/classic-init-task.rst | 416 | ||||
| -rw-r--r-- | c-user/config/device-driver.rst | 888 | ||||
| -rw-r--r-- | c-user/config/directives.rst | 1550 | ||||
| -rw-r--r-- | c-user/config/event-record.rst | 243 | ||||
| -rw-r--r-- | c-user/config/face-technical-standard.rst | 76 | ||||
| -rw-r--r-- | c-user/config/filesystem.rst | 1074 | ||||
| -rw-r--r-- | c-user/config/general.rst | 1236 | ||||
| -rw-r--r-- | c-user/config/idle-task.rst | 260 | ||||
| -rw-r--r-- | c-user/config/index.rst | 33 | ||||
| -rw-r--r-- | c-user/config/intro.rst | 322 | ||||
| -rw-r--r-- | c-user/config/introduction.rst | 227 | ||||
| -rw-r--r-- | c-user/config/libpci.rst | 55 | ||||
| -rw-r--r-- | c-user/config/mpci.rst | 355 | ||||
| -rw-r--r-- | c-user/config/obsolete.rst | 234 | ||||
| -rw-r--r-- | c-user/config/posix-api.rst | 540 | ||||
| -rw-r--r-- | c-user/config/posix-init-thread.rst | 156 | ||||
| -rw-r--r-- | c-user/config/scheduler-clustered.rst | 220 | ||||
| -rw-r--r-- | c-user/config/scheduler-general.rst | 814 | ||||
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 314 |
22 files changed, 10173 insertions, 0 deletions
diff --git a/c-user/config/ada.rst b/c-user/config/ada.rst new file mode 100644 index 0000000..49db1f7 --- /dev/null +++ b/c-user/config/ada.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. _ConfigAda: + +Ada Configuration +================= + +The GNU Ada runtime library (libgnarl) uses threads, mutexes, condition +variables, and signals from the pthreads API. It uses also thread-local storage +for the Ada Task Control Block (ATCB). From these resources only the threads +need to be accounted for in the configuration. You should include the Ada tasks +in your setting of the :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` configuration +option. diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst new file mode 100644 index 0000000..2d27d54 --- /dev/null +++ b/c-user/config/bdbuf.rst @@ -0,0 +1,533 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-bdbuf + +Block Device Cache Configuration +================================ + +This section describes configuration options related to the Block Device Cache +(bdbuf). + +.. Generated from spec:/acfg/if/appl-needs-libblock + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK + +.. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: + +CONFIGURE_APPLICATION_NEEDS_LIBBLOCK +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Block Device Cache is +initialized during system initialization. + +.. rubric:: NOTES: + +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. + +.. Generated from spec:/acfg/if/bdbuf-buffer-max-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE + +.. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: + +CONFIGURE_BDBUF_BUFFER_MAX_SIZE +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 4096. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum size of a buffer +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be an integral multiple of + :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. + +.. Generated from spec:/acfg/if/bdbuf-buffer-min-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE + +.. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: + +CONFIGURE_BDBUF_BUFFER_MIN_SIZE +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 512. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum size of a buffer +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-cache-memory-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE + +.. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: + +CONFIGURE_BDBUF_CACHE_MEMORY_SIZE +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32768. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the size of the cache memory +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +.. Generated from spec:/acfg/if/bdbuf-max-read-ahead-blocks + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS + +.. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: + +CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS +------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per +read-ahead request. + +.. rubric:: NOTES: + +A value of 0 disables the read-ahead task (default). The read-ahead task +will issue speculative read transfers if a sequential access pattern is +detected. This can improve the performance on some systems. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-max-write-blocks + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS + +.. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: + +CONFIGURE_BDBUF_MAX_WRITE_BLOCKS +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per write +request. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY + +.. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: + +CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY +---------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the read-ahead task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/bdbuf-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE + +.. _CONFIGURE_BDBUF_TASK_STACK_SIZE: + +CONFIGURE_BDBUF_TASK_STACK_SIZE +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-block-hold + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD + +.. _CONFIGURE_SWAPOUT_BLOCK_HOLD: + +CONFIGURE_SWAPOUT_BLOCK_HOLD +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1000. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-swap-period + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD + +.. _CONFIGURE_SWAPOUT_SWAP_PERIOD: + +CONFIGURE_SWAPOUT_SWAP_PERIOD +----------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 250. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task swap period +in milliseconds. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_TASK_PRIORITY: + +CONFIGURE_SWAPOUT_TASK_PRIORITY +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS + +.. _CONFIGURE_SWAPOUT_WORKER_TASKS: + +CONFIGURE_SWAPOUT_WORKER_TASKS +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout worker task count. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-taskp-riority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: + +CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout worker task +priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst new file mode 100644 index 0000000..212f666 --- /dev/null +++ b/c-user/config/classic-api.rst @@ -0,0 +1,612 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-classic + +Classic API Configuration +========================= + +This section describes configuration options related to the Classic API. + +.. Generated from spec:/acfg/if/max-barriers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_BARRIERS + +.. _CONFIGURE_MAXIMUM_BARRIERS: + +CONFIGURE_MAXIMUM_BARRIERS +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_BARRIERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Barriers that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-message-queues + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES + +.. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: + +CONFIGURE_MAXIMUM_MESSAGE_QUEUES +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Message Queues that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-partitions + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_PARTITIONS + +.. _CONFIGURE_MAXIMUM_PARTITIONS: + +CONFIGURE_MAXIMUM_PARTITIONS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PARTITIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Partitions that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-periods + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_PERIODS + +.. _CONFIGURE_MAXIMUM_PERIODS: + +CONFIGURE_MAXIMUM_PERIODS +------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PERIODS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Periods that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-ports + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_PORTS + +.. _CONFIGURE_MAXIMUM_PORTS: + +CONFIGURE_MAXIMUM_PORTS +----------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PORTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Ports that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-regions + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_REGIONS + +.. _CONFIGURE_MAXIMUM_REGIONS: + +CONFIGURE_MAXIMUM_REGIONS +------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_REGIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Regions that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-semaphores + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_SEMAPHORES + +.. _CONFIGURE_MAXIMUM_SEMAPHORES: + +CONFIGURE_MAXIMUM_SEMAPHORES +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_SEMAPHORES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Semaphore that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +In SMP configurations, the size of a Semaphore Control Block depends on the +scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores +using the :ref:`MrsP` need a ceiling priority per scheduler. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-tasks + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_TASKS + +.. _CONFIGURE_MAXIMUM_TASKS: + +CONFIGURE_MAXIMUM_TASKS +----------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TASKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Tasks that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +The calculations for the required memory in the RTEMS Workspace for tasks +assume that each task has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify task stack requirements *above* the minimum size required. + +The maximum number of POSIX threads is specified by +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. + +A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the +assumption that all tasks have floating point enabled. This would require +the addition of a new configuration parameter to specify the number of +tasks which enable floating point support. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-timers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_TIMERS + +.. _CONFIGURE_MAXIMUM_TIMERS: + +CONFIGURE_MAXIMUM_TIMERS +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API Timers that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-user-extensions + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS + +.. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: + +CONFIGURE_MAXIMUM_USER_EXTENSIONS +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of Classic +API User Extensions that can be concurrently active. + +.. rubric:: NOTES: + +This object class cannot be configured in unlimited allocation mode. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +.. Generated from spec:/acfg/if/min-tasks-with-user-provided-storage + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE + +.. _CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE: + +CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE +-------------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum count of Classic +API Tasks which are constructed by :ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: NOTES: + +By default, the calculation for the required memory in the RTEMS Workspace +for tasks assumes that all Classic API Tasks are created by +:ref:`InterfaceRtemsTaskCreate`. This configuration option can be used to +reduce the required memory for the system-provided task storage areas since +tasks constructed by :ref:`InterfaceRtemsTaskConstruct` use a user-provided +task storage area. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + :ref:`CONFIGURE_MAXIMUM_TASKS`. diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst new file mode 100644 index 0000000..f65bb8a --- /dev/null +++ b/c-user/config/classic-init-task.rst @@ -0,0 +1,416 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-classicinit + +Classic API Initialization Task Configuration +============================================= + +This section describes configuration options related to the Classic API +initialization task. + +.. Generated from spec:/acfg/if/init-task-arguments + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_ARGUMENTS + +.. _CONFIGURE_INIT_TASK_ARGUMENTS: + +CONFIGURE_INIT_TASK_ARGUMENTS +----------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ARGUMENTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines task argument of the Classic +API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :ref:`InterfaceRtemsTaskArgument`. + +.. Generated from spec:/acfg/if/init-task-attributes + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES + +.. _CONFIGURE_INIT_TASK_ATTRIBUTES: + +CONFIGURE_INIT_TASK_ATTRIBUTES +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ATTRIBUTES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task attributes of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task attribute set. + +.. Generated from spec:/acfg/if/init-task-construct-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE + +.. _CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE: + +CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE +------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the Classic API initialization task will be created with the stack size +defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task storage size of the +Classic API initialization task. + +.. rubric:: NOTES: + +If this configuration option is specified, then + +* a task storage area of the specified size is statically allocated by + ``<rtems/confdefs.h>`` for the Classic API initialization task, + +* the Classic API initialization task is constructed by + :ref:`InterfaceRtemsTaskConstruct` instead of using + :ref:`InterfaceRtemsTaskCreate`, + +* the maximum thread-local storage size defined by + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API + initialization task, + +* the Classic API initialization task should be accounted for in + :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and + +* the task storage area used for the Classic API initialization task is not + reclaimed by the system if the task is deleted. + +The + +* :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and + +* ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be defined using + :ref:`InterfaceRTEMSTASKSTORAGESIZE`. + +.. Generated from spec:/acfg/if/init-task-entrypoint + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT + +.. _CONFIGURE_INIT_TASK_ENTRY_POINT: + +CONFIGURE_INIT_TASK_ENTRY_POINT +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``Init``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the entry point of the +Classic API initialization task. + +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *entry_point )( rtems_task_argument )``. + +.. Generated from spec:/acfg/if/init-task-initial-modes + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES + +.. _CONFIGURE_INIT_TASK_INITIAL_MODES: + +CONFIGURE_INIT_TASK_INITIAL_MODES +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_INITIAL_MODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` +otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the initial execution mode of +the Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task mode set. + +.. Generated from spec:/acfg/if/init-task-name + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_NAME + +.. _CONFIGURE_INIT_TASK_NAME: + +CONFIGURE_INIT_TASK_NAME +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the name of the Classic API +initialization task. + +.. rubric:: NOTES: + +Use :ref:`InterfaceRtemsBuildName` to define the task name. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. + +.. Generated from spec:/acfg/if/init-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_PRIORITY + +.. _CONFIGURE_INIT_TASK_PRIORITY: + +CONFIGURE_INIT_TASK_PRIORITY +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the initial priority of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/init-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT_TASK_STACK_SIZE + +.. _CONFIGURE_INIT_TASK_STACK_SIZE: + +CONFIGURE_INIT_TASK_STACK_SIZE +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task stack size of the +Classic API initialization task. + +.. rubric:: NOTES: + +The + +* ``CONFIGURE_INIT_TASK_STACK_SIZE`` and + +* :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/rtems-init-tasks-table + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE + +.. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: + +CONFIGURE_RTEMS_INIT_TASKS_TABLE +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then exactly one Classic API +initialization task is configured. + +.. rubric:: NOTES: + +The application shall define at least one of the following configuration +options + +* ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, + +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or + +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` + +otherwise a compile time error in the configuration file will occur. + +The Classic API initialization task performs the +:ref:`GlobalConstruction`. diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst new file mode 100644 index 0000000..1e31575 --- /dev/null +++ b/c-user/config/device-driver.rst @@ -0,0 +1,888 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-devdrv + +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. + +.. Generated from spec:/acfg/if/appl-does-not-need-clock-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER + +.. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: + +CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER +------------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then a Clock Driver may be +initialized during system initialization. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then **no** Clock Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-extra-drivers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS + +.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS: + +CONFIGURE_APPLICATION_EXTRA_DRIVERS +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is the empty list. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the Device +Driver Table. + +.. rubric:: 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. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. + +.. Generated from spec:/acfg/if/appl-needs-ata-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the ATA Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-clock-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER +---------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Clock Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-console-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER +------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Console Driver is +initialized during system initialization. + +.. rubric:: 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 :ref:`InterfacePrintk` to work +properly without the need for the Console Driver to be configured. + +The + +* ``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. + +.. Generated from spec:/acfg/if/appl-needs-framebuffer-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER +----------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Frame Buffer Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-ide-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the IDE Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-null-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER +.. index:: /dev/null + +.. _CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the :file:`/dev/null` +Driver is initialized during system initialization. + +.. rubric:: NOTES: + +This device driver is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-needs-rtc-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Real-Time Clock Driver +is initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-simple-console-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER +------------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Simple Console Driver +is initialized during system initialization. + +.. rubric:: 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 :ref:`InterfaceGetchark`. + +This device driver writes via :ref:`InterfaceRtemsPutc`. + +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`, + +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. + +.. Generated from spec:/acfg/if/appl-needs-simple-task-console-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER +------------------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Simple Task Console +Driver is initialized during system initialization. + +.. rubric:: 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 :ref:`InterfaceGetchark`. + +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 +:ref:`InterfaceRtemsPutc`. 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 + +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +configuration options are mutually exclusive. + +.. Generated from spec:/acfg/if/appl-needs-stub-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Stub Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +This device driver simply provides entry points that return successful and +is primarily a test fixture. It is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-needs-timer-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER +---------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Benchmark Timer Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-watchdog-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Watchdog Driver is +initialized during system initialization. + +.. rubric:: 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. + +.. Generated from spec:/acfg/if/appl-needs-zero-driver + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER +.. index:: /dev/zero + +.. _CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the :file:`/dev/zero` +Driver is initialized during system initialization. + +.. rubric:: NOTES: + +This device driver is supported by all BSPs. + +.. Generated from spec:/acfg/if/appl-prerequisite-drivers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS + +.. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS: + +CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS +------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is the empty list. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the Device +Driver Table. + +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries defined by +:c:macro:`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. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsDriverAddressTable`. + +.. Generated from spec:/acfg/if/ata-driver-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_ATA_DRIVER_TASK_PRIORITY + +.. _CONFIGURE_ATA_DRIVER_TASK_PRIORITY: + +CONFIGURE_ATA_DRIVER_TASK_PRIORITY +---------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 140. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the ATA task priority. + +.. rubric:: NOTES: + +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/exception-to-signal-mapping + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING + +.. _CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING: + +CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING +------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the machine exception to +POSIX signal mapping is configured during system initialization. + +.. rubric:: NOTES: + +This device driver is responsible for setting up a mapping from machine +exceptions to POSIX signals so that applications may consume them and alter +task execution as necessary. + +This is especially useful for applications written in Ada or C++. + +.. Generated from spec:/acfg/if/max-drivers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_DRIVERS + +.. _CONFIGURE_MAXIMUM_DRIVERS: + +CONFIGURE_MAXIMUM_DRIVERS +------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This is computed by default, and is set to the number of statically +configured device drivers configured using the following configuration +options: + +* :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` + +* :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +the :term:`BSP` provides +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS`, then the BSP-provided +prerequisite device drivers are also taken into account. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of device drivers. + +.. rubric:: NOTES: + +If the application will dynamically install device drivers, then the +configuration option value shall be larger than the number of statically +configured device drivers. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be greater than or equal than the + number of statically configured device drivers. + +* The value of the configuration option 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. diff --git a/c-user/config/directives.rst b/c-user/config/directives.rst new file mode 100644 index 0000000..25351e9 --- /dev/null +++ b/c-user/config/directives.rst @@ -0,0 +1,1550 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ApplicationConfigurationInformationDirectives: + +Directives +========== + +This section details the directives of the Application Configuration +Information. A subsection is dedicated to each of this manager's directives and +lists the calling sequence, parameters, description, return values, and notes +of the directive. + +.. Generated from spec:/rtems/config/if/get-build-label + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_build_label() + +.. _InterfaceRtemsGetBuildLabel: + +rtems_get_build_label() +----------------------- + +Gets the RTEMS build label. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_build_label( void ); + +.. rubric:: DESCRIPTION: + +The build label is a user-provided string defined by the build configuration +through the ``RTEMS_BUILD_LABEL`` build option. The format of the string is +completely user-defined. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS build label. + +.. rubric:: NOTES: + +The build label can be used to distinguish test suite results obtained from +different build configurations. A use case is to record test results with +performance data to track performance regressions. For this a database of +performance limits is required. The build label and the target hash obtained +from :ref:`InterfaceRtemsGetTargetHash` can be used as a key to obtain +performance limits. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-copyright-notice + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_copyright_notice() + +.. _InterfaceRtemsGetCopyrightNotice: + +rtems_get_copyright_notice() +---------------------------- + +Gets the RTEMS copyright notice. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_copyright_notice( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS copyright notice. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-target-hash + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_target_hash() + +.. _InterfaceRtemsGetTargetHash: + +rtems_get_target_hash() +----------------------- + +Gets the RTEMS target hash. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_target_hash( void ); + +.. rubric:: DESCRIPTION: + +The target hash is calculated from BSP-specific values which characterize a +target system. The target hash is encoded as a base64url string. The target +hash algorithm is unspecified. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS target hash. + +.. rubric:: NOTES: + +For example, the device tree, settings of the memory controller, processor and +bus frequencies, a serial number of a chip may be used to calculate the target +hash. + +The target hash can be used to distinguish test suite results obtained from +different target systems. See also :ref:`InterfaceRtemsGetBuildLabel`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-version-string + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_version_string() + +.. _InterfaceRtemsGetVersionString: + +rtems_get_version_string() +-------------------------- + +Gets the RTEMS version string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_version_string( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS version string. + +.. rubric:: NOTES: + +The version string has no particular format. Parsing the string may break +across RTEMS releases. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-do-zero-of-workspace + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_do_zero_of_workspace() + +.. _InterfaceRtemsConfigurationGetDoZeroOfWorkspace: + +rtems_configuration_get_do_zero_of_workspace() +---------------------------------------------- + +Indicates if the RTEMS Workspace is configured to be zeroed during system +initialization for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_do_zero_of_workspace( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace is configured to be zeroed during system +initialization for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task_stack_size() + +.. _InterfaceRtemsConfigurationGetIdleTaskStackSize: + +rtems_configuration_get_idle_task_stack_size() +---------------------------------------------- + +Gets the IDLE task stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_idle_task_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task stack size in bytes of this application. + +.. rubric:: NOTES: + +The IDLE task stack size is defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task() + +.. _InterfaceRtemsConfigurationGetIdleTask: + +rtems_configuration_get_idle_task() +----------------------------------- + +Gets the IDLE task body of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uintptr_t ) rtems_configuration_get_idle_task( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task body of this application. + +.. rubric:: NOTES: + +The IDLE task body is defined by the :ref:`CONFIGURE_IDLE_TASK_BODY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-interrupt-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_interrupt_stack_size() + +.. _InterfaceRtemsConfigurationGetInterruptStackSize: + +rtems_configuration_get_interrupt_stack_size() +---------------------------------------------- + +Gets the interrupt stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_interrupt_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the interrupt stack size in bytes of this application. + +.. rubric:: NOTES: + +The interrupt stack size is defined by the +:ref:`CONFIGURE_INTERRUPT_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-barriers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_barriers() + +.. _InterfaceRtemsConfigurationGetMaximumBarriers: + +rtems_configuration_get_maximum_barriers() +------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_barriers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_BARRIERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_extensions() + +.. _InterfaceRtemsConfigurationGetMaximumExtensions: + +rtems_configuration_get_maximum_extensions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-message-queues + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_message_queues() + +.. _InterfaceRtemsConfigurationGetMaximumMessageQueues: + +rtems_configuration_get_maximum_message_queues() +------------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_message_queues( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-partitions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_partitions() + +.. _InterfaceRtemsConfigurationGetMaximumPartitions: + +rtems_configuration_get_maximum_partitions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicPart` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_partitions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicPart` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-periods + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_periods() + +.. _InterfaceRtemsConfigurationGetMaximumPeriods: + +rtems_configuration_get_maximum_periods() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_periods( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PERIODS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-ports + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_ports() + +.. _InterfaceRtemsConfigurationGetMaximumPorts: + +rtems_configuration_get_maximum_ports() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_ports( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PORTS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-processors + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_processors() + +.. _InterfaceRtemsConfigurationGetMaximumProcessors: + +rtems_configuration_get_maximum_processors() +-------------------------------------------- + +Gets the maximum number of processors configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_processors( void ); + +.. rubric:: RETURN VALUES: + +Returns the maximum number of processors configured for this application. + +.. rubric:: NOTES: + +The actual number of processors available to the application is returned by +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` which less than or equal to +the configured maximum number of processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). + +In uniprocessor configurations, this macro is a compile time constant which +evaluates to one. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-regions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_regions() + +.. _InterfaceRtemsConfigurationGetMaximumRegions: + +rtems_configuration_get_maximum_regions() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRegion` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_regions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRegion` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_REGIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-semaphores + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_semaphores() + +.. _InterfaceRtemsConfigurationGetMaximumSemaphores: + +rtems_configuration_get_maximum_semaphores() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_semaphores( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-tasks + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_tasks() + +.. _InterfaceRtemsConfigurationGetMaximumTasks: + +rtems_configuration_get_maximum_tasks() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTasks` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_tasks( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTasks` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TASKS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-timers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_timers() + +.. _InterfaceRtemsConfigurationGetMaximumTimers: + +rtems_configuration_get_maximum_timers() +---------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTimer` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_timers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTimer` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TIMERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-microseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_microseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMicrosecondsPerTick: + +rtems_configuration_get_microseconds_per_tick() +----------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_microseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of microseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-milliseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_milliseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMillisecondsPerTick: + +rtems_configuration_get_milliseconds_per_tick() +----------------------------------------------- + +Gets the number of milliseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_milliseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of milliseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of milliseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-nanoseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_nanoseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetNanosecondsPerTick: + +rtems_configuration_get_nanoseconds_per_tick() +---------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_nanoseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of nanoseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-number-of-initial-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_number_of_initial_extensions() + +.. _InterfaceRtemsConfigurationGetNumberOfInitialExtensions: + +rtems_configuration_get_number_of_initial_extensions() +------------------------------------------------------ + +Gets the number of initial extensions configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_number_of_initial_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of initial extensions configured for this application. + +.. rubric:: NOTES: + +The number of initial extensions is defined by the +:ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option and +related options. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-for-idle-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_for_idle_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateForIdleHook: + +rtems_configuration_get_stack_allocate_for_idle_hook() +------------------------------------------------------ + +Gets the task stack allocator allocate hook used to allocate the stack of each +:term:`IDLE task` configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uint32_t, size_t * ) + rtems_configuration_get_stack_allocate_for_idle_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook used to allocate the stack of +each :term:`IDLE task` configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook for idle tasks is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` application configuration +option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateHook: + +rtems_configuration_get_stack_allocate_hook() +--------------------------------------------- + +Gets the task stack allocator allocate hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( size_t ) rtems_configuration_get_stack_allocate_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-init-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_init_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateInitHook: + +rtems_configuration_get_stack_allocate_init_hook() +-------------------------------------------------- + +Gets the task stack allocator initialization hook configured for this +application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( size_t ) rtems_configuration_get_stack_allocate_init_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator initialization hook configured for this +application. + +.. rubric:: NOTES: + +The task stack allocator initialization hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocator-avoids-work-space + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocator_avoids_work_space() + +.. _InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace: + +rtems_configuration_get_stack_allocator_avoids_work_space() +----------------------------------------------------------- + +Indicates if the task stack allocator is configured to avoid the RTEMS +Workspace for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_stack_allocator_avoids_work_space( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the task stack allocator is configured to avoid the RTEMS +Workspace for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-free-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_free_hook() + +.. _InterfaceRtemsConfigurationGetStackFreeHook: + +rtems_configuration_get_stack_free_hook() +----------------------------------------- + +Gets the task stack allocator free hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( void * ) rtems_configuration_get_stack_free_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator free hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator free hook is defined by the +:ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_space_size() + +.. _InterfaceRtemsConfigurationGetStackSpaceSize: + +rtems_configuration_get_stack_space_size() +------------------------------------------ + +Gets the configured size in bytes of the memory space used to allocate thread +stacks for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_stack_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the configured size in bytes of the memory space used to allocate +thread stacks for this application. + +.. rubric:: NOTES: + +The size takes only threads and tasks into account with are known at the +application configuration time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-ticks-per-timeslice + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_ticks_per_timeslice() + +.. _InterfaceRtemsConfigurationGetTicksPerTimeslice: + +rtems_configuration_get_ticks_per_timeslice() +--------------------------------------------- + +Gets the clock ticks per timeslice configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_ticks_per_timeslice( void ); + +.. rubric:: RETURN VALUES: + +Returns the clock ticks per timeslice configured for this application. + +.. rubric:: NOTES: + +The :term:`clock ticks <clock tick>` per timeslice is defined by the +:ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-unified-work-area + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_unified_work_area() + +.. _InterfaceRtemsConfigurationGetUnifiedWorkArea: + +rtems_configuration_get_unified_work_area() +------------------------------------------- + +Indicates if the RTEMS Workspace and C Program Heap are configured to be +unified for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_unified_work_area( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace and C Program Heap are configured to be +unified for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_UNIFIED_WORK_AREAS` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-extension-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_extension_table() + +.. _InterfaceRtemsConfigurationGetUserExtensionTable: + +rtems_configuration_get_user_extension_table() +---------------------------------------------- + +Gets the initial extensions table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_extensions_table *rtems_configuration_get_user_extension_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the initial extensions table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-multiprocessing-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_multiprocessing_table() + +.. _InterfaceRtemsConfigurationGetUserMultiprocessingTable: + +rtems_configuration_get_user_multiprocessing_table() +---------------------------------------------------- + +Gets the MPCI configuration table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const MPCI_Configuration *rtems_configuration_get_user_multiprocessing_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the MPCI configuration table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-work-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_work_space_size() + +.. _InterfaceRtemsConfigurationGetWorkSpaceSize: + +rtems_configuration_get_work_space_size() +----------------------------------------- + +Gets the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_work_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-api-configuration + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_rtems_api_configuration() + +.. _InterfaceRtemsConfigurationGetRtemsApiConfiguration: + +rtems_configuration_get_rtems_api_configuration() +------------------------------------------------- + +Gets the Classic API Configuration Table of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_api_configuration_table * + rtems_configuration_get_rtems_api_configuration( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the Classic API Configuration Table of this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-is-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_is_unlimited() + +.. _InterfaceRtemsResourceIsUnlimited: + +rtems_resource_is_unlimited() +----------------------------- + +Indicates if the resource is unlimited. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_resource_is_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns true, if the resource is unlimited, otherwise false. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-maximum-per-allocation + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_maximum_per_allocation() + +.. _InterfaceRtemsResourceMaximumPerAllocation: + +rtems_resource_maximum_per_allocation() +--------------------------------------- + +Gets the maximum number per allocation of a resource number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_maximum_per_allocation( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns the maximum number per allocation of a resource number. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_unlimited() + +.. _InterfaceRtemsResourceUnlimited: + +rtems_resource_unlimited() +-------------------------- + +Augments the resource number so that it indicates an unlimited resource. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number to augment. + +.. rubric:: RETURN VALUES: + +Returns the resource number augmented to indicate an unlimited resource. + +.. rubric:: NOTES: + +This directive should be used to configure unlimited objects, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst new file mode 100644 index 0000000..1e5c52a --- /dev/null +++ b/c-user/config/event-record.rst @@ -0,0 +1,243 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2022 embedded brains GmbH & Co. KG + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-eventrecord + +Event Recording Configuration +============================= + +This section describes configuration options related to the event recording. + +.. Generated from spec:/acfg/if/record-extensions-enabled + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED + +.. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: + +CONFIGURE_RECORD_EXTENSIONS_ENABLED +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the event record extensions are enabled. + +.. rubric:: NOTES: + +The record extensions capture thread create, start, restart, delete, switch, +begin, exitted and terminate events. + +.. Generated from spec:/acfg/if/record-fatal-dump-base64 + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64 + +.. _CONFIGURE_RECORD_FATAL_DUMP_BASE64: + +CONFIGURE_RECORD_FATAL_DUMP_BASE64 +---------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +* and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, + +then the event records are dumped in Base64 encoding in a fatal error +extension (see :ref:`Terminate`). + +.. rubric:: NOTES: + +This extension can be used to produce crash dumps. + +.. Generated from spec:/acfg/if/record-fatal-dump-base64-zlib + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB + +.. _CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB: + +CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the event records are compressed by zlib and dumped in Base64 encoding +in a fatal error extension (see :ref:`Terminate`). + +.. rubric:: NOTES: + +The zlib compression needs about 512KiB of RAM. This extension can be used +to produce crash dumps. + +.. Generated from spec:/acfg/if/record-interrupts-enabled + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_INTERRUPTS_ENABLED + +.. _CONFIGURE_RECORD_INTERRUPTS_ENABLED: + +CONFIGURE_RECORD_INTERRUPTS_ENABLED +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_INTERRUPTS_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case + +* this configuration option is defined + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the interrupt event recording is enabled. + +.. rubric:: NOTES: + +The interrupt event recording generates interrupt entry and exit events when +interrupt entries are dispatched. + +.. Generated from spec:/acfg/if/record-per-processor-items + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS + +.. _CONFIGURE_RECORD_PER_PROCESSOR_ITEMS: + +CONFIGURE_RECORD_PER_PROCESSOR_ITEMS +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the event record item count +per processor. + +.. rubric:: NOTES: + +The event record buffers are statically allocated for each configured +processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this +configuration option is zero, then nothing is allocated. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to 16. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be a power of two. + +* The value of the configuration option 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. diff --git a/c-user/config/face-technical-standard.rst b/c-user/config/face-technical-standard.rst new file mode 100644 index 0000000..8772773 --- /dev/null +++ b/c-user/config/face-technical-standard.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-face + +FACE Technical Standard Related Configuration +============================================= + +This section describes configuration options related to adapting +RTEMS behavior to be aligned with the FACE Technical Standard. +The FACE Technical Standard is a product of the FACE Consortium +which operates under the Open Group. The FACE Consortium was founded +by avionics organizations to improve the portability of cockpit software +across various platforms. It addresses technical and business concerns. + +Most important from an RTEMS perspective, the FACE Technical Standard +defines four POSIX profiles: Security, Safety Base, Safety Extended, and +the General Purpose Profile. Each has an increasingly larger subset of +POSIX APIs. In the Security and Safety profiles, ARINC 653 is required. +It is optional in the General Purpose Profile. + +The RTEMS Project has been tracking alignment with the FACE POSIX profiles +and they are included in the "RTEMS POSIX 1003.1 Compliance Guide." + +.. Generated from spec:/acfg/if/posix-timer-face-behavior + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR + +.. _CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR: + +CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +If this configuration option is defined, then POSIX timers may not be created +to use the :term:`CLOCK_REALTIME`. Per POSIX, this is allowed +behavior but per the FACE Technical Standard, it is not. Using POSIX timers +based on CLOCK_REALTIME (e.g., time of day) is unsafe for real-time safety +systems as setting CLOCK_REALTIME will perturb any active timers. + +If this option is not defined, POSIX timers may be created to use the +CLOCK_REALTIME in compliance with the POSIX specification. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst new file mode 100644 index 0000000..c565f4c --- /dev/null +++ b/c-user/config/filesystem.rst @@ -0,0 +1,1074 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-filesystem + +Filesystem Configuration +======================== + +This section describes configuration options related to filesytems. +By default, the In-Memory Filesystem (IMFS) is used as the base filesystem (also +known as root filesystem). In order to save some memory for your application, +you can disable the filesystem support with the +:ref:`CONFIGURE_APPLICATION_DISABLE_FILESYSTEM` configuration option. +Alternatively, you can strip down the features of the base filesystem with the +:ref:`CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM` and +:ref:`CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM` configuration options. These +three configuration options are mutually exclusive. They are intended for an +advanced application configuration. + +Features of the IMFS can be disabled and enabled with the following +configuration options: + +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD` + +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN` + +* :ref:`CONFIGURE_IMFS_DISABLE_LINK` + +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD` + +* :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` + +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT` + +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME` + +* :ref:`CONFIGURE_IMFS_ENABLE_MKFIFO` + +.. Generated from spec:/acfg/if/appl-disable-filesystem + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM + +.. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: + +CONFIGURE_APPLICATION_DISABLE_FILESYSTEM +---------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then a base filesystem and the +configured filesystems are initialized during system initialization. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then **no base filesystem** is +initialized during system initialization and **no filesystems** are +configured. + +.. rubric:: NOTES: + +Filesystems shall 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. + +.. Generated from spec:/acfg/if/filesystem-all + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_ALL + +.. _CONFIGURE_FILESYSTEM_ALL: + +CONFIGURE_FILESYSTEM_ALL +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_ALL`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the following +configuration options will be defined as well + +* :ref:`CONFIGURE_FILESYSTEM_DOSFS`, + +* :ref:`CONFIGURE_FILESYSTEM_FTPFS`, + +* :ref:`CONFIGURE_FILESYSTEM_IMFS`, + +* :ref:`CONFIGURE_FILESYSTEM_JFFS2`, + +* :ref:`CONFIGURE_FILESYSTEM_NFS`, + +* :ref:`CONFIGURE_FILESYSTEM_RFS`, and + +* :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. + +.. Generated from spec:/acfg/if/filesystem-dosfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_DOSFS + +.. _CONFIGURE_FILESYSTEM_DOSFS: + +CONFIGURE_FILESYSTEM_DOSFS +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_DOSFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the DOS (FAT) filesystem +is registered, so that instances of this filesystem can be mounted by the +application. + +.. rubric:: NOTES: + +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. + +.. Generated from spec:/acfg/if/filesystem-ftpfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_FTPFS + +.. _CONFIGURE_FILESYSTEM_FTPFS: + +CONFIGURE_FILESYSTEM_FTPFS +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_FTPFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the FTP filesystem (FTP +client) is registered, so that instances of this filesystem +can be mounted by the application. + +.. Generated from spec:/acfg/if/filesystem-imfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_IMFS + +.. _CONFIGURE_FILESYSTEM_IMFS: + +CONFIGURE_FILESYSTEM_IMFS +------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_IMFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the In-Memory Filesystem +(IMFS) is registered, so that instances of this filesystem can be mounted by +the application. + +.. rubric:: NOTES: + +Applications will rarely need this configuration option. This configuration +option is intended for test programs. You do not need to define this +configuration option for the base filesystem (also known as root filesystem). + +.. Generated from spec:/acfg/if/filesystem-jffs2 + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_JFFS2 + +.. _CONFIGURE_FILESYSTEM_JFFS2: + +CONFIGURE_FILESYSTEM_JFFS2 +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_JFFS2`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the JFFS2 filesystem +is registered, so that instances of this filesystem can be mounted by the +application. + +.. Generated from spec:/acfg/if/filesystem-nfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_NFS + +.. _CONFIGURE_FILESYSTEM_NFS: + +CONFIGURE_FILESYSTEM_NFS +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_NFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Network Filesystem +(NFS) client is registered, so that instances of this filesystem can be +mounted by the application. + +.. Generated from spec:/acfg/if/filesystem-rfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_RFS + +.. _CONFIGURE_FILESYSTEM_RFS: + +CONFIGURE_FILESYSTEM_RFS +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_RFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the RTEMS Filesystem (RFS) +is registered, so that instances of this filesystem can be mounted by the +application. + +.. rubric:: NOTES: + +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. + +.. Generated from spec:/acfg/if/filesystem-tftpfs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_FILESYSTEM_TFTPFS + +.. _CONFIGURE_FILESYSTEM_TFTPFS: + +CONFIGURE_FILESYSTEM_TFTPFS +--------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_TFTPFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the TFTP filesystem (TFTP +client) is registered, so that instances of this filesystem can be mounted by +the application. + +.. Generated from spec:/acfg/if/imfs-disable-chmod + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_CHMOD + +.. _CONFIGURE_IMFS_DISABLE_CHMOD: + +CONFIGURE_IMFS_DISABLE_CHMOD +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHMOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +changing the mode of files. + +.. rubric:: DESCRIPTION: + +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`). + +.. Generated from spec:/acfg/if/imfs-disable-chown + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_CHOWN + +.. _CONFIGURE_IMFS_DISABLE_CHOWN: + +CONFIGURE_IMFS_DISABLE_CHOWN +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHOWN`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +changing the ownership of files. + +.. rubric:: DESCRIPTION: + +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`). + +.. Generated from spec:/acfg/if/imfs-disable-link + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_LINK + +.. _CONFIGURE_IMFS_DISABLE_LINK: + +CONFIGURE_IMFS_DISABLE_LINK +--------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_LINK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports hard +links. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support hard links (no support for :c:func:`link`). + +.. Generated from spec:/acfg/if/imfs-disable-mknod + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD + +.. _CONFIGURE_IMFS_DISABLE_MKNOD: + +CONFIGURE_IMFS_DISABLE_MKNOD +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports making +files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making files (no support for :c:func:`mknod`). + +.. Generated from spec:/acfg/if/imfs-disable-mknod-device + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE + +.. _CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE: + +CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports making +device files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making device files. + +.. Generated from spec:/acfg/if/imfs-disable-mknod-file + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE + +.. _CONFIGURE_IMFS_DISABLE_MKNOD_FILE: + +CONFIGURE_IMFS_DISABLE_MKNOD_FILE +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports making +regular files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making regular files. + +.. Generated from spec:/acfg/if/imfs-disable-mount + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_MOUNT + +.. _CONFIGURE_IMFS_DISABLE_MOUNT: + +CONFIGURE_IMFS_DISABLE_MOUNT +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MOUNT`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +mounting other filesystems. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support mounting other filesystems (no support for +:c:func:`mount`). + +.. Generated from spec:/acfg/if/imfs-disable-readdir + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_READDIR + +.. _CONFIGURE_IMFS_DISABLE_READDIR: + +CONFIGURE_IMFS_DISABLE_READDIR +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READDIR`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +reading directories. + +.. rubric:: DESCRIPTION: + +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. + +.. Generated from spec:/acfg/if/imfs-disable-readlink + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_READLINK + +.. _CONFIGURE_IMFS_DISABLE_READLINK: + +CONFIGURE_IMFS_DISABLE_READLINK +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READLINK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +reading symbolic links. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading symbolic links (no support for :c:func:`readlink`). + +.. Generated from spec:/acfg/if/imfs-disable-rename + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_RENAME + +.. _CONFIGURE_IMFS_DISABLE_RENAME: + +CONFIGURE_IMFS_DISABLE_RENAME +----------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RENAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +renaming files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support renaming files (no support for :c:func:`rename`). + +.. Generated from spec:/acfg/if/imfs-disable-rmnod + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_RMNOD + +.. _CONFIGURE_IMFS_DISABLE_RMNOD: + +CONFIGURE_IMFS_DISABLE_RMNOD +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RMNOD`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +removing files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support removing files (no support for :c:func:`rmnod`). + +.. Generated from spec:/acfg/if/imfs-disable-symlink + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK + +.. _CONFIGURE_IMFS_DISABLE_SYMLINK: + +CONFIGURE_IMFS_DISABLE_SYMLINK +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_SYMLINK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +creating symbolic links. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support creating symbolic links (no support for :c:func:`symlink`). + +.. Generated from spec:/acfg/if/imfs-disable-unmount + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT + +.. _CONFIGURE_IMFS_DISABLE_UNMOUNT: + +CONFIGURE_IMFS_DISABLE_UNMOUNT +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UNMOUNT`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +unmounting other filesystems. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support unmounting other filesystems (no support for +:c:func:`unmount`). + +.. Generated from spec:/acfg/if/imfs-disable-utime + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_DISABLE_UTIME + +.. _CONFIGURE_IMFS_DISABLE_UTIME: + +CONFIGURE_IMFS_DISABLE_UTIME +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UTIME`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +changing file times. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing file times (no support for :c:func:`utime`). + +.. Generated from spec:/acfg/if/imfs-enable-mkfifo + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_ENABLE_MKFIFO + +.. _CONFIGURE_IMFS_ENABLE_MKFIFO: + +CONFIGURE_IMFS_ENABLE_MKFIFO +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_ENABLE_MKFIFO`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS does not +support making FIFOs (no support for :c:func:`mkfifo`). + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS supports +making FIFOs. + +.. Generated from spec:/acfg/if/imfs-memfile-bytes-per-block + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK + +.. _CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK: + +CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 128. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the block size for in-memory +files managed by the IMFS. + +.. rubric:: NOTES: + +The configured block size has two impacts. The first is the average amount of +unused memory in the last block of each file. For example, when the block +size is 512, on average one-half of the last block of each file will remain +unused and the memory is wasted. In contrast, when the block size is 16, the +average unused memory per file is only 8 bytes. However, it requires more +allocations for the same size file and thus more overhead per block for the +dynamic memory management. + +Second, the block size has an impact on the maximum size file that can be +stored in the IMFS. With smaller block size, the maximum file size is +correspondingly smaller. The following shows the maximum file size possible +based on the configured block size: + +* when the block size is 16 bytes, the maximum file size is 1,328 bytes. + +* when the block size is 32 bytes, the maximum file size is 18,656 bytes. + +* when the block size is 64 bytes, the maximum file size is 279,488 bytes. + +* when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. + +* when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. + +* when the block size is 512 bytes, the maximum file size is 1,082,195,456 + bytes. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be equal to 16, 32, 64, 128, 256, +or 512. + +.. Generated from spec:/acfg/if/jffs2-delayed-write-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY + +.. _CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY: + +CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the JFFS2 delayed write task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. + +.. Generated from spec:/acfg/if/use-devfs-as-base-filesystem + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM + +.. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: + +CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: 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). + +.. rubric:: NOTES: + +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`, + +* :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. + +.. Generated from spec:/acfg/if/use-miniimfs-as-base-filesystem + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM + +.. _CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM: + +CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM +----------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: 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). + +.. rubric:: NOTES: + +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_READLINK`, + +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, + +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, + +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and + +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. diff --git a/c-user/config/general.rst b/c-user/config/general.rst new file mode 100644 index 0000000..61bfa1e --- /dev/null +++ b/c-user/config/general.rst @@ -0,0 +1,1236 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-general + +General System Configuration +============================ + +This section describes general system configuration options. + +.. Generated from spec:/acfg/if/dirty-memory + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_DIRTY_MEMORY + +.. _CONFIGURE_DIRTY_MEMORY: + +CONFIGURE_DIRTY_MEMORY +---------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_DIRTY_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +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. + +.. rubric:: NOTES: + +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. + +See also :ref:`CONFIGURE_MALLOC_DIRTY`. + +.. Generated from spec:/acfg/if/disable-bsp-settings + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS + +.. _CONFIGURE_DISABLE_BSP_SETTINGS: + +CONFIGURE_DISABLE_BSP_SETTINGS +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_BSP_SETTINGS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the optional BSP provided +settings listed below are disabled. + +The optional BSP provided default values for the following application +configuration options are disabled: + +* :ref:`CONFIGURE_IDLE_TASK_BODY` + +* :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` + +* :ref:`CONFIGURE_INTERRUPT_STACK_SIZE` + +The optional BSP provided initial extension set is disabled (see +:term:`initial extension sets`). The optional BSP provided +prerequisite IO device drivers are disabled (see +Device Driver Configuration). The optional BSP provided support for +:c:func:`sbrk` is disabled. + +This configuration option provides an all or nothing choice with respect to +the optional BSP provided settings. + +.. Generated from spec:/acfg/if/disable-newlib-reentrancy + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY + +.. _CONFIGURE_DISABLE_NEWLIB_REENTRANCY: + +CONFIGURE_DISABLE_NEWLIB_REENTRANCY +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Newlib reentrancy +support per thread is disabled and a global reentrancy structure is used. + +.. rubric:: NOTES: + +You can enable this option to reduce the size of the :term:`TCB`. Use this +option with care, since it can lead to race conditions and undefined system +behaviour. For example, :c:macro:`errno` is no longer a thread-local +variable if this option is enabled. + +.. Generated from spec:/acfg/if/executive-ram-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_EXECUTIVE_RAM_SIZE + +.. _CONFIGURE_EXECUTIVE_RAM_SIZE: + +CONFIGURE_EXECUTIVE_RAM_SIZE +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_EXECUTIVE_RAM_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If this configuration option is undefined, then the RTEMS Workspace and task +stack space size is calculated by ``<rtems/confdefs.h>`` based on the +values configuration options. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the RTEMS Workspace size in +bytes. + +.. rubric:: NOTES: + +This is an advanced configuration option. Use it only if you know exactly +what you are doing. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option 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. + +.. Generated from spec:/acfg/if/extra-task-stacks + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_EXTRA_TASK_STACKS +.. index:: memory for task tasks + +.. _CONFIGURE_EXTRA_TASK_STACKS: + +CONFIGURE_EXTRA_TASK_STACKS +--------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_TASK_STACKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes the +applications wishes to add to the task stack requirements calculated by +``<rtems/confdefs.h>``. + +.. rubric:: NOTES: + +This parameter is very important. If the application creates tasks with +stacks larger then the minimum, then that memory is **not** accounted for by +``<rtems/confdefs.h>``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/init + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT + +.. _CONFIGURE_INIT: + +CONFIGURE_INIT +-------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +There is no default configuration associated with this configuration option. +If ``<rtems/confdefs.h>`` is included and this configuration option is not +defined, then only white space is included. + +.. rubric:: DESCRIPTION: + +While this configuration option is defined, when the ``<rtems/confdefs.h>`` +is included, the system settings defined by present application configuration +options are statically allocated and initialized. All user provided +application configuration options defined before the include of +``<rtems/confdefs.h>`` are evaluated. They define the actual system +settings. + +.. Generated from spec:/acfg/if/initial-extensions + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INITIAL_EXTENSIONS + +.. _CONFIGURE_INITIAL_EXTENSIONS: + +CONFIGURE_INITIAL_EXTENSIONS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_INITIAL_EXTENSIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is the empty list. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +initial user extensions. + +.. rubric:: NOTES: + +The value of this configuration option is placed before the entries of +:c:macro:`BSP_INITIAL_EXTENSION` and after the entries of all other +initial user extensions. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :ref:`InterfaceRtemsExtensionsTable`. + +.. Generated from spec:/acfg/if/interrupt-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INTERRUPT_STACK_SIZE +.. index:: interrupt stack size + +.. _CONFIGURE_INTERRUPT_STACK_SIZE: + +CONFIGURE_INTERRUPT_STACK_SIZE +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_INTERRUPT_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_INTERRUPT_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_INTERRUPT_STACK_SIZE`, otherwise the default value is +:c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the size of an interrupt stack +in bytes. + +.. rubric:: NOTES: + +There is one interrupt stack available for each configured processor +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). The interrupt stack areas are +statically allocated in a special linker section (``.rtemsstack.interrupt``). +The placement of this linker section is BSP-specific. + +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. + +The interrupt stacks are covered by the stack checker, see +:ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack +size may still result in undefined behaviour. + +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the + interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does + not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +* The value of the configuration option shall be aligned according to + :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. + +.. Generated from spec:/acfg/if/malloc-dirty + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MALLOC_DIRTY + +.. _CONFIGURE_MALLOC_DIRTY: + +CONFIGURE_MALLOC_DIRTY +---------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_DIRTY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then each memory area returned +by C Program Heap allocator functions such as :c:func:`malloc` is dirtied +with a ``0xCF`` byte pattern before it is handed over to the application. + +.. rubric:: NOTES: + +The dirtying performed by this option is carried out for each successful +memory allocation from the C Program Heap in contrast to +:ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the +system initialization. + +.. Generated from spec:/acfg/if/max-file-descriptors + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS +.. index:: maximum file descriptors + +.. _CONFIGURE_MAXIMUM_FILE_DESCRIPTORS: + +CONFIGURE_MAXIMUM_FILE_DESCRIPTORS +---------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 3. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. + +.. rubric:: NOTES: + +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option 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. + +.. Generated from spec:/acfg/if/max-processors + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_PROCESSORS + +.. _CONFIGURE_MAXIMUM_PROCESSORS: + +CONFIGURE_MAXIMUM_PROCESSORS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PROCESSORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +processors an application intends to use. The number of actually available +processors depends on the hardware and may be less. It is recommended to use +the smallest value suitable for the application in order to save memory. +Each processor needs an IDLE task stack and interrupt stack for example. + +.. rubric:: NOTES: + +If there are more processors available than configured, the rest will be +ignored. + +This configuration option is only evaluated in SMP configurations of RTEMS +(e.g. RTEMS was built with the SMP build configuration option enabled). +In all other configurations it has no effect. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + :c:macro:`CPU_MAXIMUM_PROCESSORS`. + +.. Generated from spec:/acfg/if/max-thread-local-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE + +.. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: + +CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +If the value of this configuration option is greater than zero, then it +defines the maximum thread-local storage size, otherwise the thread-local +storage size is defined by the linker depending on the thread-local storage +objects used by the application in the statically-linked executable. + +.. rubric:: NOTES: + +This configuration option can be used to reserve space for the dynamic linking +of modules with thread-local storage objects. + +If the thread-local storage size defined by the thread-local storage +objects used by the application in the statically-linked executable is greater +than a non-zero value of this configuration option, then a fatal error will +occur during system initialization. + +Use :c:func:`RTEMS_ALIGN_UP` and +:c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the +minimum alignment requirement of a thread-local storage area. + +The actual thread-local storage size is determined when the application +executable is linked. The ``rtems-exeinfo`` command line tool included in +the RTEMS Tools can be used to obtain the thread-local storage size and +alignment of an application executable. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be an integral multiple of + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. + +.. Generated from spec:/acfg/if/max-thread-name-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +.. index:: maximum thread name size + +.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE: + +CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +---------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum thread name size +including the terminating ``NUL`` character. + +.. rubric:: NOTES: + +The default value was chosen for Linux compatibility, see +`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. + +The size of the thread control block is increased by the maximum thread name +size. + +This configuration option is available since RTEMS 5.1. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option 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. + +.. Generated from spec:/acfg/if/memory-overhead + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MEMORY_OVERHEAD + +.. _CONFIGURE_MEMORY_OVERHEAD: + +CONFIGURE_MEMORY_OVERHEAD +------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MEMORY_OVERHEAD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of kilobytes the +application wishes to add to the RTEMS Workspace size calculated by +``<rtems/confdefs.h>``. + +.. rubric:: NOTES: + +This configuration option should only be used when it is suspected that a bug +in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the +memory allocation will be too low when an application does not account for +all message queue buffers or task stacks, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/message-buffer-memory + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY +.. index:: configure message queue buffer memory +.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE +.. index:: memory for a single message queue's buffers + +.. _CONFIGURE_MESSAGE_BUFFER_MEMORY: + +CONFIGURE_MESSAGE_BUFFER_MEMORY +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes reserved +for message queue buffers in the RTEMS Workspace. + +.. rubric:: NOTES: + +The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and +:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message +queues can be created by the application. The memory for the message +buffers is configured by this option. For each message queue you have to +reserve some memory for the message buffers. The size depends on the +maximum number of pending messages and the maximum size of the messages of +a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro +to specify the message buffer memory for each message queue and sum them up +to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. + +The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help +macro is as follows: + +.. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) + +Where ``max_messages`` is the maximum number of pending messages and +``max_msg_size`` is the maximum size in bytes of the messages of the +corresponding message queue. Both parameters shall be compile time +constants. Not using this help macro (e.g. just using +``max_messages * max_msg_size``) may result in an underestimate of the +RTEMS Workspace size. + +The following example illustrates how the +``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro can be used to assist in +calculating the message buffer memory required. In this example, there are +two message queues used in this application. The first message queue has a +maximum of 24 pending messages with the message structure defined by the +type ``one_message_type``. The other message queue has a maximum of 500 +pending messages with the message structure defined by the type +``other_message_type``. + +.. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, \ + sizeof( one_message_type ) \ + ) \ + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, \ + sizeof( other_message_type ) \ + ) \ + ) + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/microseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MICROSECONDS_PER_TICK +.. index:: clock tick quantum +.. index:: tick quantum + +.. _CONFIGURE_MICROSECONDS_PER_TICK: + +CONFIGURE_MICROSECONDS_PER_TICK +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MICROSECONDS_PER_TICK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 10000. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the length of time in +microseconds between clock ticks (clock tick quantum). + +When the clock tick quantum value is too low, the system will spend so much +time processing clock ticks that it does not have processing time available +to perform application work. In this case, the system will become +unresponsive. + +The lowest practical time quantum varies widely based upon the speed of the +target hardware and the architectural overhead associated with +interrupts. In general terms, you do not want to configure it lower than is +needed for the application. + +The clock tick quantum should be selected such that it all blocking and +delay times in the application are evenly divisible by it. Otherwise, +rounding errors will be introduced which may negatively impact the +application. + +.. rubric:: NOTES: + +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. + +There may be Clock Driver specific limits on the resolution or maximum value +of a clock tick quantum. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + value defined by the :term:`Clock Driver`. + +* The value of the configuration option shall be less than or equal to a value + defined by the :term:`Clock Driver`. + +* The resulting clock ticks per second should be an integer. + +.. Generated from spec:/acfg/if/min-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE +.. index:: minimum task stack size + +.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE: + +CONFIGURE_MINIMUM_TASK_STACK_SIZE +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum stack size in +bytes for every user task or thread in the system. + +.. rubric:: NOTES: + +Adjusting this parameter should be done with caution. Examining the actual +stack usage using the stack checker usage reporting facility is recommended +(see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`). + +This parameter can be used to lower the minimum from that recommended. This +can be used in low memory systems to reduce memory consumption for +stacks. However, this shall be done with caution as it could increase the +possibility of a blown task stack. + +This parameter can be used to increase the minimum from that +recommended. This can be used in higher memory systems to reduce the risk +of stack overflow without performing analysis on actual consumption. + +By default, this configuration parameter defines also the minimum stack +size of POSIX threads. This can be changed with the +:ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE` +configuration option. + +In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was +used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +.. Generated from spec:/acfg/if/stack-checker-enabled + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_STACK_CHECKER_ENABLED + +.. _CONFIGURE_STACK_CHECKER_ENABLED: + +CONFIGURE_STACK_CHECKER_ENABLED +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_STACK_CHECKER_ENABLED`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the stack checker is +enabled. + +.. rubric:: NOTES: + +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. + +In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. + +.. Generated from spec:/acfg/if/ticks-per-time-slice + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TICKS_PER_TIMESLICE +.. index:: ticks per timeslice + +.. _CONFIGURE_TICKS_PER_TIMESLICE: + +CONFIGURE_TICKS_PER_TIMESLICE +----------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TICKS_PER_TIMESLICE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 50. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. + +.. rubric:: NOTES: + +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/unified-work-areas + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_UNIFIED_WORK_AREAS +.. index:: unified work areas +.. index:: separate work areas +.. index:: RTEMS Workspace +.. index:: C Program Heap + +.. _CONFIGURE_UNIFIED_WORK_AREAS: + +CONFIGURE_UNIFIED_WORK_AREAS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_UNIFIED_WORK_AREAS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then there will be separate memory +pools for the RTEMS Workspace and C Program Heap. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the RTEMS Workspace and +the C Program Heap will be one pool of memory. + +.. rubric:: NOTES: + +Having separate pools does have some advantages in the event a task blows a +stack or writes outside its memory area. However, in low memory systems the +overhead of the two pools plus the potential for unused memory in either +pool is very undesirable. + +In high memory environments, this is desirable when you want to use the +: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. + +.. Generated from spec:/acfg/if/unlimited-allocation-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE + +.. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE: + +CONFIGURE_UNLIMITED_ALLOCATION_SIZE +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 8. + +.. rubric:: DESCRIPTION: + +If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this +configuration option defines the default objects maximum of all object +classes supporting :ref:`ConfigUnlimitedObjects` to +``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. + +.. rubric:: NOTES: + +By allowing users to declare all resources as being unlimited the user can +avoid identifying and limiting the resources used. + +The object maximum of each class can be configured also individually using +the :ref:`InterfaceRtemsResourceUnlimited` macro. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall meet the constraints of all object +classes to which it is applied. + +.. Generated from spec:/acfg/if/unlimited-objects + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_UNLIMITED_OBJECTS + +.. _CONFIGURE_UNLIMITED_OBJECTS: + +CONFIGURE_UNLIMITED_OBJECTS +--------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then unlimited objects are used +by default. + +.. rubric:: NOTES: + +When using unlimited objects, it is common practice to also specify +: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`. + +.. Generated from spec:/acfg/if/verbose-system-init + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION + +.. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION: + +CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system initialization +is verbose. + +.. rubric:: NOTES: + +You may use this feature to debug system initialization issues. The +:ref:`InterfacePrintk` function is used to print the information. + +.. Generated from spec:/acfg/if/zero-workspace-automatically + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +.. index:: clear C Program Heap +.. index:: clear RTEMS Workspace +.. index:: zero C Program Heap +.. index:: zero RTEMS Workspace + +.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY: + +CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +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 ``0x00`` byte +pattern during system initialization. + +.. rubric:: NOTES: + +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 new file mode 100644 index 0000000..793fb5c --- /dev/null +++ b/c-user/config/idle-task.rst @@ -0,0 +1,260 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-idle + +Idle Task Configuration +======================= + +This section describes configuration options related to the idle tasks. + +.. Generated from spec:/acfg/if/idle-task-body + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_BODY + +.. _CONFIGURE_IDLE_TASK_BODY: + +CONFIGURE_IDLE_TASK_BODY +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_BODY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_BODY` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_BODY`, otherwise the default value is +``_CPU_Thread_Idle_body``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the IDLE thread body. + +.. rubric:: NOTES: + +IDLE threads shall not block. A blocking IDLE thread results in undefined +system behaviour because the scheduler assume that at least one ready thread +exists. + +IDLE threads can be used to initialize the application, see configuration +option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. + +The BSP may have knowledge of the specific CPU model, system controller +logic, and peripheral buses, so a BSP-specific IDLE task may be capable of +turning components off to save power during extended periods of no task +activity. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *idle_body )( uintptr_t )``. + +.. Generated from spec:/acfg/if/idle-task-init-appl + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION + +.. _CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION: + +CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the user is assumed to +provide one or more initialization tasks. + +.. rubric:: DESCRIPTION: + +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. + +.. rubric:: NOTES: + +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 shall make itself preemptible and enter an idle +body loop. + +The IDLE task shall run at the lowest priority of all tasks in the system. + +If this configuration option is defined, then it is mandatory to configure a +user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, +otherwise a compile time error in the configuration file will occur. + +The application shall define at least one of the following configuration +options + +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, + +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or + +* ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +otherwise a compile time error in the configuration file will occur. + +If no Classic API initialization task and no POSIX API initialization thread +is configured, then no :ref:`GlobalConstruction` is performed. + +.. Generated from spec:/acfg/if/idle-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE + +.. _CONFIGURE_IDLE_TASK_STACK_SIZE: + +CONFIGURE_IDLE_TASK_STACK_SIZE +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_STACK_SIZE`, otherwise the default value is +defined by the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration option. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task stack size for an +IDLE task. + +.. rubric:: NOTES: + +In SMP configurations, there is one IDLE task per configured processor, see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the IDLE + task stack area calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +.. Generated from spec:/acfg/if/idle-task-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_STORAGE_SIZE +.. index:: IDLE task storage size + +.. _CONFIGURE_IDLE_TASK_STORAGE_SIZE: + +CONFIGURE_IDLE_TASK_STORAGE_SIZE +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the task storage area for each :term:`IDLE task` will allocated +from the RTEMS Workspace or through a custom IDLE task stack allocator. + +.. rubric:: DESCRIPTION: + +If this configuration option is specified, then the task storage areas for +the :term:`IDLE tasks <IDLE task>` are statically allocated by +``<rtems/confdefs.h>``. The value of this configuration option defines the +size in bytes of the task storage area of each IDLE task in the system. + +.. rubric:: NOTES: + +By default, the IDLE task storage areas are allocated from the RTEMS +Workspace. Applications which do not want to use a heap allocator can use +this configuration option to use statically allocated memory for the IDLE +task storage areas. The task storage area contains the task stack, the +thread-local storage, and the floating-point context on architectures with a +separate floating-point context. The size of the thread-local storage area +is defined at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` +configuration option. You have to estimate the actual thread-local storage +size if you want to use this configuration option. If the IDLE task stack +size would be less than the value defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration option, for example because the +thread-local storage size is larger than expected, then the system terminates +with the :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during +system initialization. + +The value of this configuration option is passed to +:ref:`InterfaceRTEMSTASKSTORAGESIZE` by ``<rtems/confdefs.h>`` to determine +the actual size of the statically allocated area to take +architecture-specific overheads into account. + +The + +* ``CONFIGURE_IDLE_TASK_STORAGE_SIZE``, and + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be greater than or equal to +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. diff --git a/c-user/config/index.rst b/c-user/config/index.rst new file mode 100644 index 0000000..b669ea2 --- /dev/null +++ b/c-user/config/index.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. index:: configuring a system +.. _Configuring a System: + +Configuring a System +******************** + +.. toctree:: + + introduction + intro + general + device-driver + classic-api + classic-init-task + posix-api + posix-init-thread + event-record + filesystem + bdbuf + task-stack-alloc + idle-task + scheduler-general + scheduler-clustered + face-technical-standard + mpci + libpci + ada + directives + obsolete diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst new file mode 100644 index 0000000..eb9c4c1 --- /dev/null +++ b/c-user/config/intro.rst @@ -0,0 +1,322 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2012 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Default Value Selection Philosophy +================================== + +The user should be aware that the defaults are intentionally set as low as +possible. By default, no application resources are configured. The +``<rtems/confdefs.h>`` file ensures that at least one application task or +thread is configured and that at least one of the initialization task/thread +tables is configured. + +.. _Sizing the RTEMS Workspace: + +Sizing the RTEMS Workspace +========================== + +The RTEMS Workspace is a user-specified block of memory reserved for use by +RTEMS. The application should NOT modify this memory. This area consists +primarily of the RTEMS data structures whose exact size depends upon the values +specified in the Configuration Table. In addition, task stacks and floating +point context areas are dynamically allocated from the RTEMS Workspace. + +The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace +automatically. It assumes that all tasks are floating point and that all will +be allocated the minimum stack space. This calculation includes the amount of +memory that will be allocated for internal use by RTEMS. The automatic +calculation may underestimate the workspace size truly needed by the +application, in which case one can use the :ref:`CONFIGURE_MEMORY_OVERHEAD` +macro to add a value to the estimate. See :ref:`Specify Memory Overhead` for +more details. + +The memory area for the RTEMS Workspace is determined by the BSP. In case the +RTEMS Workspace is too large for the available memory, then a fatal run-time +error occurs and the system terminates. + +The file ``<rtems/confdefs.h>`` will calculate the value of the +``work_space_size`` parameter of the Configuration Table. There are many +parameters the application developer can specify to help ``<rtems/confdefs.h>`` +in its calculations. Correctly specifying the application requirements via +parameters such as :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`CONFIGURE_MAXIMUM_TASKS` is critical for production software. + +For each class of objects, the allocation can operate in one of two ways. The +default way has an ceiling on the maximum number of object instances which can +concurrently exist in the system. Memory for all instances of that object class +is reserved at system initialization. The second way allocates memory for an +initial number of objects and increases the current allocation by a fixed +increment when required. Both ways allocate space from inside the RTEMS +Workspace. + +See :ref:`ConfigUnlimitedObjects` for more details about the second way, which +allows for dynamic allocation of objects and therefore does not provide +determinism. This mode is useful mostly for when the number of objects cannot +be determined ahead of time or when porting software for which you do not know +the object requirements. + +The space needed for stacks and for RTEMS objects will vary from one version of +RTEMS and from one target processor to another. Therefore it is safest to use +``<rtems/confdefs.h>`` and specify your application's requirements in terms of +the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as +is possible. The automatic estimates of space required will in general change +when: + +- a configuration parameter is changed, + +- task or interrupt stack sizes change, + +- the floating point attribute of a task changes, + +- task floating point attribute is altered, + +- RTEMS is upgraded, or + +- the target processor is changed. + +Failure to provide enough space in the RTEMS Workspace may result in fatal +run-time errors terminating the system. + +Potential Issues with RTEMS Workspace Size Estimation +===================================================== + +The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the +RTEMS Workspace. This estimate is only as accurate as the information given to +``<rtems/confdefs.h>`` and may be either too high or too low for a variety of +reasons. Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much +memory for RTEMS are: + +- All tasks/threads are assumed to be floating point. + +Conversely, there are many more reasons that the resource estimate could be too +low: + +- Task/thread stacks greater than minimum size must be accounted for explicitly + by developer. + +- Memory for messages is not included. + +- Device driver requirements are not included. + +- Network stack requirements are not included. + +- Requirements for add-on libraries are not included. + +In general, ``<rtems/confdefs.h>`` is very accurate when given enough +information. However, it is quite easy to use a library and forget to account +for its resources. + +Configuration Example +===================== + +In the following example, the configuration information for a system with a +single message queue, four (4) tasks, and a timeslice of fifty (50) +milliseconds is as follows: + +.. code-block:: c + + #include <bsp.h> + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */ + #define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */ + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_MAXIMUM_TASKS 4 + #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1 + #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE)) + #define CONFIGURE_INIT + #include <rtems/confdefs.h> + +In this example, only a few configuration parameters are specified. The impact +of these are as follows: + +- The example specified :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE` but did not + specify any additional parameters. This results in a configuration of an + application which will begin execution of a single initialization task named + ``Init`` which is non-preemptible and at priority one (1). + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, this + application is configured to have a clock tick device driver. Without a clock + tick device driver, RTEMS has no way to know that time is passing and will be + unable to support delays and wall time. Further configuration details about + time are provided. Per :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`CONFIGURE_TICKS_PER_TIMESLICE`, the user specified they wanted a clock + tick to occur each millisecond, and that the length of a timeslice would be + fifty (50) milliseconds. + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, the + application will include a console device driver. Although the console device + driver may support a combination of multiple serial ports and display and + keyboard combinations, it is only required to provide a single device named + ``/dev/console``. This device will be used for Standard Input, Output and + Error I/O Streams. Thus when + :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` is specified, implicitly + three (3) file descriptors are reserved for the Standard I/O Streams and + those file descriptors are associated with ``/dev/console`` during + initialization. All console devices are expected to support the + POSIX*termios* interface. + +- The example above specifies via :ref:`CONFIGURE_MAXIMUM_TASKS` that the + application requires a maximum of four (4) simultaneously existing Classic + API tasks. Similarly, by specifying :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`, + there may be a maximum of only one (1) concurrently existent Classic API + message queues. + +- The most surprising configuration parameter in this example is the use of + :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. Message buffer memory is allocated + from the RTEMS Workspace and must be accounted for. In this example, the + single message queue will have up to twenty (20) messages of type ``struct + USER_MESSAGE``. + +- The :ref:`CONFIGURE_INIT` constant must be defined in order to make + ``<rtems/confdefs.h>`` instantiate the configuration data structures. This + can only be defined in one source file per application that includes + ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple + times and linking errors produced. + +This example illustrates that parameters have default values. Among other +things, the application implicitly used the following defaults: + +- All unspecified types of communications and synchronization objects in the + Classic and POSIX Threads API have maximums of zero (0). + +- The filesystem will be the default filesystem which is the In-Memory File + System (IMFS). + +- The application will have the default number of priority levels. + +- The minimum task stack size will be that recommended by RTEMS for the target + architecture. + +.. _ConfigUnlimitedObjects: + +Unlimited Objects +================= + +In real-time embedded systems the RAM is normally a limited, critical resource +and dynamic allocation is avoided as much as possible to ensure predictable, +deterministic execution times. For such cases, see :ref:`Sizing the RTEMS +Workspace` for an overview of how to tune the size of the workspace. +Frequently when users are porting software to RTEMS the precise resource +requirements of the software is unknown. In these situations users do not need +to control the size of the workspace very tightly because they just want to get +the new software to run; later they can tune the workspace size as needed. + +The following object classes in the Classic API can be configured in unlimited +mode: + +- Barriers + +- Message Queues + +- Partitions + +- Periods + +- Ports + +- Regions + +- Semaphores + +- Tasks + +- Timers + +Additionally, the following object classes from the POSIX API can be configured +in unlimited mode: + +- Keys -- :c:func:`pthread_key_create` + +- Key Value Pairs -- :c:func:`pthread_setspecific` + +- Message Queues -- :c:func:`mq_open` + +- Named Semaphores -- :c:func:`sem_open` + +- Shared Memory -- :c:func:`shm_open` + +- Threads -- :c:func:`pthread_create` + +- Timers -- :c:func:`timer_create` + +.. warning:: + + The following object classes can *not* be configured in unlimited mode: + + - Drivers + + - File Descriptors + + - POSIX Queued Signals + + - User Extensions + +Due to the memory requirements of unlimited objects it is strongly recommended +to use them only in combination with the unified work areas. See :ref:`Separate +or Unified Work Areas` for more information on unified work areas. + +The following example demonstrates how the two simple configuration defines for +unlimited objects and unified works areas can replace many seperate +configuration defines for supported object classes: + +.. code-block:: c + + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_UNIFIED_WORK_AREAS + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_INIT + #include <rtems/confdefs.h> + +Users are cautioned that using unlimited objects is not recommended for +production software unless the dynamic growth is absolutely required. It is +generally considered a safer embedded systems programming practice to know the +system limits rather than experience an out of memory error at an arbitrary and +largely unpredictable time in the field. + +.. _ConfigUnlimitedObjectsClass: + +Unlimited Objects by Class +-------------------------- + +When the number of objects is not known ahead of time, RTEMS provides an +auto-extending mode that can be enabled individually for each object type by +using the macro :ref:`InterfaceRtemsResourceUnlimited`. This takes a value as a +parameter, and is used to set the object maximum number field in an API +Configuration table. The value is an allocation unit size. When RTEMS is +required to grow the object table it is grown by this size. The kernel will +return the object memory back to the RTEMS Workspace when an object is +destroyed. The kernel will only return an allocated block of objects to the +RTEMS Workspace if at least half the allocation size of free objects remain +allocated. RTEMS always keeps one allocation block of objects allocated. Here +is an example of using :c:func:`rtems_resource_unlimited`: + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) + +Object maximum specifications can be evaluated with the +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` macros. + +.. _ConfigUnlimitedObjectsDefault: + +Unlimited Objects by Default +---------------------------- + +To ease the burden of developers who are porting new software RTEMS also +provides the capability to make all object classes listed above operate in +unlimited mode in a simple manner. The application developer is only +responsible for enabling unlimited objects +(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size +(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`). + +.. code-block:: c + + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 diff --git a/c-user/config/introduction.rst b/c-user/config/introduction.rst new file mode 100644 index 0000000..8852a24 --- /dev/null +++ b/c-user/config/introduction.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/config/if/group + +.. _ApplicationConfigurationInformationIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/config/if/get-build-label +.. spec:/rtems/config/if/get-copyright-notice +.. spec:/rtems/config/if/get-target-hash +.. spec:/rtems/config/if/get-version-string +.. spec:/rtems/config/if/get-do-zero-of-workspace +.. spec:/rtems/config/if/get-idle-task-stack-size +.. spec:/rtems/config/if/get-idle-task +.. spec:/rtems/config/if/get-interrupt-stack-size +.. spec:/rtems/config/if/get-maximum-barriers +.. spec:/rtems/config/if/get-maximum-extensions +.. spec:/rtems/config/if/get-maximum-message-queues +.. spec:/rtems/config/if/get-maximum-partitions +.. spec:/rtems/config/if/get-maximum-periods +.. spec:/rtems/config/if/get-maximum-ports +.. spec:/rtems/config/if/get-maximum-processors +.. spec:/rtems/config/if/get-maximum-regions +.. spec:/rtems/config/if/get-maximum-semaphores +.. spec:/rtems/config/if/get-maximum-tasks +.. spec:/rtems/config/if/get-maximum-timers +.. spec:/rtems/config/if/get-microseconds-per-tick +.. spec:/rtems/config/if/get-milliseconds-per-tick +.. spec:/rtems/config/if/get-nanoseconds-per-tick +.. spec:/rtems/config/if/get-number-of-initial-extensions +.. spec:/rtems/config/if/get-stack-allocate-for-idle-hook +.. spec:/rtems/config/if/get-stack-allocate-hook +.. spec:/rtems/config/if/get-stack-allocate-init-hook +.. spec:/rtems/config/if/get-stack-allocator-avoids-work-space +.. spec:/rtems/config/if/get-stack-free-hook +.. spec:/rtems/config/if/get-stack-space-size +.. spec:/rtems/config/if/get-ticks-per-timeslice +.. spec:/rtems/config/if/get-unified-work-area +.. spec:/rtems/config/if/get-user-extension-table +.. spec:/rtems/config/if/get-user-multiprocessing-table +.. spec:/rtems/config/if/get-work-space-size +.. spec:/rtems/config/if/get-api-configuration +.. spec:/rtems/config/if/resource-is-unlimited +.. spec:/rtems/config/if/resource-maximum-per-allocation +.. spec:/rtems/config/if/resource-unlimited + +The application configuration information group provides an API to get the +configuration of an application. + +RTEMS must be configured for an application. This configuration encompasses a +variety of information including the length of each clock tick, the maximum +number of each information RTEMS object that can be created, the application +initialization tasks, the task scheduling algorithm to be used, and the device +drivers in the application. + +Although this information is contained in data structures that are used by +RTEMS at system initialization time, the data structures themselves must not be +generated by hand. RTEMS provides a set of macros system which provides a +simple standard mechanism to automate the generation of these structures. + +The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic +generation of system configuration. It is based on the idea of setting macros +which define configuration parameters of interest to the application and +defaulting or calculating all others. This variety of macros can automatically +produce all of the configuration data required for an RTEMS application. The +term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with the POSIX standard. + +For each configuration parameter in the configuration tables, the macro +corresponding to that field is discussed. The RTEMS Maintainers expect that all +systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +Some application configuration settings and other system parameters can be +queried by the application. The directives provided by the Application +Configuration Information are: + +* :ref:`InterfaceRtemsGetBuildLabel` - Gets the RTEMS build label. + +* :ref:`InterfaceRtemsGetCopyrightNotice` - Gets the RTEMS copyright notice. + +* :ref:`InterfaceRtemsGetTargetHash` - Gets the RTEMS target hash. + +* :ref:`InterfaceRtemsGetVersionString` - Gets the RTEMS version string. + +* :ref:`InterfaceRtemsConfigurationGetDoZeroOfWorkspace` - Indicates if the + RTEMS Workspace is configured to be zeroed during system initialization for + this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTaskStackSize` - Gets the IDLE task + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTask` - Gets the IDLE task body of + this application. + +* :ref:`InterfaceRtemsConfigurationGetInterruptStackSize` - Gets the interrupt + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumBarriers` - Gets the resource + number of :ref:`RTEMSAPIClassicBarrier` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumExtensions` - Gets the resource + number of :ref:`RTEMSAPIClassicUserExt` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumMessageQueues` - Gets the resource + number of :ref:`RTEMSAPIClassicMessage` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPartitions` - Gets the resource + number of :ref:`RTEMSAPIClassicPart` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPeriods` - Gets the resource + number of :ref:`RTEMSAPIClassicRatemon` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPorts` - Gets the resource number + of :ref:`RTEMSAPIClassicDPMem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumProcessors` - Gets the maximum + number of processors configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumRegions` - Gets the resource + number of :ref:`RTEMSAPIClassicRegion` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumSemaphores` - Gets the resource + number of :ref:`RTEMSAPIClassicSem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTasks` - Gets the resource number + of :ref:`RTEMSAPIClassicTasks` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTimers` - Gets the resource number + of :ref:`RTEMSAPIClassicTimer` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMicrosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMillisecondsPerTick` - Gets the number of + milliseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNanosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNumberOfInitialExtensions` - Gets the + number of initial extensions configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateForIdleHook` - Gets the task + stack allocator allocate hook used to allocate the stack of each :term:`IDLE + task` configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateHook` - Gets the task stack + allocator allocate hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateInitHook` - Gets the task + stack allocator initialization hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace` - + Indicates if the task stack allocator is configured to avoid the RTEMS + Workspace for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackFreeHook` - Gets the task stack + allocator free hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackSpaceSize` - Gets the configured + size in bytes of the memory space used to allocate thread stacks for this + application. + +* :ref:`InterfaceRtemsConfigurationGetTicksPerTimeslice` - Gets the clock ticks + per timeslice configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUnifiedWorkArea` - Indicates if the RTEMS + Workspace and C Program Heap are configured to be unified for this + application. + +* :ref:`InterfaceRtemsConfigurationGetUserExtensionTable` - Gets the initial + extensions table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUserMultiprocessingTable` - Gets the MPCI + configuration table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetWorkSpaceSize` - Gets the RTEMS Workspace + size in bytes configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` - Gets the Classic + API Configuration Table of this application. + +* :ref:`InterfaceRtemsResourceIsUnlimited` - Indicates if the resource is + unlimited. + +* :ref:`InterfaceRtemsResourceMaximumPerAllocation` - Gets the maximum number + per allocation of a resource number. + +* :ref:`InterfaceRtemsResourceUnlimited` - Augments the resource number so that + it indicates an unlimited resource. diff --git a/c-user/config/libpci.rst b/c-user/config/libpci.rst new file mode 100644 index 0000000..b62a56c --- /dev/null +++ b/c-user/config/libpci.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +PCI Library Configuration +========================= + +This section defines the system configuration parameters supported by +``rtems/confdefs.h`` related to configuring the PCI Library for RTEMS. + +The PCI Library startup behaviour can be configured in four different ways +depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined: + +.. index:: PCI_LIB_AUTO + +``PCI_LIB_AUTO`` + Used to enable the PCI auto configuration software. PCI will be automatically + probed, PCI buses enumerated, all devices and bridges will be initialized + using Plug & Play software routines. The PCI device tree will be populated + based on the PCI devices found in the system, PCI devices will be configured + by allocating address region resources automatically in PCI space according + to the BSP or host bridge driver set up. + +.. index:: PCI_LIB_READ + +``PCI_LIB_READ`` + Used to enable the PCI read configuration software. The current PCI + configuration is read to create the RAM representation (the PCI device tree) + of the PCI devices present. PCI devices are assumed to already have been + initialized and PCI buses enumerated, it is therefore required that a BIOS or + a boot loader has set up configuration space prior to booting into RTEMS. + +.. index:: PCI_LIB_STATIC + +``PCI_LIB_STATIC`` + Used to enable the PCI static configuration software. The user provides a PCI + tree with information how all PCI devices are to be configured at compile + time by linking in a custom ``struct pci_bus pci_hb`` tree. The static PCI + library will not probe PCI for devices, instead it will assume that all + devices defined by the user are present, it will enumerate the PCI buses and + configure all PCI devices in static configuration accordingly. Since probe + and allocation software is not needed the startup is faster, has smaller + footprint and does not require dynamic memory allocation. + +.. index:: PCI_LIB_PERIPHERAL + +``PCI_LIB_PERIPHERAL`` + Used to enable the PCI peripheral configuration. It is similar to + ``PCI_LIB_STATIC``, but it will never write the configuration to the PCI + devices since PCI peripherals are not allowed to access PCI configuration + space. + +Note that selecting ``PCI_LIB_STATIC`` or ``PCI_LIB_PERIPHERAL`` but not +defining ``pci_hb`` will reuslt in link errors. Note also that in these modes +Plug & Play is not performed. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst new file mode 100644 index 0000000..ab9d568 --- /dev/null +++ b/c-user/config/mpci.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-mpci + +Multiprocessing Configuration +============================= + +This section describes multiprocessing related configuration options. +The options are only used if RTEMS was built when the multiprocessing +build configuration option is enabled. The multiprocessing configuration +is distinct from the SMP configuration. Additionally, this class of +configuration options are only applicable if the configuration option +:ref:`CONFIGURE_MP_APPLICATION` is defined. The multiprocessing (MPCI) +support must not be confused with the SMP support. + +.. Generated from spec:/acfg/if/mp-extra-server-stack + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK + +.. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: + +CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK +----------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: NOTES: + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be small enough so that the MPCI + receive server stack area calculation carried out by ``<rtems/confdefs.h>`` + does not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +.. Generated from spec:/acfg/if/mp-appl + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_APPLICATION + +.. _CONFIGURE_MP_APPLICATION: + +CONFIGURE_MP_APPLICATION +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the multiprocessing services +are not initialized. + +.. rubric:: DESCRIPTION: + +This configuration option is defined to indicate that the application intends +to be part of a multiprocessing configuration. Additional configuration +options are assumed to be provided. + +.. rubric:: NOTES: + +This configuration option shall be undefined if the multiprocessing support +is not enabled (e.g. RTEMS was built without the multiprocessing build +configuration option enabled). Otherwise a compile time error in the +configuration file will occur. + +.. Generated from spec:/acfg/if/mp-max-global-objects + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS + +.. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: + +CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +concurrently active global objects in a multiprocessor system. + +.. rubric:: NOTES: + +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-max-nodes + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_MAXIMUM_NODES + +.. _CONFIGURE_MP_MAXIMUM_NODES: + +CONFIGURE_MP_MAXIMUM_NODES +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_NODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 2. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. + +.. rubric:: NOTES: + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-max-proxies + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_MAXIMUM_PROXIES + +.. _CONFIGURE_MP_MAXIMUM_PROXIES: + +CONFIGURE_MP_MAXIMUM_PROXIES +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. + +.. rubric:: NOTES: + +Since a proxy is used to represent a remote task/thread which is blocking +on this node. This configuration parameter reflects the maximum number of +remote tasks/threads which can be blocked on objects on this node, see +:ref:`MPCIProxies`. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/mp-mpci-table-pointer + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER + +.. _CONFIGURE_MP_MPCI_TABLE_POINTER: + +CONFIGURE_MP_MPCI_TABLE_POINTER +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``&MPCI_table``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the MPCI Configuration +Table. + +.. rubric:: NOTES: + +RTEMS provides a Shared Memory MPCI Device Driver which can be used on any +Multiprocessor System assuming the BSP provides the proper set of +supporting methods. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a pointer to +:c:type:`rtems_mpci_table`. + +.. Generated from spec:/acfg/if/mp-node-number + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MP_NODE_NUMBER + +.. _CONFIGURE_MP_NODE_NUMBER: + +CONFIGURE_MP_NODE_NUMBER +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_MP_NODE_NUMBER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``NODE_NUMBER``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the node number of this node +in a multiprocessor system. + +.. rubric:: NOTES: + +In the RTEMS Multiprocessing Test Suite, the node number is derived from +the Makefile variable ``NODE_NUMBER``. The same code is compiled with the +``NODE_NUMBER`` set to different values. The test programs behave +differently based upon their node number. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. diff --git a/c-user/config/obsolete.rst b/c-user/config/obsolete.rst new file mode 100644 index 0000000..77cc148 --- /dev/null +++ b/c-user/config/obsolete.rst @@ -0,0 +1,234 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Obsolete Configuration Options +============================== + +.. index:: CONFIGURE_BDBUF_BUFFER_COUNT + +CONFIGURE_BDBUF_BUFFER_COUNT +---------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_BDBUF_BUFFER_SIZE + +CONFIGURE_BDBUF_BUFFER_SIZE +--------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS + +CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS +-------------------------------------- + +This configuration option was introduced in RTEMS 4.9.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_ENABLE_GO + +CONFIGURE_ENABLE_GO +------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_GNAT_RTEMS + +CONFIGURE_GNAT_RTEMS +-------------------- + +This configuration option was present in all RTEMS versions since 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE + +CONFIGURE_HAS_OWN_CONFIGURATION_TABLE +------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_BDBUF_TABLE + +CONFIGURE_HAS_OWN_BDBUF_TABLE +----------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE + +CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE +------------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE + +.. _CONFIGURE_HAS_OWN_INIT_TASK_TABLE: + +CONFIGURE_HAS_OWN_INIT_TASK_TABLE +--------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. If you used this configuration option or you +think that there should be a way to configure more than one Classic API +initialization task, then please ask on the :r:list:`users`. + +.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE + +CONFIGURE_HAS_OWN_MOUNT_TABLE +----------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE + +CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE +--------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS + +CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS +-------------------------------- + +This configuration option was present in all RTEMS versions since 1998 and is +obsolete since RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`. + +.. index:: CONFIGURE_MAXIMUM_ADA_TASKS + +CONFIGURE_MAXIMUM_ADA_TASKS +--------------------------- + +This configuration option was present in all RTEMS versions since 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_MAXIMUM_DEVICES + +.. _CONFIGURE_MAXIMUM_DEVICES: + +CONFIGURE_MAXIMUM_DEVICES +------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS + +CONFIGURE_MAXIMUM_FAKE_ADA_TASKS +-------------------------------- + +This configuration option was present in all RTEMS versions since 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS + +CONFIGURE_MAXIMUM_GO_CHANNELS +----------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_GOROUTINES + +CONFIGURE_MAXIMUM_GOROUTINES +---------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES + +CONFIGURE_MAXIMUM_MRSP_SEMAPHORES +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS + +CONFIGURE_NUMBER_OF_TERMIOS_PORTS +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS + +CONFIGURE_MAXIMUM_POSIX_BARRIERS +-------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES + +CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES +------------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS + +CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS +------------------------------- + +This configuration option was introduced in RTEMS 4.10.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES + +CONFIGURE_MAXIMUM_POSIX_MUTEXES +------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS + +CONFIGURE_MAXIMUM_POSIX_RWLOCKS +------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS + +CONFIGURE_MAXIMUM_POSIX_SPINLOCKS +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE + +.. _CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE: + +CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE +----------------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. If you used this configuration option or you +think that there should be a way to configure more than one POSIX initialization +thread, then please ask on the :r:list:`users`. + +.. index:: CONFIGURE_SMP_APPLICATION + +CONFIGURE_SMP_APPLICATION +------------------------- + +This configuration option was introduced in RTEMS 4.11.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS + +CONFIGURE_SMP_MAXIMUM_PROCESSORS +-------------------------------- + +This configuration option was introduced in RTEMS 4.11.0 and is obsolete since +RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. + +.. index:: CONFIGURE_TERMIOS_DISABLED + +CONFIGURE_TERMIOS_DISABLED +-------------------------- + +This configuration option is obsolete since RTEMS 5.1. diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst new file mode 100644 index 0000000..f788c08 --- /dev/null +++ b/c-user/config/posix-api.rst @@ -0,0 +1,540 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-posix + +POSIX API Configuration +======================= + +This section describes configuration options related to the POSIX API. Most +POSIX API objects are available by default since RTEMS 5.1. The queued signals +and timers are only available if RTEMS was built with the enable POSIX +build configuration option. + +.. Generated from spec:/acfg/if/max-posix-keys + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS + +.. _CONFIGURE_MAXIMUM_POSIX_KEYS: + +CONFIGURE_MAXIMUM_POSIX_KEYS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEYS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Keys that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-key-value-pairs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS + +.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS: + +CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is +:ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * +( :ref:`CONFIGURE_MAXIMUM_TASKS` + +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ). + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of key +value pairs used by POSIX API Keys that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +A key value pair is created by :c:func:`pthread_setspecific` if the value +is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-message-queues + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES + +.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: + +CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Message Queues that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-queued-signals + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS + +.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: + +CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Queued Signals that can be concurrently active. + +.. rubric:: NOTES: + +Unlimited objects are not available for queued signals. + +Queued signals are only available if RTEMS was built with the POSIX API +build configuration option enabled. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. + +.. Generated from spec:/acfg/if/max-posix-semaphores + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES + +.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: + +CONFIGURE_MAXIMUM_POSIX_SEMAPHORES +---------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Named Semaphores that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +Named semaphores are created with :c:func:`sem_open`. Semaphores +initialized with :c:func:`sem_init` are not affected by this +configuration option since the storage space for these semaphores is +user-provided. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-shms + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_SHMS + +.. _CONFIGURE_MAXIMUM_POSIX_SHMS: + +CONFIGURE_MAXIMUM_POSIX_SHMS +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SHMS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Shared Memory objects that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +.. Generated from spec:/acfg/if/max-posix-threads + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS + +.. _CONFIGURE_MAXIMUM_POSIX_THREADS: + +CONFIGURE_MAXIMUM_POSIX_THREADS +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Threads that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +This calculations for the required memory in the RTEMS Workspace for threads +assume that each thread has a minimum stack size and has floating point +support enabled. The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify thread stack requirements **above** the minimum size required. + +The maximum number of Classic API Tasks is specified by +:ref:`CONFIGURE_MAXIMUM_TASKS`. + +All POSIX threads have floating point enabled. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/max-posix-timers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS + +.. _CONFIGURE_MAXIMUM_POSIX_TIMERS: + +CONFIGURE_MAXIMUM_POSIX_TIMERS +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number of POSIX +API Timers that can be concurrently active. + +.. rubric:: NOTES: + +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. + +Timers are only available if RTEMS was built with the POSIX API build +configuration option enabled. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option 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. + +* The value of the configuration option may be defined through + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` + satisfies all other constraints of the configuration option. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. + +.. Generated from spec:/acfg/if/min-posix-thread-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +.. index:: minimum POSIX thread stack size + +.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE: + +CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +----------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is two times the value of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum stack size in +bytes for every POSIX thread in the system. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst new file mode 100644 index 0000000..ee09ba0 --- /dev/null +++ b/c-user/config/posix-init-thread.rst @@ -0,0 +1,156 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-posixinit + +POSIX Initialization Thread Configuration +========================================= + +This section describes configuration options related to the POSIX +initialization thread. + +.. Generated from spec:/acfg/if/posix-init-thread-entry-point + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT + +.. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: + +CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``POSIX_Init``. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the entry point of the +POSIX API initialization thread. + +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *entry_point )( void * )``. + +.. Generated from spec:/acfg/if/posix-init-thread-stack-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE + +.. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: + +CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE +-------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the thread stack size of the +POSIX API initialization thread. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +.. Generated from spec:/acfg/if/posix-init-thread-table + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE + +.. _CONFIGURE_POSIX_INIT_THREAD_TABLE: + +CONFIGURE_POSIX_INIT_THREAD_TABLE +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then exactly one POSIX +initialization thread is configured. + +.. rubric:: NOTES: + +The application shall define at least one of the following configuration +options + +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, + +* ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or + +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` + +otherwise a compile time error in the configuration file will occur. + +If no Classic API initialization task is configured, then the POSIX API +initialization thread performs the :ref:`GlobalConstruction`. diff --git a/c-user/config/scheduler-clustered.rst b/c-user/config/scheduler-clustered.rst new file mode 100644 index 0000000..47e0f4a --- /dev/null +++ b/c-user/config/scheduler-clustered.rst @@ -0,0 +1,220 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. _ConfigurationSchedulersClustered: + +Clustered Scheduler Configuration +================================= + +This section describes configuration options related to clustered scheduling. +A clustered scheduler configuration is optional. It is an advanced +configuration area and only necessary in specific circumstances. + +Clustered scheduling helps to control the worst-case latencies in a +multiprocessor system (SMP). The goal is to reduce the amount of shared state +in the system and thus prevention of lock contention. Modern multiprocessor +systems tend to have several layers of data and instruction caches. With +clustered scheduling it is possible to honour the cache topology of a system +and thus avoid expensive cache synchronization traffic. + +We have clustered scheduling in case the set of processors of a system is +partitioned into non-empty pairwise-disjoint subsets. These subsets are called +clusters. Clusters with a cardinality of one are partitions. Each cluster is +owned by exactly one scheduler. + +In order to use clustered scheduling the application designer has to answer two +questions. + +#. How is the set of processors partitioned into clusters? + +#. Which scheduler algorithm is used for which cluster? + +The schedulers are statically configured. + +Configuration Step 1 - Scheduler Algorithms +------------------------------------------- + +Firstly, the application must select which scheduling algorithms are available +with the following defines + +- :ref:`CONFIGURE_SCHEDULER_EDF_SMP <CONFIGURE_SCHEDULER_EDF_SMP>`, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP>`, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_SMP>`, and + +- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP <CONFIGURE_SCHEDULER_SIMPLE_SMP>`. + +This is necessary to calculate the per-thread overhead introduced by the +scheduler algorithms. After these definitions the configuration file must +``#include <rtems/scheduler.h>`` to have access to scheduler-specific +configuration macros. + +It is possible to make more than one scheduler algorithm available to the +application. For example a :ref:`Simple Priority SMP Scheduler +<SchedulerSMPPrioritySimple>` could be used in a partition for low latency +tasks in addition to an :ref:`EDF SMP Scheduler <SchedulerSMPEDF>` for a +general-purpose cluster. Since the per-thread overhead depends on the +scheduler algorithm only the scheduler algorithms used by the application +should be configured. + +Configuration Step 2 - Schedulers +--------------------------------- + +Each scheduler needs some data structures. Use the following macros to create +the scheduler data structures for a particular scheduler identified in the +configuration by ``name``. + +- ``RTEMS_SCHEDULER_EDF_SMP(name)``, + +- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``, + +- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and + +- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``. + +The ``name`` parameter is used as part of a designator for scheduler-specific +data structures, so the usual C/C++ designator rules apply. This ``name`` is +not the scheduler object name. Additional parameters are scheduler-specific. + +.. _ConfigurationSchedulerTable: + +Configuration Step 3 - Scheduler Table +-------------------------------------- + +The schedulers are registered in the system via the scheduler table. To +populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a +list of the following scheduler table entry initializers + +- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``, + +- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``, + +- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and + +- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``. + +The ``name`` parameter must correspond to the parameter defining the scheduler +data structures of configuration step 2. The ``obj_name`` determines the +scheduler object name and can be used in :ref:`rtems_scheduler_ident() +<rtems_scheduler_ident>` to get the scheduler object identifier. The scheduler +index is defined by the index of the scheduler table. It is a configuration +error to add a scheduler multiple times to the scheduler table. + +Configuration Step 4 - Processor to Scheduler Assignment +-------------------------------------------------------- + +The last step is to define which processor uses which scheduler. For this +purpose a scheduler assignment table must be defined. The entry count of this +table must be equal to the configured maximum processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`). A +processor assignment to a scheduler can be optional or mandatory. The boot +processor must have a scheduler assigned. In case the system needs more +mandatory processors than available then a fatal run-time error will occur. To +specify the scheduler assignments define +``CONFIGURE_SCHEDULER_ASSIGNMENTS`` to a list of + +- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and + +- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` + +macros. The ``scheduler_index`` parameter must be a valid index into the +scheduler table defined by configuration step 3. The ``attr`` parameter +defines the scheduler assignment attributes. By default, a scheduler +assignment to a processor is optional. For the scheduler assignment attribute +use one of the mutually exclusive variants + +- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``, + +- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and + +- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``. + +It is possible to add/remove processors to/from schedulers at run-time, see +:ref:`rtems_scheduler_add_processor() <rtems_scheduler_add_processor>` and +:ref:`rtems_scheduler_remove_processor() <rtems_scheduler_remove_processor>`. + +Configuration Example +--------------------- + +The following example shows a scheduler configuration for a hypothetical +product using two chip variants. One variant has four processors which is used +for the normal product line and another provides eight processors for the +high-performance product line. The first processor performs hard-real time +control of actuators and sensors. The second processor is not used by RTEMS at +all and runs a Linux instance to provide a graphical user interface. The +additional processors are used for a worker thread pool to perform data +processing operations. + +The processors managed by RTEMS use two Deterministic Priority SMP schedulers +capable of dealing with 256 priority levels. The scheduler with index zero has +the name ``"IO "``. The scheduler with index one has the name ``"WORK"``. The +scheduler assignments of the first, third and fourth processor are mandatory, +so the system must have at least four processors, otherwise a fatal run-time +error will occur during system startup. The processor assignments for the +fifth up to the eighth processor are optional so that the same application can +be used for the normal and high-performance product lines. The second +processor has no scheduler assigned and runs Linux. A hypervisor will ensure +that the two systems cannot interfere in an undesirable way. + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_PROCESSORS 8 + #define CONFIGURE_MAXIMUM_PRIORITY 255 + + /* Configuration Step 1 - Scheduler Algorithms */ + #define CONFIGURE_SCHEDULER_PRIORITY_SMP + #include <rtems/scheduler.h> + + /* Configuration Step 2 - Schedulers */ + RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); + RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); + + /* Configuration Step 3 - Scheduler Table */ + #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \ + RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ + io, \ + rtems_build_name('I', 'O', ' ', ' ') \ + ), \ + RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ + work, \ + rtems_build_name('W', 'O', 'R', 'K') \ + ) + + /* Configuration Step 4 - Processor to Scheduler Assignment */ + #define CONFIGURE_SCHEDULER_ASSIGNMENTS \ + RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL) + +Configuration Errors +-------------------- + +In case one of the scheduler indices in ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` +is invalid a link-time error will occur with an undefined reference to +``RTEMS_SCHEDULER_INVALID_INDEX``. + +Some fatal errors may occur in case of scheduler configuration inconsistencies +or a lack of processors on the system. The fatal source is +``RTEMS_FATAL_SOURCE_SMP``. + +- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor + must have a scheduler assigned. + +- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory + processor beyond the range of physically or virtually available processors. + The processor demand must be reduced for this system. + +- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory + processor failed during system initialization. The system may not have this + processor at all or it could be a problem with a boot loader for example. + Check the ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` definition. + +- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed + to start multitasking on a processor with no scheduler assigned. diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst new file mode 100644 index 0000000..d347d6b --- /dev/null +++ b/c-user/config/scheduler-general.rst @@ -0,0 +1,814 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 2010 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-schedgeneral + +General Scheduler Configuration +=============================== + +This section describes configuration options related to selecting a +scheduling algorithm for an application. A scheduler configuration is optional +and only necessary in very specific circumstances. A normal application +configuration does not need any of the configuration options described in this +section. + +By default, the :ref:`SchedulerPriority` +algorithm is used in uniprocessor configurations. In case SMP is enabled and +the configured maximum processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`) is greater +than one, then the +:ref:`SchedulerSMPEDF` +is selected as the default scheduler algorithm. + +For the schedulers provided by RTEMS (see :ref:`RTEMSAPIClassicScheduler`), the +configuration is straightforward. All that is required is to define the +configuration option which specifies which scheduler you want for in your +application. + +The pluggable scheduler interface also enables the user to provide their own +scheduling algorithm. If you choose to do this, you must define multiple +configuration option. + +.. Generated from spec:/acfg/if/cbs-max-servers + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_CBS_MAXIMUM_SERVERS + +.. _CONFIGURE_CBS_MAXIMUM_SERVERS: + +CONFIGURE_CBS_MAXIMUM_SERVERS +----------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_CBS_MAXIMUM_SERVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum number Constant +Bandwidth Servers that can be concurrently active. + +.. rubric:: NOTES: + +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_SCHEDULER_CBS` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option 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. + +.. Generated from spec:/acfg/if/max-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_PRIORITY +.. index:: maximum priority +.. index:: number of priority levels + +.. _CONFIGURE_MAXIMUM_PRIORITY: + +CONFIGURE_MAXIMUM_PRIORITY +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 255. + +.. rubric:: DESCRIPTION: + +For the following schedulers + +* :ref:`SchedulerPriority`, which is the default in uniprocessor + configurations and can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, + +* :ref:`SchedulerSMPPriority` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and + +* :ref:`SchedulerSMPPriorityAffinity` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option + +this configuration option specifies the maximum numeric priority of any task +for these schedulers and one less that the number of priority levels for +these schedulers. For all other schedulers provided by RTEMS, this +configuration option has no effect. + +.. rubric:: NOTES: + +The numerically greatest priority is the logically lowest priority in the +system and will thus be used by the IDLE task. + +Priority zero is reserved for internal use by RTEMS and is not available to +applications. + +Reducing the number of priorities through this configuration option reduces +the amount of memory allocated by the schedulers listed above. These +schedulers use a chain control structure per priority and this structure +consists of three pointers. On a 32-bit architecture, the allocated memory +is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 +priority levels (default), 48 bytes for 4 priority levels +(``CONFIGURE_MAXIMUM_PRIORITY == 3``). + +The default value is 255, because RTEMS shall support 256 priority levels to +be compliant with various standards. These priorities range from 0 to 255. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be equal to 3, 7, 31, 63, 127, or +255. + +.. Generated from spec:/acfg/if/scheduler-assignments + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_ASSIGNMENTS + +.. _CONFIGURE_SCHEDULER_ASSIGNMENTS: + +CONFIGURE_SCHEDULER_ASSIGNMENTS +------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_ASSIGNMENTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value of this configuration option is computed so that the +default scheduler is assigned to each configured processor (up to 32). + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the initial +scheduler to processor assignments. + +.. rubric:: NOTES: + +Where the system was built with SMP support enabled, this configuration +option is evaluated, otherwise it is ignored. + +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_ASSIGN( scheduler_index, attributes )`` + + * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` + + The ``scheduler_index`` macro parameter shall be a valid index of the + scheduler table defined by the :ref:`CONFIGURE_SCHEDULER_TABLE_ENTRIES` + configuration option. + + The ``attributes`` macro parameter shall be set to exactly one of the + following constants: + + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY`` + + * ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL`` + +* The value of the configuration option shall be a list of exactly + :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. + +.. Generated from spec:/acfg/if/scheduler-cbs + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_CBS + +.. _CONFIGURE_SCHEDULER_CBS: + +CONFIGURE_SCHEDULER_CBS +----------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_CBS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerCBS` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +.. Generated from spec:/acfg/if/scheduler-edf + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_EDF + +.. _CONFIGURE_SCHEDULER_EDF: + +CONFIGURE_SCHEDULER_EDF +----------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerEDF` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +.. Generated from spec:/acfg/if/scheduler-edf-smp + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_EDF_SMP + +.. _CONFIGURE_SCHEDULER_EDF_SMP: + +CONFIGURE_SCHEDULER_EDF_SMP +--------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPEDF` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +This scheduler algorithm is the default in SMP configurations if +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +greater than one. + +.. Generated from spec:/acfg/if/scheduler-name + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_NAME + +.. _CONFIGURE_SCHEDULER_NAME: + +CONFIGURE_SCHEDULER_NAME +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is + +* ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, + +* ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, + +* ``"MPD "`` for the :ref:`SchedulerSMPPriority`, + +* ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, + +* ``"UCBS"`` for the :ref:`SchedulerCBS`, + +* ``"UEDF"`` for the :ref:`SchedulerEDF`, + +* ``"UPD "`` for the :ref:`SchedulerPriority`, and + +* ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the name of the default +scheduler. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +Schedulers can be identified via :ref:`InterfaceRtemsSchedulerIdent`. + +Use :ref:`InterfaceRtemsBuildName` to define the scheduler name. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. + +.. Generated from spec:/acfg/if/scheduler-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_PRIORITY + +.. _CONFIGURE_SCHEDULER_PRIORITY: + +CONFIGURE_SCHEDULER_PRIORITY +---------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerPriority` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +This scheduler algorithm is the default when +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +exactly one. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-priority-affinity-smp + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: + +CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP +----------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriorityAffinity` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-priority-smp + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_SMP: + +CONFIGURE_SCHEDULER_PRIORITY_SMP +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriority` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +The memory allocated for this scheduler depends on the +:ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. Generated from spec:/acfg/if/scheduler-simple + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_SIMPLE + +.. _CONFIGURE_SCHEDULER_SIMPLE: + +CONFIGURE_SCHEDULER_SIMPLE +-------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerPrioritySimple` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. + +.. Generated from spec:/acfg/if/scheduler-simple-smp + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP + +.. _CONFIGURE_SCHEDULER_SIMPLE_SMP: + +CONFIGURE_SCHEDULER_SIMPLE_SMP +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPPrioritySimple` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. + +.. Generated from spec:/acfg/if/scheduler-strong-apa + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_STRONG_APA + +.. _CONFIGURE_SCHEDULER_STRONG_APA: + +CONFIGURE_SCHEDULER_STRONG_APA +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_STRONG_APA`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Strong APA algorithm +is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. + +This scheduler algorithm is not correctly implemented. Do not use it. + +.. Generated from spec:/acfg/if/scheduler-table-entries + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_TABLE_ENTRIES + +.. _CONFIGURE_SCHEDULER_TABLE_ENTRIES: + +CONFIGURE_SCHEDULER_TABLE_ENTRIES +--------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value of this configuration option is the definition of exactly +one table entry for the configured scheduler. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +configured schedulers. + +.. rubric:: NOTES: + +Schedulers registered in the scheduler table by this configuration option are +available to the application. The scheduler table entry index defines the +index of the scheduler. + +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_TABLE_CBS( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name )`` + + * ``RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name )`` + + The ``name`` macro parameter shall be the name associated with the scheduler + data structures, see :ref:`ConfigurationSchedulersClustered`. + + The ``obj_name`` macro parameter shall be the scheduler object name. It is + recommended to define the scheduler object name through + :ref:`InterfaceRtemsBuildName`. + +* Where the system was build with SMP support enabled, the table shall have one + or more entries, otherwise it shall have exactly one entry. + +.. Generated from spec:/acfg/if/scheduler-user + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SCHEDULER_USER + +.. _CONFIGURE_SCHEDULER_USER: + +CONFIGURE_SCHEDULER_USER +------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_USER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the user shall provide a +scheduler algorithm to the application. + +.. rubric:: 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 shall define +``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own +scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the +following additional macros shall be defined: + +* ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of + the scheduler data structures of the user scheduler. + +* ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler + table entry initializer for the user scheduler. + +* ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of + the per-thread information of the user scheduler. + +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 +``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on +the configuration macros, please examine +``cpukit/include/rtems/confdefs/scheduler.h`` for how these are defined for +the Deterministic Priority Scheduler. diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst new file mode 100644 index 0000000..c79833f --- /dev/null +++ b/c-user/config/task-stack-alloc.rst @@ -0,0 +1,314 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-stackalloc + +Task Stack Allocator Configuration +================================== + +This section describes configuration options related to the task stack +allocator. RTEMS allows the application or BSP to define its own allocation +and deallocation methods for task stacks. This can be used to place task stacks +in special areas of memory or to utilize a Memory Management Unit so that stack +overflows are detected in hardware. + +.. Generated from spec:/acfg/if/task-stack-allocator + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR +.. index:: task stack allocator + +.. _CONFIGURE_TASK_STACK_ALLOCATOR: + +CONFIGURE_TASK_STACK_ALLOCATOR +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Allocate``, which indicates that task +stacks will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +allocate handler. + +.. rubric:: NOTES: + +A correctly configured system shall configure the following to be consistent: + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` + +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( size_t )``. + +.. Generated from spec:/acfg/if/task-stack-no-workspace + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: + +CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE +------------------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. Generated from spec:/acfg/if/task-stack-allocator-for-idle + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +.. index:: task stack allocator for IDLE tasks + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE: + +CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +By default, the IDLE task storage area will be allocated from the RTEMS +Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is the address for the stack allocator +allocate handler used to allocate the task storage area of each +:term:`IDLE task`. + +.. rubric:: NOTES: + +This configuration option is independent of the other thread stack allocator +configuration options. It is assumed that any memory allocated for the task +storage area of an :term:`IDLE task` will not be from the RTEMS +Workspace. + +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. + +The + +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be defined to a valid function + pointer of the type ``void *( *allocate )( uint32_t, size_t * )``. + +* The IDLE task stack allocator shall return a pointer to the allocated memory + area or terminate the system with a fatal error if the allocation request + cannot be satisfied. + +* The IDLE task stack allocator may increase the size of the allocated memory + area. + +.. Generated from spec:/acfg/if/task-stack-allocator-init + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: + +CONFIGURE_TASK_STACK_ALLOCATOR_INIT +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +initialization handler. + +.. rubric:: NOTES: + +A correctly configured system shall configure the following to be consistent: + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` + +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *initialize )( size_t )`` or to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. + +.. Generated from spec:/acfg/if/task-stack-deallocator + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR +.. index:: task stack deallocator + +.. _CONFIGURE_TASK_STACK_DEALLOCATOR: + +CONFIGURE_TASK_STACK_DEALLOCATOR +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +deallocate handler. + +.. rubric:: NOTES: + +A correctly configured system shall configure the following to be consistent: + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` + +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. + +.. Generated from spec:/acfg/if/task-stack-from-alloc + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR +.. index:: task stack allocator + +.. _CONFIGURE_TASK_STACK_FROM_ALLOCATOR: + +CONFIGURE_TASK_STACK_FROM_ALLOCATOR +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is a macro which supports the system heap allocator. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to calculate the task stack +space size. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a macro which accepts +exactly one parameter and returns an unsigned integer. The parameter will be +an allocation size and the macro shall return this size plus the overhead of +the allocator to manage an allocation request for this size. |