Commit | Line | Data |
---|---|---|
66ac53a8 | 1 | =================== |
14205aa2 AAJ |
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 | |
66ac53a8 | 12 | ===================== |
14205aa2 AAJ |
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 | ||
c0b96e8f RS |
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 | +-----------+ | |
14205aa2 AAJ |
54 | |
55 | Device Driver Interface | |
66ac53a8 | 56 | ======================= |
14205aa2 AAJ |
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 | |
66ac53a8 | 69 | =================== |
14205aa2 AAJ |
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 | |
f67b7c08 | 87 | are found |
14205aa2 AAJ |
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 | |
bf0b2511 RS |
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 | }; | |
14205aa2 AAJ |
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. |