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