diff options
| author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-03-27 12:53:09 +0100 |
|---|---|---|
| committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-04-01 07:49:12 +0200 |
| commit | 7bad8940ad05ea1e3b41745012a0dc5391275477 (patch) | |
| tree | 417974a7eedf1b89c709648c36e1d234934b9ff7 | |
| parent | c-user: Avoid self references (diff) | |
| download | rtems-docs-7bad8940ad05ea1e3b41745012a0dc5391275477.tar.bz2 | |
c-user: Use new template for integer config opts
Try to bring all descriptions up to date. Add cross-references to
several options. Clarify configuration value constraints.
Use this template also for initializer type options.
Close #3901.
| -rw-r--r-- | c-user/config/bdbuf.rst | 192 | ||||
| -rw-r--r-- | c-user/config/bsp-related.rst | 179 | ||||
| -rw-r--r-- | c-user/config/classic-api.rst | 317 | ||||
| -rw-r--r-- | c-user/config/classic-init-task.rst | 134 | ||||
| -rw-r--r-- | c-user/config/device-driver.rst | 92 | ||||
| -rw-r--r-- | c-user/config/event-record.rst | 32 | ||||
| -rw-r--r-- | c-user/config/filesystem.rst | 39 | ||||
| -rw-r--r-- | c-user/config/general.rst | 376 | ||||
| -rw-r--r-- | c-user/config/idle-task.rst | 67 | ||||
| -rw-r--r-- | c-user/config/mpci.rst | 79 | ||||
| -rw-r--r-- | c-user/config/posix-api.rst | 261 | ||||
| -rw-r--r-- | c-user/config/posix-init-thread.rst | 54 | ||||
| -rw-r--r-- | c-user/config/scheduler-general.rst | 56 | ||||
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 73 |
14 files changed, 1203 insertions, 748 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 84b1d33..604f887 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Block Device Cache Configuration @@ -44,17 +45,23 @@ CONFIGURE_BDBUF_BUFFER_MAX_SIZE CONSTANT: ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - It must be positive and an integral multiple of the buffer minimum size. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 4096 bytes. + The default value is 4096. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. DESCRIPTION: - Defines the maximum size of a buffer in bytes. + The value of this configuration option defines the maximum size of a buffer + in bytes. NOTES: None. @@ -69,17 +76,19 @@ CONFIGURE_BDBUF_BUFFER_MIN_SIZE CONSTANT: ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 512 bytes. + The default value is 512. + +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. DESCRIPTION: - Defines the minimum size of a buffer in bytes. + The value of this configuration option defines the minimum size of a buffer + in bytes. NOTES: None. @@ -94,17 +103,19 @@ CONFIGURE_BDBUF_CACHE_MEMORY_SIZE CONSTANT: ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 32768 bytes. + The default value is 32768. + +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``SIZE_MAX``. DESCRIPTION: - Size of the cache memory in bytes. + The value of this configuration option defines the size of the cache memory + in bytes. NOTES: None. @@ -119,17 +130,19 @@ CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS CONSTANT: ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - Defines the maximum blocks per read-ahead request. + The value of this configuration option defines the maximum blocks per + read-ahead request. NOTES: A value of 0 disables the read-ahead task (default). The read-ahead task @@ -146,17 +159,19 @@ CONFIGURE_BDBUF_MAX_WRITE_BLOCKS CONSTANT: ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 16. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - Defines the maximum blocks per write request. + The value of this configuration option defines the maximum blocks per write + request. NOTES: None. @@ -171,17 +186,18 @@ CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY CONSTANT: ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` -DATA TYPE: - Task priority (``rtems_task_priority``). - -RANGE: - Valid task priority. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 15. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid Classic API task + priority. The set of valid task priorities is scheduler-specific. + DESCRIPTION: - Defines the read-ahead task priority. + The value of this configuration option defines the read-ahead task priority. NOTES: None. @@ -196,17 +212,29 @@ CONFIGURE_BDBUF_TASK_STACK_SIZE CONSTANT: ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. + The default value is ``RTEMS_MINIMUM_STACK_SIZE``. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. DESCRIPTION: - Defines the task stack size of the Block Device Cache tasks in bytes. + The value of this configuration option defines the task stack size of the + Block Device Cache tasks in bytes. NOTES: None. @@ -221,17 +249,19 @@ CONFIGURE_SWAPOUT_BLOCK_HOLD CONSTANT: ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 1000 milliseconds. + The default value is 1000. + +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. DESCRIPTION: - Defines the swapout task maximum block hold time in milliseconds. + The value of this configuration option defines the swapout task maximum block + hold time in milliseconds. NOTES: None. @@ -246,17 +276,19 @@ CONFIGURE_SWAPOUT_SWAP_PERIOD CONSTANT: ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 250 milliseconds. + The default value is 250. + +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. DESCRIPTION: - Defines the swapout task swap period in milliseconds. + The value of this configuration option defines the swapout task swap period + in milliseconds. NOTES: None. @@ -271,17 +303,18 @@ CONFIGURE_SWAPOUT_TASK_PRIORITY CONSTANT: ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -DATA TYPE: - Task priority (``rtems_task_priority``). - -RANGE: - Valid task priority. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 15. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid Classic API task + priority. The set of valid task priorities is scheduler-specific. + DESCRIPTION: - Defines the swapout task priority. + The value of this configuration option defines the swapout task priority. NOTES: None. @@ -296,17 +329,19 @@ CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY CONSTANT: ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` -DATA TYPE: - Task priority (``rtems_task_priority``). - -RANGE: - Valid task priority. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 15. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid Classic API task + priority. The set of valid task priorities is scheduler-specific. + DESCRIPTION: - Defines the swapout worker task priority. + The value of this configuration option defines the swapout worker task + priority. NOTES: None. @@ -321,17 +356,18 @@ CONFIGURE_SWAPOUT_WORKER_TASKS CONSTANT: ``CONFIGURE_SWAPOUT_WORKER_TASKS`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - Defines the swapout worker task count. + The value of this configuration option defines the swapout worker task count. NOTES: None. diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst index 62fcda4..ba5ca93 100644 --- a/c-user/config/bsp-related.rst +++ b/c-user/config/bsp-related.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) BSP Related Configuration Options @@ -20,24 +21,30 @@ BSP_IDLE_TASK_BODY CONSTANT: ``BSP_IDLE_TASK_BODY`` -DATA TYPE: - Function pointer. - -RANGE: - Undefined or valid function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This option is BSP specific. + The default value is BSP-specific. + +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void *( *idle_body )( uintptr_t )``. DESCRIPTION: - If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and - ``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this - BSP specific idle task body will be used. + If + + * this configuration option is defined by the BSP + + * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, + + then the value of this configuration option defines the default value of + :ref:`CONFIGURE_IDLE_TASK_BODY`. NOTES: As it has knowledge of the specific CPU model, system controller logic, and - peripheral buses, a BSP specific IDLE task may be capable of turning - components off to save power during extended periods of no task activity + peripheral buses, a BSP-specific IDLE task may be capable of turning + components off to save power during extended periods of no task activity. .. index:: BSP_IDLE_TASK_STACK_SIZE @@ -49,30 +56,35 @@ BSP_IDLE_TASK_STACK_SIZE CONSTANT: ``BSP_IDLE_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Undefined or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - This option is BSP specific. + The default value is BSP-specific. -DESCRIPTION: - If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application, then - this BSP suggested idle task stack size will be used. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: -NOTES: - The order of precedence for configuring the IDLE task stack size is: + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. + + * It 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``. - - RTEMS default minimum stack size. +DESCRIPTION: + If - - If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``. + * this configuration option is defined by the BSP - - If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``. + * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - - If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``. + then the value of this configuration option defines the default value of + :ref:`CONFIGURE_IDLE_TASK_SIZE`. + +NOTES: + None. .. index:: BSP_INITIAL_EXTENSION @@ -84,22 +96,29 @@ BSP_INITIAL_EXTENSION CONSTANT: ``BSP_INITIAL_EXTENSION`` -DATA TYPE: - List of user extension initializers (``rtems_extensions_table``). - -RANGE: - Undefined or a list of user extension initializers. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This option is BSP specific. + The default value is BSP-specific. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a list of initializers for + structures of type :c:type:`rtems_extensions_table`. DESCRIPTION: - If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific - initial extension will be placed as the last entry in the initial extension - table. + If + + * this configuration option is defined by the BSP + + * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, + + then the value of this configuration option is used to initialize the table + of initial user extensions. NOTES: - None. + The value of this configuration option is placed after the entries of all + other initial user extensions. .. index:: BSP_INTERRUPT_STACK_SIZE @@ -111,52 +130,38 @@ BSP_INTERRUPT_STACK_SIZE CONSTANT: ``BSP_INTERRUPT_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Undefined or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - This option is BSP specific. - -DESCRIPTION: - If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and - ``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application, then - this BSP specific interrupt stack size will be used. + The default value is BSP-specific. -NOTES: - None. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: -.. index:: BSP_MAXIMUM_DEVICES + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. -.. _BSP_MAXIMUM_DEVICES: + * It 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``. -BSP_MAXIMUM_DEVICES -------------------- - -CONSTANT: - ``BSP_MAXIMUM_DEVICES`` + * It shall be aligned according to + ``CPU_INTERRUPT_STACK_ALIGNMENT``. -DATA TYPE: - Unsigned integer (``size_t``). +DESCRIPTION: + If -RANGE: - Undefined or positive. + * this configuration option is defined by the BSP -DEFAULT VALUE: - This option is BSP specific. + * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, -DESCRIPTION: - If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and - ``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application, then this - BSP specific maximum device count will be used. + then the value of this configuration option defines the default value of + :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. NOTES: - This option is specific to the device file system (devFS) and should not be - confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter - only impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when - ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. + None. .. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS @@ -168,26 +173,30 @@ CONFIGURE_BSP_PREREQUISITE_DRIVERS CONSTANT: ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` -DATA TYPE: - List of device driver initializers (``rtems_driver_address_table``). - -RANGE: - Undefined or array of device drivers. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This option is BSP specific. + The default value is BSP-specific. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a list of initializers for + structures of type :c:type:`rtems_extensions_table`. DESCRIPTION: - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device - drivers it needs to include in the Device Driver Table. This should be - defined to the set of device driver entries that will be placed in the - table at the *FRONT* of the Device Driver Table and initialized before any - other drivers *INCLUDING* any application prerequisite drivers. + If + + * this configuration option is defined by the BSP + + * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, + + then the value of this configuration option is used to initialize the table + of initial user extensions. NOTES: - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to - configure common infrastructure such as bus controllers or probe for - devices. + The value of this configuration option is placed before the entries of all + other initial user extensions (including + :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). .. index:: CONFIGURE_DISABLE_BSP_SETTINGS diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst index 3647d05..bd2fa00 100644 --- a/c-user/config/classic-api.rst +++ b/c-user/config/classic-api.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Classic API Configuration @@ -17,21 +18,36 @@ CONFIGURE_MAXIMUM_BARRIERS CONSTANT: ``CONFIGURE_MAXIMUM_BARRIERS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API - Barriers that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Barriers that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES @@ -43,23 +59,38 @@ CONFIGURE_MAXIMUM_MESSAGE_QUEUES CONSTANT: ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API - Message Queues that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Message Queues that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. You have - to account for the memory used to store the messages of each message queue, - see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + 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`. .. index:: CONFIGURE_MAXIMUM_PARTITIONS @@ -71,21 +102,36 @@ CONFIGURE_MAXIMUM_PARTITIONS CONSTANT: ``CONFIGURE_MAXIMUM_PARTITIONS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API - Partitions that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Partitions that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_PERIODS @@ -97,21 +143,36 @@ CONFIGURE_MAXIMUM_PERIODS CONSTANT: ``CONFIGURE_MAXIMUM_PERIODS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods - that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Periods that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_PORTS @@ -123,21 +184,36 @@ CONFIGURE_MAXIMUM_PORTS CONSTANT: ``CONFIGURE_MAXIMUM_PORTS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that - can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Ports that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_REGIONS @@ -149,21 +225,36 @@ CONFIGURE_MAXIMUM_REGIONS CONSTANT: ``CONFIGURE_MAXIMUM_REGIONS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions - that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Regions that can be concurrently active. NOTES: - None. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_SEMAPHORES @@ -175,21 +266,36 @@ CONFIGURE_MAXIMUM_SEMAPHORES CONSTANT: ``CONFIGURE_MAXIMUM_SEMAPHORES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API - Semaphores that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Semaphore that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + 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 @@ -205,21 +311,40 @@ CONFIGURE_MAXIMUM_TASKS CONSTANT: ``CONFIGURE_MAXIMUM_TASKS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is ``0``. + The default value is 0. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. DESCRIPTION: - ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that - can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Tasks that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + 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 @@ -230,7 +355,7 @@ NOTES: ``CONFIGURE_EXTRA_TASK_STACKS``. The maximum number of POSIX threads is specified by - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS <CONFIGURE_MAXIMUM_POSIX_THREADS>`. + :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 @@ -247,21 +372,36 @@ CONFIGURE_MAXIMUM_TIMERS CONSTANT: ``CONFIGURE_MAXIMUM_TIMERS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers - that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API Timers that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS @@ -273,18 +413,27 @@ CONFIGURE_MAXIMUM_USER_EXTENSIONS CONSTANT: ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API - User Extensions that can be concurrently active. + The value of this configuration option defines the maximum number of Classic + API User Extensions that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class cannot be configured in unlimited allocation mode. diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index 8addf9f..ca300e7 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Classic API Initialization Task Configuration @@ -18,18 +19,19 @@ CONFIGURE_INIT_TASK_ARGUMENTS CONSTANT: ``CONFIGURE_INIT_TASK_ARGUMENTS`` -DATA TYPE: - RTEMS Task Argument (``rtems_task_argument``). - -RANGE: - Complete range of the type. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid integer of type + ``rtems_task_argument``. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines task argument of the Classic + API initialization task. NOTES: None. @@ -44,18 +46,18 @@ CONFIGURE_INIT_TASK_ATTRIBUTES CONSTANT: ``CONFIGURE_INIT_TASK_ATTRIBUTES`` -DATA TYPE: - RTEMS Attributes (``rtems_attribute``). - -RANGE: - Valid task attribute sets. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid task attribute set. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the task attributes of the + Classic API initialization task. NOTES: None. @@ -70,23 +72,23 @@ CONFIGURE_INIT_TASK_ENTRY_POINT CONSTANT: ``CONFIGURE_INIT_TASK_ENTRY_POINT`` -DATA TYPE: - Task entry function pointer (``rtems_task_entry``). - -RANGE: - Valid task entry function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: The default value is ``Init``. +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void ( *entry_point )( rtems_task_argument )``. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function - name) of the single initialization task defined by the Classic API - Initialization Tasks Table. + The value of this configuration option initializes the entry point of the + Classic API initialization task. NOTES: - The user must implement the function ``Init`` or the function name provided - in this configuration parameter. + The application shall provide the function referenced by this configuration + option. .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES @@ -98,19 +100,19 @@ CONFIGURE_INIT_TASK_INITIAL_MODES CONSTANT: ``CONFIGURE_INIT_TASK_INITIAL_MODES`` -DATA TYPE: - RTEMS Mode (``rtems_mode``). - -RANGE: - Valid task mode sets. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is ``RTEMS_NO_PREEMPT``. + In SMP configurations, the default value is ``RTEMS_DEFAULT_MODES``, + otherwise the default value is ``RTEMS_NO_PREEMPT``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid task mode set. DESCRIPTION: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the - single initialization task defined by the Classic API Initialization Tasks - Table. + The value of this configuration option defines the initial execution mode of + the Classic API initialization task. NOTES: None. @@ -125,21 +127,22 @@ CONFIGURE_INIT_TASK_NAME CONSTANT: ``CONFIGURE_INIT_TASK_NAME`` -DATA TYPE: - RTEMS Name (``rtems_name``). - -RANGE: - Any value. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid integer of type + ``rtems_name``. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task - defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the name of the Classic API + initialization task. NOTES: - None. + Use :c:func:`rtems_build_name` to define the task name. .. index:: CONFIGURE_INIT_TASK_PRIORITY @@ -151,18 +154,19 @@ CONFIGURE_INIT_TASK_PRIORITY CONSTANT: ``CONFIGURE_INIT_TASK_PRIORITY`` -DATA TYPE: - RTEMS Task Priority (``rtems_task_priority``). - -RANGE: - One (1) to the maximum user priority value of the scheduler. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 1, which is the highest priority in the Classic API. + The default value is 1. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid Classic API task + priority. The set of valid task priorities is scheduler-specific. DESCRIPTION: - ``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the initial priority of the + Classic API initialization task. NOTES: None. @@ -177,24 +181,28 @@ CONFIGURE_INIT_TASK_STACK_SIZE CONSTANT: ``CONFIGURE_INIT_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. + The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + + * It 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``. DESCRIPTION: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the task stack size of the + Classic API initialization task. NOTES: - If the stack size specified is greater than the configured minimum, it must - be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. + None. .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE @@ -218,10 +226,10 @@ DESCRIPTION: initialization task is configured. NOTES: - The application must define exactly one of the following configuration + The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, + * `CONFIGURE_RTEMS_INIT_TASKS_TABLE`, * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst index e783111..0a18b2d 100644 --- a/c-user/config/device-driver.rst +++ b/c-user/config/device-driver.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Device Driver Configuration @@ -34,7 +35,7 @@ NOTES: of using the Hello World example as the baseline for an application and leaving out a clock tick source. - The application must define exactly one of the following configuration options + The application shall define exactly one of the following configuration options * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, @@ -54,23 +55,26 @@ CONFIGURE_APPLICATION_EXTRA_DRIVERS CONSTANT: ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` -DATA TYPE: - device driver entry structures - -RANGE: - Undefined or set of device driver entry structures +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This is not defined by default. + The default value is the empty list. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a list of initializers for + structures of type :c:type:`rtems_driver_address_table`. DESCRIPTION: - ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has - device drivers it needs to include in the Device Driver Table. This should - be defined to the set of device driver entries that will be placed in the - table at the *END* of the Device Driver Table. + The value of this configuration option is used to initialize the Device + Driver Table. NOTES: - None. + The value of this configuration option is placed after the entries of other + device driver configuration options. + + See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative + placement of application device driver initializers. .. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER @@ -97,7 +101,7 @@ NOTES: The Clock Driver is responsible for providing a regular interrupt which invokes a clock tick directive. - The application must define exactly one of the following configuration options + The application shall define exactly one of the following configuration options * `CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, @@ -372,7 +376,7 @@ NOTES: The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS Testsuite. Applications should not use this driver. - The application must define exactly one of the following configuration options + The application shall define exactly one of the following configuration options * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, @@ -445,28 +449,27 @@ CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS CONSTANT: ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` -DATA TYPE: - device driver entry structures - -RANGE: - Undefined or set of device driver entry structures +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This is not defined by default. + The default value is the empty list. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a list of initializers for + structures of type :c:type:`rtems_driver_address_table`. DESCRIPTION: - ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the - application has device drivers it needs to include in the Device Driver - Table. This should be defined to the set of device driver entries that - will be placed in the table at the *FRONT* of the Device Driver Table and - initialized before any other drivers *EXCEPT* any BSP prerequisite drivers. + The value of this configuration option is used to initialize the Device + Driver Table. NOTES: - In some cases, it is used by System On Chip BSPs to support peripheral - buses beyond those normally found on the System On Chip. For example, this - is used by one RTEMS system which has implemented a SPARC/ERC32 based board - with VMEBus. The VMEBus Controller initialization is performed by a device - driver configured via this configuration parameter. + The value of this configuration option is placed after the entries defined by + :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver + configuration options. + + See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement + of application device driver initializers. .. index:: CONFIGURE_MAXIMUM_DRIVERS @@ -478,24 +481,33 @@ CONFIGURE_MAXIMUM_DRIVERS CONSTANT: ``CONFIGURE_MAXIMUM_DRIVERS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: This is computed by default, and is set to the number of device drivers configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` - configuration parameters. + configuration options. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be less than or equal to ``SIZE_MAX``. + + * It shall be greater than or equal than the number of statically configured + device drivers. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. DESCRIPTION: - ``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers - per node. + The value of this configuration option defines the number of device drivers. NOTES: If the application will dynamically install device drivers, then this - configuration parameter must be larger than the number of statically + configuration parameter shall be larger than the number of statically configured device drivers. Drivers configured using the - ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are + ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration options are statically installed. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst index edd8722..6c93a3a 100644 --- a/c-user/config/event-record.rst +++ b/c-user/config/event-record.rst @@ -110,19 +110,31 @@ CONFIGURE_RECORD_PER_PROCESSOR_ITEMS CONSTANT: ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` -DATA TYPE: - Unsigned integer (``unsigned int``). - -RANGE: - A power of two greater than or equal to 16. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - This is not defined by default. + The default value is 0. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 16. + + * It shall be less than or equal to ``SIZE_MAX``. + + * It shall be a power of two. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. DESCRIPTION: - If defined, then a record item buffer of the specified item count is - statically allocated for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`). + The value of this configuration option defines the event record item count + per processor. NOTES: - None. + 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. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst index 3a7b7fe..b4bccc9 100644 --- a/c-user/config/filesystem.rst +++ b/c-user/config/filesystem.rst @@ -70,7 +70,7 @@ DESCRIPTION: configured. NOTES: - Filesystems must be initialized to support file descriptor based device + 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. @@ -421,26 +421,28 @@ CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK CONSTANT: ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` -DATA TYPE: - Boolean feature macro. - -RANGE: - Valid values for this configuration parameter are a power of two (2) - between 16 and 512 inclusive. In other words, valid values are 16, 32, 64, - 128, 256,and 512. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default IMFS block size is 128 bytes. + The default value is 128. + +VALUE CONSTRAINTS: + The value of this configuration option shall be + an element of {16, 32, 64, 128, 256, 512}. DESCRIPTION: - This configuration parameter specifies the block size for in-memory files - managed by the IMFS. 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. + The value of this configuration option defines the block size for in-memory + files managed by the IMFS. + +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 @@ -460,9 +462,6 @@ DESCRIPTION: - when the block size is 512 bytes, the maximum file size is 1,082,195,456 bytes. -NOTES: - None. - .. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM .. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: diff --git a/c-user/config/general.rst b/c-user/config/general.rst index 35225f9..3615a2c 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) General System Configuration @@ -47,23 +48,30 @@ CONFIGURE_EXTRA_TASK_STACKS CONSTANT: ``CONFIGURE_EXTRA_TASK_STACKS`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Undefined or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It 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``. + DESCRIPTION: - This configuration parameter is set to the number of bytes the applications - wishes to add to the task stack requirements calculated by + 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>``. 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 + stacks larger then the minimum, then that memory is **not** accounted for by ``<rtems/confdefs.h>``. .. index:: CONFIGURE_INITIAL_EXTENSIONS @@ -76,22 +84,24 @@ CONFIGURE_INITIAL_EXTENSIONS CONSTANT: ``CONFIGURE_INITIAL_EXTENSIONS`` -DATA TYPE: - List of user extension initializers (``rtems_extensions_table``). - -RANGE: - Undefined or a list of one or more user extensions. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This is not defined by default. + The default value is the empty list. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a list of initializers for + structures of type :c:type:`rtems_extensions_table`. DESCRIPTION: - If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then - this application specific set of initial extensions will be placed in the - initial extension table. + The value of this configuration option is used to initialize the table of + initial user extensions. NOTES: - None. + The value of this configuration option is placed before the entries of + :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial + user extensions. .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size @@ -104,29 +114,36 @@ CONFIGURE_INTERRUPT_STACK_SIZE CONSTANT: ``CONFIGURE_INTERRUPT_STACK_SIZE`` -DATA TYPE: - Unsigned integer. - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is ``BSP_INTERRUPT_STACK_SIZE`` in case it is defined, + The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined, otherwise the default value is ``CPU_STACK_MINIMUM_SIZE``. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. + + * It 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``. + + * It shall be aligned according to + ``CPU_INTERRUPT_STACK_ALIGNMENT``. + DESCRIPTION: - The ``CONFIGURE_INTERRUPT_STACK_SIZE`` configuration option defines the - size of an interrupt stack in bytes. + The value of this configuration option defines the size of an interrupt stack + in bytes. NOTES: - The interrupt stack size must be aligned according to - ``CPU_INTERRUPT_STACK_ALIGNMENT``. - There is one interrupt stack available for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS <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. + (: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 @@ -137,8 +154,7 @@ NOTES: stack size may still result in undefined behaviour. In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE - <CONFIGURE_MINIMUM_TASK_STACK_SIZE>` instead of ``CPU_STACK_MINIMUM_SIZE``. + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of ``CPU_STACK_MINIMUM_SIZE``. .. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS .. index:: maximum file descriptors @@ -151,24 +167,31 @@ CONFIGURE_MAXIMUM_FILE_DESCRIPTORS CONSTANT: ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the - default value is 3, otherwise the default value is 0. Three file - descriptors allows RTEMS to support standard input, output, and error I/O - streams on ``/dev/console``. + The default value is 3. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to ``SIZE_MAX``. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. DESCRIPTION: - This configuration parameter is set to the maximum number of file like - objects that can be concurrently open. + The value of this configuration option defines the maximum number of file + like objects that can be concurrently open. NOTES: - None. + The default value of three file descriptors allows RTEMS to support standard + input, output, and error I/O streams on ``/dev/console``. .. index:: CONFIGURE_MAXIMUM_PRIORITY .. index:: maximum priority @@ -182,21 +205,18 @@ CONFIGURE_MAXIMUM_PRIORITY CONSTANT: ``CONFIGURE_MAXIMUM_PRIORITY`` -DATA TYPE: - Unsigned integer (``uint8_t``). - -RANGE: - Valid values for this configuration parameter must be one (1) less than - than a power of two (2) between 4 and 256 inclusively. In other words, - valid values are 3, 7, 31, 63, 127, and 255. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 255, because RTEMS must support 256 priority levels to - be compliant with various standards. These priorities range from zero (0) - to 255. + The default value is 255. + +VALUE CONSTRAINTS: + The value of this configuration option shall be + an element of {3, 7, 31, 63, 127, 255}. DESCRIPTION: - For the schedulers + For the following schedulers * :ref:`SchedulerPriority`, which is the default in uniprocessor configurations and can be configured through the @@ -217,8 +237,8 @@ NOTES: The numerically greatest priority is the logically lowest priority in the system and will thus be used by the IDLE task. - Priority zero (0) is reserved for internal use by RTEMS and is not available - to applications. + 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 @@ -228,6 +248,9 @@ NOTES: 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. + .. index:: CONFIGURE_MAXIMUM_PROCESSORS .. _CONFIGURE_MAXIMUM_PROCESSORS: @@ -238,27 +261,27 @@ CONFIGURE_MAXIMUM_PROCESSORS CONSTANT: ``CONFIGURE_MAXIMUM_PROCESSORS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 1. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``CPU_MAXIMUM_PROCESSORS``. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_PROCESSORS`` must be set to the maximum number of + 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 thread and interrupt stack for - example. + 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. NOTES: If there are more processors available than configured, the rest will be - ignored. This configuration define is ignored in uniprocessor - configurations. + ignored. In uniprocessor configuration, this configuration define is + ignored. .. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE .. index:: maximum thread name size @@ -271,24 +294,36 @@ CONFIGURE_MAXIMUM_THREAD_NAME_SIZE CONSTANT: ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - No restrictions. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 16. This value was chosen for Linux compatibility, - see - `PTHREAD_SETNAME_NP(3) <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. + The default value is 16. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to ``SIZE_MAX``. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. DESCRIPTION: - This configuration parameter specifies the maximum thread name size - including the terminating `NUL` character. + The value of this configuration option defines the maximum thread name size + including the terminating ``NUL`` character. NOTES: + The default value was chosen for Linux compatibility, see + `PTHREAD_SETNAME_NP(3) <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. + size. + + This configuration option is available since RTEMS 5.1. .. index:: CONFIGURE_MEMORY_OVERHEAD @@ -300,24 +335,37 @@ CONFIGURE_MEMORY_OVERHEAD CONSTANT: ``CONFIGURE_MEMORY_OVERHEAD`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + DESCRIPTION: - This parameter is set to the number of kilobytes the application wishes to - add to the requirements calculated by ``<rtems/confdefs.h>``. + 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>``. NOTES: - This configuration parameter 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. + 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`. .. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY .. index:: configure message queue buffer memory @@ -332,18 +380,29 @@ CONFIGURE_MESSAGE_BUFFER_MEMORY CONSTANT: ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` -DATA TYPE: - integer summation macro - -RANGE: - undefined (zero) or calculation resulting in a positive integer +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is zero. + The default value is 0. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. DESCRIPTION: - The value of this configuration option defines the number of bytes - resereved for message queue buffers in the RTEMS Workspace. + The value of this configuration option defines the number of bytes reserved + for message queue buffers in the RTEMS Workspace. NOTES: The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and @@ -393,6 +452,7 @@ NOTES: ) .. index:: CONFIGURE_MICROSECONDS_PER_TICK +.. index:: clock tick quantum .. index:: tick quantum .. _CONFIGURE_MICROSECONDS_PER_TICK: @@ -403,18 +463,25 @@ CONFIGURE_MICROSECONDS_PER_TICK CONSTANT: ``CONFIGURE_MICROSECONDS_PER_TICK`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - This is not defined by default. When not defined, the clock tick quantum is - configured to be 10,000 microseconds which is ten (10) milliseconds. + The default value is 10000. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to a Clock Driver specific value. + + * It shall be less than or equal to a Clock Driver specific value. + + * The resulting clock ticks per second should be an integer. DESCRIPTION: - This constant is used to specify the length of time between clock ticks. + 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 @@ -432,11 +499,11 @@ DESCRIPTION: application. NOTES: - This configuration parameter has no impact if the Clock Tick Device driver - is not configured. + 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 BSP specific limits on the resolution or maximum value of a - clock tick quantum. + There may be Clock Driver specific limits on the resolution or maximum value + of a clock tick quantum. .. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE .. index:: minimum task stack size @@ -449,27 +516,35 @@ CONFIGURE_MINIMUM_TASK_STACK_SIZE CONSTANT: ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is architecture-specific. + The default value is ``CPU_STACK_MINIMUM_SIZE``. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It 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``. + + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every user task or thread in the system. + The value of this configuration option defines the minimum stack size in + bytes for every user task or thread in the system. 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 <CONFIGURE_STACK_CHECKER_ENABLED>`). + (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 must be done with caution as it could increase the + 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 @@ -478,12 +553,11 @@ NOTES: 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 <CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE>` + :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 - <CONFIGURE_INTERRUPT_STACK_SIZE>`. + used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. .. index:: CONFIGURE_STACK_CHECKER_ENABLED @@ -524,22 +598,23 @@ CONFIGURE_TICKS_PER_TIMESLICE CONSTANT: ``CONFIGURE_TICKS_PER_TIMESLICE`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 50. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - This configuration parameter specifies the length of the timeslice quantum - in ticks for each task. + The value of this configuration option defines the length of the timeslice + quantum in ticks for each task. NOTES: - This configuration parameter has no impact if the Clock Tick Device driver - is not configured. + This configuration option has no impact if the Clock Driver is not + configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. .. index:: CONFIGURE_UNIFIED_WORK_AREAS .. index:: unified work areas @@ -587,27 +662,28 @@ CONFIGURE_UNLIMITED_ALLOCATION_SIZE CONSTANT: ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, the default - value is eight (8). + The default value is 8. + +VALUE CONSTRAINTS: + The value of this configuration option shall meet the constraints of all + object classes to which it is applied. DESCRIPTION: - ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an allocation size to use - for ``rtems_resource_unlimited`` when using - ``CONFIGURE_UNLIMITED_OBJECTS``. + 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)``. NOTES: By allowing users to declare all resources as being unlimited the user can - avoid identifying and limiting the resources - used. ``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the - allocation sizes for different objects; users who want that much control - can define the ``rtems_resource_unlimited`` macros themselves. + avoid identifying and limiting the resources used. + + The object maximum of each class can be configured also individually using + the :c:func:`rtems_resource_unlimited` macro. .. index:: CONFIGURE_UNLIMITED_OBJECTS diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst index 7af8b2f..12e7f46 100644 --- a/c-user/config/idle-task.rst +++ b/c-user/config/idle-task.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Idle Task Configuration @@ -17,22 +18,27 @@ CONFIGURE_IDLE_TASK_BODY CONSTANT: ``CONFIGURE_IDLE_TASK_BODY`` -DATA TYPE: - Function pointer. - -RANGE: - Undefined or valid function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This is not defined by default. + If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value, + otherwise the default value is ``_CPU_Thread_Idle_body``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void *( *idle_body )( uintptr_t )``. DESCRIPTION: - ``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to - the application specific IDLE thread body. If not specified, the BSP or - RTEMS default IDLE thread body will be used. + The value of this configuration option initializes the IDLE thread body. NOTES: - None. + 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`. .. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION @@ -53,30 +59,30 @@ DEFAULT CONFIGURATION: 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 + **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. + an IDLE task. NOTES: - If you use this option be careful, the user idle task **cannot** block at all + If you use this option be careful, the user IDLE task **cannot** block at all during the initialization sequence. Further, once application - initialization is complete, it must make itself preemptible and enter an idle + initialization is complete, it shall make itself preemptible and enter an idle body loop. - The idle task must run at the lowest priority of all tasks in the system. + 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, + 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 must define exactly one of the following configuration + The application shall define exactly one of the following configuration options * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` + * `CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` otherwise a compile time error in the configuration file will occur. @@ -90,18 +96,27 @@ CONFIGURE_IDLE_TASK_STACK_SIZE CONSTANT: ``CONFIGURE_IDLE_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Undefined or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. + The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. + + * It 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``. DESCRIPTION: - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the desired stack size for the + The value of this configuration option defines the task stack size for an IDLE task. NOTES: - None. + In SMP configurations, there is one IDLE task per configured processor, see + :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index a24bfd5..f96a703 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.rst @@ -48,17 +48,18 @@ CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS CONSTANT: ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 32. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of + The value of this configuration option defines the maximum number of concurrently active global objects in a multiprocessor system. NOTES: @@ -75,18 +76,19 @@ CONFIGURE_MP_MAXIMUM_NODES CONSTANT: ``CONFIGURE_MP_MAXIMUM_NODES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 2. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - ``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a - multiprocessor system. + The value of this configuration option defines the maximum number of nodes in + a multiprocessor system. NOTES: None. @@ -101,18 +103,20 @@ CONFIGURE_MP_MAXIMUM_PROXIES CONSTANT: ``CONFIGURE_MP_MAXIMUM_PROXIES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Undefined or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 32. +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. + DESCRIPTION: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently - active thread/task proxies on this node in a multiprocessor system. + The value of this configuration option defines the maximum number of + concurrently active thread/task proxies on this node in a multiprocessor + system. NOTES: Since a proxy is used to represent a remote task/thread which is blocking @@ -130,18 +134,19 @@ CONFIGURE_MP_MPCI_TABLE_POINTER CONSTANT: ``CONFIGURE_MP_MPCI_TABLE_POINTER`` -DATA TYPE: - pointer to ``rtems_mpci_table`` - -RANGE: - undefined or valid pointer +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - This is not defined by default. + The default value is ``&MPCI_table``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a pointer to + :c:type:`rtems_mpci_table`. DESCRIPTION: - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI - Configuration Table. The default value of this field is``&MPCI_table``. + The value of this configuration option initializes the MPCI Configuration + Table. NOTES: RTEMS provides a Shared Memory MPCI Device Driver which can be used on any @@ -158,19 +163,19 @@ CONFIGURE_MP_NODE_NUMBER CONSTANT: ``CONFIGURE_MP_NODE_NUMBER`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is ``NODE_NUMBER``, which is assumed to be set by the - compilation environment. + The default value is ``NODE_NUMBER``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be greater than or equal to 0 + and less than or equal to ``UINT32_MAX``. DESCRIPTION: - ``CONFIGURE_MP_NODE_NUMBER`` is the node number of this node in a - multiprocessor system. + The value of this configuration option defines the node number of this node + in a multiprocessor system. NOTES: In the RTEMS Multiprocessing Test Suite, the node number is derived from diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 13ac18d..54e8d99 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) POSIX API Configuration @@ -20,21 +21,36 @@ CONFIGURE_MAXIMUM_POSIX_KEYS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_KEYS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys - that can be concurrently active. + The value of this configuration option defines the maximum number of POSIX + API Keys that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS @@ -46,24 +62,39 @@ CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS <CONFIGURE_MAXIMUM_POSIX_KEYS>` * - :ref:`CONFIGURE_MAXIMUM_TASKS <CONFIGURE_MAXIMUM_TASKS>` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS <CONFIGURE_MAXIMUM_POSIX_THREADS>`. + :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * + :ref:`CONFIGURE_MAXIMUM_TASKS` + + :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` is the maximum number of key + The value of this configuration option defines the maximum number of key value pairs used by POSIX API Keys that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + 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 :c:macro:`NULL`, otherwise it is deleted. @@ -78,23 +109,42 @@ CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX + The value of this configuration option defines the maximum number of POSIX API Message Queues that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. You have - to account for the memory used to store the messages of each message queue, - see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + 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`. .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS @@ -106,17 +156,28 @@ CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX + The value of this configuration option defines the maximum number of POSIX API Queued Signals that can be concurrently active. NOTES: @@ -135,25 +196,44 @@ CONFIGURE_MAXIMUM_POSIX_SEMAPHORES CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API - Named Semaphores that can be concurrently active. + The value of this configuration option defines the maximum number of POSIX + API Named Semaphores that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. - Named semaphores are created with ``sem_open()``. Semaphores initialized - with ``sem_init()`` are not affected by this configuration option since the - storage space for these semaphores is user-provided. + 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. .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS @@ -165,32 +245,46 @@ CONFIGURE_MAXIMUM_POSIX_THREADS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_THREADS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It 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``. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API - Threads that can be concurrently active. + The value of this configuration option defines the maximum number of POSIX + API Threads that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + 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 parameter - ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack - requirements *ABOVE* the minimum size required. See :ref:`Reserve + point support enabled. The configuration option + :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used to specify thread stack + requirements **above** the minimum size required. See :ref:`Reserve Task/Thread Stack Memory Above Minimum` for more information about ``CONFIGURE_EXTRA_TASK_STACKS``. The maximum number of Classic API Tasks is specified by - :ref:`CONFIGURE_MAXIMUM_TASKS <CONFIGURE_MAXIMUM_TASKS>`. + :ref:`CONFIGURE_MAXIMUM_TASKS`. All POSIX threads have floating point enabled. @@ -204,21 +298,36 @@ CONFIGURE_MAXIMUM_POSIX_TIMERS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API - Timers that can be concurrently active. + The value of this configuration option defines the maximum number of POSIX + API Timers that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. Timers are only available if RTEMS was built with the ``--enable-posix`` build configuration option. @@ -234,19 +343,27 @@ CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE CONSTANT: ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE <CONFIGURE_MINIMUM_TASK_STACK_SIZE>`. + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It 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``. + + * It shall be greater than or equal to a + BSP-specific and application-specific minimum value. DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every POSIX thread in the system. + The value of this configuration option defines the minimum stack size in + bytes for every POSIX thread in the system. NOTES: None. diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst index 82c0942..65ccfe8 100644 --- a/c-user/config/posix-init-thread.rst +++ b/c-user/config/posix-init-thread.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) POSIX Initialization Thread Configuration @@ -18,23 +19,23 @@ CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT CONSTANT: ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` -DATA TYPE: - POSIX thread function pointer (``void *(*entry_point)(void *)``). - -RANGE: - Undefined or a valid POSIX thread function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: The default value is ``POSIX_Init``. +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void *( *entry_point )( void * )``. + DESCRIPTION: - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point - (a.k.a. function name) of the single initialization thread defined by the - POSIX API Initialization Threads Table. + The value of this configuration option initializes the entry point of the + POSIX API initialization thread. NOTES: - The user must implement the function ``POSIX_Init`` or the function name - provided in this configuration parameter. + The application shall provide the function referenced by this configuration + option. .. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE @@ -46,25 +47,28 @@ CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE CONSTANT: ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. + The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + + * It 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``. DESCRIPTION: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single - initialization thread defined by the POSIX API Initialization Threads - Table. + The value of this configuration option defines the thread stack size of the + POSIX API initialization thread. NOTES: - If the stack size specified is greater than the configured minimum, it must - be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. + None. .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE @@ -88,12 +92,12 @@ DESCRIPTION: initialization thread is configured. NOTES: - The application must define exactly one of the following configuration + The application shall define exactly one of the following configuration options * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or + * `CONFIGURE_POSIX_INIT_THREAD_TABLE`, or * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst index bf32986..db8e5ca 100644 --- a/c-user/config/scheduler-general.rst +++ b/c-user/config/scheduler-general.rst @@ -135,32 +135,44 @@ CONFIGURE_SCHEDULER_NAME CONSTANT: ``CONFIGURE_SCHEDULER_NAME`` -DATA TYPE: - RTEMS Name (``rtems_name``). - -RANGE: - Any value. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default name is + The default value is + + * ``"MEDF"`` for the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`, + + * ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler <SchedulerSMPPriorityAffinity>`, + + * ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`, + + * ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`, - - ``"MEDF"`` for the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`, - - ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler <SchedulerSMPPriorityAffinity>`, - - ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`, - - ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`, - - ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler <SchedulerCBS>`, - - ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler <SchedulerEDF>`, - - ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler <SchedulerPriority>`, and - - ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler <SchedulerPrioritySimple>`. + * ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler <SchedulerCBS>`, + + * ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler <SchedulerEDF>`, + + * ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler <SchedulerPriority>`, and + + * ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler <SchedulerPrioritySimple>`. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid integer of type + ``rtems_name``. DESCRIPTION: - Schedulers can be identified via ``rtems_scheduler_ident``. The name of - the scheduler is determined by the configuration. + The value of this configuration option defines the name of the default + scheduler. NOTES: This scheduler configuration option is an advanced configuration option. Think twice before you use it. + Schedulers can be identified via c:func:`rtems_scheduler_ident`. + + Use :c:func:`rtems_build_name` to define the scheduler name. + .. index:: CONFIGURE_SCHEDULER_PRIORITY .. _CONFIGURE_SCHEDULER_PRIORITY: @@ -352,7 +364,7 @@ DEFAULT CONFIGURATION: enabled. DESCRIPTION: - In case this configuration option is defined, then the user must provide a + In case this configuration option is defined, then the user shall provide a scheduler algorithm to the application. NOTES: @@ -360,18 +372,18 @@ NOTES: Think twice before you use it. RTEMS allows the application to provide its own task/thread scheduling - algorithm. In order to do this, one must define + 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 must be defined: + following additional macros shall be defined: - - ``CONFIGURE_SCHEDULER`` must be defined to a static definition of + - ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of the scheduler data structures of the user scheduler. - - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` must be defined to a scheduler + - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler table entry initializer for the user scheduler. - - ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of + - ``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 diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index e031595..513815c 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -22,28 +22,29 @@ CONFIGURE_TASK_STACK_ALLOCATOR CONSTANT: ``CONFIGURE_TASK_STACK_ALLOCATOR`` -DATA TYPE: - Function pointer. - -RANGE: - Undefined or valid function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: The default value is ``_Workspace_Allocate``, which indicates that task stacks will be allocated from the RTEMS Workspace. +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void *( *allocate )( size_t )``. + DESCRIPTION: - ``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to - allocate task stacks. + The value of this configuration option initializes the stack allocator + allocate handler. NOTES: - A correctly configured system must configure the following to be consistent: + A correctly configured system shall configure the following to be consistent: - - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - - ``CONFIGURE_TASK_STACK_ALLOCATOR`` + - `CONFIGURE_TASK_STACK_ALLOCATOR` - - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT @@ -55,29 +56,28 @@ CONFIGURE_TASK_STACK_ALLOCATOR_INIT CONSTANT: ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` -DATA TYPE: - Function pointer. - -RANGE: - Undefined, NULL or valid function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: - The default value is NULL, which indicates that task stacks will be - allocated from the RTEMS Workspace. + The default value is ``NULL``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void ( *initialize )( size_t )`` or to ``NULL``. DESCRIPTION: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization - method for an application or BSP specific task stack allocation - implementation. + The value of this configuration option initializes the stack allocator + initialization handler. NOTES: - A correctly configured system must configure the following to be consistent: + A correctly configured system shall configure the following to be consistent: - - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + - `CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - - ``CONFIGURE_TASK_STACK_ALLOCATOR`` + - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -90,25 +90,26 @@ CONFIGURE_TASK_STACK_DEALLOCATOR CONSTANT: ``CONFIGURE_TASK_STACK_DEALLOCATOR`` -DATA TYPE: - Function pointer. - -RANGE: - Undefined or valid function pointer. +OPTION TYPE: + This configuration option is an initializer define. DEFAULT VALUE: The default value is ``_Workspace_Free``, which indicates that task stacks will be allocated from the RTEMS Workspace. +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid function + pointer of the type ``void ( *deallocate )( void * )``. + DESCRIPTION: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine - to free task stacks. + The value of this configuration option initializes the stack allocator + deallocate handler. NOTES: - A correctly configured system must configure the following to be consistent: + A correctly configured system shall configure the following to be consistent: - - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - - ``CONFIGURE_TASK_STACK_ALLOCATOR`` + - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + - `CONFIGURE_TASK_STACK_DEALLOCATOR` |