nfc-hci.rst 13 KB

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