Purpose of rtems_device_driver?

[dufault at hda.com]

I wasn't thinking about user code, I was thinking about the RTEMS source code and that the construct should go away. The typedef should be gotten rid of in a way that supports user code for a release or so.

> On Sep 29, 2020, at 15:34 , Joel Sherrill <joel at rtems.org> wrote:
> 
> 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.
> 

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 --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 235 bytes
Desc: Message signed with OpenPGP
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200929/f292fcaa/attachment-0001.bin>