michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Apply constant qualifier on device instance where relevant

Browse source 
s/struct device */const struct device *

Fixes #27399

Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
This commit is contained in:
Tomasz Bursztyka 2020-08-18 09:22:14 +02:00 • committed by Carles Cufí
commit c0bcfd2a77
7 changed files with 37 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/guides/design_guidelines.rst
View file

@ -53,7 +53,7 @@ Examples
* The requirements of :c:type:`counter_alarm_callback_t` invoked when a
counter device alarm fires are satisfied by::
void handle_alarm(struct device *dev,
void handle_alarm(const struct device *dev,
uint8_t chan_id,
uint32_t ticks,
void *user_data)

4
doc/guides/dts/howtos.rst
View file

@ -375,8 +375,8 @@ device-specific configuration and data structures and API functions, like this:
};
/* Implement driver API functions (drivers/some_api.h callbacks): */
static int my_driver_api_func1(struct device *dev, uint32_t *foo) { /* ... */ }
static int my_driver_api_func2(struct device *dev, uint64_t bar) { /* ... */ }
static int my_driver_api_func1(const struct device *dev, uint32_t *foo) { /* ... */ }
static int my_driver_api_func2(const struct device *dev, uint64_t bar) { /* ... */ }
static struct some_api my_api_funcs = {
.func1 = my_driver_api_func1,
.func2 = my_driver_api_func2,

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

@ -134,15 +134,15 @@ A subsystem API definition typically looks like this:
.. code-block:: C
typedef int (*subsystem_do_this_t)(struct device *device, int foo, int bar);
typedef void (*subsystem_do_that_t)(struct device *device, void *baz);
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);
struct subsystem_api {
subsystem_do_this_t do_this;
subsystem_do_that_t do_that;
};
static inline int subsystem_do_this(struct device *device, int foo, int bar)
static inline int subsystem_do_this(const struct device *device, int foo, int bar)
{
struct subsystem_api *api;
@ -150,7 +150,7 @@ A subsystem API definition typically looks like this:
return api->do_this(device, foo, bar);
}
static inline void subsystem_do_that(struct device *device, void *baz)
static inline void subsystem_do_that(const struct device *device, void *baz)
{
struct subsystem_api *api;
@ -163,12 +163,12 @@ of these APIs, and populate an instance of subsystem_api structure:
.. code-block:: C
static int my_driver_do_this(struct device *device, int foo, int bar)
static int my_driver_do_this(const struct device *device, int foo, int bar)
{
...
}
static void my_driver_do_that(struct device *device, void *baz)
static void my_driver_do_that(const struct device *device, void *baz)
{
...
}
@ -205,10 +205,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(struct device *device, int foo);
int specific_do_that(const struct device *device, int foo);
/* When extensions must be invokable from user mode threads */
__syscall int specific_from_user(struct device *device, int bar);
__syscall int specific_from_user(const struct device *device, int bar);
/* Only needed when extensions include syscalls */
#include <syscalls/specific.h>
@ -218,7 +218,7 @@ implementation of both the subsystem API and the specific APIs:
.. code-block:: C
static int generic_do_this(struct device *device, void *arg)
static int generic_do_this(const struct device *device, void *arg)
{
...
}
@ -230,13 +230,13 @@ implementation of both the subsystem API and the specific APIs:
};
/* supervisor-only API is globally visible */
int specific_do_that(struct device *device, int foo)
int specific_do_that(const struct device *device, int foo)
{
...
}
/* syscall API passes through a translation */
int z_impl_specific_from_user(struct device *device, int bar)
int z_impl_specific_from_user(const struct device *device, int bar)
{
...
}
@ -245,7 +245,7 @@ implementation of both the subsystem API and the specific APIs:
#include <syscall_handler.h>
int z_vrfy_specific_from_user(struct device *device, int bar)
int z_vrfy_specific_from_user(const struct device *device, int bar)
{
Z_OOPS(Z_SYSCALL_SPECIFIC_DRIVER(dev, K_OBJ_DRIVER_GENERIC, &api));
return z_impl_specific_do_that(device, bar)
@ -281,7 +281,7 @@ with a different interrupt line. In ``drivers/subsystem/subsystem_my_driver.h``:
.. code-block:: C
typedef void (*my_driver_config_irq_t)(struct device *device);
typedef void (*my_driver_config_irq_t)(const struct device *device);
struct my_driver_config {
DEVICE_MMIO_ROM;
@ -292,13 +292,13 @@ In the implementation of the common init function:
.. code-block:: C
void my_driver_isr(struct device *device)
void my_driver_isr(const struct device *device)
{
/* Handle interrupt */
...
}
int my_driver_init(struct device *device)
int my_driver_init(const struct device *device)
{
const struct my_driver_config *config = device->config;
@ -471,14 +471,14 @@ is made within the init function:
...
}
int my_driver_init(struct device *device)
int my_driver_init(const struct device *device)
{
...
DEVICE_MMIO_MAP(device, K_MEM_CACHE_NONE);
...
}
int my_driver_some_function(struct device *device)
int my_driver_some_function(const struct device *device)
{
...
/* Write some data to the MMIO region */
@ -532,7 +532,7 @@ For example:
...
}
int my_driver_init(struct device *device)
int my_driver_init(const struct device *device)
{
...
DEVICE_MMIO_NAMED_MAP(device, courge, K_MEM_CACHE_NONE);
@ -540,7 +540,7 @@ For example:
...
}
int my_driver_some_function(struct device *device)
int my_driver_some_function(const struct device *device)
{
...
/* Write some data to the MMIO regions */

2
doc/reference/networking/8021Qav.rst
View file

@ -23,7 +23,7 @@ also priority queues ``ETHERNET_PRIORITY_QUEUES`` need to be supported.
.. code-block:: none
static enum ethernet_hw_caps eth_get_capabilities(struct device *dev)
static enum ethernet_hw_caps eth_get_capabilities(const struct device *dev)
{
ARG_UNUSED(dev);

2
doc/reference/networking/can_api.rst
View file

@ -178,7 +178,7 @@ occurred. It does not block until the message is sent like the example above.
}
}
int send_function(struct device *can_dev)
int send_function(const struct device *can_dev)
{
struct zcan_frame frame = {
.id_type = CAN_EXTENDED_IDENTIFIER,

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

@ -279,7 +279,7 @@ Default Initializer Function
.. code-block:: c
int device_pm_control_nop(struct device *unused_device, uint32_t unused_ctrl_command, void *unused_context);
int device_pm_control_nop(const struct device *unused_device, uint32_t unused_ctrl_command, void *unused_context);
If the driver doesn't implement any power control operations, the driver can
@ -315,7 +315,7 @@ Device Set Power State
.. code-block:: c
int device_set_power_state(struct device *device, uint32_t device_power_state, device_pm_cb cb, void *arg);
int device_set_power_state(const struct device *device, 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.
@ -325,7 +325,7 @@ Device Get Power State
.. code-block:: c
int device_get_power_state(struct device *device, uint32_t * device_power_state);
int device_get_power_state(const struct device *device, 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.
@ -364,7 +364,7 @@ Indicate Busy Status API
.. code-block:: c
void device_busy_set(struct device *busy_dev);
void device_busy_set(const struct device *busy_dev);
Sets a bit corresponding to the device, in a data structure maintained by the
kernel, to indicate whether or not it is in the middle of a transaction.
@ -374,7 +374,7 @@ Clear Busy Status API
.. code-block:: c
void device_busy_clear(struct device *busy_dev);
void device_busy_clear(const struct device *busy_dev);
Clears the bit corresponding to the device in a data structure
maintained by the kernel to indicate that the device is not in the middle of
@ -385,7 +385,7 @@ Check Busy Status of Single Device API
.. code-block:: c
int device_busy_check(struct device *chk_dev);
int device_busy_check(const struct device *chk_dev);
Checks whether a device is busy. The API returns 0 if the device
is not busy.
@ -425,7 +425,7 @@ Enable Device Idle Power Management of a Device API
.. code-block:: c
void device_pm_enable(struct device *dev);
void device_pm_enable(const struct device *dev);
Enbles Idle Power Management of the device.
@ -434,7 +434,7 @@ Disable Device Idle Power Management of a Device API
.. code-block:: c
void device_pm_disable(struct device *dev);
void device_pm_disable(const struct device *dev);
Disables Idle Power Management of the device.
@ -443,7 +443,7 @@ Resume Device asynchronously API
.. code-block:: c
int device_pm_get(struct device *dev);
int device_pm_get(const struct device *dev);
Marks the device as being used. This API will asynchronously
bring the device to resume state. The API returns 0 on success.
@ -453,7 +453,7 @@ Resume Device synchronously API
.. code-block:: c
int device_pm_get_sync(struct device *dev);
int device_pm_get_sync(const struct device *dev);
Marks the device as being used. It will bring up or resume
the device if it is in suspended state based on the device
@ -465,7 +465,7 @@ Suspend Device asynchronously API
.. code-block:: c
int device_pm_put(struct device *dev);
int device_pm_put(const struct device *dev);
Marks the device as being released. This API asynchronously put
the device to suspend state if not already in suspend state.
@ -476,7 +476,7 @@ Suspend Device synchronously API
.. code-block:: c
int device_pm_put_sync(struct device *dev);
int device_pm_put_sync(const struct device *dev);
Marks the device as being released. It will put the device to
suspended state if is is in active state based on the device

2
doc/reference/usermode/kernelobjects.rst
View file

@ -8,7 +8,7 @@ A kernel object can be one of three classes of data:
* A core kernel object, such as a semaphore, thread, pipe, etc.
* A thread stack, which is an array of :c:struct:`z_thread_stack_element`
and declared with :c:macro:`K_THREAD_STACK_DEFINE()`
* A device driver instance (struct device) that belongs to one of a defined
* A device driver instance (const struct device) that belongs to one of a defined
set of subsystems
The set of known kernel objects and driver subsystems is defined in