Purpose of rtems_device_driver?

[Joel Sherrill]

I'm not disagreeing with you at all Peter. This is definitely history and a
"grep -r _routine | grep typedef" will show a few other cases where this
pattern still exists. In at least one, it is internal and deprecated.

You are right. This is from the earliest days of RTEMS. I looked in the
scanned RTEID and ORKID documents and can't fine the IO manager. I swear it
came from there but I did find a pSOS+ manual online and their interface
was so bare, it did not use any typedef at all. It even mentioned CPU
architecture specific differences. <shudder>

If we want to deprecate it, I'm ok with that. But we should put all of
these kind of typedefs. on the way to the dustbin.

It is definitely used enough where eliminating it will take scripting.

 grep -r "rtems_device_driver " . 2>/dev/null | wc -l
710

That doesn't count timer_service_routine, the one for signals, etc.

I'm not opposed and now is the time if there is consensus. I have reached
the point where I acknowledge the long history and mostly am concerned
about how changes impact user code more than the idea of change itself.

--joel

On Tue, Sep 29, 2020 at 1:01 PM Peter Dufault <dufault at hda.com> wrote:

>
>
> > On Sep 29, 2020, at 10:13 , Joel Sherrill <joel at rtems.org> wrote:
> >
> >
> >
> > On Tue, Sep 29, 2020 at 8:54 AM Sebastian Huber <
> sebastian.huber at embedded-brains.de> wrote:
> > On 29/09/2020 15:47, Sebastian Huber wrote:
> >
> > > On 29/09/2020 15:42, Joel Sherrill wrote:
> > >
> > >>
> > >>
> > >> On Tue, Sep 29, 2020 at 8:37 AM Sebastian Huber
> > >> <sebastian.huber at embedded-brains.de
> > >> <mailto:sebastian.huber at embedded-brains.de>> wrote:
> > >>
> > >>     Hello,
> > >>
> > >>     I work currently on the documentation of the IO Manager. What is
> the
> > >>     purpose of
> > >>
> > >>     typedef rtems_status_code rtems_device_driver;
> > >>
> > >>     ?
> > >>
> > >>     For me this looks a bit like camouflage.
> > >>
> > >>
> > >> No. It is a use of typedef to make the purpose of the method clear.
> > >>
> > >> You have nibbled at these for years. There were at least types for
> > >> Classic Tasks, ASRs, and TSRs at one point.
> > > Yes, the typedefs to void.
> > >>
> > >> If this is the last one, I'm not going to fight it. This isn't the
> > >> hill I am
> > >> going to die on.
> > > I am not suggesting to remove them although I find these typedefs
> > > pretty odd. I just look for some documentation text.
> >
> > What about this:
> >
> > /**
> >   * @ingroup RTEMSAPIClassicIO
> >   *
> >   * @brief This type shall be used in device driver entry declarations
> and
> >   *   definitions.
> >   *
> >   * Device driver entries return an #rtems_status_code status code. This
> > type
> >   * definition helps to document device driver entries in the source
> code.
> >   */
> > typedef rtems_status_code rtems_device_driver;
> >
> > That's more than sufficient.
> >
> > Thanks.
>
> This typedef is odd.  Unless I'm missing a fine-point.
>
> If the typedef is, and always will remain, "rtems_status_code" I would not
> use a typedef.
>
> The RTEMS API documentation is moving to Doxygen (and more formally than
> that given Sebastian's ESA work). Using a typedef to indicate a function is
> part of a device driver as "documentation" is not a good idea.
>
> When I've thought I needed a special return code in the past I've made the
> return code a "struct" so that it can't be used interchangeably with other
> return codes, even with casting, and so that you need to be *sure* you
> really want such a special return type. This probably pre-dates enabling
> aggressive warnings.
>
> I haven't done this recently.  Recently I've assumed that:
> - Status codes are an integral type;
> - Status codes of 0 always mean success.
>
> Trying to pretend you need to compare a return to a special "success"
> #define that is 0 is pointless and error prone now-a-days IMHO.
>
> If I really wanted a return code that was special I'd do something like:
>
> typedef struct {
>   rtems_status_code status; /* Error return. */
>   int unused;               /* Unused */
> } rtems_device_driver;
>
> Peter
> -----------------
> Peter Dufault
> HD Associates, Inc.      Software and System Engineering
>
> This email is delivered through the public internet using protocols
> subject to interception and tampering.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200929/395d17af/attachment.html>