1 /*
2 * Copyright (c) 2020 Libre Solar Technologies GmbH
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief DAC public API header file.
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_DAC_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_DAC_H_
14
15 #include <zephyr/device.h>
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 /**
22 * @brief DAC driver APIs
23 * @defgroup dac_interface DAC driver APIs
24 * @since 2.3
25 * @version 0.8.0
26 * @ingroup io_interfaces
27 * @{
28 */
29
30 /**
31 * @brief Broadcast channel identifier for DACs that support it.
32 * @note Only for use in dac_write_value().
33 */
34 #define DAC_CHANNEL_BROADCAST 0xFF
35
36 /**
37 * @brief Structure for specifying the configuration of a DAC channel.
38 */
39 struct dac_channel_cfg {
40 /** Channel identifier of the DAC that should be configured. */
41 uint8_t channel_id;
42 /** Desired resolution of the DAC (depends on device capabilities). */
43 uint8_t resolution;
44 /** Enable output buffer for this channel.
45 * This is relevant for instance if the output is directly connected to the load,
46 * without an amplifierin between. The actual details on this are hardware dependent.
47 */
48 bool buffered: 1;
49 /** Enable internal output path for this channel. This is relevant for channels that
50 * support directly connecting to on-chip peripherals via internal paths. The actual
51 * details on this are hardware dependent.
52 */
53 bool internal: 1;
54 };
55
56 /**
57 * @cond INTERNAL_HIDDEN
58 *
59 * For internal use only, skip these in public documentation.
60 */
61
62 /*
63 * Type definition of DAC API function for configuring a channel.
64 * See dac_channel_setup() for argument descriptions.
65 */
66 typedef int (*dac_api_channel_setup)(const struct device *dev,
67 const struct dac_channel_cfg *channel_cfg);
68
69 /*
70 * Type definition of DAC API function for setting a write request.
71 * See dac_write_value() for argument descriptions.
72 */
73 typedef int (*dac_api_write_value)(const struct device *dev,
74 uint8_t channel, uint32_t value);
75
76 /*
77 * DAC driver API
78 *
79 * This is the mandatory API any DAC driver needs to expose.
80 */
81 __subsystem struct dac_driver_api {
82 dac_api_channel_setup channel_setup;
83 dac_api_write_value write_value;
84 };
85
86 /**
87 * @endcond
88 */
89
90 /**
91 * @brief Configure a DAC channel.
92 *
93 * It is required to call this function and configure each channel before it is
94 * selected for a write request.
95 *
96 * @param dev Pointer to the device structure for the driver instance.
97 * @param channel_cfg Channel configuration.
98 *
99 * @retval 0 On success.
100 * @retval -EINVAL If a parameter with an invalid value has been provided.
101 * @retval -ENOTSUP If the requested resolution is not supported.
102 */
103 __syscall int dac_channel_setup(const struct device *dev,
104 const struct dac_channel_cfg *channel_cfg);
105
z_impl_dac_channel_setup(const struct device * dev,const struct dac_channel_cfg * channel_cfg)106 static inline int z_impl_dac_channel_setup(const struct device *dev,
107 const struct dac_channel_cfg *channel_cfg)
108 {
109 const struct dac_driver_api *api =
110 (const struct dac_driver_api *)dev->api;
111
112 return api->channel_setup(dev, channel_cfg);
113 }
114
115 /**
116 * @brief Write a single value to a DAC channel
117 *
118 * @param dev Pointer to the device structure for the driver instance.
119 * @param channel Number of the channel to be used.
120 * @param value Data to be written to DAC output registers.
121 *
122 * @retval 0 On success.
123 * @retval -EINVAL If a parameter with an invalid value has been provided.
124 */
125 __syscall int dac_write_value(const struct device *dev, uint8_t channel,
126 uint32_t value);
127
z_impl_dac_write_value(const struct device * dev,uint8_t channel,uint32_t value)128 static inline int z_impl_dac_write_value(const struct device *dev,
129 uint8_t channel, uint32_t value)
130 {
131 const struct dac_driver_api *api =
132 (const struct dac_driver_api *)dev->api;
133
134 return api->write_value(dev, channel, value);
135 }
136
137 /**
138 * @}
139 */
140
141 #ifdef __cplusplus
142 }
143 #endif
144
145 #include <zephyr/syscalls/dac.h>
146
147 #endif /* ZEPHYR_INCLUDE_DRIVERS_DAC_H_ */
148
