drivers: sensor: Add sensor clock API support

This commit introduces a new Sensor Clock API, enabling the retrieval
of cycle counts and conversion to nanoseconds based on the system or
external clock. The API includes:

- `sensor_clock_get_cycles()` to get the current cycle count from the
  sensor clock.
- `sensor_clock_cycles_to_ns()` to convert cycles to nanoseconds using
  the clock's frequency.

The implementation supports both system clocks and external clocks
defined in the device tree, making the sensor clock integration more
flexible for various sensor use cases.

Signed-off-by: Mark Chen <[email protected]>

Author: cmark85

doc/releases/release-notes-4.1.rst

@@ -242,6 +242,33 @@ Drivers and Sensors
 
 * Sensors
 
+  * Sensor Clock
+
+    * The asynchronous sensor API now supports external clock sources. To use an external clock source
+      with the asynchronous sensor API, the following configurations are required:
+
+      * Enable one of the Kconfig options:
+        :kconfig:option:`CONFIG_SENSOR_CLOCK_COUNTER`,
+        :kconfig:option:`CONFIG_SENSOR_CLOCK_RTC`, or
+        :kconfig:option:`CONFIG_SENSOR_CLOCK_SYSTEM`.
+
+      * If not using the system clock, define the ``zephyr,sensor-clock`` property in the device tree to specify
+        the external clock source.
+
+        A typical configuration in the device tree structure is as follows:
+
+        .. code-block:: devicetree
+
+          / {
+            chosen {
+              zephyr,sensor-clock = &timer0;
+            };
+          };
+
+          &timer0 {
+            status = "okay";
+          };
+
 * Serial
 
 * SPI

drivers/sensor/CMakeLists.txt

@@ -74,3 +74,15 @@ zephyr_library_sources_ifdef(CONFIG_SENSOR_SHELL sensor_shell.c)
 zephyr_library_sources_ifdef(CONFIG_SENSOR_SHELL_STREAM sensor_shell_stream.c)
 zephyr_library_sources_ifdef(CONFIG_SENSOR_SHELL_BATTERY shell_battery.c)
 zephyr_library_sources_ifdef(CONFIG_SENSOR_ASYNC_API sensor_decoders_init.c default_rtio_sensor.c)
+
+dt_has_chosen(has_zephyr_sensor_clock PROPERTY "zephyr,sensor-clock")
+
+if(CONFIG_SENSOR_CLOCK_RTC OR CONFIG_SENSOR_CLOCK_COUNTER)
+  if(has_zephyr_sensor_clock)
+    zephyr_library_sources(sensor_clock_external.c)
+  else()
+    message(FATAL_ERROR "Sensor clock type (RTC or Counter) is selected, but no zephyr,sensor-clock is defined in the device tree.")
+  endif()
+elseif(CONFIG_SENSOR_CLOCK_SYSTEM)
+  zephyr_library_sources(sensor_clock_sys.c)
+endif()

drivers/sensor/Kconfig

@@ -82,6 +82,8 @@ config SENSOR_SHELL_MAX_TRIGGER_DEVICES
 config SENSOR_INFO
 	bool "Sensor Info iterable section"
 
+source "drivers/sensor/Kconfig.sensor_clock"
+
 comment "Device Drivers"
 
 # zephyr-keep-sorted-start

drivers/sensor/Kconfig.sensor_clock

@@ -0,0 +1,30 @@
+# Sensor clock configuration options
+# Copyright(c) 2024 Cienet
+# SPDX-License-Identifier: Apache-2.0
+
+config SENSOR_CLOCK
+	bool
+	default y if SENSOR_ASYNC_API
+	help
+	  Configure the sensor clock source for the system.
+
+if SENSOR_CLOCK
+
+choice
+	prompt "Sensor clock type"
+	default SENSOR_CLOCK_SYSTEM
+	help
+	  Select the clock source to be used for sensor timing.
+
+config SENSOR_CLOCK_SYSTEM
+	bool "Use the system counter for sensor time"
+
+config SENSOR_CLOCK_COUNTER
+	bool "Use a counter device/API for sensor time"
+
+config SENSOR_CLOCK_RTC
+	bool "Use an RTC device/API for sensor time"
+
+endchoice
+
+endif # SENSOR_CLOCK

drivers/sensor/adi/adxl345/adxl345_stream.c

@@ -6,7 +6,7 @@
 
 #include <zephyr/logging/log.h>
 #include <zephyr/drivers/sensor.h>
-
+#include <zephyr/drivers/sensor_clock.h>
 #include "adxl345.h"
 
 LOG_MODULE_DECLARE(ADXL345, CONFIG_SENSOR_LOG_LEVEL);
@@ -358,11 +358,21 @@ void adxl345_stream_irq_handler(const struct device *dev)
 {
 	struct adxl345_dev_data *data = (struct adxl345_dev_data *) dev->data;
 	const struct adxl345_dev_config *cfg = (const struct adxl345_dev_config *) dev->config;
+	uint64_t cycles;
+	int rc;
 
 	if (data->sqe == NULL) {
 		return;
 	}
-	data->timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(data->sqe, rc);
+		return;
+	}
+
+	data->timestamp = sensor_clock_cycles_to_ns(cycles);
 	struct rtio_sqe *write_status_addr = rtio_sqe_acquire(data->rtio_ctx);
 	struct rtio_sqe *read_status_reg = rtio_sqe_acquire(data->rtio_ctx);
 	struct rtio_sqe *check_status_reg = rtio_sqe_acquire(data->rtio_ctx);

drivers/sensor/adi/adxl362/adxl362_stream.c

@@ -6,7 +6,7 @@
 
 #include <zephyr/logging/log.h>
 #include <zephyr/drivers/sensor.h>
-
+#include <zephyr/drivers/sensor_clock.h>
 #include "adxl362.h"
 
 LOG_MODULE_DECLARE(ADXL362, CONFIG_SENSOR_LOG_LEVEL);
@@ -384,12 +384,20 @@ static void adxl362_process_status_cb(struct rtio *r, const struct rtio_sqe *sqr
 void adxl362_stream_irq_handler(const struct device *dev)
 {
 	struct adxl362_data *data = (struct adxl362_data *) dev->data;
-
+	uint64_t cycles;
+	int rc;
 	if (data->sqe == NULL) {
 		return;
 	}
 
-	data->timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(data->sqe, rc);
+		return;
+	}
+
+	data->timestamp = sensor_clock_cycles_to_ns(cycles);
 
 	struct rtio_sqe *write_status_addr = rtio_sqe_acquire(data->rtio_ctx);
 	struct rtio_sqe *read_status_reg = rtio_sqe_acquire(data->rtio_ctx);

drivers/sensor/adi/adxl367/adxl367_stream.c

@@ -6,7 +6,7 @@
 
 #include <zephyr/logging/log.h>
 #include <zephyr/drivers/sensor.h>
-
+#include <zephyr/drivers/sensor_clock.h>
 #include "adxl367.h"
 
 LOG_MODULE_DECLARE(ADXL362, CONFIG_SENSOR_LOG_LEVEL);
@@ -537,12 +537,20 @@ static void adxl367_process_status_cb(struct rtio *r, const struct rtio_sqe *sqr
 void adxl367_stream_irq_handler(const struct device *dev)
 {
 	struct adxl367_data *data = (struct adxl367_data *) dev->data;
-
+	uint64_t cycles;
+	int rc;
 	if (data->sqe == NULL) {
 		return;
 	}
 
-	data->timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(data->sqe, rc);
+		return;
+	}
+
+	data->timestamp = sensor_clock_cycles_to_ns(cycles);
 
 	struct rtio_sqe *write_status_addr = rtio_sqe_acquire(data->rtio_ctx);
 	struct rtio_sqe *read_status_reg = rtio_sqe_acquire(data->rtio_ctx);

drivers/sensor/adi/adxl372/adxl372_stream.c

@@ -6,6 +6,7 @@
 
 #include <zephyr/logging/log.h>
 #include <zephyr/drivers/sensor.h>
+#include <zephyr/drivers/sensor_clock.h>
 
 #include "adxl372.h"
 
@@ -424,12 +425,20 @@ static void adxl372_process_status1_cb(struct rtio *r, const struct rtio_sqe *sq
 void adxl372_stream_irq_handler(const struct device *dev)
 {
 	struct adxl372_data *data = (struct adxl372_data *)dev->data;
-
+	uint64_t cycles;
+	int rc;
 	if (data->sqe == NULL) {
 		return;
 	}
 
-	data->timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(data->sqe, rc);
+		return;
+	}
+
+	data->timestamp = sensor_clock_cycles_to_ns(cycles);
 
 	struct rtio_sqe *write_status_addr = rtio_sqe_acquire(data->rtio_ctx);
 	struct rtio_sqe *read_status_reg = rtio_sqe_acquire(data->rtio_ctx);

drivers/sensor/asahi_kasei/akm09918c/akm09918c_async.c

@@ -8,6 +8,7 @@
 
 #include <zephyr/logging/log.h>
 #include <zephyr/rtio/work.h>
+#include <zephyr/drivers/sensor_clock.h>
 
 #include "akm09918c.h"
 
@@ -20,6 +21,7 @@ void akm09918c_submit_sync(struct rtio_iodev_sqe *iodev_sqe)
 	struct akm09918c_data *data = dev->data;
 	const struct sensor_chan_spec *const channels = cfg->channels;
 	const size_t num_channels = cfg->count;
+	uint64_t cycles;
 	int rc;
 
 	/* Check if the requested channels are supported */
@@ -46,8 +48,15 @@ void akm09918c_submit_sync(struct rtio_iodev_sqe *iodev_sqe)
 		return;
 	}
 
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(iodev_sqe, rc);
+		return;
+	}
+
 	/* save information for the work item */
-	data->work_ctx.timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+	data->work_ctx.timestamp = sensor_clock_cycles_to_ns(cycles);
 	data->work_ctx.iodev_sqe = iodev_sqe;
 
 	rc = k_work_schedule(&data->work_ctx.async_fetch_work, K_USEC(AKM09918C_MEASURE_TIME_US));

drivers/sensor/bosch/bma4xx/bma4xx.c

@@ -14,6 +14,7 @@
 #include <zephyr/logging/log.h>
 #include <zephyr/pm/device.h>
 #include <zephyr/rtio/work.h>
+#include <zephyr/drivers/sensor_clock.h>
 
 LOG_MODULE_REGISTER(bma4xx, CONFIG_SENSOR_LOG_LEVEL);
 #include "bma4xx.h"
@@ -352,6 +353,7 @@ static void bma4xx_submit_one_shot(const struct device *dev, struct rtio_iodev_s
 	struct bma4xx_encoded_data *edata;
 	uint8_t *buf;
 	uint32_t buf_len;
+	uint64_t cycles;
 	int rc;
 
 	/* Get the buffer for the frame, it may be allocated dynamically by the rtio context */
@@ -362,11 +364,18 @@ static void bma4xx_submit_one_shot(const struct device *dev, struct rtio_iodev_s
 		return;
 	}
 
+	rc = sensor_clock_get_cycles(&cycles);
+	if (rc != 0) {
+		LOG_ERR("Failed to get sensor clock cycles");
+		rtio_iodev_sqe_err(iodev_sqe, rc);
+		return;
+	}
+
 	/* Prepare response */
 	edata = (struct bma4xx_encoded_data *)buf;
 	edata->header.is_fifo = false;
 	edata->header.accel_fs = bma4xx->accel_fs_range;
-	edata->header.timestamp = k_ticks_to_ns_floor64(k_uptime_ticks());
+	edata->header.timestamp = sensor_clock_cycles_to_ns(cycles);
 	edata->has_accel = 0;
 	edata->has_temp = 0;