Documentation/driver-api/nfc/nfc-hci.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/nfc/nfc-hci.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/nfc/nfc-hci.rst
Extension
.rst
Size
13081 bytes
Lines
312
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct nfc_hci_ops {
	int (*open)(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 (*start_poll) (struct nfc_hci_dev *hdev,
			   u32 im_protocols, u32 tm_protocols);
	int (*dep_link_up)(struct nfc_hci_dev *hdev, struct nfc_target *target,
			   u8 comm_mode, u8 *gb, size_t gb_len);
	int (*dep_link_down)(struct nfc_hci_dev *hdev);
	int (*target_from_gate) (struct nfc_hci_dev *hdev, u8 gate,
				 struct nfc_target *target);
	int (*complete_target_discovered) (struct nfc_hci_dev *hdev, u8 gate,
					   struct nfc_target *target);
	int (*im_transceive) (struct nfc_hci_dev *hdev,
			      struct nfc_target *target, struct sk_buff *skb,
			      data_exchange_cb_t cb, void *cb_context);
	int (*tm_send)(struct nfc_hci_dev *hdev, struct sk_buff *skb);
	int (*check_presence)(struct nfc_hci_dev *hdev,
			      struct nfc_target *target);
	int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
			      struct sk_buff *skb);
  };

- open() and close() shall turn the hardware on and off.
- hci_ready() is an optional entry point that is called right after the hci
  session has been set up. The driver can use it to do additional initialization
  that must be performed using HCI commands.
- xmit() shall simply write a frame to the physical link.
- 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.
- dep_link_up() is called after a p2p target has been detected, to finish
  the p2p connection setup with hardware parameters that need to be passed back
  to nfc core.
- dep_link_down() is called to bring the p2p link down.
- target_from_gate() is an optional entrypoint to return the nfc protocols
  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.
- im_transceive() 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. The data exchange command itself must be sent
  asynchronously.
- tm_send() is called to send data in the case of a p2p connection
- 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
- event_received() is called to handle an event coming from the chip. Driver
  can handle the event or return 1 to let HCI attempt standard processing.

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
This must be done from a context that can sleep.

PHY Management
--------------

The physical link (i2c, ...) management is defined by the following structure::

  struct nfc_phy_ops {
	int (*write)(void *dev_id, struct sk_buff *skb);
	int (*enable)(void *dev_id);
	void (*disable)(void *dev_id);
  };

Annotation

Implementation Notes