[PATCH] confdefs: Add declaration for unlimited objects.
Joel Sherrill
joel.sherrill at OARcorp.com
Tue Mar 27 23:33:07 UTC 2012
Instead of "proper way" to configure, how about refererring to as a way that is more predictable and deterministic?
Did you add index entry markers for the new macro names?
I thought confdefs.h was mostly if not all Doxygen comments now. If so, the new element should have Doxygen markup
--joel
Gedare Bloom <gedare at rtems.org> wrote:
>I added some documentation. ACK if ok to commit.
>
>On Tue, Mar 27, 2012 at 7:20 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 | 103 ++++++++++++++++++++++++++++++++-
>> doc/user/Makefile.am | 2 +-
>> doc/user/conf.t | 90 ++++++++++++++++++++++------
>> testsuites/samples/unlimited/system.h | 3 +-
>> 4 files changed, 176 insertions(+), 22 deletions(-)
>>
>> diff --git a/cpukit/sapi/include/confdefs.h b/cpukit/sapi/include/confdefs.h
>> index 8f03c87..3567ca2 100644
>> --- a/cpukit/sapi/include/confdefs.h
>> +++ b/cpukit/sapi/include/confdefs.h
>> @@ -1345,6 +1345,107 @@ rtems_fs_init_functions_t rtems_fs_init_helper =
>>
>>
>> /*
>> + * Unlimited objects
>> + */
>> +#if defined(CONFIGURE_UNLIMITED_OBJECTS)
>> + #if !defined(CONFIGURE_UNLIMITED_ALLOCATION_SIZE)
>> + #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 +1649,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..93bdfbd 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}:
>> -
>> - at example
>> -#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
>> - at end example
>> +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.
>>
>> -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,64 @@ 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. For such cases,
>> +see @ref{Configuring a System Sizing the RTEMS RAM Workspace}
>> +for an overview of the proper way 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 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 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