diff options
Diffstat (limited to 'c-user/config/bdbuf.rst')
| -rw-r--r-- | c-user/config/bdbuf.rst | 542 |
1 files changed, 351 insertions, 191 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 79459bf..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,14 +1,37 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. 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: @@ -16,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. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +.. rubric:: DESCRIPTION: -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. +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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE @@ -42,29 +76,37 @@ 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 0. +.. 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE @@ -73,25 +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. + +.. rubric:: DEFAULT VALUE: + +The default value is 512. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the minimum size of a buffer +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: -OPTION TYPE: - This configuration option is an integer define. +* The value of the configuration option shall be greater than or equal to zero. -DEFAULT VALUE: - The default value is 512. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. Generated from spec:/acfg/if/bdbuf-cache-memory-size -DESCRIPTION: - The value of this configuration option defines the minimum size of a buffer - in bytes. +.. raw:: latex -NOTES: - None. + \clearpage .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE @@ -100,25 +154,37 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -DEFAULT VALUE: - The default value is 32768. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``SIZE_MAX``. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +The default value is 32768. + +.. rubric:: DESCRIPTION: + +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 @@ -127,27 +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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the maximum blocks per +read-ahead request. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +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. -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. +.. 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-max-write-blocks + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS @@ -156,25 +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: + +The value of this configuration option defines the maximum blocks per write +request. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 16. +The following constraints apply to this configuration option: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the maximum blocks per write - 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: - None. +.. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY @@ -183,24 +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: + +The default value is 15. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 15. +The value of this configuration option defines the read-ahead task priority. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the read-ahead 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. -NOTES: - None. +.. Generated from spec:/acfg/if/bdbuf-task-stack-size + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE @@ -209,35 +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`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``RTEMS_MINIMUM_STACK_SIZE``. +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The following constraints apply to this configuration option: - * 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 value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. - * 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``. +* 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. -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 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>`_. -NOTES: - None. +.. Generated from spec:/acfg/if/bdbuf-swapout-block-hold + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD @@ -246,25 +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. + +.. rubric:: DEFAULT VALUE: + +The default value is 1000. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 1000. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the swapout task maximum block - hold time 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-swap-period + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD @@ -273,25 +397,37 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. 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 250. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +The default value is 250. -DESCRIPTION: - The value of this configuration option 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 @@ -300,24 +436,33 @@ 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. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task priority. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: CONSTRAINTS: -DEFAULT VALUE: - The default value is 15. +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. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities is scheduler-specific. +.. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks -DESCRIPTION: - The value of this configuration option defines the swapout task priority. +.. raw:: latex -NOTES: - None. + \clearpage .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS @@ -326,24 +471,36 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_SWAPOUT_WORKER_TASKS`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to ``UINT32_MAX``. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +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 @@ -352,22 +509,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 is scheduler-specific. +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. |