Merge tag 'nfc-next-3.9-1' of git://git.kernel.org/pub/scm/linux/kernel/git/sameo/nfc-next

HCI registers as an nfc device with NFC Core. Requests coming from userspace are

routed through netlink sockets to NFC Core and then to HCI. From this point,

they are translated in a sequence of HCI commands sent to the HCI layer in the

host controller (the chip). The sending context blocks while waiting for the

response to arrive.

host controller (the chip). Commands can be executed synchronously (the sending

context blocks waiting for response) or asynchronously (the response is returned

from HCI Rx context).

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. There are hooks to

let the HCI driver handle proprietary events or override standard behavior.

HCI uses 2 execution contexts:

- one for executing commands : nfc_hci_msg_tx_work(). Only one command

can be executing at any given moment.

support proprietary gates. This is the reason why the driver will pass a list

of proprietary gates that must be part of the session. HCI will ensure all

those gates have pipes connected when the hci device is set up.

In case the chip supports pre-opened gates and pseudo-static pipes, the driver

can pass that information to HCI core.

HCI Gates and Pipes

-------------------

Driver interface

----------------

A driver is generally written in two parts : the physical link management and

the HCI management. This makes it easier to maintain a driver for a chip that

can be connected using various phy (i2c, spi, ...)

HCI Management

--------------

A driver would normally register itself with HCI and provide the following

entry points:

	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 protocols);

	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 (*data_exchange) (struct nfc_hci_dev *hdev,

			      struct nfc_target *target,

			      struct sk_buff *skb, struct sk_buff **res_skb);

	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 chip.

- 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.

- data_exchange() must be implemented by the driver if proprietary HCI commands

- 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.

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.

SHDLC

-----

PHY Management

--------------

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

struct nfc_phy_ops {

	int (*write)(void *dev_id, struct sk_buff *skb);

	int (*enable)(void *dev_id);

	void (*disable)(void *dev_id);

};

enable(): turn the phy on (power on), make it ready to transfer data

disable(): turn the phy off

write(): Send a data frame to the chip. Note that to enable higher

layers such as an llc to store the frame for re-emission, this function must

not alter the skb. It must also not return a positive result (return 0 for

success, negative for failure).

Data coming from the chip shall be sent directly to nfc_hci_recv_frame().

LLC

---

Communication between the CPU and the chip often requires some link layer

protocol. Those are isolated as modules managed by the HCI layer. There are

currently two modules : nop (raw transfert) and shdlc.

A new llc must implement the following functions:

struct nfc_llc_ops {

	void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,

		       rcv_to_hci_t rcv_to_hci, int tx_headroom,

		       int tx_tailroom, int *rx_headroom, int *rx_tailroom,

		       llc_failure_t llc_failure);

	void (*deinit) (struct nfc_llc *llc);

	int (*start) (struct nfc_llc *llc);

	int (*stop) (struct nfc_llc *llc);

	void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);

	int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);

};

- init() : allocate and init your private storage

- deinit() : cleanup

- start() : establish the logical connection

- stop () : terminate the logical connection

- rcv_from_drv() : handle data coming from the chip, going to HCI

- xmit_from_hci() : handle data sent by HCI, going to the chip

Most chips use shdlc to ensure integrity and delivery ordering of the HCP

frames between the host controller (the chip) and hosts (entities connected

to the chip, like the cpu). In order to simplify writing the driver, an shdlc

layer is available for use by the driver.

When used, the driver actually registers with shdlc, and shdlc will register

with HCI. HCI sees shdlc as the driver and thus send its HCP frames

through shdlc->xmit.

SHDLC adds a new execution context (nfc_shdlc_sm_work()) to run its state

machine and handle both its rx and tx path.

The llc must be registered with nfc before it can be used. Do that by

calling nfc_llc_register(const char *name, struct nfc_llc_ops *ops);

Again, note that the llc does not handle the physical link. It is thus very

easy to mix any physical link with any llc for a given chip driver.

Included Drivers

----------------

The execution contexts are the following:

- IRQ handler (IRQH):

fast, cannot sleep. stores incoming frames into an shdlc rx queue

fast, cannot sleep. sends incoming frames to HCI where they are passed to

the current llc. In case of shdlc, the frame is queued in shdlc rx queue.

- SHDLC State Machine worker (SMW)

handles shdlc rx & tx queues. Dispatches HCI cmd responses.

Only when llc_shdlc is used: handles shdlc rx & tx queues.

Dispatches HCI cmd responses.

- HCI Tx Cmd worker (MSGTXWQ)

Serializes execution of HCI commands. Completes execution in case of response

callback that was provided by nfc_hci_msg_tx_work() when it sent the command.

The completion callback will then wake the syscall context.

It is also possible to execute the command asynchronously using this API:

static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,

			       const u8 *param, size_t param_len,

			       data_exchange_cb_t cb, void *cb_context)

The workflow is the same, except that the API call returns immediately, and

the callback will be called with the result from the SMW context.

Workflow receiving an HCI event or command

------------------------------------------

Kernel driver for the NXP Semiconductors PN544 Near Field

Communication chip

Author: Jari Vanhala

Contact: Matti Aaltonen (matti.j.aaltonen at nokia.com)

General

-------

The PN544 is an integrated transmission module for contactless

communication. The driver goes under drives/nfc/ and is compiled as a

module named "pn544". It registers a misc device and creates a device

file named "/dev/pn544".

module named "pn544".

Host Interfaces: I2C, SPI and HSU, this driver supports currently only I2C.

The Interface

-------------

The driver offers a sysfs interface for a hardware test and an IOCTL

interface for selecting between two operating modes. There are read,

write and poll functions for transferring messages. The two operating

modes are the normal (HCI) mode and the firmware update mode.

PN544 is controlled by sending messages from the userspace to the

chip. The main function of the driver is just to pass those messages

without caring about the message content.

Protocols

---------

For the ETSI HCI specification see

http://www.etsi.org/WebSite/Technologies/ProtocolSpecification.aspx

The Hardware Test

-----------------

The idea of the test is that it can performed by reading from the

corresponding sysfs file. The test is implemented in the board file

and it should test that PN544 can be put into the firmware update

mode. If the test is not implemented the sysfs file does not get

created.

Example:

> cat /sys/module/pn544/drivers/i2c\:pn544/3-002b/nfc_test

1

Normal Operation

----------------

PN544 is powered up when the device file is opened, otherwise it's

turned off. Only one instance can use the device at a time.

Userspace applications control PN544 with HCI messages. The hardware

sends an interrupt when data is available for reading. Data is

physically read when the read function is called by a userspace

application. Poll() checks the read interrupt state. Configuration and

self testing are also done from the userspace using read and write.

Example platform data:

static int rx71_pn544_nfc_request_resources(struct i2c_client *client)

{

	/* Get and setup the HW resources for the device */

}

static void rx71_pn544_nfc_free_resources(void)

{

	/* Release the HW resources */

}

static void rx71_pn544_nfc_enable(int fw)

{

	/* Turn the device on */

}

static int rx71_pn544_nfc_test(void)

{

	/*

	 * Put the device into the FW update mode

	 * and then back to the normal mode.

	 * Check the behavior and return one on success,

	 * zero on failure.

	 */

}

static void rx71_pn544_nfc_disable(void)

{

	/* turn the power off */

}

static struct pn544_nfc_platform_data rx71_nfc_data = {

	.request_resources = rx71_pn544_nfc_request_resources,

	.free_resources = rx71_pn544_nfc_free_resources,

	.enable = rx71_pn544_nfc_enable,

	.test = rx71_pn544_nfc_test,

	.disable = rx71_pn544_nfc_disable,

};

menu "Near Field Communication (NFC) devices"

	depends on NFC

config PN544_HCI_NFC

	tristate "HCI PN544 NFC driver"

	depends on I2C && NFC_HCI && NFC_SHDLC

	select CRC_CCITT

	default n

	---help---

	  NXP PN544 i2c driver.

	  This is a driver based on the SHDLC and HCI NFC kernel layers and

	  will thus not work with NXP libnfc library.

	  To compile this driver as a module, choose m here. The module will

	  be called pn544_hci.

config NFC_PN533

	tristate "NXP PN533 USB driver"

	depends on USB

	  Say Y here to compile support for Texas Instrument's NFC WiLink driver

	  into the kernel or say M to compile it as module.

source "drivers/nfc/pn544/Kconfig"

endmenu

# Makefile for nfc devices

#

obj-$(CONFIG_PN544_HCI_NFC)	+= pn544/

obj-$(CONFIG_NFC_PN544)		+= pn544/

obj-$(CONFIG_NFC_PN533)		+= pn533.o

obj-$(CONFIG_NFC_WILINK)	+= nfcwilink.o

	drv->ndev = nci_allocate_device(&nfcwilink_ops,

					protocols,

					NFC_SE_NONE,

					NFCWILINK_HDR_LEN,

					0);

	if (!drv->ndev) {