tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
NFC: Update Documentation/nfc-hci.txt
Document the new HCI ops and fix a few typos and spelling mistakes.
Signed-off-by: Eric Lapuyade <eric.lapuyade@intel.com>
Signed-off-by: Samuel Ortiz <sameo@linux.intel.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
authored by
Eric Lapuyade
and committed by
John W. Linville
a202abb1
1676f751
+35
-10
+35
-10
Documentation/nfc/nfc-hci.txt
+35
-10
Documentation/nfc/nfc-hci.txt
···
22
22
HCI events can also be received from the host controller. They will be handled
23
23
and a translation will be forwarded to NFC Core as needed.
24
24
HCI uses 2 execution contexts:
25
-
- one if for executing commands : nfc_hci_msg_tx_work(). Only one command
25
+
- one for executing commands : nfc_hci_msg_tx_work(). Only one command
26
26
can be executing at any given moment.
27
-
- one if for dispatching received events and responses : nfc_hci_msg_rx_work()
27
+
- one for dispatching received events and commands : nfc_hci_msg_rx_work().
28
28
29
29
HCI Session initialization:
30
30
---------------------------
···
52
52
struct nfc_hci_ops {
53
53
int (*open)(struct nfc_hci_dev *hdev);
54
54
void (*close)(struct nfc_hci_dev *hdev);
55
+
int (*hci_ready) (struct nfc_hci_dev *hdev);
55
56
int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
56
57
int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols);
57
58
int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate,
58
59
struct nfc_target *target);
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);
59
67
};
60
68
61
-
open() and close() shall turn the hardware on and off. xmit() shall simply
62
-
write a frame to the chip. start_poll() is an optional entrypoint that shall
63
-
set the hardware in polling mode. This must be implemented only if the hardware
64
-
uses proprietary gates or a mechanism slightly different from the HCI standard.
65
-
target_from_gate() is another optional entrypoint to return the protocols
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
66
78
corresponding to a proprietary gate.
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
67
91
68
92
On the rx path, the driver is responsible to push incoming HCP frames to HCI
69
93
using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
···
123
99
handles shdlc rx & tx queues. Dispatches HCI cmd responses.
124
100
125
101
- HCI Tx Cmd worker (MSGTXWQ)
126
-
Serialize execution of HCI commands. Complete execution in case of resp timeout.
102
+
Serializes execution of HCI commands. Completes execution in case of response
103
+
timeout.
127
104
128
105
- HCI Rx worker (MSGRXWQ)
129
106
Dispatches incoming HCI commands or events.
···
158
133
SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function
159
134
handles shdlc framing in and out. It uses the driver xmit to send frames and
160
135
receives incoming frames in an skb queue filled from the driver IRQ handler.
161
-
SHDLC I(nformation) frames payload are HCP fragments. They are agregated to
136
+
SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to
162
137
form complete HCI frames, which can be a response, command, or event.
163
138
164
139
HCI Responses are dispatched immediately from this context to unblock
165
-
waiting command execution. Reponse processing involves invoking the completion
140
+
waiting command execution. Response processing involves invoking the completion
166
141
callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
167
142
The completion callback will then wake the syscall context.
168
143