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_CONTROLLER "nci"
  57
  58 /*
  59  *  nfc_nci_module_t should contain module-specific parameters
  60  */
  61 typedef 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  */
  68 typedef uint8_t nfc_event_t;
  69
  70 enum {
  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  */
  83 typedef uint8_t nfc_status_t;
  84
  85 enum {
  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  */
  97 typedef 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  */
 103 typedef 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  */
 110 typedef 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  */
 186 static 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
 192 static 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
 212 typedef 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  */
 222 typedef 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
 229 typedef 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
 261 static 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
 267 static 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