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 <mchehab+samsung@kernel.org>

Documentation/nfc/index.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+========================
+Near Field Communication
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   nfc-hci
+   nfc-pn544

Documentation/nfc/nfc-hci.rst

@@ -1,7 +1,9 @@
+========================
 HCI backend for NFC Core
+========================
 
-Author: Eric Lapuyade, Samuel Ortiz
+- Author: Eric Lapuyade, Samuel Ortiz
-Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
+- Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
 
 General
 -------
@@ -24,12 +26,13 @@ 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:
+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
@@ -58,7 +61,7 @@ HCI Management
 --------------
 
 A driver would normally register itself with HCI and provide the following
-entry points:
+entry points::
 
   struct nfc_hci_ops {
 	int (*open)(struct nfc_hci_dev *hdev);
@@ -122,7 +125,7 @@ This must be done from a context that can sleep.
 PHY Management
 --------------
 
-The physical link (i2c, ...) management is defined by the following structure:
+The physical link (i2c, ...) management is defined by the following structure::
 
   struct nfc_phy_ops {
 	int (*write)(void *dev_id, struct sk_buff *skb);
@@ -130,12 +133,15 @@ struct nfc_phy_ops {
 	void (*disable)(void *dev_id);
   };
 
-enable(): turn the phy on (power on), make it ready to transfer data
+enable():
-disable(): turn the phy off
+	turn the phy on (power on), make it ready to transfer data
-write(): Send a data frame to the chip. Note that to enable higher
+disable():
-layers such as an llc to store the frame for re-emission, this function must
+	turn the phy off
-not alter the skb. It must also not return a positive result (return 0 for
+write():
-success, negative for failure).
+	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().
 
@@ -145,7 +151,7 @@ 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:
+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,
@@ -159,15 +165,23 @@ struct nfc_llc_ops {
 	int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
   };
 
-- init() : allocate and init your private storage
+init():
-- deinit() : cleanup
+	allocate and init your private storage
-- start() : establish the logical connection
+deinit():
-- stop () : terminate the logical connection
+	cleanup
-- rcv_from_drv() : handle data coming from the chip, going to HCI
+start():
-- xmit_from_hci() : handle data sent by HCI, going to the chip
+	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);
+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.
@@ -187,24 +201,30 @@ 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.
+  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:
+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)
@@ -234,7 +254,7 @@ 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:
+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,
@@ -268,10 +288,10 @@ 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
+  that any subsequent call to the driver will result in this error. Then it
-the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem
+  calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the
-above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to
+  problem above. shdlc stores a EREMOTEIO sticky status, which will trigger
-report above in turn.
+  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
@@ -281,10 +301,11 @@ 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.
+  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.
+  space to let it know that the poll operation will never be able to detect a
-If polling is not active and the error was sticky, lower levels will return it
+  tag. If polling is not active and the error was sticky, lower levels will
-at next invocation.
+  return it at next invocation.

Documentation/nfc/nfc-pn544.rst

@@ -1,5 +1,7 @@
-Kernel driver for the NXP Semiconductors PN544 Near Field
+============================================================================
-Communication chip
+Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip
+============================================================================
+
 
 General
 -------