Commit | Line | Data |
---|---|---|
0efbf7fb EL |
1 | HCI backend for NFC Core |
2 | ||
3 | Author: Eric Lapuyade, Samuel Ortiz | |
4 | Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com | |
5 | ||
6 | General | |
7 | ------- | |
8 | ||
9 | The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It | |
10 | enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core | |
11 | backend, implementing an abstract nfc device and translating NFC Core API | |
12 | to HCI commands and events. | |
13 | ||
14 | HCI | |
15 | --- | |
16 | ||
17 | HCI registers as an nfc device with NFC Core. Requests coming from userspace are | |
18 | routed through netlink sockets to NFC Core and then to HCI. From this point, | |
19 | they are translated in a sequence of HCI commands sent to the HCI layer in the | |
20 | host controller (the chip). The sending context blocks while waiting for the | |
21 | response to arrive. | |
22 | HCI events can also be received from the host controller. They will be handled | |
23 | and a translation will be forwarded to NFC Core as needed. | |
24 | HCI uses 2 execution contexts: | |
a202abb1 | 25 | - one for executing commands : nfc_hci_msg_tx_work(). Only one command |
0efbf7fb | 26 | can be executing at any given moment. |
a202abb1 | 27 | - one for dispatching received events and commands : nfc_hci_msg_rx_work(). |
0efbf7fb EL |
28 | |
29 | HCI Session initialization: | |
30 | --------------------------- | |
31 | ||
32 | The Session initialization is an HCI standard which must unfortunately | |
33 | support proprietary gates. This is the reason why the driver will pass a list | |
34 | of proprietary gates that must be part of the session. HCI will ensure all | |
35 | those gates have pipes connected when the hci device is set up. | |
36 | ||
37 | HCI Gates and Pipes | |
38 | ------------------- | |
39 | ||
40 | A gate defines the 'port' where some service can be found. In order to access | |
41 | a service, one must create a pipe to that gate and open it. In this | |
42 | implementation, pipes are totally hidden. The public API only knows gates. | |
43 | This is consistent with the driver need to send commands to proprietary gates | |
44 | without knowing the pipe connected to it. | |
45 | ||
46 | Driver interface | |
47 | ---------------- | |
48 | ||
49 | A driver would normally register itself with HCI and provide the following | |
50 | entry points: | |
51 | ||
52 | struct nfc_hci_ops { | |
53 | int (*open)(struct nfc_hci_dev *hdev); | |
54 | void (*close)(struct nfc_hci_dev *hdev); | |
a202abb1 | 55 | int (*hci_ready) (struct nfc_hci_dev *hdev); |
0efbf7fb EL |
56 | int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb); |
57 | int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols); | |
58 | int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate, | |
59 | struct nfc_target *target); | |
a202abb1 EL |
60 | int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate, |
61 | struct nfc_target *target); | |
62 | int (*data_exchange) (struct nfc_hci_dev *hdev, | |
63 | struct nfc_target *target, | |
64 | struct sk_buff *skb, struct sk_buff **res_skb); | |
65 | int (*check_presence)(struct nfc_hci_dev *hdev, | |
66 | struct nfc_target *target); | |
0efbf7fb EL |
67 | }; |
68 | ||
a202abb1 EL |
69 | - open() and close() shall turn the hardware on and off. |
70 | - hci_ready() is an optional entry point that is called right after the hci | |
71 | session has been set up. The driver can use it to do additional initialization | |
72 | that must be performed using HCI commands. | |
73 | - xmit() shall simply write a frame to the chip. | |
74 | - start_poll() is an optional entrypoint that shall set the hardware in polling | |
75 | mode. This must be implemented only if the hardware uses proprietary gates or a | |
76 | mechanism slightly different from the HCI standard. | |
77 | - target_from_gate() is an optional entrypoint to return the nfc protocols | |
0efbf7fb | 78 | corresponding to a proprietary gate. |
a202abb1 EL |
79 | - complete_target_discovered() is an optional entry point to let the driver |
80 | perform additional proprietary processing necessary to auto activate the | |
81 | discovered target. | |
82 | - data_exchange() must be implemented by the driver if proprietary HCI commands | |
83 | are required to send data to the tag. Some tag types will require custom | |
84 | commands, others can be written to using the standard HCI commands. The driver | |
85 | can check the tag type and either do proprietary processing, or return 1 to ask | |
86 | for standard processing. | |
87 | - check_presence() is an optional entry point that will be called regularly | |
88 | by the core to check that an activated tag is still in the field. If this is | |
89 | not implemented, the core will not be able to push tag_lost events to the user | |
90 | space | |
0efbf7fb EL |
91 | |
92 | On the rx path, the driver is responsible to push incoming HCP frames to HCI | |
93 | using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling | |
94 | This must be done from a context that can sleep. | |
95 | ||
96 | SHDLC | |
97 | ----- | |
98 | ||
99 | Most chips use shdlc to ensure integrity and delivery ordering of the HCP | |
100 | frames between the host controller (the chip) and hosts (entities connected | |
101 | to the chip, like the cpu). In order to simplify writing the driver, an shdlc | |
102 | layer is available for use by the driver. | |
103 | When used, the driver actually registers with shdlc, and shdlc will register | |
104 | with HCI. HCI sees shdlc as the driver and thus send its HCP frames | |
105 | through shdlc->xmit. | |
106 | SHDLC adds a new execution context (nfc_shdlc_sm_work()) to run its state | |
107 | machine and handle both its rx and tx path. | |
108 | ||
109 | Included Drivers | |
110 | ---------------- | |
111 | ||
112 | An HCI based driver for an NXP PN544, connected through I2C bus, and using | |
113 | shdlc is included. | |
114 | ||
115 | Execution Contexts | |
116 | ------------------ | |
117 | ||
118 | The execution contexts are the following: | |
119 | - IRQ handler (IRQH): | |
120 | fast, cannot sleep. stores incoming frames into an shdlc rx queue | |
121 | ||
122 | - SHDLC State Machine worker (SMW) | |
123 | handles shdlc rx & tx queues. Dispatches HCI cmd responses. | |
124 | ||
125 | - HCI Tx Cmd worker (MSGTXWQ) | |
a202abb1 EL |
126 | Serializes execution of HCI commands. Completes execution in case of response |
127 | timeout. | |
0efbf7fb EL |
128 | |
129 | - HCI Rx worker (MSGRXWQ) | |
130 | Dispatches incoming HCI commands or events. | |
131 | ||
132 | - Syscall context from a userspace call (SYSCALL) | |
133 | Any entrypoint in HCI called from NFC Core | |
134 | ||
135 | Workflow executing an HCI command (using shdlc) | |
136 | ----------------------------------------------- | |
137 | ||
138 | Executing an HCI command can easily be performed synchronously using the | |
139 | following API: | |
140 | ||
141 | int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, | |
142 | const u8 *param, size_t param_len, struct sk_buff **skb) | |
143 | ||
144 | The API must be invoked from a context that can sleep. Most of the time, this | |
145 | will be the syscall context. skb will return the result that was received in | |
146 | the response. | |
147 | ||
148 | Internally, execution is asynchronous. So all this API does is to enqueue the | |
149 | HCI command, setup a local wait queue on stack, and wait_event() for completion. | |
150 | The wait is not interruptible because it is guaranteed that the command will | |
151 | complete after some short timeout anyway. | |
152 | ||
153 | MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work(). | |
154 | This function will dequeue the next pending command and send its HCP fragments | |
155 | to the lower layer which happens to be shdlc. It will then start a timer to be | |
156 | able to complete the command with a timeout error if no response arrive. | |
157 | ||
158 | SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function | |
159 | handles shdlc framing in and out. It uses the driver xmit to send frames and | |
160 | receives incoming frames in an skb queue filled from the driver IRQ handler. | |
a202abb1 | 161 | SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to |
0efbf7fb EL |
162 | form complete HCI frames, which can be a response, command, or event. |
163 | ||
164 | HCI Responses are dispatched immediately from this context to unblock | |
a202abb1 | 165 | waiting command execution. Response processing involves invoking the completion |
0efbf7fb EL |
166 | callback that was provided by nfc_hci_msg_tx_work() when it sent the command. |
167 | The completion callback will then wake the syscall context. | |
168 | ||
169 | Workflow receiving an HCI event or command | |
170 | ------------------------------------------ | |
171 | ||
172 | HCI commands or events are not dispatched from SMW context. Instead, they are | |
173 | queued to HCI rx_queue and will be dispatched from HCI rx worker | |
174 | context (MSGRXWQ). This is done this way to allow a cmd or event handler | |
175 | to also execute other commands (for example, handling the | |
176 | NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an | |
177 | ANY_GET_PARAMETER to the reader A gate to get information on the target | |
178 | that was discovered). | |
179 | ||
180 | Typically, such an event will be propagated to NFC Core from MSGRXWQ context. | |
36516268 EL |
181 | |
182 | Error management | |
183 | ---------------- | |
184 | ||
185 | Errors that occur synchronously with the execution of an NFC Core request are | |
186 | simply returned as the execution result of the request. These are easy. | |
187 | ||
188 | Errors that occur asynchronously (e.g. in a background protocol handling thread) | |
189 | must be reported such that upper layers don't stay ignorant that something | |
190 | went wrong below and know that expected events will probably never happen. | |
191 | Handling of these errors is done as follows: | |
192 | ||
193 | - driver (pn544) fails to deliver an incoming frame: it stores the error such | |
194 | that any subsequent call to the driver will result in this error. Then it calls | |
195 | the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem | |
196 | above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to | |
197 | report above in turn. | |
198 | ||
199 | - SMW is basically a background thread to handle incoming and outgoing shdlc | |
200 | frames. This thread will also check the shdlc sticky status and report to HCI | |
201 | when it discovers it is not able to run anymore because of an unrecoverable | |
202 | error that happened within shdlc or below. If the problem occurs during shdlc | |
203 | connection, the error is reported through the connect completion. | |
204 | ||
205 | - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an | |
206 | error from a lower layer, HCI will either complete the currently executing | |
207 | command with that error, or notify NFC Core directly if no command is executing. | |
208 | ||
209 | - NFC Core: when NFC Core is notified of an error from below and polling is | |
210 | active, it will send a tag discovered event with an empty tag list to the user | |
211 | space to let it know that the poll operation will never be able to detect a tag. | |
212 | If polling is not active and the error was sticky, lower levels will return it | |
213 | at next invocation. |