device: introduce device_get

Add a new API to claim a device. This function will increase device
usage count and, if not initialized, it will perform its
initialization.

Function is thread-safe and will block until initialization
completes, returning the result.

If device has been initialized at boot time, regardless of its usage
count, device reference count will be increased but no initialization
will be performed.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>

Author: gmarull

include/zephyr/device.h

@@ -11,6 +11,7 @@
 
 #include <zephyr/devicetree.h>
 #include <zephyr/init.h>
+#include <zephyr/kernel.h>
 #include <zephyr/linker/sections.h>
 #include <zephyr/pm/state.h>
 #include <zephyr/sys/device_mmio.h>
@@ -433,6 +434,12 @@ struct device_state {
 	 * invoked.
 	 */
 	bool initialized : 1;
+	/** Usage count. */
+	uint8_t usage;
+#if defined(CONFIG_MULTITHREADING) || defined(__DOXYGEN__)
+	/** Usage lock (@kconfig_dep(CONFIG_MULTITHREADING}). */
+	struct k_sem usage_lock;
+#endif
 };
 
 struct pm_device_base;
@@ -844,6 +851,21 @@ __syscall bool device_is_ready(const struct device *dev);
  */
 __syscall int device_init(const struct device *dev);
 
+/**
+ * Get a device.
+ *
+ * When getting a device, its usage count will be increased and, if not yet
+ * initialized, its initialization routine will be called. This function will
+ * not return until device initialization has finished.
+ *
+ * @param dev Device instance
+ *
+ * @retval -errno Device failed to initialize.
+ * @retval >=0 Device was successfully initialized and can be used. Values > 0
+ * indicate the current reference count.
+ */
+__syscall int device_get(const struct device *dev);
+
 /**
  * @}
  */
@@ -861,9 +883,13 @@ __syscall int device_init(const struct device *dev);
  *
  * @param dev_id Device identifier.
  */
-#define Z_DEVICE_STATE_DEFINE(dev_id)                                          \
-	static Z_DECL_ALIGN(struct device_state) Z_DEVICE_STATE_NAME(dev_id)   \
-		__attribute__((__section__(".z_devstate")))
+#define Z_DEVICE_STATE_DEFINE(dev_id)                                                    \
+	static Z_DECL_ALIGN(struct device_state) Z_DEVICE_STATE_NAME(dev_id)             \
+		__attribute__((__section__(".z_devstate"))) = {                          \
+			IF_ENABLED(CONFIG_MULTITHREADING,                                \
+				   (.usage_lock = Z_SEM_INITIALIZER(                     \
+					Z_DEVICE_STATE_NAME(dev_id).usage_lock, 1, 1),)) \
+		}
 
 /**
  * @brief Device flags obtained from DT.

include/zephyr/sw_isr_table.h

@@ -15,7 +15,6 @@
 #define ZEPHYR_INCLUDE_SW_ISR_TABLE_H_
 
 #if !defined(_ASMLANGUAGE)
-#include <zephyr/device.h>
 #include <zephyr/sys/iterable_sections.h>
 #include <zephyr/types.h>
 #include <zephyr/toolchain.h>
@@ -25,6 +24,8 @@
 extern "C" {
 #endif
 
+struct device;
+
 /* Default vector for the IRQ vector table */
 void _isr_wrapper(void);
 

kernel/device.c

@@ -142,6 +142,61 @@ bool z_impl_device_is_ready(const struct device *dev)
 	return dev->state->initialized && (dev->state->init_res == 0U);
 }
 
+int z_impl_device_get(const struct device *dev)
+{
+	int ret = 0;
+
+	if (dev == NULL) {
+		return -ENODEV;
+	}
+
+#ifdef CONFIG_MULTITHREADING
+	if (!k_is_pre_kernel()) {
+		(void)k_sem_take(&dev->state->usage_lock, K_FOREVER);
+	}
+#endif
+
+	if (dev->state->usage == UINT8_MAX) {
+		ret = -EPERM;
+		goto out;
+	}
+
+	if ((dev->state->usage == 0U) && (dev->ops.init != NULL)) {
+		if (dev->state->initialized) {
+			if (dev->state->init_res != 0U) {
+				ret = dev->ops.init(dev);
+			}
+			dev->state->initialized = false;
+		} else {
+			ret = dev->ops.init(dev);
+		}
+	}
+
+	if (ret == 0) {
+		dev->state->usage++;
+		ret = dev->state->usage;
+	}
+
+out:
+#ifdef CONFIG_MULTITHREADING
+	if (!k_is_pre_kernel()) {
+		(void)k_sem_give(&dev->state->usage_lock);
+	}
+#endif
+
+	return ret;
+}
+
+#ifdef CONFIG_USERSPACE
+static inline int z_vrfy_device_get(const struct device *dev)
+{
+	K_OOPS(K_SYSCALL_OBJ_INIT(dev, K_OBJ_ANY));
+
+	return z_impl_device_get(dev);
+}
+#include <zephyr/syscalls/device_get_mrsh.c>
+#endif
+
 #ifdef CONFIG_DEVICE_DEPS
 
 static int device_visitor(const device_handle_t *handles,