[PATCH] smp: Documentation

[Gedare Bloom]

On Fri, Sep 4, 2015 at 2:49 AM, Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
>
> 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.
>
Hopefully the rtems-tools / RSB get to that point.

>>> +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" ?
Yes you're right, all three parts of the compound adjective should be
hyphenated preceding the noun "thread pools".

>
> Maybe use "determines the thread pools for each scheduler instance".
>
Yes, this will look and read better.

>>
>>> + 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.
>
I would add a note about the last part too then, about not being able
to change their parameters directly.

Thanks for the documentation!
Gedare