From d46ab11bcd2c662d59ca7d40a98f0e718c0df155 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 7 Mar 2014 13:20:04 -0600 Subject: 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(-) create mode 100644 doc/user/smp.t 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 @@ -160,11 +160,16 @@ 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 + +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_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_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 -- cgit v1.2.3