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

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 zephyrproject-rtos#17072
and approved by the Technical Steering Committee during its 2019-08-07
meeting.

Relates-to: zephyrproject-rtos#11993
Signed-off-by: Peter A. Bigot <pab@pabigot.com>

doc/reference/drivers/index.rst

@@ -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
 *********************************