About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / nfc.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog