include/hardware/nfc.h

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