Documentation/nfc/nfc-hci.txt

   1 HCI backend for NFC Core
   2
   3 Author: Eric Lapuyade, Samuel Ortiz
   4 Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
   5
   6 General
   7 -------
   8
   9 The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It
  10 enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core
  11 backend, implementing an abstract nfc device and translating NFC Core API
  12 to HCI commands and events.
  13
  14 HCI
  15 ---
  16
  17 HCI registers as an nfc device with NFC Core. Requests coming from userspace are
  18 routed through netlink sockets to NFC Core and then to HCI. From this point,
  19 they are translated in a sequence of HCI commands sent to the HCI layer in the
  20 host controller (the chip). The sending context blocks while waiting for the
  21 response to arrive.
  22 HCI events can also be received from the host controller. They will be handled
  23 and a translation will be forwarded to NFC Core as needed.
  24 HCI uses 2 execution contexts:
  25 - one for executing commands : nfc_hci_msg_tx_work(). Only one command
  26 can be executing at any given moment.
  27 - one for dispatching received events and commands : nfc_hci_msg_rx_work().
  28
  29 HCI Session initialization:
  30 ---------------------------
  31
  32 The Session initialization is an HCI standard which must unfortunately
  33 support proprietary gates. This is the reason why the driver will pass a list
  34 of proprietary gates that must be part of the session. HCI will ensure all
  35 those gates have pipes connected when the hci device is set up.
  36
  37 HCI Gates and Pipes
  38 -------------------
  39
  40 A gate defines the 'port' where some service can be found. In order to access
  41 a service, one must create a pipe to that gate and open it. In this
  42 implementation, pipes are totally hidden. The public API only knows gates.
  43 This is consistent with the driver need to send commands to proprietary gates
  44 without knowing the pipe connected to it.
  45
  46 Driver interface
  47 ----------------
  48
  49 A driver would normally register itself with HCI and provide the following
  50 entry points:
  51
  52 struct nfc_hci_ops {
  53         int (*open)(struct nfc_hci_dev *hdev);
  54         void (*close)(struct nfc_hci_dev *hdev);
  55         int (*hci_ready) (struct nfc_hci_dev *hdev);
  56         int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
  57         int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols);
  58         int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate,
  59                                 struct nfc_target *target);
  60         int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
  61                                            struct nfc_target *target);
  62         int (*data_exchange) (struct nfc_hci_dev *hdev,
  63                               struct nfc_target *target,
  64                               struct sk_buff *skb, struct sk_buff **res_skb);
  65         int (*check_presence)(struct nfc_hci_dev *hdev,
  66                               struct nfc_target *target);
  67 };
  68
  69 - open() and close() shall turn the hardware on and off.
  70 - hci_ready() is an optional entry point that is called right after the hci
  71 session has been set up. The driver can use it to do additional initialization
  72 that must be performed using HCI commands.
  73 - xmit() shall simply write a frame to the chip.
  74 - start_poll() is an optional entrypoint that shall set the hardware in polling
  75 mode. This must be implemented only if the hardware uses proprietary gates or a
  76 mechanism slightly different from the HCI standard.
  77 - target_from_gate() is an optional entrypoint to return the nfc protocols
  78 corresponding to a proprietary gate.
  79 - complete_target_discovered() is an optional entry point to let the driver
  80 perform additional proprietary processing necessary to auto activate the
  81 discovered target.
  82 - data_exchange() must be implemented by the driver if proprietary HCI commands
  83 are required to send data to the tag. Some tag types will require custom
  84 commands, others can be written to using the standard HCI commands. The driver
  85 can check the tag type and either do proprietary processing, or return 1 to ask
  86 for standard processing.
  87 - check_presence() is an optional entry point that will be called regularly
  88 by the core to check that an activated tag is still in the field. If this is
  89 not implemented, the core will not be able to push tag_lost events to the user
  90 space
  91
  92 On the rx path, the driver is responsible to push incoming HCP frames to HCI
  93 using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
  94 This must be done from a context that can sleep.
  95
  96 SHDLC
  97 -----
  98
  99 Most chips use shdlc to ensure integrity and delivery ordering of the HCP
 100 frames between the host controller (the chip) and hosts (entities connected
 101 to the chip, like the cpu). In order to simplify writing the driver, an shdlc
 102 layer is available for use by the driver.
 103 When used, the driver actually registers with shdlc, and shdlc will register
 104 with HCI. HCI sees shdlc as the driver and thus send its HCP frames
 105 through shdlc->xmit.
 106 SHDLC adds a new execution context (nfc_shdlc_sm_work()) to run its state
 107 machine and handle both its rx and tx path.
 108
 109 Included Drivers
 110 ----------------
 111
 112 An HCI based driver for an NXP PN544, connected through I2C bus, and using
 113 shdlc is included.
 114
 115 Execution Contexts
 116 ------------------
 117
 118 The execution contexts are the following:
 119 - IRQ handler (IRQH):
 120 fast, cannot sleep. stores incoming frames into an shdlc rx queue
 121
 122 - SHDLC State Machine worker (SMW)
 123 handles shdlc rx & tx queues. Dispatches HCI cmd responses.
 124
 125 - HCI Tx Cmd worker (MSGTXWQ)
 126 Serializes execution of HCI commands. Completes execution in case of response
 127 timeout.
 128
 129 - HCI Rx worker (MSGRXWQ)
 130 Dispatches incoming HCI commands or events.
 131
 132 - Syscall context from a userspace call (SYSCALL)
 133 Any entrypoint in HCI called from NFC Core
 134
 135 Workflow executing an HCI command (using shdlc)
 136 -----------------------------------------------
 137
 138 Executing an HCI command can easily be performed synchronously using the
 139 following API:
 140
 141 int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
 142                         const u8 *param, size_t param_len, struct sk_buff **skb)
 143
 144 The API must be invoked from a context that can sleep. Most of the time, this
 145 will be the syscall context. skb will return the result that was received in
 146 the response.
 147
 148 Internally, execution is asynchronous. So all this API does is to enqueue the
 149 HCI command, setup a local wait queue on stack, and wait_event() for completion.
 150 The wait is not interruptible because it is guaranteed that the command will
 151 complete after some short timeout anyway.
 152
 153 MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work().
 154 This function will dequeue the next pending command and send its HCP fragments
 155 to the lower layer which happens to be shdlc. It will then start a timer to be
 156 able to complete the command with a timeout error if no response arrive.
 157
 158 SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function
 159 handles shdlc framing in and out. It uses the driver xmit to send frames and
 160 receives incoming frames in an skb queue filled from the driver IRQ handler.
 161 SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to
 162 form complete HCI frames, which can be a response, command, or event.
 163
 164 HCI Responses are dispatched immediately from this context to unblock
 165 waiting command execution. Response processing involves invoking the completion
 166 callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
 167 The completion callback will then wake the syscall context.
 168
 169 Workflow receiving an HCI event or command
 170 ------------------------------------------
 171
 172 HCI commands or events are not dispatched from SMW context. Instead, they are
 173 queued to HCI rx_queue and will be dispatched from HCI rx worker
 174 context (MSGRXWQ). This is done this way to allow a cmd or event handler
 175 to also execute other commands (for example, handling the
 176 NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an
 177 ANY_GET_PARAMETER to the reader A gate to get information on the target
 178 that was discovered).
 179
 180 Typically, such an event will be propagated to NFC Core from MSGRXWQ context.
 181
 182 Error management
 183 ----------------
 184
 185 Errors that occur synchronously with the execution of an NFC Core request are
 186 simply returned as the execution result of the request. These are easy.
 187
 188 Errors that occur asynchronously (e.g. in a background protocol handling thread)
 189 must be reported such that upper layers don't stay ignorant that something
 190 went wrong below and know that expected events will probably never happen.
 191 Handling of these errors is done as follows:
 192
 193 - driver (pn544) fails to deliver an incoming frame: it stores the error such
 194 that any subsequent call to the driver will result in this error. Then it calls
 195 the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem
 196 above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to
 197 report above in turn.
 198
 199 - SMW is basically a background thread to handle incoming and outgoing shdlc
 200 frames. This thread will also check the shdlc sticky status and report to HCI
 201 when it discovers it is not able to run anymore because of an unrecoverable
 202 error that happened within shdlc or below. If the problem occurs during shdlc
 203 connection, the error is reported through the connect completion.
 204
 205 - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an
 206 error from a lower layer, HCI will either complete the currently executing
 207 command with that error, or notify NFC Core directly if no command is executing.
 208
 209 - NFC Core: when NFC Core is notified of an error from below and polling is
 210 active, it will send a tag discovered event with an empty tag list to the user
 211 space to let it know that the poll operation will never be able to detect a tag.
 212 If polling is not active and the error was sticky, lower levels will return it
 213 at next invocation.