Commit | Line | Data |
---|---|---|
1e494cf4 JB |
1 | /* |
2 | * Copyright (C) 2011, 2012 The Android Open Source Project | |
3 | * | |
4 | * Licensed under the Apache License, Version 2.0 (the "License"); | |
5 | * you may not use this file except in compliance with the License. | |
6 | * You may obtain a copy of the License at | |
7 | * | |
8 | * http://www.apache.org/licenses/LICENSE-2.0 | |
9 | * | |
10 | * Unless required by applicable law or agreed to in writing, software | |
11 | * distributed under the License is distributed on an "AS IS" BASIS, | |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
13 | * See the License for the specific language governing permissions and | |
14 | * limitations under the License. | |
15 | */ | |
16 | ||
17 | #ifndef ANDROID_NFC_HAL_INTERFACE_H | |
18 | #define ANDROID_NFC_HAL_INTERFACE_H | |
19 | ||
20 | #include <stdint.h> | |
21 | #include <strings.h> | |
22 | #include <sys/cdefs.h> | |
23 | #include <sys/types.h> | |
24 | ||
25 | #include <hardware/hardware.h> | |
26 | ||
27 | __BEGIN_DECLS | |
28 | ||
29 | ||
30 | /* NFC device HAL for NCI-based NFC controllers. | |
31 | * | |
32 | * This HAL allows NCI silicon vendors to make use | |
33 | * of the core NCI stack in Android for their own silicon. | |
34 | * | |
35 | * The responibilities of the NCI HAL implementation | |
36 | * are as follows: | |
37 | * | |
38 | * - Implement the transport to the NFC controller | |
39 | * - Implement each of the HAL methods specified below as applicable to their silicon | |
40 | * - Pass up received NCI messages from the controller to the stack | |
41 | * | |
42 | * A simplified timeline of NCI HAL method calls: | |
43 | * 1) Core NCI stack calls open() | |
44 | * 2) Core NCI stack executes CORE_RESET and CORE_INIT through calls to write() | |
45 | * 3) Core NCI stack calls core_initialized() to allow HAL to do post-init configuration | |
46 | * 4) Core NCI stack calls pre_discover() to allow HAL to prepare for RF discovery | |
47 | * 5) Core NCI stack starts discovery through calls to write() | |
48 | * 6) Core NCI stack stops discovery through calls to write() (e.g. screen turns off) | |
49 | * 7) Core NCI stack calls pre_discover() to prepare for RF discovery (e.g. screen turned back on) | |
50 | * 8) Core NCI stack starts discovery through calls to write() | |
51 | * ... | |
52 | * ... | |
53 | * 9) Core NCI stack calls close() | |
54 | */ | |
55 | #define NFC_NCI_HARDWARE_MODULE_ID "nfc_nci" | |
56 | #define NFC_NCI_CONTROLLER "nci" | |
57 | ||
58 | /* | |
59 | * nfc_nci_module_t should contain module-specific parameters | |
60 | */ | |
61 | typedef struct nfc_nci_module_t { | |
62 | struct hw_module_t common; | |
63 | } nfc_nci_module_t; | |
64 | ||
65 | /* | |
66 | * HAL events that can be passed back to the stack | |
67 | */ | |
68 | typedef uint8_t nfc_event_t; | |
69 | ||
70 | enum { | |
71 | HAL_NFC_OPEN_CPLT_EVT = 0x00, | |
72 | HAL_NFC_CLOSE_CPLT_EVT = 0x01, | |
73 | HAL_NFC_POST_INIT_CPLT_EVT = 0x02, | |
74 | HAL_NFC_PRE_DISCOVER_CPLT_EVT = 0x03, | |
75 | HAL_NFC_REQUEST_CONTROL_EVT = 0x04, | |
76 | HAL_NFC_RELEASE_CONTROL_EVT = 0x05, | |
77 | HAL_NFC_ERROR_EVT = 0x06 | |
78 | }; | |
79 | ||
80 | /* | |
81 | * Allowed status return values for each of the HAL methods | |
82 | */ | |
83 | typedef uint8_t nfc_status_t; | |
84 | ||
85 | enum { | |
86 | HAL_NFC_STATUS_OK = 0x00, | |
87 | HAL_NFC_STATUS_FAILED = 0x01, | |
88 | HAL_NFC_STATUS_ERR_TRANSPORT = 0x02, | |
89 | HAL_NFC_STATUS_ERR_CMD_TIMEOUT = 0x03, | |
90 | HAL_NFC_STATUS_REFUSED = 0x04 | |
91 | }; | |
92 | ||
93 | /* | |
94 | * The callback passed in from the NFC stack that the HAL | |
95 | * can use to pass events back to the stack. | |
96 | */ | |
97 | typedef void (nfc_stack_callback_t) (nfc_event_t event, nfc_status_t event_status); | |
98 | ||
99 | /* | |
100 | * The callback passed in from the NFC stack that the HAL | |
101 | * can use to pass incomming data to the stack. | |
102 | */ | |
103 | typedef void (nfc_stack_data_callback_t) (uint16_t data_len, uint8_t* p_data); | |
104 | ||
105 | /* nfc_nci_device_t starts with a hw_device_t struct, | |
106 | * followed by device-specific methods and members. | |
107 | * | |
108 | * All methods in the NCI HAL are asynchronous. | |
109 | */ | |
110 | typedef struct nfc_nci_device { | |
111 | struct hw_device_t common; | |
112 | /* | |
113 | * (*open)() Opens the NFC controller device and performs initialization. | |
114 | * This may include patch download and other vendor-specific initialization. | |
115 | * | |
116 | * If open completes successfully, the controller should be ready to perform | |
117 | * NCI initialization - ie accept CORE_RESET and subsequent commands through | |
118 | * the write() call. | |
119 | * | |
120 | * If open() returns 0, the NCI stack will wait for a HAL_NFC_OPEN_CPLT_EVT | |
121 | * before continuing. | |
122 | * | |
123 | * If open() returns any other value, the NCI stack will stop. | |
124 | * | |
125 | */ | |
126 | int (*open)(const struct nfc_nci_device *p_dev, nfc_stack_callback_t *p_cback, | |
127 | nfc_stack_data_callback_t *p_data_cback); | |
128 | ||
129 | /* | |
130 | * (*write)() Performs an NCI write. | |
131 | * | |
132 | * This method may queue writes and return immediately. The only | |
133 | * requirement is that the writes are executed in order. | |
134 | */ | |
135 | int (*write)(const struct nfc_nci_device *p_dev, uint16_t data_len, const uint8_t *p_data); | |
136 | ||
137 | /* | |
138 | * (*core_initialized)() is called after the CORE_INIT_RSP is received from the NFCC. | |
139 | * At this time, the HAL can do any chip-specific configuration. | |
140 | * | |
141 | * If core_initialized() returns 0, the NCI stack will wait for a HAL_NFC_POST_INIT_CPLT_EVT | |
142 | * before continuing. | |
143 | * | |
144 | * If core_initialized() returns any other value, the NCI stack will continue | |
145 | * immediately. | |
146 | */ | |
147 | int (*core_initialized)(const struct nfc_nci_device *p_dev, uint8_t* p_core_init_rsp_params); | |
148 | ||
149 | /* | |
150 | * (*pre_discover)() Is called every time before starting RF discovery. | |
151 | * It is a good place to do vendor-specific configuration that must be | |
152 | * performed every time RF discovery is about to be started. | |
153 | * | |
154 | * If pre_discover() returns 0, the NCI stack will wait for a HAL_NFC_PRE_DISCOVER_CPLT_EVT | |
155 | * before continuing. | |
156 | * | |
157 | * If pre_discover() returns any other value, the NCI stack will start | |
158 | * RF discovery immediately. | |
159 | */ | |
160 | int (*pre_discover)(const struct nfc_nci_device *p_dev); | |
161 | ||
162 | /* | |
163 | * (*close)() Closed the NFC controller. Should free all resources. | |
164 | */ | |
165 | int (*close)(const struct nfc_nci_device *p_dev); | |
166 | ||
167 | /* | |
168 | * (*control_granted)() Grant HAL the exclusive control to send NCI commands. | |
169 | * Called in response to HAL_REQUEST_CONTROL_EVT. | |
170 | * Must only be called when there are no NCI commands pending. | |
171 | * HAL_RELEASE_CONTROL_EVT will notify when HAL no longer needs exclusive control. | |
172 | */ | |
173 | int (*control_granted)(const struct nfc_nci_device *p_dev); | |
174 | ||
175 | /* | |
176 | * (*power_cycle)() Restart controller by power cyle; | |
177 | * HAL_OPEN_CPLT_EVT will notify when operation is complete. | |
178 | */ | |
179 | int (*power_cycle)(const struct nfc_nci_device *p_dev); | |
180 | } nfc_nci_device_t; | |
181 | ||
182 | /* | |
183 | * Convenience methods that the NFC stack can use to open | |
184 | * and close an NCI device | |
185 | */ | |
186 | static inline int nfc_nci_open(const struct hw_module_t* module, | |
187 | nfc_nci_device_t** dev) { | |
188 | return module->methods->open(module, NFC_NCI_CONTROLLER, | |
189 | (struct hw_device_t**) dev); | |
190 | } | |
191 | ||
192 | static inline int nfc_nci_close(nfc_nci_device_t* dev) { | |
193 | return dev->common.close(&dev->common); | |
194 | } | |
195 | /* | |
196 | * End NFC NCI HAL | |
197 | */ | |
198 | ||
199 | /* | |
200 | * This is a limited NFC HAL for NXP PN544-based devices. | |
201 | * This HAL as Android is moving to | |
202 | * an NCI-based NFC stack. | |
203 | * | |
204 | * All NCI-based NFC controllers should use the NFC-NCI | |
205 | * HAL instead. | |
206 | * Begin PN544 specific HAL | |
207 | */ | |
208 | #define NFC_HARDWARE_MODULE_ID "nfc" | |
209 | ||
210 | #define NFC_PN544_CONTROLLER "pn544" | |
211 | ||
212 | typedef struct nfc_module_t { | |
213 | struct hw_module_t common; | |
214 | } nfc_module_t; | |
215 | ||
216 | /* | |
217 | * PN544 linktypes. | |
218 | * UART | |
219 | * I2C | |
220 | * USB (uses UART DAL) | |
221 | */ | |
222 | typedef enum { | |
223 | PN544_LINK_TYPE_UART, | |
224 | PN544_LINK_TYPE_I2C, | |
225 | PN544_LINK_TYPE_USB, | |
226 | PN544_LINK_TYPE_INVALID, | |
227 | } nfc_pn544_linktype; | |
228 | ||
229 | typedef struct { | |
230 | struct hw_device_t common; | |
231 | ||
232 | /* The number of EEPROM registers to write */ | |
233 | uint32_t num_eeprom_settings; | |
234 | ||
235 | /* The actual EEPROM settings | |
236 | * For PN544, each EEPROM setting is a 4-byte entry, | |
237 | * of the format [0x00, addr_msb, addr_lsb, value]. | |
238 | */ | |
239 | uint8_t* eeprom_settings; | |
240 | ||
241 | /* The link type to which the PN544 is connected */ | |
242 | nfc_pn544_linktype linktype; | |
243 | ||
244 | /* The device node to which the PN544 is connected */ | |
245 | const char* device_node; | |
246 | ||
247 | /* On Crespo we had an I2C issue that would cause us to sometimes read | |
248 | * the I2C slave address (0x57) over the bus. libnfc contains | |
249 | * a hack to ignore this byte and try to read the length byte | |
250 | * again. | |
251 | * Set to 0 to disable the workaround, 1 to enable it. | |
252 | */ | |
253 | uint8_t enable_i2c_workaround; | |
254 | /* I2C slave address. Multiple I2C addresses are | |
255 | * possible for PN544 module. Configure address according to | |
256 | * board design. | |
257 | */ | |
258 | uint8_t i2c_device_address; | |
259 | } nfc_pn544_device_t; | |
260 | ||
261 | static inline int nfc_pn544_open(const struct hw_module_t* module, | |
262 | nfc_pn544_device_t** dev) { | |
263 | return module->methods->open(module, NFC_PN544_CONTROLLER, | |
264 | (struct hw_device_t**) dev); | |
265 | } | |
266 | ||
267 | static inline int nfc_pn544_close(nfc_pn544_device_t* dev) { | |
268 | return dev->common.close(&dev->common); | |
269 | } | |
270 | /* | |
271 | * End PN544 specific HAL | |
272 | */ | |
273 | ||
274 | __END_DECLS | |
275 | ||
276 | #endif // ANDROID_NFC_HAL_INTERFACE_H |