drivers: blink: add custom out-of-tree driver class

Add a new out-of-tree custom driver class to demonstrate all aspects of
custom driver class creation.

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

CMakeLists.txt

@@ -4,6 +4,12 @@
 # This CMake file is picked by the Zephyr build system because it is defined
 # as the module CMake entry point (see zephyr/module.yml).
 
+
+# This is needed so that custom driver classes using system calls are taken into
+# account
+list(APPEND SYSCALL_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/include)
+set(SYSCALL_INCLUDE_DIRS ${SYSCALL_INCLUDE_DIRS} PARENT_SCOPE)
+
 zephyr_include_directories(include)
 
 add_subdirectory(drivers)

drivers/CMakeLists.txt

@@ -1,4 +1,8 @@
 # Copyright (c) 2021 Nordic Semiconductor ASA
 # SPDX-License-Identifier: Apache-2.0
 
+# Out-of-tree drivers for custom classes
+add_subdirectory_ifdef(CONFIG_BLINK blink)
+
+# Out-of-tree drivers for existing driver classes
 add_subdirectory_ifdef(CONFIG_SENSOR sensor)

drivers/Kconfig

@@ -2,5 +2,6 @@
 # SPDX-License-Identifier: Apache-2.0
 
 menu "Drivers"
+rsource "blink/Kconfig"
 rsource "sensor/Kconfig"
 endmenu

drivers/blink/CMakeLists.txt

@@ -0,0 +1,4 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()

drivers/blink/Kconfig

@@ -0,0 +1,21 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig BLINK
+	bool "Blink device drivers"
+	help
+	  This option enables the blink custom driver class.
+
+if BLINK
+
+config BLINK_INIT_PRIORITY
+	int "Blink device drivers init priority"
+	default KERNEL_INIT_PRIORITY_DEVICE
+	help
+	  Blink device drivers init priority.
+
+module = BLINK
+module-str = blink
+source "subsys/logging/Kconfig.template.log_config"
+
+endif # BLINK

include/app/drivers/blink.h

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef APP_DRIVERS_BLINK_H_
+#define APP_DRIVERS_BLINK_H_
+
+#include <zephyr/device.h>
+#include <zephyr/toolchain.h>
+
+/**
+ * @defgroup drivers_blink Blink drivers
+ * @ingroup drivers
+ * @{
+ *
+ * @brief A custom driver class to blink LEDs
+ *
+ * This driver class is provided as an example of how to create custom driver
+ * classes. It provides an interface to blink an LED at a configurable rate.
+ * Implementations could include simple GPIO-controlled LEDs, addressable LEDs,
+ * etc.
+ */
+
+/**
+ * @defgroup drivers_blink_ops Blink driver operations
+ * @{
+ *
+ * @brief Operations of the blink driver class.
+ *
+ * Each driver class tipically provides a set of operations that need to be
+ * implemented by each driver. These are used to implement the public API. If
+ * support for system calls is needed, the operations structure must be tagged
+ * with `__subsystem` and follow the `${class}_driver_api` naming scheme.
+ */
+
+/** @brief Blink driver class operations */
+__subsystem struct blink_driver_api {
+	/**
+	 * @brief Configure the LED blink period.
+	 *
+	 * @param dev Blink device instance.
+	 * @param period_ms Period of the LED blink in milliseconds, 0 to
+	 * disable blinking.
+	 *
+	 * @retval 0 if successful.
+	 * @retval -EINVAL if @p period_ms can not be set.
+	 * @retval -errno Other negative errno code on failure.
+	 */
+	int (*set_period_ms)(const struct device *dev, unsigned int period_ms);
+};
+
+/** @} */
+
+/**
+ * @defgroup drivers_blink_api Blink driver API
+ * @{
+ *
+ * @brief Public API provided by the blink driver class.
+ *
+ * The public API is the interface that is used by applications to interact with
+ * devices that implement the blink driver class. If support for system calls is
+ * needed, functions accessing device fields need to be tagged with `__syscall`
+ * and provide an implementation that follows the `z_impl_${function_name}`
+ * naming scheme.
+ */
+
+/**
+ * @brief Configure the LED blink period.
+ *
+ *
+ * @param dev Blink device instance.
+ * @param period_ms Period of the LED blink in milliseconds.
+ *
+ * @retval 0 if successful.
+ * @retval -EINVAL if @p period_ms can not be set.
+ * @retval -errno Other negative errno code on failure.
+ */
+__syscall int blink_set_period_ms(const struct device *dev,
+				  unsigned int period_ms);
+
+static inline int z_impl_blink_set_period_ms(const struct device *dev,
+					     unsigned int period_ms)
+{
+	const struct blink_driver_api *api =
+		(const struct blink_driver_api *)dev->api;
+
+	return api->set_period_ms(dev, period_ms);
+}
+
+/**
+ * @brief Turn LED blinking off.
+ *
+ * This is a convenience function to turn off the LED blinking. It also shows
+ * how to create convenience functions that re-use other driver functions, or
+ * driver operations, to provide a higher-level API.
+ *
+ * @param dev Blink device instance.
+ *
+ * @return See blink_set_period_ms().
+ */
+static inline int blink_off(const struct device *dev)
+{
+	return blink_set_period_ms(dev, 0);
+}
+
+#include <syscalls/blink.h>
+
+/** @} */
+
+/** @} */
+
+#endif /* APP_DRIVERS_BLINK_H_ */