Phrases for CONSTRAINTS section in the directive documentation

[Gedare Bloom]

On Wed, Jan 27, 2021 at 1:14 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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.
>
> Also fine, it does allow consistency with the second form, if needed.


> 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?)
>
> I don't quite understand this context. I guess it is "all other contexts"?
or a combination of "interrupt context or task context or initialization
context"?

Mechanically, it might be better to enumerate all the contexts in which a
directive may be called?
This directive may be called from within task context.
This directive may be called from within interrupt context.
This directive must not be called from within termination context.

That might be verbose, but it would be very clear.


> 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)
>

maybe, "initialization context" is ok?


>
> 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)
>

"termination context" would seem ok to me also, I guess it can be reached
without necessarily a fatal error? or not?


>
> 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.
>
> I think it is helpful to be precise about context when it matters. I don't
think 2 implies 3 and 3 implies 4 makes sense. Interrupt context is a
separate context to


> 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().
>
>
Countering my own argument above, we could also simplify by using some
implicit rules that are made clear, such as "unless otherwise specified,
all API calls can be made from task context" or even just enumerate the
contexts from which an API directive can not be called, if that is somehow
simpler?

Sorry, I'm not sure what is best to do. This will be a great contribution
to the API documentation though.


> --
> 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/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210127/4096c09c/attachment.html>