1=================== 2Linux NFC subsystem 3=================== 4 5The Near Field Communication (NFC) subsystem is required to standardize the 6NFC device drivers development and to create an unified userspace interface. 7 8This document covers the architecture overview, the device driver interface 9description and the userspace interface description. 10 11Architecture overview 12===================== 13 14The NFC subsystem is responsible for: 15 - NFC adapters management; 16 - Polling for targets; 17 - Low-level data exchange; 18 19The subsystem is divided in some parts. The 'core' is responsible for 20providing the device driver interface. On the other side, it is also 21responsible for providing an interface to control operations and low-level 22data exchange. 23 24The control operations are available to userspace via generic netlink. 25 26The low-level data exchange interface is provided by the new socket family 27PF_NFC. The NFC_SOCKPROTO_RAW performs raw communication with NFC targets. 28 29.. code-block:: none 30 31 +--------------------------------------+ 32 | USER SPACE | 33 +--------------------------------------+ 34 ^ ^ 35 | low-level | control 36 | data exchange | operations 37 | | 38 | v 39 | +-----------+ 40 | AF_NFC | netlink | 41 | socket +-----------+ 42 | raw ^ 43 | | 44 v v 45 +---------+ +-----------+ 46 | rawsock | <--------> | core | 47 +---------+ +-----------+ 48 ^ 49 | 50 v 51 +-----------+ 52 | driver | 53 +-----------+ 54 55Device Driver Interface 56======================= 57 58When registering on the NFC subsystem, the device driver must inform the core 59of the set of supported NFC protocols and the set of ops callbacks. The ops 60callbacks that must be implemented are the following: 61 62* start_poll - setup the device to poll for targets 63* stop_poll - stop on progress polling operation 64* activate_target - select and initialize one of the targets found 65* deactivate_target - deselect and deinitialize the selected target 66* data_exchange - send data and receive the response (transceive operation) 67 68Userspace interface 69=================== 70 71The userspace interface is divided in control operations and low-level data 72exchange operation. 73 74Control operations 75------------------ 76 77Generic netlink is used to implement the interface to the control operations. 78The operations are composed by commands and events, all listed below: 79 80* NFC_CMD_GET_DEVICE - get specific device info or dump the device list 81* NFC_CMD_START_POLL - setup a specific device to polling for targets 82* NFC_CMD_STOP_POLL - stop the polling operation in a specific device 83* NFC_CMD_GET_TARGET - dump the list of targets found by a specific device 84 85* NFC_EVENT_DEVICE_ADDED - reports an NFC device addition 86* NFC_EVENT_DEVICE_REMOVED - reports an NFC device removal 87* NFC_EVENT_TARGETS_FOUND - reports START_POLL results when 1 or more targets 88 are found 89 90The user must call START_POLL to poll for NFC targets, passing the desired NFC 91protocols through NFC_ATTR_PROTOCOLS attribute. The device remains in polling 92state until it finds any target. However, the user can stop the polling 93operation by calling STOP_POLL command. In this case, it will be checked if 94the requester of STOP_POLL is the same of START_POLL. 95 96If the polling operation finds one or more targets, the event TARGETS_FOUND is 97sent (including the device id). The user must call GET_TARGET to get the list of 98all targets found by such device. Each reply message has target attributes with 99relevant information such as the supported NFC protocols. 100 101All polling operations requested through one netlink socket are stopped when 102it's closed. 103 104Low-level data exchange 105----------------------- 106 107The userspace must use PF_NFC sockets to perform any data communication with 108targets. All NFC sockets use AF_NFC:: 109 110 struct sockaddr_nfc { 111 sa_family_t sa_family; 112 __u32 dev_idx; 113 __u32 target_idx; 114 __u32 nfc_protocol; 115 }; 116 117To establish a connection with one target, the user must create an 118NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc 119struct correctly filled. All information comes from NFC_EVENT_TARGETS_FOUND 120netlink event. As a target can support more than one NFC protocol, the user 121must inform which protocol it wants to use. 122 123Internally, 'connect' will result in an activate_target call to the driver. 124When the socket is closed, the target is deactivated. 125 126The data format exchanged through the sockets is NFC protocol dependent. For 127instance, when communicating with MIFARE tags, the data exchanged are MIFARE 128commands and their responses. 129 130The first received package is the response to the first sent package and so 131on. In order to allow valid "empty" responses, every data received has a NULL 132header of 1 byte. 133