Declare prototypes. This allows them to be documented with doxygen.

server/drivers/port.h

@@ -1,4 +1,21 @@
-/*
+/** \file server/drivers/port.h
+ * Low level functions to access I/O ports.
+ *
+ * If you make modifications to this file: References to the LPT port should
+ * not be in this file but in lpt-port.h.
+ *
+ * The functions are defined within this header file and as \c static
+ * \c inline absolutely on purpose.  Each driver including this header file
+ * gets its own copy of the functions and they are inlined into the driver's
+ * code.  As a result calls to \c port_in and \c port_out are directly
+ * translated to \c inb or \c outb or assembly code by the compiler.  There
+ * is less to no overhead in using them.
+ *
+ * \note Anyone who whishes to extend functionality has to provide a solution
+ * that provides comparable overhead and speed for direct I/O calls!
+ */
+
+/*-
  * Low level I/O functions taken from led-stat.txt
  * Jan 22 95 copyright damianf@wpi.edu
  *
@@ -17,37 +34,6 @@
  *
  */
 
-/*
-This file defines 6 static inline functions for port I/O:
-
-static inline int port_in (unsigned short port);
-	Read a byte from port
-	Returns the content of the byte.
-
-static inline void port_out (unsigned short port, unsigned char val);
-	Write a char(byte) 'val' to port.
-	Returns nothing.
-
-static inline int port_access (unsigned short port);
-	Get access to a specific port
-	Returns 0 if successful, -1 if failed
-
-static inline int port_deny (unsigned short port);
-	Close access to a specific port
-	Returns 0 if successful, -1 if failed
-
-static inline int port_access_multiple (unsigned short port, unsigned short count)
-	Get access multiple to ports at once.
-	Returns 0 if successful, -1 if failed
-
-static inline int port_deny_multiple (unsigned short port, unsigned short count)
-	Close access to multiple ports at once.
-	Returns 0 if successful, -1 if failed
-
-If you make modifications to this file: References to the LPT port should
-not be in this file but in lpt-port.h ...
-*/
-
 #ifndef PORT_H
 #define PORT_H
 
@@ -57,7 +43,55 @@ not be in this file but in lpt-port.h ...
 
 #include <stdio.h>
 
-/*  ------------------------------------------------------------- */
+
+/* This file defines 6 static inline functions for port I/O: */
+
+/**
+ * Read a byte from port.
+ * \param port  Address of I/O port to use.
+ * \return  The content of the byte.
+ */
+static inline int port_in(unsigned short port);
+
+/**
+ * Write a char (byte) to port.
+ * \param port  Address of I/O port to use.
+ * \param val   The value (one byte) to write to the port.
+ */
+static inline void port_out(unsigned short port, unsigned char val);
+
+/**
+ * Get access to a specific port.
+ * \param port  Address of I/O port to use.
+ * \return  0 if successful, -1 if failed
+ */
+static inline int port_access(unsigned short port);
+
+/**
+ * Close access to a specific port.
+ * \param port  Address of I/O port to use.
+ * \return  0 if successful, -1 if failed
+ */
+static inline int port_deny(unsigned short port);
+
+/**
+ * Get access multiple to ports at once.
+ * \param port   Base address of I/O port.
+ * \param count  Number of consecutive port to request access to.
+ * \return  0 if successful, -1 if failed
+ */
+static inline int port_access_multiple(unsigned short port, unsigned short count);
+
+/**
+ * Close access to multiple ports at once.
+ * \param port   Base address of I/O port.
+ * \param count  Number of consecutive port to release.
+ * \return  0 if successful, -1 if failed
+ */
+static inline int port_deny_multiple(unsigned short port, unsigned short count);
+
+
+/*  ---------------------------- Linux ------------------------------------ */
 /*  Use ioperm, inb and outb in <sys/io.h> (Linux) */
 /*  And iopl for higher addresses of PCI LPT cards */
 #if defined HAVE_IOPERM
@@ -86,11 +120,13 @@ static inline void port_out (unsigned short port, unsigned char val) {
 static inline int port_access (unsigned short port) {
 	if (port <= 0x3FF) {
 		return ioperm(port, 1, 255);
-	} else {
+	}
+	else {
 #ifdef HAVE_IOPL
 		/* Is there a better way to do this ? */
 		static short int iopl_done = 0;
-		if (iopl_done) return 0;
+		if (iopl_done)
+			return 0;
 		iopl_done = 1;
 		return iopl(3);
 #else
@@ -112,7 +148,8 @@ static inline int port_deny (unsigned short port) {
 static inline int port_access_multiple (unsigned short port, int count) {
 	if (port+count-1 <= 0x3FF) {
 		return ioperm(port, count, 255);
-	} else {
+	}
+	else {
 #ifdef HAVE_IOPL
 		return port_access(port+count);
 		/* to use the iopl part there... */
@@ -132,8 +169,8 @@ static inline int port_deny_multiple (unsigned short port, int count) {
 	return 0;
 }
 
-/*  ------------------------------------------------------------- */
+/*  --------------------- NetBSD & OpenBSD -------------------------------- */
-/*  Use i386_get_ioperm, i386_set_ioperm, inb and outb from <machine/pio.h> (NetBSD&OpenBSD) */
+/*  Use i386_get_ioperm, i386_set_ioperm, inb and outb from <machine/pio.h> */
 #elif defined HAVE_I386_IOPERM_NETBSD && defined HAVE_MACHINE_PIO_H && defined HAVE_MACHINE_SYSARCH_H && defined HAVE_SYS_TYPES_H
 #include <sys/types.h>
 #include <machine/pio.h>
@@ -149,6 +186,7 @@ static inline void port_out (unsigned short port, unsigned char val) {
 	outb(port, val);
 }
 
+/*  Set / release the requested port in the iomap */
 static inline void setaccess(u_long * map, u_int bit, int allow) {
 	u_int word;
 	u_int shift;
@@ -168,11 +206,13 @@ static inline void setaccess(u_long * map, u_int bit, int allow) {
 static inline int port_access (unsigned short port) {
 	u_long iomap[32];
 
-	if (i386_get_ioperm(iomap) == -1) return -1;
+	if (i386_get_ioperm(iomap) == -1)
+		return -1;
 
-	setaccess(iomap, port  , 1);
+	setaccess(iomap, port, 1);
 
-	if (i386_set_ioperm(iomap) == -1) return -1;
+	if (i386_set_ioperm(iomap) == -1)
+		return -1;
 
 	return 0;
 }
@@ -181,11 +221,13 @@ static inline int port_access (unsigned short port) {
 static inline int port_deny (unsigned short port) {
 	u_long iomap[32];
 
-	if (i386_get_ioperm(iomap) == -1) return -1;
+	if (i386_get_ioperm(iomap) == -1)
+		return -1;
 
 	setaccess(iomap, port, 0);
 
-	if (i386_set_ioperm(iomap) == -1) return -1;
+	if (i386_set_ioperm(iomap) == -1)
+		return -1;
 
 	return 0;
 }
@@ -195,13 +237,15 @@ static inline int port_access_multiple (unsigned short port, unsigned short coun
 	u_long iomap[32];
 	unsigned short i;
 
-	if (i386_get_ioperm(iomap) == -1) return -1;
+	if (i386_get_ioperm(iomap) == -1)
+		return -1;
 
-	for (i=0; i<count; i++) {
+	for (i = 0; i < count; i++) {
 		setaccess(iomap, port + i, 1);
 	}
 
-	if (i386_set_ioperm(iomap) == -1) return -1;
+	if (i386_set_ioperm(iomap) == -1)
+		return -1;
 
 	return 0;
 }
@@ -211,20 +255,24 @@ static inline int port_deny_multiple (unsigned short port, unsigned short count)
 	u_long iomap[32];
 	unsigned short i;
 
-	if (i386_get_ioperm(iomap) == -1) return -1;
+	if (i386_get_ioperm(iomap) == -1)
+		return -1;
 
-	for (i=0; i<count; i++) {
+	for (i = 0; i < count; i++) {
 		setaccess(iomap, port + i, 0);
 	}
 
-	if (i386_set_ioperm(iomap) == -1) return -1;
+	if (i386_set_ioperm(iomap) == -1)
+		return -1;
 
 	return 0;
 }
 
-/*#endif // defined HAVE_I386_IOPERM_NETBSD && defined HAVE_MACHINE_PIO_H && defined HAVE_MACHINE_SYSARCH_H
+/*  ------------------------------- FreeBSD ------------------------------- */
--------------------------------------------------------------
+/*
-Use i386_get_ioperm, i386_set_ioperm from <machine/sysarch.h> and inb and outb from <machine/cpufunc.h> (FreeBSD) */
+ * Use i386_get_ioperm, i386_set_ioperm from <machine/sysarch.h> and inb and
+ * outb from <machine/cpufunc.h>
+ */
 #elif defined HAVE_I386_IOPERM_FREEBSD && defined HAVE_MACHINE_CPUFUNC_H && defined HAVE_MACHINE_SYSARCH_H && defined HAVE_SYS_TYPES_H
 #include <sys/types.h>
 #include <sys/param.h>
@@ -232,7 +280,7 @@ Use i386_get_ioperm, i386_set_ioperm from <machine/sysarch.h> and inb and outb f
 #include <machine/sysarch.h>
 
 #if (__FreeBSD_version > 500000)
-static FILE * port_access_handle = NULL;
+static FILE *port_access_handle = NULL;
 #endif
 
 /* Read a byte from port */
@@ -242,17 +290,18 @@ static inline int port_in (unsigned short port) {
 
 /* Write a byte 'val' to port */
 static inline void port_out (unsigned short port, unsigned char val) {
-        outb(port,val);
+	outb(port, val);
 }
 
 /* Get access to a specific port */
 static inline int port_access (unsigned short port) {
 #if (__FreeBSD_version > 500000)
-	if( port_access_handle
+	if (port_access_handle
-	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL ) {
+	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL) {
 		return i386_set_ioperm(port, 1, 1);
-	} else {
+	}
-		return( -1 );  /*  Failure */
+	else {
+		return (-1);	/* Failure */
 	};
 #else
 	return i386_set_ioperm(port, 1, 1);
@@ -262,11 +311,12 @@ static inline int port_access (unsigned short port) {
 /* Get access to multiple ports at once */
 static inline int port_access_multiple (unsigned short port, unsigned short count) {
 #if (__FreeBSD_version > 500000)
-	if( port_access_handle
+	if (port_access_handle
-	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL ) {
+	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL) {
 		return i386_set_ioperm(port, count, 1);
-	} else {
+	}
-		return( -1 );  /*  Failure */
+	else {
+		return (-1);	/* Failure */
 	};
 #else
 	return i386_set_ioperm(port, count, 1);
@@ -284,32 +334,34 @@ static inline int port_deny_multiple (unsigned short port, unsigned short count)
 }
 
 #else
-/*  ------------------------------------------------------------- */
+
+/*  ------------------------- Everything else ----------------------------- */
 /*  Last chance! Use /dev/io and i386 ASM code (BSD4.3 ?) */
 
 /*  Read a byte from port */
 static inline int port_in (unsigned short port) {
 	unsigned char value;
 	__asm__ volatile ("inb %1,%0":"=a" (value)
-							:"d" ((unsigned short) port));
+			  :        "d"((unsigned short)port));
 	return value;
 }
 
 /*  Write a byte 'val' to port */
 static inline void port_out (unsigned short port, unsigned char val) {
-	__asm__ volatile ("outb %0,%1\n"::"a" (val), "d" (port)
+	__asm__ volatile ("outb %0,%1\n"::"a" (val), "d"(port)
 	);
 }
 
 /*  Get access to a specific port */
 static inline int port_access (unsigned short port) {
-	static FILE *  port_access_handle = NULL ;
+	static FILE *port_access_handle = NULL;
 
-	if( port_access_handle
+	if (port_access_handle
-	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL ) {
+	    || (port_access_handle = fopen("/dev/io", "rw")) != NULL) {
-		return( 0 );  /*  Success */
+		return (0);	/* Success */
-	} else {
+	}
-		return( -1 );  /*  Failure */
+	else {
+		return (-1);	/* Failure */
 	};
 
 	return -1;
@@ -323,7 +375,7 @@ static inline int port_deny (unsigned short port) {
 
 /*  Get access to multiple ports at once */
 static inline int port_access_multiple (unsigned short port, unsigned short count) {
-	return port_access (port); /* /dev/io gives you access to all ports. */
+	return port_access(port);	/* /dev/io gives you access to all ports. */
 }
 
 /*  Close access to multiple ports at once */
@@ -334,24 +386,4 @@ static inline int port_deny_multiple (unsigned short port, unsigned short count)
 
 #endif
 
-/*
-#else
-#include <pc.h>
-
-static inline int
-port_in (int port)
-{
-	unsigned char value;
-	value = inportb ((unsigned short) port);
-	return (int) value;
-}
-
-static inline void
-port_out (unsigned int port, unsigned char val)
-{
-	outportb ((unsigned short) port, val);
-}
-#endif
-*/
-
 #endif /* PORT_H */