michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: device: follow coding guidelines

Browse source 
Do not reuse tag name (misra rule 5.7).

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2021-03-22 10:02:01 -04:00
commit a86505b450
2 changed files with 35 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -126,28 +126,28 @@ A subsystem API definition typically looks like this:
.. code-block:: C .. code-block:: C
typedef int (*subsystem_do_this_t)(const struct device *device, int foo, int bar); typedef int (*subsystem_do_this_t)(const struct device *dev, int foo, int bar);
typedef void (*subsystem_do_that_t)(const struct device *device, void *baz); typedef void (*subsystem_do_that_t)(const struct device *dev, void *baz);
struct subsystem_api { struct subsystem_api {
subsystem_do_this_t do_this; subsystem_do_this_t do_this;
subsystem_do_that_t do_that; subsystem_do_that_t do_that;
}; };
static inline int subsystem_do_this(const struct device *device, int foo, int bar) static inline int subsystem_do_this(const struct device *dev, int foo, int bar)
{ {
struct subsystem_api *api; struct subsystem_api *api;
api = (struct subsystem_api *)device->api; api = (struct subsystem_api *)dev->api;
return api->do_this(device, foo, bar); return api->do_this(dev, foo, bar);
} }
static inline void subsystem_do_that(const struct device *device, void *baz) static inline void subsystem_do_that(const struct device *dev, void *baz)
{ {
struct subsystem_api *api; struct subsystem_api *api;
api = (struct subsystem_api *)device->api; api = (struct subsystem_api *)dev->api;
api->do_that(device, foo, bar); api->do_that(dev, foo, bar);
} }
A driver implementing a particular subsystem will define the real implementation A driver implementing a particular subsystem will define the real implementation
@ -155,12 +155,12 @@ of these APIs, and populate an instance of subsystem_api structure:
.. code-block:: C .. code-block:: C
static int my_driver_do_this(const struct device *device, int foo, int bar) static int my_driver_do_this(const struct device *dev, int foo, int bar)
{ {
... ...
} }
static void my_driver_do_that(const struct device *device, void *baz) static void my_driver_do_that(const struct device *dev, void *baz)
{ {
... ...
} }
@ -197,10 +197,10 @@ A device-specific API definition typically looks like this:
#include <drivers/subsystem.h> #include <drivers/subsystem.h>
/* When extensions need not be invoked from user mode threads */ /* When extensions need not be invoked from user mode threads */
int specific_do_that(const struct device *device, int foo); int specific_do_that(const struct device *dev, int foo);
/* When extensions must be invokable from user mode threads */ /* When extensions must be invokable from user mode threads */
__syscall int specific_from_user(const struct device *device, int bar); __syscall int specific_from_user(const struct device *dev, int bar);
/* Only needed when extensions include syscalls */ /* Only needed when extensions include syscalls */
#include <syscalls/specific.h> #include <syscalls/specific.h>
@ -210,7 +210,7 @@ implementation of both the subsystem API and the specific APIs:
.. code-block:: C .. code-block:: C
static int generic_do_this(const struct device *device, void *arg) static int generic_do_this(const struct device *dev, void *arg)
{ {
... ...
} }
@ -222,13 +222,13 @@ implementation of both the subsystem API and the specific APIs:
}; };
/* supervisor-only API is globally visible */ /* supervisor-only API is globally visible */
int specific_do_that(const struct device *device, int foo) int specific_do_that(const struct device *dev, int foo)
{ {
... ...
} }
/* syscall API passes through a translation */ /* syscall API passes through a translation */
int z_impl_specific_from_user(const struct device *device, int bar) int z_impl_specific_from_user(const struct device *dev, int bar)
{ {
... ...
} }
@ -237,10 +237,10 @@ implementation of both the subsystem API and the specific APIs:
#include <syscall_handler.h> #include <syscall_handler.h>
int z_vrfy_specific_from_user(const struct device *device, int bar) int z_vrfy_specific_from_user(const struct device *dev, int bar)
{ {
Z_OOPS(Z_SYSCALL_SPECIFIC_DRIVER(dev, K_OBJ_DRIVER_GENERIC, &api)); Z_OOPS(Z_SYSCALL_SPECIFIC_DRIVER(dev, K_OBJ_DRIVER_GENERIC, &api));
return z_impl_specific_do_that(device, bar) return z_impl_specific_do_that(dev, bar)
} }
#include <syscalls/specific_from_user_mrsh.c> #include <syscalls/specific_from_user_mrsh.c>
@ -273,7 +273,7 @@ with a different interrupt line. In ``drivers/subsystem/subsystem_my_driver.h``:
.. code-block:: C .. code-block:: C
typedef void (*my_driver_config_irq_t)(const struct device *device); typedef void (*my_driver_config_irq_t)(const struct device *dev);
struct my_driver_config { struct my_driver_config {
DEVICE_MMIO_ROM; DEVICE_MMIO_ROM;
@ -284,22 +284,22 @@ In the implementation of the common init function:
.. code-block:: C .. code-block:: C
void my_driver_isr(const struct device *device) void my_driver_isr(const struct device *dev)
{ {
/* Handle interrupt */ /* Handle interrupt */
... ...
} }
int my_driver_init(const struct device *device) int my_driver_init(const struct device *dev)
{ {
const struct my_driver_config *config = device->config; const struct my_driver_config *config = dev->config;
DEVICE_MMIO_MAP(device, K_MEM_CACHE_NONE); DEVICE_MMIO_MAP(dev, K_MEM_CACHE_NONE);
/* Do other initialization stuff */ /* Do other initialization stuff */
... ...
config->config_func(device); config->config_func(dev);
return 0; return 0;
} }
@ -463,18 +463,18 @@ is made within the init function:
... ...
} }
int my_driver_init(const struct device *device) int my_driver_init(const struct device *dev)
{ {
... ...
DEVICE_MMIO_MAP(device, K_MEM_CACHE_NONE); DEVICE_MMIO_MAP(dev, K_MEM_CACHE_NONE);
... ...
} }
int my_driver_some_function(const struct device *device) int my_driver_some_function(const struct device *dev)
{ {
... ...
/* Write some data to the MMIO region */ /* Write some data to the MMIO region */
sys_write32(DEVICE_MMIO_GET(device), 0xDEADBEEF); sys_write32(DEVICE_MMIO_GET(dev), 0xDEADBEEF);
... ...
} }
@ -524,20 +524,20 @@ For example:
... ...
} }
int my_driver_init(const struct device *device) int my_driver_init(const struct device *dev)
{ {
... ...
DEVICE_MMIO_NAMED_MAP(device, courge, K_MEM_CACHE_NONE); DEVICE_MMIO_NAMED_MAP(dev, courge, K_MEM_CACHE_NONE);
DEVICE_MMIO_NAMED_MAP(device, grault, K_MEM_CACHE_NONE); DEVICE_MMIO_NAMED_MAP(dev, grault, K_MEM_CACHE_NONE);
... ...
} }
int my_driver_some_function(const struct device *device) int my_driver_some_function(const struct device *dev)
{ {
... ...
/* Write some data to the MMIO regions */ /* Write some data to the MMIO regions */
sys_write32(DEVICE_MMIO_GET(device, grault), 0xDEADBEEF); sys_write32(DEVICE_MMIO_GET(dev, grault), 0xDEADBEEF);
sys_write32(DEVICE_MMIO_GET(device, courge), 0xF0CCAC1A); sys_write32(DEVICE_MMIO_GET(dev, courge), 0xF0CCAC1A);
... ...
} }

4
doc/reference/power_management/index.rst
View file

@ -307,7 +307,7 @@ Device Set Power State
.. code-block:: c .. code-block:: c
int device_set_power_state(const struct device *device, uint32_t device_power_state, device_pm_cb cb, void *arg); int device_set_power_state(const struct device *dev, uint32_t device_power_state, device_pm_cb cb, void *arg);
Calls the :c:func:`device_pm_control()` handler function implemented by the Calls the :c:func:`device_pm_control()` handler function implemented by the
device driver with DEVICE_PM_SET_POWER_STATE command. device driver with DEVICE_PM_SET_POWER_STATE command.
@ -317,7 +317,7 @@ Device Get Power State
.. code-block:: c .. code-block:: c
int device_get_power_state(const struct device *device, uint32_t * device_power_state); int device_get_power_state(const struct device *dev, uint32_t * device_power_state);
Calls the :c:func:`device_pm_control()` handler function implemented by the Calls the :c:func:`device_pm_control()` handler function implemented by the
device driver with DEVICE_PM_GET_POWER_STATE command. device driver with DEVICE_PM_GET_POWER_STATE command.