Classic API Users Guide: Add SMP and affinity services.

This patch adds the initial version of the SMP chapter to the Users Guide.

6 files changed, 181 insertions, 9 deletions

diff --git a/doc/ada_user/Makefile.am b/doc/ada_user/Makefile.am
index d628a29669..ab19e71643 100644
--- a/doc/ada_user/Makefile.am
+++ b/doc/ada_user/Makefile.am
@@ -24,7 +24,8 @@ COMMON_FILES += \
     $(top_builddir)/user/task.texi $(top_builddir)/user/timer.texi \
     $(top_builddir)/user/userext.texi $(top_builddir)/user/stackchk.texi \
     $(top_builddir)/user/cpuuse.texi $(top_srcdir)/common/cpright.texi \
-    $(top_builddir)/user/object.texi $(top_builddir)/user/cbs.texi
+    $(top_builddir)/user/object.texi $(top_builddir)/user/cbs.texi \
+    $(top_builddir)/user/smp.texi
 
 FILES = example.texi
 
diff --git a/doc/ada_user/ada_user.texi b/doc/ada_user/ada_user.texi
index d12663d81f..80a0e49c11 100644
--- a/doc/ada_user/ada_user.texi
+++ b/doc/ada_user/ada_user.texi
@@ -8,7 +8,7 @@
 @c %**end of header
 
 @c
-@c  COPYRIGHT (c) 1989-2013.
+@c  COPYRIGHT (c) 1989-2014.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 
@@ -107,6 +107,7 @@
 * User Extensions Manager::
 * Configuring a System::
 * Multiprocessing Manager::
+* Symmetric Multiprocessing Services::
 * Stack Bounds Checker::
 * CPU Usage Statistics::
 * Object Services::
@@ -150,6 +151,7 @@
 @include user/userext.texi
 @include user/conf.texi
 @include user/mp.texi
+@include user/smp.texi
 @include user/stackchk.texi
 @include user/cpuuse.texi
 @include user/object.texi
diff --git a/doc/ada_user/example.texi b/doc/ada_user/example.texi
index 697d1e0153..74567672a8 100644
--- a/doc/ada_user/example.texi
+++ b/doc/ada_user/example.texi
@@ -1,9 +1,9 @@
 @c
-@c  COPYRIGHT (c) 1989-2011.
+@c  COPYRIGHT (c) 1989-2014.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 
-@node Example Application, Glossary, Directive Status Codes STATUS_TEXT - Returns a text for a status code, Top
+@node Example Application, Glossary, Directive Status Codes STATUS_CODE_DESCRIPTION - Returns a description for a status code, Top
 @chapter Example Application
 
 @example
@@ -11,6 +11,3 @@
 Currently there is no example Ada application provided.
 
 @end example
-
-
-
diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
index eec627a882..03f776db09 100644
--- a/doc/user/Makefile.am
+++ b/doc/user/Makefile.am
@@ -15,7 +15,7 @@ GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \
     signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \
     schedule.texi rtmon.texi barrier.texi bsp.texi userext.texi conf.texi \
     mp.texi stackchk.texi cpuuse.texi object.texi chains.texi timespec.texi \
-    cbs.texi dirstat.texi
+    cbs.texi dirstat.texi smp.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
 
@@ -161,10 +161,15 @@ conf.texi: conf.t
 mp.texi: mp.t
 	$(BMENU2) -p "Configuring a System Configuration Data Structures" \
 	    -u "Top" \
+	    -n "Symmetric Multiprocessing Services" < $< > $@
+
+smp.texi: smp.t
+	$(BMENU2) -p  "Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet"\
+	    -u "Top" \
 	    -n "Stack Bounds Checker" < $< > $@
 
 stackchk.texi: stackchk.t
-	$(BMENU2) -p "Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet" \
+	$(BMENU2) -p "Symmetric Multiprocessing Services rtems_task_set_affinity - Set Task Affinity" \
 	    -u "Top" \
 	    -n "CPU Usage Statistics" < $< > $@
 
diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi
index a1a5fab026..2085415e3a 100644
--- a/doc/user/c_user.texi
+++ b/doc/user/c_user.texi
@@ -106,6 +106,7 @@
 * User Extensions Manager::
 * Configuring a System::
 * Multiprocessing Manager::
+* Symmetric Multiprocessing Services::
 * Stack Bounds Checker::
 * CPU Usage Statistics::
 * Object Services::
@@ -149,6 +150,7 @@
 @include userext.texi
 @include conf.texi
 @include mp.texi
+@include smp.texi
 @include stackchk.texi
 @include cpuuse.texi
 @include object.texi
diff --git a/doc/user/smp.t b/doc/user/smp.t
new file mode 100644
index 0000000000..240613ddea
--- /dev/null
+++ b/doc/user/smp.t
@@ -0,0 +1,165 @@
+@c
+@c  COPYRIGHT (c) 2014.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved. 
+@c
+
+@chapter Symmetric Multiprocessing Services
+
+@section Introduction
+
+This chapter describes the services related to Symmetric Multiprocessing
+provided by RTEMS. 
+
+The application level services currently provided are:
+
+@itemize @bullet
+@item @code{rtems_smp_get_processor_count} - Obtain Number of CPUs
+@item @code{rtems_task_get_affinity} - Obtain Task Affinity
+@item @code{rtems_task_set_affinity} - Set Task Affinity
+@end itemize
+
+@section Background
+
+@section Operations
+
+@section Directives
+
+This section details the symmetric multiprocessing services.  A subsection
+is dedicated to each of these services and describes the calling sequence,
+related constants, usage, and status codes.
+
+@c
+@c rtems_smp_get_processor_count
+@c
+@page
+@subsection rtems_smp_get_processor_count - Obtain Number of CPUs
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+#include <rtems.h>
+
+int rtems_smp_get_processor_count(void);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+Returns the number of processors being utilized.
+
+@subheading DESCRIPTION:
+
+The @code{rtems_smp_get_processor_count} routine is used to obtain the
+number of processor cores being utilized.
+
+@subheading NOTES:
+
+NONE
+
+@c
+@c rtems_task_get_affinity
+@c
+@page
+@subsection rtems_task_get_affinity - Obtain Task Affinity
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+#include <rtems.h>
+
+rtems_status_code rtems_task_get_affinity(
+  rtems_id             id,
+  size_t               cpusetsize,
+  cpu_set_t           *cpuset 
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+@table @b
+@item RTEMS_UNSATISFIED
+The cpuset pointer argument is invalid.
+
+@item RTEMS_UNSATISFIED
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+@item RTEMS_INVALID_ID
+The @code{id} is invalid.
+
+@end table
+
+@subheading DESCRIPTION:
+
+The @code{rtems_task_get_affinity} routine is used to obtain the
+@code{affinityset} field from the thread object @code{id}.
+The value of this field is returned in @code{cpuset}
+
+@subheading NOTES:
+
+NONE
+
+@c
+@c rtems_task_set_affinity
+@c
+@page
+@subsection rtems_task_set_affinity - Set Task Affinity
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+#include <rtems.h>
+
+rtems_status_code rtems_task_set_affinity(
+  rtems_id             id,
+  size_t               cpusetsize,
+  cpu_set_t           *cpuset 
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+@table @b
+@item RTEMS_UNSATISFIED
+The cpuset pointer argument is invalid.
+
+@item RTEMS_UNSATISFIED
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+@item RTEMS_UNSATISFIED
+The @code{cpuset} did not select a valid cpu.
+
+@item RTEMS_UNSATISFIED
+The @code{cpuset} selected a cpu that was invalid.
+
+@item RTEMS_INVALID_ID
+The @code{id} is invalid.
+
+@end table
+
+@subheading DESCRIPTION:
+
+The @code{rtems_task_set_affinity} routine is used to set the
+@code{affinity.set} field of the thread control object associated
+with @code{id}.  This value controls the cpuset that the task can
+execute on.
+
+@subheading NOTES:
+
+NONE