[PATCH] smp: Documentation

Fri Sep 4 06:49:16 UTC 2015

On 03/09/15 17:09, Gedare Bloom wrote:
> On Thu, Sep 3, 2015 at 8:46 AM, Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
>> ---
>>   doc/user/smp.t | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 66 insertions(+)
>>
>> diff --git a/doc/user/smp.t b/doc/user/smp.t
>> index 2ab9aaf..a06be8a 100644
>> --- a/doc/user/smp.t
>> +++ b/doc/user/smp.t
>> @@ -465,6 +465,72 @@ architecture please consult the @cite{RTEMS CPU Architecture Supplement}.
>>   The only remaining user of task variables in the RTEMS code base is the Ada
>>   support.  So basically Ada is not available on RTEMS SMP.
>>
>> + at subsection OpenMP
>> +
>> +OpenMP support for RTEMS is available via the GCC provided libgomp.  There is
>> +libgomp support for RTEMS in the POSIX configuration since GCC 4.9 (requires a
>> +Newlib snapshot after 2015-03-12). In GCC 6.1 or later (requires a Newlib
>> +snapshot after 2015-07-30 for <sys/lock.h> provided self-contained
> Do these versions relate to any release versions of RTEMS, e.g. did
> this stuff make it into the toolchains for 4.11? Translating between
> gcc/newlib versions and RTEMS versions is a bit of work for casual
> user to know if this support will be available or not for them.

In case the manual includes this section, then its supported by RTEMS. 
It helps to check if you use the right tool chain version. In general it 
would be nice to collect such information in a well known central place.

>
>> +synchronization objects) there is RTEMS support in a RTEMS specific
> hyphenate: "RTEMS-specific" here and below.
>
>> +configuration which offers a significantly better performance compared to the
> "libgomp configuration"
>
>> +POSIX configuration (the term configuration refers here to the libgomp
>> +configuration and should not be confused with the POSIX API provided by RTEMS).
>> +In addition scheduler instance specific thread pools may be defined.
> Last sentence doesn't say why that matters. Perhaps just say something
> about discussing this further below.

Hm, I wanted to say that the thread pools are new in GCC 6.1 and not 
available before.

>
>> +
>> +The run-time configuration of libgomp is done via environment variables
>> +documented in the @uref{https://gcc.gnu.org/onlinedocs/libgomp/, libgomp
>> +manual}.  The environment variables are evaluated in a constructor function
>> +which executes in the context of the first initialization task before the
>> +actual initialization task function is called (just like a global C++
>> +constructor).  To set application specific values, a higher priority
> hyphenate: "application-specific"
>
>> +constructor function must be used to set up the environment variables.
>> +
>> + at example
>> + at group
>> +#include <stdlib.h>
>> +
>> +static void __attribute__((constructor(1000))) config_libgomp( void )
>> +@{
>> +  setenv( "OMP_DISPLAY_ENV", "VERBOSE", 1 );
>> +  setenv( "GOMP_SPINCOUNT", "30000", 1 );
>> +  setenv( "GOMP_RTEMS_THREAD_POOLS", "1$2@@SCHD", 1 );
>> +@}
>> + at end group
>> + at end example
>> +
> The following discussion may warrant it's own subsection on Thread Pools.
>
>> +The environment variable @env{GOMP_RTEMS_THREAD_POOLS} is RTEMS specific.  It
>> +determines the scheduler instance specific thread pools.  The format for
> hyphenate: "instance-specific"

Shouldn't this be "scheduler-instance-specific" ?

Maybe use "determines the thread pools for each scheduler instance".

>
>> + at env{GOMP_RTEMS_THREAD_POOLS} is a list of optional
>> + at code{<thread-pool-count>[$<priority>]@@<scheduler-name>} configurations
>> +separated by @code{:} where:
>> +
>> + at itemize @bullet
>> + at item @code{<thread-pool-count>} is the thread pool count for this scheduler
>> +instance.
>> + at item @code{$<priority>} is an optional priority for the worker threads of a
>> +thread pool according to @code{pthread_setschedparam}.  In case a priority
>> +value is omitted, then a worker thread will inherit the priority of the OpenMP
>> +master thread that created it.  The priority of the worker thread is not
>> +changed after creation, even if a new OpenMP master thread using the worker has
> This statement "priority of the worker thread is not changed after
> creation" probably is not accurate, in case of PIP/PCP or API calls to
> change priority. It might be better to state that the priority is not
> changed despite a change in the master thread?

The priority is implicitly the "real priority".  I think it is clear 
that protocols may do all sorts of stuff with the current priority of a 
thread.  Its not possible to change parameters of the worker threads by 
API calls.

>
>> +a different priority.
>> + at item @code{@@<scheduler-name>} is the scheduler instance name according to the
>> +RTEMS application configuration.
>> + at end itemize
>> +
>> +In case no thread pool configuration is specified for a scheduler instance,
>> +then each OpenMP master thread of this scheduler instance will use its own
>> +dynamically allocated thread pool.  To limit the worker thread count of the
>> +thread pools, each OpenMP master thread must call @code{omp_set_num_threads}.
>> +
>> +Lets suppose we have three scheduler instances @code{IO}, @code{WRK0}, and
>> + at code{WRK1} with @env{GOMP_RTEMS_THREAD_POOLS} set to
>> + at code{"1@@WRK0:3$4@@WRK1"}.  Then there are no thread pool restrictions for
>> +scheduler instance @code{IO}.  In the scheduler instance @code{WRK0} there is
>> +one thread pool available.  Since no priority is specified for this scheduler
>> +instance, the worker thread inherits the priority of the OpenMP master thread
>> +that created it.  In the scheduler instance @code{WRK1} there are three thread
>> +pools available and their worker threads run at priority four.
>> +
>>   @subsection Thread Dispatch Details
>>
>>   This section gives background information to developers interested in the
>> --
>> 1.8.4.5
>>
>> _______________________________________________
>> devel mailing list
>> devel at rtems.org
>> http://lists.rtems.org/mailman/listinfo/devel

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.