Linux NFC subsystem

NFC driver와 userspace 표준화

Near Field Communication subsystem은 NFC 장치 driver 개발을 표준화하고 통합 userspace interface를 제공하기 위해 존재합니다. 문서는 architecture, driver interface, userspace interface를 설명합니다.

===================
Linux NFC subsystem
===================

The Near Field Communication (NFC) subsystem is required to standardize the
NFC device drivers development and to create an unified userspace interface.

This document covers the architecture overview, the device driver interface
description and the userspace interface description.

Architecture overview

Core, Generic Netlink와 PF_NFC

NFC subsystem은 adapter 관리, target polling, low-level data exchange를 담당합니다. Core는 한쪽으로 device driver interface를 제공하고 다른 쪽으로 control operation과 low-level data exchange interface를 제공합니다.

Control operation은 generic netlink로 userspace에 노출됩니다. Low-level data exchange는 새 socket family `PF_NFC`가 담당하며 `NFC_SOCKPROTO_RAW`가 NFC target과 raw communication을 수행합니다.

=====================

The NFC subsystem is responsible for:
      - NFC adapters management;
      - Polling for targets;
      - Low-level data exchange;

The subsystem is divided in some parts. The 'core' is responsible for
providing the device driver interface. On the other side, it is also
responsible for providing an interface to control operations and low-level
data exchange.

The control operations are available to userspace via generic netlink.

The low-level data exchange interface is provided by the new socket family
PF_NFC. The NFC_SOCKPROTO_RAW performs raw communication with NFC targets.

.. code-block:: none

        +--------------------------------------+
        |              USER SPACE              |
        +--------------------------------------+
            ^                       ^
            | low-level             | control
            | data exchange         | operations
            |                       |
            |                       v
            |                  +-----------+
            | AF_NFC           |  netlink  |
            | socket           +-----------+
            | raw                   ^
            |                       |
            v                       v
        +---------+            +-----------+
        | rawsock | <--------> |   core    |
        +---------+            +-----------+
                                    ^
                                    |
                                    v
                               +-----------+
                               |  driver   |
                               +-----------+

Device Driver Interface

Device driver callback

NFC subsystem에 등록할 때 driver는 지원하는 NFC protocol 집합과 ops callback 집합을 core에 알려야 합니다. `start_poll`은 target polling을 설정하고 `stop_poll`은 진행 중 polling을 멈춥니다. `activate_target`과 `deactivate_target`은 발견한 target 하나를 선택·초기화하거나 해제하며, `data_exchange`는 데이터를 보내고 응답을 받는 transceive를 수행합니다.

=======================

When registering on the NFC subsystem, the device driver must inform the core
of the set of supported NFC protocols and the set of ops callbacks. The ops
callbacks that must be implemented are the following:

* start_poll - setup the device to poll for targets
* stop_poll - stop on progress polling operation
* activate_target - select and initialize one of the targets found
* deactivate_target - deselect and deinitialize the selected target
* data_exchange - send data and receive the response (transceive operation)

Userspace interface

Userspace control과 raw data exchange

Userspace interface는 control operation과 low-level data exchange로 나뉩니다. Generic netlink command는 `NFC_CMD_GET_DEVICE`, `NFC_CMD_START_POLL`, `NFC_CMD_STOP_POLL`, `NFC_CMD_GET_TARGET`이며 각각 장치 조회, polling 시작·중지, 발견한 target 목록 조회를 수행합니다.

Event는 장치 추가·제거를 알리는 `NFC_EVENT_DEVICE_ADDED`, `NFC_EVENT_DEVICE_REMOVED`와 하나 이상의 target을 찾았을 때 결과를 알리는 `NFC_EVENT_TARGETS_FOUND`입니다.

사용자는 `NFC_ATTR_PROTOCOLS`로 원하는 protocol을 전달해 START_POLL을 호출합니다. Target을 찾을 때까지 polling하며 STOP_POLL로 중지할 수 있습니다. 이때 중지 요청자가 시작 요청자와 같은지 검사합니다. Target을 찾으면 device ID를 포함한 TARGETS_FOUND event가 오고, GET_TARGET으로 전체 목록과 지원 protocol 같은 속성을 얻습니다. 한 netlink socket에서 요청한 polling은 socket을 닫을 때 모두 중지됩니다.

실제 target data communication에는 `PF_NFC` socket을 사용하며 모든 NFC socket의 address family는 `AF_NFC`입니다. `sockaddr_nfc`는 `sa_family`, `dev_idx`, `target_idx`, `nfc_protocol`을 담습니다.

Target에 연결하려면 `NFC_SOCKPROTO_RAW` socket을 만들고 TARGETS_FOUND event에서 얻은 정보로 `sockaddr_nfc`를 채워 `connect`합니다. Target이 여러 protocol을 지원할 수 있으므로 사용할 하나를 지정해야 합니다. 내부적으로 connect는 driver의 `activate_target`을 호출하고 socket close는 target을 deactivate합니다.

Socket을 통해 교환하는 data 형식은 NFC protocol에 따라 다릅니다. MIFARE tag라면 MIFARE command와 response가 오갑니다. 수신 순서는 송신 순서와 일대일로 대응하며, 유효한 빈 응답도 표현할 수 있도록 모든 수신 data 앞에 1바이트 NULL header가 붙습니다.

===================

The userspace interface is divided in control operations and low-level data
exchange operation.

CONTROL OPERATIONS:

Generic netlink is used to implement the interface to the control operations.
The operations are composed by commands and events, all listed below:

* NFC_CMD_GET_DEVICE - get specific device info or dump the device list
* NFC_CMD_START_POLL - setup a specific device to polling for targets
* NFC_CMD_STOP_POLL - stop the polling operation in a specific device
* NFC_CMD_GET_TARGET - dump the list of targets found by a specific device

* NFC_EVENT_DEVICE_ADDED - reports an NFC device addition
* NFC_EVENT_DEVICE_REMOVED - reports an NFC device removal
* NFC_EVENT_TARGETS_FOUND - reports START_POLL results when 1 or more targets
  are found

The user must call START_POLL to poll for NFC targets, passing the desired NFC
protocols through NFC_ATTR_PROTOCOLS attribute. The device remains in polling
state until it finds any target. However, the user can stop the polling
operation by calling STOP_POLL command. In this case, it will be checked if
the requester of STOP_POLL is the same of START_POLL.

If the polling operation finds one or more targets, the event TARGETS_FOUND is
sent (including the device id). The user must call GET_TARGET to get the list of
all targets found by such device. Each reply message has target attributes with
relevant information such as the supported NFC protocols.

All polling operations requested through one netlink socket are stopped when
it's closed.

LOW-LEVEL DATA EXCHANGE:

The userspace must use PF_NFC sockets to perform any data communication with
targets. All NFC sockets use AF_NFC::

        struct sockaddr_nfc {
               sa_family_t sa_family;
               __u32 dev_idx;
               __u32 target_idx;
               __u32 nfc_protocol;
        };

To establish a connection with one target, the user must create an
NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc
struct correctly filled. All information comes from NFC_EVENT_TARGETS_FOUND
netlink event. As a target can support more than one NFC protocol, the user
must inform which protocol it wants to use.

Internally, 'connect' will result in an activate_target call to the driver.
When the socket is closed, the target is deactivated.

The data format exchanged through the sockets is NFC protocol dependent. For
instance, when communicating with MIFARE tags, the data exchanged are MIFARE
commands and their responses.

The first received package is the response to the first sent package and so
on. In order to allow valid "empty" responses, every data received has a NULL
header of 1 byte.