[PATCH] c-user: Use rubric for configuration options
Chris Johns
chrisj at rtems.org
Tue Nov 16 21:43:09 UTC 2021
OK to push. This is a sensible change to make.
Thanks
Chris
On 16/11/21 6:27 pm, Sebastian Huber wrote:
> Use a rubric instead of a definition list for the application
> configuration options similar to the directive documentation pages. For
> direcives and application configuration options use the same rubric
> order.
>
> Generalize value constraints to constraints.
>
> This patch does not change hand written content.
> ---
>
> The generated PDF can be reviewed here:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
> c-user/config/bdbuf.rst | 457 +++++------
> c-user/config/bsp-related.rst | 304 ++++----
> c-user/config/classic-api.rst | 676 ++++++++--------
> c-user/config/classic-init-task.rst | 355 +++++----
> c-user/config/device-driver.rst | 792 ++++++++++---------
> c-user/config/event-record.rst | 160 ++--
> c-user/config/filesystem.rst | 844 ++++++++++----------
> c-user/config/general.rst | 1103 +++++++++++++++------------
> c-user/config/idle-task.rst | 147 ++--
> c-user/config/mpci.rst | 315 ++++----
> c-user/config/posix-api.rst | 539 +++++++------
> c-user/config/posix-init-thread.rst | 115 +--
> c-user/config/scheduler-general.rst | 669 ++++++++--------
> c-user/config/task-stack-alloc.rst | 244 +++---
> 14 files changed, 3691 insertions(+), 3029 deletions(-)
>
> diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst
> index c5381e1..d36c2bd 100644
> --- a/c-user/config/bdbuf.rst
> +++ b/c-user/config/bdbuf.rst
> @@ -35,24 +35,29 @@ This section describes configuration options related to the Block Device Cache
> CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
> ------------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK``
> +.. rubric:: CONSTANT:
>
> -OPTION TYPE:
> - This configuration option is a boolean feature define.
> +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK``
>
> -DEFAULT CONFIGURATION:
> - If this configuration option is undefined, then the described feature is not
> - enabled.
> +.. rubric:: OPTION TYPE:
>
> -DESCRIPTION:
> - In case this configuration option is defined, then the Block Device Cache is
> - initialized during system initialization.
> +This configuration option is a boolean feature define.
>
> -NOTES:
> - Each option of the Block Device Cache (bdbuf) configuration can be explicitly
> - set by the user with the configuration options below. The Block Device Cache
> - is used for example by the RFS and DOSFS filesystems.
> +.. rubric:: DEFAULT CONFIGURATION:
> +
> +If this configuration option is undefined, then the described feature is not
> +enabled.
> +
> +.. rubric:: DESCRIPTION:
> +
> +In case this configuration option is defined, then the Block Device Cache is
> +initialized during system initialization.
> +
> +.. rubric:: NOTES:
> +
> +Each option of the Block Device Cache (bdbuf) configuration can be explicitly
> +set by the user with the configuration options below. The Block Device Cache
> +is used for example by the RFS and DOSFS filesystems.
>
> .. Generated from spec:/acfg/if/bdbuf-buffer-max-size
>
> @@ -63,30 +68,31 @@ NOTES:
> CONFIGURE_BDBUF_BUFFER_MAX_SIZE
> -------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE``
> +
> +.. rubric:: OPTION TYPE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +This configuration option is an integer define.
>
> -DEFAULT VALUE:
> - The default value is 4096.
> +.. rubric:: DEFAULT VALUE:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The default value is 4096.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: DESCRIPTION:
>
> - * It shall be an integral multiple of
> - :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`.
> +The value of this configuration option defines the maximum size of a buffer
> +in bytes.
>
> -DESCRIPTION:
> - The value of this configuration option defines the maximum size of a buffer
> - in bytes.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - None.
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be an integral multiple of
> + :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`.
>
> .. Generated from spec:/acfg/if/bdbuf-buffer-min-size
>
> @@ -97,30 +103,31 @@ NOTES:
> CONFIGURE_BDBUF_BUFFER_MIN_SIZE
> -------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE``
> +
> +.. rubric:: OPTION TYPE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +This configuration option is an integer define.
>
> -DEFAULT VALUE:
> - The default value is 512.
> +.. rubric:: DEFAULT VALUE:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The default value is 512.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: DESCRIPTION:
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +The value of this configuration option defines the minimum size of a buffer
> +in bytes.
>
> -DESCRIPTION:
> - The value of this configuration option defines the minimum size of a buffer
> - in bytes.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - None.
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-cache-memory-size
>
> @@ -131,30 +138,31 @@ NOTES:
> CONFIGURE_BDBUF_CACHE_MEMORY_SIZE
> ---------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE``
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +.. rubric:: OPTION TYPE:
>
> -DEFAULT VALUE:
> - The default value is 32768.
> +This configuration option is an integer define.
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +.. rubric:: DEFAULT VALUE:
>
> - * It shall be greater than or equal to zero.
> +The default value is 32768.
>
> - * It shall be less than or equal to `SIZE_MAX
> - <https://en.cppreference.com/w/c/types/limits>`_.
> +.. rubric:: DESCRIPTION:
>
> -DESCRIPTION:
> - The value of this configuration option defines the size of the cache memory
> - in bytes.
> +The value of this configuration option defines the size of the cache memory
> +in bytes.
>
> -NOTES:
> - None.
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-max-read-ahead-blocks
>
> @@ -165,32 +173,37 @@ NOTES:
> CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS
> -------------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS``
> +
> +.. rubric:: OPTION TYPE:
> +
> +This configuration option is an integer define.
> +
> +.. rubric:: DEFAULT VALUE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +The default value is 0.
>
> -DEFAULT VALUE:
> - The default value is 0.
> +.. rubric:: DESCRIPTION:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The value of this configuration option defines the maximum blocks per
> +read-ahead request.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: NOTES:
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +A value of 0 disables the read-ahead task (default). The read-ahead task
> +will issue speculative read transfers if a sequential access pattern is
> +detected. This can improve the performance on some systems.
>
> -DESCRIPTION:
> - The value of this configuration option defines the maximum blocks per
> - read-ahead request.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - A value of 0 disables the read-ahead task (default). The read-ahead task
> - will issue speculative read transfers if a sequential access pattern is
> - detected. This can improve the performance on some systems.
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-max-write-blocks
>
> @@ -201,30 +214,31 @@ NOTES:
> CONFIGURE_BDBUF_MAX_WRITE_BLOCKS
> --------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS``
> +
> +.. rubric:: OPTION TYPE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +This configuration option is an integer define.
>
> -DEFAULT VALUE:
> - The default value is 16.
> +.. rubric:: DEFAULT VALUE:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The default value is 16.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: DESCRIPTION:
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +The value of this configuration option defines the maximum blocks per write
> +request.
>
> -DESCRIPTION:
> - The value of this configuration option defines the maximum blocks per write
> - request.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - None.
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority
>
> @@ -235,25 +249,27 @@ NOTES:
> CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY
> ----------------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY``
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +.. rubric:: OPTION TYPE:
>
> -DEFAULT VALUE:
> - The default value is 15.
> +This configuration option is an integer define.
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall be a valid Classic API task
> - priority. The set of valid task priorities depends on the scheduler
> - configuration.
> +.. rubric:: DEFAULT VALUE:
>
> -DESCRIPTION:
> - The value of this configuration option defines the read-ahead task priority.
> +The default value is 15.
>
> -NOTES:
> - None.
> +.. rubric:: DESCRIPTION:
> +
> +The value of this configuration option defines the read-ahead task priority.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The value of the configuration option shall be a valid Classic API task
> +priority. The set of valid task priorities depends on the scheduler
> +configuration.
>
> .. Generated from spec:/acfg/if/bdbuf-task-stack-size
>
> @@ -264,36 +280,38 @@ NOTES:
> CONFIGURE_BDBUF_TASK_STACK_SIZE
> -------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_BDBUF_TASK_STACK_SIZE``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_BDBUF_TASK_STACK_SIZE``
> +
> +.. rubric:: OPTION TYPE:
> +
> +This configuration option is an integer define.
> +
> +.. rubric:: DEFAULT VALUE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`.
>
> -DEFAULT VALUE:
> - The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`.
> +.. rubric:: DESCRIPTION:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The value of this configuration option defines the task stack size of the
> +Block Device Cache tasks in bytes.
>
> - * It shall be greater than or equal to
> - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
> +.. rubric:: CONSTRAINTS:
>
> - * 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.
> +The following constraints apply to this configuration option:
>
> - * 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 <https://en.cppreference.com/w/c/types/integer>`_.
> +* The value of the configuration option shall be greater than or equal to
> + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
>
> -DESCRIPTION:
> - The value of this configuration option defines the task stack size of the
> - Block Device Cache tasks in bytes.
> +* The value of the configuration option shall be less than or equal to a
> + BSP-specific and application-specific value which depends on the size of the
> + memory available to the application.
>
> -NOTES:
> - None.
> +* The value of the configuration option shall be small enough so that the task
> + stack space calculation carried out by ``<rtems/confdefs.h>`` does not
> + overflow an integer of type `uintptr_t
> + <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-swapout-block-hold
>
> @@ -304,30 +322,31 @@ NOTES:
> CONFIGURE_SWAPOUT_BLOCK_HOLD
> ----------------------------
>
> -CONSTANT:
> - ``CONFIGURE_SWAPOUT_BLOCK_HOLD``
> +.. rubric:: CONSTANT:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +``CONFIGURE_SWAPOUT_BLOCK_HOLD``
>
> -DEFAULT VALUE:
> - The default value is 1000.
> +.. rubric:: OPTION TYPE:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +This configuration option is an integer define.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: DEFAULT VALUE:
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +The default value is 1000.
>
> -DESCRIPTION:
> - The value of this configuration option defines the swapout task maximum block
> - hold time in milliseconds.
> +.. rubric:: DESCRIPTION:
>
> -NOTES:
> - None.
> +The value of this configuration option defines the swapout task maximum block
> +hold time in milliseconds.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-swapout-swap-period
>
> @@ -338,30 +357,31 @@ NOTES:
> CONFIGURE_SWAPOUT_SWAP_PERIOD
> -----------------------------
>
> -CONSTANT:
> - ``CONFIGURE_SWAPOUT_SWAP_PERIOD``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_SWAPOUT_SWAP_PERIOD``
> +
> +.. rubric:: OPTION TYPE:
> +
> +This configuration option is an integer define.
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +.. rubric:: DEFAULT VALUE:
>
> -DEFAULT VALUE:
> - The default value is 250.
> +The default value is 250.
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +.. rubric:: DESCRIPTION:
>
> - * It shall be greater than or equal to zero.
> +The value of this configuration option defines the swapout task swap period
> +in milliseconds.
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +.. rubric:: CONSTRAINTS:
>
> -DESCRIPTION:
> - The value of this configuration option defines the swapout task swap period
> - in milliseconds.
> +The following constraints apply to this configuration option:
>
> -NOTES:
> - None.
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-swapout-task-priority
>
> @@ -372,25 +392,27 @@ NOTES:
> CONFIGURE_SWAPOUT_TASK_PRIORITY
> -------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_SWAPOUT_TASK_PRIORITY``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_SWAPOUT_TASK_PRIORITY``
> +
> +.. rubric:: OPTION TYPE:
> +
> +This configuration option is an integer define.
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +.. rubric:: DEFAULT VALUE:
>
> -DEFAULT VALUE:
> - The default value is 15.
> +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 depends on the scheduler
> - configuration.
> +.. rubric:: DESCRIPTION:
>
> -DESCRIPTION:
> - The value of this configuration option defines the swapout task priority.
> +The value of this configuration option defines the swapout task priority.
>
> -NOTES:
> - None.
> +.. rubric:: CONSTRAINTS:
> +
> +The value of the configuration option shall be a valid Classic API task
> +priority. The set of valid task priorities depends on the scheduler
> +configuration.
>
> .. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks
>
> @@ -401,29 +423,30 @@ NOTES:
> CONFIGURE_SWAPOUT_WORKER_TASKS
> ------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_SWAPOUT_WORKER_TASKS``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_SWAPOUT_WORKER_TASKS``
> +
> +.. rubric:: OPTION TYPE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +This configuration option is an integer define.
>
> -DEFAULT VALUE:
> - The default value is 0.
> +.. rubric:: DEFAULT VALUE:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall satisfy all of the following
> - constraints:
> +The default value is 0.
>
> - * It shall be greater than or equal to zero.
> +.. rubric:: DESCRIPTION:
>
> - * It shall be less than or equal to `UINT32_MAX
> - <https://en.cppreference.com/w/c/types/integer>`_.
> +The value of this configuration option defines the swapout worker task count.
>
> -DESCRIPTION:
> - The value of this configuration option defines the swapout worker task count.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - None.
> +The following constraints apply to this configuration option:
> +
> +* The value of the configuration option shall be greater than or equal to zero.
> +
> +* The value of the configuration option shall be less than or equal to
> + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
>
> .. Generated from spec:/acfg/if/bdbuf-swapout-worker-taskp-riority
>
> @@ -434,23 +457,25 @@ NOTES:
> CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY
> --------------------------------------
>
> -CONSTANT:
> - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY``
> +.. rubric:: CONSTANT:
> +
> +``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY``
> +
> +.. rubric:: OPTION TYPE:
> +
> +This configuration option is an integer define.
> +
> +.. rubric:: DEFAULT VALUE:
>
> -OPTION TYPE:
> - This configuration option is an integer define.
> +The default value is 15.
>
> -DEFAULT VALUE:
> - The default value is 15.
> +.. rubric:: DESCRIPTION:
>
> -VALUE CONSTRAINTS:
> - The value of this configuration option shall be a valid Classic API task
> - priority. The set of valid task priorities depends on the scheduler
> - configuration.
> +The value of this configuration option defines the swapout worker task
> +priority.
>
> -DESCRIPTION:
> - The value of this configuration option defines the swapout worker task
> - priority.
> +.. rubric:: CONSTRAINTS:
>
> -NOTES:
> - None.
> +The value of the configuration option shall be a valid Classic API task
> +priority. The set of valid task priorities depends on the scheduler
> +configuration.
> [ the remaining patch was removed due to the mailing list size limit ]
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
More information about the devel
mailing list