[PATCH v2] rtems: Add rtems_task_create_from_config()

Joel Sherrill joel at rtems.org
Tue Sep 8 22:25:44 UTC 2020

  This has gotten to be a long-ish side discussion. I havecomments on the
patch and will reply to the original email for that.

On Thu, Sep 3, 2020 at 10:17 PM Chris Johns <chrisj at rtems.org> wrote:

> On 3/9/20 10:08 pm, Sebastian Huber wrote:
> >
> > On 03/09/2020 04:08, Chris Johns wrote:
> >> On 3/9/20 2:09 am, Sebastian Huber wrote:
> >>> In contrast to rtems_task_create() this function creates a task with a
> >>> user-provided task storage area.  The new create function uses a
> >>> configuration structure instead of individual parameters.
> >>>
> >>> Add RTEMS_TASK_STORAGE_ALIGNMENT to define the recommended alignment of
> >>> a task storage area.
> >>>
> >>> Add RTEMS_TASK_STORAGE_SIZE() to calculate the recommended size of a
> >>> task storage area based on the task attributes and the size dedicated
> to
> >>> the task stack and thread-local storage.  This macro may allow future
> >>> extensions without breaking the API.
> >> Have all the issues in the other thread been resolved? It would be good
> to have
> >> Joel ack this patch before it is merged.
> > I tried to address the issues raised by Joel.
> He will need to answer.

I will also comment on the patch. But the first thing I noticed was how
does the user
know the amount of memory required for keys? That was in a Doxygen comment
about the macro which is a big improvement but still makes the user guess
something we should compute.

This reminds me of not giving an option to account for message buffers. Then
we added a confdefs macro to specify the total amount of memory. It took
release before we realized that we didn't give the user a way to calculate
memory required per queue based on number of messages and size of the
buffer. This made them guess to account for the overhead for each of those.
Let's try to avoid making users guess the size of memory that we would

> >> In considering the support for static allocation in general I am
> wondering if
> >> the RTEMS Classic API Guide is poorly named? This is a new API with new
> features
> >> and it is not "classic". The Key Concepts section of the that manual
> says...
> >>
> >>   "RTEMS provides directives which can be used to dynamically
> >>    create, delete, and manipulate a set of predefined object types."
> >>
> >> This change makes this statement questionable.
> >
> > The task is still dynamically created, however, with a user-provided task
> > storage area. It is similar to the POSIX threads which also have to
> option to
> > use a user-provided task storage area. When you don't use unlimited
> objects,
> > then the memory for task control blocks is only statically allocated.
> The tasks
> > are dynamically maintained.
> Thanks. This makes sense and almost what could be used in the
> documentation :)

We just need to make sure we name the various situations clearly without
like new/old, improved, etc.

I see a handful of RTOS memory organizations a systems designer has to pick
and we have to name and explain them.

(1) Workspace vs C Program Heap
    - usually associated with hard limits on objects. Unlimited is of
      use with the split memory model.

(2) Unified Workspace/Heap
   - usually associated with unlimited objects

On top of that, you have

    (a) stack and FP allocated from Workspace
    (b)  BSP/application provided stack allocator
    (c) Application provided memory per task

That makes six combinations. I would tend to say that if you choose to
use Unified Workspace, then 2a makes sense. 2b also makes sense if
you had some stack protection scheme. But why would someone mix in
2c. Should work but not likely to be a common setup unless we do it
in support code.

For (1), I can see situations where you would use 1a, 1b, and 1c.

Overall, I see a-c as useful with 1+2 and a-c should work with 1 or 2
but we have to explain the choices.

I think this means we need to name a-c so we use consistent
terms across the community.

> > The self-contained synchronization objects of this chapter
> >
> >
> https://docs.rtems.org/branches/master/c-user/self_contained_objects.html
> >
> > are a different kind of thing.
> Yes and this makes the word Classic look wrong.

Classic is probably technically only the core APIs that derived from
or soon thereafter. Perhaps only the managers that existed before any POSIX
added which would be strictly less than v4.x of RTEMS.

But now, Classic is just RTEMS specific APIs that start with rtems_ even
though that
leads to duplicate functionality between Classic proper and the self
contained objects.

I think this is just a matter of naming chapters correctly and ensuring
that the
first 2 sentences of each self-contained object type's description makes it
the distinction.

> >> I am sure there are other places
> >> that will need to be updated. What documentation and examples are
> planned to
> >> explain the different allocation models RTEMS now supports? I think we
> have 3
> >> APIs and the "Classic" API now has 2 allocation models. I fine with the
> >> expansion of the ways RTEMS can be used but we need to make sure we
> explain
> >> these differing ways, why they exist, and the advantages and
> disadvantages. I
> >> would prefer we not leave this as an exercise for the users to do by
> reading
> >> header files.
> >
> > Yes, we need some guidance for the users. I will definitely work on
> > documentation updates. I would like to work first on the specification
> of the
> > Classic API directives:
> >
> > https://devel.rtems.org/ticket/3993
> >
> > This involves a unification/consolidation of the Doxgyen and Sphinx
> documentation.


FWIW I also think the rationale for picking a scheduling algorithm is a
and similar in that we have multiple options for a very high level systems
design decision.  Questions like OS memory allocation scheme, scheduler
selection, and API selection need to be addressed somewhere. The first two
fit into the Classic API Guide (which used to be the Users Guide so could be
renamed again). But selecting an API is a bit different in that you are
down a design level when in this manual.

> > Afterwards I would like to concentrate more on higher level aspects
> which cover
> > more than one directive.
> >
> Excellent and thanks. The question is about the plan not the timeline.


I'm not opposed in principle. I am just leary of adding anything that does
not present a clear definition to the user and has a well-defined purpose.
You added some concepts that need to be accounted for as design
variations and the APIs need to be solid.


> Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200908/dccfc846/attachment.html>

More information about the devel mailing list