Phrases for CONSTRAINTS section in the directive documentation

[Sebastian Huber]

On 23/01/2021 23:44, Chris Johns wrote:

> On 23/1/21 12:19 am, Gedare Bloom wrote:
>   On Fri, Jan 22, 2021 at 5:55 AM Andrew Butterfield
>> <Andrew.Butterfield at scss.tcd.ie <mailto:Andrew.Butterfield at scss.tcd.ie>> wrote:
>>
>>      Hi Sebastian,
>>
>>      I'd prefer 2.
>>
>>      The directive may be called from an interrupt context
>>
>>      (substituting  "must",  "must not", as appropriate)
>>
>> Yes, I agree. (Use of "in" is ambiguous here, because "called in" has a meaning
>> in colloquial speech that differs from the intent here.)
>    "The directive may be called from within an interrupt context."
>
> ?
>
> A context is a area, region or bounded "space" (what this means) so I suggest
> "from within"? And this also lets you use "this call cannot be made from outside
> an interrupt context".

The "from within" is fine for me, you are the native speakers.

After reviewing the documentation, I found these contexts relevant to 
the API:

1. constant expressions (for example rtems_build_name(), 
rtems_resource_unlimited())

2. runtime context (for example rtems_clock_get_ticks_per_second(), 
rtems_configuration_get_maximum_barriers(); better name for the context?)

3. interrupt context

4. device driver initialization context (this is just a special case 
during system initialization, in this area we have a lot more 
"contexts", however, I think only this one visible via the API; the 
stack allocator initialization handler is an exception)

5. task context

6. fatal error context (I am not sure about the name, this is more 
generally the system termination context, however, through the API you 
end up here via the fatal error user extension)

I think 1. implies 2., 2. implies 3., 3. implies 4., and 4. implies 5. 
The question is if we want to use this reasoning to compact the 
constraints list for the directives.

Another question is if we want to explicitly mention 5. I think the only 
directive which cannot be called in task context is 
rtems_initialize_executive().

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/