linux-kernel - [PATCH v2 28/31] io-mapping.txt: standardize document format

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <a4a3782bc53a907e00d1f8a51f03fa4a445e6d88.1497713142.git.mchehab@s-opensource.com>
Date:   Sat, 17 Jun 2017 12:25:47 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: [PATCH v2 28/31] io-mapping.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:

- Add a title for the document and for API chapter;
- mark literal blocks;
- Adjust whitespacing.

Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
---
 Documentation/io-mapping.txt | 67 +++++++++++++++++++++++++++-----------------
 1 file changed, 41 insertions(+), 26 deletions(-)

diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.txt
index 5ca78426f54c..a966239f04e4 100644
--- a/Documentation/io-mapping.txt
+++ b/Documentation/io-mapping.txt
@@ -1,66 +1,81 @@
+========================
+The io_mapping functions
+========================
+
+API
+===
+
 The io_mapping functions in linux/io-mapping.h provide an abstraction for
 efficiently mapping small regions of an I/O device to the CPU. The initial
 usage is to support the large graphics aperture on 32-bit processors where
 ioremap_wc cannot be used to statically map the entire aperture to the CPU
 as it would consume too much of the kernel address space.
 
-A mapping object is created during driver initialization using
+A mapping object is created during driver initialization using::
 
 	struct io_mapping *io_mapping_create_wc(unsigned long base,
 						unsigned long size)
 
-		'base' is the bus address of the region to be made
-		mappable, while 'size' indicates how large a mapping region to
-		enable. Both are in bytes.
+'base' is the bus address of the region to be made
+mappable, while 'size' indicates how large a mapping region to
+enable. Both are in bytes.
 
-		This _wc variant provides a mapping which may only be used
-		with the io_mapping_map_atomic_wc or io_mapping_map_wc.
+This _wc variant provides a mapping which may only be used
+with the io_mapping_map_atomic_wc or io_mapping_map_wc.
 
 With this mapping object, individual pages can be mapped either atomically
 or not, depending on the necessary scheduling environment. Of course, atomic
-maps are more efficient:
+maps are more efficient::
 
 	void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
 				       unsigned long offset)
 
-		'offset' is the offset within the defined mapping region.
-		Accessing addresses beyond the region specified in the
-		creation function yields undefined results. Using an offset
-		which is not page aligned yields an undefined result. The
-		return value points to a single page in CPU address space.
+'offset' is the offset within the defined mapping region.
+Accessing addresses beyond the region specified in the
+creation function yields undefined results. Using an offset
+which is not page aligned yields an undefined result. The
+return value points to a single page in CPU address space.
 
-		This _wc variant returns a write-combining map to the
-		page and may only be used with mappings created by
-		io_mapping_create_wc
+This _wc variant returns a write-combining map to the
+page and may only be used with mappings created by
+io_mapping_create_wc
 
-		Note that the task may not sleep while holding this page
-		mapped.
+Note that the task may not sleep while holding this page
+mapped.
+
+::
 
 	void io_mapping_unmap_atomic(void *vaddr)
 
-		'vaddr' must be the value returned by the last
-		io_mapping_map_atomic_wc call. This unmaps the specified
-		page and allows the task to sleep once again.
+'vaddr' must be the value returned by the last
+io_mapping_map_atomic_wc call. This unmaps the specified
+page and allows the task to sleep once again.
 
 If you need to sleep while holding the lock, you can use the non-atomic
 variant, although they may be significantly slower.
 
+::
+
 	void *io_mapping_map_wc(struct io_mapping *mapping,
 				unsigned long offset)
 
-		This works like io_mapping_map_atomic_wc except it allows
-		the task to sleep while holding the page mapped.
+This works like io_mapping_map_atomic_wc except it allows
+the task to sleep while holding the page mapped.
+
+
+::
 
 	void io_mapping_unmap(void *vaddr)
 
-		This works like io_mapping_unmap_atomic, except it is used
-		for pages mapped with io_mapping_map_wc.
+This works like io_mapping_unmap_atomic, except it is used
+for pages mapped with io_mapping_map_wc.
 
-At driver close time, the io_mapping object must be freed:
+At driver close time, the io_mapping object must be freed::
 
 	void io_mapping_free(struct io_mapping *mapping)
 
-Current Implementation:
+Current Implementation
+======================
 
 The initial implementation of these functions uses existing mapping
 mechanisms and so provides only an abstraction layer and no new
-- 
2.9.4