dmaengine: doc: ReSTize client API doc

This converts and moves client API file with some format
changes for RST style
Signed-off-by: Vinod Koul <vinod.koul@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/dmaengine/client.txt → Documentation/driver-api/dmaengine/client.rst

-			DMA Engine API Guide
-			====================
+====================
+DMA Engine API Guide
+====================
 
-		 Vinod Koul <vinod dot koul at intel.com>
+Vinod Koul <vinod dot koul at intel.com>
 
-NOTE: For DMA Engine usage in async_tx please see:
-	Documentation/crypto/async-tx-api.txt
+.. note:: For DMA Engine usage in async_tx please see:
+          ``Documentation/crypto/async-tx-api.txt``
 
 
 Below is a guide to device driver writers on how to use the Slave-DMA API of the
 DMA Engine. This is applicable only for slave DMA usage only.
 
+DMA usage
+=========
+
 The slave DMA usage consists of following steps:
-1. Allocate a DMA slave channel
-2. Set slave and controller specific parameters
-3. Get a descriptor for transaction
-4. Submit the transaction
-5. Issue pending requests and wait for callback notification
+
+- Allocate a DMA slave channel
+
+- Set slave and controller specific parameters
+
+- Get a descriptor for transaction
+
+- Submit the transaction
+
+- Issue pending requests and wait for callback notification
+
+The details of these operations are:
 
 1. Allocate a DMA slave channel
 
@@ -25,9 +36,12 @@ The slave DMA usage consists of following steps:
    To request a channel dma_request_chan() API is used.
 
    Interface:
+
+   .. code-block:: c
+
       struct dma_chan *dma_request_chan(struct device *dev, const char *name);
 
-   Which will find and return the 'name' DMA channel associated with the 'dev'
+   Which will find and return the ``name`` DMA channel associated with the 'dev'
    device. The association is done via DT, ACPI or board file based
    dma_slave_map matching table.
 
@@ -48,6 +62,9 @@ The slave DMA usage consists of following steps:
    parameters, if required.
 
    Interface:
+
+   .. code-block:: c
+
       int dmaengine_slave_config(struct dma_chan *chan,
 			struct dma_slave_config *config)
 
@@ -61,10 +78,12 @@ The slave DMA usage consists of following steps:
   For slave usage the various modes of slave transfers supported by the
   DMA-engine are:
 
-   slave_sg	- DMA a list of scatter gather buffers from/to a peripheral
-   dma_cyclic	- Perform a cyclic DMA operation from/to a peripheral till the
+  - slave_sg: DMA a list of scatter gather buffers from/to a peripheral
+
+  - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the
     operation is explicitly stopped.
-   interleaved_dma - This is common to Slave as well as M2M clients. For slave
+
+  - interleaved_dma: This is common to Slave as well as M2M clients. For slave
     address of devices' fifo could be already known to the driver.
     Various types of operations could be expressed by setting
     appropriate values to the 'dma_interleaved_template' members.
@@ -73,6 +92,9 @@ The slave DMA usage consists of following steps:
   the given transaction.
 
   Interface:
+
+  .. code-block:: c
+
      struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
 		struct dma_chan *chan, struct scatterlist *sgl,
 		unsigned int sg_len, enum dma_data_direction direction,
@@ -94,6 +116,8 @@ The slave DMA usage consists of following steps:
   called using the DMA struct device, too.
   So, normal setup should look like this:
 
+  .. code-block:: c
+
      nr_sg = dma_map_sg(chan->device->dev, sgl, sg_len);
 	if (nr_sg == 0)
 		/* error */
@@ -106,7 +130,8 @@ The slave DMA usage consists of following steps:
   submission so it is important that these two operations are closely
   paired.
 
-   Note:
+  .. note::
+
      Although the async_tx API specifies that completion callback
      routines cannot submit any new operations, this is not the
      case for slave/cyclic DMA.
@@ -132,6 +157,9 @@ The slave DMA usage consists of following steps:
    added, it must be placed on the DMA engine drivers pending queue.
 
    Interface:
+
+   .. code-block:: c
+
       dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)
 
    This returns a cookie can be used to check the progress of DMA engine
@@ -151,11 +179,19 @@ The slave DMA usage consists of following steps:
    completion callback routine for notification, if set.
 
    Interface:
+
+   .. code-block:: c
+
       void dma_async_issue_pending(struct dma_chan *chan);
 
 Further APIs:
+------------
+
+1. Terminate APIs
+
+   .. code-block:: c
 
-1. int dmaengine_terminate_sync(struct dma_chan *chan)
+      int dmaengine_terminate_sync(struct dma_chan *chan)
       int dmaengine_terminate_async(struct dma_chan *chan)
       int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */
 
@@ -178,16 +214,28 @@ Further APIs:
 
    dmaengine_terminate_all() is deprecated and should not be used in new code.
 
-2. int dmaengine_pause(struct dma_chan *chan)
+2. Pause API
+
+   .. code-block:: c
+
+      int dmaengine_pause(struct dma_chan *chan)
 
    This pauses activity on the DMA channel without data loss.
 
-3. int dmaengine_resume(struct dma_chan *chan)
+3. Resume API
+
+   .. code-block:: c
+
+       int dmaengine_resume(struct dma_chan *chan)
 
    Resume a previously paused DMA channel. It is invalid to resume a
    channel which is not currently paused.
 
-4. enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
+4. Check Txn complete
+
+   .. code-block:: c
+
+      enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
 		dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used)
 
    This can be used to check the status of the channel. Please see
@@ -198,13 +246,18 @@ Further APIs:
    the cookie returned from dmaengine_submit() to check for
    completion of a specific DMA transaction.
 
-   Note:
+   .. note::
+
       Not all DMA engine drivers can return reliable information for
       a running DMA channel. It is recommended that DMA engine users
       pause or stop (via dmaengine_terminate_all()) the channel before
       using this API.
 
-5. void dmaengine_synchronize(struct dma_chan *chan)
+5. Synchronize termination API
+
+   .. code-block:: c
+
+      void dmaengine_synchronize(struct dma_chan *chan)
 
    Synchronize the termination of the DMA channel to the current context.
 

Documentation/driver-api/dmaengine/index.rst

@@ -16,6 +16,17 @@ driver writers.
 
    provider
 
+DMAEngine client documentation
+------------------------------
+
+This book is a guide to device driver writers on how to use the Slave-DMA
+API of the DMAEngine. This is applicable only for slave DMA usage only.
+
+.. toctree::
+   :maxdepth: 1
+
+   client
+
 .. only::  subproject
 
    Indices