haptics: Introduces a haptics API

Introduces a haptics API for use with LRA driver ICs to
create haptic feedback events.

Signed-off-by: Ricardo Rivera-Matos <ricardo.rivera-matos@cirrus.com>

doc/hardware/peripherals/haptics.rst

@@ -0,0 +1,26 @@
+.. _haptics_api:
+
+Haptics
+#######
+
+Overview
+********
+
+The haptics API allows for the control of haptic driver devices for the
+purposes of performing haptic feedback events.
+
+During a haptic feedback event the haptic device drives a signal to an
+actuator. The source of the haptic event signal varies depending on the
+capabilities of the haptic device.
+
+Some examples of haptic signal sources are analog signals, preprogrammed
+(ROM) wavetables, synthesized (RAM) wavetables, and digital audio streams.
+
+Additionally, haptic driver devices often offer controls for adjusting and
+tuning the drive signal to meet the electrical requirements of their respective
+actuators.
+
+API Reference
+*************
+
+.. doxygengroup:: haptics_interface

doc/hardware/peripherals/index.rst

@@ -31,6 +31,7 @@ Peripherals
    fuel_gauge.rst
    gnss.rst
    gpio.rst
+   haptics.rst
    hwinfo.rst
    i2c_eeprom_target.rst
    i3c.rst

drivers/CMakeLists.txt

@@ -42,6 +42,7 @@ add_subdirectory_ifdef(CONFIG_FPGA fpga)
 add_subdirectory_ifdef(CONFIG_FUEL_GAUGE fuel_gauge)
 add_subdirectory_ifdef(CONFIG_GNSS gnss)
 add_subdirectory_ifdef(CONFIG_GPIO gpio)
+add_subdirectory_ifdef(CONFIG_HAPTICS haptics)
 add_subdirectory_ifdef(CONFIG_HWINFO hwinfo)
 add_subdirectory_ifdef(CONFIG_HWSPINLOCK  hwspinlock)
 add_subdirectory_ifdef(CONFIG_I2C i2c)

drivers/Kconfig

@@ -35,6 +35,7 @@ source "drivers/fpga/Kconfig"
 source "drivers/fuel_gauge/Kconfig"
 source "drivers/gnss/Kconfig"
 source "drivers/gpio/Kconfig"
+source "drivers/haptics/Kconfig"
 source "drivers/hwinfo/Kconfig"
 source "drivers/hwspinlock/Kconfig"
 source "drivers/i2c/Kconfig"

drivers/haptics/CMakeLists.txt

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()
+zephyr_syscall_header(${ZEPHYR_BASE}/include/zephyr/drivers/haptics.h)
+
+zephyr_library_sources_ifdef(CONFIG_USERSPACE haptics_handlers.c)

drivers/haptics/Kconfig

@@ -0,0 +1,22 @@
+# Copyright 2024 Cirrus Logic, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig HAPTICS
+	bool "Haptic feedback drivers"
+	help
+	  Enable haptics driver configuration.
+
+if HAPTICS
+
+module = HAPTICS
+module-str = haptics
+source "subsys/logging/Kconfig.template.log_config"
+
+config HAPTICS_INIT_PRIORITY
+	int "Haptic driver init priority"
+	default 90
+	help
+	  Haptic driver initialization priority.
+
+endif # HAPTICS

drivers/haptics/haptics_handlers.c

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024 Cirrus Logic, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/syscall_handler.h>
+#include <zephyr/drivers/haptics.h>
+
+static inline int z_vrfy_haptics_start_output(const struct device *dev)
+{
+	Z_OOPS(Z_SYSCALL_DRIVER_HAPTICS(dev, start_output));
+
+	return z_impl_haptics_start_output(dev);
+}
+
+#include <syscalls/haptics_start_output_mrsh.c>
+
+static inline int z_vrfy_haptics_stop_output(const struct device *dev)
+{
+	Z_OOPS(Z_SYSCALL_DRIVER_HAPTICS(dev, stop_output));
+
+	z_impl_haptics_stop_output(dev);
+}
+
+#include <syscalls/haptics_stop_output_mrsh.c>

include/zephyr/drivers/haptics.h

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2024 Cirrus Logic, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_
+#define ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_
+
+/**
+ * @brief Haptics Interface
+ * @defgroup haptics_interface Haptics Interface
+ * @ingroup io_interfaces
+ * @{
+ */
+
+#include <zephyr/device.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @typedef haptics_stop_output_t
+ * @brief Set the haptic device to stop output
+ * @param dev Pointer to the device structure for haptic device instance
+ */
+typedef int (*haptics_stop_output_t)(const struct device *dev);
+
+/**
+ * @typedef haptics_start_output_t
+ * @brief Set the haptic device to start output for a playback event
+ */
+typedef int (*haptics_start_output_t)(const struct device *dev);
+
+/**
+ * @brief Haptic device API
+ */
+__subsystem struct haptics_driver_api {
+	haptics_start_output_t start_output;
+	haptics_stop_output_t stop_output;
+};
+
+/**
+ * @brief Set the haptic device to start output for a playback event
+ *
+ * @param dev Pointer to the device structure for haptic device instance
+ *
+ * @retval 0 if successful
+ * @retval <0 if failed
+ */
+__syscall int haptics_start_output(const struct device *dev);
+
+static inline int z_impl_haptics_start_output(const struct device *dev)
+{
+	const struct haptics_driver_api *api = (const struct haptics_driver_api *)dev->api;
+
+	return api->start_output(dev);
+}
+
+/**
+ * @brief Set the haptic device to stop output for a playback event
+ *
+ * @param dev Pointer to the device structure for haptic device instance
+ *
+ * @retval 0 if successful
+ * @retval <0 if failed
+ */
+__syscall int haptics_stop_output(const struct device *dev);
+
+static inline int z_impl_haptics_stop_output(const struct device *dev)
+{
+	const struct haptics_driver_api *api = (const struct haptics_driver_api *)dev->api;
+
+	return api->stop_output(dev);
+}
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#include <syscalls/haptics.h>
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_ */