1 ========================
2 HCI backend for NFC Core
3 ========================
4
5 - Author: Eric Lapuyade, Samuel Ortiz
6 - Contact: eric.lapuyade@intel.com, samuel.ort
7
8 General
9 -------
10
11 The HCI layer implements much of the ETSI TS 1
12 enables easy writing of HCI-based NFC drivers.
13 backend, implementing an abstract nfc device a
14 to HCI commands and events.
15
16 HCI
17 ---
18
19 HCI registers as an nfc device with NFC Core.
20 routed through netlink sockets to NFC Core and
21 they are translated in a sequence of HCI comma
22 host controller (the chip). Commands can be ex
23 context blocks waiting for response) or asynch
24 from HCI Rx context).
25 HCI events can also be received from the host
26 and a translation will be forwarded to NFC Cor
27 let the HCI driver handle proprietary events o
28 HCI uses 2 execution contexts:
29
30 - one for executing commands : nfc_hci_msg_tx_
31 can be executing at any given moment.
32 - one for dispatching received events and comm
33
34 HCI Session initialization
35 --------------------------
36
37 The Session initialization is an HCI standard
38 support proprietary gates. This is the reason
39 of proprietary gates that must be part of the
40 those gates have pipes connected when the hci
41 In case the chip supports pre-opened gates and
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 c
48 a service, one must create a pipe to that gate
49 implementation, pipes are totally hidden. The
50 This is consistent with the driver need to sen
51 without knowing the pipe connected to it.
52
53 Driver interface
54 ----------------
55
56 A driver is generally written in two parts : t
57 the HCI management. This makes it easier to ma
58 can be connected using various phy (i2c, spi,
59
60 HCI Management
61 --------------
62
63 A driver would normally register itself with H
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 *
70 int (*xmit) (struct nfc_hci_dev *hdev,
71 int (*start_poll) (struct nfc_hci_dev
72 u32 im_protocols, u
73 int (*dep_link_up)(struct nfc_hci_dev
74 u8 comm_mode, u8 *g
75 int (*dep_link_down)(struct nfc_hci_de
76 int (*target_from_gate) (struct nfc_hc
77 struct nfc_ta
78 int (*complete_target_discovered) (str
79 str
80 int (*im_transceive) (struct nfc_hci_d
81 struct nfc_targe
82 data_exchange_cb
83 int (*tm_send)(struct nfc_hci_dev *hde
84 int (*check_presence)(struct nfc_hci_d
85 struct nfc_targe
86 int (*event_received)(struct nfc_hci_d
87 struct sk_buff *
88 };
89
90 - open() and close() shall turn the hardware o
91 - hci_ready() is an optional entry point that
92 session has been set up. The driver can use
93 that must be performed using HCI commands.
94 - xmit() shall simply write a frame to the phy
95 - start_poll() is an optional entrypoint that
96 mode. This must be implemented only if the h
97 mechanism slightly different from the HCI st
98 - dep_link_up() is called after a p2p target h
99 the p2p connection setup with hardware param
100 to nfc core.
101 - dep_link_down() is called to bring the p2p l
102 - target_from_gate() is an optional entrypoint
103 corresponding to a proprietary gate.
104 - complete_target_discovered() is an optional
105 perform additional proprietary processing ne
106 discovered target.
107 - im_transceive() must be implemented by the d
108 are required to send data to the tag. Some t
109 commands, others can be written to using the
110 can check the tag type and either do proprie
111 for standard processing. The data exchange c
112 asynchronously.
113 - tm_send() is called to send data in the case
114 - check_presence() is an optional entry point
115 by the core to check that an activated tag i
116 not implemented, the core will not be able t
117 space
118 - event_received() is called to handle an even
119 can handle the event or return 1 to let HCI
120
121 On the rx path, the driver is responsible to p
122 using nfc_hci_recv_frame(). HCI will take care
123 This must be done from a context that can slee
124
125 PHY Management
126 --------------
127
128 The physical link (i2c, ...) management is def
129
130 struct nfc_phy_ops {
131 int (*write)(void *dev_id, struct sk_b
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 re
138 disable():
139 turn the phy off
140 write():
141 Send a data frame to the chip. Note th
142 layers such as an llc to store the fra
143 function must not alter the skb. It mu
144 result (return 0 for success, negative
145
146 Data coming from the chip shall be sent direct
147
148 LLC
149 ---
150
151 Communication between the CPU and the chip oft
152 protocol. Those are isolated as modules manage
153 currently two modules : nop (raw transfer) and
154 A new llc must implement the following functio
155
156 struct nfc_llc_ops {
157 void *(*init) (struct nfc_hci_dev *hde
158 rcv_to_hci_t rcv_to_hci
159 int tx_tailroom, int *r
160 llc_failure_t llc_failu
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 *
165 int (*xmit_from_hci) (struct nfc_llc *
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, goin
178 xmit_from_hci():
179 handle data sent by HCI, going to the
180
181 The llc must be registered with nfc before it
182 calling::
183
184 nfc_llc_register(const char *name, con
185
186 Again, note that the llc does not handle the p
187 easy to mix any physical link with any llc for
188
189 Included Drivers
190 ----------------
191
192 An HCI based driver for an NXP PN544, connecte
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 H
201 the current llc. In case of shdlc, the frame i
202
203 - SHDLC State Machine worker (SMW)
204
205 Only when llc_shdlc is used: handles shdlc r
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 time
214
215 - HCI Rx worker (MSGRXWQ)
216
217 Dispatches incoming HCI commands or events.
218
219 - Syscall context from a userspace call (SYSCA
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 perform
227 following API::
228
229 int nfc_hci_send_cmd (struct nfc_hci_dev *hd
230 const u8 *param, size_
231
232 The API must be invoked from a context that ca
233 will be the syscall context. skb will return t
234 the response.
235
236 Internally, execution is asynchronous. So all
237 HCI command, setup a local wait queue on stack
238 The wait is not interruptible because it is gu
239 complete after some short timeout anyway.
240
241 MSGTXWQ context will then be scheduled and inv
242 This function will dequeue the next pending co
243 to the lower layer which happens to be shdlc.
244 able to complete the command with a timeout er
245
246 SMW context gets scheduled and invokes nfc_shd
247 handles shdlc framing in and out. It uses the
248 receives incoming frames in an skb queue fille
249 SHDLC I(nformation) frames payload are HCP fra
250 form complete HCI frames, which can be a respo
251
252 HCI Responses are dispatched immediately from
253 waiting command execution. Response processing
254 callback that was provided by nfc_hci_msg_tx_w
255 The completion callback will then wake the sys
256
257 It is also possible to execute the command asy
258
259 static int nfc_hci_execute_cmd_async(struct
260 const u
261 data_ex
262
263 The workflow is the same, except that the API
264 the callback will be called with the result fr
265
266 Workflow receiving an HCI event or command
267 ------------------------------------------
268
269 HCI commands or events are not dispatched from
270 queued to HCI rx_queue and will be dispatched
271 context (MSGRXWQ). This is done this way to al
272 to also execute other commands (for example, h
273 NFC_HCI_EVT_TARGET_DISCOVERED event from PN544
274 ANY_GET_PARAMETER to the reader A gate to get
275 that was discovered).
276
277 Typically, such an event will be propagated to
278
279 Error management
280 ----------------
281
282 Errors that occur synchronously with the execu
283 simply returned as the execution result of the
284
285 Errors that occur asynchronously (e.g. in a ba
286 must be reported such that upper layers don't
287 went wrong below and know that expected events
288 Handling of these errors is done as follows:
289
290 - driver (pn544) fails to deliver an incoming
291 that any subsequent call to the driver will
292 calls the standard nfc_shdlc_recv_frame() wi
293 problem above. shdlc stores a EREMOTEIO stic
294 SMW to report above in turn.
295
296 - SMW is basically a background thread to hand
297 frames. This thread will also check the shdl
298 when it discovers it is not able to run anym
299 error that happened within shdlc or below. I
300 connection, the error is reported through th
301
302 - HCI: if an internal HCI error happens (frame
303 error from a lower layer, HCI will either co
304 command with that error, or notify NFC Core
305 executing.
306
307 - NFC Core: when NFC Core is notified of an er
308 active, it will send a tag discovered event
309 space to let it know that the poll operation
310 tag. If polling is not active and the error
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.