drivers: dac: Add API for DAC peripherals

DAC (digital to analog converter) peripheral driver with a generic API
suitable for most MCUs (only basic DAC features considered).

Signed-off-by: Martin Jäger <martin@libre.solar>

CODEOWNERS

@@ -144,6 +144,7 @@
 /drivers/console/*mux*                    @jukkar
 /drivers/display/                         @vanwinkeljan
 /drivers/display/display_framebuf.c       @andrewboie
+/drivers/dac/                             @martinjaeger
 /drivers/dma/*dw*                         @tbursztyka
 /drivers/dma/*sam0*                       @Sizurka
 /drivers/dma/dma_stm32*                   @cybertale
@@ -285,6 +286,7 @@
 /include/drivers/adc.h                    @anangl
 /include/drivers/can.h                    @alexanderwachter
 /include/drivers/counter.h                @nordic-krch
+/include/drivers/dac.h                    @martinjaeger
 /include/drivers/display.h                @vanwinkeljan
 /include/drivers/espi.h                   @albertofloyd @franciscomunoz @scottwcpg
 /include/drivers/bluetooth/               @joerchan @jhedberg @Vudentz

doc/reference/overview.rst

@@ -99,6 +99,11 @@ current :ref:`stability level <api_lifecycle>`.
      - 1.5
      - 2.0
 
+   * - :ref:`dac_api`
+     - Experimental
+     - 2.3
+     - 2.3
+
    * - :ref:`eeprom_api`
      - Experimental
      - 2.1

doc/reference/peripherals/dac.rst

@@ -0,0 +1,22 @@
+.. _dac_api:
+
+DAC
+###
+
+Overview
+********
+
+The DAC API provides access to Digital-to-Analog Converter (DAC) devices.
+
+Configuration Options
+*********************
+
+Related configuration options:
+
+* :option:`CONFIG_DAC`
+
+API Reference
+*************
+
+.. doxygengroup:: dac_interface
+   :project: Zephyr

doc/reference/peripherals/index.rst

@@ -9,6 +9,7 @@ Peripherals
    adc.rst
    counter.rst
    clock_control.rst
+   dac.rst
    dma.rst
    eeprom.rst
    entropy.rst

drivers/CMakeLists.txt

@@ -9,6 +9,7 @@ add_subdirectory_if_kconfig(adc)
 add_subdirectory_if_kconfig(clock_control)
 add_subdirectory_if_kconfig(counter)
 add_subdirectory_if_kconfig(crypto)
+add_subdirectory_if_kconfig(dac)
 add_subdirectory_if_kconfig(display)
 add_subdirectory_if_kconfig(dma)
 add_subdirectory_if_kconfig(gpio)

drivers/Kconfig

@@ -45,6 +45,8 @@ source "drivers/pinmux/Kconfig"
 
 source "drivers/adc/Kconfig"
 
+source "drivers/dac/Kconfig"
+
 source "drivers/watchdog/Kconfig"
 
 source "drivers/clock_control/Kconfig"

drivers/dac/CMakeLists.txt

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()
+
+zephyr_library_sources_ifdef(CONFIG_USERSPACE		dac_handlers.c)

drivers/dac/Kconfig

@@ -0,0 +1,20 @@
+# DAC configuration options
+
+# Copyright (c) 2020 Libre Solar Technologies GmbH
+# SPDX-License-Identifier: Apache-2.0
+
+#
+# DAC options
+#
+menuconfig DAC
+	bool "DAC drivers"
+	help
+	  Enable DAC (Digital to Analog Converter) driver configuration.
+
+if DAC
+
+module = DAC
+module-str = DAC
+source "subsys/logging/Kconfig.template.log_config"
+
+endif # DAC

drivers/dac/dac_handlers.c

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2020 Libre Solar Technologies GmbH
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <drivers/dac.h>
+#include <syscall_handler.h>
+#include <kernel.h>
+
+static inline int z_vrfy_dac_channel_setup(struct device *dev,
+			const struct dac_channel_cfg *user_channel_cfg)
+{
+	struct dac_channel_cfg channel_cfg;
+
+	Z_OOPS(Z_SYSCALL_DRIVER_DAC(dev, channel_setup));
+	Z_OOPS(z_user_from_copy(&channel_cfg,
+				(struct dac_channel_cfg *)user_channel_cfg,
+				sizeof(struct dac_channel_cfg)));
+
+	return z_impl_dac_channel_setup((struct device *)dev, &channel_cfg);
+}
+#include <syscalls/dac_channel_setup_mrsh.c>
+
+static inline int z_vrfy_dac_write_value(struct device *dev,
+					u8_t channel, u32_t value)
+{
+	Z_OOPS(Z_SYSCALL_DRIVER_DAC(dev, write_value));
+
+	return z_impl_dac_write_value((struct device *)dev, channel, value);
+}
+#include <syscalls/dac_write_value_mrsh.c>

dts/bindings/dac/dac-controller.yaml

@@ -0,0 +1,14 @@
+# Copyright (c) 2020 Libre Solar Technologies GmbH
+# SPDX-License-Identifier: Apache-2.0
+
+# Common fields for DAC controllers
+
+include: base.yaml
+
+properties:
+    label:
+      required: true
+
+    "#io-channel-cells":
+      type: int
+      required: true

include/drivers/dac.h

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2020 Libre Solar Technologies GmbH
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief DAC public API header file.
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_DAC_H_
+#define ZEPHYR_INCLUDE_DRIVERS_DAC_H_
+
+#include <device.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief DAC driver APIs
+ * @defgroup dac_interface DAC driver APIs
+ * @ingroup io_interfaces
+ * @{
+ */
+
+/**
+ * @struct dac_channel_cfg
+ * @brief Structure for specifying the configuration of a DAC channel.
+ *
+ * @param channel_id Channel identifier of the DAC that should be configured.
+ * @param resolution Desired resolution of the DAC (depends on device
+ *                   capabilities).
+ */
+struct dac_channel_cfg {
+	u8_t channel_id;
+	u8_t resolution;
+};
+
+/**
+ * @cond INTERNAL_HIDDEN
+ *
+ * For internal use only, skip these in public documentation.
+ */
+
+/*
+ * Type definition of DAC API function for configuring a channel.
+ * See dac_channel_setup() for argument descriptions.
+ */
+typedef int (*dac_api_channel_setup)(struct device *dev,
+				const struct dac_channel_cfg *channel_cfg);
+
+/*
+ * Type definition of DAC API function for setting a write request.
+ * See dac_write_value() for argument descriptions.
+ */
+typedef int (*dac_api_write_value)(struct device *dev,
+				    u8_t channel, u32_t value);
+
+/*
+ * DAC driver API
+ *
+ * This is the mandatory API any DAC driver needs to expose.
+ */
+__subsystem struct dac_driver_api {
+	dac_api_channel_setup channel_setup;
+	dac_api_write_value   write_value;
+};
+
+/**
+ * @endcond
+ */
+
+/**
+ * @brief Configure a DAC channel.
+ *
+ * It is required to call this function and configure each channel before it is
+ * selected for a write request.
+ *
+ * @param dev          Pointer to the device structure for the driver instance.
+ * @param channel_cfg  Channel configuration.
+ *
+ * @retval 0         On success.
+ * @retval -EINVAL   If a parameter with an invalid value has been provided.
+ * @retval -ENOTSUP  If the requested resolution is not supported.
+ */
+__syscall int dac_channel_setup(struct device *dev,
+				const struct dac_channel_cfg *channel_cfg);
+
+static inline int z_impl_dac_channel_setup(struct device *dev,
+				const struct dac_channel_cfg *channel_cfg)
+{
+	const struct dac_driver_api *api =
+				(const struct dac_driver_api *)dev->driver_api;
+
+	return api->channel_setup(dev, channel_cfg);
+}
+
+/**
+ * @brief Write a single value to a DAC channel
+ *
+ * @param dev         Pointer to the device structure for the driver instance.
+ * @param channel     Number of the channel to be used.
+ * @param value       Data to be written to DAC output registers.
+ *
+ * @retval 0        On success.
+ * @retval -EINVAL  If a parameter with an invalid value has been provided.
+ */
+__syscall int dac_write_value(struct device *dev, u8_t channel, u32_t value);
+
+static inline int z_impl_dac_write_value(struct device *dev,
+						u8_t channel, u32_t value)
+{
+	const struct dac_driver_api *api =
+				(const struct dac_driver_api *)dev->driver_api;
+
+	return api->write_value(dev, channel, value);
+}
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <syscalls/dac.h>
+
+#endif  /* ZEPHYR_INCLUDE_DRIVERS_DAC_H_ */