[Backport v3.7.99-ncs1-branch] Comparator driver fromtree

MAINTAINERS.yml

@@ -1156,6 +1156,23 @@ Release Notes:
   tests:
     - drivers.clock
 
+"Drivers: Comparator":
+  status: maintained
+  maintainers:
+    - bjarki-andreasen
+  files:
+    - drivers/comparator/
+    - dts/bindings/comparator/
+    - include/zephyr/drivers/comparator.h
+    - include/zephyr/drivers/comparator/
+    - tests/drivers/build_all/comparator/
+    - tests/drivers/comparator/
+    - doc/hardware/peripherals/comparator.rst
+  labels:
+    - "area: Comparator"
+  tests:
+    - drivers.comparator
+
 "Drivers: Console":
   status: odd fixes
   files:

doc/hardware/peripherals/comparator.rst

@@ -0,0 +1,69 @@
+.. _comparator_api:
+
+Comparator
+##########
+
+Overview
+********
+
+An analog comparator compares the voltages of two analog signals connected to its negative and
+positive inputs. If the voltage at the positive input is higher than the negative input, the
+comparator's output will be high, otherwise, it will be low.
+
+Comparators can typically set a trigger which triggers on output changes. This trigger can
+either invoke a callback, or its status can be polled.
+
+Related configuration options:
+
+* :kconfig:option:`CONFIG_COMPARATOR`
+
+Configuration
+*************
+
+Embedded comparators can typically be configured at runtime. When enabled, an initial
+configuration must be provided using the devicetree. At runtime, comparators can have their
+configuration updated using device driver specific APIs. The configuration will be applied
+when the comparator is resumed.
+
+Power management
+****************
+
+Comparators are enabled using power management. When resumed, the comparator will actively
+compare its inputs, producing an output and detecting edges. When suspended, the comparator
+will be inactive.
+
+Comparator shell
+****************
+
+The comparator shell provides the ``comp`` command with a set of subcommands for the
+:ref:`shell <shell_api>` module.
+
+The ``comp`` shell command provides the following subcommands:
+
+* ``get_output`` See :c:func:`comparator_get_output`
+* ``set_trigger`` See :c:func:`comparator_set_trigger`
+* ``await_trigger`` Awaits trigger using the following flow:
+  * Set trigger callback using :c:func:`comparator_set_trigger_callback`
+  * Await callback or time out after default or optionally provided timeout
+  * Clear trigger callback using :c:func:`comparator_set_trigger_callback`
+* ``trigger_is_pending`` See :c:func:`comparator_trigger_is_pending`
+
+Related configuration options:
+
+* :kconfig:option:`CONFIG_SHELL`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_DEFAULT_TIMEOUT`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_MAX_TIMEOUT`
+
+.. note::
+   The power management shell can optionally be enabled alongside the comparator shell.
+
+   Related configuration options:
+
+   * :kconfig:option:`CONFIG_PM_DEVICE`
+   * :kconfig:option:`CONFIG_PM_DEVICE_SHELL`
+
+API Reference
+*************
+
+.. doxygengroup:: comparator_interface

doc/hardware/peripherals/index.rst

@@ -18,6 +18,7 @@ Peripherals
    clock_control.rst
    can/index.rst
    charger.rst
+   comparator.rst
    coredump.rst
    counter.rst
    dac.rst

doc/releases/migration-guide-4.0.rst

@@ -150,6 +150,11 @@ Sensors
   to support all JEDEC JC 42.4 compatible temperature sensors. It now uses the
   :dtcompatible:`jedec,jc-42.4-temp` compatible string instead to the ``microchip,mcp9808`` string.
 
+* The ``nxp,`` prefixed properties in :dtcompatible:`nxp,kinetis-acmp` have been deprecated in favor
+  of properties without the prefix. The sensor based driver for the :dtcompatible:`nxp,kinetis-acmp`
+  has been updated to support both the new and deprecated property names. Uses of the deprecated
+  property names should be updated to the new property names.
+
 Serial
 ======
 

doc/releases/release-notes-4.0.rst

@@ -145,6 +145,14 @@ Drivers and Sensors
 
 * Clock control
 
+* Comparator
+
+  * Introduced comparator device driver subsystem selected with :kconfig:option:`CONFIG_COMPARATOR`
+  * Introduced comparator shell commands selected with :kconfig:option:`CONFIG_COMPARATOR_SHELL`
+  * Added support for Nordic nRF COMP (:dtcompatible:`nordic,nrf-comp`)
+  * Added support for Nordic nRF LPCOMP (:dtcompatible:`nordic,nrf-lpcomp`)
+  * Added support for NXP Kinetis ACMP (:dtcompatible:`nxp,kinetis-acmp`)
+
 * Counter
 
 * DAC

drivers/CMakeLists.txt

@@ -24,6 +24,7 @@ add_subdirectory_ifdef(CONFIG_CACHE_MANAGEMENT cache)
 add_subdirectory_ifdef(CONFIG_CAN can)
 add_subdirectory_ifdef(CONFIG_CHARGER charger)
 add_subdirectory_ifdef(CONFIG_CLOCK_CONTROL clock_control)
+add_subdirectory_ifdef(CONFIG_COMPARATOR comparator)
 add_subdirectory_ifdef(CONFIG_CONSOLE console)
 add_subdirectory_ifdef(CONFIG_COREDUMP_DEVICE coredump)
 add_subdirectory_ifdef(CONFIG_COUNTER counter)

drivers/Kconfig

@@ -15,6 +15,7 @@ source "drivers/cache/Kconfig"
 source "drivers/can/Kconfig"
 source "drivers/charger/Kconfig"
 source "drivers/clock_control/Kconfig"
+source "drivers/comparator/Kconfig"
 source "drivers/console/Kconfig"
 source "drivers/coredump/Kconfig"
 source "drivers/counter/Kconfig"

drivers/comparator/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_syscall_header(${ZEPHYR_BASE}/include/zephyr/drivers/comparator.h)
+
+zephyr_library()
+
+zephyr_library_sources_ifdef(CONFIG_USERSPACE comparator_handlers.c)
+zephyr_library_sources_ifdef(CONFIG_COMPARATOR_FAKE_COMP comparator_fake_comp.c)
+zephyr_library_sources_ifdef(CONFIG_COMPARATOR_MCUX_ACMP comparator_mcux_acmp.c)
+zephyr_library_sources_ifdef(CONFIG_COMPARATOR_NRF_COMP comparator_nrf_comp.c)
+zephyr_library_sources_ifdef(CONFIG_COMPARATOR_NRF_LPCOMP comparator_nrf_lpcomp.c)
+zephyr_library_sources_ifdef(CONFIG_COMPARATOR_SHELL comparator_shell.c)

drivers/comparator/Kconfig

@@ -0,0 +1,27 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig COMPARATOR
+	bool "Comparator drivers"
+	help
+	  Enable comparator driver configuration.
+
+if COMPARATOR
+
+module = COMPARATOR
+module-str = comparator
+source "subsys/logging/Kconfig.template.log_config"
+
+config COMPARATOR_INIT_PRIORITY
+	int "COMPARATOR init priority"
+	default KERNEL_INIT_PRIORITY_DEVICE
+	help
+	  Comparator device driver initialization priority.
+
+rsource "Kconfig.fake_comp"
+rsource "Kconfig.mcux_acmp"
+rsource "Kconfig.nrf_comp"
+rsource "Kconfig.nrf_lpcomp"
+rsource "Kconfig.shell"
+
+endif # COMPARATOR

drivers/comparator/Kconfig.fake_comp

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config COMPARATOR_FAKE_COMP
+	bool "Fake comparator driver"
+	default y
+	depends on DT_HAS_ZEPHYR_FAKE_COMP_ENABLED
+	depends on ZTEST

drivers/comparator/Kconfig.mcux_acmp

@@ -0,0 +1,9 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config COMPARATOR_MCUX_ACMP
+	bool "NXP MCUX ACMP comparator driver"
+	default y
+	depends on DT_HAS_NXP_KINETIS_ACMP_ENABLED
+	select PINCTRL
+	select MCUX_ACMP

drivers/comparator/Kconfig.nrf_comp

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config COMPARATOR_NRF_COMP
+	bool "Nordic COMP comparator driver"
+	default y
+	depends on DT_HAS_NORDIC_NRF_COMP_ENABLED
+	select NRFX_COMP

drivers/comparator/Kconfig.nrf_lpcomp

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config COMPARATOR_NRF_LPCOMP
+	bool "Nordic LPCOMP comparator driver"
+	default y
+	depends on DT_HAS_NORDIC_NRF_LPCOMP_ENABLED
+	select NRFX_LPCOMP

drivers/comparator/Kconfig.shell

@@ -0,0 +1,21 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config COMPARATOR_SHELL
+	bool "Comparator shell"
+	default y
+	depends on SHELL
+	help
+	  Comparator device driver shell.
+
+if COMPARATOR_SHELL
+
+config COMPARATOR_SHELL_AWAIT_TRIGGER_DEFAULT_TIMEOUT
+	int "Default timeout for await_trigger command in seconds"
+	default 10
+
+config COMPARATOR_SHELL_AWAIT_TRIGGER_MAX_TIMEOUT
+	int "Max timeout for await_trigger command in seconds"
+	default 60
+
+endif # COMPARATOR_SHELL

drivers/comparator/comparator_fake_comp.c

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/comparator/fake_comp.h>
+
+#ifdef CONFIG_ZTEST
+#include <zephyr/ztest.h>
+#endif
+
+#define DT_DRV_COMPAT zephyr_fake_comp
+
+DEFINE_FAKE_VALUE_FUNC(int,
+		       comp_fake_comp_get_output,
+		       const struct device *);
+
+DEFINE_FAKE_VALUE_FUNC(int,
+		       comp_fake_comp_set_trigger,
+		       const struct device *,
+		       enum comparator_trigger);
+
+DEFINE_FAKE_VALUE_FUNC(int,
+		       comp_fake_comp_set_trigger_callback,
+		       const struct device *,
+		       comparator_callback_t,
+		       void *);
+
+DEFINE_FAKE_VALUE_FUNC(int,
+		       comp_fake_comp_trigger_is_pending,
+		       const struct device *);
+
+static const struct comparator_driver_api fake_comp_api = {
+	.get_output = comp_fake_comp_get_output,
+	.set_trigger = comp_fake_comp_set_trigger,
+	.set_trigger_callback = comp_fake_comp_set_trigger_callback,
+	.trigger_is_pending = comp_fake_comp_trigger_is_pending,
+};
+
+#ifdef CONFIG_ZTEST
+static void fake_comp_reset_rule_before(const struct ztest_unit_test *test, void *fixture)
+{
+	ARG_UNUSED(test);
+	ARG_UNUSED(fixture);
+
+	RESET_FAKE(comp_fake_comp_get_output);
+	RESET_FAKE(comp_fake_comp_set_trigger);
+	RESET_FAKE(comp_fake_comp_set_trigger_callback);
+	RESET_FAKE(comp_fake_comp_trigger_is_pending);
+}
+
+ZTEST_RULE(comp_fake_comp_reset_rule, fake_comp_reset_rule_before, NULL);
+#endif
+
+DEVICE_DT_INST_DEFINE(
+	0,
+	NULL,
+	NULL,
+	NULL,
+	NULL,
+	POST_KERNEL,
+	CONFIG_COMPARATOR_INIT_PRIORITY,
+	&fake_comp_api
+);

drivers/comparator/comparator_handlers.c

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/comparator.h>
+#include <zephyr/internal/syscall_handler.h>
+
+static inline int z_vrfy_comparator_get_output(const struct device *dev)
+{
+	K_OOPS(K_SYSCALL_DRIVER_COMPARATOR(dev, get_output));
+	return z_impl_comparator_get_output(dev);
+}
+#include <zephyr/syscalls/comparator_get_output_mrsh.c>
+
+static inline int z_vrfy_comparator_set_trigger(const struct device *dev,
+						enum comparator_trigger trigger)
+{
+	K_OOPS(K_SYSCALL_DRIVER_COMPARATOR(dev, set_trigger));
+	return z_impl_comparator_set_trigger(dev, trigger);
+}
+#include <zephyr/syscalls/comparator_set_trigger_mrsh.c>
+
+static inline int z_vrfy_comparator_trigger_is_pending(const struct device *dev)
+{
+	K_OOPS(K_SYSCALL_DRIVER_COMPARATOR(dev, trigger_is_pending));
+	return z_impl_comparator_trigger_is_pending(dev);
+}
+#include <zephyr/syscalls/comparator_trigger_is_pending_mrsh.c>