^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) HCI backend for NFC Core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) - Author: Eric Lapuyade, Samuel Ortiz
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) - Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) backend, implementing an abstract nfc device and translating NFC Core API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) to HCI commands and events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) HCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) HCI registers as an nfc device with NFC Core. Requests coming from userspace are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) routed through netlink sockets to NFC Core and then to HCI. From this point,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) they are translated in a sequence of HCI commands sent to the HCI layer in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) host controller (the chip). Commands can be executed synchronously (the sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) context blocks waiting for response) or asynchronously (the response is returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) from HCI Rx context).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) HCI events can also be received from the host controller. They will be handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) and a translation will be forwarded to NFC Core as needed. There are hooks to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) let the HCI driver handle proprietary events or override standard behavior.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) HCI uses 2 execution contexts:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) - one for executing commands : nfc_hci_msg_tx_work(). Only one command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) can be executing at any given moment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) - one for dispatching received events and commands : nfc_hci_msg_rx_work().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) HCI Session initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The Session initialization is an HCI standard which must unfortunately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) support proprietary gates. This is the reason why the driver will pass a list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) of proprietary gates that must be part of the session. HCI will ensure all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) those gates have pipes connected when the hci device is set up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) In case the chip supports pre-opened gates and pseudo-static pipes, the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) can pass that information to HCI core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) HCI Gates and Pipes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) A gate defines the 'port' where some service can be found. In order to access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) a service, one must create a pipe to that gate and open it. In this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) implementation, pipes are totally hidden. The public API only knows gates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) This is consistent with the driver need to send commands to proprietary gates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) without knowing the pipe connected to it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) Driver interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) A driver is generally written in two parts : the physical link management and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) the HCI management. This makes it easier to maintain a driver for a chip that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) can be connected using various phy (i2c, spi, ...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) HCI Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) A driver would normally register itself with HCI and provide the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) entry points::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) struct nfc_hci_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) int (*open)(struct nfc_hci_dev *hdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) void (*close)(struct nfc_hci_dev *hdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) int (*hci_ready) (struct nfc_hci_dev *hdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) int (*xmit) (struct nfc_hci_dev *hdev, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) int (*start_poll) (struct nfc_hci_dev *hdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) u32 im_protocols, u32 tm_protocols);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) int (*dep_link_up)(struct nfc_hci_dev *hdev, struct nfc_target *target,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) u8 comm_mode, u8 *gb, size_t gb_len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) int (*dep_link_down)(struct nfc_hci_dev *hdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) int (*target_from_gate) (struct nfc_hci_dev *hdev, u8 gate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) struct nfc_target *target);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) struct nfc_target *target);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) int (*im_transceive) (struct nfc_hci_dev *hdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) struct nfc_target *target, struct sk_buff *skb,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) data_exchange_cb_t cb, void *cb_context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) int (*tm_send)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) int (*check_presence)(struct nfc_hci_dev *hdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) struct nfc_target *target);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) - open() and close() shall turn the hardware on and off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) - hci_ready() is an optional entry point that is called right after the hci
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) session has been set up. The driver can use it to do additional initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) that must be performed using HCI commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) - xmit() shall simply write a frame to the physical link.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) - start_poll() is an optional entrypoint that shall set the hardware in polling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) mode. This must be implemented only if the hardware uses proprietary gates or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) mechanism slightly different from the HCI standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) - dep_link_up() is called after a p2p target has been detected, to finish
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) the p2p connection setup with hardware parameters that need to be passed back
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) to nfc core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) - dep_link_down() is called to bring the p2p link down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - target_from_gate() is an optional entrypoint to return the nfc protocols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) corresponding to a proprietary gate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) - complete_target_discovered() is an optional entry point to let the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) perform additional proprietary processing necessary to auto activate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) discovered target.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) - im_transceive() must be implemented by the driver if proprietary HCI commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) are required to send data to the tag. Some tag types will require custom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) commands, others can be written to using the standard HCI commands. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) can check the tag type and either do proprietary processing, or return 1 to ask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) for standard processing. The data exchange command itself must be sent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) asynchronously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - tm_send() is called to send data in the case of a p2p connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) - check_presence() is an optional entry point that will be called regularly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) by the core to check that an activated tag is still in the field. If this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) not implemented, the core will not be able to push tag_lost events to the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) - event_received() is called to handle an event coming from the chip. Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) can handle the event or return 1 to let HCI attempt standard processing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) On the rx path, the driver is responsible to push incoming HCP frames to HCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) This must be done from a context that can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) PHY Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) The physical link (i2c, ...) management is defined by the following structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) struct nfc_phy_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) int (*write)(void *dev_id, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) int (*enable)(void *dev_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) void (*disable)(void *dev_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) enable():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) turn the phy on (power on), make it ready to transfer data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) disable():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) turn the phy off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) write():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Send a data frame to the chip. Note that to enable higher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) layers such as an llc to store the frame for re-emission, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) function must not alter the skb. It must also not return a positive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) result (return 0 for success, negative for failure).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) Data coming from the chip shall be sent directly to nfc_hci_recv_frame().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) LLC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Communication between the CPU and the chip often requires some link layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) protocol. Those are isolated as modules managed by the HCI layer. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) currently two modules : nop (raw transfert) and shdlc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) A new llc must implement the following functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) struct nfc_llc_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) rcv_to_hci_t rcv_to_hci, int tx_headroom,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) int tx_tailroom, int *rx_headroom, int *rx_tailroom,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) llc_failure_t llc_failure);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) void (*deinit) (struct nfc_llc *llc);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) int (*start) (struct nfc_llc *llc);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) int (*stop) (struct nfc_llc *llc);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) init():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) allocate and init your private storage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) deinit():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) cleanup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) start():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) establish the logical connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) stop ():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) terminate the logical connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) rcv_from_drv():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) handle data coming from the chip, going to HCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) xmit_from_hci():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) handle data sent by HCI, going to the chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) The llc must be registered with nfc before it can be used. Do that by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) calling::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Again, note that the llc does not handle the physical link. It is thus very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) easy to mix any physical link with any llc for a given chip driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Included Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) An HCI based driver for an NXP PN544, connected through I2C bus, and using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) shdlc is included.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Execution Contexts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) The execution contexts are the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) - IRQ handler (IRQH):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) fast, cannot sleep. sends incoming frames to HCI where they are passed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) the current llc. In case of shdlc, the frame is queued in shdlc rx queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) - SHDLC State Machine worker (SMW)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Only when llc_shdlc is used: handles shdlc rx & tx queues.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) Dispatches HCI cmd responses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) - HCI Tx Cmd worker (MSGTXWQ)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) Serializes execution of HCI commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Completes execution in case of response timeout.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) - HCI Rx worker (MSGRXWQ)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) Dispatches incoming HCI commands or events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) - Syscall context from a userspace call (SYSCALL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Any entrypoint in HCI called from NFC Core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) Workflow executing an HCI command (using shdlc)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) -----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) Executing an HCI command can easily be performed synchronously using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) following API::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) const u8 *param, size_t param_len, struct sk_buff **skb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) The API must be invoked from a context that can sleep. Most of the time, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) will be the syscall context. skb will return the result that was received in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) the response.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Internally, execution is asynchronous. So all this API does is to enqueue the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) HCI command, setup a local wait queue on stack, and wait_event() for completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) The wait is not interruptible because it is guaranteed that the command will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) complete after some short timeout anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) This function will dequeue the next pending command and send its HCP fragments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) to the lower layer which happens to be shdlc. It will then start a timer to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) able to complete the command with a timeout error if no response arrive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) SMW context gets scheduled and invokes nfc_shdlc_sm_work(). This function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) handles shdlc framing in and out. It uses the driver xmit to send frames and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) receives incoming frames in an skb queue filled from the driver IRQ handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) form complete HCI frames, which can be a response, command, or event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) HCI Responses are dispatched immediately from this context to unblock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) waiting command execution. Response processing involves invoking the completion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) The completion callback will then wake the syscall context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) It is also possible to execute the command asynchronously using this API::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) const u8 *param, size_t param_len,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) data_exchange_cb_t cb, void *cb_context)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) The workflow is the same, except that the API call returns immediately, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) the callback will be called with the result from the SMW context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) Workflow receiving an HCI event or command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) HCI commands or events are not dispatched from SMW context. Instead, they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) queued to HCI rx_queue and will be dispatched from HCI rx worker
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) context (MSGRXWQ). This is done this way to allow a cmd or event handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) to also execute other commands (for example, handling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) ANY_GET_PARAMETER to the reader A gate to get information on the target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) that was discovered).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) Typically, such an event will be propagated to NFC Core from MSGRXWQ context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) Error management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Errors that occur synchronously with the execution of an NFC Core request are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) simply returned as the execution result of the request. These are easy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Errors that occur asynchronously (e.g. in a background protocol handling thread)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) must be reported such that upper layers don't stay ignorant that something
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) went wrong below and know that expected events will probably never happen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) Handling of these errors is done as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) - driver (pn544) fails to deliver an incoming frame: it stores the error such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) that any subsequent call to the driver will result in this error. Then it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) problem above. shdlc stores a EREMOTEIO sticky status, which will trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) SMW to report above in turn.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) - SMW is basically a background thread to handle incoming and outgoing shdlc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) frames. This thread will also check the shdlc sticky status and report to HCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) when it discovers it is not able to run anymore because of an unrecoverable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) error that happened within shdlc or below. If the problem occurs during shdlc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) connection, the error is reported through the connect completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) error from a lower layer, HCI will either complete the currently executing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) command with that error, or notify NFC Core directly if no command is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) executing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) - NFC Core: when NFC Core is notified of an error from below and polling is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) active, it will send a tag discovered event with an empty tag list to the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) space to let it know that the poll operation will never be able to detect a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) tag. If polling is not active and the error was sticky, lower levels will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) return it at next invocation.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags