From: Mauro Carvalho Chehab Date: Thu, 18 Apr 2019 16:02:23 +0000 (-0300) Subject: docs: nfc: convert to ReST X-Git-Url: http://git.lede-project.org./?a=commitdiff_plain;h=9e678dd886c11fad6511ffad4d400e3abde81d64;p=openwrt%2Fstaging%2Fblogic.git docs: nfc: convert to ReST Rename the nfc documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- diff --git a/Documentation/nfc/index.rst b/Documentation/nfc/index.rst new file mode 100644 index 000000000000..4f4947fce80d --- /dev/null +++ b/Documentation/nfc/index.rst @@ -0,0 +1,11 @@ +:orphan: + +======================== +Near Field Communication +======================== + +.. toctree:: + :maxdepth: 1 + + nfc-hci + nfc-pn544 diff --git a/Documentation/nfc/nfc-hci.rst b/Documentation/nfc/nfc-hci.rst new file mode 100644 index 000000000000..eb8a1a14e919 --- /dev/null +++ b/Documentation/nfc/nfc-hci.rst @@ -0,0 +1,311 @@ +======================== +HCI backend for NFC Core +======================== + +- Author: Eric Lapuyade, Samuel Ortiz +- Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com + +General +------- + +The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It +enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core +backend, implementing an abstract nfc device and translating NFC Core API +to HCI commands and events. + +HCI +--- + +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). 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. 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. +- one for dispatching received events and commands : nfc_hci_msg_rx_work(). + +HCI Session initialization +-------------------------- + +The Session initialization is an HCI standard which must unfortunately +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 +------------------- + +A gate defines the 'port' where some service can be found. In order to access +a service, one must create a pipe to that gate and open it. In this +implementation, pipes are totally hidden. The public API only knows gates. +This is consistent with the driver need to send commands to proprietary gates +without knowing the pipe connected to it. + +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:: + + 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); + }; + +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 + +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 +---------------- + +An HCI based driver for an NXP PN544, connected through I2C bus, and using +shdlc is included. + +Execution Contexts +------------------ + +The execution contexts are the following: +- IRQ handler (IRQH): +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) + + 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 timeout. + +- HCI Rx worker (MSGRXWQ) + + Dispatches incoming HCI commands or events. + +- Syscall context from a userspace call (SYSCALL) + + Any entrypoint in HCI called from NFC Core + +Workflow executing an HCI command (using shdlc) +----------------------------------------------- + +Executing an HCI command can easily be performed synchronously using the +following API:: + + int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, + const u8 *param, size_t param_len, struct sk_buff **skb) + +The API must be invoked from a context that can sleep. Most of the time, this +will be the syscall context. skb will return the result that was received in +the response. + +Internally, execution is asynchronous. So all this API does is to enqueue the +HCI command, setup a local wait queue on stack, and wait_event() for completion. +The wait is not interruptible because it is guaranteed that the command will +complete after some short timeout anyway. + +MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work(). +This function will dequeue the next pending command and send its HCP fragments +to the lower layer which happens to be shdlc. It will then start a timer to be +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 +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. +SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to +form complete HCI frames, which can be a response, command, or event. + +HCI Responses are dispatched immediately from this context to unblock +waiting command execution. Response processing involves invoking the completion +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 +------------------------------------------ + +HCI commands or events are not dispatched from SMW context. Instead, they are +queued to HCI rx_queue and will be dispatched from HCI rx worker +context (MSGRXWQ). This is done this way to allow a cmd or event handler +to also execute other commands (for example, handling the +NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an +ANY_GET_PARAMETER to the reader A gate to get information on the target +that was discovered). + +Typically, such an event will be propagated to NFC Core from MSGRXWQ context. + +Error management +---------------- + +Errors that occur synchronously with the execution of an NFC Core request are +simply returned as the execution result of the request. These are easy. + +Errors that occur asynchronously (e.g. in a background protocol handling thread) +must be reported such that upper layers don't stay ignorant that something +went wrong below and know that expected events will probably never happen. +Handling of these errors is done as follows: + +- driver (pn544) fails to deliver an incoming frame: it stores the error such + that any subsequent call to the driver will result in this error. Then it + calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the + problem above. shdlc stores a EREMOTEIO sticky status, which will trigger + SMW to report above in turn. + +- SMW is basically a background thread to handle incoming and outgoing shdlc + frames. This thread will also check the shdlc sticky status and report to HCI + when it discovers it is not able to run anymore because of an unrecoverable + error that happened within shdlc or below. If the problem occurs during shdlc + connection, the error is reported through the connect completion. + +- HCI: if an internal HCI error happens (frame is lost), or HCI is reported an + error from a lower layer, HCI will either complete the currently executing + command with that error, or notify NFC Core directly if no command is + executing. + +- NFC Core: when NFC Core is notified of an error from below and polling is + active, it will send a tag discovered event with an empty tag list to the user + space to let it know that the poll operation will never be able to detect a + tag. If polling is not active and the error was sticky, lower levels will + return it at next invocation. diff --git a/Documentation/nfc/nfc-hci.txt b/Documentation/nfc/nfc-hci.txt deleted file mode 100644 index 0dc078cab972..000000000000 --- a/Documentation/nfc/nfc-hci.txt +++ /dev/null @@ -1,290 +0,0 @@ -HCI backend for NFC Core - -Author: Eric Lapuyade, Samuel Ortiz -Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com - -General -------- - -The HCI layer implements much of the ETSI TS 102 622 V10.2.0 specification. It -enables easy writing of HCI-based NFC drivers. The HCI layer runs as an NFC Core -backend, implementing an abstract nfc device and translating NFC Core API -to HCI commands and events. - -HCI ---- - -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). 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. 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. -- one for dispatching received events and commands : nfc_hci_msg_rx_work(). - -HCI Session initialization: ---------------------------- - -The Session initialization is an HCI standard which must unfortunately -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 -------------------- - -A gate defines the 'port' where some service can be found. In order to access -a service, one must create a pipe to that gate and open it. In this -implementation, pipes are totally hidden. The public API only knows gates. -This is consistent with the driver need to send commands to proprietary gates -without knowing the pipe connected to it. - -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: - -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); -}; - -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 - -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 ----------------- - -An HCI based driver for an NXP PN544, connected through I2C bus, and using -shdlc is included. - -Execution Contexts ------------------- - -The execution contexts are the following: -- IRQ handler (IRQH): -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) -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 -timeout. - -- HCI Rx worker (MSGRXWQ) -Dispatches incoming HCI commands or events. - -- Syscall context from a userspace call (SYSCALL) -Any entrypoint in HCI called from NFC Core - -Workflow executing an HCI command (using shdlc) ------------------------------------------------ - -Executing an HCI command can easily be performed synchronously using the -following API: - -int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, - const u8 *param, size_t param_len, struct sk_buff **skb) - -The API must be invoked from a context that can sleep. Most of the time, this -will be the syscall context. skb will return the result that was received in -the response. - -Internally, execution is asynchronous. So all this API does is to enqueue the -HCI command, setup a local wait queue on stack, and wait_event() for completion. -The wait is not interruptible because it is guaranteed that the command will -complete after some short timeout anyway. - -MSGTXWQ context will then be scheduled and invoke nfc_hci_msg_tx_work(). -This function will dequeue the next pending command and send its HCP fragments -to the lower layer which happens to be shdlc. It will then start a timer to be -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 -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. -SHDLC I(nformation) frames payload are HCP fragments. They are aggregated to -form complete HCI frames, which can be a response, command, or event. - -HCI Responses are dispatched immediately from this context to unblock -waiting command execution. Response processing involves invoking the completion -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 ------------------------------------------- - -HCI commands or events are not dispatched from SMW context. Instead, they are -queued to HCI rx_queue and will be dispatched from HCI rx worker -context (MSGRXWQ). This is done this way to allow a cmd or event handler -to also execute other commands (for example, handling the -NFC_HCI_EVT_TARGET_DISCOVERED event from PN544 requires to issue an -ANY_GET_PARAMETER to the reader A gate to get information on the target -that was discovered). - -Typically, such an event will be propagated to NFC Core from MSGRXWQ context. - -Error management ----------------- - -Errors that occur synchronously with the execution of an NFC Core request are -simply returned as the execution result of the request. These are easy. - -Errors that occur asynchronously (e.g. in a background protocol handling thread) -must be reported such that upper layers don't stay ignorant that something -went wrong below and know that expected events will probably never happen. -Handling of these errors is done as follows: - -- driver (pn544) fails to deliver an incoming frame: it stores the error such -that any subsequent call to the driver will result in this error. Then it calls -the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem -above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to -report above in turn. - -- SMW is basically a background thread to handle incoming and outgoing shdlc -frames. This thread will also check the shdlc sticky status and report to HCI -when it discovers it is not able to run anymore because of an unrecoverable -error that happened within shdlc or below. If the problem occurs during shdlc -connection, the error is reported through the connect completion. - -- HCI: if an internal HCI error happens (frame is lost), or HCI is reported an -error from a lower layer, HCI will either complete the currently executing -command with that error, or notify NFC Core directly if no command is executing. - -- NFC Core: when NFC Core is notified of an error from below and polling is -active, it will send a tag discovered event with an empty tag list to the user -space to let it know that the poll operation will never be able to detect a tag. -If polling is not active and the error was sticky, lower levels will return it -at next invocation. diff --git a/Documentation/nfc/nfc-pn544.rst b/Documentation/nfc/nfc-pn544.rst new file mode 100644 index 000000000000..6b2d8aae0c4e --- /dev/null +++ b/Documentation/nfc/nfc-pn544.rst @@ -0,0 +1,34 @@ +============================================================================ +Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip +============================================================================ + + +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". + +Host Interfaces: I2C, SPI and HSU, this driver supports currently only I2C. + +Protocols +--------- + +In the normal (HCI) mode and in the firmware update mode read and +write functions behave a bit differently because the message formats +or the protocols are different. + +In the normal (HCI) mode the protocol used is derived from the ETSI +HCI specification. The firmware is updated using a specific protocol, +which is different from HCI. + +HCI messages consist of an eight bit header and the message body. The +header contains the message length. Maximum size for an HCI message is +33. In HCI mode sent messages are tested for a correct +checksum. Firmware update messages have the length in the second (MSB) +and third (LSB) bytes of the message. The maximum FW message length is +1024 bytes. + +For the ETSI HCI specification see +http://www.etsi.org/WebSite/Technologies/ProtocolSpecification.aspx diff --git a/Documentation/nfc/nfc-pn544.txt b/Documentation/nfc/nfc-pn544.txt deleted file mode 100644 index b36ca14ca2d6..000000000000 --- a/Documentation/nfc/nfc-pn544.txt +++ /dev/null @@ -1,32 +0,0 @@ -Kernel driver for the NXP Semiconductors PN544 Near Field -Communication chip - -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". - -Host Interfaces: I2C, SPI and HSU, this driver supports currently only I2C. - -Protocols ---------- - -In the normal (HCI) mode and in the firmware update mode read and -write functions behave a bit differently because the message formats -or the protocols are different. - -In the normal (HCI) mode the protocol used is derived from the ETSI -HCI specification. The firmware is updated using a specific protocol, -which is different from HCI. - -HCI messages consist of an eight bit header and the message body. The -header contains the message length. Maximum size for an HCI message is -33. In HCI mode sent messages are tested for a correct -checksum. Firmware update messages have the length in the second (MSB) -and third (LSB) bytes of the message. The maximum FW message length is -1024 bytes. - -For the ETSI HCI specification see -http://www.etsi.org/WebSite/Technologies/ProtocolSpecification.aspx