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