diff --git a/c-user/configuring_a_system.rst b/c-user/config/index.rst similarity index 88% rename from c-user/configuring_a_system.rst rename to c-user/config/index.rst index 75b1c7b..982a258 100644 --- a/c-user/configuring_a_system.rst +++ b/c-user/config/index.rst @@ -9,414 +9,9 @@ Configuring a System ******************** -Introduction -============ +.. toctree:: -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 must not 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:: - -The RTEMS header file ```` 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 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 ```` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - -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 -```` 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. - -.. _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 ```` 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 ```` 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 ```` -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:`ConfigUnlimitedObjects` 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 -```` 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. - -Potential Issues with RTEMS Workspace Size Estimation -===================================================== - -The ```` file estimates the amount of memory required for the -RTEMS Workspace. This estimate is only as accurate as the information given to -```` and may be either too high or too low for a variety of -reasons. Some of the reasons that ```` 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, ```` is very accurate when given enough -information. However, it is quite easy to use a library and forget to account -for its resources. - -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) - -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 - #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 - -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 - ```` instantiate the configuration data structures. This - can only be defined in one source file per application that includes - ```` 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. - -.. _ConfigUnlimitedObjects: - -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 object classes in the Classic API can be configured in unlimited -mode: - -- Barriers - -- Message Queues - -- Partitions - -- Periods - -- Ports - -- Regions - -- Semaphores - -- Tasks - -- Timers - -Additionally, the following object classes from the POSIX API can be configured -in unlimited mode: - -- Keys -- :c:func:`pthread_key_create` - -- Key Value Pairs -- :c:func:`pthread_setspecific` - -- Message Queues -- :c:func:`mq_open` - -- Named Semaphores -- :c:func:`sem_open` - -- Shared Memory -- :c:func:`shm_open` - -- Threads -- :c:func:`pthread_create` - -- Timers -- :c:func:`timer_create` - -.. warning:: - - The following object classes can *not* be configured in unlimited mode: - - - Drivers - - - File Descriptors - - - POSIX Queued Signals - - - User Extensions - -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 - -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. - -.. index:: rtems_resource_unlimited - -.. _ConfigUnlimitedObjectsClass: - -Unlimited Objects by Class --------------------------- - -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. - -.. _ConfigUnlimitedObjectsDefault: - -Unlimited Objects by Default ----------------------------- - -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 -(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size -(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`). - -.. code-block:: c - - #define CONFIGURE_UNLIMITED_OBJECTS - #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 + intro General System Configuration ============================ diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst new file mode 100644 index 0000000..636a7b8 --- /dev/null +++ b/c-user/config/intro.rst @@ -0,0 +1,412 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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 must not 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:: + +The RTEMS header file ```` 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 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 ```` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +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 +```` 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. + +.. _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 ```` 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 ```` 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 ```` +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:`ConfigUnlimitedObjects` 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 +```` 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. + +Potential Issues with RTEMS Workspace Size Estimation +===================================================== + +The ```` file estimates the amount of memory required for the +RTEMS Workspace. This estimate is only as accurate as the information given to +```` and may be either too high or too low for a variety of +reasons. Some of the reasons that ```` 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, ```` is very accurate when given enough +information. However, it is quite easy to use a library and forget to account +for its resources. + +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) + +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 + #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 + +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 + ```` instantiate the configuration data structures. This + can only be defined in one source file per application that includes + ```` 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. + +.. _ConfigUnlimitedObjects: + +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 object classes in the Classic API can be configured in unlimited +mode: + +- Barriers + +- Message Queues + +- Partitions + +- Periods + +- Ports + +- Regions + +- Semaphores + +- Tasks + +- Timers + +Additionally, the following object classes from the POSIX API can be configured +in unlimited mode: + +- Keys -- :c:func:`pthread_key_create` + +- Key Value Pairs -- :c:func:`pthread_setspecific` + +- Message Queues -- :c:func:`mq_open` + +- Named Semaphores -- :c:func:`sem_open` + +- Shared Memory -- :c:func:`shm_open` + +- Threads -- :c:func:`pthread_create` + +- Timers -- :c:func:`timer_create` + +.. warning:: + + The following object classes can *not* be configured in unlimited mode: + + - Drivers + + - File Descriptors + + - POSIX Queued Signals + + - User Extensions + +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 + +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. + +.. index:: rtems_resource_unlimited + +.. _ConfigUnlimitedObjectsClass: + +Unlimited Objects by Class +-------------------------- + +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. + +.. _ConfigUnlimitedObjectsDefault: + +Unlimited Objects by Default +---------------------------- + +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 +(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size +(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`). + +.. code-block:: c + + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 diff --git a/c-user/index.rst b/c-user/index.rst index 30cd165..e958481 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -47,7 +47,7 @@ RTEMS Classic API Guide (|version|). fatal_error board_support_packages user_extensions - configuring_a_system + config/index self_contained_objects multiprocessing symmetric_multiprocessing_services