tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
NFC: update HCI documentation
Signed-off-by: Eric Lapuyade <eric.lapuyade@intel.com>
Signed-off-by: Samuel Ortiz <sameo@linux.intel.com>
authored by
Eric Lapuyade
and committed by
Samuel Ortiz
2ad554a5
a0f36536
+103
-26
+103
-26
Documentation/nfc/nfc-hci.txt
+103
-26
Documentation/nfc/nfc-hci.txt
···
17
17
HCI registers as an nfc device with NFC Core. Requests coming from userspace are
18
18
routed through netlink sockets to NFC Core and then to HCI. From this point,
19
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.
20
+
host controller (the chip). Commands can be executed synchronously (the sending
21
+
context blocks waiting for response) or asynchronously (the response is returned
22
+
from HCI Rx context).
22
23
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
+
and a translation will be forwarded to NFC Core as needed. There are hooks to
25
+
let the HCI driver handle proprietary events or override standard behavior.
24
26
HCI uses 2 execution contexts:
25
27
- one for executing commands : nfc_hci_msg_tx_work(). Only one command
26
28
can be executing at any given moment.
···
35
33
support proprietary gates. This is the reason why the driver will pass a list
36
34
of proprietary gates that must be part of the session. HCI will ensure all
37
35
those gates have pipes connected when the hci device is set up.
36
+
In case the chip supports pre-opened gates and pseudo-static pipes, the driver
37
+
can pass that information to HCI core.
38
38
39
39
HCI Gates and Pipes
40
40
-------------------
···
50
46
Driver interface
51
47
----------------
52
48
49
+
A driver is generally written in two parts : the physical link management and
50
+
the HCI management. This makes it easier to maintain a driver for a chip that
51
+
can be connected using various phy (i2c, spi, ...)
52
+
53
+
HCI Management
54
+
--------------
55
+
53
56
A driver would normally register itself with HCI and provide the following
54
57
entry points:
55
58
···
64
53
int (*open)(struct nfc_hci_dev *hdev);
65
54
void (*close)(struct nfc_hci_dev *hdev);
66
55
int (*hci_ready) (struct nfc_hci_dev *hdev);
67
-
int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
68
-
int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols);
69
-
int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate,
70
-
struct nfc_target *target);
56
+
int (*xmit) (struct nfc_hci_dev *hdev, struct sk_buff *skb);
57
+
int (*start_poll) (struct nfc_hci_dev *hdev,
58
+
u32 im_protocols, u32 tm_protocols);
59
+
int (*dep_link_up)(struct nfc_hci_dev *hdev, struct nfc_target *target,
60
+
u8 comm_mode, u8 *gb, size_t gb_len);
61
+
int (*dep_link_down)(struct nfc_hci_dev *hdev);
62
+
int (*target_from_gate) (struct nfc_hci_dev *hdev, u8 gate,
63
+
struct nfc_target *target);
71
64
int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
72
65
struct nfc_target *target);
73
-
int (*data_exchange) (struct nfc_hci_dev *hdev,
74
-
struct nfc_target *target,
75
-
struct sk_buff *skb, struct sk_buff **res_skb);
66
+
int (*im_transceive) (struct nfc_hci_dev *hdev,
67
+
struct nfc_target *target, struct sk_buff *skb,
68
+
data_exchange_cb_t cb, void *cb_context);
69
+
int (*tm_send)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
76
70
int (*check_presence)(struct nfc_hci_dev *hdev,
77
71
struct nfc_target *target);
72
+
int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
73
+
struct sk_buff *skb);
78
74
};
79
75
80
76
- open() and close() shall turn the hardware on and off.
81
77
- hci_ready() is an optional entry point that is called right after the hci
82
78
session has been set up. The driver can use it to do additional initialization
83
79
that must be performed using HCI commands.
84
-
- xmit() shall simply write a frame to the chip.
80
+
- xmit() shall simply write a frame to the physical link.
85
81
- start_poll() is an optional entrypoint that shall set the hardware in polling
86
82
mode. This must be implemented only if the hardware uses proprietary gates or a
87
83
mechanism slightly different from the HCI standard.
84
+
- dep_link_up() is called after a p2p target has been detected, to finish
85
+
the p2p connection setup with hardware parameters that need to be passed back
86
+
to nfc core.
87
+
- dep_link_down() is called to bring the p2p link down.
88
88
- target_from_gate() is an optional entrypoint to return the nfc protocols
89
89
corresponding to a proprietary gate.
90
90
- complete_target_discovered() is an optional entry point to let the driver
91
91
perform additional proprietary processing necessary to auto activate the
92
92
discovered target.
93
-
- data_exchange() must be implemented by the driver if proprietary HCI commands
93
+
- im_transceive() must be implemented by the driver if proprietary HCI commands
94
94
are required to send data to the tag. Some tag types will require custom
95
95
commands, others can be written to using the standard HCI commands. The driver
96
96
can check the tag type and either do proprietary processing, or return 1 to ask
97
-
for standard processing.
97
+
for standard processing. The data exchange command itself must be sent
98
+
asynchronously.
99
+
- tm_send() is called to send data in the case of a p2p connection
98
100
- check_presence() is an optional entry point that will be called regularly
99
101
by the core to check that an activated tag is still in the field. If this is
100
102
not implemented, the core will not be able to push tag_lost events to the user
101
103
space
104
+
- event_received() is called to handle an event coming from the chip. Driver
105
+
can handle the event or return 1 to let HCI attempt standard processing.
102
106
103
107
On the rx path, the driver is responsible to push incoming HCP frames to HCI
104
108
using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
105
109
This must be done from a context that can sleep.
106
110
107
-
SHDLC
108
-
-----
111
+
PHY Management
112
+
--------------
109
113
110
-
Most chips use shdlc to ensure integrity and delivery ordering of the HCP
111
-
frames between the host controller (the chip) and hosts (entities connected
112
-
to the chip, like the cpu). In order to simplify writing the driver, an shdlc
113
-
layer is available for use by the driver.
114
-
When used, the driver actually registers with shdlc, and shdlc will register
115
-
with HCI. HCI sees shdlc as the driver and thus send its HCP frames
116
-
through shdlc->xmit.
117
-
SHDLC adds a new execution context (nfc_shdlc_sm_work()) to run its state
118
-
machine and handle both its rx and tx path.
114
+
The physical link (i2c, ...) management is defined by the following struture:
115
+
116
+
struct nfc_phy_ops {
117
+
int (*write)(void *dev_id, struct sk_buff *skb);
118
+
int (*enable)(void *dev_id);
119
+
void (*disable)(void *dev_id);
120
+
};
121
+
122
+
enable(): turn the phy on (power on), make it ready to transfer data
123
+
disable(): turn the phy off
124
+
write(): Send a data frame to the chip. Note that to enable higher
125
+
layers such as an llc to store the frame for re-emission, this function must
126
+
not alter the skb. It must also not return a positive result (return 0 for
127
+
success, negative for failure).
128
+
129
+
Data coming from the chip shall be sent directly to nfc_hci_recv_frame().
130
+
131
+
LLC
132
+
---
133
+
134
+
Communication between the CPU and the chip often requires some link layer
135
+
protocol. Those are isolated as modules managed by the HCI layer. There are
136
+
currently two modules : nop (raw transfert) and shdlc.
137
+
A new llc must implement the following functions:
138
+
139
+
struct nfc_llc_ops {
140
+
void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,
141
+
rcv_to_hci_t rcv_to_hci, int tx_headroom,
142
+
int tx_tailroom, int *rx_headroom, int *rx_tailroom,
143
+
llc_failure_t llc_failure);
144
+
void (*deinit) (struct nfc_llc *llc);
145
+
int (*start) (struct nfc_llc *llc);
146
+
int (*stop) (struct nfc_llc *llc);
147
+
void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);
148
+
int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
149
+
};
150
+
151
+
- init() : allocate and init your private storage
152
+
- deinit() : cleanup
153
+
- start() : establish the logical connection
154
+
- stop () : terminate the logical connection
155
+
- rcv_from_drv() : handle data coming from the chip, going to HCI
156
+
- xmit_from_hci() : handle data sent by HCI, going to the chip
157
+
158
+
The llc must be registered with nfc before it can be used. Do that by
159
+
calling nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
160
+
161
+
Again, note that the llc does not handle the physical link. It is thus very
162
+
easy to mix any physical link with any llc for a given chip driver.
119
163
120
164
Included Drivers
121
165
----------------
···
183
117
184
118
The execution contexts are the following:
185
119
- IRQ handler (IRQH):
186
-
fast, cannot sleep. stores incoming frames into an shdlc rx queue
120
+
fast, cannot sleep. sends incoming frames to HCI where they are passed to
121
+
the current llc. In case of shdlc, the frame is queued in shdlc rx queue.
187
122
188
123
- SHDLC State Machine worker (SMW)
189
-
handles shdlc rx & tx queues. Dispatches HCI cmd responses.
124
+
Only when llc_shdlc is used: handles shdlc rx & tx queues.
125
+
Dispatches HCI cmd responses.
190
126
191
127
- HCI Tx Cmd worker (MSGTXWQ)
192
128
Serializes execution of HCI commands. Completes execution in case of response
···
233
165
waiting command execution. Response processing involves invoking the completion
234
166
callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
235
167
The completion callback will then wake the syscall context.
168
+
169
+
It is also possible to execute the command asynchronously using this API:
170
+
171
+
static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
172
+
const u8 *param, size_t param_len,
173
+
data_exchange_cb_t cb, void *cb_context)
174
+
175
+
The workflow is the same, except that the API call returns immediately, and
176
+
the callback will be called with the result from the SMW context.
236
177
237
178
Workflow receiving an HCI event or command
238
179
------------------------------------------