remoteproc.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document and section titles;
- adjust identation;
- mark literal blocks

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/remoteproc.txt

@@ -1,6 +1,9 @@
+==========================
 Remote Processor Framework
+==========================
 
-1. Introduction
+Introduction
+============
 
 Modern SoCs typically have heterogeneous remote processor devices in asymmetric
 multiprocessing (AMP) configurations, which may be running different instances
@@ -26,38 +29,56 @@ remoteproc will add those devices. This makes it possible to reuse the
 existing virtio drivers with remote processor backends at a minimal development
 cost.
 
-2. User API
+User API
+========
+
+::
 
   int rproc_boot(struct rproc *rproc)
-    - Boot a remote processor (i.e. load its firmware, power it on, ...).
+
+Boot a remote processor (i.e. load its firmware, power it on, ...).
+
 If the remote processor is already powered on, this function immediately
 returns (successfully).
+
 Returns 0 on success, and an appropriate error value otherwise.
 Note: to use this function you should already have a valid rproc
 handle. There are several ways to achieve that cleanly (devres, pdata,
 the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
 might also consider using dev_archdata for this).
 
+::
+
   void rproc_shutdown(struct rproc *rproc)
-    - Power off a remote processor (previously booted with rproc_boot()).
+
+Power off a remote processor (previously booted with rproc_boot()).
 In case @rproc is still being used by an additional user(s), then
 this function will just decrement the power refcount and exit,
 without really powering off the device.
+
 Every call to rproc_boot() must (eventually) be accompanied by a call
 to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
-      Notes:
+
-      - we're not decrementing the rproc's refcount, only the power refcount.
+.. note::
+
+  we're not decrementing the rproc's refcount, only the power refcount.
   which means that the @rproc handle stays valid even after
   rproc_shutdown() returns, and users can still use it with a subsequent
   rproc_boot(), if needed.
 
+::
+
   struct rproc *rproc_get_by_phandle(phandle phandle)
-    - Find an rproc handle using a device tree phandle. Returns the rproc
+
+Find an rproc handle using a device tree phandle. Returns the rproc
 handle on success, and NULL on failure. This function increments
 the remote processor's refcount, so always use rproc_put() to
 decrement it back once rproc isn't needed anymore.
 
-3. Typical usage
+Typical usage
+=============
+
+::
 
   #include <linux/remoteproc.h>
 
@@ -82,12 +103,16 @@ int dummy_rproc_example(struct rproc *my_rproc)
 	rproc_shutdown(my_rproc);
   }
 
-4. API for implementors
+API for implementors
+====================
+
+::
 
   struct rproc *rproc_alloc(struct device *dev, const char *name,
 				const struct rproc_ops *ops,
 				const char *firmware, int len)
-    - Allocate a new remote processor handle, but don't register
+
+Allocate a new remote processor handle, but don't register
 it yet. Required parameters are the underlying device, the
 name of this remote processor, platform-specific ops handlers,
 the name of the firmware to boot this rproc with, and the
@@ -95,36 +120,54 @@ int dummy_rproc_example(struct rproc *my_rproc)
 
 This function should be used by rproc implementations during
 initialization of the remote processor.
+
 After creating an rproc handle using this function, and when ready,
 implementations should then call rproc_add() to complete
 the registration of the remote processor.
+
 On success, the new rproc is returned, and on failure, NULL.
 
-      Note: _never_ directly deallocate @rproc, even if it was not registered
+.. note::
+
+  **never** directly deallocate @rproc, even if it was not registered
   yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
 
+::
+
   void rproc_free(struct rproc *rproc)
-    - Free an rproc handle that was allocated by rproc_alloc.
+
+Free an rproc handle that was allocated by rproc_alloc.
+
 This function essentially unrolls rproc_alloc(), by decrementing the
 rproc's refcount. It doesn't directly free rproc; that would happen
 only if there are no other references to rproc and its refcount now
 dropped to zero.
 
+::
+
   int rproc_add(struct rproc *rproc)
-    - Register @rproc with the remoteproc framework, after it has been
+
+Register @rproc with the remoteproc framework, after it has been
 allocated with rproc_alloc().
+
 This is called by the platform-specific rproc implementation, whenever
 a new remote processor device is probed.
+
 Returns 0 on success and an appropriate error code otherwise.
 Note: this function initiates an asynchronous firmware loading
 context, which will look for virtio devices supported by the rproc's
 firmware.
+
 If found, those virtio devices will be created and added, so as a result
 of registering this remote processor, additional virtio drivers might get
 probed.
 
+::
+
   int rproc_del(struct rproc *rproc)
-    - Unroll rproc_add().
+
+Unroll rproc_add().
+
 This function should be called when the platform specific rproc
 implementation decides to remove the rproc device. it should
 _only_ be called if a previous invocation of rproc_add()
@@ -135,17 +178,22 @@ int dummy_rproc_example(struct rproc *my_rproc)
 
 Returns 0 on success and -EINVAL if @rproc isn't valid.
 
+::
+
   void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
-    - Report a crash in a remoteproc
+
+Report a crash in a remoteproc
+
 This function must be called every time a crash is detected by the
 platform specific rproc implementation. This should not be called from a
 non-remoteproc driver. This function can be called from atomic/interrupt
 context.
 
-5. Implementation callbacks
+Implementation callbacks
+========================
 
 These callbacks should be provided by platform-specific remoteproc
-drivers:
+drivers::
 
   /**
    * struct rproc_ops - platform-specific device handlers
@@ -179,7 +227,8 @@ the exact virtqueue index to look in is optional: it is easy (and not
 too expensive) to go through the existing virtqueues and look for new buffers
 in the used rings.
 
-6. Binary Firmware Structure
+Binary Firmware Structure
+=========================
 
 At this point remoteproc only supports ELF32 firmware binaries. However,
 it is quite expected that other platforms/devices which we'd want to
@@ -207,7 +256,7 @@ resource entries that publish the existence of supported features
 or configurations by the remote processor, such as trace buffers and
 supported virtio devices (and their configurations).
 
-The resource table begins with this header:
+The resource table begins with this header::
 
   /**
    * struct resource_table - firmware resource table header
@@ -229,7 +278,7 @@ struct resource_table {
   } __packed;
 
 Immediately following this header are the resource entries themselves,
-each of which begins with the following resource entry header:
+each of which begins with the following resource entry header::
 
   /**
    * struct fw_rsc_hdr - firmware resource entry header
@@ -252,7 +301,7 @@ is expected, where the firmware requests a resource, and once allocated,
 the host should provide back its details (e.g. address of an allocated
 memory region).
 
-Here are the various resource types that are currently supported:
+Here are the various resource types that are currently supported::
 
   /**
    * enum fw_resource_type - types of resource entries
@@ -286,7 +335,8 @@ We also expect that platform-specific resource entries will show up
 at some point. When that happens, we could easily add a new RSC_PLATFORM
 type, and hand those resources to the platform-specific rproc driver to handle.
 
-7. Virtio and remoteproc
+Virtio and remoteproc
+=====================
 
 The firmware should provide remoteproc information about virtio devices
 that it supports, and their configurations: a RSC_VDEV resource entry