[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