patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

doc: simplify docs on driver-specific APIs.

Browse source 
This documentation is well-intentioned but not good advice.

The reason why we have a vtable-like API abstraction at the
driver subsystem level is to introduce object orientation.
The subsystem defintions implement an abstract class that
specific driver implementations all implement, providing
a common interface for end users. Multiple drivers may be
written for a subsystem that are interchangeable to the end
user.

However, there is no point in introducing a vtable-like
abstraction for APIs which are specific to a single driver.
We are not trying to present an interface abstraction which
could support multiple implementations. There is just one.

Simply declare a function in a header, and implement it in
the driver's C file.

Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
This commit is contained in:
Andrew Boie 2020-04-21 12:34:11 -07:00 committed by Anas Nashif
parent 2599f705a8
commit 6627249dc1
1 changed files with 2 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
doc/reference/drivers/index.rst
View file

@ -205,19 +205,7 @@ A device-specific API definition typically looks like this:
#include <drivers/subsystem.h>
typedef int (*specific_do_this_t)(struct device *device, int foo);
struct specific_api {
subsystem_driver_api subsystem_api; /* this must be first */
specific_do_this_t do_this;
};
static inline int specific_do_this(struct device *device, int foo)
{
struct specific_api *api = (struct specific_api*)device->driver_api;
return api->do_this(device, foo);
}
int specific_do_this(struct device *device, int foo);
A driver implementing extensions to the subsystem will define the real
implementation of both the subsystem API and the specific APIs:
@ -234,16 +222,8 @@ implementation of both the subsystem API and the specific APIs:
...
}
static const struct specific_api driver_api = {
.subsystem_api = {
.do_whatever = generic_do_whatever,
},
.do_this = specific_do_this,
};
Applications use the device through both the subsystem and specific
APIs. The subsystem APIs will directly access the subsystem part of the
specific API structure.
APIs.
Single Driver, Multiple Instances
*********************************