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