Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753115AbdFQP00 (ORCPT ); Sat, 17 Jun 2017 11:26:26 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:38558 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1751966AbdFQP0O (ORCPT ); Sat, 17 Jun 2017 11:26:14 -0400 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH v2 28/31] io-mapping.txt: standardize document format Date: Sat, 17 Jun 2017 12:25:47 -0300 Message-Id: X-Mailer: git-send-email 2.9.4 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4695 Lines: 129 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 --- 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