diff options
Diffstat (limited to 'c-user/config/intro.rst')
| -rw-r--r-- | c-user/config/intro.rst | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst new file mode 100644 index 0000000..eb9c4c1 --- /dev/null +++ b/c-user/config/intro.rst @@ -0,0 +1,322 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2012 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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. + +.. _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 :ref:`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 :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`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 +``<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. + +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. + +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 :ref:`CONFIGURE_RTEMS_INIT_TASKS_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 :ref:`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 :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`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 :ref:`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 + :ref:`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 :ref:`CONFIGURE_MAXIMUM_TASKS` that the + application requires a maximum of four (4) simultaneously existing Classic + API tasks. Similarly, by specifying :ref:`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 + :ref:`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 :ref:`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. + +.. _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 <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. + +.. _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 :ref:`InterfaceRtemsResourceUnlimited`. 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 :c:func:`rtems_resource_unlimited`: + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) + +Object maximum specifications can be evaluated with the +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` 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 |