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