rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-06-06 13:23:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Use new template for integer config opts

Browse Source 
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.
This commit is contained in:
Sebastian Huber 2020-03-27 12:53:09 +01:00
parent e26f87497e
commit 7bad8940ad
14 changed files with 1210 additions and 755 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
c-user/config/bdbuf.rst
View File

@ -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.

193
c-user/config/bsp-related.rst
View File

@ -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.
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:
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.
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_SIZE`.
NOTES:
The order of precedence for configuring the IDLE task stack size is:
- RTEMS default minimum stack size.
- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``.
- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``.
- If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``.
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,53 +130,39 @@ 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.
The default value is BSP-specific.
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:
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.
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_INTERRUPT_STACK_SIZE`.
NOTES:
None.
.. index:: BSP_MAXIMUM_DEVICES
.. _BSP_MAXIMUM_DEVICES:
BSP_MAXIMUM_DEVICES
-------------------
CONSTANT:
``BSP_MAXIMUM_DEVICES``
DATA TYPE:
Unsigned integer (``size_t``).
RANGE:
Undefined or positive.
DEFAULT VALUE:
This option is BSP specific.
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.
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.
.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS
.. _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

317
c-user/config/classic-api.rst
View File

@ -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.

134
c-user/config/classic-init-task.rst
View File

@ -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

92
c-user/config/device-driver.rst
View File

@ -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.

32
c-user/config/event-record.rst
View File

@ -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.

39
c-user/config/filesystem.rst
View File

@ -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:

376
c-user/config/general.rst
View File

@ -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

67
c-user/config/idle-task.rst
View File

@ -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`.

79
c-user/config/mpci.rst
View File

@ -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

261
c-user/config/posix-api.rst
View File

@ -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.

54
c-user/config/posix-init-thread.rst
View File

@ -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`

56
c-user/config/scheduler-general.rst
View File

@ -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>`,
- ``"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>`.
* ``"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>`.
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

73
c-user/config/task-stack-alloc.rst
View File

@ -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`