xref: /netbsd/share/man/man4/iop.4 (revision bf9ec67e)
1.\"	$NetBSD: iop.4,v 1.15 2002/02/13 08:17:37 ross Exp $
2.\"
3.\" Copyright (c) 2000, 2001 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd November 8, 2000
38.Dt IOP 4
39.Os
40.Sh NAME
41.Nm iop
42.Nd
43.Tn I2O adapter driver
44.Sh SYNOPSIS
45.Cd "iop* at pci? dev ? function ?"
46.Cd "iopsp* at iop? tid ?"
47.Cd "ld* at iop? tid ?"
48.Cd "dpti* at iop? tid 0"
49.Pp
50.Cd options I2OVERBOSE
51.Sh DESCRIPTION
52The
53.Nm
54driver provides support for
55.Tn PCI
56I/O processors conforming to the
57.Tn I2O
58specification, revision 1.5 and above.
59.Pp
60I2O is a specification that defines a software interface for communicating
61with a number of device types.  In its basic form, I2O provides the
62following:
63.Pp
64.Bl -bullet
65.It
66A vendor-neutral interface for communicating with an I/O processor (IOP)
67and a number of types of peripherals.  In order to achieve this,
68hardware-specific device drivers run on the IOP, and hardware-neutral device
69drivers run on the host.
70.It
71Reduced I/O overhead for the host.  All communication between the host and
72the IOP is performed using a high level protocol.  The specification also
73provides for batching of requests and replies between the host and IOP.
74.It
75An optional vendor-neutral configuration interface.  Data from HTTP GET and
76POST operations can be channeled to individual devices, and HTML pages
77returned.
78.El
79.Pp
80Five types of devices are well defined by the specification.  These are:
81.Pp
82.Bl -bullet -compact
83.It
84Random block storage devices (disks).
85.It
86Sequential storage devices (tapes).
87.It
88LAN interfaces, including Ethernet, FDDI, and Token Ring.
89.It
90Bus ports (SCSI).
91.It
92SCSI peripherals.
93.El
94.Pp
95The
96.Nm
97driver's role is to initialize and monitor the IOP, provide a conduit for
98messages and replies to and from devices, and provide other common services
99for peripheral drivers, such as DMA mapping.
100.Sh IOCTL INTERFACE
101The following structures and constants are defined in
102.Pa dev/i2o/iopio.h .
103Note that the headers
104.Pa sys/types.h ,
105.Pa sys/device.h
106and
107.Pa dev/i2o/i2o.h
108are prerequisites and must therefore be included beforehand.
109.Bl -tag -width OTTF
110.It Dv IOPIOCPT (struct ioppt)
111Submit a message to the IOP and return the reply.  Note that the return
112value of this ioctl is not affected by completion status as indicated by the
113reply.
114.Bd -literal
115struct ioppt {
116	void	*pt_msg;	/* pointer to message buffer */
117	size_t	pt_msglen;	/* message buffer size in bytes */
118	void	*pt_reply;	/* pointer to reply buffer */
119	size_t	pt_replylen;	/* reply buffer size in bytes */
120	int	pt_timo;	/* completion timeout in ms */
121	int	pt_nbufs;	/* number of transfers */
122	struct	ioppt_buf pt_bufs[IOP_MAX_MSG_XFERS]; /* transfers */
123};
124
125struct ioppt_buf {
126	void	*ptb_data;	/* pointer to buffer */
127	size_t	ptb_datalen;	/* buffer size in bytes */
128	int	ptb_out;	/* non-zero if transfer is to IOP */
129};
130.Ed
131.Pp
132The minimum timeout value that may be specified is 1000ms.  All other values
133must not exceed the
134.Nm
135driver's operational limits.
136.Pp
137The initiator context and transaction context fields in the message frame
138will be filled by the
139.Nm
140driver.  As such, this ioctl may not be used to send messages without a
141transaction context payload.
142.It Dv IOPIOCGSTATUS (struct iovec)
143Request the latest available status record from the IOP.  This special-case
144ioctl is provided as the I2O_EXEC_STATUS_GET message does not post replies,
145and can therefore not be safely issued using the IOPIOCPT ioctl.
146.El
147.Pp
148The following ioctls may block while attempting to acquire the
149.Nm
150driver's configuration lock, and may fail if the acquisition times out.
151.Bl -tag -width OTTF
152.It Dv IOPIOCGLCT (struct iovec)
153Retrieve the
154.Nm
155driver's copy of the logical configuration table.  This copy of the LCT
156matches the current device configuration, but is not necessarily the latest
157available version of the LCT.
158.It Dv IOPIOCRECONFIG
159Request that the
160.Nm
161driver scan all bus ports, retrieve the latest version of the LCT, and
162attach or detach devices as necessary.  Note that higher-level
163reconfiguration tasks (such as logically re-scanning SCSI busses) will not
164be performed by this ioctl.
165.It Dv IOPIOCGTIDMAP (struct iovec)
166Retrieve the TID to device map.  This map indicates which targets are
167configured, and what the corresponding device name for each is.  Although at
168any given point it contains the same number of entries as the LCT, the number
169of entries should be determined using the iov_len field from the returned
170iovec.
171.Bd -literal
172struct iop_tidmap {
173	u_short	it_tid;
174	u_short	it_flags;
175	char	it_dvname[sizeof(((struct device *)NULL)-\*[Gt]dv_xname)];
176};
177#define	IT_CONFIGURED	0x02	/* target configured */
178.Ed
179.El
180.Sh FILES
181.Bl -tag -width /dev/iopn -compact
182.It Pa /dev/iop Ns Ar u
183control device for IOP unit
184.Ar u
185.El
186.Sh SEE ALSO
187.Xr dpti 4 ,
188.Xr intro 4 ,
189.Xr iopsp 4 ,
190.Xr ld 4 ,
191.Xr iopctl 8
192.Pp
193.Pa http://www.intelligent-io.com/
194.Sh HISTORY
195The
196.Nm
197driver first appeared in
198.Nx 1.5.3 .
199.Sh AUTHORS
200The
201.Nm
202driver was written by
203.An Andrew Doran
204.Aq ad@netbsd.org .
205