share/man/man4/dmoverio.4

   1 .\"     $NetBSD: dmoverio.4,v 1.5 2003/04/16 13:35:17 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002 Wasabi Systems, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed for the NetBSD Project by
  19 .\"     Wasabi Systems, Inc.
  20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  21 .\"    or promote products derived from this software without specific prior
  22 .\"    written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .Dd August 1, 2002
  37 .Dt DMOVERIO 4
  38 .Os
  39 .Sh NAME
  40 .Nm dmoverio
  41 .Nd hardware-assisted data mover interface
  42 .Sh SYNOPSIS
  43 .Cd pseudo-device dmoverio
  44 .Pp
  45 .In dev/dmover/dmover_io.h
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 pseudo-device driver provides an interface to hardware-assisted
  50 data movers, which the kernel supports using the
  51 .Xr dmover 9
  52 facility.  This can be used to copy data from one location in
  53 memory to another, clear a region of memory, fill a region of memory
  54 with a pattern, and perform simple operations on multiple regions of
  55 memory, such as an XOR, without intervention by the CPU.
  56 .Pp
  57 A
  58 .Nm
  59 function always has one output region.  A function may have zero or more
  60 input regions, or may use an immediate value as an input.  For functions
  61 which use input regions, the lengths of each input region and the output
  62 region must be the same.  All
  63 .Nm
  64 functions with the same name will have the same number of and type inputs.
  65 .Pp
  66 To use
  67 .Nm ,
  68 the client must first create a session.  This is achieved by performing
  69 the following steps:
  70 .Bl -bullet
  71 .It
  72 Create a session handle by opening the
  73 .Pa /dev/dmoverio
  74 device.
  75 .It
  76 Select the
  77 .Nm
  78 function using the DMIO_SETFUNC ioctl, which takes the following
  79 argument:
  80 .Bd -literal -offset indent
  81 #define DMIO_MAX_FUNCNAME     64
  82 struct dmio_setfunc {
  83         char dsf_name[DMIO_MAX_FUNCNAME];
  84 };
  85 .Ed
  86 .Pp
  87 If the specified function is not available, the DMIO_SETFUNC ioctl
  88 will fail with an error code of
  89 .Er ESRCH .
  90 .El
  91 .Pp
  92 To submit a request for processing the following steps must be
  93 performed:
  94 .Bl -bullet
  95 .It
  96 Fill in a request structure:
  97 .Bd -literal -offset indent
  98 typedef struct {
  99         struct iovec *dmbuf_iov;
 100         u_int dmbuf_iovcnt;
 101 } dmio_buffer;
 102
 103 struct dmio_usrreq {
 104         /* Output buffer. */
 105         dmio_buffer req_outbuf;
 106
 107         /* Input buffer. */
 108         union {
 109                 uint8_t _immediate[8];
 110                 dmio_buffer *_inbuf;
 111         } _req_inbuf_un;
 112
 113 #define req_immediate           _req_inbuf_un._immediate
 114 #define req_inbuf               _req_inbuf_un._inbuf
 115
 116         uint32_t req_id;        /* request ID; passed in response */
 117 };
 118 .Ed
 119 .Pp
 120 For functions which use an immediate value as an input, the
 121 .Em req_immediate
 122 member is used to specify the value.  Values smaller than 8 bytes should
 123 use the least-significant bytes first.  For example, a 32-bit integer
 124 would occupy bytes 0, 1, 2, and 3.
 125 .Pp
 126 For functions which use input regions,
 127 .Em req_inbuf
 128 should point to an array of
 129 .Fa dmio_buffer Ns 's .
 130 .Pp
 131 The
 132 .Em req_id
 133 should be a unique value for each request submitted by the client.  It
 134 will be passed back unchanged in the response when processing of the
 135 request has completed.
 136 .It
 137 Write the request structure to the session handle using the
 138 .Xr write 2
 139 system call.  Multiple requests may be written to the session in a
 140 single call.
 141 .It
 142 Read the response structure back from the session handle using the
 143 .Xr read 2
 144 system call.  The response structure is defined as follows:
 145 .Bd -literal -offset indent
 146 struct dmio_usrresp {
 147         uint32_t resp_id;
 148         int resp_error;
 149 };
 150 .Ed
 151 .Pp
 152 The
 153 .Em resp_id
 154 corresponds to the
 155 .Em req_id
 156 in the request.
 157 .Em resp_error
 158 contains 0 if the request succeeded or an
 159 .Xr errno 2
 160 value indicating why the request failed.  Multiple responses may
 161 be read back in a single call.  Note that responses may not be
 162 received in the same order as requests were written.
 163 .El
 164 .Pp
 165 When a client is finished using a
 166 .Nm
 167 session, the session is destroyed by closing the session handle using
 168 .Xr close 2 .
 169 .Sh EXAMPLES
 170 The following is an example of a client using
 171 .Nm
 172 to zero-fill a region of memory.  In this example, the application would
 173 be able to perform other work while the hardware-assisted data mover clears
 174 the specified block of memory.
 175 .Bd -literal
 176 int
 177 hw_bzero(void *buf, size_t len)
 178 {
 179         static uint32_t reqid;
 180
 181         struct dmio_setfunc dsf;
 182         struct iovec iov;
 183         struct dmio_usrreq req;
 184         struct dmio_usrresp resp;
 185         int fd;
 186
 187         fd = open("/dev/dmoverio", O_RDWR, 0666);
 188         if (fd == -1)
 189                 return (-1);
 190
 191         strcpy(dsf.dsf_name, "zero");
 192
 193         if (ioctl(fd, DMIO_SETFUNC, &dsf) == -1) {
 194                 close(fd);
 195                 return (-1);
 196         }
 197
 198         iov.iov_base = buf;
 199         iov.iov_len = len;
 200
 201         req.req_outbuf.dmbuf_iov = &iov;
 202         req.req_outbuf.dmbuf_iovcnt = 1;
 203         req.req_id = reqid++;
 204
 205         if (write(fd, &req, sizeof(req)) != sizeof(req)) {
 206                 close(fd);
 207                 return (-1);
 208         }
 209
 210         /* Application can do other work here. */
 211
 212         if (read(fd, &resp, sizeof(resp)) != sizeof(resp)) {
 213                 close(fd);
 214                 return (-1);
 215         }
 216
 217         if (resp.resp_id != req.req_id) {
 218                 close(fd);
 219                 return (-1);
 220         }
 221
 222         if (resp.resp_error != 0) {
 223                 close(fd);
 224                 return (-1);
 225         }
 226
 227         close(fd);
 228         return (0);
 229 }
 230 .Ed
 231 .Sh SEE ALSO
 232 .Xr dmover 9
 233 .Sh HISTORY
 234 The
 235 .Nm
 236 device first appeared in
 237 .Nx 2.0 .
 238 .Sh AUTHORS
 239 The
 240 .Nm
 241 device was designed and implemented by
 242 .An Jason R. Thorpe
 243 .Aq thorpej@wasabisystems.com
 244 and contributed by Wasabi Systems, Inc.