Commit a202abb1 authored by Eric Lapuyade's avatar Eric Lapuyade Committed by John W. Linville
Browse files

NFC: Update Documentation/nfc-hci.txt



Document the new HCI ops and fix a few typos and spelling mistakes.
Signed-off-by: default avatarEric Lapuyade <eric.lapuyade@intel.com>
Signed-off-by: default avatarSamuel Ortiz <sameo@linux.intel.com>
Signed-off-by: default avatarJohn W. Linville <linville@tuxdriver.com>
parent 1676f751
...@@ -22,9 +22,9 @@ response to arrive. ...@@ -22,9 +22,9 @@ response to arrive.
HCI events can also be received from the host controller. They will be handled HCI events can also be received from the host controller. They will be handled
and a translation will be forwarded to NFC Core as needed. and a translation will be forwarded to NFC Core as needed.
HCI uses 2 execution contexts: HCI uses 2 execution contexts:
- one if for executing commands : nfc_hci_msg_tx_work(). Only one command - one for executing commands : nfc_hci_msg_tx_work(). Only one command
can be executing at any given moment. can be executing at any given moment.
- one if for dispatching received events and responses : nfc_hci_msg_rx_work() - one for dispatching received events and commands : nfc_hci_msg_rx_work().
HCI Session initialization: HCI Session initialization:
--------------------------- ---------------------------
...@@ -52,18 +52,42 @@ entry points: ...@@ -52,18 +52,42 @@ entry points:
struct nfc_hci_ops { struct nfc_hci_ops {
int (*open)(struct nfc_hci_dev *hdev); int (*open)(struct nfc_hci_dev *hdev);
void (*close)(struct nfc_hci_dev *hdev); void (*close)(struct nfc_hci_dev *hdev);
int (*hci_ready) (struct nfc_hci_dev *hdev);
int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb); int (*xmit)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols); int (*start_poll)(struct nfc_hci_dev *hdev, u32 protocols);
int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate, int (*target_from_gate)(struct nfc_hci_dev *hdev, u8 gate,
struct nfc_target *target); struct nfc_target *target);
int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
struct nfc_target *target);
int (*data_exchange) (struct nfc_hci_dev *hdev,
struct nfc_target *target,
struct sk_buff *skb, struct sk_buff **res_skb);
int (*check_presence)(struct nfc_hci_dev *hdev,
struct nfc_target *target);
}; };
open() and close() shall turn the hardware on and off. xmit() shall simply - open() and close() shall turn the hardware on and off.
write a frame to the chip. start_poll() is an optional entrypoint that shall - hci_ready() is an optional entry point that is called right after the hci
set the hardware in polling mode. This must be implemented only if the hardware session has been set up. The driver can use it to do additional initialization
uses proprietary gates or a mechanism slightly different from the HCI standard. that must be performed using HCI commands.
target_from_gate() is another optional entrypoint to return the protocols - xmit() shall simply write a frame to the chip.
- start_poll() is an optional entrypoint that shall set the hardware in polling
mode. This must be implemented only if the hardware uses proprietary gates or a
mechanism slightly different from the HCI standard.
- target_from_gate() is an optional entrypoint to return the nfc protocols
corresponding to a proprietary gate. corresponding to a proprietary gate.
- complete_target_discovered() is an optional entry point to let the driver
perform additional proprietary processing necessary to auto activate the
discovered target.
- data_exchange() must be implemented by the driver if proprietary HCI commands
are required to send data to the tag. Some tag types will require custom
commands, others can be written to using the standard HCI commands. The driver
can check the tag type and either do proprietary processing, or return 1 to ask
for standard processing.
- check_presence() is an optional entry point that will be called regularly
by the core to check that an activated tag is still in the field. If this is
not implemented, the core will not be able to push tag_lost events to the user
space
On the rx path, the driver is responsible to push incoming HCP frames to HCI On the rx path, the driver is responsible to push incoming HCP frames to HCI
using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
...@@ -99,7 +123,8 @@ fast, cannot sleep. stores incoming frames into an shdlc rx queue ...@@ -99,7 +123,8 @@ fast, cannot sleep. stores incoming frames into an shdlc rx queue
handles shdlc rx & tx queues. Dispatches HCI cmd responses. handles shdlc rx & tx queues. Dispatches HCI cmd responses.
- HCI Tx Cmd worker (MSGTXWQ) - HCI Tx Cmd worker (MSGTXWQ)
Serialize execution of HCI commands. Complete execution in case of resp timeout. Serializes execution of HCI commands. Completes execution in case of response
timeout.
- HCI Rx worker (MSGRXWQ) - HCI Rx worker (MSGRXWQ)
Dispatches incoming HCI commands or events. Dispatches incoming HCI commands or events.
...@@ -133,11 +158,11 @@ able to complete the command with a timeout error if no response arrive. ...@@ -133,11 +158,11 @@ able to complete the command with a timeout error if no response arrive.
SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function
handles shdlc framing in and out. It uses the driver xmit to send frames and handles shdlc framing in and out. It uses the driver xmit to send frames and
receives incoming frames in an skb queue filled from the driver IRQ handler. receives incoming frames in an skb queue filled from the driver IRQ handler.
SHDLC I(nformation) frames payload are HCP fragments. They are agregated to SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to
form complete HCI frames, which can be a response, command, or event. form complete HCI frames, which can be a response, command, or event.
HCI Responses are dispatched immediately from this context to unblock HCI Responses are dispatched immediately from this context to unblock
waiting command execution. Reponse processing involves invoking the completion waiting command execution. Response processing involves invoking the completion
callback that was provided by nfc_hci_msg_tx_work() when it sent the command. callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
The completion callback will then wake the syscall context. The completion callback will then wake the syscall context.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment