^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Linux NFC subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) The Near Field Communication (NFC) subsystem is required to standardize the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) NFC device drivers development and to create an unified userspace interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) This document covers the architecture overview, the device driver interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) description and the userspace interface description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Architecture overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) The NFC subsystem is responsible for:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) - NFC adapters management;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) - Polling for targets;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) - Low-level data exchange;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) The subsystem is divided in some parts. The 'core' is responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) providing the device driver interface. On the other side, it is also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) responsible for providing an interface to control operations and low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) data exchange.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) The control operations are available to userspace via generic netlink.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) The low-level data exchange interface is provided by the new socket family
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) PF_NFC. The NFC_SOCKPROTO_RAW performs raw communication with NFC targets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) +--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) | USER SPACE |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) +--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) ^ ^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) | low-level | control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) | data exchange | operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) | v
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) | +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) | AF_NFC | netlink |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) | socket +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) | raw ^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) v v
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) +---------+ +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) | rawsock | <--------> | core |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) +---------+ +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) ^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) v
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) | driver |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Device Driver Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) When registering on the NFC subsystem, the device driver must inform the core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) of the set of supported NFC protocols and the set of ops callbacks. The ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) callbacks that must be implemented are the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) * start_poll - setup the device to poll for targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) * stop_poll - stop on progress polling operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) * activate_target - select and initialize one of the targets found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) * deactivate_target - deselect and deinitialize the selected target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) * data_exchange - send data and receive the response (transceive operation)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Userspace interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The userspace interface is divided in control operations and low-level data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) exchange operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) CONTROL OPERATIONS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Generic netlink is used to implement the interface to the control operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) The operations are composed by commands and events, all listed below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * NFC_CMD_GET_DEVICE - get specific device info or dump the device list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) * NFC_CMD_START_POLL - setup a specific device to polling for targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) * NFC_CMD_STOP_POLL - stop the polling operation in a specific device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) * NFC_CMD_GET_TARGET - dump the list of targets found by a specific device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) * NFC_EVENT_DEVICE_ADDED - reports an NFC device addition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) * NFC_EVENT_DEVICE_REMOVED - reports an NFC device removal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * NFC_EVENT_TARGETS_FOUND - reports START_POLL results when 1 or more targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) are found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) The user must call START_POLL to poll for NFC targets, passing the desired NFC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) protocols through NFC_ATTR_PROTOCOLS attribute. The device remains in polling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) state until it finds any target. However, the user can stop the polling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) operation by calling STOP_POLL command. In this case, it will be checked if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) the requester of STOP_POLL is the same of START_POLL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) If the polling operation finds one or more targets, the event TARGETS_FOUND is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) sent (including the device id). The user must call GET_TARGET to get the list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) all targets found by such device. Each reply message has target attributes with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) relevant information such as the supported NFC protocols.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) All polling operations requested through one netlink socket are stopped when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) it's closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) LOW-LEVEL DATA EXCHANGE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) The userspace must use PF_NFC sockets to perform any data communication with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) targets. All NFC sockets use AF_NFC::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) struct sockaddr_nfc {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) sa_family_t sa_family;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) __u32 dev_idx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) __u32 target_idx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) __u32 nfc_protocol;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) To establish a connection with one target, the user must create an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) struct correctly filled. All information comes from NFC_EVENT_TARGETS_FOUND
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) netlink event. As a target can support more than one NFC protocol, the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) must inform which protocol it wants to use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Internally, 'connect' will result in an activate_target call to the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) When the socket is closed, the target is deactivated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) The data format exchanged through the sockets is NFC protocol dependent. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) instance, when communicating with MIFARE tags, the data exchanged are MIFARE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) commands and their responses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) The first received package is the response to the first sent package and so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) on. In order to allow valid "empty" responses, every data received has a NULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) header of 1 byte.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags