| 1 |
======================== |
| 2 |
HCI backend for NFC Core |
| 3 |
======================== |
| 4 |
|
| 5 |
- Author: Eric Lapuyade, Samuel Ortiz |
| 6 |
- Contact: [email protected], [email protected] |
| 7 |
|
| 8 |
General |
| 9 |
------- |
| 10 |
|
| 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. The HCI layer runs as an NFC Core |
| 13 |
backend, implementing an abstract nfc device and translating NFC Core API |
| 14 |
to HCI commands and events. |
| 15 |
|
| 16 |
HCI |
| 17 |
--- |
| 18 |
|
| 19 |
HCI registers as an nfc device with NFC Core. Requests coming from userspace are |
| 20 |
routed through netlink sockets to NFC Core and then to HCI. From this point, |
| 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 executed synchronously (the sending |
| 23 |
context blocks waiting for response) or asynchronously (the response is returned |
| 24 |
from HCI Rx context). |
| 25 |
HCI events can also be received from the host controller. They will be handled |
| 26 |
and a translation will be forwarded to NFC Core as needed. There are hooks to |
| 27 |
let the HCI driver handle proprietary events or override standard behavior. |
| 28 |
HCI uses 2 execution contexts: |
| 29 |
|
| 30 |
- one for executing commands : nfc_hci_msg_tx_work(). Only one command |
| 31 |
can be executing at any given moment. |
| 32 |
- one for dispatching received events and commands : nfc_hci_msg_rx_work(). |
| 33 |
|
| 34 |
HCI Session initialization |
| 35 |
-------------------------- |
| 36 |
|
| 37 |
The Session initialization is an HCI standard which must unfortunately |
| 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 session. HCI will ensure all |
| 40 |
those gates have pipes connected when the hci device is set up. |
| 41 |
In case the chip supports pre-opened gates and pseudo-static pipes, the driver |
| 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 can be found. In order to access |
| 48 |
a service, one must create a pipe to that gate and open it. In this |
| 49 |
implementation, pipes are totally hidden. The public API only knows gates. |
| 50 |
This is consistent with the driver need to send commands to proprietary gates |
| 51 |
without knowing the pipe connected to it. |
| 52 |
|
| 53 |
Driver interface |
| 54 |
---------------- |
| 55 |
|
| 56 |
A driver is generally written in two parts : the physical link management and |
| 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, ...) |
| 59 |
|
| 60 |
HCI Management |
| 61 |
-------------- |
| 62 |
|
| 63 |
A driver would normally register itself with HCI and provide the following |
| 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 *hdev); |
| 70 |
int (*xmit) (struct nfc_hci_dev *hdev, struct sk_buff *skb); |
| 71 |
int (*start_poll) (struct nfc_hci_dev *hdev, |
| 72 |
u32 im_protocols, u32 tm_protocols); |
| 73 |
int (*dep_link_up)(struct nfc_hci_dev *hdev, struct nfc_target *target, |
| 74 |
u8 comm_mode, u8 *gb, size_t gb_len); |
| 75 |
int (*dep_link_down)(struct nfc_hci_dev *hdev); |
| 76 |
int (*target_from_gate) (struct nfc_hci_dev *hdev, u8 gate, |
| 77 |
struct nfc_target *target); |
| 78 |
int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate, |
| 79 |
struct nfc_target *target); |
| 80 |
int (*im_transceive) (struct nfc_hci_dev *hdev, |
| 81 |
struct nfc_target *target, struct sk_buff *skb, |
| 82 |
data_exchange_cb_t cb, void *cb_context); |
| 83 |
int (*tm_send)(struct nfc_hci_dev *hdev, struct sk_buff *skb); |
| 84 |
int (*check_presence)(struct nfc_hci_dev *hdev, |
| 85 |
struct nfc_target *target); |
| 86 |
int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event, |
| 87 |
struct sk_buff *skb); |
| 88 |
}; |
| 89 |
|
| 90 |
- open() and close() shall turn the hardware on and off. |
| 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 it to do additional initialization |
| 93 |
that must be performed using HCI commands. |
| 94 |
- xmit() shall simply write a frame to the physical link. |
| 95 |
- start_poll() is an optional entrypoint that shall set the hardware in polling |
| 96 |
mode. This must be implemented only if the hardware uses proprietary gates or a |
| 97 |
mechanism slightly different from the HCI standard. |
| 98 |
- dep_link_up() is called after a p2p target has been detected, to finish |
| 99 |
the p2p connection setup with hardware parameters that need to be passed back |
| 100 |
to nfc core. |
| 101 |
- dep_link_down() is called to bring the p2p link down. |
| 102 |
- target_from_gate() is an optional entrypoint to return the nfc protocols |
| 103 |
corresponding to a proprietary gate. |
| 104 |
- complete_target_discovered() is an optional entry point to let the driver |
| 105 |
perform additional proprietary processing necessary to auto activate the |
| 106 |
discovered target. |
| 107 |
- im_transceive() must be implemented by the driver if proprietary HCI commands |
| 108 |
are required to send data to the tag. Some tag types will require custom |
| 109 |
commands, others can be written to using the standard HCI commands. The driver |
| 110 |
can check the tag type and either do proprietary processing, or return 1 to ask |
| 111 |
for standard processing. The data exchange command itself must be sent |
| 112 |
asynchronously. |
| 113 |
- tm_send() is called to send data in the case of a p2p connection |
| 114 |
- check_presence() is an optional entry point that will be called regularly |
| 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 to push tag_lost events to the user |
| 117 |
space |
| 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 attempt standard processing. |
| 120 |
|
| 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 of re-aggregation and handling |
| 123 |
This must be done from a context that can sleep. |
| 124 |
|
| 125 |
PHY Management |
| 126 |
-------------- |
| 127 |
|
| 128 |
The physical link (i2c, ...) management is defined by the following structure:: |
| 129 |
|
| 130 |
struct nfc_phy_ops { |
| 131 |
int (*write)(void *dev_id, struct sk_buff *skb); |
| 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 ready to transfer data |
| 138 |
disable(): |
| 139 |
turn the phy off |
| 140 |
write(): |
| 141 |
Send a data frame to the chip. Note that to enable higher |
| 142 |
layers such as an llc to store the frame for re-emission, this |
| 143 |
function must not alter the skb. It must also not return a positive |
| 144 |
result (return 0 for success, negative for failure). |
| 145 |
|
| 146 |
Data coming from the chip shall be sent directly to nfc_hci_recv_frame(). |
| 147 |
|
| 148 |
LLC |
| 149 |
--- |
| 150 |
|
| 151 |
Communication between the CPU and the chip often requires some link layer |
| 152 |
protocol. Those are isolated as modules managed by the HCI layer. There are |
| 153 |
currently two modules : nop (raw transfer) and shdlc. |
| 154 |
A new llc must implement the following functions:: |
| 155 |
|
| 156 |
struct nfc_llc_ops { |
| 157 |
void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv, |
| 158 |
rcv_to_hci_t rcv_to_hci, int tx_headroom, |
| 159 |
int tx_tailroom, int *rx_headroom, int *rx_tailroom, |
| 160 |
llc_failure_t llc_failure); |
| 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 *llc, struct sk_buff *skb); |
| 165 |
int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb); |
| 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, going to HCI |
| 178 |
xmit_from_hci(): |
| 179 |
handle data sent by HCI, going to the chip |
| 180 |
|
| 181 |
The llc must be registered with nfc before it can be used. Do that by |
| 182 |
calling:: |
| 183 |
|
| 184 |
nfc_llc_register(const char *name, const struct nfc_llc_ops *ops); |
| 185 |
|
| 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 a given chip driver. |
| 188 |
|
| 189 |
Included Drivers |
| 190 |
---------------- |
| 191 |
|
| 192 |
An HCI based driver for an NXP PN544, connected through I2C bus, and using |
| 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 HCI where they are passed to |
| 201 |
the current llc. In case of shdlc, the frame is queued in shdlc rx queue. |
| 202 |
|
| 203 |
- SHDLC State Machine worker (SMW) |
| 204 |
|
| 205 |
Only when llc_shdlc is used: handles shdlc rx & tx queues. |
| 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 timeout. |
| 214 |
|
| 215 |
- HCI Rx worker (MSGRXWQ) |
| 216 |
|
| 217 |
Dispatches incoming HCI commands or events. |
| 218 |
|
| 219 |
- Syscall context from a userspace call (SYSCALL) |
| 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 performed synchronously using the |
| 227 |
following API:: |
| 228 |
|
| 229 |
int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, |
| 230 |
const u8 *param, size_t param_len, struct sk_buff **skb) |
| 231 |
|
| 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 the result that was received in |
| 234 |
the response. |
| 235 |
|
| 236 |
Internally, execution is asynchronous. So all this API does is to enqueue the |
| 237 |
HCI command, setup a local wait queue on stack, and wait_event() for completion. |
| 238 |
The wait is not interruptible because it is guaranteed that the command will |
| 239 |
complete after some short timeout anyway. |
| 240 |
|
| 241 |
MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work(). |
| 242 |
This function will dequeue the next pending command and send its HCP fragments |
| 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 error if no response arrive. |
| 245 |
|
| 246 |
SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function |
| 247 |
handles shdlc framing in and out. It uses the driver xmit to send frames and |
| 248 |
receives incoming frames in an skb queue filled from the driver IRQ handler. |
| 249 |
SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to |
| 250 |
form complete HCI frames, which can be a response, command, or event. |
| 251 |
|
| 252 |
HCI Responses are dispatched immediately from this context to unblock |
| 253 |
waiting command execution. Response processing involves invoking the completion |
| 254 |
callback that was provided by nfc_hci_msg_tx_work() when it sent the command. |
| 255 |
The completion callback will then wake the syscall context. |
| 256 |
|
| 257 |
It is also possible to execute the command asynchronously using this API:: |
| 258 |
|
| 259 |
static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd, |
| 260 |
const u8 *param, size_t param_len, |
| 261 |
data_exchange_cb_t cb, void *cb_context) |
| 262 |
|
| 263 |
The workflow is the same, except that the API call returns immediately, and |
| 264 |
the callback will be called with the result from the SMW context. |
| 265 |
|
| 266 |
Workflow receiving an HCI event or command |
| 267 |
------------------------------------------ |
| 268 |
|
| 269 |
HCI commands or events are not dispatched from SMW context. Instead, they are |
| 270 |
queued to HCI rx_queue and will be dispatched from HCI rx worker |
| 271 |
context (MSGRXWQ). This is done this way to allow a cmd or event handler |
| 272 |
to also execute other commands (for example, handling the |
| 273 |
NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an |
| 274 |
ANY_GET_PARAMETER to the reader A gate to get information on the target |
| 275 |
that was discovered). |
| 276 |
|
| 277 |
Typically, such an event will be propagated to NFC Core from MSGRXWQ context. |
| 278 |
|
| 279 |
Error management |
| 280 |
---------------- |
| 281 |
|
| 282 |
Errors that occur synchronously with the execution of an NFC Core request are |
| 283 |
simply returned as the execution result of the request. These are easy. |
| 284 |
|
| 285 |
Errors that occur asynchronously (e.g. in a background protocol handling thread) |
| 286 |
must be reported such that upper layers don't stay ignorant that something |
| 287 |
went wrong below and know that expected events will probably never happen. |
| 288 |
Handling of these errors is done as follows: |
| 289 |
|
| 290 |
- driver (pn544) fails to deliver an incoming frame: it stores the error such |
| 291 |
that any subsequent call to the driver will result in this error. Then it |
| 292 |
calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the |
| 293 |
problem above. shdlc stores a EREMOTEIO sticky status, which will trigger |
| 294 |
SMW to report above in turn. |
| 295 |
|
| 296 |
- SMW is basically a background thread to handle incoming and outgoing shdlc |
| 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 anymore because of an unrecoverable |
| 299 |
error that happened within shdlc or below. If the problem occurs during shdlc |
| 300 |
connection, the error is reported through the connect completion. |
| 301 |
|
| 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 complete the currently executing |
| 304 |
command with that error, or notify NFC Core directly if no command is |
| 305 |
executing. |
| 306 |
|
| 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 with an empty tag list to the user |
| 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 was sticky, lower levels will |
| 311 |
return it at next invocation. |