Documentation/driver-api/nfc/nfc-hci.rst

   1 ========================
   2 HCI backend for NFC Core
   3 ========================
   4
   5 - Author: Eric Lapuyade, Samuel Ortiz
   6 - Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
   7
   8 General
   9 -------
  10
  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
  13 backend, implementing an abstract nfc device and translating NFC Core API
  14 to HCI commands and events.
  15
  16 HCI
  17 ---
  18
  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
  22 host controller (the chip). Commands can be executed synchronously (the sending
  23 context blocks waiting for response) or asynchronously (the response is returned
  24 from HCI Rx context).
  25 HCI events can also be received from the host controller. They will be handled
  26 and a translation will be forwarded to NFC Core as needed. There are hooks to
  27 let the HCI driver handle proprietary events or override standard behavior.
  28 HCI uses 2 execution contexts:
  29
  30 - one for executing commands : nfc_hci_msg_tx_work(). Only one command
  31   can be executing at any given moment.
  32 - one for dispatching received events and commands : nfc_hci_msg_rx_work().
  33
  34 HCI Session initialization
  35 --------------------------
  36
  37 The Session initialization is an HCI standard which must unfortunately
  38 support proprietary gates. This is the reason why the driver will pass a list
  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.
  41 In case the chip supports pre-opened gates and pseudo-static pipes, the driver
  42 can pass that information to HCI core.
  43
  44 HCI Gates and Pipes
  45 -------------------
  46
  47 A gate defines the 'port' where some service can be found. In order to access
  48 a service, one must create a pipe to that gate and open it. In this
  49 implementation, pipes are totally hidden. The public API only knows gates.
  50 This is consistent with the driver need to send commands to proprietary gates
  51 without knowing the pipe connected to it.
  52
  53 Driver interface
  54 ----------------
  55
  56 A driver is generally written in two parts : the physical link management and
  57 the HCI management. This makes it easier to maintain a driver for a chip that
  58 can be connected using various phy (i2c, spi, ...)
  59
  60 HCI Management
  61 --------------
  62
  63 A driver would normally register itself with HCI and provide the following
  64 entry points::
  65
  66   struct nfc_hci_ops {
  67         int (*open)(struct nfc_hci_dev *hdev);
  68         void (*close)(struct nfc_hci_dev *hdev);
  69         int (*hci_ready) (struct nfc_hci_dev *hdev);
  70         int (*xmit) (struct nfc_hci_dev *hdev, struct sk_buff *skb);
  71         int (*start_poll) (struct nfc_hci_dev *hdev,
  72                            u32 im_protocols, u32 tm_protocols);
  73         int (*dep_link_up)(struct nfc_hci_dev *hdev, struct nfc_target *target,
  74                            u8 comm_mode, u8 *gb, size_t gb_len);
  75         int (*dep_link_down)(struct nfc_hci_dev *hdev);
  76         int (*target_from_gate) (struct nfc_hci_dev *hdev, u8 gate,
  77                                  struct nfc_target *target);
  78         int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
  79                                            struct nfc_target *target);
  80         int (*im_transceive) (struct nfc_hci_dev *hdev,
  81                               struct nfc_target *target, struct sk_buff *skb,
  82                               data_exchange_cb_t cb, void *cb_context);
  83         int (*tm_send)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
  84         int (*check_presence)(struct nfc_hci_dev *hdev,
  85                               struct nfc_target *target);
  86         int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
  87                               struct sk_buff *skb);
  88   };
  89
  90 - open() and close() shall turn the hardware on and off.
  91 - hci_ready() is an optional entry point that is called right after the hci
  92   session has been set up. The driver can use it to do additional initialization
  93   that must be performed using HCI commands.
  94 - xmit() shall simply write a frame to the physical link.
  95 - start_poll() is an optional entrypoint that shall set the hardware in polling
  96   mode. This must be implemented only if the hardware uses proprietary gates or a
  97   mechanism slightly different from the HCI standard.
  98 - dep_link_up() is called after a p2p target has been detected, to finish
  99   the p2p connection setup with hardware parameters that need to be passed back
 100   to nfc core.
 101 - dep_link_down() is called to bring the p2p link down.
 102 - target_from_gate() is an optional entrypoint to return the nfc protocols
 103   corresponding to a proprietary gate.
 104 - complete_target_discovered() is an optional entry point to let the driver
 105   perform additional proprietary processing necessary to auto activate the
 106   discovered target.
 107 - im_transceive() must be implemented by the driver if proprietary HCI commands
 108   are required to send data to the tag. Some tag types will require custom
 109   commands, others can be written to using the standard HCI commands. The driver
 110   can check the tag type and either do proprietary processing, or return 1 to ask
 111   for standard processing. The data exchange command itself must be sent
 112   asynchronously.
 113 - tm_send() is called to send data in the case of a p2p connection
 114 - check_presence() is an optional entry point that will be called regularly
 115   by the core to check that an activated tag is still in the field. If this is
 116   not implemented, the core will not be able to push tag_lost events to the user
 117   space
 118 - event_received() is called to handle an event coming from the chip. Driver
 119   can handle the event or return 1 to let HCI attempt standard processing.
 120
 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
 123 This must be done from a context that can sleep.
 124
 125 PHY Management
 126 --------------
 127
 128 The physical link (i2c, ...) management is defined by the following structure::
 129
 130   struct nfc_phy_ops {
 131         int (*write)(void *dev_id, struct sk_buff *skb);
 132         int (*enable)(void *dev_id);
 133         void (*disable)(void *dev_id);
 134   };
 135
 136 enable():
 137         turn the phy on (power on), make it ready to transfer data
 138 disable():
 139         turn the phy off
 140 write():
 141         Send a data frame to the chip. Note that to enable higher
 142         layers such as an llc to store the frame for re-emission, this
 143         function must not alter the skb. It must also not return a positive
 144         result (return 0 for success, negative for failure).
 145
 146 Data coming from the chip shall be sent directly to nfc_hci_recv_frame().
 147
 148 LLC
 149 ---
 150
 151 Communication between the CPU and the chip often requires some link layer
 152 protocol. Those are isolated as modules managed by the HCI layer. There are
 153 currently two modules : nop (raw transfert) and shdlc.
 154 A new llc must implement the following functions::
 155
 156   struct nfc_llc_ops {
 157         void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,
 158                        rcv_to_hci_t rcv_to_hci, int tx_headroom,
 159                        int tx_tailroom, int *rx_headroom, int *rx_tailroom,
 160                        llc_failure_t llc_failure);
 161         void (*deinit) (struct nfc_llc *llc);
 162         int (*start) (struct nfc_llc *llc);
 163         int (*stop) (struct nfc_llc *llc);
 164         void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);
 165         int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
 166   };
 167
 168 init():
 169         allocate and init your private storage
 170 deinit():
 171         cleanup
 172 start():
 173         establish the logical connection
 174 stop ():
 175         terminate the logical connection
 176 rcv_from_drv():
 177         handle data coming from the chip, going to HCI
 178 xmit_from_hci():
 179         handle data sent by HCI, going to the chip
 180
 181 The llc must be registered with nfc before it can be used. Do that by
 182 calling::
 183
 184         nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
 185
 186 Again, note that the llc does not handle the physical link. It is thus very
 187 easy to mix any physical link with any llc for a given chip driver.
 188
 189 Included Drivers
 190 ----------------
 191
 192 An HCI based driver for an NXP PN544, connected through I2C bus, and using
 193 shdlc is included.
 194
 195 Execution Contexts
 196 ------------------
 197
 198 The execution contexts are the following:
 199 - IRQ handler (IRQH):
 200 fast, cannot sleep. sends incoming frames to HCI where they are passed to
 201 the current llc. In case of shdlc, the frame is queued in shdlc rx queue.
 202
 203 - SHDLC State Machine worker (SMW)
 204
 205   Only when llc_shdlc is used: handles shdlc rx & tx queues.
 206
 207   Dispatches HCI cmd responses.
 208
 209 - HCI Tx Cmd worker (MSGTXWQ)
 210
 211   Serializes execution of HCI commands.
 212
 213   Completes execution in case of response timeout.
 214
 215 - HCI Rx worker (MSGRXWQ)
 216
 217   Dispatches incoming HCI commands or events.
 218
 219 - Syscall context from a userspace call (SYSCALL)
 220
 221   Any entrypoint in HCI called from NFC Core
 222
 223 Workflow executing an HCI command (using shdlc)
 224 -----------------------------------------------
 225
 226 Executing an HCI command can easily be performed synchronously using the
 227 following API::
 228
 229   int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
 230                         const u8 *param, size_t param_len, struct sk_buff **skb)
 231
 232 The API must be invoked from a context that can sleep. Most of the time, this
 233 will be the syscall context. skb will return the result that was received in
 234 the response.
 235
 236 Internally, execution is asynchronous. So all this API does is to enqueue the
 237 HCI command, setup a local wait queue on stack, and wait_event() for completion.
 238 The wait is not interruptible because it is guaranteed that the command will
 239 complete after some short timeout anyway.
 240
 241 MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work().
 242 This function will dequeue the next pending command and send its HCP fragments
 243 to the lower layer which happens to be shdlc. It will then start a timer to be
 244 able to complete the command with a timeout error if no response arrive.
 245
 246 SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function
 247 handles shdlc framing in and out. It uses the driver xmit to send frames and
 248 receives incoming frames in an skb queue filled from the driver IRQ handler.
 249 SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to
 250 form complete HCI frames, which can be a response, command, or event.
 251
 252 HCI Responses are dispatched immediately from this context to unblock
 253 waiting command execution. Response processing involves invoking the completion
 254 callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
 255 The completion callback will then wake the syscall context.
 256
 257 It is also possible to execute the command asynchronously using this API::
 258
 259   static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
 260                                        const u8 *param, size_t param_len,
 261                                        data_exchange_cb_t cb, void *cb_context)
 262
 263 The workflow is the same, except that the API call returns immediately, and
 264 the callback will be called with the result from the SMW context.
 265
 266 Workflow receiving an HCI event or command
 267 ------------------------------------------
 268
 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
 271 context (MSGRXWQ). This is done this way to allow a cmd or event handler
 272 to also execute other commands (for example, handling the
 273 NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an
 274 ANY_GET_PARAMETER to the reader A gate to get information on the target
 275 that was discovered).
 276
 277 Typically, such an event will be propagated to NFC Core from MSGRXWQ context.
 278
 279 Error management
 280 ----------------
 281
 282 Errors that occur synchronously with the execution of an NFC Core request are
 283 simply returned as the execution result of the request. These are easy.
 284
 285 Errors that occur asynchronously (e.g. in a background protocol handling thread)
 286 must be reported such that upper layers don't stay ignorant that something
 287 went wrong below and know that expected events will probably never happen.
 288 Handling of these errors is done as follows:
 289
 290 - driver (pn544) fails to deliver an incoming frame: it stores the error such
 291   that any subsequent call to the driver will result in this error. Then it
 292   calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the
 293   problem above. shdlc stores a EREMOTEIO sticky status, which will trigger
 294   SMW to report above in turn.
 295
 296 - SMW is basically a background thread to handle incoming and outgoing shdlc
 297   frames. This thread will also check the shdlc sticky status and report to HCI
 298   when it discovers it is not able to run anymore because of an unrecoverable
 299   error that happened within shdlc or below. If the problem occurs during shdlc
 300   connection, the error is reported through the connect completion.
 301
 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
 304   command with that error, or notify NFC Core directly if no command is
 305   executing.
 306
 307 - NFC Core: when NFC Core is notified of an error from below and polling is
 308   active, it will send a tag discovered event with an empty tag list to the user
 309   space to let it know that the poll operation will never be able to detect a
 310   tag. If polling is not active and the error was sticky, lower levels will
 311   return it at next invocation.