[rtems commit] Classic API Users Guide: Add SMP and affinity services.

Joel Sherrill joel at rtems.org
Tue Mar 11 23:59:21 UTC 2014


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

Author:    Joel Sherrill <joel.sherrill at oarcorp.com>
Date:      Fri Mar  7 13:20:04 2014 -0600

Classic API Users Guide: Add SMP and affinity services.

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

---

 doc/ada_user/Makefile.am   |    3 +-
 doc/ada_user/ada_user.texi |    4 +-
 doc/ada_user/example.texi  |    7 +--
 doc/user/Makefile.am       |    9 ++-
 doc/user/c_user.texi       |    2 +
 doc/user/smp.t             |  165 ++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 181 insertions(+), 9 deletions(-)

diff --git a/doc/ada_user/Makefile.am b/doc/ada_user/Makefile.am
index d628a29..ab19e71 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 d12663d..80a0e49 100644
--- a/doc/ada_user/ada_user.texi
+++ b/doc/ada_user/ada_user.texi
@@ -8,7 +8,7 @@
 @c %**end of header
 
 @c
- at c  COPYRIGHT (c) 1989-2013.
+ at 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
+ at 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 697d1e0..7456767 100644
--- a/doc/ada_user/example.texi
+++ b/doc/ada_user/example.texi
@@ -1,9 +1,9 @@
 @c
- at c  COPYRIGHT (c) 1989-2011.
+ at c  COPYRIGHT (c) 1989-2014.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 
- at node Example Application, Glossary, Directive Status Codes STATUS_TEXT - Returns a text for a status code, Top
+ at 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 eec627a..03f776d 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 a1a5fab..2085415 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
+ at 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 0000000..240613d
--- /dev/null
+++ b/doc/user/smp.t
@@ -0,0 +1,165 @@
+ at c
+ at c  COPYRIGHT (c) 2014.
+ at c  On-Line Applications Research Corporation (OAR).
+ at c  All rights reserved. 
+ at c
+
+ at chapter Symmetric Multiprocessing Services
+
+ at section Introduction
+
+This chapter describes the services related to Symmetric Multiprocessing
+provided by RTEMS. 
+
+The application level services currently provided are:
+
+ at itemize @bullet
+ at item @code{rtems_smp_get_processor_count} - Obtain Number of CPUs
+ at item @code{rtems_task_get_affinity} - Obtain Task Affinity
+ at item @code{rtems_task_set_affinity} - Set Task Affinity
+ at end itemize
+
+ at section Background
+
+ at section Operations
+
+ at 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.
+
+ at c
+ at c rtems_smp_get_processor_count
+ at c
+ at page
+ at subsection rtems_smp_get_processor_count - Obtain Number of CPUs
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#include <rtems.h>
+
+int rtems_smp_get_processor_count(void);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+Returns the number of processors being utilized.
+
+ at subheading DESCRIPTION:
+
+The @code{rtems_smp_get_processor_count} routine is used to obtain the
+number of processor cores being utilized.
+
+ at subheading NOTES:
+
+NONE
+
+ at c
+ at c rtems_task_get_affinity
+ at c
+ at page
+ at subsection rtems_task_get_affinity - Obtain Task Affinity
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#include <rtems.h>
+
+rtems_status_code rtems_task_get_affinity(
+  rtems_id             id,
+  size_t               cpusetsize,
+  cpu_set_t           *cpuset 
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item RTEMS_UNSATISFIED
+The cpuset pointer argument is invalid.
+
+ at item RTEMS_UNSATISFIED
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at item RTEMS_INVALID_ID
+The @code{id} is invalid.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{rtems_task_get_affinity} routine is used to obtain the
+ at code{affinityset} field from the thread object @code{id}.
+The value of this field is returned in @code{cpuset}
+
+ at subheading NOTES:
+
+NONE
+
+ at c
+ at c rtems_task_set_affinity
+ at c
+ at page
+ at subsection rtems_task_set_affinity - Set Task Affinity
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#include <rtems.h>
+
+rtems_status_code rtems_task_set_affinity(
+  rtems_id             id,
+  size_t               cpusetsize,
+  cpu_set_t           *cpuset 
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item RTEMS_UNSATISFIED
+The cpuset pointer argument is invalid.
+
+ at item RTEMS_UNSATISFIED
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at item RTEMS_UNSATISFIED
+The @code{cpuset} did not select a valid cpu.
+
+ at item RTEMS_UNSATISFIED
+The @code{cpuset} selected a cpu that was invalid.
+
+ at item RTEMS_INVALID_ID
+The @code{id} is invalid.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{rtems_task_set_affinity} routine is used to set the
+ at code{affinity.set} field of the thread control object associated
+with @code{id}.  This value controls the cpuset that the task can
+execute on.
+
+ at subheading NOTES:
+
+NONE




More information about the vc mailing list