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