[rtems commit] doc: Extend documentation for unlimited objects

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    0832ca7dc3def9aa0207c1d2952b3b53189c842b
Changeset: http://git.rtems.org/rtems/commit/?id=0832ca7dc3def9aa0207c1d2952b3b53189c842b

Author:    Ralf Kirchner <ralf.kirchner at embedded-brains.de>
Date:      Tue Apr 29 16:57:37 2014 +0200

doc: Extend documentation for unlimited objects

Mark POSIX Keys and POSIX Key Value Pairs as supported.
Add list of unsupported object classes.
Add hint to unified work areas.
Add example.

---

 doc/user/conf.t |   41 +++++++++++++++++++++++++++++++++++++----
 1 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/doc/user/conf.t b/doc/user/conf.t
index f0aa022..4709022 100644
--- a/doc/user/conf.t
+++ b/doc/user/conf.t
@@ -355,6 +355,14 @@ 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 API-independent object classes can be configured in
+unlimited mode:
+
+ at itemize @bullet
+ at item POSIX Keys
+ at item POSIX Key Value Pairs
+ at end itemize
+
 The following object classes in the Classic API can be configured in
 unlimited mode:
 
@@ -377,7 +385,6 @@ configured in unlimited mode:
 @item Threads
 @item Mutexes
 @item Condition Variables
- at item Keys
 @item Timers
 @item Message Queues
 @item Message Queue Descriptors
@@ -387,9 +394,35 @@ configured in unlimited mode:
 @item Spinlocks
 @end itemize
 
-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.
+The following object classes can @strong{not} be configured in unlimited mode:
+ at itemize @bullet
+ at item Drivers
+ at item File Descriptors
+ at item User Extensions
+ at item POSIX Queued Signals
+ at end itemize
+
+Due to the memory requirements of unlimited objects it is strongly recommended
+to use them only in combination with the unified work areas. See
+ at ref{Configuring a System 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:
+ at example
+#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>
+ at end example
 
 Users are cautioned that using unlimited objects is not recommended for
 production software unless the dynamic growth is absolutely required. It