drivers: can: rename API functions for better consistency

Rename a few CAN API functions for clarity and consistency with other
Zephyr RTOS APIs.

CAN_DEFINE_MSGQ() becomes CAN_MSGQ_DEFINE() to match K_MSGQ_DEFINE().

can_attach_isr() becomes can_add_rx_filter() since a filter callback
function is not an interrupt service routine (although it is called in
isr context). The word "attach" is replaced with "add" since filters are
added, not attached. This matches the terminology used is other Zephyr
APIs better.

can_detach() becomes can_remove_rx_filter() to pair with
can_add_rx_filter().

can_attach_msgq() becomes can_add_rx_filter_msgq() and documentation is
updated to mention its relationship with can_add_rx_filter().

can_register_state_change_isr() becomes can_set_state_change_callback()
since a state change callback function is not an interrupt service
routine (although it is called in isr context). The word "register" is
replaced with "set" since only one state change callback can be in
place.

Signed-off-by: Henrik Brix Andersen <[email protected]>

Author: henrikbrixandersen

doc/reference/canbus/controller.rst

@@ -205,24 +205,24 @@ Receiving
 *********
 
 Frames are only received when they match a filter.
-The following code snippets show how to receive frames by attaching filters.
+The following code snippets show how to receive frames by adding filters.
 
 Here we have an example for a receiving callback as used for
-:c:func:`can_attach_isr`. The argument arg is passed when the filter is
-attached.
+:c:func:`can_add_rx_filter`. The user data argument is passed when the filter is
+added.
 
 .. code-block:: C
 
-  void rx_callback_function(struct zcan_frame *frame, void *arg)
+  void rx_callback_function(struct zcan_frame *frame, void *user_data)
   {
           ... do something with the frame ...
   }
 
-The following snippet shows how to attach a filter with an interrupt callback.
+The following snippet shows how to add a filter with a callback function.
 It is the most efficient but also the most critical way to receive messages.
 The callback function is called from an interrupt context, which means that the
 callback function should be as short as possible and must not block.
-Attaching ISRs is not allowed from userspace context.
+Adding callback functions is not allowed from userspace context.
 
 The filter for this example is configured to match the identifier 0x123 exactly.
 
@@ -240,15 +240,15 @@ The filter for this example is configured to match the identifier 0x123 exactly.
 
   can_dev = device_get_binding("CAN_0");
 
-  filter_id = can_attach_isr(can_dev, rx_callback_function, callback_arg, &my_filter);
+  filter_id = can_add_rx_filter(can_dev, rx_callback_function, callback_arg, &my_filter);
   if (filter_id < 0) {
-    LOG_ERR("Unable to attach isr [%d]", filter_id);
+    LOG_ERR("Unable to add rx filter [%d]", filter_id);
   }
 
-Here an example for :c:func:`can_attach_msgq` is shown. With this function, it
-is possible to receive frames synchronously. This function can be called from
-userspace context.
-The size of the message queue should be as big as the expected backlog.
+Here an example for :c:func:`can_add_rx_filter_msgq` is shown. With this
+function, it is possible to receive frames synchronously. This function can be
+called from userspace context.  The size of the message queue should be as big
+as the expected backlog.
 
 The filter for this example is configured to match the extended identifier
 0x1234567 exactly.
@@ -262,16 +262,16 @@ The filter for this example is configured to match the extended identifier
           .rtr_mask = 1,
           .id_mask = CAN_EXT_ID_MASK
   };
-  CAN_DEFINE_MSGQ(my_can_msgq, 2);
+  CAN_MSGQ_DEFINE(my_can_msgq, 2);
   struct zcan_frame rx_frame;
   int filter_id;
   const struct device *can_dev;
 
   can_dev = device_get_binding("CAN_0");
 
-  filter_id = can_attach_msgq(can_dev, &my_can_msgq, &my_filter);
+  filter_id = can_add_rx_filter_msgq(can_dev, &my_can_msgq, &my_filter);
   if (filter_id < 0) {
-    LOG_ERR("Unable to attach isr [%d]", filter_id);
+    LOG_ERR("Unable to add rx msgq [%d]", filter_id);
     return;
   }
 
@@ -280,11 +280,11 @@ The filter for this example is configured to match the extended identifier
     ... do something with the frame ...
   }
 
-:c:func:`can_detach` removes the given filter.
+:c:func:`can_remove_rx_filter` removes the given filter.
 
 .. code-block:: C
 
-  can_detach(can_dev, filter_id);
+  can_remove_rx_filter(can_dev, filter_id);
 
 Setting the bitrate
 *******************

drivers/can/can_common.c

@@ -40,12 +40,12 @@ static void can_msgq_put(struct zcan_frame *frame, void *arg)
 	}
 }
 
-int z_impl_can_attach_msgq(const struct device *dev, struct k_msgq *msg_q,
-			   const struct zcan_filter *filter)
+int z_impl_can_add_rx_filter_msgq(const struct device *dev, struct k_msgq *msgq,
+				  const struct zcan_filter *filter)
 {
 	const struct can_driver_api *api = dev->api;
 
-	return api->attach_isr(dev, can_msgq_put, msg_q, filter);
+	return api->add_rx_filter(dev, can_msgq_put, msgq, filter);
 }
 
 static inline void can_work_buffer_init(struct can_frame_buffer *buffer)
@@ -140,7 +140,7 @@ int can_attach_workq(const struct device *dev, struct k_work_q *work_q,
 	work->cb_arg = user_data;
 	can_work_buffer_init(&work->buf);
 
-	return api->attach_isr(dev, can_work_isr_put, work, filter);
+	return api->add_rx_filter(dev, can_work_isr_put, work, filter);
 }
 
 

drivers/can/can_handlers.c

@@ -55,30 +55,30 @@ static inline int z_vrfy_can_send(const struct device *dev,
 }
 #include <syscalls/can_send_mrsh.c>
 
-static inline int z_vrfy_can_attach_msgq(const struct device *dev,
-					 struct k_msgq *msgq,
-					 const struct zcan_filter *filter)
+static inline int z_vrfy_can_add_rx_filter_msgq(const struct device *dev,
+						struct k_msgq *msgq,
+						const struct zcan_filter *filter)
 {
 	Z_OOPS(Z_SYSCALL_OBJ(dev, K_OBJ_DRIVER_CAN));
 
 	Z_OOPS(Z_SYSCALL_MEMORY_READ((struct zcan_filter *)filter,
 				     sizeof(struct zcan_filter)));
 	Z_OOPS(Z_SYSCALL_OBJ(msgq, K_OBJ_MSGQ));
 
-	return z_impl_can_attach_msgq((const struct device *)dev,
-				      (struct k_msgq *)msgq,
-				      (const struct zcan_filter *) filter);
+	return z_impl_can_add_rx_filter_msgq((const struct device *)dev,
+					     (struct k_msgq *)msgq,
+					     (const struct zcan_filter *)filter);
 }
-#include <syscalls/can_attach_msgq_mrsh.c>
+#include <syscalls/can_add_rx_filter_msgq_mrsh.c>
 
-static inline void z_vrfy_can_detach(const struct device *dev, int filter_id)
+static inline void z_vrfy_can_remove_rx_filter(const struct device *dev, int filter_id)
 {
 
-	Z_OOPS(Z_SYSCALL_DRIVER_CAN(dev, detach));
+	Z_OOPS(Z_SYSCALL_DRIVER_CAN(dev, remove_rx_filter));
 
-	z_impl_can_detach((const struct device *)dev, (int)filter_id);
+	z_impl_can_remove_rx_filter((const struct device *)dev, (int)filter_id);
 }
-#include <syscalls/can_detach_mrsh.c>
+#include <syscalls/can_remove_rx_filter_mrsh.c>
 
 static inline
 enum can_state z_vrfy_can_get_state(const struct device *dev,

drivers/can/can_loopback.c

@@ -147,9 +147,8 @@ static inline int get_free_filter(struct can_loopback_filter *filters)
 	return -ENOSPC;
 }
 
-int can_loopback_attach_isr(const struct device *dev, can_rx_callback_t isr,
-			    void *cb_arg,
-			    const struct zcan_filter *filter)
+int can_loopback_add_rx_filter(const struct device *dev, can_rx_callback_t cb,
+			       void *cb_arg, const struct zcan_filter *filter)
 {
 	struct can_loopback_data *data = dev->data;
 	struct can_loopback_filter *loopback_filter;
@@ -175,21 +174,21 @@ int can_loopback_attach_isr(const struct device *dev, can_rx_callback_t isr,
 
 	loopback_filter = &data->filters[filter_id];
 
-	loopback_filter->rx_cb = isr;
+	loopback_filter->rx_cb = cb;
 	loopback_filter->cb_arg = cb_arg;
 	loopback_filter->filter = *filter;
 	k_mutex_unlock(&data->mtx);
 
-	LOG_DBG("Filter attached. ID: %d", filter_id);
+	LOG_DBG("Filter added. ID: %d", filter_id);
 
 	return filter_id;
 }
 
-void can_loopback_detach(const struct device *dev, int filter_id)
+void can_loopback_remove_rx_filter(const struct device *dev, int filter_id)
 {
 	struct can_loopback_data *data = dev->data;
 
-	LOG_DBG("Detach filter ID: %d", filter_id);
+	LOG_DBG("Remove filter ID: %d", filter_id);
 	k_mutex_lock(&data->mtx, K_FOREVER);
 	data->filters[filter_id].rx_cb = NULL;
 	k_mutex_unlock(&data->mtx);
@@ -236,11 +235,11 @@ int can_loopback_recover(const struct device *dev, k_timeout_t timeout)
 }
 #endif /* CONFIG_CAN_AUTO_BUS_OFF_RECOVERY */
 
-static void can_loopback_register_state_change_isr(const struct device *dev,
-						   can_state_change_isr_t isr)
+static void can_loopback_set_state_change_callback(const struct device *dev,
+						   can_state_change_callback_t cb)
 {
 	ARG_UNUSED(dev);
-	ARG_UNUSED(isr);
+	ARG_UNUSED(cb);
 }
 
 int can_loopback_get_core_clock(const struct device *dev, uint32_t *rate)
@@ -261,13 +260,13 @@ static const struct can_driver_api can_loopback_driver_api = {
 	.set_mode = can_loopback_set_mode,
 	.set_timing = can_loopback_set_timing,
 	.send = can_loopback_send,
-	.attach_isr = can_loopback_attach_isr,
-	.detach = can_loopback_detach,
+	.add_rx_filter = can_loopback_add_rx_filter,
+	.remove_rx_filter = can_loopback_remove_rx_filter,
 	.get_state = can_loopback_get_state,
 #ifndef CONFIG_CAN_AUTO_BUS_OFF_RECOVERY
 	.recover = can_loopback_recover,
 #endif
-	.register_state_change_isr = can_loopback_register_state_change_isr,
+	.set_state_change_callback = can_loopback_set_state_change_callback,
 	.get_core_clock = can_loopback_get_core_clock,
 	.get_max_filters = can_loopback_get_max_filters,
 	.timing_min = {