[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kernel-janitors
Subject:    RFC - [patch] towards documenting include/asm-i386/io.h
From:       Ken Moffat <ken () kenmoffat ! uklinux ! net>
Date:       2001-05-22 22:28:01
[Download RAW message or body]

Well, I solved my problem with jad segfaulting - duff memory. It seems
jade is as stressful to the box as compiling gcc, or as using a gcc-3
snapshot to compile the kernel. Anyway, a new mobo works wonders.

This patch is part-way towards documenting io.h. There is a chapter in
deviceiobook for public functions, but no documentation gets extracted so
jade reports an error, the chapter is not finished.

This is against 2.4.4-ac11, it applies (with some -2 offsets reported) to
2.4.5-pre4 and 2.4.4. (on 2.4.4 there is another error because a tag had
')' for '>', which was fixed first in -ac.) If anyone wonders why I have 
altered colons in existing documentation, it's because they cause DocBook
to split test or ignore it altogether.

Some questions for this list:

1. Is this worth doing ? I've had to expand the existing documentation to
get it into DocBook format, and repeat comments for macros where
previously a single comment was enough. The existing documentation was
mostly adequate (even I could understand it, I think), is the change to
produce proper DocBook documentation over the top ?

2. I read (in deviceiobook.tmpl) that the functions prefixed isa_ should
not be used for new drivers. Does this mean they should not appear in this
list of public functions ?

3. I had to change e.g. #define virt_to_bus virt_to_phys to
#define virt_to_bus(a) virt_to_phys(a)  to get DocBook to understand
it. Will this inadvertently alter the resulting code ? (This is a
documentation exercise, I haven't compiled it yet!)

Plus the usual implicit question - have I got any of it wrong ?

If you ask me anything, it may take a while for me to respond, because I
only collect mail once or twice a day. Patch follows.

Cheers, Ken.

diff -uNr linux-2.4.4-ac/include/asm-i386/io.h altered-2.4.4-ac/include/asm-i386/io.h
--- linux-2.4.4-ac/include/asm-i386/io.h	Tue May 22 07:39:53 2001
+++ altered-2.4.4-ac/include/asm-i386/io.h	Tue May 22 22:47:36 2001
@@ -123,15 +123,21 @@
 //#define __io_phys(x) __pa(x)
 #endif
 
-/*
- * Change virtual addresses to physical addresses and vv.
- * These are pretty trivial
- */
+/**
+ * virt_to_phys - convert virtual address to physical address
+ * @address: the virtual address
+ *
+ */ 
 extern inline unsigned long virt_to_phys(volatile void * address)
 {
 	return __pa(address);
 }
 
+/**
+ * phys_to_virt - convert physical address to  virtual address
+ * @address: the physical address
+ *
+ */
 extern inline void * phys_to_virt(unsigned long address)
 {
 	return __va(address);
@@ -144,10 +150,14 @@
 	return __ioremap(offset, size, 0);
 }
 
-/*
+/**
+ * ioremap_nocache - map high address memory and disable caching.
+ * @offset: the memory address
+ * @size: the size of the memory being mapped
+ *
  * This one maps high address device memory and turns off caching for that area.
- * it's useful if some control registers are in such an area and write combining
- * or read caching is not desirable:
+ * it's useful if some control registers are in such an area and write combining 
+ * or read caching is not desirable.
  */
 extern inline void * ioremap_nocache (unsigned long offset, unsigned long size)
 {
@@ -156,11 +166,25 @@
 
 extern void iounmap(void *addr);
 
-/*
- * IO bus memory addresses are also 1:1 with the physical address
+/**
+ * virt_to_bus - convert memory address to IO address
+ * @a: the address
+ *
+ * IO bus memory addresses are also 1 to 1 with the physical address on x86.
+ * This macro allows us to use a common function name on architectures where
+ * they differ.
+ */
+#define virt_to_bus(a) virt_to_phys(a)
+
+/**
+ * bus_to_virt - convert IO address to memory address
+ * @a: the IO address 
+ *
+ * IO bus memory addresses are also 1 to 1 with the physical address on x86.
+ * This macro allows us to use a common function name on architectures where
+ * they differ.
  */
-#define virt_to_bus virt_to_phys
-#define bus_to_virt phys_to_virt
+#define bus_to_virt(a) phys_to_virt(a)
 
 /*
  * readX/writeX() are used to access memory mapped devices. On some
@@ -169,22 +193,80 @@
  * memory location directly.
  */
 
+/**
+ * readb - read a byte from IO space
+ * @addr: the IO address 
+ *
+ * This macro reads 8 bits from a virtual IO address
+ */
 #define readb(addr) (*(volatile unsigned char *) __io_virt(addr))
+
+/**
+ * readw - read a word from IO space
+ * @addr: the IO address
+ *
+ * This macro reads 16 bits from a virtual IO address
+ */
 #define readw(addr) (*(volatile unsigned short *) __io_virt(addr))
+
+/**
+ * readl - read a long from IO space
+ * @addr: the IO address
+ *
+ * This macro reads 32 bits from a virtual IO address
+ */
 #define readl(addr) (*(volatile unsigned int *) __io_virt(addr))
 #define __raw_readb readb
 #define __raw_readw readw
 #define __raw_readl readl
 
+/**
+ * writeb - write a byte to IO space
+ * @b: the byte to write
+ * @addr: the IO address
+ *
+ * This macro writes 8 bits to a virtual i/o address
+ */
 #define writeb(b,addr) (*(volatile unsigned char *) __io_virt(addr) = (b))
+
+/**
+ * writew - write a word to IO space
+ * @b: the word to write
+ * @addr: the IO address
+ *
+ * This macro writes 16 bits to a virtual i/o address
+ */
 #define writew(b,addr) (*(volatile unsigned short *) __io_virt(addr) = (b))
+
+/**
+ * writel - write a long to IO space
+ * @b: the long to write
+ * @addr: the IO address
+ *
+ * This macro writes 32 bits to a virtual i/o address
+ */
 #define writel(b,addr) (*(volatile unsigned int *) __io_virt(addr) = (b))
+
 #define __raw_writeb writeb
 #define __raw_writew writew
 #define __raw_writel writel
 
 #define memset_io(a,b,c)	memset(__io_virt(a),(b),(c))
+
+/**
+ * memcpy_fromio - copy an IO area to memory
+ * @a: the memory address
+ * @b: the IO virtual address
+ * @c: the number of bytes to copy
+ */
 #define memcpy_fromio(a,b,c)	memcpy((a),__io_virt(b),(c))
+
+/**
+ * memcpy_toio - copy memory to an IO area
+ * @a: the IO virtual address
+ * @b: the memory address
+ * @c: the number of bytes to copy
+ */
 #define memcpy_toio(a,b,c)	memcpy(__io_virt(a),(b),(c))
 
 /*
@@ -215,6 +297,15 @@
 #define eth_io_copy_and_sum(a,b,c,d)		eth_copy_and_sum((a),__io_virt(b),(c),(d))
 #define isa_eth_io_copy_and_sum(a,b,c,d)	eth_copy_and_sum((a),__io_virt(__ISA_IO_base + (b)),(c),(d))
 
+/**
+ * check_signature - check a device's IO area against a signature
+ * @io_addr: IO address for the device
+ * @signature: pointer to the signature
+ * @length: the length of the signature, in bytes
+ *
+ * Read an IO area to see if it matches the signature. Return 1 for success,
+ * 0 for failure.
+ */
 static inline int check_signature(unsigned long io_addr,
 	const unsigned char *signature, int length)
 {
@@ -231,6 +322,15 @@
 	return retval;
 }
 
+/**
+ * isa_check_signature - check an isa device's IO area against a signature.
+ * @io_addr: IO offset for the device
+ * @signature: pointer to the signature
+ * @length: the length of the signature, in bytes
+ *
+ * Read an isa IO area to see if it matches the signature. Return 1 for
+ * success, 0 for failure. This function should not be used for new drivers.
+ */
 static inline int isa_check_signature(unsigned long io_addr,
 	const unsigned char *signature, int length)
 {

-- 
That's it, six times nine, forty-two.

Home page : http://www.kenmoffat.uklinux.net


_______________________________________________
Kernel-janitor-discuss mailing list
Kernel-janitor-discuss@lists.sourceforge.net
http://lists.sourceforge.net/lists/listinfo/kernel-janitor-discuss

[prev in list] [next in list] [prev in thread] [next in thread]