Eric Lee / linux-smarc-t335x-v3.2

Commit 14205aa21c8041d7e940ee9bcde87824dc00a08a

Authored by Aloisio Almeida Jr 2011-07-02 06:31:38 +0800

Committed by John W. Linville 2011-07-06 03:26:58 +0800

Exists in master and in 4 other branches

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>

Showing 1 changed file with 128 additions and 0 deletions Side-by-side Diff

Documentation/networking/nfc.txt

Documentation/networking/nfc.txt

Diff comments View file @ 14205aa

	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.