app_adc.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_adc.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of ADC app library.
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  ****************************************************************************************
36  */
37 
38 /** @addtogroup PERIPHERAL Peripheral Driver
39  * @{
40  */
41 
42 /** @addtogroup APP_DRIVER APP DRIVER
43  * @{
44  */
45 
46 /** @defgroup APP_ADC ADC
47  * @brief ADC APP module driver.
48  * @{
49  */
50 
51 
52 #ifndef _APP_ADC_H_
53 #define _APP_ADC_H_
54 
55 #include "grx_hal.h"
56 #include "app_io.h"
57 #include "app_dma.h"
58 #include "app_drv_error.h"
59 #include "app_drv_config.h"
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 #ifdef HAL_ADC_MODULE_ENABLED
66 
67 /** @addtogroup APP_ADC_ENUM Enumerations
68  * @{
69  */
70 
71 /**
72  * @brief ADC event Enumerations definition
73  */
74 typedef enum
75 {
76  APP_ADC_EVT_CONV_CPLT, /**< Conversion completed by ADC peripheral. */
78 
79 /** @} */
80 
81 
82 /** @addtogroup APP_ADC_STRUCT Structures
83  * @{
84  */
85 
86 /**
87  * @brief ADC pins Structures
88  */
89 typedef struct
90 {
91  app_io_type_t type; /**< Specifies the type of ADC IO. */
92  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
93  uint32_t pin; /**< Specifies the IO pins to be configured.
94  This parameter can be any value of @ref GR5xxx_pins. */
96 
97 /**
98  * @brief ADC pins config Structures
99  */
100 typedef struct
101 {
102  app_adc_pin_t channel_p; /**< Set the configuration of ADC pin. */
103  app_adc_pin_t channel_n; /**< Set the configuration of ADC pin. */
104  app_adc_pin_t extern_ref; /**< Set the configuration of extern reference pin. */
106 
107 /**
108  * @brief ADC DMA configuration Structures
109  */
110 typedef struct
111 {
112  dma_regs_t * dma_instance; /**< Specifies the dma instance of ADC. */
113  dma_channel_t dma_channel; /**< Specifies the dma channel of ADC. */
115 
116 /**@brief App adc state types. */
117 typedef enum
118 {
121 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
122  APP_ADC_SLEEP,
123 #endif
125 
126 /**@brief App adc dma state types. */
127 typedef enum
128 {
132 
133 /**
134  * @brief ADC event structure definition
135  */
136 typedef struct
137 {
138  app_adc_evt_type_t type; /**< Type of event. */
139 } app_adc_evt_t;
140 
141 /**
142  * @brief ADC event callback definition
143  */
144 typedef void (*app_adc_evt_handler_t)(app_adc_evt_t *p_evt);
145 
146 #if (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR551X)
147 /**
148  * @brief ADC sample-node definition
149  */
150 typedef struct link_node
151 {
152  uint32_t channel; /**< Which channel to be sample; This parameter can be any value of ADC_INPUT_SOURCE:ADC_INPUT_SRC_IO0~ADC_INPUT_SRC_REF*/
153  uint16_t *p_buf; /**< Buffer pointer of current channel sample codes. Note:pointer must be 4-byte aligned as it is filled in datas by DMA */
154  uint32_t len; /**< Sample len codes on current channel. */
155  struct link_node *next; /**< Point to the next sample node. */
157 #endif
158 
159 /**
160  * @brief ADC device structure definition
161  */
162 typedef struct
163 {
164  app_adc_evt_handler_t evt_handler; /**< ADC event callback definition. */
165  adc_handle_t handle; /**< ADC handle definition. */
166  dma_id_t dma_id; /**< DMA id definition . */
167  app_adc_state_t adc_state; /**< ADC state types. */
168  app_adc_dma_state_t adc_dma_state; /**< ADC dma state types. */
169 #if (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR551X)
170  app_adc_sample_node_t *p_current_sample_node; /**< ADC sample-node definition. */
171  uint32_t multi_channel; /**< multi channel definition. */
172 #endif
173 } adc_env_t;
174 
175 /**
176  * @brief ADC parameters structure definition
177  */
178 typedef struct
179 {
180  app_adc_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified ADC module. */
181  app_adc_dma_cfg_t dma_cfg; /**< ADC DMA configuration. */
182  adc_init_t init; /**< ADC configuration parameters. */
183  adc_env_t adc_env; /**< ADC device structure definition. */
185 
186 /** @} */
187 
188 /* Exported functions --------------------------------------------------------*/
189 /** @addtogroup APP_ADC_DRIVER_FUNCTIONS Functions
190  * @{
191  */
192 
193 /**
194  ****************************************************************************************
195  * @brief Initialize the APP ADC DRIVER according to the specified parameters
196  * in the app_adc_params_t and app_adc_evt_handler_t.
197  * @note If DMA mode is set, you can use blocking mode. Conversely, if blocking mode
198  * is set, you can't use DMA mode.
199  *
200  * @param[in] p_params: Pointer to app_adc_params_t parameter which contains the
201  * configuration information for the specified ADC module.
202  * @param[in] evt_handler: ADC user callback function.
203  *
204  * @return Result of initialization.
205  ****************************************************************************************
206  */
207 uint16_t app_adc_init(app_adc_params_t *p_params, app_adc_evt_handler_t evt_handler);
208 
209 /**
210  ****************************************************************************************
211  * @brief De-initialize the APP ADC DRIVER peripheral.
212  *
213  * @return Result of De-initialization.
214  ****************************************************************************************
215  */
216 uint16_t app_adc_deinit(void);
217 
218 /**
219  ****************************************************************************************
220  * @brief Polling for conversion.
221  *
222  * @param[in] p_data: Pointer to data buffer which to storage ADC conversion results.
223  * @param[in] length: Length of data buffer.
224  * @param[in] timeout : Timeout duration
225  *
226  * @return Result of operation.
227  ****************************************************************************************
228  */
229 uint16_t app_adc_conversion_sync(uint16_t *p_data, uint32_t length, uint32_t timeout);
230 
231 /**
232  ****************************************************************************************
233  * @brief DMA for conversion.
234  *
235  * @param[in] p_data: Pointer to data buffer which to storage ADC conversion results.
236  * @param[in] length: Length of data buffer, ranging between 0 and 4095.
237  *
238  * @return Result of operation.
239  ****************************************************************************************
240  */
241 uint16_t app_adc_conversion_async(uint16_t *p_data, uint32_t length);
242 
243 /**
244  ****************************************************************************************
245  * @brief Convert the ADC conversion results to a voltage value(internal reference).
246  *
247  * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
248  * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
249  * @param[in] buflen: Length of data buffer.
250  *
251  * @return Result of operation.
252  ****************************************************************************************
253  */
254 uint16_t app_adc_voltage_intern(uint16_t *inbuf, double *outbuf, uint32_t buflen);
255 
256 /**
257  ****************************************************************************************
258  * @brief Convert the ADC conversion results to a voltage value(external reference).
259  *
260  * @param[in] ref: slope of ADC.
261  * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
262  * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
263  * @param[in] buflen: Length of data buffer.
264  *
265  * @return Result of operation.
266  ****************************************************************************************
267  */
268 uint16_t app_adc_voltage_extern(double ref, uint16_t *inbuf, double *outbuf, uint32_t buflen);
269 
270 #if (APP_DRIVER_CHIP_TYPE != APP_DRIVER_GR551X)
271 /**
272  ****************************************************************************************
273  * @brief Convert the ADC conversion results to temperature value.
274  *
275  * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
276  * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
277  * @param[in] buflen: Length of data buffer.
278  *
279  * @return Result of operation.
280  ****************************************************************************************
281  */
282 uint16_t app_adc_temperature_conv(uint16_t *inbuf, double *outbuf, uint32_t buflen);
283 
284 /**
285  ****************************************************************************************
286  * @brief Convert the ADC conversion results to battery value.
287  *
288  * @param[in] inbuf: Pointer to data buffer which storage ADC codes.
289  * @param[out] outbuf: Pointer to data buffer which to storage conversion results.
290  * @param[in] buflen: Length of data buffer.
291  *
292  * @return Result of operation.
293  ****************************************************************************************
294  */
295 uint16_t app_adc_vbat_conv(uint16_t *inbuf, double *outbuf, uint32_t buflen);
296 #endif
297 
298 /**
299  ****************************************************************************************
300  * @brief Return the ADC handle.
301  *
302  * @return Pointer to the ADC handle.
303  ****************************************************************************************
304  */
306 
307 #if (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR551X)
308 /**
309  ****************************************************************************************
310  * @brief DMA for multi channels conversion; evt_handler in app_adc_init will callback when all channels finish.
311  *
312  * @param[in] p_begin_node: Pointer to the multi sample channels list node.
313  * @param[in] total_nodes: total sample channels.
314  *
315  * @return Result of operation.
316  ****************************************************************************************
317  */
318 uint16_t app_adc_multi_channel_conversion_async(app_adc_sample_node_t *p_begin_node, uint32_t total_nodes);
319 #endif
320 
321 /** @} */
322 
323 #endif
324 
325 #ifdef __cplusplus
326 }
327 #endif
328 
329 #endif
330 
331 /** @} */
332 
333 /** @} */
334 
335 /** @} */
336 
app_adc_voltage_extern
uint16_t app_adc_voltage_extern(double ref, uint16_t *inbuf, double *outbuf, uint32_t buflen)
Convert the ADC conversion results to a voltage value(external reference).
APP_ADC_EVT_CONV_CPLT
@ APP_ADC_EVT_CONV_CPLT
Definition: app_adc.h:76
app_adc_pin_t::mux
app_io_mux_t mux
Definition: app_adc.h:92
app_adc_sample_node_t
struct link_node app_adc_sample_node_t
ADC sample-node definition.
app_adc_dma_cfg_t::dma_channel
dma_channel_t dma_channel
Definition: app_adc.h:113
app_adc_dma_state_t
app_adc_dma_state_t
App adc dma state types.
Definition: app_adc.h:128
app_adc_state_t
app_adc_state_t
App adc state types.
Definition: app_adc.h:118
app_adc_multi_channel_conversion_async
uint16_t app_adc_multi_channel_conversion_async(app_adc_sample_node_t *p_begin_node, uint32_t total_nodes)
DMA for multi channels conversion; evt_handler in app_adc_init will callback when all channels finish...
app_adc_params_t::adc_env
adc_env_t adc_env
Definition: app_adc.h:183
adc_env_t::adc_state
app_adc_state_t adc_state
Definition: app_adc.h:167
adc_env_t
ADC device structure definition.
Definition: app_adc.h:163
app_adc_evt_t::type
app_adc_evt_type_t type
Definition: app_adc.h:138
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:145
adc_env_t::adc_dma_state
app_adc_dma_state_t adc_dma_state
Definition: app_adc.h:168
app_adc_params_t
ADC parameters structure definition.
Definition: app_adc.h:179
app_adc_pin_t::pin
uint32_t pin
Definition: app_adc.h:93
app_adc_dma_cfg_t
ADC DMA configuration Structures.
Definition: app_adc.h:111
app_adc_params_t::pin_cfg
app_adc_pin_cfg_t pin_cfg
Definition: app_adc.h:180
APP_ADC_INVALID
@ APP_ADC_INVALID
Definition: app_adc.h:119
_ll_adc_init
LL ADC init Structure definition.
Definition: gr55xx_ll_adc.h:77
app_io.h
Header file containing functions prototypes of GPIO app library.
app_adc_evt_t
ADC event structure definition.
Definition: app_adc.h:137
app_adc_evt_type_t
app_adc_evt_type_t
ADC event Enumerations definition.
Definition: app_adc.h:75
app_adc_voltage_intern
uint16_t app_adc_voltage_intern(uint16_t *inbuf, double *outbuf, uint32_t buflen)
Convert the ADC conversion results to a voltage value(internal reference).
adc_env_t::evt_handler
app_adc_evt_handler_t evt_handler
Definition: app_adc.h:164
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_adc_evt_handler_t
void(* app_adc_evt_handler_t)(app_adc_evt_t *p_evt)
ADC event callback definition.
Definition: app_adc.h:144
app_adc_conversion_sync
uint16_t app_adc_conversion_sync(uint16_t *p_data, uint32_t length, uint32_t timeout)
Polling for conversion.
_adc_handle
ADC handle Structure definition.
Definition: gr55xx_hal_adc.h:111
app_adc_pin_t::type
app_io_type_t type
Definition: app_adc.h:91
app_adc_pin_cfg_t::extern_ref
app_adc_pin_t extern_ref
Definition: app_adc.h:104
app_adc_params_t::init
adc_init_t init
Definition: app_adc.h:182
app_dma.h
Header file containing functions prototypes of DMA app library.
app_adc_deinit
uint16_t app_adc_deinit(void)
De-initialize the APP ADC DRIVER peripheral.
APP_ADC_DMA_INVALID
@ APP_ADC_DMA_INVALID
Definition: app_adc.h:129
app_adc_pin_cfg_t::channel_n
app_adc_pin_t channel_n
Definition: app_adc.h:103
app_adc_get_handle
adc_handle_t * app_adc_get_handle(void)
Return the ADC handle.
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:253
adc_env_t::handle
adc_handle_t handle
Definition: app_adc.h:165
adc_env_t::multi_channel
uint32_t multi_channel
Definition: app_adc.h:171
APP_ADC_ACTIVITY
@ APP_ADC_ACTIVITY
Definition: app_adc.h:120
app_adc_conversion_async
uint16_t app_adc_conversion_async(uint16_t *p_data, uint32_t length)
DMA for conversion.
app_adc_pin_cfg_t::channel_p
app_adc_pin_t channel_p
Definition: app_adc.h:102
adc_env_t::dma_id
dma_id_t dma_id
Definition: app_adc.h:166
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
APP_ADC_DMA_ACTIVITY
@ APP_ADC_DMA_ACTIVITY
Definition: app_adc.h:130
app_adc_dma_cfg_t::dma_instance
dma_regs_t * dma_instance
Definition: app_adc.h:112
dma_id_t
int16_t dma_id_t
DMA id definition.
Definition: app_dma.h:98
app_adc_pin_cfg_t
ADC pins config Structures.
Definition: app_adc.h:101
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
adc_env_t::p_current_sample_node
app_adc_sample_node_t * p_current_sample_node
Definition: app_adc.h:170
app_adc_params_t::dma_cfg
app_adc_dma_cfg_t dma_cfg
Definition: app_adc.h:181
app_adc_pin_t
ADC pins Structures.
Definition: app_adc.h:90
app_adc_init
uint16_t app_adc_init(app_adc_params_t *p_params, app_adc_evt_handler_t evt_handler)
Initialize the APP ADC DRIVER according to the specified parameters in the app_adc_params_t and app_a...