196 lines
6.2 KiB
Groff
196 lines
6.2 KiB
Groff
.\" $NetBSD: iop.4,v 1.20 2009/05/18 13:49:43 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000, 2001, 2007 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.
|
|
.\"
|
|
.\" 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 December 2, 2007
|
|
.Dt IOP 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm iop
|
|
.Nd
|
|
.Tn I2O adapter driver
|
|
.Sh SYNOPSIS
|
|
.Cd "iop* at pci? dev ? function ?"
|
|
.Cd "iopsp* at iop? tid ?"
|
|
.Cd "ld* at iop? tid ?"
|
|
.Cd "dpti* at iop? tid 0"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for
|
|
.Tn PCI
|
|
I/O processors conforming to the
|
|
.Tn I2O
|
|
specification, revision 1.5 and above.
|
|
.Pp
|
|
I2O is a specification that defines a software interface for communicating
|
|
with a number of device types.
|
|
In its basic form, I2O provides the following:
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
A vendor-neutral interface for communicating with an I/O processor (IOP)
|
|
and a number of types of peripherals.
|
|
In order to achieve this, hardware-specific device drivers run on
|
|
the IOP, and hardware-neutral device drivers run on the host.
|
|
.It
|
|
Reduced I/O overhead for the host.
|
|
All communication between the host and the IOP is performed using
|
|
a high level protocol.
|
|
The specification also provides for batching of requests and replies
|
|
between the host and IOP.
|
|
.It
|
|
An optional vendor-neutral configuration interface.
|
|
Data from HTTP GET and POST operations can be channeled to individual
|
|
devices, and HTML pages returned.
|
|
.El
|
|
.Pp
|
|
Five types of devices are well defined by the specification.
|
|
These are:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Random block storage devices (disks).
|
|
.It
|
|
Sequential storage devices (tapes).
|
|
.It
|
|
LAN interfaces, including Ethernet, FDDI, and Token Ring.
|
|
.It
|
|
Bus ports (SCSI).
|
|
.It
|
|
SCSI peripherals.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver's role is to initialize and monitor the IOP, provide a conduit for
|
|
messages and replies to and from devices, and provide other common services
|
|
for peripheral drivers, such as DMA mapping.
|
|
.Sh IOCTL INTERFACE
|
|
The following structures and constants are defined in
|
|
.Pa dev/i2o/iopio.h .
|
|
Note that the headers
|
|
.Pa sys/types.h ,
|
|
.Pa sys/device.h
|
|
and
|
|
.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.
|
|
.Pp
|
|
The initiator context and transaction context fields in the message frame
|
|
will be filled by the
|
|
.Nm
|
|
driver.
|
|
As such, this ioctl may not be used to send messages without a
|
|
transaction context payload.
|
|
.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 busses) 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)-\*[Gt]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 dpti 4 ,
|
|
.Xr intro 4 ,
|
|
.Xr iopsp 4 ,
|
|
.Xr ld 4 ,
|
|
.Xr iopctl 8
|
|
.Pp
|
|
.Pa http://www.intelligent-io.com/
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver first appeared in
|
|
.Nx 1.5.3 .
|