diff options
Diffstat (limited to 'c-user/config/bdbuf.rst')
-rw-r--r-- | c-user/config/bdbuf.rst | 543 |
1 files changed, 348 insertions, 195 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 8f49c89..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,14 +1,24 @@ .. 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 was automatically generated. Do not edit it manually. -.. Please have a look at +.. 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://docs.rtems.org/branches/master/eng/req/howto.html +.. https://www.rtems.org/bugs.html .. -.. for information how to maintain and re-generate this file. +.. 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 ================================ @@ -16,6 +26,12 @@ 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: @@ -23,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: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -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:: 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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE @@ -49,29 +76,37 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 4096. +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 0. +The default value is 4096. - * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - in bytes. +The value of this configuration option defines the maximum 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 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 @@ -80,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: -OPTION TYPE: - This configuration option is an integer define. +The following constraints apply to this configuration option: -DEFAULT VALUE: - The default value is 512. +* The value of the configuration option shall be greater than or equal to zero. -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. -DESCRIPTION: - The value of this configuration option defines the minimum size of a buffer - in bytes. +.. Generated from spec:/acfg/if/bdbuf-cache-memory-size -NOTES: - None. +.. raw:: latex + + \clearpage .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE @@ -107,25 +154,37 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 32768. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the size of the cache memory +in bytes. -DEFAULT VALUE: - The default value is 32768. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +* 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 + `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 @@ -134,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: -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 be greater than or equal to 0 - and 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 +read-ahead request. -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +.. rubric:: NOTES: -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. +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 @@ -163,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: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum blocks per write +request. -DEFAULT VALUE: - The default value is 16. +.. rubric:: CONSTRAINTS: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option 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 @@ -190,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: -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 read-ahead task priority. -DESCRIPTION: - The value of this configuration option 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 @@ -216,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: -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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD @@ -253,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: -OPTION TYPE: - This configuration option is an integer define. +The default value is 1000. -DEFAULT VALUE: - The default value is 1000. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. -DESCRIPTION: - The value of this configuration option defines the swapout task maximum block - hold time in milliseconds. +.. 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-swap-period + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD @@ -280,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 <https://en.cppreference.com/w/c/types/integer>`_. +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 @@ -307,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 @@ -333,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 <https://en.cppreference.com/w/c/types/integer>`_. +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 @@ -359,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. |