svn commit: r208716 - head/share/man/man4

[Attilio Rao]

Author: attilio
Date: Tue Jun  1 18:27:48 2010
New Revision: 208716
URL: http://svn.freebsd.org/changeset/base/208716

Log:
  Adjust the manpage after r207329.
  
  Sponsored by:	Sandvine Incorporated
  Reviewed by:	cpercival, emaste, marcel
  X-MFC:		r207329

Modified:
  head/share/man/man4/io.4

Modified: head/share/man/man4/io.4
==============================================================================
--- head/share/man/man4/io.4	Tue Jun  1 16:04:01 2010	(r208715)
+++ head/share/man/man4/io.4	Tue Jun  1 18:27:48 2010	(r208716)
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 8, 2010
+.Dd June 01, 2010
 .Dt IO 4
 .Os
 .Sh NAME
@@ -35,32 +35,89 @@
 .Nd I/O privilege file
 .Sh SYNOPSIS
 .Cd "device io"
+.Pp
+.In sys/types.h
+.In sys/ioctl.h
+.In dev/io/iodev.h
+.In machine/iodev.h
+.Pp
+.Bd -literal
+struct iodev_pio_req {
+	u_int access;
+	u_int port;
+	u_int width;
+	u_int val;
+};
 .Sh DESCRIPTION
 The special file
 .Pa /dev/io
 is a controlled security hole that allows a process to gain I/O
 privileges
 (which are normally reserved for kernel-internal code).
-Any process that holds a file descriptor on
-.Pa /dev/io
-open will get its
-.Em IOPL
-bits in the flag register set, thus allowing it to perform direct
-I/O operations.
 This can be useful in order to write userland
 programs that handle some hardware directly.
-Note that even read-only access will grant the full I/O privileges.
+.Pp
+The usual operations on the device are to open it via the
+.Xr open 2
+interface and to send I/O requests to the file descriptor using the
+.Xr ioctl 2
+syscall.
+.Pp
+The
+.Xr ioctl 2
+requests available for
+.Pa /dev/io
+are mostly platform dependent, but there are also some in common between
+all of them.
+The
+.Dv IODEV_PIO
+is used by all the architectures in order to request that an I/O operation
+be performed. It takes a 'struct iodev_pio_req' argument
+that must be previously setup.
+.Pp
+The
+.Fa access
+member specifies the type of operation requested. It may be:
+.Bl -tag -width IODEV_PIO_WRITE
+.It Dv IODEV_PIO_READ
+The operation is an "in" type. A value will be read from the specified port
+(retrieved from the
+.Fa port
+member) and the result will be stored in the
+.Fa val
+member.
+.It Dv IODEV_PIO_WRITE
+The operation is a "out" type. The value will be fetched from the
+.Fa val
+member and will be written out to the specified port (defined as the
+.Fa port
+member).
+.El
+.Pp
+Finally, the
+.Fa width
+member specifies the size of the operand to be read/written, expressed
+in bytes.
 .Pp
 In addition to any file access permissions on
 .Pa /dev/io ,
 the kernel enforces that only the super-user may open this device.
-.Sh FILES
-.Bl -tag -width Pa -compact
-.It Pa /dev/io
-.El
+.Sh LEGACY
+The
+.Pa /dev/io
+interface used to be very i386 specific and worked differently. The initial
+implementation, in fact, simply raised the
+.Em IOPL
+of the current thread when
+.Xr open 2
+was called on the file. This behaviour is retained in the current
+implementation as legacy support for both i386 and amd64 architectures.
 .Sh SEE ALSO
+.Xr close 2 ,
 .Xr i386_get_ioperm 2 ,
 .Xr i386_set_ioperm 2 ,
+.Xr ioctl 2 ,
+.Xr open 2 ,
 .Xr mem 4
 .Sh HISTORY
 The