1 /***************************************************************************//** 2 * \file cyhal_dac.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Infineon Digital to 6 * Analog Converter. This interface abstracts out the chip specific details. If 7 * any chip specific functionality is necessary, or performance is critical the 8 * low level functions can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_dac DAC (Digital to Analog Converter) 32 * \ingroup group_hal 33 * \{ 34 * High level interface for interacting with the digital to analog converter (DAC). 35 * 36 * This block drives a pin with a firmware configurable voltage. See the device datasheet 37 * for details on which pins support DAC output. 38 * 39 * \section subsection_dac_features Features 40 * The DAC driver provides APIs to: 41 * * Configure and work with the DAC hardware 42 * * Update the DAC output value 43 * * Read the DAC output voltage setting 44 * 45 * \note The \ref cyhal_dac_write and \ref cyhal_dac_read APIs are defined as 16-bit, which may not match the underlying hardware. 46 * The functions will linearly scale the 16-bit value to and from a resolution that hardware is capable of outputting. 47 * For instance, if the device supports 12-bit resolution, only the 12 MSBs of the 16-bit value will be used. 48 * Refer to BSP Settings section in the kit's BSP API Reference Manual for details on the DAC's output range. 49 * 50 * \section subsection_dac_quickstart Quick Start 51 * Call \ref cyhal_dac_init to initialize a DAC instance by providing the DAC 52 * object ( <b> obj </b> ) and an output pin (<b> pin </b>). 53 * 54 * See \ref subsection_dac_use_case_1. 55 * 56 * \section subsection_dac_snippets Code Snippets 57 * 58 * \subsection subsection_dac_use_case_1 Use case 1: Simple DAC initialization 59 * The following snippet initializes a DAC resource and assigns the output to the specified <b>pin</b> using \ref cyhal_dac_init. 60 * \ref cyhal_dac_write is used to set the DAC output value. \ref cyhal_dac_read is used to read back DAC register. 61 * \snippet hal_dac.c snippet_cyhal_dac_simple_init 62 */ 63 64 #pragma once 65 66 #include <stdint.h> 67 #include <stdbool.h> 68 #include "cy_result.h" 69 #include "cyhal_hw_types.h" 70 71 #if defined(__cplusplus) 72 extern "C" { 73 #endif 74 75 /** \addtogroup group_hal_results_dac DAC HAL Results 76 * DAC specific return codes 77 * \ingroup group_hal_results 78 * \{ *//** 79 */ 80 81 /** Bad argument */ 82 #define CYHAL_DAC_RSLT_BAD_ARGUMENT \ 83 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_DAC, 0)) 84 /** Failed to initialize DAC */ 85 #define CYHAL_DAC_RSLT_FAILED_INIT \ 86 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_DAC, 1)) 87 /** Reference voltage is not set */ 88 #define CYHAL_DAC_RSLT_BAD_REF_VOLTAGE \ 89 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_DAC, 2)) 90 /** Bad OPAMP instance is selected */ 91 #define CYHAL_DAC_RSLT_BAD_OPAMP_INSTANCE \ 92 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_DAC, 3)) 93 /** Operation not valid when owned by a configurator */ 94 #define CYHAL_DAC_RSLT_INVALID_CONFIGURATOR \ 95 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_DAC, 4)) 96 97 /** 98 * \} 99 */ 100 101 /** Reference choices for the DAC */ 102 typedef enum 103 { 104 CYHAL_DAC_REF_VDDA, //!< Analog supply (default) 105 CYHAL_DAC_REF_VREF //!< Internal reference. See the BSP documentation for the reference value. 106 } cyhal_dac_ref_t; 107 108 /** Initialize the DAC peripheral 109 * 110 * By default, the reference will be set to @ref CYHAL_DAC_REF_VDDA. 111 * 112 * @param[out] obj Pointer to a DAC object. The caller must allocate the memory 113 * for this object but the init function will initialize its contents. 114 * @param[in] pin The dac pin name 115 * @return The status of the init request. On success returns \ref CY_RSLT_SUCCESS.<br> 116 * On failure, a problem specific error code will be returned. 117 * This error could be from the HAL or lower level driver. <br> 118 * For all other return codes, please refer to device driver documentation available in the BSP landing page 119 */ 120 cy_rslt_t cyhal_dac_init(cyhal_dac_t *obj, cyhal_gpio_t pin); 121 122 /** Initialize the DAC peripheral using a configurator generated configuration struct 123 * 124 * @param[out] obj Pointer to a DAC object. The caller must allocate the memory 125 * for this object but the init function will initialize its contents. 126 * @param[in] cfg Configuration structure generated by a configurator. 127 * @return The status of the init request 128 */ 129 cy_rslt_t cyhal_dac_init_cfg(cyhal_dac_t *obj, const cyhal_dac_configurator_t *cfg); 130 131 /** Release the dac object 132 * 133 * @param[in,out] obj The dac object 134 */ 135 void cyhal_dac_free(cyhal_dac_t *obj); 136 137 /** Set the DAC voltage reference. This determines the highest value that the DAC can output. 138 * 139 * @param obj The DAC object 140 * @param ref The selected voltage reference. 141 * @return The status of the reference selection request 142 */ 143 cy_rslt_t cyhal_dac_set_reference(cyhal_dac_t *obj, cyhal_dac_ref_t ref); 144 145 /** Set the output voltage, as a normalized unsigned 16-bit value 146 * (where 0 is the lowest value the DAC can output and 0xFFFF 147 * is the highest) 148 * 149 * @note While the input value is 16 bits, the actual resolution that can be achieved 150 * is dependent on what the underlying hardware supports. See the device datasheet for details. 151 * 152 * @param[in] obj The dac object 153 * @param[in] value The 16-bit output value to set 154 */ 155 void cyhal_dac_write(const cyhal_dac_t *obj, uint16_t value); 156 157 /** Set the output voltage, as an unsigned number of millivolts. 158 * 159 * @note Depending on the resolution of the underlying hardware, it may not 160 * be possible to achieve the precise voltage requested. See the device datasheet 161 * for more details about the DAC resolution. 162 * 163 * It is an error to specify a value that is outside of the DAC's operating range. 164 * 165 * @param[in] obj The dac object 166 * @param[in] value The number of millivolts to output set. 167 * @return The status of the write request. 168 */ 169 cy_rslt_t cyhal_dac_write_mv(const cyhal_dac_t *obj, uint16_t value); 170 171 /** Read the current DAC output voltage setting, as a normalized unsigned 172 * 16-bit value (where 0 is the lowest value the DAC can output and 0xFFFF 173 * is the highest). 174 * Note: Depending on the precision of the underlying hardware, this may not 175 * precisely match the most recent value passed in to cyhal_dac_write. 176 * 177 * @param[in] obj The dac object 178 * @return The 16-bit output value 179 */ 180 uint16_t cyhal_dac_read(cyhal_dac_t *obj); 181 182 /** Changes the current operating power level of the DAC. 183 * 184 * If the power level is set to @ref CYHAL_POWER_LEVEL_OFF, the DAC will be powered-off 185 * but it will retain its configuration, so it is not necessary to reconfigure it when changing 186 * the power level from @ref CYHAL_POWER_LEVEL_OFF to any other value. 187 * 188 * @param[in] obj dac object 189 * @param[in] power The power level to set 190 * @return The status of the set power request 191 */ 192 cy_rslt_t cyhal_dac_set_power(cyhal_dac_t *obj, cyhal_power_level_t power); 193 194 #if defined(__cplusplus) 195 } 196 #endif 197 198 #ifdef CYHAL_DAC_IMPL_HEADER 199 #include CYHAL_DAC_IMPL_HEADER 200 #endif /* CYHAL_DAC_IMPL_HEADER */ 201 202 /** \} group_hal_dac */ 203
