nfc.h
Go to the documentation of this file.
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  */
71 
72 /*
73  * HAL events that can be passed back to the stack
74  */
75 typedef uint8_t nfc_event_t;
76 
77 enum {
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 {
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  */
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);
194 
195 /*
196  * Convenience methods that the NFC stack can use to open
197  * and close an NCI device
198  */
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 
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  */
233 } nfc_module_t;
234 
235 /*
236  * PN544 linktypes.
237  * UART
238  * I2C
239  * USB (uses UART DAL)
240  */
241 typedef enum {
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 */
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 */
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  */
279  /* I2C slave address. Multiple I2C addresses are
280  * possible for PN544 module. Configure address according to
281  * board design.
282  */
285 
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 
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
int(* core_initialized)(const struct nfc_nci_device *p_dev, uint8_t *p_core_init_rsp_params)
Definition: nfc.h:160
int(* open)(const struct hw_module_t *module, const char *id, struct hw_device_t **device)
Definition: hardware.h:158
nfc_pn544_linktype linktype
Definition: nfc.h:267
int(* open)(const struct nfc_nci_device *p_dev, nfc_stack_callback_t *p_cback, nfc_stack_data_callback_t *p_data_cback)
Definition: nfc.h:139
int(* close)(struct hw_device_t *device)
Definition: hardware.h:200
const char * device_node
Definition: nfc.h:270
#define NFC_PN544_CONTROLLER
Definition: nfc.h:223
struct hw_device_t common
Definition: nfc.h:124
struct nfc_nci_device nfc_nci_device_t
int(* control_granted)(const struct nfc_nci_device *p_dev)
Definition: nfc.h:186
uint32_t num_eeprom_settings
Definition: nfc.h:258
int(* write)(const struct nfc_nci_device *p_dev, uint16_t data_len, const uint8_t *p_data)
Definition: nfc.h:148
struct nfc_module_t nfc_module_t
struct hw_module_t common
Definition: nfc.h:232
struct hw_module_t * module
Definition: hardware.h:190
int(* pre_discover)(const struct nfc_nci_device *p_dev)
Definition: nfc.h:173
struct hw_module_t common
Definition: nfc.h:69
uint8_t nfc_status_t
Definition: nfc.h:90
uint8_t enable_i2c_workaround
Definition: nfc.h:278
void( nfc_stack_data_callback_t)(uint16_t data_len, uint8_t *p_data)
Definition: nfc.h:110
uint8_t i2c_device_address
Definition: nfc.h:283
void( nfc_stack_callback_t)(nfc_event_t event, nfc_status_t event_status)
Definition: nfc.h:104
int(* close)(const struct nfc_nci_device *p_dev)
Definition: nfc.h:178
int(* power_cycle)(const struct nfc_nci_device *p_dev)
Definition: nfc.h:192
struct hw_module_methods_t * methods
Definition: hardware.h:142
uint8_t * eeprom_settings
Definition: nfc.h:264
struct hw_device_t common
Definition: nfc.h:255
uint8_t nfc_event_t
Definition: nfc.h:75
#define NFC_NCI_CONTROLLER
Definition: nfc.h:57
struct nfc_nci_module_t nfc_nci_module_t
nfc_pn544_linktype
Definition: nfc.h:241