[PATCH] confdefs: Add declaration for unlimited objects.
Gedare Bloom
gedare at rtems.org
Wed Mar 28 00:44:47 UTC 2012
On Tue, Mar 27, 2012 at 8:02 PM, Joel Sherrill
<joel.sherrill at oarcorp.com> wrote:
> Looks Ok to me. Commit it and add an entry to the 4.11 release notes page
>
Done and done.
> Gedare Bloom <gedare at rtems.org> wrote:
>
>>Please review.
>>
>>On Tue, Mar 27, 2012 at 7:52 PM, Gedare Bloom <gedare at rtems.org> wrote:
>>> Adds to confdefs a way to specify rtems_resource_unlimited for classic and
>>> posix objects using a new macro CONFIGURE_OBJECTS_UNLIMITED.
>>> Use CONFIGURE_OBJECTS_ALLOCATION_SIZE to declare the allocation size for
>>> extending the set of objects at runtime. Updates the unlimited sample
>>> to demonstrate how to use the new macros. Also adds new documentation in
>>> the C User's Manual regarding configuring with unlimited objects.
>>> ---
>>> cpukit/sapi/include/confdefs.h | 108 ++++++++++++++++++++++++++++++++-
>>> doc/user/Makefile.am | 2 +-
>>> doc/user/conf.t | 93 ++++++++++++++++++++++------
>>> testsuites/samples/unlimited/system.h | 3 +-
>>> 4 files changed, 184 insertions(+), 22 deletions(-)
>>>
>>> diff --git a/cpukit/sapi/include/confdefs.h b/cpukit/sapi/include/confdefs.h
>>> index 8f03c87..ab8e473 100644
>>> --- a/cpukit/sapi/include/confdefs.h
>>> +++ b/cpukit/sapi/include/confdefs.h
>>> @@ -1344,6 +1344,112 @@ rtems_fs_init_functions_t rtems_fs_init_helper =
>>> #endif
>>>
>>>
>>> +/**
>>> + * This macro specifies that the user wants to use unlimited objects for any
>>> + * classic or posix objects that have not already been given resource limits.
>>> + */
>>> +#if defined(CONFIGURE_UNLIMITED_OBJECTS)
>>> + #if !defined(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + /**
>>> + * This macro specifies a default allocation size for when auto-extending
>>> + * unlimited objects if none was given by the user.
>>> + */
>>> + #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 8
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_TASKS)
>>> + #define CONFIGURE_MAXIMUM_TASKS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_TIMERS)
>>> + #define CONFIGURE_MAXIMUM_TIMERS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_SEMAPHORES)
>>> + #define CONFIGURE_MAXIMUM_SEMAPHORES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_MESSAGE_QUEUES)
>>> + #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_PARTITIONS)
>>> + #define CONFIGURE_MAXIMUM_PARTITIONS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_REGIONS)
>>> + #define CONFIGURE_MAXIMUM_REGIONS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_PORTS)
>>> + #define CONFIGURE_MAXIMUM_PORTS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_PERIODS)
>>> + #define CONFIGURE_MAXIMUM_PERIODS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_BARRIERS)
>>> + #define CONFIGURE_MAXIMUM_BARRIERS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> +
>>> + #ifdef RTEMS_POSIX_API
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_THREADS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_THREADS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_MUTEXES)
>>> + #define CONFIGURE_MAXIMUM_POSIX_MUTEXES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES)
>>> + #define CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> +/*
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_KEYS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_KEYS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> +*/
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_TIMERS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_TIMERS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> +/*
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> +*/
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES)
>>> + #define CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_SEMAPHORES)
>>> + #define CONFIGURE_MAXIMUM_POSIX_SEMAPHORES \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_BARRIERS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_BARRIERS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_RWLOCKS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_RWLOCKS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #if !defined(CONFIGURE_MAXIMUM_POSIX_SPINLOCKS)
>>> + #define CONFIGURE_MAXIMUM_POSIX_SPINLOCKS \
>>> + rtems_resource_unlimited(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>>> + #endif
>>> + #endif /* RTEMS_POSIX_API */
>>> +#endif /* CONFIGURE_UNLIMITED_OBJECTS */
>>> +
>>> +
>>> /*
>>> * Default Configuration Table.
>>> */
>>> @@ -1548,7 +1654,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper =
>>> */
>>> #define _Configure_POSIX_Named_Object_RAM(_number, _size) \
>>> _Configure_Object_RAM( (_number), _size ) + \
>>> - ((_number) * _Configure_From_workspace(NAME_MAX) )
>>> + (_Configure_Max_Objects(_number) * _Configure_From_workspace(NAME_MAX) )
>>>
>>> #ifndef CONFIGURE_MAXIMUM_POSIX_THREADS
>>> #define CONFIGURE_MAXIMUM_POSIX_THREADS 0
>>> diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
>>> index 847767d..af2b24d 100644
>>> --- a/doc/user/Makefile.am
>>> +++ b/doc/user/Makefile.am
>>> @@ -161,7 +161,7 @@ conf.texi: conf.t
>>> -n "Multiprocessing Manager" < $< > $@
>>>
>>> mp.texi: mp.t
>>> - $(BMENU2) -p "Configuring a System Sizing the RTEMS RAM Workspace" \
>>> + $(BMENU2) -p "Configuring a System Unlimited Objects" \
>>> -u "Top" \
>>> -n "Stack Bounds Checker" < $< > $@
>>>
>>> diff --git a/doc/user/conf.t b/doc/user/conf.t
>>> index f4a581d..d7f6809 100644
>>> --- a/doc/user/conf.t
>>> +++ b/doc/user/conf.t
>>> @@ -2135,7 +2135,7 @@ parameters the application developer can specify to
>>> help @code{<rtems/confdefs.h>} in its calculations. Correctly
>>> specifying the application requirements via parameters
>>> such as @code{CONFIGURE_EXTRA_TASK_STACKS} and
>>> - at code{CONFIGURE_MAXIMUM_TASKS} is critical.
>>> + at code{CONFIGURE_MAXIMUM_TASKS} is critical for production software.
>>>
>>> The allocation of objects can operate in two modes. The default mode
>>> has an object number ceiling. No more than the specified number of
>>> @@ -2144,27 +2144,18 @@ specified in the particular API Configuration table fields are
>>> allocated at initialisation. The second mode allows the number of
>>> objects to grow to use the available free memory in the RTEMS RAM Workspace.
>>>
>>> -The auto-extending mode can be enabled individually for each object
>>> -type by using the macro @code{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 RAM Workspace
>>> -when an object is destroyed. The kernel will only return an allocated
>>> -block of objects to the RTEMS RAM 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
>>> - at code{rtems_resource_unlimited}:
>>> +See @ref{Configuring a System Unlimited Objects} for more details
>>> +about the second mode, 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.
>>>
>>> - at example
>>> -#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
>>> - at end example
>>> -
>>> -The user is cautioned that future versions of RTEMS may not have the
>>> +Note that future versions of RTEMS may not have the
>>> same memory requirements per object. Although the value calculated is
>>> -suficient for a particular target processor and release of RTEMS,
>>> +sufficient for a particular target processor and release of RTEMS,
>>> memory usage is subject to change across versions and target
>>> -processors. To avoid problems, the user should accurately
>>> +processors. To avoid problems, users should accurately
>>> specify each configuration parameter and allow
>>> @code{<rtems/confdefs.h>} to calculate the memory requirements.
>>> The memory requirements are likely to change each
>>> @@ -2182,3 +2173,67 @@ Failure to provide enough space in the RTEMS RAM
>>> Workspace will result in the
>>> @code{@value{DIRPREFIX}fatal_error_occurred} directive
>>> being invoked with the appropriate error code.
>>> +
>>> + at subsection 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{Configuring a System Sizing the RTEMS RAM 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.
>>> +
>>> +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 @code{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 RAM Workspace
>>> +when an object is destroyed. The kernel will only return an allocated
>>> +block of objects to the RTEMS RAM 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
>>> + at code{rtems_resource_unlimited}:
>>> +
>>> + at example
>>> +#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
>>> + at end example
>>> +
>>> +To ease the burden of developers who are porting new software RTEMS also
>>> +provides the following macros:
>>> + at itemize @bullet
>>> +
>>> + at findex CONFIGURE_OBJECTS_UNLIMITED
>>> + at item @code{CONFIGURE_OBJECTS_UNLIMITED}
>>> +uses @code{rtems_resource_unlimited} for classic and posix objects that
>>> +do not already have a maximum limit defined.
>>> +
>>> + at findex CONFIGURE_OBJECTS_ALLOCATION_SIZE
>>> + at item @code{CONFIGURE_OBJECTS_ALLOCATION_SIZE}
>>> +provides an allocation size to use for @code{rtems_resource_unlimited} when
>>> +using @code{CONFIGURE_OBJECTS_UNLIMITED}; the default value is 8.
>>> +
>>> + at end itemize
>>> +
>>> +By allowing users to declare all resources as being unlimited the user
>>> +can avoid identifying and limiting the resources used.
>>> + at code{CONFIGURE_OBJECTS_UNLIMITED} does not support varying
>>> +the allocation sizes for different objects; users who want that
>>> +much control can define the @code{rtems_resource_unlimited} macros themselves.
>>> +
>>> + at example
>>> +#define CONFIGURE_OBJECTS_UNLIMITED
>>> +#define CONFIGURE_OBJECTS_ALLOCATION_SIZE 5
>>> + at end example
>>> +
>>> +Due to how the posix object memory requirements are configured the
>>> +unlimited object support does not provide unlimited size declarations
>>> +for posix keys or queued signals.
>>> +
>>> +Users are cautioned that using unlimited objects is not recommended for
>>> +production software unless the dynamic growth is absolutely required.
>>> diff --git a/testsuites/samples/unlimited/system.h b/testsuites/samples/unlimited/system.h
>>> index e1c9cb7..8acbded 100644
>>> --- a/testsuites/samples/unlimited/system.h
>>> +++ b/testsuites/samples/unlimited/system.h
>>> @@ -50,7 +50,8 @@ extern void test3(void);
>>> #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
>>>
>>> #define TASK_ALLOCATION_SIZE (5)
>>> -#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(TASK_ALLOCATION_SIZE)
>>> +#define CONFIGURE_UNLIMITED_OBJECTS
>>> +#define CONFIGURE_UNLIMITED_ALLOCATION_SIZE TASK_ALLOCATION_SIZE
>>> #define CONFIGURE_INIT_TASK_STACK_SIZE (8 * 1024)
>>>
>>>
>>> --
>>> 1.7.4.4
>>>
>>
>>_______________________________________________
>>rtems-devel mailing list
>>rtems-devel at rtems.org
>>http://www.rtems.org/mailman/listinfo/rtems-devel
More information about the devel
mailing list