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