[rtems commit] confdefs: Add declaration for unlimited objects.
gedare at rtems.org
gedare at rtems.org
Wed Mar 28 00:40:07 UTC 2012
Module: rtems
Branch: master
Commit: e53aae2676c42cda521328504f82d26c33827021
Changeset: http://git.rtems.org/rtems/commit/?id=e53aae2676c42cda521328504f82d26c33827021
Author: Gedare Bloom <gedare at rtems.org>
Date: Mon Mar 26 16:42:38 2012 -0400
confdefs: Add declaration for unlimited objects.
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)
More information about the vc
mailing list