share/man/man4/iop.4

   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
  43 The
  44 .Nm
  45 driver provides support for
  46 .Tn PCI
  47 I/O processors conforming to the
  48 .Tn I2O
  49 specification, revision 1.5 and above.
  50 .Pp
  51 I2O is a specification that defines a software interface for communicating
  52 with a number of device types.
  53 In its basic form, I2O provides the following:
  54 .Pp
  55 .Bl -bullet
  56 .It
  57 A vendor-neutral interface for communicating with an I/O processor (IOP)
  58 and a number of types of peripherals.
  59 In order to achieve this, hardware-specific device drivers run on
  60 the IOP, and hardware-neutral device drivers run on the host.
  61 .It
  62 Reduced I/O overhead for the host.
  63 All communication between the host and the IOP is performed using
  64 a high level protocol.
  65 The specification also provides for batching of requests and replies
  66 between the host and IOP.
  67 .It
  68 An optional vendor-neutral configuration interface.
  69 Data from HTTP GET and POST operations can be channeled to individual
  70 devices, and HTML pages returned.
  71 .El
  72 .Pp
  73 Five types of devices are well defined by the specification.
  74 These are:
  75 .Pp
  76 .Bl -bullet -compact
  77 .It
  78 Random block storage devices (disks).
  79 .It
  80 Sequential storage devices (tapes).
  81 .It
  82 LAN interfaces, including Ethernet, FDDI, and Token Ring.
  83 .It
  84 Bus ports (SCSI).
  85 .It
  86 SCSI peripherals.
  87 .El
  88 .Pp
  89 The
  90 .Nm
  91 driver's role is to initialize and monitor the IOP, provide a conduit for
  92 messages and replies to and from devices, and provide other common services
  93 for peripheral drivers, such as DMA mapping.
  94 .Sh IOCTL INTERFACE
  95 The following structures and constants are defined in
  96 .Pa dev/i2o/iopio.h .
  97 Note that the headers
  98 .Pa sys/types.h ,
  99 .Pa sys/device.h
 100 and
 101 .Pa dev/i2o/i2o.h
 102 are prerequisites and must therefore be included beforehand.
 103 .Bl -tag -width OTTF
 104 .It Dv IOPIOCPT (struct ioppt)
 105 Submit a message to the IOP and return the reply.
 106 Note that the return value of this ioctl is not affected by completion
 107 status as indicated by the reply.
 108 .Bd -literal
 109 struct 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
 119 struct 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
 126 The minimum timeout value that may be specified is 1000ms.
 127 All other values must not exceed the
 128 .Nm
 129 driver's operational limits.
 130 .Pp
 131 The initiator context and transaction context fields in the message frame
 132 will be filled by the
 133 .Nm
 134 driver.
 135 As such, this ioctl may not be used to send messages without a
 136 transaction context payload.
 137 .It Dv IOPIOCGSTATUS (struct iovec)
 138 Request the latest available status record from the IOP.
 139 This special-case ioctl is provided as the I2O_EXEC_STATUS_GET
 140 message does not post replies, and can therefore not be safely
 141 issued using the IOPIOCPT ioctl.
 142 .El
 143 .Pp
 144 The following ioctls may block while attempting to acquire the
 145 .Nm
 146 driver's configuration lock, and may fail if the acquisition times out.
 147 .Bl -tag -width OTTF
 148 .It Dv IOPIOCGLCT (struct iovec)
 149 Retrieve the
 150 .Nm
 151 driver's copy of the logical configuration table.
 152 This copy of the LCT matches the current device configuration, but
 153 is not necessarily the latest available version of the LCT.
 154 .It Dv IOPIOCRECONFIG
 155 Request that the
 156 .Nm
 157 driver scan all bus ports, retrieve the latest version of the LCT, and
 158 attach or detach devices as necessary.
 159 Note that higher-level reconfiguration tasks (such as logically
 160 re-scanning SCSI busses) will not be performed by this ioctl.
 161 .It Dv IOPIOCGTIDMAP (struct iovec)
 162 Retrieve the TID to device map.
 163 This map indicates which targets are
 164 configured, and what the corresponding device name for each is.
 165 Although at any given point it contains the same number of entries
 166 as the LCT, the number of entries should be determined using the
 167 iov_len field from the returned iovec.
 168 .Bd -literal
 169 struct iop_tidmap {
 170         u_short it_tid;
 171         u_short it_flags;
 172         char    it_dvname[sizeof(((struct device *)NULL)-\*[Gt]dv_xname)];
 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
 180 control 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 .Pp
 190 .Pa http://www.intelligent-io.com/
 191 .Sh HISTORY
 192 The
 193 .Nm
 194 driver first appeared in
 195 .Nx 1.5.3 .