patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki 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
parent 2976e12946
commit a86505b450
2 changed files with 35 additions and 35 deletions
Show stats 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
typedef int (*subsystem_do_this_t)(const struct device *device, int foo, int bar);
typedef void (*subsystem_do_that_t)(const struct device *device, void *baz);
typedef int (*subsystem_do_this_t)(const struct device *dev, int foo, int bar);
typedef void (*subsystem_do_that_t)(const struct device *dev, void *baz);
struct subsystem_api {
subsystem_do_this_t do_this;
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;
api = (struct subsystem_api *)device->api;
return api->do_this(device, foo, bar);
api = (struct subsystem_api *)dev->api;
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;
api = (struct subsystem_api *)device->api;
api->do_that(device, foo, bar);
api = (struct subsystem_api *)dev->api;
api->do_that(dev, foo, bar);
}
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
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>
/* 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 */
__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 */
#include <syscalls/specific.h>
@ -210,7 +210,7 @@ implementation of both the subsystem API and the specific APIs:
.. 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 */
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 */
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>
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));
return z_impl_specific_do_that(device, bar)
return z_impl_specific_do_that(dev, bar)
}
#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
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 {
DEVICE_MMIO_ROM;
@ -284,22 +284,22 @@ In the implementation of the common init function:
.. code-block:: C
void my_driver_isr(const struct device *device)
void my_driver_isr(const struct device *dev)
{
/* 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 */
...
config->config_func(device);
config->config_func(dev);
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 */
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(device, grault, K_MEM_CACHE_NONE);
DEVICE_MMIO_NAMED_MAP(dev, courge, 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 */
sys_write32(DEVICE_MMIO_GET(device, grault), 0xDEADBEEF);
sys_write32(DEVICE_MMIO_GET(device, courge), 0xF0CCAC1A);
sys_write32(DEVICE_MMIO_GET(dev, grault), 0xDEADBEEF);
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
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
device driver with DEVICE_PM_SET_POWER_STATE command.
@ -317,7 +317,7 @@ Device Get Power State
.. 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
device driver with DEVICE_PM_GET_POWER_STATE command.