1.\" $NetBSD: dmoverio.4,v 1.3 2002/08/04 05:02:22 thorpej 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.Fd #include \*[Lt]dev/dmover/dmover_io.h\*[Gt] 46.Sh DESCRIPTION 47The 48.Nm 49pseudo-device driver provides an interface to hardware-assisted 50data movers, which the kernel supports using the 51.Xr dmover 9 52facility. This can be used to copy data from one location in 53memory to another, clear a region of memory, fill a region of memory 54with a pattern, and perform simple operations on multiple regions of 55memory, such as an XOR, without intervention by the CPU. 56.Pp 57A 58.Nm 59function always has one output region. A function may have zero or more 60input regions, or may use an immediate value as an input. For functions 61which use input regions, the lengths of each input region and the output 62region must be the same. All 63.Nm 64functions with the same name will have the same number of and type inputs. 65.Pp 66To use 67.Nm "" , 68the client must first create a session. This is achieved by performing 69the following steps: 70.Bl -bullet 71.It 72Create a session handle by opening the 73.Pa /dev/dmover 74device. 75.It 76Select the 77.Nm 78function using the DMIO_SETFUNC ioctl, which takes the following 79argument: 80.Bd -literal -offset indent 81#define DMIO_MAX_FUNCNAME 64 82struct dmio_setfunc { 83 char dsf_name[DMIO_MAX_FUNCNAME]; 84}; 85.Ed 86.Pp 87If the specified function is not available, the DMIO_SETFUNC ioctl 88will fail with an error code of 89.Er ESRCH . 90.El 91.Pp 92To submit a request for processing the following steps must be 93performed: 94.Bl -bullet 95.It 96Fill in a request structure: 97.Bd -literal -offset indent 98typedef struct { 99 struct iovec *dmbuf_iov; 100 u_int dmbuf_iovcnt; 101} dmio_buffer; 102 103struct 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 120For functions which use an immediate value as an input, the 121.Em req_immediate 122member is used to specify the value. Values smaller than 8 bytes should 123use the least-significant bytes first. For example, a 32-bit integer 124would occupy bytes 0, 1, 2, and 3. 125.Pp 126For functions which use input regions, 127.Em req_inbuf 128should point to an array of 129.Fa dmio_buffer Ns 's . 130.Pp 131The 132.Em req_id 133should be a unique value for each request submitted by the client. It 134will be passed back unchanged in the response when processing of the 135request has completed. 136.It 137Write the request structure to the session handle using the 138.Xr write 2 139system call. Multiple requests may be written to the session in a 140single call. 141.It 142Read the response structure back from the session handle using the 143.Xr read 2 144system call. The response structure is defined as follows: 145.Bd -literal -offset indent 146struct dmio_usrresp { 147 uint32_t resp_id; 148 int resp_error; 149}; 150.Ed 151.Pp 152The 153.Em resp_id 154corresponds to the 155.Em req_id 156in the request. 157.Em resp_error 158contains 0 if the request succeeded or an 159.Xr errno 2 160value indicating why the request failed. Multiple responses may 161be read back in a single call. Note that responses may not be 162received in the same order as requests were written. 163.El 164.Pp 165When a client is finished using a 166.Nm 167session, the session is destroyed by closing the session handle using 168.Xr close 2 . 169.Sh EXAMPLES 170The following is an example of a client using 171.Nm 172to zero-fill a region of memory. In this example, the application would 173be able to perform other work while the hardware-assisted data mover clears 174the specified block of memory. 175.Bd -literal 176int 177hw_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/dmover", 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 234The 235.Nm 236device first appeared in 237.Nx 2.0 . 238.Sh AUTHORS 239The 240.Nm 241device was designed and implemented by 242.An Jason R. Thorpe 243.Aq thorpej@wasabisystems.com 244and contributed by Wasabi Systems, Inc. 245