Purpose of rtems_device_driver?

[Peter Dufault]

> 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 --------------
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/2e9b7f69/attachment.bin>