tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
NFC: add Documentation/networking/nfc.txt
Signed-off-by: Aloisio Almeida Jr <aloisio.almeida@openbossa.org>
Signed-off-by: Lauro Ramos Venancio <lauro.venancio@openbossa.org>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
authored by
Aloisio Almeida Jr
and committed by
John W. Linville
14205aa2
c46ee386
+128
+128
Documentation/networking/nfc.txt
+128
Documentation/networking/nfc.txt
···
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.