diff options
Diffstat (limited to 'c-user/config/bdbuf.rst')
| -rw-r--r-- | c-user/config/bdbuf.rst | 528 |
1 files changed, 362 insertions, 166 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 84b1d33..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,13 +1,37 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-bdbuf + Block Device Cache Configuration ================================ This section describes configuration options related to the Block Device Cache (bdbuf). +.. Generated from spec:/acfg/if/appl-needs-libblock + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK .. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: @@ -15,24 +39,35 @@ This section describes configuration options related to the Block Device Cache CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +In case this configuration option is defined, then the Block Device Cache is +initialized during system initialization. -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:: 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE @@ -41,23 +76,37 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -DATA TYPE: - Unsigned integer (``uint32_t``). +The default value is 4096. -RANGE: - It must be positive and an integral multiple of the buffer minimum size. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 4096 bytes. +The value of this configuration option defines the maximum size of a buffer +in bytes. -DESCRIPTION: - 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE @@ -66,23 +115,37 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MIN_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -DATA TYPE: - Unsigned integer (``uint32_t``). +.. rubric:: DEFAULT VALUE: -RANGE: - Positive. +The default value is 512. -DEFAULT VALUE: - The default value is 512 bytes. +.. rubric:: DESCRIPTION: -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. +.. 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-cache-memory-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE @@ -91,23 +154,37 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` + +.. rubric:: OPTION TYPE: -DATA TYPE: - Unsigned integer (``size_t``). +This configuration option is an integer define. -RANGE: - Positive. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 32768 bytes. +The default value is 32768. -DESCRIPTION: - Size of the cache memory in bytes. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the size of the cache memory +in bytes. + +.. 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS @@ -116,25 +193,43 @@ 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: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per +read-ahead request. + +.. rubric:: 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. -DATA TYPE: - Unsigned integer (``uint32_t``). +.. rubric:: CONSTRAINTS: -RANGE: - Positive. +The following constraints apply to this configuration option: -DEFAULT VALUE: - The default value is 0. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - Defines the maximum blocks per read-ahead request. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -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. +.. Generated from spec:/acfg/if/bdbuf-max-write-blocks + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS @@ -143,23 +238,37 @@ NOTES: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. + +.. rubric:: DESCRIPTION: -DATA TYPE: - Unsigned integer (``uint32_t``). +The value of this configuration option defines the maximum blocks per write +request. -RANGE: - Positive. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 16. +The following constraints apply to this configuration option: -DESCRIPTION: - Defines the maximum blocks per write request. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - None. +* 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY @@ -168,23 +277,33 @@ NOTES: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ---------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -DATA TYPE: - Task priority (``rtems_task_priority``). +The default value is 15. -RANGE: - Valid task priority. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 15. +The value of this configuration option defines the read-ahead task priority. -DESCRIPTION: - Defines the read-ahead 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. + +.. Generated from spec:/acfg/if/bdbuf-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE @@ -193,23 +312,44 @@ 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: + +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. -DATA TYPE: - Unsigned integer (``size_t``). +.. rubric:: DESCRIPTION: -RANGE: - Zero or positive. +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. -DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - Defines the task stack size of the Block Device Cache tasks in bytes. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* 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. + +* 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD @@ -218,23 +358,37 @@ NOTES: CONFIGURE_SWAPOUT_BLOCK_HOLD ---------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -DATA TYPE: - Unsigned integer (``uint32_t``). +.. rubric:: DEFAULT VALUE: -RANGE: - Positive. +The default value is 1000. -DEFAULT VALUE: - The default value is 1000 milliseconds. +.. rubric:: DESCRIPTION: -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. +.. 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD @@ -243,23 +397,37 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. rubric:: OPTION TYPE: -DATA TYPE: - Unsigned integer (``uint32_t``). +This configuration option is an integer define. -RANGE: - Positive. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 250 milliseconds. +The default value is 250. -DESCRIPTION: - Defines the swapout task swap period in milliseconds. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the swapout task swap period +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-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY @@ -268,48 +436,33 @@ NOTES: CONFIGURE_SWAPOUT_TASK_PRIORITY ------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` +.. rubric:: CONSTANT: -DATA TYPE: - Task priority (``rtems_task_priority``). +``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -RANGE: - Valid task priority. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 15. +This configuration option is an integer define. -DESCRIPTION: - Defines the swapout task priority. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +The default value is 15. -.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY +.. rubric:: DESCRIPTION: -.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: - -CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY --------------------------------------- +The value of this configuration option defines the swapout task priority. -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` +.. rubric:: CONSTRAINTS: -DATA TYPE: - Task priority (``rtems_task_priority``). +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. -RANGE: - Valid task priority. +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks -DEFAULT VALUE: - The default value is 15. +.. raw:: latex -DESCRIPTION: - Defines the swapout worker task priority. - -NOTES: - None. + \clearpage .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS @@ -318,20 +471,63 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout worker task count. + +.. 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-worker-taskp-riority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: + +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: -DATA TYPE: - Unsigned integer (``size_t``). +The default value is 15. -RANGE: - Zero or positive. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the swapout worker task +priority. -DESCRIPTION: - Defines the swapout worker task count. +.. 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. |