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