michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Update device driver documentation on driver_* attributes rename

Browse source 
s/driver_data/data
s/driver_api/api

Fixes #27397

Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
This commit is contained in:
Tomasz Bursztyka 2020-05-28 21:00:44 +02:00 • committed by Carles Cufí
commit d86f79cbd7
1 changed files with 11 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -105,8 +105,8 @@ split into read-only and runtime-mutable parts. At a high level we have:
struct device { struct device {
const char *name; const char *name;
const void *config; const void *config;
const void *driver_api; const void *api;
void * const driver_data; void * const data;
}; };
The ``config`` member is for read-only configuration data set at build time. For The ``config`` member is for read-only configuration data set at build time. For
@ -114,11 +114,11 @@ example, base memory mapped IO addresses, IRQ line numbers, or other fixed
physical characteristics of the device. This is the ``config`` pointer physical characteristics of the device. This is the ``config`` pointer
passed to ``DEVICE_DEFINE()`` and related macros. passed to ``DEVICE_DEFINE()`` and related macros.
The ``driver_data`` struct is kept in RAM, and is used by the driver for The ``data`` struct is kept in RAM, and is used by the driver for
per-instance runtime housekeeping. For example, it may contain reference counts, per-instance runtime housekeeping. For example, it may contain reference counts,
semaphores, scratch buffers, etc. semaphores, scratch buffers, etc.
The ``driver_api`` struct maps generic subsystem APIs to the device-specific The ``api`` struct maps generic subsystem APIs to the device-specific
implementations in the driver. It is typically read-only and populated at implementations in the driver. It is typically read-only and populated at
build time. The next section describes this in more detail. build time. The next section describes this in more detail.
@ -146,7 +146,7 @@ A subsystem API definition typically looks like this:
{ {
struct subsystem_api *api; struct subsystem_api *api;
api = (struct subsystem_api *)device->driver_api; api = (struct subsystem_api *)device->api;
return api->do_this(device, foo, bar); return api->do_this(device, foo, bar);
} }
@ -154,7 +154,7 @@ A subsystem API definition typically looks like this:
{ {
struct subsystem_api *api; struct subsystem_api *api;
api = (struct subsystem_api *)device->driver_api; api = (struct subsystem_api *)device->api;
api->do_that(device, foo, bar); api->do_that(device, foo, bar);
} }
@ -183,7 +183,7 @@ The driver would then pass ``my_driver_api_funcs`` as the ``api`` argument to
.. note:: .. note::
Since pointers to the API functions are referenced in the ``driver_api`` Since pointers to the API functions are referenced in the ``api``
struct, they will always be included in the binary even if unused; struct, they will always be included in the binary even if unused;
``gc-sections`` linker option will always see at least one reference to ``gc-sections`` linker option will always see at least one reference to
them. Providing for link-time size optimizations with driver APIs in them. Providing for link-time size optimizations with driver APIs in
@ -269,7 +269,7 @@ Single Driver, Multiple Instances
Some drivers may be instantiated multiple times in a given system. For example Some drivers may be instantiated multiple times in a given system. For example
there can be multiple GPIO banks, or multiple UARTS. Each instance of the driver there can be multiple GPIO banks, or multiple UARTS. Each instance of the driver
will have a different ``config`` struct and ``driver_data`` struct. will have a different ``config`` struct and ``data`` struct.
Configuring interrupts for multiple drivers instances is a special case. If each Configuring interrupts for multiple drivers instances is a special case. If each
instance needs to configure a different interrupt line, this can be accomplished instance needs to configure a different interrupt line, this can be accomplished
@ -331,11 +331,11 @@ Then when the particular instance is declared:
.config_func = my_driver_config_irq_0 .config_func = my_driver_config_irq_0
} }
static struct my_driver_data_0; static struct my_data_0;
DEVICE_AND_API_INIT(my_driver_0, MY_DRIVER_0_NAME, my_driver_init, DEVICE_AND_API_INIT(my_driver_0, MY_DRIVER_0_NAME, my_driver_init,
&my_driver_data_0, &my_driver_config_0, POST_KERNEL, &my_data_0, &my_driver_config_0, POST_KERNEL,
MY_DRIVER_0_PRIORITY, &my_driver_api_funcs); MY_DRIVER_0_PRIORITY, &my_api_funcs);
#endif /* CONFIG_MY_DRIVER_0 */ #endif /* CONFIG_MY_DRIVER_0 */