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