Documentation/networking/nfc.rst

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