> On Sep 29, 2020, at 10:13 , Joel Sherrill <j...@rtems.org> wrote: > > > > On Tue, Sep 29, 2020 at 8:54 AM Sebastian Huber > <sebastian.hu...@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.hu...@embedded-brains.de > >> <mailto:sebastian.hu...@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.
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
