PCI: Document pci_iomap()

This useful interface is hardly mentioned anywhere in the in-tree
documentation.

Signed-off-by: Rolf Eike Beer <[e-mail]>
Cc: Tejun Heo <[e-mail]>
Acked-by: Randy Dunlap <[e-mail]>
Signed-off-by: Andrew Morton <[e-mail]>
Signed-off-by: Greg Kroah-Hartman <[e-mail]>

Documentation/DocBook/deviceiobook.tmpl

···
 
   <chapter id="pubfunctions">
      <title>Public Functions Provided</title>
-!Einclude/asm-i386/io.h
+!Iinclude/asm-i386/io.h
+!Elib/iomap.c
   </chapter>
 
 </book>

include/asm-i386/io.h

···
  * writew/writel functions and the other mmio helpers. The returned
  * address is not guaranteed to be usable directly as a virtual
  * address. 
+ *
+ * If the area you are trying to map is a PCI BAR you should have a
+ * look at pci_iomap().
  */
 
 static inline void __iomem * ioremap(unsigned long offset, unsigned long size)

lib/iomap.c

···
 EXPORT_SYMBOL(ioport_map);
 EXPORT_SYMBOL(ioport_unmap);
 
-/* Create a virtual mapping cookie for a PCI BAR (memory or IO) */
+/**
+ * pci_iomap - create a virtual mapping cookie for a PCI BAR
+ * @dev: PCI device that owns the BAR
+ * @bar: BAR number
+ * @maxlen: length of the memory to map
+ *
+ * Using this function you will get a __iomem address to your device BAR.
+ * You can access it using ioread*() and iowrite*(). These functions hide
+ * the details if this is a MMIO or PIO address space and will just do what
+ * you expect from them in the correct way.
+ *
+ * @maxlen specifies the maximum length to map. If you want to get access to
+ * the complete BAR without checking for its length first, pass %0 here.
+ * */
 void __iomem *pci_iomap(struct pci_dev *dev, int bar, unsigned long maxlen)
 {
 	unsigned long start = pci_resource_start(dev, bar);