diff options
| author | Chris Johns <chrisj@rtems.org> | 2016-11-03 16:58:08 +1100 |
|---|---|---|
| committer | Chris Johns <chrisj@rtems.org> | 2016-11-03 16:58:08 +1100 |
| commit | 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 (patch) | |
| tree | 6b0e527e67141f8126ba56b8a3c1eb90aeed5849 /c_user/configuring_a_system.rst | |
| parent | waf: Use separate doctrees so avoid sphinx clashes. (diff) | |
| download | rtems-docs-72a62ad88f82fe1ffee50024db4dd0f3fa5806f7.tar.bz2 | |
Rename all manuals with an _ to have a -. It helps released naming of files.
Diffstat (limited to 'c_user/configuring_a_system.rst')
| -rw-r--r-- | c_user/configuring_a_system.rst | 5345 |
1 files changed, 0 insertions, 5345 deletions
diff --git a/c_user/configuring_a_system.rst b/c_user/configuring_a_system.rst deleted file mode 100644 index e993877..0000000 --- a/c_user/configuring_a_system.rst +++ /dev/null @@ -1,5345 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 1988-2008. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: All rights reserved. - -.. _Configuring a System: - -Configuring a System -#################### - -.. index:: configuring a system - -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves should only -rarely to be generated by hand. RTEMS provides a set of macros system which -provides a simple standard mechanism to automate the generation of these -structures. - -.. index:: confdefs.h -.. index:: confdefs.h -.. index:: <rtems/confdefs.h> -.. index:: <rtems/confdefs.h> - -The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic -generation of system configuration. It is based on the idea of setting macros -which define configuration parameters of interest to the application and -defaulting or calculating all others. This variety of macros can automatically -produce all of the configuration data required for an RTEMS application. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with with the POSIX standard. - -For each configuration parameter in the configuration tables, the macro -corresponding to that field is discussed. The RTEMS Maintainers expect that all -systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - -.. COMMENT: === Philosophy === - -Default Value Selection Philosophy -================================== - -The user should be aware that the defaults are intentionally set as low as -possible. By default, no application resources are configured. The -``<rtems/confdefs.h>`` file ensures that at least one application task or -thread is configured and that at least one of the initialization task/thread -tables is configured. - -.. COMMENT: === Sizing the RTEMS Workspace === - -.. _Sizing the RTEMS Workspace: - -Sizing the RTEMS Workspace -========================== - -The RTEMS Workspace is a user-specified block of memory reserved for use by -RTEMS. The application should NOT modify this memory. This area consists -primarily of the RTEMS data structures whose exact size depends upon the values -specified in the Configuration Table. In addition, task stacks and floating -point context areas are dynamically allocated from the RTEMS Workspace. - -The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace -automatically. It assumes that all tasks are floating point and that all will -be allocated the minimum stack space. This calculation includes the amount of -memory that will be allocated for internal use by RTEMS. The automatic -calculation may underestimate the workspace size truly needed by the -application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro -to add a value to the estimate. See :ref:`Specify Memory Overhead` for more -details. - -The memory area for the RTEMS Workspace is determined by the BSP. In case the -RTEMS Workspace is too large for the available memory, then a fatal run-time -error occurs and the system terminates. - -The file ``<rtems/confdefs.h>`` will calculate the value of the -``work_space_size`` parameter of the Configuration Table. There are many -parameters the application developer can specify to help ``<rtems/confdefs.h>`` -in its calculations. Correctly specifying the application requirements via -parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and -``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. - -For each class of objects, the allocation can operate in one of two ways. The -default way has an ceiling on the maximum number of object instances which can -concurrently exist in the system. Memory for all instances of that object class -is reserved at system initialization. The second way allocates memory for an -initial number of objects and increases the current allocation by a fixed -increment when required. Both ways allocate space from inside the RTEMS -Workspace. - -See :ref:`Unlimited Objects` for more details about the second way, which -allows for dynamic allocation of objects and therefore does not provide -determinism. This mode is useful mostly for when the number of objects cannot -be determined ahead of time or when porting software for which you do not know -the object requirements. - -The space needed for stacks and for RTEMS objects will vary from one version of -RTEMS and from one target processor to another. Therefore it is safest to use -``<rtems/confdefs.h>`` and specify your application's requirements in terms of -the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as -is possible. The automatic estimates of space required will in general change -when: - -- a configuration parameter is changed, - -- task or interrupt stack sizes change, - -- the floating point attribute of a task changes, - -- task floating point attribute is altered, - -- RTEMS is upgraded, or - -- the target processor is changed. - -Failure to provide enough space in the RTEMS Workspace may result in fatal -run-time errors terminating the system. - -.. COMMENT: === Potential Issues === - -Potential Issues with RTEMS Workspace Size Estimation -===================================================== - -The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the -RTEMS Workspace. This estimate is only as accurate as the information given to -``<rtems/confdefs.h>`` and may be either too high or too low for a variety of -reasons. Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much -memory for RTEMS are: - -- All tasks/threads are assumed to be floating point. - -Conversely, there are many more reasons that the resource estimate could be too -low: - -- Task/thread stacks greater than minimum size must be accounted for explicitly - by developer. - -- Memory for messages is not included. - -- Device driver requirements are not included. - -- Network stack requirements are not included. - -- Requirements for add-on libraries are not included. - -In general, ``<rtems/confdefs.h>`` is very accurate when given enough -information. However, it is quite easy to use a library and forget to account -for its resources. - -.. COMMENT: === Format to be followed for making changes in this file === - -Format to be followed for making changes in this file -===================================================== - -*MACRO NAME:*: - Should be alphanumeric. Can have '_' (underscore). - -*DATA TYPE:* - Please refer to all existing formats. - -*RANGE:* - The range depends on the Data Type of the macro. - - - If the data type is of type task priority, then its value should be an - integer in the range of 1 to 255. - - - If the data type is an integer, then it can have numbers, characters (in - case the value is defined using another macro) and arithmetic operations - (+, -, \*, /). - - - If the data type is a function pointer the first character should be an - alphabet or an underscore. The rest of the string can be alphanumeric. - - - If the data type is RTEMS Attributes or RTEMS Mode then the string should - be alphanumeric. - - - If the data type is RTEMS NAME then the value should be an integer>=0 or - RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' ) - -*DEFAULT VALUE:* - The default value should be in the following formats- Please note that the - '.' (full stop) is necessary. - - - In case the value is not defined then: This is not defined by default. - - - If we know the default value then: The default value is XXX. - - - If the default value is BSP Specific then: This option is BSP specific. - -*DESCRIPTION:* - The description of the macro. (No specific format) - -*NOTES:* - Any further notes. (No specific format) - -.. COMMENT: === Configuration Example === - -Configuration Example -===================== - -In the following example, the configuration information for a system with a -single message queue, four (4) tasks, and a timeslice of fifty (50) -milliseconds is as follows: - -.. code-block:: c - - #include <bsp.h> - #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - #define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */ - #define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */ - #define CONFIGURE_RTEMS_INIT_TASKS_TABLE - #define CONFIGURE_MAXIMUM_TASKS 4 - #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1 - #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE)) - #define CONFIGURE_INIT - #include <rtems/confdefs.h> - -In this example, only a few configuration parameters are specified. The impact -of these are as follows: - -- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify - any additional parameters. This results in a configuration of an application - which will begin execution of a single initialization task named ``Init`` - which is non-preemptible and at priority one (1). - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application - is configured to have a clock tick device driver. Without a clock tick device - driver, RTEMS has no way to know that time is passing and will be unable to - support delays and wall time. Further configuration details about time are - provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and - ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock - tick to occur each millisecond, and that the length of a timeslice would be - fifty (50) milliseconds. - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application - will include a console device driver. Although the console device driver may - support a combination of multiple serial ports and display and keyboard - combinations, it is only required to provide a single device named - ``/dev/console``. This device will be used for Standard Input, Output and - Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - is specified, implicitly three (3) file descriptors are reserved for the - Standard I/O Streams and those file descriptors are associated with - ``/dev/console`` during initialization. All console devices are expected to - support the POSIX*termios* interface. - -- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the - application requires a maximum of four (4) simultaneously existing Classic - API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, - there may be a maximum of only one (1) concurrently existent Classic API - message queues. - -- The most surprising configuration parameter in this example is the use of - ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from - the RTEMS Workspace and must be accounted for. In this example, the single - message queue will have up to twenty (20) messages of type ``struct - USER_MESSAGE``. - -- The ``CONFIGURE_INIT`` constant must be defined in order to make - ``<rtems/confdefs.h>`` instantiate the configuration data structures. This - can only be defined in one source file per application that includes - ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple - times and linking errors produced. - -This example illustrates that parameters have default values. Among other -things, the application implicitly used the following defaults: - -- All unspecified types of communications and synchronization objects in the - Classic and POSIX Threads API have maximums of zero (0). - -- The filesystem will be the default filesystem which is the In-Memory File - System (IMFS). - -- The application will have the default number of priority levels. - -- The minimum task stack size will be that recommended by RTEMS for the target - architecture. - -.. COMMENT: === Unlimited Objects === - -.. _Unlimited Objects: - -Unlimited Objects ------------------ - -In real-time embedded systems the RAM is normally a limited, critical resource -and dynamic allocation is avoided as much as possible to ensure predictable, -deterministic execution times. For such cases, see :ref:`Sizing the RTEMS -Workspace` for an overview of how to tune the size of the workspace. -Frequently when users are porting software to RTEMS the precise resource -requirements of the software is unknown. In these situations users do not need -to control the size of the workspace very tightly because they just want to get -the new software to run; later they can tune the workspace size as needed. - -The following API-independent object classes can be configured in unlimited -mode: - -- POSIX Keys - -- POSIX Key Value Pairs - -The following object classes in the Classic API can be configured in unlimited -mode: - -- Tasks - -- Timers - -- Semaphores - -- Message Queues - -- Periods - -- Barriers - -- Partitions - -- Regions - -- Ports - -Additionally, the following object classes from the POSIX API can be configured -in unlimited mode: - -- Threads - -- Mutexes - -- Condition Variables - -- Timers - -- Message Queues - -- Message Queue Descriptors - -- Semaphores - -- Barriers - -- Read/Write Locks - -- Spinlocks - -The following object classes can *not* be configured in unlimited mode: - -- Drivers - -- File Descriptors - -- User Extensions - -- POSIX Queued Signals - -Due to the memory requirements of unlimited objects it is strongly recommended -to use them only in combination with the unified work areas. See :ref:`Separate -or Unified Work Areas` for more information on unified work areas. - -The following example demonstrates how the two simple configuration defines for -unlimited objects and unified works areas can replace many seperate -configuration defines for supported object classes: - -.. code-block:: c - - #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - #define CONFIGURE_UNIFIED_WORK_AREAS - #define CONFIGURE_UNLIMITED_OBJECTS - #define CONFIGURE_RTEMS_INIT_TASKS_TABLE - #define CONFIGURE_INIT - #include <rtems/confdefs.h> - -Users are cautioned that using unlimited objects is not recommended for -production software unless the dynamic growth is absolutely required. It is -generally considered a safer embedded systems programming practice to know the -system limits rather than experience an out of memory error at an arbitrary and -largely unpredictable time in the field. - -.. COMMENT: === Per Object Class Unlimited Object Instances === - -.. _Per Object Class Unlimited Object Instances: - -Per Object Class Unlimited Object Instances -------------------------------------------- -.. index:: rtems_resource_unlimited - -When the number of objects is not known ahead of time, RTEMS provides an -auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a -parameter, and is used to set the object maximum number field in an API -Configuration table. The value is an allocation unit size. When RTEMS is -required to grow the object table it is grown by this size. The kernel will -return the object memory back to the RTEMS Workspace when an object is -destroyed. The kernel will only return an allocated block of objects to the -RTEMS Workspace if at least half the allocation size of free objects remain -allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: - -.. code-block:: c - - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation - -Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. - -.. COMMENT: === Unlimited Object Instances === - -.. _Unlimited Object Instances: - -Unlimited Object Instances --------------------------- - -To ease the burden of developers who are porting new software RTEMS also -provides the capability to make all object classes listed above operate in -unlimited mode in a simple manner. The application developer is only -responsible for enabling unlimited objects and specifying the allocation size. - -.. COMMENT: === CONFIGURE_UNLIMITED_OBJECTS === - -.. _Enable Unlimited Object Instances: - -Enable Unlimited Object Instances ---------------------------------- -.. index:: CONFIGURE_UNLIMITED_OBJECTS - -*CONSTANT:* - ``CONFIGURE_UNLIMITED_OBJECTS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited`` mode for -Classic API and POSIX API objects that do not already have a specific maximum -limit defined. - -**NOTES:** - -When using unlimited objects, it is common practice to also specify -``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single pool of -memory for both RTEMS and application memory allocations. - -.. COMMENT: === CONFIGURE_UNLIMITED_ALLOCATION_SIZE === - -.. _Specify Unlimited Objects Allocation Size: - -Specify Unlimited Objects Allocation Size ------------------------------------------ - -*CONSTANT:* - ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, - the default value is eight (8). - -**DESCRIPTION:** - -``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an allocation size to use for -``rtems_resource_unlimited`` when using ``CONFIGURE_UNLIMITED_OBJECTS``. - -**NOTES:** - -By allowing users to declare all resources as being unlimited the user can -avoid identifying and limiting the resources -used. ``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the allocation -sizes for different objects; users who want that much control can define the -``rtems_resource_unlimited`` macros themselves. - -.. code-block:: c - - #define CONFIGURE_UNLIMITED_OBJECTS - #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 - -.. COMMENT: === Classic API Configuration === - -Classic API Configuration -========================= - -This section defines the Classic API related system configuration parameters -supported by ``<rtems/confdefs.h>``. - -.. COMMENT: === CONFIGURE_MAXIMUM_TASKS === - -.. _Specify Maximum Classic API Tasks: - -Specify Maximum Classic API Tasks ---------------------------------- -.. index:: CONFIGURE_MAXIMUM_TASKS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_TASKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that can -be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -The calculations for the required memory in the RTEMS Workspace for tasks -assume that each task has a minimum stack size and has floating point support -enabled. The configuration parameter ``CONFIGURE_EXTRA_TASK_STACKS`` is used -to specify task stack requirements *ABOVE* the minimum size required. See -:ref:`Reserve Task/Thread Stack Memory Above Minimum` for more information -about ``CONFIGURE_EXTRA_TASK_STACKS``. - -The maximum number of POSIX threads is specified by -``CONFIGURE_MAXIMUM_POSIX_THREADS``. - -.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS. - -A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the -assumption that all tasks have floating point enabled. This would require the -addition of a new configuration parameter to specify the number of tasks which -enable floating point support. - -.. COMMENT: === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS === - -.. _Specify Maximum Classic API Timers: - -Specify Maximum Classic API Timers ----------------------------------- -.. index:: CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS - -*CONSTANT:* - ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, and Classic API Notepads are not supported. - -**DESCRIPTION:** - ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` should be defined if the - user wants to have support for Classic API Notepads in their application. - -**NOTES:** - Disabling Classic API Notepads saves the allocation of sixteen (16) - thirty-two bit integers. This saves sixty-four bytes per task/thread - plus the allocation overhead. Notepads are rarely used in applications - and this can save significant memory in a low RAM system. Classic API - Notepads are deprecated, and this option has been removed from - post 4.11 versions of RTEMS. - -.. COMMENT: === CONFIGURE_MAXIMUM_TIMERS === - -.. _Specify Maximum Classic API Timers: - -Specify Maximum Classic API Timers ----------------------------------- -.. index:: CONFIGURE_MAXIMUM_TIMERS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_TIMERS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers that -can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_SEMAPHORES === - -.. _Specify Maximum Classic API Semaphores: - -Specify Maximum Classic API Semaphores --------------------------------------- -.. index:: CONFIGURE_MAXIMUM_SEMAPHORES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_SEMAPHORES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API -Semaphores that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES === - -.. _Specify Maximum Classic API Semaphores usable with MrsP: - -Specify Maximum Classic API Semaphores usable with MrsP -------------------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API -Semaphores using the Multiprocessor Resource Sharing Protocol (MrsP) that can -be concurrently active. - -**NOTES:** - -This configuration option is only used on SMP configurations. On uni-processor -configurations the Priority Ceiling Protocol is used for MrsP semaphores and -thus no extra memory is necessary. - -.. COMMENT: === CONFIGURE_MAXIMUM_MESSAGE_QUEUES === - -.. _Specify Maximum Classic API Message Queues: - -Specify Maximum Classic API Message Queues ------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API -Message Queues that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_BARRIERS === - -.. _Specify Maximum Classic API Barriers: - -Specify Maximum Classic API Barriers ------------------------------------- -.. index:: CONFIGURE_MAXIMUM_BARRIERS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_BARRIERS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API Barriers -that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_PERIODS === - -.. _Specify Maximum Classic API Periods: - -Specify Maximum Classic API Periods ------------------------------------ -.. index:: CONFIGURE_MAXIMUM_PERIODS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_PERIODS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods that -can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_PARTITIONS === - -.. _Specify Maximum Classic API Partitions: - -Specify Maximum Classic API Partitions --------------------------------------- -.. index:: CONFIGURE_MAXIMUM_PARTITIONS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_PARTITIONS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API -Partitions that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_REGIONS === - -.. _Specify Maximum Classic API Regions: - -Specify Maximum Classic API Regions ------------------------------------ -.. index:: CONFIGURE_MAXIMUM_REGIONS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_REGIONS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions that -can be concurrently active. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MAXIMUM_PORTS === - -.. _Specify Maximum Classic API Ports: - -Specify Maximum Classic API Ports ---------------------------------- -.. index:: CONFIGURE_MAXIMUM_PORTS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_PORTS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that can -be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_USER_EXTENSIONS === - -.. _Specify Maximum Classic API User Extensions: - -Specify Maximum Classic API User Extensions -------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API User -Extensions that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === Classic API Initialization Task Configuration === - -Classic API Initialization Tasks Table Configuration -==================================================== - -The ``<rtems/confdefs.h>`` configuration system can automatically generate an -Initialization Tasks Table named ``Initialization_tasks`` with a single entry. -The following parameters control the generation of that table. - -.. COMMENT: === CONFIGURE_RTEMS_INIT_TASKS_TABLE === - -.. _Instantiate Classic API Initialization Task Table: - -Instantiate Classic API Initialization Task Table -------------------------------------------------- -.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE - -*CONSTANT:* - ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes to use a -Classic RTEMS API Initialization Task Table. The table built by -``<rtems/confdefs.h>`` specifies the parameters for a single task. This is -sufficient for applications which initialization the system from a single task. - -By default, this field is not defined as the user MUST select their own API for -initialization tasks. - -**NOTES:** - -The application may choose to use the initialization tasks or threads table -from another API. - -A compile time error will be generated if the user does not configure any -initialization tasks or threads. - -.. COMMENT: === CONFIGURE_INIT_TASK_ENTRY_POINT === - -.. _Specifying Classic API Initialization Task Entry Point: - -Specifying Classic API Initialization Task Entry Point ------------------------------------------------------- -.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` - -*DATA TYPE:* - Task entry function pointer (``rtems_task_entry``). - -*RANGE:* - Valid task entry function pointer. - -*DEFAULT VALUE:* - The default value is ``Init``. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function name) -of the single initialization task defined by the Classic API Initialization -Tasks Table. - -**NOTES:** - -The user must implement the function ``Init`` or the function name provided in -this configuration parameter. - -.. COMMENT: === CONFIGURE_INIT_TASK_NAME === - -.. _Specifying Classic API Initialization Task Name: - -Specifying Classic API Initialization Task Name ------------------------------------------------ -.. index:: CONFIGURE_INIT_TASK_NAME - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_NAME`` - -*DATA TYPE:* - RTEMS Name (``rtems_name``). - -*RANGE:* - Any value. - -*DEFAULT VALUE:* - The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task -defined by the Classic API Initialization Tasks Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_INIT_TASK_STACK_SIZE === - -.. _Specifying Classic API Initialization Task Stack Size: - -Specifying Classic API Initialization Task Stack Size ------------------------------------------------------ -.. index:: CONFIGURE_INIT_TASK_STACK_SIZE - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is RTEMS_MINIMUM_STACK_SIZE. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single -initialization task defined by the Classic API Initialization Tasks Table. - -**NOTES:** - -If the stack size specified is greater than the configured minimum, it must be -accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve -Task/Thread Stack Memory Above Minimum` for more information about -``CONFIGURE_EXTRA_TASK_STACKS``. - -.. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY === - -.. _Specifying Classic API Initialization Task Priority: - -Specifying Classic API Initialization Task Priority ---------------------------------------------------- -.. index:: CONFIGURE_INIT_TASK_PRIORITY - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_PRIORITY`` - -*DATA TYPE:* - RTEMS Task Priority (``rtems_task_priority``). - -*RANGE:* - One (1) to CONFIGURE_MAXIMUM_PRIORITY. - -*DEFAULT VALUE:* - The default value is 1, which is the highest priority in the - Classic API. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single -initialization task defined by the Classic API Initialization Tasks Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_INIT_TASK_ATTRIBUTES === - -.. _Specifying Classic API Initialization Task Attributes: - -Specifying Classic API Initialization Task Attributes ------------------------------------------------------ -.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` - -*DATA TYPE:* - RTEMS Attributes (``rtems_attribute``). - -*RANGE:* - Valid task attribute sets. - -*DEFAULT VALUE:* - The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single -initialization task defined by the Classic API Initialization Tasks Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_INIT_TASK_INITIAL_MODES === - -.. _Specifying Classic API Initialization Task Modes: - -Specifying Classic API Initialization Task Modes ------------------------------------------------- -.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` - -*DATA TYPE:* - RTEMS Mode (``rtems_mode``). - -*RANGE:* - Valid task mode sets. - -*DEFAULT VALUE:* - The default value is ``RTEMS_NO_PREEMPT``. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the -single initialization task defined by the Classic API Initialization Tasks -Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_INIT_TASK_ARGUMENTS === - -.. _Specifying Classic API Initialization Task Arguments: - -Specifying Classic API Initialization Task Arguments ----------------------------------------------------- -.. index:: CONFIGURE_INIT_TASK_ARGUMENTS - -*CONSTANT:* - ``CONFIGURE_INIT_TASK_ARGUMENTS`` - -*DATA TYPE:* - RTEMS Task Argument (``rtems_task_argument``). - -*RANGE:* - Complete range of the type. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single -initialization task defined by the Classic API Initialization Tasks Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_HAS_OWN_INIT_TASK_TABLE === - -.. _Not Using Generated Initialization Tasks Table: - -Not Using Generated Initialization Tasks Table ----------------------------------------------- -.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE - -*CONSTANT:* - ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to define -their own Classic API Initialization Tasks Table. This table should be named -``Initialization_tasks``. - -**NOTES:** - -This is a seldom used configuration parameter. The most likely use case is when -an application desires to have more than one initialization task. - -.. COMMENT: === POSIX API Configuration === - -POSIX API Configuration -======================= - -The parameters in this section are used to configure resources for the RTEMS -POSIX API. They are only relevant if the POSIX API is enabled at configure -time using the ``--enable-posix`` option. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_THREADS === - -.. _Specify Maximum POSIX API Threads: - -Specify Maximum POSIX API Threads ---------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API -Threads that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -This calculations for the required memory in the RTEMS Workspace for threads -assume that each thread has a minimum stack size and has floating point support -enabled. The configuration parameter ``CONFIGURE_EXTRA_TASK_STACKS`` is used -to specify thread stack requirements *ABOVE* the minimum size required. See -:ref:`Reserve Task/Thread Stack Memory Above Minimum` for more information -about ``CONFIGURE_EXTRA_TASK_STACKS``. - -The maximum number of Classic API Tasks is specified by -``CONFIGURE_MAXIMUM_TASKS``. - -All POSIX threads have floating point enabled. - -.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_TASKS. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MUTEXES === - -.. _Specify Maximum POSIX API Mutexes: - -Specify Maximum POSIX API Mutexes ---------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX API Mutexes -that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES === - -.. _Specify Maximum POSIX API Condition Variables: - -Specify Maximum POSIX API Condition Variables ---------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number of POSIX -API Condition Variables that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_KEYS === - -.. _Specify Maximum POSIX API Keys: - -Specify Maximum POSIX API Keys ------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys that -can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: XXX - Key pairs - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_TIMERS === - -.. _Specify Maximum POSIX API Timers: - -Specify Maximum POSIX API Timers --------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API Timers -that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS === - -.. _Specify Maximum POSIX API Queued Signals: - -Specify Maximum POSIX API Queued Signals ----------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX API -Queued Signals that can be concurrently active. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES === - -.. _Specify Maximum POSIX API Message Queues: - -Specify Maximum POSIX API Message Queues ----------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX API -Message Queues that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: XXX - memory for buffers note - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS === - -.. _Specify Maximum POSIX API Message Queue Descriptors: - -Specify Maximum POSIX API Message Queue Descriptors ---------------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES`` - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum number of -POSIX API Message Queue Descriptors that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be greater than or -equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES === - -.. _Specify Maximum POSIX API Semaphores: - -Specify Maximum POSIX API Semaphores ------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API -Semaphores that can be concurrently active. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_BARRIERS === - -.. _Specify Maximum POSIX API Barriers: - -Specify Maximum POSIX API Barriers ----------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX API -Barriers that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS === - -.. _Specify Maximum POSIX API Spinlocks: - -Specify Maximum POSIX API Spinlocks ------------------------------------ -.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX API -Spinlocks that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_RWLOCKS === - -.. _Specify Maximum POSIX API Read/Write Locks: - -Specify Maximum POSIX API Read/Write Locks ------------------------------------------- -.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX API -Read/Write Locks that can be concurrently active. - -**NOTES:** - -This object class can be configured in unlimited allocation mode. - -.. COMMENT: === POSIX Initialization Threads Table Configuration === - -POSIX Initialization Threads Table Configuration -================================================ - -The ``<rtems/confdefs.h>`` configuration system can automatically generate a -POSIX Initialization Threads Table named ``POSIX_Initialization_threads`` with -a single entry. The following parameters control the generation of that table. - -.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_TABLE === - -.. _Instantiate POSIX API Initialization Thread Table: - -Instantiate POSIX API Initialization Thread Table -------------------------------------------------- -.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE - -*CONSTANT:* - .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This field is not defined by default, as the user MUST select their own API - for initialization tasks. - -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes to use a -POSIX API Initialization Threads Table. The table built by -``<rtems/confdefs.h>`` specifies the parameters for a single thread. This is -sufficient for applications which initialization the system from a single task. - -By default, this field is not defined as the user MUST select their own API for -initialization tasks. - -**NOTES:** - -The application may choose to use the initialization tasks or threads table -from another API. - -A compile time error will be generated if the user does not configure any -initialization tasks or threads. - -.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT === - -.. _Specifying POSIX API Initialization Thread Entry Point: - -Specifying POSIX API Initialization Thread Entry Point ------------------------------------------------------- -.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT - -*CONSTANT:* - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` - -*DATA TYPE:* - POSIX thread function pointer (``void *(*entry_point)(void *)``). - -*RANGE:* - Undefined or a valid POSIX thread function pointer. - -*DEFAULT VALUE:* - The default value is ``POSIX_Init``. - -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point (a.k.a. function -name) of the single initialization thread defined by the POSIX API -Initialization Threads Table. - -**NOTES:** - -The user must implement the function ``POSIX_Init`` or the function name -provided in this configuration parameter. - -.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE === - -.. _Specifying POSIX API Initialization Thread Stack Size: - -Specifying POSIX API Initialization Thread Stack Size ------------------------------------------------------ -.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE - -*CONSTANT:* - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. - -**DESCRIPTION:** - -``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single -initialization thread defined by the POSIX API Initialization Threads Table. - -**NOTES:** - -If the stack size specified is greater than the configured minimum, it must be -accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve -Task/Thread Stack Memory Above Minimum` for more information about -``CONFIGURE_EXTRA_TASK_STACKS``. - -.. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE === - -.. _Not Using Generated POSIX Initialization Threads Table: - -Not Using Generated POSIX Initialization Threads Table ------------------------------------------------------- -.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE - -*CONSTANT:* - ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes to -define their own POSIX API Initialization Threads Table. This table should be -named ``POSIX_Initialization_threads``. - -**NOTES:** - -This is a seldom used configuration parameter. The most likely use case is when -an application desires to have more than one initialization task. - -.. COMMENT: === Basic System Information === - -Basic System Information -======================== - -This section defines the general system configuration parameters supported by -``<rtems/confdefs.h>``. - -.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS === - -.. _Separate or Unified Work Areas: - -Separate or Unified Work Areas ------------------------------- -.. index:: CONFIGURE_UNIFIED_WORK_AREAS -.. index:: unified work areas -.. index:: separate work areas -.. index:: RTEMS Workspace -.. index:: C Program Heap - -*CONSTANT:* - ``CONFIGURE_UNIFIED_WORK_AREAS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, which specifies that the C Program Heap and - the RTEMS Workspace will be separate. - -**DESCRIPTION:** - -When defined, the C Program Heap and the RTEMS Workspace will be one pool of -memory. - -When not defined, there will be separate memory pools for the RTEMS Workspace -and C Program Heap. - -**NOTES:** - -Having separate pools does have some advantages in the event a task blows a -stack or writes outside its memory area. However, in low memory systems the -overhead of the two pools plus the potential for unused memory in either pool -is very undesirable. - -In high memory environments, this is desirable when you want to use the RTEMS -"unlimited" objects option. You will be able to create objects until you run -out of all available memory rather then just until you run out of RTEMS -Workspace. - -.. COMMENT: === CONFIGURE_MICROSECONDS_PER_TICK === - -.. _Length of Each Clock Tick: - -Length of Each Clock Tick -------------------------- -.. index:: CONFIGURE_MICROSECONDS_PER_TICK -.. index:: tick quantum - -*CONSTANT:* - ``CONFIGURE_MICROSECONDS_PER_TICK`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - This is not defined by default. When not defined, the clock tick quantum is - configured to be 10,000 microseconds which is ten (10) milliseconds. - -**DESCRIPTION:** - -This constant is used to specify the length of time between clock ticks. - -When the clock tick quantum value is too low, the system will spend so much -time processing clock ticks that it does not have processing time available to -perform application work. In this case, the system will become unresponsive. - -The lowest practical time quantum varies widely based upon the speed of the -target hardware and the architectural overhead associated with interrupts. In -general terms, you do not want to configure it lower than is needed for the -application. - -The clock tick quantum should be selected such that it all blocking and delay -times in the application are evenly divisible by it. Otherwise, rounding errors -will be introduced which may negatively impact the application. - -**NOTES:** - -This configuration parameter has no impact if the Clock Tick Device driver is -not configured. - -There may be BSP specific limits on the resolution or maximum value of a clock -tick quantum. - -.. COMMENT: === CONFIGURE_TICKS_PER_TIMESLICE === - -.. _Specifying Timeslicing Quantum: - -Specifying Timeslicing Quantum ------------------------------- -.. index:: CONFIGURE_TICKS_PER_TIMESLICE -.. index:: ticks per timeslice - -*CONSTANT:* - ``CONFIGURE_TICKS_PER_TIMESLICE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 50. - -**DESCRIPTION:** - -This configuration parameter specifies the length of the timeslice quantum in -ticks for each task. - -**NOTES:** - -This configuration parameter has no impact if the Clock Tick Device driver is -not configured. - -.. COMMENT: === CONFIGURE_MAXIMUM_PRIORITY === - -.. _Specifying the Number of Thread Priority Levels: - -Specifying the Number of Thread Priority Levels ------------------------------------------------ -.. index:: CONFIGURE_MAXIMUM_PRIORITY -.. index:: maximum priority -.. index:: number of priority levels - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_PRIORITY`` - -*DATA TYPE:* - Unsigned integer (``uint8_t``). - -*RANGE:* - Valid values for this configuration parameter must be one (1) less than - than a power of two (2) between 4 and 256 inclusively. In other words, - valid values are 3, 7, 31, 63, 127, and 255. - -*DEFAULT VALUE:* - The default value is 255, because RTEMS must support 256 priority levels to - be compliant with various standards. These priorities range from zero (0) - to 255. - -**DESCRIPTION:** - -This configuration parameter specified the maximum numeric priority of any task -in the system and one less that the number of priority levels in the system. - -Reducing the number of priorities in the system reduces the amount of memory -allocated from the RTEMS Workspace. - -**NOTES:** - -The numerically greatest priority is the logically lowest priority in the -system and will thus be used by the IDLE task. - -Priority zero (0) is reserved for internal use by RTEMS and is not available to -applications. - -With some schedulers, reducing the number of priorities can reduce the amount -of memory used by the scheduler. For example, the Deterministic Priority -Scheduler (DPS) used by default uses three pointers of storage per priority -level. Reducing the number of priorities from 256 levels to sixteen (16) can -reduce memory usage by about three (3) kilobytes. - -.. COMMENT: === CONFIGURE_MINIMUM_TASK_STACK_SIZE === - -.. _Specifying the Minimum Task Size: - -Specifying the Minimum Task Size --------------------------------- -.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE -.. index:: minimum task stack size - -*CONSTANT:* - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - This is not defined by default, which sets the executive to the recommended - minimum stack size for this processor. - -**DESCRIPTION:** - -The configuration parameter is set to the number of bytes the application wants -the minimum stack size to be for every task or thread in the system. - -Adjusting this parameter should be done with caution. Examining the actual -usage using the Stack Checker Usage Reporting facility is recommended. - -**NOTES:** - -This parameter can be used to lower the minimum from that recommended. This can -be used in low memory systems to reduce memory consumption for stacks. However, -this must be done with caution as it could increase the possibility of a blown -task stack. - -This parameter can be used to increase the minimum from that recommended. This -can be used in higher memory systems to reduce the risk of stack overflow -without performing analysis on actual consumption. - -.. COMMENT: === CONFIGURE_INTERRUPT_STACK_SIZE === - -.. _Configuring the Size of the Interrupt Stack: - -Configuring the Size of the Interrupt Stack -------------------------------------------- -.. index:: CONFIGURE_INTERRUPT_STACK_SIZE -.. index:: interrupt stack size - -*CONSTANT:* - ``CONFIGURE_INTERRUPT_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the - minimum interrupt stack size. - -**DESCRIPTION:** - -``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the interrupt stack. -The interrupt stack size is often set by the BSP but since this memory may be -allocated from the RTEMS Workspace, it must be accounted for. - -**NOTES:** - -In some BSPs, changing this constant does NOT change the size of the interrupt -stack, only the amount of memory reserved for it. - -Patches which result in this constant only being used in memory calculations -when the interrupt stack is intended to be allocated from the RTEMS Workspace -would be welcomed by the RTEMS Project. - -.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS === - -.. _Reserve Task/Thread Stack Memory Above Minimum: - -Reserve Task/Thread Stack Memory Above Minimum ----------------------------------------------- -.. index:: CONFIGURE_EXTRA_TASK_STACKS -.. index:: memory for task tasks - -*CONSTANT:* - ``CONFIGURE_EXTRA_TASK_STACKS`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -This configuration parameter is set to the number of bytes the applications -wishes to add to the task stack requirements calculated by -``<rtems/confdefs.h>``. - -**NOTES:** - -This parameter is very important. If the application creates tasks with stacks -larger then the minimum, then that memory is NOT accounted for by -``<rtems/confdefs.h>``. - -.. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY === - -.. _Automatically Zeroing the RTEMS Workspace and C Program Heap: - -Automatically Zeroing the RTEMS Workspace and C Program Heap ------------------------------------------------------------- -.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -.. index:: clear C Program Heap -.. index:: clear RTEMS Workspace -.. index:: zero C Program Heap -.. index:: zero RTEMS Workspace - -*CONSTANT:* - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, unless overridden by the BSP. The default - is *NOT* to zero out the RTEMS Workspace or C Program Heap. - -**DESCRIPTION:** - -This macro indicates whether RTEMS should zero the RTEMS Workspace and C -Program Heap as part of its initialization. If defined, the memory regions are -zeroed. Otherwise, they are not. - -**NOTES:** - -Zeroing memory can add significantly to system boot time. It is not necessary -for RTEMS but is often assumed by support libraries. - -.. COMMENT: === CONFIGURE_STACK_CHECKER_ENABLED === - -.. _Enable The Task Stack Usage Checker: - -Enable The Task Stack Usage Checker ------------------------------------ -.. index:: CONFIGURE_STACK_CHECKER_ENABLED - -*CONSTANT:* - ``CONFIGURE_STACK_CHECKER_ENABLED`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, and thus stack checking is disabled. - -**DESCRIPTION:** - -This configuration parameter is defined when the application wishes to enable -run-time stack bounds checking. - -**NOTES:** - -In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``. - -This increases the time required to create tasks as well as adding overhead to -each context switch. - -.. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS === - -.. _Specify Application Specific User Extensions: - -Specify Application Specific User Extensions --------------------------------------------- -.. index:: CONFIGURE_INITIAL_EXTENSIONS - -*CONSTANT:* - ``CONFIGURE_INITIAL_EXTENSIONS`` - -*DATA TYPE:* - List of user extension initializers (``rtems_extensions_table``). - -*RANGE:* - Undefined or a list of one or more user extensions. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then this -application specific set of initial extensions will be placed in the initial -extension table. - -**NOTES:** - -None. - -.. COMMENT: === Custom Stack Allocator === - -Configuring Custom Task Stack Allocation -======================================== - -RTEMS allows the application or BSP to define its own allocation and -deallocation methods for task stacks. This can be used to place task stacks in -special areas of memory or to utilize a Memory Management Unit so that stack -overflows are detected in hardware. - -.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR_INIT === - -.. _Custom Task Stack Allocator Initialization: - -Custom Task Stack Allocator Initialization ------------------------------------------- -.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT - -*CONSTANT:* - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - -*DATA TYPE:* - Function pointer. - -*RANGE:* - Undefined, NULL or valid function pointer. - -*DEFAULT VALUE:* - The default value is NULL, which indicates that task stacks will be - allocated from the RTEMS Workspace. - -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization method -for an application or BSP specific task stack allocation implementation. - -**NOTES:** - -A correctly configured system must configure the following to be consistent: - -- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - -- ``CONFIGURE_TASK_STACK_ALLOCATOR`` - -- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - -.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR === - -.. _Custom Task Stack Allocator: - -Custom Task Stack Allocator ---------------------------- -.. index:: CONFIGURE_TASK_STACK_ALLOCATOR - -.. index:: task stack allocator - -*CONSTANT:* - ``CONFIGURE_TASK_STACK_ALLOCATOR`` - -*DATA TYPE:* - Function pointer. - -*RANGE:* - Undefined or valid function pointer. - -*DEFAULT VALUE:* - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. - -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to -allocate task stacks. - -**NOTES:** - -A correctly configured system must configure the following to be consistent: - -- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - -- ``CONFIGURE_TASK_STACK_ALLOCATOR`` - -- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - -.. COMMENT: === CONFIGURE_TASK_STACK_DEALLOCATOR === - -.. _Custom Task Stack Deallocator: - -Custom Task Stack Deallocator ------------------------------ -.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR -.. index:: task stack deallocator - -*CONSTANT:* - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - -*DATA TYPE:* - Function pointer. - -*RANGE:* - Undefined or valid function pointer. - -*DEFAULT VALUE:* - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. - -**DESCRIPTION:** - -``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine to -free task stacks. - -**NOTES:** - -A correctly configured system must configure the following to be consistent: - -- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - -- ``CONFIGURE_TASK_STACK_ALLOCATOR`` - -- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - -.. COMMENT: === Classic API Message Buffers === - -Configuring Memory for Classic API Message Buffers -================================================== - -This section describes the configuration parameters related to specifying the -amount of memory reserved for Classic API Message Buffers. - -.. COMMENT: === CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE === - -.. _Calculate Memory for a Single Classic Message API Message Queue: - -Calculate Memory for a Single Classic Message API Message Queue ---------------------------------------------------------------- -.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE -.. index:: memory for a single message queue's buffers - -*CONSTANT:* - ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is None. - -**DESCRIPTION:** - -This is a helper macro which is used to assist in computing the total amount of -memory required for message buffers. Each message queue will have its own -configuration with maximum message size and maximum number of pending messages. - -The interface for this macro is as follows: - -.. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) - -Where ``max_messages`` is the maximum number of pending messages and -``size_per`` is the size in bytes of the user message. - -**NOTES:** - -This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. - -.. COMMENT: === CONFIGURE_MESSAGE_BUFFER_MEMORY === - -.. _Reserve Memory for All Classic Message API Message Queues: - -Reserve Memory for All Classic Message API Message Queues ---------------------------------------------------------- -.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY -.. index:: configure message queue buffer memory - -*CONSTANT:* - ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` - -*DATA TYPE:* - integer summation macro - -*RANGE:* - undefined (zero) or calculation resulting in a positive integer - -*DEFAULT VALUE:* - This is not defined by default, and zero (0) memory is reserved. - -**DESCRIPTION:** - -This macro is set to the number of bytes the application requires to be -reserved for pending Classic API Message Queue buffers. - -**NOTES:** - -The following illustrates how the help macro -``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` can be used to assist in calculating -the message buffer memory required. In this example, there are two message -queues used in this application. The first message queue has maximum of 24 -pending messages with the message structure defined by the type -``one_message_type``. The other message queue has maximum of 500 pending -messages with the message structure defined by the type ``other_message_type``. - -.. code-block:: c - - #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ - (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 24, sizeof(one_message_type) \ - ) + \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 500, sizeof(other_message_type) \ - ) - -.. COMMENT: === Seldom Used Configuration Parameters === - -Seldom Used Configuration Parameters -==================================== - -This section describes configuration parameters supported by -``<rtems/confdefs.h>`` which are seldom used by applications. These parameters -tend to be oriented to debugging system configurations and providing -work-arounds when the memory estimated by ``<rtems/confdefs.h>`` is incorrect. - -.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD === - -.. _Specify Memory Overhead: - -Specify Memory Overhead ------------------------ -.. index:: CONFIGURE_MEMORY_OVERHEAD - -*CONSTANT:* - ``CONFIGURE_MEMORY_OVERHEAD`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -Thie parameter is set to the number of kilobytes the application wishes to add -to the requirements calculated by ``<rtems/confdefs.h>``. - -**NOTES:** - -This configuration parameter should only be used when it is suspected that a -bug in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically -the memory allocation will be too low when an application does not account for -all message queue buffers or task stacks. - -.. COMMENT: === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE === - -.. _Do Not Generate Configuration Information: - -Do Not Generate Configuration Information ------------------------------------------ -.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE - -*CONSTANT:* - ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -This configuration parameter should only be defined if the application is -providing their own complete set of configuration tables. - -**NOTES:** - -None. - -.. COMMENT: === C Library Support Configuration === - -C Library Support Configuration -=============================== - -This section defines the file system and IO library related configuration -parameters supported by ``<rtems/confdefs.h>``. - -.. COMMENT: === CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS === - -.. _Specify Maximum Number of File Descriptors: - -Specify Maximum Number of File Descriptors ------------------------------------------- -.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS -.. index:: maximum file descriptors - -*CONSTANT:* - ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the - default value is 3, otherwise the default value is 0. Three file - descriptors allows RTEMS to support standard input, output, and error I/O - streams on ``/dev/console``. - -**DESCRIPTION:** - -This configuration parameter is set to the maximum number of file like objects -that can be concurrently open. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_TERMIOS_DISABLED === - -.. _Disable POSIX Termios Support: - -Disable POSIX Termios Support ------------------------------ -.. index:: CONFIGURE_TERMIOS_DISABLED - -*CONSTANT:* - ``CONFIGURE_TERMIOS_DISABLED`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, and resources are reserved for the termios - functionality. - -**DESCRIPTION:** - -This configuration parameter is defined if the software implementing POSIX -termios functionality is not going to be used by this application. - -**NOTES:** - -The termios support library should not be included in an application executable -unless it is directly referenced by the application or a device driver. - -.. COMMENT: === CONFIGURE_NUMBER_OF_TERMIOS_PORTS === - -.. _Specify Maximum Termios Ports: - -Specify Maximum Termios Ports ------------------------------ -.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS - -*CONSTANT:* - ``CONFIGURE_NUMBER_OF_TERMIOS_PORTS`` - -*DATA TYPE:* - Unsigned integer. - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 1, so a console port can be used. - -**DESCRIPTION:** - -This configuration parameter is set to the number of ports using the termios -functionality. Each concurrently active termios port requires resources. - -**NOTES:** - -If the application will be using serial ports including, but not limited to, -the Console Device (e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then -it is highly likely that this configuration parameter should NOT be is defined. - -.. COMMENT: === File System Configuration Parameters === - -File System Configuration Parameters -==================================== - -This section defines File System related configuration parameters. - -.. COMMENT: === CONFIGURE_HAS_OWN_MOUNT_TABLE === - -.. _Providing Application Specific Mount Table: - -Providing Application Specific Mount Table ------------------------------------------- -.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE - -*CONSTANT:* - ``CONFIGURE_HAS_OWN_MOUNT_TABLE`` - -*DATA TYPE:* - Undefined or an array of type ``rtems_filesystem_mount_table_t``. - -*RANGE:* - Undefined or an array of type ``rtems_filesystem_mount_table_t``. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -This configuration parameter is defined when the application provides their own -filesystem mount table. The mount table is an array of -``rtems_filesystem_mount_table_t`` entries pointed to by the global variable -``rtems_filesystem_mount_table``. The number of entries in this table is in an -integer variable named ``rtems_filesystem_mount_table_t``. - -.. COMMENT: XXX - is the variable name for the count right? - -**NOTES:** - -None. - -.. COMMENT: XXX - Please provide an example - -.. COMMENT: === CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM === - -.. _Configure devFS as Root File System: - -Configure devFS as Root File System ------------------------------------ -.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM - -*CONSTANT:* - ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. If no other root file system configuration - parameters are specified, the IMFS will be used as the root file system. - -**DESCRIPTION:** - -This configuration parameter is defined if the application wishes to use the -device-only filesytem as the root file system. - -**NOTES:** - -The device-only filesystem supports only device nodes and is smaller in -executable code size than the full IMFS and miniIMFS. - -The devFS is comparable in functionality to the pseudo-filesystem name space -provided before RTEMS release 4.5.0. - -.. COMMENT: === CONFIGURE_MAXIMUM_DEVICES === - -.. _Specifying Maximum Devices for devFS: - -Specifying Maximum Devices for devFS ------------------------------------- -.. index:: CONFIGURE_MAXIMUM_DEVICES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_DEVICES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - If ``BSP_MAXIMUM_DEVICES`` is defined, then the default value is - ``BSP_MAXIMUM_DEVICES``, otherwise the default value is 4. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of individual devices -that may be registered in the device file system (devFS). - -**NOTES:** - -This option is specific to the device file system (devFS) and should not be -confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only -impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when -``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. - -.. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM === - -.. _Disable File System Support: - -Disable File System Support ---------------------------- -.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM - -*CONSTANT:* - ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. If no other root file system configuration - parameters are specified, the IMFS will be used as the root file system. - -**DESCRIPTION:** - -This configuration parameter is defined if the application dose not intend to -use any kind of filesystem support. This include the device infrastructure -necessary to support ``printf()``. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM === - -.. _Use a Root IMFS with a Minimalistic Feature Set: - -Use a Root IMFS with a Minimalistic Feature Set ------------------------------------------------ -.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM - -*CONSTANT:* - ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the following configuration -options will be defined as well - -- ``CONFIGURE_IMFS_DISABLE_CHMOD``, - -- ``CONFIGURE_IMFS_DISABLE_CHOWN``, - -- ``CONFIGURE_IMFS_DISABLE_UTIME``, - -- ``CONFIGURE_IMFS_DISABLE_LINK``, - -- ``CONFIGURE_IMFS_DISABLE_SYMLINK``, - -- ``CONFIGURE_IMFS_DISABLE_READLINK``, - -- ``CONFIGURE_IMFS_DISABLE_RENAME``, and - -- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``. - -.. COMMENT: === CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK === - -.. _Specify Block Size for IMFS: - -Specify Block Size for IMFS ---------------------------- -.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK - -*CONSTANT:* - ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Valid values for this configuration parameter are a power of two (2) - between 16 and 512 inclusive. In other words, valid values are 16, 32, 64, - 128, 256,and 512. - -*DEFAULT VALUE:* - The default IMFS block size is 128 bytes. - -**DESCRIPTION:** - -This configuration parameter specifies the block size for in-memory files -managed by the IMFS. The configured block size has two impacts. The first is -the average amount of unused memory in the last block of each file. For -example, when the block size is 512, on average one-half of the last block of -each file will remain unused and the memory is wasted. In contrast, when the -block size is 16, the average unused memory per file is only 8 bytes. However, -it requires more allocations for the same size file and thus more overhead per -block for the dynamic memory management. - -Second, the block size has an impact on the maximum size file that can be -stored in the IMFS. With smaller block size, the maximum file size is -correspondingly smaller. The following shows the maximum file size possible -based on the configured block size: - -- when the block size is 16 bytes, the maximum file size is 1,328 bytes. - -- when the block size is 32 bytes, the maximum file size is 18,656 bytes. - -- when the block size is 64 bytes, the maximum file size is 279,488 bytes. - -- when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. - -- when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. - -- when the block size is 512 bytes, the maximum file size is 1,082,195,456 - bytes. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHOWN === - -.. _Disable Change Owner Support of Root IMFS: - -Disable Change Owner Support of Root IMFS ------------------------------------------ -.. index:: CONFIGURE_IMFS_DISABLE_CHOWN - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_CHOWN`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change the -owner is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHMOD === - -.. _Disable Change Mode Support of Root IMFS: - -Disable Change Mode Support of Root IMFS ----------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_CHMOD - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_CHMOD`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change the -mode is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_UTIME === - -.. _Disable Change Times Support of Root IMFS: - -Disable Change Times Support of Root IMFS ------------------------------------------ -.. index:: CONFIGURE_IMFS_DISABLE_UTIME - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_UTIME`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to change times -is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_LINK === - -.. _Disable Create Hard Link Support of Root IMFS: - -Disable Create Hard Link Support of Root IMFS ---------------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_LINK - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_LINK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to create hard -links is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_SYMLINK === - -.. _Disable Create Symbolic Link Support of Root IMFS: - -Disable Create Symbolic Link Support of Root IMFS -------------------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_SYMLINK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to create -symbolic links is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_READLINK === - -.. _Disable Read Symbolic Link Support of Root IMFS: - -Disable Read Symbolic Link Support of Root IMFS ------------------------------------------------ -.. index:: CONFIGURE_IMFS_DISABLE_READLINK - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_READLINK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to read symbolic -links is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_RENAME === - -.. _Disable Rename Support of Root IMFS: - -Disable Rename Support of Root IMFS ------------------------------------ -.. index:: CONFIGURE_IMFS_DISABLE_RENAME - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_RENAME`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to rename nodes -is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_READDIR === - -.. _Disable Directory Read Support of Root IMFS: - -Disable Directory Read Support of Root IMFS -------------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_READDIR - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_READDIR`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to read a -directory is disabled in the root IMFS. It is still possible to open nodes in -a directory. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_MOUNT === - -.. _Disable Mount Support of Root IMFS: - -Disable Mount Support of Root IMFS ----------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_MOUNT - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_MOUNT`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to mount other -file systems is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_UNMOUNT === - -.. _Disable Unmount Support of Root IMFS: - -Disable Unmount Support of Root IMFS ------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to unmount file -systems is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD === - -.. _Disable Make Nodes Support of Root IMFS: - -Disable Make Nodes Support of Root IMFS ---------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_MKNOD - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_MKNOD`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to make -directories, devices, regular files and FIFOs is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD_FILE === - -.. _Disable Make Files Support of Root IMFS: - -Disable Make Files Support of Root IMFS ---------------------------------------- -.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to make regular -files is disabled in the root IMFS. - -.. COMMENT: === CONFIGURE_IMFS_DISABLE_RMNOD === - -.. _Disable Remove Nodes Support of Root IMFS: - -Disable Remove Nodes Support of Root IMFS ------------------------------------------ -.. index:: CONFIGURE_IMFS_DISABLE_RMNOD - -*CONSTANT:* - ``CONFIGURE_IMFS_DISABLE_RMNOD`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -In case this configuration option is defined, then the support to remove nodes -is disabled in the root IMFS. - -.. COMMENT: === Block Device Cache Configuration === - -Block Device Cache Configuration -================================ - -This section defines Block Device Cache (bdbuf) related configuration -parameters. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_LIBBLOCK === - -.. _Enable Block Device Cache: - -Enable Block Device Cache -------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -Provides a Block Device Cache configuration. - -**NOTES:** - -Each option of the Block Device Cache 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 file systems. - -.. COMMENT: === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE === - -.. _Size of the Cache Memory: - -Size of the Cache Memory ------------------------- -.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE - -*CONSTANT:* - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 32768 bytes. - -**DESCRIPTION:** - -Size of the cache memory in bytes. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MIN_SIZE === - -.. _Minimum Size of a Buffer: - -Minimum Size of a Buffer ------------------------- -.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE - -*CONSTANT:* - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 512 bytes. - -**DESCRIPTION:** - -Defines the minimum size of a buffer in bytes. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MAX_SIZE === - -.. _Maximum Size of a Buffer: - -Maximum Size of a Buffer ------------------------- -.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE - -*CONSTANT:* - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - It must be positive and an integral multiple of the buffer minimum size. - -*DEFAULT VALUE:* - The default value is 4096 bytes. - -**DESCRIPTION:** - -Defines the maximum size of a buffer in bytes. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SWAPOUT_SWAP_PERIOD === - -.. _Swapout Task Swap Period: - -Swapout Task Swap Period ------------------------- -.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD - -*CONSTANT:* - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 250 milliseconds. - -**DESCRIPTION:** - -Defines the swapout task swap period in milliseconds. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SWAPOUT_BLOCK_HOLD === - -.. _Swapout Task Maximum Block Hold Time: - -Swapout Task Maximum Block Hold Time ------------------------------------- -.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD - -*CONSTANT:* - ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 1000 milliseconds. - -**DESCRIPTION:** - -Defines the swapout task maximum block hold time in milliseconds. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SWAPOUT_TASK_PRIORITY === - -.. _Swapout Task Priority: - -Swapout Task Priority ---------------------- -.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY - -*CONSTANT:* - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` - -*DATA TYPE:* - Task priority (``rtems_task_priority``). - -*RANGE:* - Valid task priority. - -*DEFAULT VALUE:* - The default value is 15. - -**DESCRIPTION:** - -Defines the swapout task priority. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS === - -.. _Maximum Blocks per Read-Ahead Request: - -Maximum Blocks per Read-Ahead Request -------------------------------------- -.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS - -*CONSTANT:* - ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -Defines the maximum blocks per read-ahead request. - -**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. - -.. COMMENT: === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS === - -.. _Maximum Blocks per Write Request: - -Maximum Blocks per Write Request --------------------------------- -.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS - -*CONSTANT:* - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 16. - -**DESCRIPTION:** - -Defines the maximum blocks per write request. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_BDBUF_TASK_STACK_SIZE === - -.. _Task Stack Size of the Block Device Cache Tasks: - -Task Stack Size of the Block Device Cache Tasks ------------------------------------------------ -.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE - -*CONSTANT:* - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is RTEMS_MINIMUM_STACK_SIZE. - -**DESCRIPTION:** - -Defines the task stack size of the Block Device Cache tasks in bytes. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY === - -.. _Read-Ahead Task Priority: - -Read-Ahead Task Priority ------------------------- -.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY - -*CONSTANT:* - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` - -*DATA TYPE:* - Task priority (``rtems_task_priority``). - -*RANGE:* - Valid task priority. - -*DEFAULT VALUE:* - The default value is 15. - -**DESCRIPTION:** - -Defines the read-ahead task priority. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASKS === - -.. _Swapout Worker Task Count: - -Swapout Worker Task Count -------------------------- -.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS - -*CONSTANT:* - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -Defines the swapout worker task count. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY === - -.. _Swapout Worker Task Priority: - -Swapout Worker Task Priority ----------------------------- -.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY - -*CONSTANT:* - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` - -*DATA TYPE:* - Task priority (``rtems_task_priority``). - -*RANGE:* - Valid task priority. - -*DEFAULT VALUE:* - The default value is 15. - -**DESCRIPTION:** - -Defines the swapout worker task priority. - -**NOTES:** - -None. - -.. COMMENT: === BSP Specific Settings === - -BSP Specific Settings -===================== - -This section describes BSP specific configuration settings used by -``<rtems/confdefs.h>``. The BSP specific configuration settings are defined in -``<bsp.h>``. - -.. COMMENT: === Disable BSP Settings === - -.. _Disable BSP Configuration Settings: - -Disable BSP Configuration Settings ----------------------------------- -.. index:: CONFIGURE_DISABLE_BSP_SETTINGS - -*CONSTANT:* - ``CONFIGURE_DISABLE_BSP_SETTINGS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -All BSP specific configuration settings can be disabled by the application with -the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK === - -.. _Specify BSP Supports sbrk(): - -Specify BSP Supports sbrk() ---------------------------- -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -*CONSTANT:* - ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -This configuration parameter is defined by a BSP to indicate that it does not -allocate all available memory to the C Program Heap used by the Malloc Family -of routines. - -If defined, when ``malloc()`` is unable to allocate memory, it will call the -BSP supplied ``sbrk()`` to obtain more memory. - -**NOTES:** - -This parameter should not be defined by the application. Only the BSP knows how -it allocates memory to the C Program Heap. - -.. COMMENT: === BSP_IDLE_TASK_BODY === - -.. _Specify BSP Specific Idle Task: - -Specify BSP Specific Idle Task ------------------------------- -.. index:: BSP_IDLE_TASK_BODY - -*CONSTANT:* - ``BSP_IDLE_TASK_BODY`` - -*DATA TYPE:* - Function pointer. - -*RANGE:* - Undefined or valid function pointer. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and -``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this BSP -specific idle task body will be used. - -**NOTES:** - -As it has knowledge of the specific CPU model, system controller logic, and -peripheral buses, a BSP specific IDLE task may be capable of turning components -off to save power during extended periods of no task activity - -.. COMMENT: === BSP_IDLE_TASK_STACK_SIZE === - -.. _Specify BSP Suggested Value for IDLE Task Stack Size: - -Specify BSP Suggested Value for IDLE Task Stack Size ----------------------------------------------------- -.. index:: BSP_IDLE_TASK_STACK_SIZE - -*CONSTANT:* - ``BSP_IDLE_TASK_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and -``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application, then this -BSP suggested idle task stack size will be used. - -**NOTES:** - -The order of precedence for configuring the IDLE task stack size is: - -- RTEMS default minimum stack size. - -- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``. - -- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``. - -- If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``. - -.. COMMENT: XXX - add cross references to other related values. - -.. COMMENT: === BSP_INITIAL_EXTENSION === - -.. _Specify BSP Specific User Extensions: - -Specify BSP Specific User Extensions ------------------------------------- -.. index:: BSP_INITIAL_EXTENSION - -*CONSTANT:* - ``BSP_INITIAL_EXTENSION`` - -*DATA TYPE:* - List of user extension initializers (``rtems_extensions_table``). - -*RANGE:* - Undefined or a list of user extension initializers. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific -initial extension will be placed as the last entry in the initial extension -table. - -**NOTES:** - -None. - -.. COMMENT: === BSP_INTERRUPT_STACK_SIZE === - -.. _Specifying BSP Specific Interrupt Stack Size: - -Specifying BSP Specific Interrupt Stack Size --------------------------------------------- -.. index:: BSP_INTERRUPT_STACK_SIZE - -*CONSTANT:* - ``BSP_INTERRUPT_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and -``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application, then this -BSP specific interrupt stack size will be used. - -**NOTES:** - -None. - -.. COMMENT: === BSP_MAXIMUM_DEVICES === - -.. _Specifying BSP Specific Maximum Devices: - -Specifying BSP Specific Maximum Devices ---------------------------------------- -.. index:: BSP_MAXIMUM_DEVICES - -*CONSTANT:* - ``BSP_MAXIMUM_DEVICES`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and -``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application, then this BSP -specific maximum device count will be used. - -**NOTES:** - -This option is specific to the device file system (devFS) and should not be -confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only -impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when -``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. - -.. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY === - -.. _BSP Recommends RTEMS Workspace be Cleared: - -BSP Recommends RTEMS Workspace be Cleared ------------------------------------------ -.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY - -*CONSTANT:* - ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and -``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the application, -then the workspace will be zeroed automatically. - -**NOTES:** - -Zeroing memory can add significantly to system boot time. It is not necessary -for RTEMS but is often assumed by support libraries. - -.. COMMENT: === CONFIGURE_BSP_PREREQUISITE_DRIVERS === - -.. _Specify BSP Prerequisite Drivers: - -Specify BSP Prerequisite Drivers --------------------------------- -.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS - -*CONSTANT:* - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` - -*DATA TYPE:* - List of device driver initializers (``rtems_driver_address_table``). - -*RANGE:* - Undefined or array of device drivers. - -*DEFAULT VALUE:* - This option is BSP specific. - -**DESCRIPTION:** - -``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device drivers -it needs to include in the Device Driver Table. This should be defined to the -set of device driver entries that will be placed in the table at the *FRONT* of -the Device Driver Table and initialized before any other drivers *INCLUDING* -any application prerequisite drivers. - -**NOTES:** - -``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to configure -common infrastructure such as bus controllers or probe for devices. - -.. COMMENT: === Idle Task Configuration === - -Idle Task Configuration -======================= - -This section defines the IDLE task related configuration parameters supported -by ``<rtems/confdefs.h>``. - -.. COMMENT: === CONFIGURE_IDLE_TASK_BODY === - -.. _Specify Application Specific Idle Task Body: - -Specify Application Specific Idle Task Body -------------------------------------------- -.. index:: CONFIGURE_IDLE_TASK_BODY - -*CONSTANT:* - ``CONFIGURE_IDLE_TASK_BODY`` - -*DATA TYPE:* - Function pointer. - -*RANGE:* - Undefined or valid function pointer. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to the -application specific IDLE thread body. If not specified, the BSP or RTEMS -default IDLE thread body will be used. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_IDLE_TASK_STACK_SIZE === - -.. _Specify Idle Task Stack Size: - -Specify Idle Task Stack Size ----------------------------- -.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE - -*CONSTANT:* - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` - -*DATA TYPE:* - Unsigned integer (``size_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - The default value is RTEMS_MINIMUM_STACK_SIZE. - -**DESCRIPTION:** - -``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the -desired stack size for the IDLE task. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION === - -.. _Specify Idle Task Performs Application Initialization: - -Specify Idle Task Performs Application Initialization ------------------------------------------------------ -.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION - -*CONSTANT:* - ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, the user is assumed - to provide one or more initialization tasks. - -**DESCRIPTION:** - -``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set to indicate that the -user has configured *NO* user initialization tasks or threads and that the user -provided IDLE task will perform application initialization and then transform -itself into an IDLE task. - -**NOTES:** - -If you use this option be careful, the user IDLE task *CANNOT* block at all -during the initialization sequence. Further, once application initialization -is complete, it must make itself preemptible and enter an IDLE body loop. - -The IDLE task must run at the lowest priority of all tasks in the system. - -.. COMMENT: === Scheduler Algorithm Configuration === - -Scheduler Algorithm Configuration -================================= - -This section defines the configuration parameters related to selecting a -scheduling algorithm for an application. For the schedulers built into RTEMS, -the configuration is straightforward. All that is required is to define the -configuration macro which specifies which scheduler you want for in your -application. The currently available schedulers are: - -The pluggable scheduler interface also enables the user to provide their own -scheduling algorithm. If you choose to do this, you must define multiple -configuration macros. - -.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY === - -.. _Use Deterministic Priority Scheduler: - -Use Deterministic Priority Scheduler ------------------------------------- -.. index:: CONFIGURE_SCHEDULER_PRIORITY - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_PRIORITY`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is defined by default. This is the default scheduler and specifying - this configuration parameter is redundant. - -**DESCRIPTION:** - -The Deterministic Priority Scheduler is the default scheduler in RTEMS for -uni-processor applications and is designed for predictable performance under -the highest loads. It can block or unblock a thread in a constant amount of -time. This scheduler requires a variable amount of memory based upon the -number of priorities configured in the system. - -**NOTES:** - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the default -behavior. - -.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE === - -.. _Use Simple Priority Scheduler: - -Use Simple Priority Scheduler ------------------------------ -.. index:: CONFIGURE_SCHEDULER_SIMPLE - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_SIMPLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -When defined, the Simple Priority Scheduler is used at the thread scheduling -algorithm. This is an alternative scheduler in RTEMS. It is designed to -provide the same task scheduling behaviour as the Deterministic Priority -Scheduler while being simpler in implementation and uses less memory for data -management. It maintains a single sorted list of all ready threads. Thus -blocking or unblocking a thread is not a constant time operation with this -scheduler. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_SIMPLE``. - -**NOTES:** - -This scheduler is appropriate for use in small systems where RAM is limited. - -.. COMMENT: === CONFIGURE_SCHEDULER_EDF === - -.. _Use Earliest Deadline First Scheduler: - -Use Earliest Deadline First Scheduler -------------------------------------- -.. index:: CONFIGURE_SCHEDULER_EDF - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_EDF`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in -RTEMS for uni-processor applications. The EDF schedules tasks with dynamic -priorities equal to deadlines. The deadlines are declared using only Rate -Monotonic manager which handles periodic behavior. Period is always equal to -deadline. If a task does not have any deadline declared or the deadline is -cancelled, the task is considered a background task which is scheduled in case -no deadline-driven tasks are ready to run. Moreover, multiple background tasks -are scheduled according their priority assigned upon initialization. All ready -tasks reside in a single ready queue. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_EDF``. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SCHEDULER_CBS === - -.. _Use Constant Bandwidth Server Scheduler: - -Use Constant Bandwidth Server Scheduler ---------------------------------------- -.. index:: CONFIGURE_SCHEDULER_CBS - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_CBS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler in -RTEMS for uni-processor applications. The CBS is a budget aware extension of -EDF scheduler. The goal of this scheduler is to ensure temporal isolation of -tasks. The CBS is equipped with a set of additional rules and provides with an -extensive API. - -This scheduler may be explicitly selected by defining -``CONFIGURE_SCHEDULER_CBS``. - -.. COMMENT: XXX - add cross reference to API chapter - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY_SMP === - -.. _Use Deterministic Priority SMP Scheduler: - -Use Deterministic Priority SMP Scheduler ----------------------------------------- -.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -The Deterministic Priority SMP Scheduler is derived from the Deterministic -Priority Scheduler but is capable of scheduling threads across multiple -processors. - -In a configuration with SMP enabled at configure time, it may be explicitly -selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``. - -**NOTES:** - -This scheduler is only available when RTEMS is configured with SMP -support enabled. - -This scheduler is currently the default in SMP configurations and is only -selected when ``CONFIGURE_SMP_APPLICATION`` is defined. - -.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE_SMP === - -.. _Use Simple SMP Priority Scheduler: - -Use Simple SMP Priority Scheduler ---------------------------------- -.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -The Simple SMP Priority Scheduler is derived from the Simple Priority Scheduler -but is capable of scheduling threads across multiple processors. It is -designed to provide the same task scheduling behaviour as the Deterministic -Priority Scheduler while distributing threads across multiple processors. -Being based upon the Simple Priority Scheduler, it also maintains a single -sorted list of all ready threads. Thus blocking or unblocking a thread is not -a constant time operation with this scheduler. - -In addition, when allocating threads to processors, the algorithm is not -constant time. This algorithm was not designed with efficiency as a primary -design goal. Its primary design goal was to provide an SMP-aware scheduling -algorithm that is simple to understand. - -In a configuration with SMP enabled at configure time, it may be explicitly -selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``. - -**NOTES:** - -This scheduler is only available when RTEMS is configured with SMP support -enabled. - -.. COMMENT: === Configuring a Scheduler Name === - -.. _Configuring a Scheduler Name: - -Configuring a Scheduler Name ----------------------------- -.. index:: CONFIGURE_SCHEDULER_NAME - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_NAME`` - -*DATA TYPE:* - RTEMS Name (``rtems_name``). - -*RANGE:* - Any value. - -*DEFAULT VALUE:* - The default name is - - ``"UCBS"`` for the Uni-Processor CBS scheduler, - - ``"UEDF"`` for the Uni-Processor EDF scheduler, - - ``"UPD "`` for the Uni-Processor Deterministic Priority scheduler, - - ``"UPS "`` for the Uni-Processor Simple Priority scheduler, - - ``"MPA "`` for the Multi-Processor Priority Affinity scheduler, and - - ``"MPD "`` for the Multi-Processor Deterministic Priority scheduler, and - - ``"MPS "`` for the Multi-Processor Simple Priority scheduler. - -**DESCRIPTION:** - -Schedulers can be identified via ``rtems_scheduler_ident``. The name of the -scheduler is determined by the configuration. - -**NOTES:** - -None. - -.. COMMENT: === Configuring a User Scheduler === - -.. _Configuring a User Provided Scheduler: - -Configuring a User Provided Scheduler -------------------------------------- -.. index:: CONFIGURE_SCHEDULER_USER - -*CONSTANT:* - ``CONFIGURE_SCHEDULER_USER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -RTEMS allows the application to provide its own task/thread scheduling -algorithm. In order to do this, one must define ``CONFIGURE_SCHEDULER_USER`` to -indicate the application provides its own scheduling algorithm. If -``CONFIGURE_SCHEDULER_USER`` is defined then the following additional macros -must be defined: - -- ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition of the - scheduler context of the user scheduler. - -- ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler control - initializer for the user scheduler. - -- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of the - per-thread information of the user scheduler. - -**NOTES:** - -At this time, the mechanics and requirements for writing a new scheduler are -evolving and not fully documented. It is recommended that you look at the -existing Deterministic Priority Scheduler in -``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on the -configuration macros, please examine ``cpukit/sapi/include/confdefs.h`` for how -these are defined for the Deterministic Priority Scheduler. - -.. COMMENT: === Configuring Clustered Schedulers === - -.. _Configuring Clustered Schedulers: - -Configuring Clustered Schedulers --------------------------------- - -Clustered scheduling helps to control the worst-case latencies in a -multi-processor system. The goal is to reduce the amount of shared state in -the system and thus prevention of lock contention. Modern multi-processor -systems tend to have several layers of data and instruction caches. With -clustered scheduling it is possible to honour the cache topology of a system -and thus avoid expensive cache synchronization traffic. - -We have clustered scheduling in case the set of processors of a system is -partitioned into non-empty pairwise-disjoint subsets. These subsets are called -clusters. Clusters with a cardinality of one are partitions. Each cluster is -owned by exactly one scheduler instance. In order to use clustered scheduling -the application designer has to answer two questions. - -#. How is the set of processors partitioned into clusters? - -#. Which scheduler is used for which cluster? - -**CONFIGURATION:** - -The schedulers in an SMP system are statically configured on RTEMS. Firstly -the application must select which scheduling algorithms are available with the -following defines - -- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``, - -- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and - -- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``. - -This is necessary to calculate the per-thread overhead introduced by the -schedulers. After these definitions the configuration file must ``#include -<rtems/scheduler.h>`` to have access to scheduler specific configuration -macros. Each scheduler needs a context to store state information at run-time. -To provide a context for each scheduler is the next step. Use the following -macros to create scheduler contexts - -- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``, - -- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and - -- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``. - -The ``name`` parameter is used as part of a designator for a global variable, -so the usual C/C++ designator rules apply. Additional parameters are scheduler -specific. The schedulers are registered in the system via the scheduler table. -To create the scheduler table define ``CONFIGURE_SCHEDULER_CONTROLS`` to a list -of the following scheduler control initializers - -- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``, - -- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and - -- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``. - -The ``name`` parameter must correspond to the parameter defining the scheduler -context. The ``obj_name`` determines the scheduler object name and can be used -in ``rtems_scheduler_ident()`` to get the scheduler object identifier. - -The last step is to define which processor uses which scheduler. For this -purpose a scheduler assignment table must be defined. The entry count of this -table must be equal to the configured maximum processors -(``CONFIGURE_SMP_MAXIMUM_PROCESSORS``). A processor assignment to a scheduler -can be optional or mandatory. The boot processor must have a scheduler -assigned. In case the system needs more mandatory processors than available -then a fatal run-time error will occur. To specify the scheduler assignments -define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of -``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and -``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros. The ``index`` parameter must -be a valid index into the scheduler table. The ``attr`` parameter defines the -scheduler assignment attributes. By default a scheduler assignment to a -processor is optional. For the scheduler assignment attribute use one of the -mutually exclusive variants - -- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``, - -- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and - -- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``. - -**ERRORS:** - -In case one of the scheduler indices in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` -is invalid a link-time error will occur with an undefined reference to -``RTEMS_SCHEDULER_INVALID_INDEX``. - -Some fatal errors may occur in case of scheduler configuration inconsistencies -or a lack of processors on the system. The fatal source is -``RTEMS_FATAL_SOURCE_SMP``. None of the errors is internal. - -- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor - must have a scheduler assigned. - -- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory - processor beyond the range of physically or virtually available processors. - The processor demand must be reduced for this system. - -- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory - processor failed during system initialization. The system may not have this - processor at all or it could be a problem with a boot loader for example. - Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition. - -- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed - to start multitasking on a processor with no scheduler assigned. - -**EXAMPLE:** - -The following example shows a scheduler configuration for a hypothetical -product using two chip variants. One variant has four processors which is used -for the normal product line and another provides eight processors for the -high-performance product line. The first processor performs hard-real time -control of actuators and sensors. The second processor is not used by RTEMS at -all and runs a Linux instance to provide a graphical user interface. The -additional processors are used for a worker thread pool to perform data -processing operations. - -The processors managed by RTEMS use two Deterministic Priority scheduler -instances capable of dealing with 256 priority levels. The scheduler with -index zero has the name ``"IO "``. The scheduler with index one has the name -``"WORK"``. The scheduler assignments of the first, third and fourth processor -are mandatory, so the system must have at least four processors, otherwise a -fatal run-time error will occur during system startup. The processor -assignments for the fifth up to the eighth processor are optional so that the -same application can be used for the normal and high-performance product lines. -The second processor has no scheduler assigned and runs Linux. A hypervisor -will ensure that the two systems cannot interfere in an undesirable way. - -.. code-block:: c - - #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8 - #define CONFIGURE_MAXIMUM_PRIORITY 255 - /* Make the scheduler algorithm available */ - #define CONFIGURE_SCHEDULER_PRIORITY_SMP - #include <rtems/scheduler.h> - /* Create contexts for the two scheduler instances */ - RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); - RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); - /* Define the scheduler table */ - #define CONFIGURE_SCHEDULER_CONTROLS \\ - RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ - io, \ - rtems_build_name('I', 'O', ' ', ' ') \ - ), \ - RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ - work, \ - rtems_build_name('W', 'O', 'R', 'K') \ - ) - /* Define the processor to scheduler assignments */ - #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \ - RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ - RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL) - -.. COMMENT: === SMP Specific Configuration Parameters === - -SMP Specific Configuration Parameters -===================================== - -When RTEMS is configured to support SMP target systems, there are other -configuration parameters which apply. - -.. COMMENT: XXX - add -enable-smp - -.. COMMENT: === CONFIGURE_SMP_APPLICATION === - -.. _Enable SMP Support for Applications: - -Enable SMP Support for Applications ------------------------------------ -.. index:: CONFIGURE_SMP_APPLICATION - -*CONSTANT:* - ``CONFIGURE_SMP_APPLICATION`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the -application. - -**NOTES:** - -This define may go away in the future in case all RTEMS components are SMP -ready. This configuration define is ignored on uni-processor configurations. - -.. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS === - -.. _Specify Maximum Processors in SMP System: - -Specify Maximum Processors in SMP System ----------------------------------------- -.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS - -*CONSTANT:* - ``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined). - -**DESCRIPTION:** - -``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of processors in -the SMP configuration. - -**NOTES:** - -If there are more processors available than configured, the rest will be -ignored. This configuration define is ignored on uni-processor configurations. - -.. COMMENT: === Device Driver Table === - -Device Driver Table -=================== - -This section defines the configuration parameters related to the automatic -generation of a Device Driver Table. As ``<rtems/confdefs.h>`` only is aware -of a small set of standard device drivers, the generated Device Driver Table is -suitable for simple applications with no custom device drivers. - -Note that network device drivers are not configured in the Device Driver Table. - -.. COMMENT: === CONFIGURE_MAXIMUM_DRIVERS === - -.. _Specifying the Maximum Number of Device Drivers: - -Specifying the Maximum Number of Device Drivers ------------------------------------------------ -.. index:: CONFIGURE_MAXIMUM_DRIVERS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_DRIVERS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - This is computed by default, and is set to the number of device drivers - configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` - configuration parameters. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers per -node. - -**NOTES:** - -If the application will dynamically install device drivers, then this -configuration parameter must be larger than the number of statically configured -device drivers. Drivers configured using the -``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are -statically installed. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER === - -.. _Enable Console Device Driver: - -Enable Console Device Driver ----------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the application -wishes to include the Console Device Driver. - -**NOTES:** - -This device driver is responsible for providing standard input and output using -*/dev/console*. - -BSPs should be constructed in a manner that allows ``printk()`` to work -properly without the need for the console driver to be configured. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER === - -.. _Enable Clock Driver: - -Enable Clock Driver -------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application -wishes to include the Clock Device Driver. - -**NOTES:** - -This device driver is responsible for providing a regular interrupt which -invokes the ``rtems_clock_tick`` directive. - -If neither the Clock Driver not Benchmark Timer is enabled and the -configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is -not defined, then a compile time error will occur. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER === - -.. _Enable the Benchmark Timer Driver: - -Enable the Benchmark Timer Driver ---------------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the -application wishes to include the Timer Driver. This device driver is -used to benchmark execution times by the RTEMS Timing Test Suites. - -**NOTES:** - -If neither the Clock Driver not Benchmark Timer is enabled and the -configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is -not defined, then a compile time error will occur. - -.. COMMENT: === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER === - -.. _Specify Clock and Benchmark Timer Drivers Are Not Needed: - -Specify Clock and Benchmark Timer Drivers Are Not Needed --------------------------------------------------------- -.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the -application does *NOT* want the Clock Device Driver and is *NOT* using the -Timer Driver. The inclusion or exclusion of the Clock Driver must be explicit -in user applications. - -**NOTES:** - -This configuration parameter is intended to prevent the common user error of -using the Hello World example as the baseline for an application and leaving -out a clock tick source. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER === - -.. _Enable Real-Time Clock Driver: - -Enable Real-Time Clock Driver ------------------------------ -.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application wishes -to include the Real-Time Clock Driver. - -**NOTES:** - -Most BSPs do not include support for a real-time clock. This is because many -boards do not include the required hardware. - -If this is defined and the BSP does not have this device driver, then the user -will get a link time error for an undefined symbol. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER === - -.. _Enable the Watchdog Device Driver: - -Enable the Watchdog Device Driver ---------------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the application -wishes to include the Watchdog Driver. - -**NOTES:** - -Most BSPs do not include support for a watchdog device driver. This is because -many boards do not include the required hardware. - -If this is defined and the BSP does not have this device driver, then the user -will get a link time error for an undefined symbol. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER === - -.. _Enable the Graphics Frame Buffer Device Driver: - -Enable the Graphics Frame Buffer Device Driver ----------------------------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the -application wishes to include the BSP's Frame Buffer Device Driver. - -**NOTES:** - -Most BSPs do not include support for a Frame Buffer Device Driver. This is -because many boards do not include the required hardware. - -If this is defined and the BSP does not have this device driver, then the user -will get a link time error for an undefined symbol. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER === - -.. _Enable Stub Device Driver: - -Enable Stub Device Driver -------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application -wishes to include the Stub Device Driver. - -**NOTES:** - -This device driver simply provides entry points that return successful and is -primarily a test fixture. It is supported by all BSPs. - -.. COMMENT: === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS === - -.. _Specify Application Prerequisite Device Drivers: - -Specify Application Prerequisite Device Drivers ------------------------------------------------ -.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS - -*CONSTANT:* - ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` - -*DATA TYPE:* - device driver entry structures - -*RANGE:* - Undefined or set of device driver entry structures - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the application -has device drivers it needs to include in the Device Driver Table. This should -be defined to the set of device driver entries that will be placed in the table -at the *FRONT* of the Device Driver Table and initialized before any other -drivers *EXCEPT* any BSP prerequisite drivers. - -**NOTES:** - -In some cases, it is used by System On Chip BSPs to support peripheral buses -beyond those normally found on the System On Chip. For example, this is used by -one RTEMS system which has implemented a SPARC/ERC32 based board with -VMEBus. The VMEBus Controller initialization is performed by a device driver -configured via this configuration parameter. - -.. COMMENT: XXX Add example - -.. COMMENT: === CONFIGURE_APPLICATION_EXTRA_DRIVERS === - -.. _Specify Extra Application Device Drivers: - -Specify Extra Application Device Drivers ----------------------------------------- -.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS - -*CONSTANT:* - ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` - -*DATA TYPE:* - device driver entry structures - -*RANGE:* - Undefined or set of device driver entry structures - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has -device drivers it needs to include in the Device Driver Table. This should be -defined to the set of device driver entries that will be placed in the table at -the *END* of the Device Driver Table. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER === - -.. _Enable /dev/null Device Driver: - -Enable /dev/null Device Driver ------------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER -.. index:: /dev/null - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -This configuration variable is specified to enable ``/dev/null`` device driver. - -**NOTES:** - -This device driver is supported by all BSPs. - -.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER === - -.. _Enable /dev/zero Device Driver: - -Enable /dev/zero Device Driver ------------------------------- -.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER -.. index:: /dev/zero - -*CONSTANT:* - ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -This configuration variable is specified to enable ``/dev/zero`` device driver. - -**NOTES:** - -This device driver is supported by all BSPs. - -.. COMMENT: === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE === - -.. _Specifying Application Defined Device Driver Table: - -Specifying Application Defined Device Driver Table --------------------------------------------------- -.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE - -*CONSTANT:* - ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default, indicating the ``<rtems/confdefs.h>`` is - providing the device driver table. - -**DESCRIPTION:** - -``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application wishes -to provide their own Device Driver Table. - -The table must be an array of ``rtems_driver_address_table`` entries named`` -_IO_Driver_address_table``. The application must also provide a const variable -``_IO_Number_of_drivers`` of type ``size_t`` indicating the number of entries -in the ``_IO_Driver_address_table``. - -**NOTES:** - -It is expected that there the application would only rarely need to do this. - -.. COMMENT: === Multiprocessing Configuration === - -Multiprocessing Configuration -============================= - -This section defines the multiprocessing related system configuration -parameters supported by ``<rtems/confdefs.h>``. They are only used if the -Multiprocessing Support (distinct from the SMP support) is enabled at configure -time using the ``--enable-multiprocessing`` option. - -Additionally, this class of Configuration Constants are only applicable if -``CONFIGURE_MP_APPLICATION`` is defined. - -.. COMMENT: === CONFIGURE_MP_APPLICATION === - -.. _Specify Application Will Use Multiprocessing: - -Specify Application Will Use Multiprocessing --------------------------------------------- -.. index:: CONFIGURE_MP_APPLICATION - -*CONSTANT:* - ``CONFIGURE_MP_APPLICATION`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -This configuration parameter must be defined to indicate that the application -intends to be part of a multiprocessing configuration. Additional configuration -parameters are assumed to be provided. - -**NOTES:** - -This has no impact unless RTEMS was configured and built using the -``--enable-multiprocessing`` option. - -.. COMMENT: === CONFIGURE_MP_NODE_NUMBER === - -.. _Configure Node Number in Multiprocessor Configuration: - -Configure Node Number in Multiprocessor Configuration ------------------------------------------------------ -.. index:: CONFIGURE_MP_NODE_NUMBER - -*CONSTANT:* - ``CONFIGURE_MP_NODE_NUMBER`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is ``NODE_NUMBER``, which is assumed to be set by the - compilation environment. - -**DESCRIPTION:** - -``CONFIGURE_MP_NODE_NUMBER`` is the node number of this node in a -multiprocessor system. - -**NOTES:** - -In the RTEMS Multiprocessing Test Suite, the node number is derived from the -Makefile variable ``NODE_NUMBER``. The same code is compiled with the -``NODE_NUMBER`` set to different values. The test programs behave differently -based upon their node number. - -.. COMMENT: === CONFIGURE_MP_MAXIMUM_NODES === - -.. _Configure Maximum Node in Multiprocessor Configuration: - -Configure Maximum Node in Multiprocessor Configuration ------------------------------------------------------- -.. index:: CONFIGURE_MP_MAXIMUM_NODES - -*CONSTANT:* - ``CONFIGURE_MP_MAXIMUM_NODES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 2. - -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a -multiprocessor system. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS === - -.. _Configure Maximum Global Objects in Multiprocessor Configuration: - -Configure Maximum Global Objects in Multiprocessor Configuration ----------------------------------------------------------------- -.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS - -*CONSTANT:* - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Positive. - -*DEFAULT VALUE:* - The default value is 32. - -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of concurrently -active global objects in a multiprocessor system. - -**NOTES:** - -This value corresponds to the total number of objects which can be created with -the ``RTEMS_GLOBAL`` attribute. - -.. COMMENT: === CONFIGURE_MP_MAXIMUM_PROXIES === - -.. _Configure Maximum Proxies in Multiprocessor Configuration: - -Configure Maximum Proxies in Multiprocessor Configuration ---------------------------------------------------------- -.. index:: CONFIGURE_MP_MAXIMUM_PROXIES - -*CONSTANT:* - ``CONFIGURE_MP_MAXIMUM_PROXIES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - The default value is 32. - -**DESCRIPTION:** - -``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently -active thread/task proxies on this node in a multiprocessor system. - -**NOTES:** - -Since a proxy is used to represent a remote task/thread which is blocking on -this node. This configuration parameter reflects the maximum number of remote -tasks/threads which can be blocked on objects on this node. - -.. COMMENT: XXX - add xref to proxy discussion in MP chapter - -.. COMMENT: === CONFIGURE_MP_MPCI_TABLE_POINTER === - -.. _Configure MPCI in Multiprocessor Configuration: - -Configure MPCI in Multiprocessor Configuration ----------------------------------------------- -.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER - -*CONSTANT:* - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` - -*DATA TYPE:* - pointer to ``rtems_mpci_table`` - -*RANGE:* - undefined or valid pointer - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI Configuration -Table. The default value of this field is``&MPCI_table``. - -**NOTES:** - -RTEMS provides a Shared Memory MPCI Device Driver which can be used on any -Multiprocessor System assuming the BSP provides the proper set of supporting -methods. - -.. COMMENT: === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE === - -.. _Do Not Generate Multiprocessor Configuration Table: - -Do Not Generate Multiprocessor Configuration Table --------------------------------------------------- -.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE - -*CONSTANT:* - ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the application -wishes to provide their own Multiprocessing Configuration Table. The generated -table is named ``Multiprocessing_configuration``. - -**NOTES:** - -This is a configuration parameter which is very unlikely to be used by an -application. If you find yourself wanting to use it in an application, please -reconsider and discuss this on the RTEMS Users mailing list. - -.. COMMENT: === Ada Tasks === - -Ada Tasks -========= - -This section defines the system configuration parameters supported by -``<rtems/confdefs.h>`` related to configuring RTEMS to support a task using Ada -tasking with GNAT/RTEMS. - -These configuration parameters are only available when RTEMS is built with the -``--enable-ada`` configure option and the application specifies -``CONFIGURE_GNAT_RTEMS``. - -Additionally RTEMS includes an Ada language binding to the Classic API which -has a test suite. This test suite is enabled only when``--enable-tests`` and -``--enable-expada`` are specified on the configure command. - -.. COMMENT: === CONFIGURE_GNAT_RTEMS === - -.. _Specify Application Includes Ada Code: - -Specify Application Includes Ada Code -------------------------------------- -.. index:: CONFIGURE_GNAT_RTEMS - -*CONSTANT:* - ``CONFIGURE_GNAT_RTEMS`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT Ada run-time -is to be used by the application. - -**NOTES:** - -This configuration parameter is critical as it makes``<rtems/confdefs.h>`` -configure the resources (POSIX API Threads, Mutexes, Condition Variables, and -Keys) used implicitly by the GNAT run-time. - -.. COMMENT: === CONFIGURE_MAXIMUM_ADA_TASKS === - -.. _Specify the Maximum Number of Ada Tasks.: - -Specify the Maximum Number of Ada Tasks. ----------------------------------------- -.. index:: CONFIGURE_MAXIMUM_ADA_TASKS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_ADA_TASKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Undefined or positive. - -*DEFAULT VALUE:* - If ``CONFIGURE_GNAT_RTEMS`` is defined, then the default value is 20, - otherwise the default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can be -concurrently active in the system. - -**NOTES:** - -None. - -.. COMMENT: === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS === - -.. _Specify the Maximum Fake Ada Tasks: - -Specify the Maximum Fake Ada Tasks ----------------------------------- -.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS - -*CONSTANT:* - .. index:: ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 0. - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks that can -be concurrently active in the system. A *fake* Ada task is a non-Ada task that -makes calls back into Ada code and thus implicitly uses the Ada run-time. - -**NOTES:** - -None. - -.. COMMENT: === PCI Library === - -PCI Library -=========== - -This section defines the system configuration parameters supported by -``rtems/confdefs.h`` related to configuring the PCI Library for RTEMS. - -The PCI Library startup behaviour can be configured in four different ways -depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined: - -.. index:: PCI_LIB_AUTO - -``PCI_LIB_AUTO`` - Used to enable the PCI auto configuration software. PCI will be automatically - probed, PCI buses enumerated, all devices and bridges will be initialized - using Plug & Play software routines. The PCI device tree will be populated - based on the PCI devices found in the system, PCI devices will be configured - by allocating address region resources automatically in PCI space according - to the BSP or host bridge driver set up. - -.. index:: PCI_LIB_READ - -``PCI_LIB_READ`` - Used to enable the PCI read configuration software. The current PCI - configuration is read to create the RAM representation (the PCI device tree) - of the PCI devices present. PCI devices are assumed to already have been - initialized and PCI buses enumerated, it is therefore required that a BIOS or - a boot loader has set up configuration space prior to booting into RTEMS. - -.. index:: PCI_LIB_STATIC - -``PCI_LIB_STATIC`` - Used to enable the PCI static configuration software. The user provides a PCI - tree with information how all PCI devices are to be configured at compile - time by linking in a custom ``struct pci_bus pci_hb`` tree. The static PCI - library will not probe PCI for devices, instead it will assume that all - devices defined by the user are present, it will enumerate the PCI buses and - configure all PCI devices in static configuration accordingly. Since probe - and allocation software is not needed the startup is faster, has smaller - footprint and does not require dynamic memory allocation. - -.. index:: PCI_LIB_PERIPHERAL - -``PCI_LIB_PERIPHERAL`` - Used to enable the PCI peripheral configuration. It is similar to - ``PCI_LIB_STATIC``, but it will never write the configuration to the PCI - devices since PCI peripherals are not allowed to access PCI configuration - space. - -Note that selecting ``PCI_LIB_STATIC`` or ``PCI_LIB_PERIPHERAL`` but not -defining ``pci_hb`` will reuslt in link errors. Note also that in these modes -Plug & Play is not performed. - -.. COMMENT: === Go Tasks === - -Go Tasks -======== - -.. COMMENT: === CONFIGURE_ENABLE_GO === - -.. _Specify Application Includes Go Code: - -Specify Application Includes Go Code ------------------------------------- -.. index:: CONFIGURE_ENABLE_GO - -*CONSTANT:* - ``CONFIGURE_ENABLE_GO`` - -*DATA TYPE:* - Boolean feature macro. - -*RANGE:* - Defined or undefined. - -*DEFAULT VALUE:* - This is not defined by default. - -**DESCRIPTION:** - -``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go run-time is to -be used by the application. - -**NOTES:** - -The Go language support is experimental - -.. COMMENT: === CONFIGURE_MAXIMUM_GOROUTINES === - -.. _Specify the maximum number of Go routines: - -Specify the maximum number of Go routines ------------------------------------------ -.. index:: CONFIGURE_MAXIMUM_GOROUTINES - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_GOROUTINES`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 400 - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number of Go -routines. - -**NOTES:** - -The Go language support is experimental - -.. COMMENT: === CONFIGURE_MAXIMUM_GO_CHANNELS === - -.. _Specify the maximum number of Go Channels: - -Specify the maximum number of Go Channels ------------------------------------------ -.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS - -*CONSTANT:* - ``CONFIGURE_MAXIMUM_GO_CHANNELS`` - -*DATA TYPE:* - Unsigned integer (``uint32_t``). - -*RANGE:* - Zero or positive. - -*DEFAULT VALUE:* - The default value is 500 - -**DESCRIPTION:** - -``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number of -Go channels. - -**NOTES:** - -The Go language support is experimental - -.. COMMENT: === Configuration Data Structures === - -Configuration Data Structures -============================= - -It is recommended that applications be configured using ``<rtems/confdefs.h>`` -as it is simpler and insulates applications from changes in the underlying data -structures. However, it is sometimes important to understand the data -structures that are automatically filled in by the configuration parameters. -This section describes the primary configuration data structures. - -If the user wishes to see the details of a particular data structure, they are -are advised to look at the source code. After all, that is one of the -advantages of RTEMS. |