.\"	$OpenBSD: i386_get_ioperm.2,v 1.15 2013/09/14 14:58:54 jmc Exp $
.\"	$NetBSD: i386_get_ioperm.2,v 1.3 1996/02/27 22:57:17 jtc Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by John T. Kohl and Charles M. Hannum.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: September 14 2013 $
.Dt I386_GET_IOPERM 2 i386
.Os
.Sh NAME
.Nm i386_get_ioperm ,
.Nm i386_set_ioperm
.Nd manage i386 per-process I/O permission bitmap
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <machine/sysarch.h>
.Ft int
.Fn i386_get_ioperm "u_long *iomap"
.Ft int
.Fn i386_set_ioperm "u_long *iomap"
.Sh DESCRIPTION
.Fn i386_get_ioperm
copies the current I/O permission bitmap into the memory referenced by
.Fa iomap .
.Pp
.Fn i386_set_ioperm
sets the I/O permission bitmap from the data pointed to by
.Fa iomap .
This call may only be made by the superuser.
Additionally, it is only permitted when the
.Xr securelevel 7
is less than or equal to 0 or the
.Va machdep.allowaperture
sysctl has been set to a non-zero value.
.Pp
The permission bitmap contains 1024 bits in 32 longwords.
If bit
.Va n
is clear in the bitmap, then access is granted to I/O port
.Va n .
If bit
.Va n
is set in the bitmap, then an attempt to access I/O port
.Va n
results in delivery of a
.Dv SIGBUS
signal unless the process's I/O permission level would grant I/O access.
.Pp
.Sy Note:
Code using the
.Fn i386_get_ioperm
and
.Fn i386_set_ioperm
functions must be compiled using
.Cm -li386 .
.Sh RETURN VALUES
Upon successful completion,
.Fn i386_get_ioperm
and
.Fn i386_set_ioperm
return 0.
Otherwise, a value of \-1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn i386_get_ioperm
and
.Fn i386_set_ioperm
will fail if:
.Bl -tag -width [EINVAL]
.It Bq Er EFAULT
.Fa iomap
points outside the process's allocated address space.
.El
.Pp
Additionally
.Fn i386_set_ioperm
will fail if:
.Bl -tag -width [EINVAL]
.It Bq Er EPERM
The caller was not the superuser, or the securelevel is greater than zero and
.Va machdep.allowaperture
has not been set to a non-zero value.
.El
.Sh SEE ALSO
.Xr i386_iopl 2
.Rs
.%A Intel
.%T i386 Microprocessor Programmer's Reference Manual
.Re
.Sh WARNING
You can really hose your machine if you enable user-level I/O and
write to hardware ports without care.
.Sh BUGS
The bitmap should really cover 65536 bits, but that's just too big for
allocation in a kernel structure.
If you need access to ports beyond 1024, use
.Xr i386_iopl 2 .