app_iso7816.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_iso7816.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of ISO7816 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_ISO7816 ISO7816
47  * @brief ISO7816 APP module driver.
48  * @{
49  */
50 
51 
52 #ifndef _APP_ISO7816_H_
53 #define _APP_ISO7816_H_
54 
55 #include "grx_hal.h"
56 #include "app_io.h"
57 #include "app_drv_error.h"
58 #include "app_drv_config.h"
59 #include "stdbool.h"
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 #ifdef HAL_ISO7816_MODULE_ENABLED
66 /** @addtogroup APP_ISO7816_DEFINE Defines
67  * @{
68  */
69 
70 /** @defgroup APP_ISO7816_ACTION Action state
71  * @{
72  */
73 #define APP_ISO7816_ACTION_NONE HAL_ISO7816_ACTION_NONE /**< Do Nothing */
74 #define APP_ISO7816_ACTION_OFF HAL_ISO7816_ACTION_OFF /**< Switch Off */
75 #define APP_ISO7816_ACTION_STOPCLK HAL_ISO7816_ACTION_STOPCLK /**< Stop the clock */
76 #define APP_ISO7816_ACTION_ON HAL_ISO7816_ACTION_ON /**< Switch on and receive ATR */
77 #define APP_ISO7816_ACTION_WARMRST HAL_ISO7816_ACTION_WARMRST /**< Trigger warm reset and receive ATR */
78 #define APP_ISO7816_ACTION_RX HAL_ISO7816_ACTION_RX /**< Receive */
79 #define APP_ISO7816_ACTION_TX HAL_ISO7816_ACTION_TX /**< Transmit */
80 #define APP_ISO7816_ACTION_TXRX HAL_ISO7816_ACTION_TXRX /**< Transmit, followed by RX */
81 /** @} */
82 
83 /** @defgroup APP_ISO7816_Interrupt_definition ISO7816 Interrupt Definition
84  * @{
85  */
86 #define APP_ISO7816_INTR_PRESENCE HAL_ISO7816_INTR_PRESENCE /**< Source presence interrupt */
87 #define APP_ISO7816_INTR_STATE_ERR HAL_ISO7816_INTR_STATE_ERR /**< Source state error interrupt */
88 #define APP_ISO7816_INTR_DMA_ERR HAL_ISO7816_INTR_DMA_ERR /**< Source dma error interrupt */
89 #define APP_ISO7816_INTR_RETRY_ERR HAL_ISO7816_INTR_RETRY_ERR /**< Source retry error interrupt */
90 #define APP_ISO7816_INTR_RX_ERR HAL_ISO7816_INTR_RX_ERR /**< Source rx error interrupt */
91 #define APP_ISO7816_INTR_DONE HAL_ISO7816_INTR_DONE /**< Source done error interrupt */
92 /** @} */
93 
94 
95 /** @defgroup APP_ISO7816_CARD_PRESENCE Card Presence Defines
96  * @{
97  */
98 #define APP_ISO7816_CARD_ABSENT HAL_ISO7816_CARD_ABSENT /**< SIM Card is absent */
99 #define APP_ISO7816_CARD_PRESENT HAL_ISO7816_CARD_PRESENT /**< SIM Card is present */
100 /** @} */
101 
102 /** @defgroup APP_ISO7816_IO_STATES IO States Defines
103  * @{
104  */
105 #define APP_ISO7816_IO_STATE_OFF HAL_ISO7816_IO_STATE_OFF /**< Off */
106 #define APP_ISO7816_IO_STATE_IDLE HAL_ISO7816_IO_STATE_IDLE /**< Idle */
107 #define APP_ISO7816_IO_STATE_RX_WAIT HAL_ISO7816_IO_STATE_RX_WAIT /**< Receive Wait */
108 #define APP_ISO7816_IO_STATE_RX HAL_ISO7816_IO_STATE_RX /**< Receive */
109 #define APP_ISO7816_IO_STATE_TX HAL_ISO7816_IO_STATE_TX /**< Transmit */
110 #define APP_ISO7816_IO_STATE_TX_GUARD HAL_ISO7816_IO_STATE_TX_GUARD /**< Transmit Guard */
111 /** @} */
112 
113 /** @defgroup APP_ISO7816_PWR_STATES Power States Defines
114  * @{
115  */
116 #define APP_ISO7816_PWR_STATE_OFF HAL_ISO7816_PWR_STATE_OFF /**< Off */
117 #define APP_ISO7816_PWR_STATE_PWRUP_VCC HAL_ISO7816_PWR_STATE_PWRUP_VCC /**< Power up VCC */
118 #define APP_ISO7816_PWR_STATE_PWRUP_RST HAL_ISO7816_PWR_STATE_PWRUP_RST /**< Power up reset */
119 #define APP_ISO7816_PWR_STATE_PWRDN_RST HAL_ISO7816_PWR_STATE_PWRDN_RST /**< Power Down reset */
120 #define APP_ISO7816_PWR_STATE_PWRDN_VCC HAL_ISO7816_PWR_STATE_PWRDN_VCC /**< Power Down VCC */
121 #define APP_ISO7816_PWR_STATE_STOP_PRE HAL_ISO7816_PWR_STATE_STOP_PRE /**< Preparing Clock Stop */
122 #define APP_ISO7816_PWR_STATE_STOP HAL_ISO7816_PWR_STATE_STOP /**< Clock Stopped */
123 #define APP_ISO7816_PWR_STATE_STOP_POST HAL_ISO7816_PWR_STATE_STOP_POST /**< Exiting Clock Stop */
124 #define APP_ISO7816_PWR_STATE_IDLE HAL_ISO7816_PWR_STATE_IDLE /**< Idle */
125 #define APP_ISO7816_PWR_STATE_RX_TS0 HAL_ISO7816_PWR_STATE_RX_TS0 /**< RX TS Character */
126 #define APP_ISO7816_PWR_STATE_RX_TS1 HAL_ISO7816_PWR_STATE_RX_TS1 /**< RX TS Character */
127 #define APP_ISO7816_PWR_STATE_RX HAL_ISO7816_PWR_STATE_RX /**< Receive */
128 #define APP_ISO7816_PWR_STATE_TX HAL_ISO7816_PWR_STATE_TX /**< Transmit */
129 #define APP_ISO7816_PWR_STATE_TX_RX HAL_ISO7816_PWR_STATE_TX_RX /**< Transmit and Receive */
130 /** @} */
131 
132 /** @} */
133 
134 /** @addtogroup APP_ISO7816_ENUM Enumerations
135  * @{
136  */
137 
138 /**
139  * @brief ISO7816 operating mode Enumerations definition
140  */
141 typedef enum
142 {
143  APP_ISO7816_TYPE_INTERRUPT, /**< Interrupt operation mode. */
144  APP_ISO7816_TYPE_POLLING, /**< Polling operation mode. */
145  APP_ISO7816_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */
146 } app_iso7816_mode_t;
147 
148 /**
149  * @brief ISO7816 event Enumerations definition
150  */
151 typedef enum
152 {
153  APP_ISO7816_EVT_ERROR, /**< Error reported by ISO7816 peripheral. */
154  APP_ISO7816_EVT_ABORT, /**< Error reported by ISO7816 peripheral. */
155  APP_ISO7816_EVT_PRESENCE, /**< Requested RX transfer completed. */
156  APP_ISO7816_EVT_ATR_CPLT, /**< Requested TX transfer completed. */
157  APP_ISO7816_EVT_TX_CPLT, /**< Requested TX transfer completed. */
158  APP_ISO7816_EVT_RX_CPLT, /**< Requested RX transfer completed. */
159  APP_ISO7816_EVT_TX_RX_CPLT, /**< Requested RX transfer completed. */
160 } app_iso7816_evt_type_t;
161 /** @} */
162 
163 /** @addtogroup APP_ISO7816_STRUCTURES Structures
164  * @{
165  */
166 
167 /**
168  * @brief ISO7816 IO configuration Structures
169  */
170 typedef struct
171 {
172  app_io_type_t type; /**< Specifies the type of IO. */
173  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
174  uint32_t pin; /**< Specifies the IO pins to be configured.
175  This parameter can be any value of @ref GR5xxx_pins. */
176  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
177 } app_iso7816_pin_t;
178 
179 /**
180  * @brief ISO7816 pin configure structure definition
181  */
182 typedef struct
183 {
184  app_iso7816_pin_t clk; /**< Set the configuration of ISO7816 clock pin. */
185  app_iso7816_pin_t rst; /**< Set the configuration of ISO7816 reset pin. */
186  app_iso7816_pin_t io; /**< Set the configuration of ISO7816 io pin. */
187  app_iso7816_pin_t presence; /**< Set the configuration of ISO7816 presence pin. */
188 } app_iso7816_pin_cfg_t;
189 
190 /**
191  * @brief ISO7816 event structure definition
192  */
193 typedef struct
194 {
195  app_iso7816_evt_type_t type; /**< Type of event. */
196  union
197  {
198  uint32_t error_code; /**< ISO7816 Error code. */
199  uint16_t size; /**< ISO7816 transmitted/received counter. */
200  } data; /**< ISO7816 union data. */
201 } app_iso7816_evt_t;
202 
203 /** @} */
204 
205 /** @addtogroup APP_ISO7816_TYPEDEFS Type definitions
206  * @{
207  */
208 
209 /**
210  * @brief ISO7816 event callback definition
211  */
212 typedef void (*app_iso7816_evt_handler_t)(app_iso7816_evt_t *p_evt);
213 
214 /** @} */
215 
216 /** @addtogroup APP_ISO7816_ENUM Enumerations
217  * @{
218  */
219 
220 /**@brief App iso7816 state types. */
221 typedef enum
222 {
223  APP_ISO7816_INVALID = 0,
224  APP_ISO7816_ACTIVITY,
225 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
226  APP_ISO7816_SLEEP,
227 #endif
228 } app_iso7816_state_t;
229 
230 /** @} */
231 
232 /** @addtogroup APP_ISO7816_STRUCTURES Structures
233  * @{
234  */
235 /**
236  * @brief ISO7816 device structure definition
237  */
238 typedef struct
239 {
240  app_iso7816_evt_handler_t evt_handler; /**< ISO7816 event callback. */
241  iso7816_handle_t handle; /**< ISO7816 handle Structure. */
242  app_iso7816_mode_t use_mode; /**< ISO7816 operating mode Enumerations. */
243  app_iso7816_pin_cfg_t *p_pin_cfg; /**< ISO7816 pin configure structure. */
244  app_iso7816_state_t iso7816_state; /**< ISO7816 state configure structure. */
245  bool start_flag; /**< ISO7816 start_flage. */
246 }iso7816_env_t;
247 
248 /**
249  * @brief ISO7816 parameters structure definition
250  */
251 typedef struct
252 {
253  app_iso7816_mode_t use_mode; /**< Specifies the operation mode of ISO7816. */
254  app_iso7816_pin_cfg_t pin_cfg; /**< The pin configuration information for the ISO7816. */
255  iso7816_init_t init; /**< ISO7816 communication parameters. */
256  iso7816_env_t iso7816_env; /**< ISO7816 device structure definition. */
257 } app_iso7816_params_t;
258 
259 /** @} */
260 
261 /* Exported functions --------------------------------------------------------*/
262 /** @addtogroup APP_ISO7816_DRIVER_FUNCTIONS Functions
263  * @{
264  */
265 /**
266  ****************************************************************************************
267  * @brief Initialize the APP ISO7816 DRIVER according to the specified parameters
268  * in the app_iso7816_params_t and app_iso7816_evt_handler_t.
269  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
270  * is set, you can't use interrupt mode.
271  *
272  * @param[in] p_params: Pointer to app_iso7816_params_t parameter which contains the
273  * configuration information for the specified ISO7816 module.
274  * @param[in] evt_handler: ISO7816 user callback function.
275  *
276  * @return Result of initialization.
277  ****************************************************************************************
278  */
279 uint16_t app_iso7816_init(app_iso7816_params_t *p_params, app_iso7816_evt_handler_t evt_handler);
280 
281 /**
282  ****************************************************************************************
283  * @brief De-initialize the APP ISO7816 DRIVER peripheral.
284  *
285  * @return Result of De-initialization.
286  ****************************************************************************************
287  */
288 uint16_t app_iso7816_deinit(void);
289 
290 /**
291  ****************************************************************************************
292  * @brief Receive an amount of data in blocking mode.
293  *
294  * @param[in] size: Amount of data to be sent
295  * @param[in] timeout: Timeout duration
296  *
297  * @return Result of operation.
298  ****************************************************************************************
299  */
300 uint16_t app_iso7816_receive_sync(uint16_t size, uint32_t timeout);
301 
302 /**
303  ****************************************************************************************
304  * @brief Receive an amount of data in non-blocking mode with Interrupt/DMA.
305  *
306  * @param[in] size: Amount of data to be sent
307  *
308  * @return Result of operation.
309  ****************************************************************************************
310  */
311 uint16_t app_iso7816_receive_async(uint16_t size);
312 
313 /**
314  ****************************************************************************************
315  * @brief Transmits an amount of data in blocking mode.
316  *
317  * @param[in] size: Amount of data to be sent
318  * @param[in] timeout: Timeout duration
319  *
320  * @return Result of operation.
321  ****************************************************************************************
322  */
323 uint16_t app_iso7816_transmit_sync(uint16_t size, uint32_t timeout);
324 
325 /**
326  ****************************************************************************************
327  * @brief Transmits an amount of data in non-blocking mode with Interrupt/DMA.
328  *
329  * @param[in] size: Amount of data to be sent
330  *
331  * @return Result of operation.
332  ****************************************************************************************
333  */
334 uint16_t app_iso7816_transmit_async(uint16_t size);
335 
336 /**
337  ****************************************************************************************
338  * @brief Transmit and receive in master mode an amount of data in blocking mode.
339  *
340  * @param[in] tx_size: Amount of data to be sent
341  * @param[in] rx_size: Amount of data to be receive
342  * @param[in] timeout: Timeout duration
343  *
344  * @return Result of operation.
345  ****************************************************************************************
346  */
347 uint16_t app_iso7816_transmit_receive_sync(uint16_t tx_size, uint16_t rx_size, uint32_t timeout);
348 
349 /**
350  ****************************************************************************************
351  * @brief Transmit and receive in master mode an amount of data in non-blocking mode.
352  *
353  * @param[in] tx_size: Amount of data to be sent
354  * @param[in] rx_size: Amount of data to be receive
355  *
356  * @return Result of operation.
357  ****************************************************************************************
358  */
359 uint16_t app_iso7816_transmit_receive_async(uint16_t tx_size, uint16_t rx_size);
360 
361 /**
362  * @brief Request ISO7816 to go to the next action.
363  * @param action: This parameter can be one of the following values:
364  * @arg @ref APP_ISO7816_ACTION_NONE
365  * @arg @ref APP_ISO7816_ACTION_OFF
366  * @arg @ref APP_ISO7816_ACTION_STOPCLK
367  * @arg @ref APP_ISO7816_ACTION_ON
368  * @arg @ref APP_ISO7816_ACTION_WARMRST
369  * @arg @ref APP_ISO7816_ACTION_RX
370  * @arg @ref APP_ISO7816_ACTION_TX
371  * @arg @ref APP_ISO7816_ACTION_TXRX
372  *
373  * @return Result of operation.
374  */
375 uint16_t app_iso7816_set_action(uint32_t action);
376 
377 /**
378  * @brief Get ISO7816 Power States.
379  * @return Returned value can be one of the following values:
380  * @arg @ref APP_ISO7816_PWR_STATE_OFF
381  * @arg @ref APP_ISO7816_PWR_STATE_PWRUP_VCC
382  * @arg @ref APP_ISO7816_PWR_STATE_PWRUP_RST
383  * @arg @ref APP_ISO7816_PWR_STATE_PWRDN_RST
384  * @arg @ref APP_ISO7816_PWR_STATE_PWRDN_VCC
385  * @arg @ref APP_ISO7816_PWR_STATE_STOP_PRE
386  * @arg @ref APP_ISO7816_PWR_STATE_STOP
387  * @arg @ref APP_ISO7816_PWR_STATE_STOP_POST
388  * @arg @ref APP_ISO7816_PWR_STATE_IDLE
389  * @arg @ref APP_ISO7816_PWR_STATE_RX_TS0
390  * @arg @ref APP_ISO7816_PWR_STATE_RX_TS1
391  * @arg @ref APP_ISO7816_PWR_STATE_RX
392  * @arg @ref APP_ISO7816_PWR_STATE_TX
393  * @arg @ref APP_ISO7816_PWR_STATE_TX_RX
394  */
395 uint32_t app_iso7816_get_power_states(void);
396 
397 /**
398  * @brief Set divide ISO7816 clock.
399  * @note Divide SIM clock by this value+1 to define ETU length. The reset value
400  * is the one, needed for theATR.
401  * @param divide This parameter should range between 0x0 and 0x3FF.
402  *
403  * @return Result of operation.
404  */
405 uint16_t app_iso7816_set_etudiv(uint32_t divide);
406 
407 /**
408  ****************************************************************************************
409  * @brief Return the ISO7816 handle.
410  *
411  * @return Pointer to the specified ID's ISO7816 handle.
412  ****************************************************************************************
413  */
414 iso7816_handle_t *app_iso7816_get_handle(void);
415 
416 /** @} */
417 
418 #endif
419 
420 #ifdef __cplusplus
421 }
422 #endif
423 
424 #endif /* _APP_ISO7816_H_ */
425 
426 /** @} */
427 /** @} */
428 /** @} */
429 
_iso7816_handle_t
ISO7816 handle Structure definition.
Definition: gr55xx_hal_iso7816.h:121
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:183
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:147
app_io.h
Header file containing functions prototypes of GPIO app library.
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:255
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
iso7816_init_t
ISO7816 init structure definition.
Definition: gr55xx_hal_iso7816.h:102