Robert Schwebel | 66ac53a | 2019-11-22 08:43:02 +0100 | [diff] [blame] | 1 | =================== |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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 |
Robert Schwebel | 66ac53a | 2019-11-22 08:43:02 +0100 | [diff] [blame] | 12 | ===================== |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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 | |
Robert Schwebel | c0b96e8 | 2019-11-22 08:43:03 +0100 | [diff] [blame] | 29 | .. code-block:: none |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 30 | |
Robert Schwebel | c0b96e8 | 2019-11-22 08:43:03 +0100 | [diff] [blame] | 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 | +-----------+ |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 54 | |
| 55 | Device Driver Interface |
Robert Schwebel | 66ac53a | 2019-11-22 08:43:02 +0100 | [diff] [blame] | 56 | ======================= |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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 |
Robert Schwebel | 66ac53a | 2019-11-22 08:43:02 +0100 | [diff] [blame] | 69 | =================== |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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 |
Robert Schwebel | f67b7c0 | 2019-11-22 08:43:04 +0100 | [diff] [blame] | 87 | are found |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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 |
Robert Schwebel | bf0b251 | 2019-11-22 08:43:05 +0100 | [diff] [blame] | 106 | targets. All NFC sockets use AF_NFC:: |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 107 | |
Robert Schwebel | bf0b251 | 2019-11-22 08:43:05 +0100 | [diff] [blame] | 108 | struct sockaddr_nfc { |
| 109 | sa_family_t sa_family; |
| 110 | __u32 dev_idx; |
| 111 | __u32 target_idx; |
| 112 | __u32 nfc_protocol; |
| 113 | }; |
Aloisio Almeida Jr | 14205aa | 2011-07-01 19:31:38 -0300 | [diff] [blame] | 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. |