Re: [PATCH 4/4][Doc] Document pci_iomap()

[Randy Dunlap <rdunlap@xenotime.net>]

On Sun, 8 Jul 2007 18:09:19 +0200 Rolf Eike Beer wrote:

> This useful interface is hardly mentioned anywhere in the in-tree
> documentation.
> 
> Signed-off-by: Rolf Eike Beer <eike-kernel@sf-tec.de>

Hi Rolf,

quilt says:

Warning: trailing whitespace in lines 250,251,254 of lib/iomap.c

> ---
> commit 2cb2450818804edcbcb1486a4df0db06e5d49969
> tree 2c53fbd2e0be832767446a8684561200b437a695
> parent 288a3f1fd00365669ed9ad725b15ff67004cee0a
> author Rolf Eike Beer <eike-kernel@sf-tec.de> Mon, 14 Aug 2006 14:20:30 +0200
> committer Rolf Eike Beer <eike-kernel@sf-tec.de> Mon, 14 Aug 2006 14:20:30 +0200
> 
>  Documentation/DocBook/deviceiobook.tmpl |    1 +
>  include/asm-i386/io.h                   |    3 +++
>  lib/iomap.c                             |   15 ++++++++++++++-
>  3 files changed, 18 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl
> index 90ed23d..4f85515 100644
> --- a/Documentation/DocBook/deviceiobook.tmpl
> +++ b/Documentation/DocBook/deviceiobook.tmpl
> @@ -317,6 +317,7 @@ CPU B:  spin_unlock_irqrestore(&amp;dev_lock, flags)
>    <chapter id="pubfunctions">
>       <title>Public Functions Provided</title>
>  !Einclude/asm-i386/io.h

Weird.  After applying this patch, I am getting this kdoc warning:

  DOCPROC Documentation/DocBook/deviceiobook.xml
Warning(/var/linsrc/linux-2.6.22//include/asm-i386/io.h): no structured comments found

but the warning is not correct... :(
Oh, the !E should be !I for the io.h file.
Would you correct that also?  :)


> +!Elib/iomap.c
>    </chapter>
>  
>  </book>
> diff --git a/include/asm-i386/io.h b/include/asm-i386/io.h
> index b3724fe..e176483 100644
> --- a/include/asm-i386/io.h
> +++ b/include/asm-i386/io.h
> @@ -112,6 +112,9 @@ extern void __iomem * __ioremap(unsigned long offset, unsigned long size, unsign
>   * 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 on pci_iomap().

      look at

>   */
>  
>  static inline void __iomem * ioremap(unsigned long offset, unsigned long size)
> diff --git a/lib/iomap.c b/lib/iomap.c
> index 55689c5..8de891d 100644
> --- a/lib/iomap.c
> +++ b/lib/iomap.c
> @@ -202,7 +202,20 @@ void ioport_unmap(void __iomem *addr)
>  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 their length first pass %0 here.

s/their/its/
s/first/first,/

> + **/
>  void __iomem *pci_iomap(struct pci_dev *dev, int bar, unsigned long maxlen)
>  {
>  	unsigned long start = pci_resource_start(dev, bar);
> 

Please make these minor corrections.  Looks good to me.
Matthew, OK with you?

Thanks.
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/