1.\" $NetBSD: iop.4,v 1.19 2008/04/30 13:10:54 martin 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. In its basic form, I2O provides the 53following: 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. In order to achieve this, 59hardware-specific device drivers run on the IOP, and hardware-neutral device 60drivers run on the host. 61.It 62Reduced I/O overhead for the host. All communication between the host and 63the IOP is performed using a high level protocol. The specification also 64provides for batching of requests and replies between the host and IOP. 65.It 66An optional vendor-neutral configuration interface. Data from HTTP GET and 67POST operations can be channeled to individual devices, and HTML pages 68returned. 69.El 70.Pp 71Five types of devices are well defined by the specification. These are: 72.Pp 73.Bl -bullet -compact 74.It 75Random block storage devices (disks). 76.It 77Sequential storage devices (tapes). 78.It 79LAN interfaces, including Ethernet, FDDI, and Token Ring. 80.It 81Bus ports (SCSI). 82.It 83SCSI peripherals. 84.El 85.Pp 86The 87.Nm 88driver's role is to initialize and monitor the IOP, provide a conduit for 89messages and replies to and from devices, and provide other common services 90for peripheral drivers, such as DMA mapping. 91.Sh IOCTL INTERFACE 92The following structures and constants are defined in 93.Pa dev/i2o/iopio.h . 94Note that the headers 95.Pa sys/types.h , 96.Pa sys/device.h 97and 98.Pa dev/i2o/i2o.h 99are prerequisites and must therefore be included beforehand. 100.Bl -tag -width OTTF 101.It Dv IOPIOCPT (struct ioppt) 102Submit a message to the IOP and return the reply. Note that the return 103value of this ioctl is not affected by completion status as indicated by the 104reply. 105.Bd -literal 106struct ioppt { 107 void *pt_msg; /* pointer to message buffer */ 108 size_t pt_msglen; /* message buffer size in bytes */ 109 void *pt_reply; /* pointer to reply buffer */ 110 size_t pt_replylen; /* reply buffer size in bytes */ 111 int pt_timo; /* completion timeout in ms */ 112 int pt_nbufs; /* number of transfers */ 113 struct ioppt_buf pt_bufs[IOP_MAX_MSG_XFERS]; /* transfers */ 114}; 115 116struct ioppt_buf { 117 void *ptb_data; /* pointer to buffer */ 118 size_t ptb_datalen; /* buffer size in bytes */ 119 int ptb_out; /* non-zero if transfer is to IOP */ 120}; 121.Ed 122.Pp 123The minimum timeout value that may be specified is 1000ms. All other values 124must not exceed the 125.Nm 126driver's operational limits. 127.Pp 128The initiator context and transaction context fields in the message frame 129will be filled by the 130.Nm 131driver. As such, this ioctl may not be used to send messages without a 132transaction context payload. 133.It Dv IOPIOCGSTATUS (struct iovec) 134Request the latest available status record from the IOP. This special-case 135ioctl is provided as the I2O_EXEC_STATUS_GET message does not post replies, 136and can therefore not be safely issued using the IOPIOCPT ioctl. 137.El 138.Pp 139The following ioctls may block while attempting to acquire the 140.Nm 141driver's configuration lock, and may fail if the acquisition times out. 142.Bl -tag -width OTTF 143.It Dv IOPIOCGLCT (struct iovec) 144Retrieve the 145.Nm 146driver's copy of the logical configuration table. This copy of the LCT 147matches the current device configuration, but is not necessarily the latest 148available version of the LCT. 149.It Dv IOPIOCRECONFIG 150Request that the 151.Nm 152driver scan all bus ports, retrieve the latest version of the LCT, and 153attach or detach devices as necessary. Note that higher-level 154reconfiguration tasks (such as logically re-scanning SCSI busses) will not 155be performed by this ioctl. 156.It Dv IOPIOCGTIDMAP (struct iovec) 157Retrieve the TID to device map. This map indicates which targets are 158configured, and what the corresponding device name for each is. Although at 159any given point it contains the same number of entries as the LCT, the number 160of entries should be determined using the iov_len field from the returned 161iovec. 162.Bd -literal 163struct iop_tidmap { 164 u_short it_tid; 165 u_short it_flags; 166 char it_dvname[sizeof(((struct device *)NULL)-\*[Gt]dv_xname)]; 167}; 168#define IT_CONFIGURED 0x02 /* target configured */ 169.Ed 170.El 171.Sh FILES 172.Bl -tag -width /dev/iopn -compact 173.It Pa /dev/iop Ns Ar u 174control device for IOP unit 175.Ar u 176.El 177.Sh SEE ALSO 178.Xr dpti 4 , 179.Xr intro 4 , 180.Xr iopsp 4 , 181.Xr ld 4 , 182.Xr iopctl 8 183.Pp 184.Pa http://www.intelligent-io.com/ 185.Sh HISTORY 186The 187.Nm 188driver first appeared in 189.Nx 1.5.3 . 190