1 /*
2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6 
7 /*******************************************************************************************************************//**
8  * @ingroup RENESAS_ANALOG_INTERFACES
9  * @defgroup DAC_API DAC Interface
10  * @brief Interface for D/A converters.
11  *
12  * @section DAC_API_SUMMARY Summary
13  * The DAC interface provides standard Digital/Analog Converter functionality.  A DAC application writes digital
14  * sample data to the device and generates analog output on the DAC output pin.
15  *
16  *
17  * @{
18  **********************************************************************************************************************/
19 
20 #ifndef R_DAC_API_H
21 #define R_DAC_API_H
22 
23 /***********************************************************************************************************************
24  * Includes
25  **********************************************************************************************************************/
26 
27 /* Common error codes and definitions. */
28 #include "bsp_api.h"
29 
30 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
31 FSP_HEADER
32 
33 /**********************************************************************************************************************
34  * Macro definitions
35  **********************************************************************************************************************/
36 
37 /**********************************************************************************************************************
38  * Typedef definitions
39  **********************************************************************************************************************/
40 
41 /** DAC Open API data format settings. */
42 typedef enum e_dac_data_format
43 {
44     DAC_DATA_FORMAT_FLUSH_RIGHT = 0,   ///< LSB of data is flush to the right leaving the top 4 bits unused.
45     DAC_DATA_FORMAT_FLUSH_LEFT  = 1    ///< MSB of data is flush to the left leaving the bottom 4 bits unused.
46 } dac_data_format_t;
47 
48 /** DAC information structure to store various information for a DAC */
49 typedef struct dac_info
50 {
51     uint8_t bit_width;                 ///< Resolution of the DAC.
52 } dac_info_t;
53 
54 /** DAC Open API configuration parameter */
55 typedef struct st_dac_cfg
56 {
57     uint8_t      channel;              ///< ID associated with this DAC channel
58     bool         ad_da_synchronized;   ///< AD/DA synchronization
59     void const * p_extend;
60 } dac_cfg_t;
61 
62 /** DAC control block.  Allocate an instance specific control block to pass into the DAC API calls.
63  */
64 typedef void dac_ctrl_t;
65 
66 /** DAC driver structure.  General DAC functions implemented at the HAL layer follow this API. */
67 typedef struct st_dac_api
68 {
69     /** Initial configuration.
70      *
71      * @param[in]   p_ctrl     Pointer to control block. Must be declared by user. Elements set here.
72      * @param[in]   p_cfg      Pointer to configuration structure. All elements of this structure must be set by user.
73      */
74     fsp_err_t (* open)(dac_ctrl_t * const p_ctrl, dac_cfg_t const * const p_cfg);
75 
76     /** Close the D/A Converter.
77      *
78      * @param[in]   p_ctrl     Control block set in @ref dac_api_t::open call for this timer.
79      */
80     fsp_err_t (* close)(dac_ctrl_t * const p_ctrl);
81 
82     /** Write sample value to the D/A Converter.
83      *
84      * @param[in]   p_ctrl     Control block set in @ref dac_api_t::open call for this timer.
85      * @param[in]   value      Sample value to be written to the D/A Converter.
86      */
87     fsp_err_t (* write)(dac_ctrl_t * const p_ctrl, uint16_t value);
88 
89     /** Start the D/A Converter if it has not been started yet.
90      *
91      * @param[in]   p_ctrl     Control block set in @ref dac_api_t::open call for this timer.
92      */
93     fsp_err_t (* start)(dac_ctrl_t * const p_ctrl);
94 
95     /** Stop the D/A Converter if the converter is running.
96      *
97      * @param[in]   p_ctrl     Control block set in @ref dac_api_t::open call for this timer.
98      */
99     fsp_err_t (* stop)(dac_ctrl_t * const p_ctrl);
100 } dac_api_t;
101 
102 /** This structure encompasses everything that is needed to use an instance of this interface. */
103 typedef struct st_dac_instance
104 {
105     dac_ctrl_t      * p_ctrl;          ///< Pointer to the control structure for this instance
106     dac_cfg_t const * p_cfg;           ///< Pointer to the configuration structure for this instance
107     dac_api_t const * p_api;           ///< Pointer to the API structure for this instance
108 } dac_instance_t;
109 
110 /*******************************************************************************************************************//**
111  * @} (end defgroup DAC_API)
112  **********************************************************************************************************************/
113 
114 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
115 FSP_FOOTER
116 
117 #endif
118