From 7bad8940ad05ea1e3b41745012a0dc5391275477 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 27 Mar 2020 12:53:09 +0100 Subject: c-user: Use new template for integer config opts Try to bring all descriptions up to date. Add cross-references to several options. Clarify configuration value constraints. Use this template also for initializer type options. Close #3901. --- c-user/config/posix-api.rst | 261 ++++++++++++++++++++++++++++++++------------ 1 file changed, 189 insertions(+), 72 deletions(-) (limited to 'c-user/config/posix-api.rst') diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 13ac18d..54e8d99 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) POSIX API Configuration @@ -20,21 +21,36 @@ CONFIGURE_MAXIMUM_POSIX_KEYS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_KEYS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to 0. + + * It shall be less than or equal to 65535. + + * It shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + + * It may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for this + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of this configuration option. + DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys - that can be concurrently active. + The value of this configuration option defines the maximum number of POSIX + API Keys that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + This object class can be configured in unlimited allocation mode, see + :ref:`ConfigUnlimitedObjects`. .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS @@ -46,24 +62,39 @@ CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS CONSTANT: ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS ` * - :ref:`CONFIGURE_MAXIMUM_TASKS ` + - :ref:`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 ```` 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 ```` 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 ```` 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 ```` 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 `. + :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 `. + :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 ```` 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. -- cgit v1.2.3