2009-11-09 Joel Sherrill <joel.sherrill@oarcorp.com>

* ada_user/Makefile.am, ada_user/ada_user.texi, user/Makefile.am,
	user/c_user.texi, user/concepts.t, user/overview.t,
	user/preface.texi, user/schedule.t, user/sem.t: Add table of figures.
	Add text and graphic of tree illustrating valid combinations of
	semaphore attributes.
	* user/semaphore_attributes.eps, user/semaphore_attributes.png:
	New files.

doc/ChangeLog

@@ -1,3 +1,13 @@
+2009-11-09	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* ada_user/Makefile.am, ada_user/ada_user.texi, user/Makefile.am,
+	user/c_user.texi, user/concepts.t, user/overview.t,
+	user/preface.texi, user/schedule.t, user/sem.t: Add table of figures.
+	Add text and graphic of tree illustrating valid combinations of
+	semaphore attributes.
+	* user/semaphore_attributes.eps, user/semaphore_attributes.png:
+	New files.
+
 2009-10-14	Joel Sherrill <joel.sherrill@oarcorp.com>
 
 	* bsp_howto/console.t: Capitalization.

doc/ada_user/Makefile.am

@@ -38,10 +38,12 @@ ObjectId-32Bits.eps: $(top_srcdir)/user/ObjectId-32Bits.eps
 	$(LN_S) $<
 rtemspie.eps: $(top_srcdir)/user/rtemspie.eps
 	$(LN_S) $<
+semaphore_attributes.eps: $(top_srcdir)/user/semaphore_attributes.eps
+	$(LN_S) $<
 states.eps: $(top_srcdir)/user/states.eps
 	$(LN_S) $<
-CLEANFILES += rtemspie.eps states.eps rtemsarc.png rtemspie.png states.png \
-    ObjectId-32Bits.png
+CLEANFILES += rtrtemspie.eps states.eps rtemsarc.png rtemspie.png states.png \
+    ObjectId-32Bits.png semaphore_attributes.png
 
 ObjectId-16Bits.png: $(top_srcdir)/user/ObjectId-16Bits.png
 	$(LN_S) $<
@@ -51,6 +53,8 @@ rtemsarc.png: $(top_srcdir)/user/rtemsarc.png
 	$(LN_S) $<
 rtemspie.png: $(top_srcdir)/user/rtemspie.png
 	$(LN_S) $<
+semaphore_attributes.png: $(top_srcdir)/user/semaphore_attributes.png
+	$(LN_S) $<
 states.png: $(top_srcdir)/user/states.png
 	$(LN_S) $<
 
@@ -59,11 +63,11 @@ ada_user_TEXINFOS = $(FILES) $(COMMON_FILES)
 
 if USE_HTML
 html_project_DATA += rtemsarc.png rtemspie.png states.png \
-    ObjectId-16Bits.png ObjectId-32Bits.png
+    ObjectId-16Bits.png ObjectId-32Bits.png semaphore_attributes.png
 endif
 
 $(PROJECT).dvi: rtemspie.eps states.eps ObjectId-16Bits.eps \
-    ObjectId-32Bits.eps
+    ObjectId-32Bits.eps semaphore_attributes.eps
 PDF_IMAGES = rtemspie.pdf states.pdf
 
 CLEANFILES += ada_user.info ada_user.info-? ada_user.info-??

doc/ada_user/ada_user.texi

@@ -79,6 +79,10 @@
 
 @contents
 
+@node List of Figures, Preface, Top, Top
+@unnumbered List of Figures
+@listoffloats Figure
+
 @include user/preface.texi
 @include user/overview.texi
 @include user/concepts.texi
@@ -112,12 +116,13 @@
 @include example.texi
 @include user/glossary.texi
 @ifinfo
-@node Top, Preface, (dir), (dir)
+@node Top, List of Figures, (dir), (dir)
 @top ada_user
 
 This is the online version of the RTEMS Ada User's Guide.
 
 @menu
+* List of Figures::
 * Preface::
 * Overview::
 * Key Concepts::

doc/user/Makefile.am

@@ -28,14 +28,14 @@ c_user_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
 TXT_FILES = rtemsarc.txt rtemspie.txt states.txt
 
 PNG_FILES = rtemsarc.png rtemspie.png states.png ObjectId-32Bits.png \
-    ObjectId-16Bits.png
+    ObjectId-16Bits.png semaphore_attributes.png
 
 EPS_IMAGES = rtemspie.eps states.eps ObjectId-32Bits.eps \
-    ObjectId-32Bits.eps
+    ObjectId-32Bits.eps semaphore_attributes.eps
 $(PROJECT).dvi: $(EPS_IMAGES)
 
 PDF_IMAGES = rtemspie.pdf states.pdf ObjectId-16Bits.pdf \
-    ObjectId-32Bits.pdf
+    ObjectId-32Bits.pdf semaphore_attributes.pdf
 CLEANFILES += $(PDF_IMAGES)
 
 if USE_HTML

doc/user/c_user.texi

@@ -78,6 +78,10 @@
 
 @contents
 
+@node List of Figures, Preface, Top, Top
+@unnumbered List of Figures
+@listoffloats Figure
+
 @include preface.texi
 @include overview.texi
 @include concepts.texi
@@ -111,12 +115,13 @@
 @include example.texi
 @include glossary.texi
 @ifinfo
-@node Top, Preface, (dir), (dir)
+@node Top, List of Figures, (dir), (dir)
 @top c_user
 
 This is the online version of the RTEMS C User's Guide.
 
 @menu
+* List of Figures::
 * Preface::
 * Overview::
 * Key Concepts::

doc/user/concepts.t

@@ -136,6 +136,9 @@ object class, node, and index.  The data type @code{@value{DIRPREFIX}id}
 is used to store object IDs.
 
 
+@float Figure,fig:Object-Id-32
+@caption{Thirty-Two Bit Object Id}
+
 @ifset use-ascii
 @example
 @group
@@ -151,15 +154,16 @@ is used to store object IDs.
 
 @ifset use-tex
 @sp1
-@center{@image{ObjectId-32Bits,,2in}}
+@center{@image{ObjectId-32Bits,,2in,Thirty-Two Bit Object Id}}
 @end ifset
 
 @ifset use-html
 @html
 <P ALIGN="center"><IMG SRC="ObjectId-32Bits.png"
-     WIDTH=550 HEIGHT=400 ALT="32 Bit Object Id"></P>
+     WIDTH=550 HEIGHT=400 ALT="Thirty-Two Bit Object Id"></P>
 @end html
 @end ifset
+@end float
 
 The most significant five bits are the object class.  The next
 three bits indicate the API to which the object class belongs.
@@ -176,6 +180,9 @@ The sixteen bit format for an object ID is composed of three parts: API,
 object class, and index.  The data type @code{@value{DIRPREFIX}id}
 is used to store object IDs.
 
+@float Figure,fig:Object-Id-16
+@caption{Sixteen Bit Object Id}
+
 
 @ifset use-ascii
 @example
@@ -192,7 +199,7 @@ is used to store object IDs.
 
 @ifset use-tex
 @sp1
-@center{@image{ObjectId-16Bits,,2in}}
+@center{@image{ObjectId-16Bits,,2in,Sixteen Bit Object Id}}
 @end ifset
 
 @ifset use-html
@@ -201,6 +208,7 @@ is used to store object IDs.
      WIDTH=550 HEIGHT=400 ALT="16 Bit Object Id"></P>
 @end html
 @end ifset
+@end float
 
 The sixteen-bit format is designed to be as similar as possible to the
 thrity-two bit format.  The differences are limited to the eliminatation

doc/user/overview.t

@@ -141,6 +141,9 @@ project dependent application code and the target hardware.
 Most hardware dependencies for real-time applications can be
 localized to the low level device drivers.
 
+@float Figure,fig:RTEMS-App-Arch
+@caption{RTEMS Application Architecture}
+
 @ifset use-ascii
 @example
 @group
@@ -214,6 +217,7 @@ localized to the low level device drivers.
 <IMG SRC="rtemsarc.png" WIDTH=500 HEIGHT=300 ALT="RTEMS Application Architecture">
 @end html
 @end ifset
+@end float
 
 The RTEMS I/O interface manager provides an efficient tool for incorporating
 these hardware dependencies into the system while simultaneously
@@ -236,6 +240,9 @@ Together these components provide a powerful run time
 environment that promotes the development of efficient real-time
 application systems.  The following figure illustrates this organization:
 
+@float Figure,fig:rtems-layers
+@caption{RTEMS Layered Architecture}
+
 @ifset use-ascii
 @example
 @group
@@ -251,28 +258,18 @@ application systems.  The following figure illustrates this organization:
 @end ifset
 
 @ifset use-tex
-@c for now use the ascii version
-@c @example
-@c @group
-@c            +-----------------------------------------------+
-@c            |          RTEMS Executive Interface            |
-@c            +-----------------------------------------------+
-@c            |                 RTEMS Core                    |
-@c            +-----------------------------------------------+
-@c            |              CPU Dependent Code               |
-@c            +-----------------------------------------------+
-@c @end group
-@c @end example
-@image{rtemspie,4in,3in}
+@center{@image{rtemspie,4in,3in, RTEMS Layered Architecture}}
 @tex
 @end tex
 @end ifset
 
 @ifset use-html
 @html
-<IMG SRC="rtemspie.png" WIDTH=500 HEIGHT=300 ALT="RTEMS Architecture">
+<IMG SRC="rtemspie.png" WIDTH=500 HEIGHT=300 ALT="RTEMS Layered Architecture">
 @end html
 @end ifset
+@end float
+
 Subsequent chapters present a detailed description of the capabilities
 provided by each of the following RTEMS managers:
 

doc/user/preface.texi

@@ -7,7 +7,7 @@
 @c
 
 @ifinfo
-@node Preface, Overview, Top, Top
+@node Preface, Overview, List of Figures, Top
 @end ifinfo
 @unnumbered Preface
 

doc/user/schedule.t

@@ -207,6 +207,9 @@ directive, at which time it enters the ready state.  The task is
 now permitted to be scheduled for the processor and to compete
 for other system resources.
 
+@float Figure,fig:RTEMS-Task-States
+@caption{RTEMS Task States}
+
 @ifset use-ascii
 @example
 @group
@@ -243,35 +246,7 @@ for other system resources.
 @ifset use-tex
 @c @page
 @example
-@image{states,,3in}
-@c @group
-@c      +-------------------------------------------------------------+
-@c      |                         Non-existent                        |
-@c      |  +-------------------------------------------------------+  |
-@c      |  |                                                       |  |
-@c      |  |                                                       |  |
-@c      |  |      Creating        +---------+     Deleting         |  |
-@c      |  | -------------------> | Dormant | -------------------> |  |
-@c      |  |                      +---------+                      |  |
-@c      |  |                           |                           |  |
-@c      |  |                  Starting |                           |  |
-@c      |  |                           |                           |  |
-@c      |  |                           V          Deleting         |  |
-@c      |  |             +-------> +-------+ ------------------->  |  |
-@c      |  |  Yielding  /   +----- | Ready | ------+               |  |
-@c      |  |           /   /       +-------+ <--+   \              |  |
-@c      |  |          /   /                      \   \ Blocking    |  |
-@c      |  |         /   / Dispatching   Readying \   \            |  |
-@c      |  |        /   V                          \   V           |  |
-@c      |  |      +-----------+    Blocking     +---------+        |  |
-@c      |  |      | Executing | --------------> | Blocked |        |  |
-@c      |  |      +-----------+                 +---------+        |  |
-@c      |  |                                                       |  |
-@c      |  |                                                       |  |
-@c      |  +-------------------------------------------------------+  |
-@c      |                         Non-existent                        |
-@c      +-------------------------------------------------------------+
-@c @end group
+@center{@image{states,,3in,RTEMS Task States}}
 @end example
 @end ifset
 
@@ -280,6 +255,7 @@ for other system resources.
 <IMG SRC="states.png" WIDTH=550 HEIGHT=400 ALT="RTEMS Task States">
 @end html
 @end ifset
+@end float
 
 A task occupies the blocked state whenever it is
 unable to be scheduled to run.  A running task may block itself

doc/user/sem.t

@@ -232,6 +232,35 @@ default for all created tasks.  If a similar semaphore were to be known
 globally, then the attribute_set parameter would be
 @code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
 
+Some combinatinos of these attributes are invalid.  For example, priority
+ordered blocking discipline must be applied to a binary semaphore in order
+to use either the priority inheritance or priority ceiling functionality.
+The following tree figure illustrates the valid combinations.
+
+@float Figure,fig:semaphore-attributes
+@caption{Valid Semaphore Attributes Combinations}
+
+@ifset use-ascii
+@example
+@group
+Not available in ASCII representation
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@example
+@image{semaphore_attributes,5in,3.5in}
+@end example
+@end ifset
+
+@ifset use-html
+@html
+<IMG SRC="semaphore_attributes.png" WIDTH=550 HEIGHT=400 ALT="Valid Semaphore Attribute Combinations">
+@end html
+@end ifset
+@end float
+
 @subsection Building a SEMAPHORE_OBTAIN Option Set
 
 In general, an option is built by a bitwise OR of the
@@ -468,9 +497,9 @@ inheritance (default)
 @item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
 ceiling (default)
 
-@item @code{@value{RPREFIX}LOCAL} - local task (default)
+@item @code{@value{RPREFIX}LOCAL} - local semaphore (default)
 
-@item @code{@value{RPREFIX}GLOBAL} - global task
+@item @code{@value{RPREFIX}GLOBAL} - global semaphore
 @end itemize
 
 Semaphores should not be made global unless remote
@@ -480,9 +509,11 @@ semaphore.  When a global semaphore is created, the semaphore's
 name and id must be transmitted to every node in the system for
 insertion in the local copy of the global object table.
 
-The total number of global objects, including
-semaphores, is limited by the maximum_global_objects field in
-the Configuration Table.
+Note that some combinations of attributes are not valid.  See the
+earlier discussion on this.
+
+The total number of global objects, including semaphores, is limited by
+the maximum_global_objects field in the Configuration Table.
 
 @c
 @c