driver-api/nfc/nfc-hci.rst

2 HCI backend for NFC Core
11 The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It
12 enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core
14 to HCI commands and events.
16 HCI  chapter
19 HCI registers as an nfc device with NFC Core. Requests coming from userspace are
20 routed through netlink sockets to NFC Core and then to HCI. From this point,
21 they are translated in a sequence of HCI commands sent to the HCI layer in the
24 from HCI Rx context).
25 HCI events can also be received from the host controller. They will be handled
27 let the HCI driver handle proprietary events or override standard behavior.
28 HCI uses 2 execution contexts:
34 HCI Session initialization
37 The Session initialization is an HCI standard which must unfortunately
39 of proprietary gates that must be part of the session. HCI will ensure all
40 those gates have pipes connected when the hci device is set up.
42 can pass that information to HCI core.
44 HCI Gates and Pipes
57 the HCI management. This makes it easier to maintain a driver for a chip that
60 HCI Management
63 A driver would normally register itself with HCI and provide the following
91 - hci_ready() is an optional entry point that is called right after the hci
93   that must be performed using HCI commands.
97   mechanism slightly different from the HCI standard.
107 - im_transceive() must be implemented by the driver if proprietary HCI commands
109   commands, others can be written to using the standard HCI commands. The driver
119   can handle the event or return 1 to let HCI attempt standard processing.
121 On the rx path, the driver is responsible to push incoming HCP frames to HCI
122 using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
152 protocol. Those are isolated as modules managed by the HCI layer. There are
177 	handle data coming from the chip, going to HCI
179 	handle data sent by HCI, going to the chip
192 An HCI based driver for an NXP PN544, connected through I2C bus, and using
200 fast, cannot sleep. sends incoming frames to HCI where they are passed to
207   Dispatches HCI cmd responses.
209 - HCI Tx Cmd worker (MSGTXWQ)
211   Serializes execution of HCI commands.
215 - HCI Rx worker (MSGRXWQ)
217   Dispatches incoming HCI commands or events.
221   Any entrypoint in HCI called from NFC Core
223 Workflow executing an HCI command (using shdlc)
226 Executing an HCI command can easily be performed synchronously using the
237 HCI command, setup a local wait queue on stack, and wait_event() for completion.
250 form complete HCI frames, which can be a response, command, or event.
252 HCI Responses are dispatched immediately from this context to unblock
266 Workflow receiving an HCI event or command
269 HCI commands or events are not dispatched from SMW context. Instead, they are
270 queued to HCI rx_queue and will be dispatched from HCI rx worker
297   frames. This thread will also check the shdlc sticky status and report to HCI
302 - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an
303   error from a lower layer, HCI will either complete the currently executing