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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel > _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel