blob: 9aab3a88c9b2983fe53e366308bf1d278830cac5 [file] [log] [blame]
Robert Schwebel66ac53a2019-11-22 08:43:02 +01001===================
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -03002Linux 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
Robert Schwebel66ac53a2019-11-22 08:43:02 +010012=====================
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -030013
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
Robert Schwebelc0b96e82019-11-22 08:43:03 +010029.. code-block:: none
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -030030
Robert Schwebelc0b96e82019-11-22 08:43:03 +010031 +--------------------------------------+
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 Jr14205aa2011-07-01 19:31:38 -030054
55Device Driver Interface
Robert Schwebel66ac53a2019-11-22 08:43:02 +010056=======================
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -030057
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
Robert Schwebel66ac53a2019-11-22 08:43:02 +010069===================
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -030070
71The userspace interface is divided in control operations and low-level data
72exchange operation.
73
74CONTROL OPERATIONS:
75
76Generic netlink is used to implement the interface to the control operations.
77The 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 Schwebelf67b7c02019-11-22 08:43:04 +010087 are found
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -030088
89The user must call START_POLL to poll for NFC targets, passing the desired NFC
90protocols through NFC_ATTR_PROTOCOLS attribute. The device remains in polling
91state until it finds any target. However, the user can stop the polling
92operation by calling STOP_POLL command. In this case, it will be checked if
93the requester of STOP_POLL is the same of START_POLL.
94
95If the polling operation finds one or more targets, the event TARGETS_FOUND is
96sent (including the device id). The user must call GET_TARGET to get the list of
97all targets found by such device. Each reply message has target attributes with
98relevant information such as the supported NFC protocols.
99
100All polling operations requested through one netlink socket are stopped when
101it's closed.
102
103LOW-LEVEL DATA EXCHANGE:
104
105The userspace must use PF_NFC sockets to perform any data communication with
Robert Schwebelbf0b2512019-11-22 08:43:05 +0100106targets. All NFC sockets use AF_NFC::
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -0300107
Robert Schwebelbf0b2512019-11-22 08:43:05 +0100108 struct sockaddr_nfc {
109 sa_family_t sa_family;
110 __u32 dev_idx;
111 __u32 target_idx;
112 __u32 nfc_protocol;
113 };
Aloisio Almeida Jr14205aa2011-07-01 19:31:38 -0300114
115To establish a connection with one target, the user must create an
116NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc
117struct correctly filled. All information comes from NFC_EVENT_TARGETS_FOUND
118netlink event. As a target can support more than one NFC protocol, the user
119must inform which protocol it wants to use.
120
121Internally, 'connect' will result in an activate_target call to the driver.
122When the socket is closed, the target is deactivated.
123
124The data format exchanged through the sockets is NFC protocol dependent. For
125instance, when communicating with MIFARE tags, the data exchanged are MIFARE
126commands and their responses.
127
128The first received package is the response to the first sent package and so
129on. In order to allow valid "empty" responses, every data received has a NULL
130header of 1 byte.