.\"	$OpenBSD: iop.4,v 1.14 2007/05/31 19:19:50 jmc Exp $
.\"	$NetBSD: iop.4,v 1.7 2001/03/20 13:09:19 ad Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Andrew Doran.
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 FOUNDATION 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: May 31 2007 $
.Dt IOP 4
.Os
.Sh NAME
.Nm iop
.Nd
.Tn I2O (RAID) adapter driver
.Sh SYNOPSIS
.Cd "iop* at pci?"
.Cd "iopsp* at iop?"
.Cd "ioprbs* at iop?"
.Cd "scsibus* at iopsp?"
.Cd "scsibus* at ioprbs?"
.Cd "option I2OVERBOSE"
.Sh DESCRIPTION
The
.Nm
driver provides support for
.Tn PCI
I/O processors conforming to the
.Tn I2O
specification, revision 1.5 and above.
.Sh IOCTL INTERFACE
The following structures and constants are defined in
.Aq Pa dev/i2o/iopio.h .
Note that the headers
.Aq Pa sys/types.h ,
.Aq Pa sys/device.h
and
.Aq Pa dev/i2o/i2o.h
are prerequisites and must therefore be included beforehand.
.Bl -tag -width OTTF
.It Dv IOPIOCPT (struct ioppt)
Submit a message to the IOP and return the reply.
Note that the return value of this ioctl is not affected by completion status
as indicated by the reply.
.Bd -literal
struct ioppt {
	void	*pt_msg;	/* pointer to message buffer */
	size_t	pt_msglen;	/* message buffer size in bytes */
	void	*pt_reply;	/* pointer to reply buffer */
	size_t	pt_replylen;	/* reply buffer size in bytes */
	int	pt_timo;	/* completion timeout in ms */
	int	pt_nbufs;	/* number of transfers */
	struct	ioppt_buf pt_bufs[IOP_MAX_MSG_XFERS]; /* transfers */
};

struct ioppt_buf {
	void	*ptb_data;	/* pointer to buffer */
	size_t	ptb_datalen;	/* buffer size in bytes */
	int	ptb_out;	/* non-zero if transfer is to IOP */
};
.Ed
.Pp
The minimum timeout value that may be specified is 1000ms.
All other values must not exceed the
.Nm
driver's operational limits.
.It Dv IOPIOCGSTATUS (struct iovec)
Request the latest available status record from the IOP.
This special-case ioctl is provided as the I2O_EXEC_STATUS_GET message
does not post replies, and can therefore not be safely issued using
the IOPIOCPT ioctl.
.El
.Pp
The following ioctls may block while attempting to acquire the
.Nm
driver's configuration lock, and may fail if the acquisition times out.
.Bl -tag -width OTTF
.It Dv IOPIOCGLCT (struct iovec)
Retrieve the
.Nm
driver's copy of the logical configuration table.
This copy of the LCT matches the current device configuration, but is not
necessarily the latest available version of the LCT.
.It Dv IOPIOCRECONFIG
Request that the
.Nm
driver scan all bus ports, retrieve the latest version of the LCT, and
attach or detach devices as necessary.
Note that higher-level reconfiguration tasks (such as logically re-scanning
SCSI buses) will not be performed by this ioctl.
.It Dv IOPIOCGTIDMAP (struct iovec)
Retrieve the TID to device map.
This map indicates which targets are configured, and what the corresponding
device name for each is.
Although at any given point it contains the same number of entries as the LCT,
the number of entries should be determined using the iov_len field from
the returned iovec.
.Bd -literal
struct iop_tidmap {
	u_short	it_tid;
	u_short	it_flags;
	char	it_dvname[sizeof(((struct device *)NULL)->dv_xname)];
};
#define	IT_CONFIGURED	0x02	/* target configured */
.Ed
.El
.Sh FILES
.Bl -tag -width /dev/iopn -compact
.It Pa /dev/iop Ns Ar u
control device for IOP unit
.Ar u
.El
.Sh SEE ALSO
.Xr intro 4 ,
.Xr ioprbs 4 ,
.Xr iopsp 4 ,
.Xr pci 4 ,
.Xr scsibus 4 ,
.Xr iopctl 8
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 1.6 ,
.Ox
support was added in
.Ox 3.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Andrew Doran Aq ad@netbsd.org
and ported to
.Ox 3.0
by
.An Niklas Hallqvist Aq niklas@openbsd.org
and
.An Michael Shalayeff Aq mickey@openbsd.org .