205 lines
6.7 KiB
Groff
205 lines
6.7 KiB
Groff
.\" $NetBSD: iop.4,v 1.16 2003/02/14 15:20:18 grant Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000, 2001 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 November 8, 2000
|
|
.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"
|
|
.Pp
|
|
.Cd options 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.
|
|
.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 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
driver was written by
|
|
.An Andrew Doran
|
|
.Aq ad@NetBSD.org .
|