From c0bcfd2a7764e00ebe1570cf553da82d4d3a4ad6 Mon Sep 17 00:00:00 2001 From: Tomasz Bursztyka Date: Tue, 18 Aug 2020 09:22:14 +0200 Subject: [PATCH] doc: Apply constant qualifier on device instance where relevant s/struct device */const struct device * Fixes #27399 Signed-off-by: Tomasz Bursztyka --- doc/guides/design_guidelines.rst | 2 +- doc/guides/dts/howtos.rst | 4 +-- doc/reference/drivers/index.rst | 38 ++++++++++++------------ doc/reference/networking/8021Qav.rst | 2 +- doc/reference/networking/can_api.rst | 2 +- doc/reference/power_management/index.rst | 24 +++++++-------- doc/reference/usermode/kernelobjects.rst | 2 +- 7 files changed, 37 insertions(+), 37 deletions(-) diff --git a/doc/guides/design_guidelines.rst b/doc/guides/design_guidelines.rst index 6192d4357ca..42413b48269 100644 --- a/doc/guides/design_guidelines.rst +++ b/doc/guides/design_guidelines.rst @@ -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) diff --git a/doc/guides/dts/howtos.rst b/doc/guides/dts/howtos.rst index 104724bbfe6..9fb357af061 100644 --- a/doc/guides/dts/howtos.rst +++ b/doc/guides/dts/howtos.rst @@ -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, diff --git a/doc/reference/drivers/index.rst b/doc/reference/drivers/index.rst index 2cd31e680e4..20f03c44dd6 100644 --- a/doc/reference/drivers/index.rst +++ b/doc/reference/drivers/index.rst @@ -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 /* 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 @@ -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 - 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 */ diff --git a/doc/reference/networking/8021Qav.rst b/doc/reference/networking/8021Qav.rst index c943b6cda26..d5a80999e75 100644 --- a/doc/reference/networking/8021Qav.rst +++ b/doc/reference/networking/8021Qav.rst @@ -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); diff --git a/doc/reference/networking/can_api.rst b/doc/reference/networking/can_api.rst index 11f1aef8a40..30bc458011d 100644 --- a/doc/reference/networking/can_api.rst +++ b/doc/reference/networking/can_api.rst @@ -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, diff --git a/doc/reference/power_management/index.rst b/doc/reference/power_management/index.rst index f43c1558542..705a51a9b65 100644 --- a/doc/reference/power_management/index.rst +++ b/doc/reference/power_management/index.rst @@ -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 diff --git a/doc/reference/usermode/kernelobjects.rst b/doc/reference/usermode/kernelobjects.rst index 9b6ffd69134..eba6331a4f1 100644 --- a/doc/reference/usermode/kernelobjects.rst +++ b/doc/reference/usermode/kernelobjects.rst @@ -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