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 */
61typedef 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 */
68typedef uint8_t nfc_event_t;
69
70enum {
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 */
83typedef uint8_t nfc_status_t;
84
85enum {
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 */
97typedef 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 */
103typedef 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 */
110typedef 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 */
186static 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
192static 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
212typedef 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 */
222typedef 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
229typedef 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
261static 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
267static 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
277