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_BCM2079X_HARDWARE_MODULE_ID "nfc_nci.bcm2079x"
57 #define NFC_NCI_CONTROLLER "nci"
58
59 /*
60 * nfc_nci_module_t should contain module-specific parameters
61 */
62 typedef struct nfc_nci_module_t {
63 /**
64 * Common methods of the NFC NCI module. This *must* be the first member of
65 * nfc_nci_module_t as users of this structure will cast a hw_module_t to
66 * nfc_nci_module_t pointer in contexts where it's known the hw_module_t references a
67 * nfc_nci_module_t.
68 */
69 struct hw_module_t common;
70 } nfc_nci_module_t;
71
72 /*
73 * HAL events that can be passed back to the stack
74 */
75 typedef uint8_t nfc_event_t;
76
77 enum {
78 HAL_NFC_OPEN_CPLT_EVT = 0x00,
79 HAL_NFC_CLOSE_CPLT_EVT = 0x01,
80 HAL_NFC_POST_INIT_CPLT_EVT = 0x02,
81 HAL_NFC_PRE_DISCOVER_CPLT_EVT = 0x03,
82 HAL_NFC_REQUEST_CONTROL_EVT = 0x04,
83 HAL_NFC_RELEASE_CONTROL_EVT = 0x05,
84 HAL_NFC_ERROR_EVT = 0x06
85 };
86
87 /*
88 * Allowed status return values for each of the HAL methods
89 */
90 typedef uint8_t nfc_status_t;
91
92 enum {
93 HAL_NFC_STATUS_OK = 0x00,
94 HAL_NFC_STATUS_FAILED = 0x01,
95 HAL_NFC_STATUS_ERR_TRANSPORT = 0x02,
96 HAL_NFC_STATUS_ERR_CMD_TIMEOUT = 0x03,
97 HAL_NFC_STATUS_REFUSED = 0x04
98 };
99
100 /*
101 * The callback passed in from the NFC stack that the HAL
102 * can use to pass events back to the stack.
103 */
104 typedef void (nfc_stack_callback_t) (nfc_event_t event, nfc_status_t event_status);
105
106 /*
107 * The callback passed in from the NFC stack that the HAL
108 * can use to pass incomming data to the stack.
109 */
110 typedef void (nfc_stack_data_callback_t) (uint16_t data_len, uint8_t* p_data);
111
112 /* nfc_nci_device_t starts with a hw_device_t struct,
113 * followed by device-specific methods and members.
114 *
115 * All methods in the NCI HAL are asynchronous.
116 */
117 typedef struct nfc_nci_device {
118 /**
119 * Common methods of the NFC NCI device. This *must* be the first member of
120 * nfc_nci_device_t as users of this structure will cast a hw_device_t to
121 * nfc_nci_device_t pointer in contexts where it's known the hw_device_t references a
122 * nfc_nci_device_t.
123 */
124 struct hw_device_t common;
125 /*
126 * (*open)() Opens the NFC controller device and performs initialization.
127 * This may include patch download and other vendor-specific initialization.
128 *
129 * If open completes successfully, the controller should be ready to perform
130 * NCI initialization - ie accept CORE_RESET and subsequent commands through
131 * the write() call.
132 *
133 * If open() returns 0, the NCI stack will wait for a HAL_NFC_OPEN_CPLT_EVT
134 * before continuing.
135 *
136 * If open() returns any other value, the NCI stack will stop.
137 *
138 */
139 int (*open)(const struct nfc_nci_device *p_dev, nfc_stack_callback_t *p_cback,
140 nfc_stack_data_callback_t *p_data_cback);
141
142 /*
143 * (*write)() Performs an NCI write.
144 *
145 * This method may queue writes and return immediately. The only
146 * requirement is that the writes are executed in order.
147 */
148 int (*write)(const struct nfc_nci_device *p_dev, uint16_t data_len, const uint8_t *p_data);
149
150 /*
151 * (*core_initialized)() is called after the CORE_INIT_RSP is received from the NFCC.
152 * At this time, the HAL can do any chip-specific configuration.
153 *
154 * If core_initialized() returns 0, the NCI stack will wait for a HAL_NFC_POST_INIT_CPLT_EVT
155 * before continuing.
156 *
157 * If core_initialized() returns any other value, the NCI stack will continue
158 * immediately.
159 */
160 int (*core_initialized)(const struct nfc_nci_device *p_dev, uint8_t* p_core_init_rsp_params);
161
162 /*
163 * (*pre_discover)() Is called every time before starting RF discovery.
164 * It is a good place to do vendor-specific configuration that must be
165 * performed every time RF discovery is about to be started.
166 *
167 * If pre_discover() returns 0, the NCI stack will wait for a HAL_NFC_PRE_DISCOVER_CPLT_EVT
168 * before continuing.
169 *
170 * If pre_discover() returns any other value, the NCI stack will start
171 * RF discovery immediately.
172 */
173 int (*pre_discover)(const struct nfc_nci_device *p_dev);
174
175 /*
176 * (*close)() Closed the NFC controller. Should free all resources.
177 */
178 int (*close)(const struct nfc_nci_device *p_dev);
179
180 /*
181 * (*control_granted)() Grant HAL the exclusive control to send NCI commands.
182 * Called in response to HAL_REQUEST_CONTROL_EVT.
183 * Must only be called when there are no NCI commands pending.
184 * HAL_RELEASE_CONTROL_EVT will notify when HAL no longer needs exclusive control.
185 */
186 int (*control_granted)(const struct nfc_nci_device *p_dev);
187
188 /*
189 * (*power_cycle)() Restart controller by power cyle;
190 * HAL_OPEN_CPLT_EVT will notify when operation is complete.
191 */
192 int (*power_cycle)(const struct nfc_nci_device *p_dev);
193 } nfc_nci_device_t;
194
195 /*
196 * Convenience methods that the NFC stack can use to open
197 * and close an NCI device
198 */
nfc_nci_open(const struct hw_module_t * module,nfc_nci_device_t ** dev)199 static inline int nfc_nci_open(const struct hw_module_t* module,
200 nfc_nci_device_t** dev) {
201 return module->methods->open(module, NFC_NCI_CONTROLLER,
202 (struct hw_device_t**) dev);
203 }
204
nfc_nci_close(nfc_nci_device_t * dev)205 static inline int nfc_nci_close(nfc_nci_device_t* dev) {
206 return dev->common.close(&dev->common);
207 }
208 /*
209 * End NFC NCI HAL
210 */
211
212 /*
213 * This is a limited NFC HAL for NXP PN544-based devices.
214 * This HAL as Android is moving to
215 * an NCI-based NFC stack.
216 *
217 * All NCI-based NFC controllers should use the NFC-NCI
218 * HAL instead.
219 * Begin PN544 specific HAL
220 */
221 #define NFC_HARDWARE_MODULE_ID "nfc"
222
223 #define NFC_PN544_CONTROLLER "pn544"
224
225 typedef struct nfc_module_t {
226 /**
227 * Common methods of the NFC NXP PN544 module. This *must* be the first member of
228 * nfc_module_t as users of this structure will cast a hw_module_t to
229 * nfc_module_t pointer in contexts where it's known the hw_module_t references a
230 * nfc_module_t.
231 */
232 struct hw_module_t common;
233 } nfc_module_t;
234
235 /*
236 * PN544 linktypes.
237 * UART
238 * I2C
239 * USB (uses UART DAL)
240 */
241 typedef enum {
242 PN544_LINK_TYPE_UART,
243 PN544_LINK_TYPE_I2C,
244 PN544_LINK_TYPE_USB,
245 PN544_LINK_TYPE_INVALID,
246 } nfc_pn544_linktype;
247
248 typedef struct {
249 /**
250 * Common methods of the NFC NXP PN544 device. This *must* be the first member of
251 * nfc_pn544_device_t as users of this structure will cast a hw_device_t to
252 * nfc_pn544_device_t pointer in contexts where it's known the hw_device_t references a
253 * nfc_pn544_device_t.
254 */
255 struct hw_device_t common;
256
257 /* The number of EEPROM registers to write */
258 uint32_t num_eeprom_settings;
259
260 /* The actual EEPROM settings
261 * For PN544, each EEPROM setting is a 4-byte entry,
262 * of the format [0x00, addr_msb, addr_lsb, value].
263 */
264 uint8_t* eeprom_settings;
265
266 /* The link type to which the PN544 is connected */
267 nfc_pn544_linktype linktype;
268
269 /* The device node to which the PN544 is connected */
270 const char* device_node;
271
272 /* On Crespo we had an I2C issue that would cause us to sometimes read
273 * the I2C slave address (0x57) over the bus. libnfc contains
274 * a hack to ignore this byte and try to read the length byte
275 * again.
276 * Set to 0 to disable the workaround, 1 to enable it.
277 */
278 uint8_t enable_i2c_workaround;
279 /* I2C slave address. Multiple I2C addresses are
280 * possible for PN544 module. Configure address according to
281 * board design.
282 */
283 uint8_t i2c_device_address;
284 } nfc_pn544_device_t;
285
nfc_pn544_open(const struct hw_module_t * module,nfc_pn544_device_t ** dev)286 static inline int nfc_pn544_open(const struct hw_module_t* module,
287 nfc_pn544_device_t** dev) {
288 return module->methods->open(module, NFC_PN544_CONTROLLER,
289 (struct hw_device_t**) dev);
290 }
291
nfc_pn544_close(nfc_pn544_device_t * dev)292 static inline int nfc_pn544_close(nfc_pn544_device_t* dev) {
293 return dev->common.close(&dev->common);
294 }
295 /*
296 * End PN544 specific HAL
297 */
298
299 __END_DECLS
300
301 #endif // ANDROID_NFC_HAL_INTERFACE_H
302