[PATCH] c-user: Use rubric for configuration options

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
> 