michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc/reference/drivers: document device-specific API extensions

Browse source 
This PR updates the documentation to cover a technical solution to
providing a driver instance that extends the functionality of a
subsystem API.  The solution described was mooted in Zephyr PR #17072
and approved by the Technical Steering Committee during its 2019-08-07
meeting.

Relates-to: #11993
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
This commit is contained in:
Peter A. Bigot 2019-08-01 11:54:31 -05:00 • committed by Ioannis Glaropoulos
commit 24b67ef119
1 changed files with 54 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -180,6 +180,60 @@ in the driver init function.
most cases requires that the optional feature be controlled by a
Kconfig option.
Device-Specific API Extensions
******************************
Some devices can be cast as an instance of a driver subsystem such as GPIO,
but provide additional functionality that cannot be exposed through the
standard API. These devices combine subsystem operations with
device-specific APIs, described in a device-specific header.
A device-specific API definition typically looks like this:
.. code-block:: C
#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);
}
A driver implementing extensions to the subsystem will define the real
implementation of both the subsystem API and the specific APIs:
.. code-block:: C
static int generic_do_whatever(struct device *device, void *arg)
{
...
}
static int specific_do_this(struct device *device, int foo)
{
...
}
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.
Single Driver, Multiple Instances
*********************************