[PATCH] confdefs: Add declaration for unlimited objects.
Gedare Bloom
gedare at rtems.org
Tue Mar 27 23:22:50 UTC 2012
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
>
More information about the devel
mailing list