diff options
Diffstat (limited to 'c-user/config/bdbuf.rst')
-rw-r--r-- | c-user/config/bdbuf.rst | 499 |
1 files changed, 308 insertions, 191 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index 7377bee..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,6 +1,6 @@ .. 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 @@ -28,6 +28,10 @@ This section describes configuration options related to the Block Device Cache .. Generated from spec:/acfg/if/appl-needs-libblock +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK .. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: @@ -35,27 +39,36 @@ 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 .. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: @@ -63,32 +76,38 @@ 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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 4096. +The default value is 4096. -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 0. +The value of this configuration option defines the maximum size of a buffer +in bytes. - * It shall be an integral multiple of :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - 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 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 .. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: @@ -96,28 +115,38 @@ 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. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 512. +The default value is 512. -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>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option 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 .. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: @@ -125,28 +154,38 @@ 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 be greater than or equal to 0 - and less than or equal to `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +The default value is 32768. -NOTES: - None. +.. 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 .. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: @@ -154,30 +193,44 @@ 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 <https://en.cppreference.com/w/c/types/integer>`_. +.. 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 .. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: @@ -185,28 +238,38 @@ NOTES: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 16. +This configuration option is an integer define. -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>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per write - request. +The default value is 16. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the maximum blocks per write +request. + +.. 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-read-ahead-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY .. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: @@ -214,27 +277,34 @@ 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: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 15. +.. rubric:: DEFAULT VALUE: -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 default value is 15. -DESCRIPTION: - The value of this configuration option defines the read-ahead task priority. +.. rubric:: DESCRIPTION: -NOTES: - None. +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 +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE .. _CONFIGURE_BDBUF_TASK_STACK_SIZE: @@ -242,38 +312,45 @@ NOTES: CONFIGURE_BDBUF_TASK_STACK_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_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 :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. - * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: - * 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 this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. - * 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>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option 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 .. _CONFIGURE_SWAPOUT_BLOCK_HOLD: @@ -281,28 +358,38 @@ 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 <https://en.cppreference.com/w/c/types/integer>`_. +.. 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 .. _CONFIGURE_SWAPOUT_SWAP_PERIOD: @@ -310,28 +397,38 @@ 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 be greater than or equal to 0 - and less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the swapout task swap period - in milliseconds. +The value of this configuration option defines the swapout task swap period +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-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_TASK_PRIORITY: @@ -339,27 +436,34 @@ NOTES: CONFIGURE_SWAPOUT_TASK_PRIORITY ------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_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 is scheduler-specific. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the swapout task priority. +The default value is 15. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout 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-swapout-worker-tasks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS .. _CONFIGURE_SWAPOUT_WORKER_TASKS: @@ -367,27 +471,37 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASKS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -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>`_. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +The default value is 0. -NOTES: - None. +.. 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: @@ -395,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. |