From a564ee723ced2607acfffaf6e5810d993a7d2091 Mon Sep 17 00:00:00 2001 From: thorpej Date: Fri, 2 Aug 2002 00:43:12 +0000 Subject: [PATCH] Manual page for pseudo-device access to hardware-assisted data movers. --- share/man/man4/Makefile | 8 +- share/man/man4/dmoverio.4 | 243 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 247 insertions(+), 4 deletions(-) create mode 100644 share/man/man4/dmoverio.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 8e4311a16ed3..64affca7de8f 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.263 2002/07/09 23:30:23 wiz Exp $ +# $NetBSD: Makefile,v 1.264 2002/08/02 00:43:12 thorpej Exp $ # @(#)Makefile 8.1 (Berkeley) 6/18/93 MAN= aac.4 acphy.4 adv.4 adw.4 agp.4 ahb.4 ahc.4 amdpm.4 \ @@ -7,9 +7,9 @@ MAN= aac.4 acphy.4 adv.4 adw.4 agp.4 ahb.4 ahc.4 amdpm.4 \ auvia.4 awi.4 bba.4 bha.4 bktr.4 bpf.4 bmtphy.4 brgphy.4 \ bridge.4 cac.4 cardbus.4 ccd.4 cd.4 cfb.4 ch.4 clcs.4 clct.4 \ clnp.4 clockctl.4 cltp.4 \ - cmpci.4 cms.4 cnw.4 com.4 ddb.4 de.4 dmphy.4 dpt.4 dpti.4 drum.4 eap.4 \ - ebus.4 edc.4 elmc.4 emuxki.4 en.4 envsys.4 ep.4 esh.4 esis.4 esa.4 \ - esiop.4 esl.4 esm.4 eso.4 exphy.4 \ + cmpci.4 cms.4 cnw.4 com.4 ddb.4 de.4 dmoverio.4 dmphy.4 dpt.4 dpti.4 \ + drum.4 eap.4 ebus.4 edc.4 elmc.4 emuxki.4 en.4 envsys.4 ep.4 esh.4 \ + esis.4 esa.4 esiop.4 esl.4 esm.4 eso.4 exphy.4 \ fd.4 fpa.4 fms.4 fxp.4 \ gem.4 gentbi.4 glxtphy.4 gre.4 gphyter.4 gsip.4 hme.4 \ icmp.4 icp.4 icsphy.4 idp.4 ifmedia.4 iha.4 inet.4 \ diff --git a/share/man/man4/dmoverio.4 b/share/man/man4/dmoverio.4 new file mode 100644 index 000000000000..96eb8e92b541 --- /dev/null +++ b/share/man/man4/dmoverio.4 @@ -0,0 +1,243 @@ +.\" $NetBSD: dmoverio.4,v 1.1 2002/08/02 00:43:13 thorpej Exp $ +.\" +.\" Copyright (c) 2002 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd Aug 1, 2002 +.Dt DMOVERIO 4 +.Os +.Sh NAME +.Nm dmoverio +.Nd hardware-assisted data mover interface +.Sh SYNOPSIS +.Cd pseudo-device dmoverio +.Pp +.Fd #include \*[Lt]dev/dmover/dmover_io.h\*[Gt] +.Sh DESCRIPTION +The +.Nm dmoverio +pesudo-device driver provides an interface to hardware-assisted +data movers, which the kernel supports using the +.Xr dmover 9 +facility. This can be used to copy data from one location in +memory to another, clear a region of memory, fill a region of memory +with a patter, and perform simple operations on multiple regions of +memory, such as an XOR, without intervention by the CPU. +.Pp +A +.Nm dmoverio +function always has one output region. A function may have zero or more +input regions, or may use an immediate value as an input. For functions +which use input regions, the lenghts of each input region and the output +region must be the same. All +.Nm dmover +functions with the same name will have the same number of and type inputs. +.Pp +To use +.Nm dmoverio , +the client must first create a session. This is achieved by performing +the following steps: +.Bl -bullet +.It +Create a session handle by opening the +.Pa /dev/dmover +device. +.It +Select the +.Nm dmoverio +function using the DMIO_SETFUNC ioctl, which takes the following +argument: +.Bd -literal -offset indent +#define DMIO_MAX_FUNCNAME 64 +struct dmio_setfunc { + char dsf_name[DMIO_MAX_FUNCNAME]; +}; +.Ed +.Pp +If the specified function is not available, the DMIO_SETFUNC ioctl +will fail with an error code of +.Er ESRCH . +.El +.Pp +To submit a request for processing the following steps must be +performed: +.Bl -bullet +.It +Fill in a request structure: +.Bd -literal -offset indent +typedef struct { + struct iovec *dmbuf_iov; + u_int dmbuf_iovcnt; +} dmio_buffer; + +struct dmio_usrreq { + /* Output buffer. */ + dmio_buffer req_outbuf; + + /* Input buffer. */ + union { + uint8_t _immediate[8]; + dmio_buffer *_inbuf; + } _req_inbuf_un; + +#define req_immediate _req_inbuf_un._immediate +#define req_inbuf _req_inbuf_un._inbuf + + uint32_t req_id; /* request ID; passed in response */ +}; +.Ed +.Pp +For functions which use an immediate value as an input, the +.Em req_immediate +member is used to specify the value. Values smaller than 8 bytes should +use the least-significant bytes first. For example, a 32-bit integer +would occupy bytes 0, 1, 2, and 3. +.Pp +For functions which use input regions, +.Em req_inbuf +should point to an array of +.Fa dmio_buffer Ns 's . +.Pp +The +.Em req_id +should be a unique value for each request submitted by the client. It +will be passed back unchanged in the response when processing of the +request has completed. +.It +Write the request structure to the session handle using the +.Xr write 2 +system call. Multiple requests may be written to the session in a +single call. +.It +Read the response structure back from the session handle using the +.Xr read 2 +system call. The response structure is defined as follows: +.Bd -literal -offset indent +struct dmio_usrresp { + uint32_t resp_id; + int resp_error; +}; +.Ed +.Pp +The +.Em resp_id +corresponds to the +.Em req_id +in the request. +.Em resp_error +contains 0 if the request succeeded or an +.Xr errno 2 +value indicating why the request failed. Multiple responses may +be read back in a single call. Note that responses may not be +received in the same order as requests were written. +.El +.Pp +When a client is finished using a +.Nm dmoverio +session, the session is destroyed by closing the session handle using +.Xr close 2 . +.Ss EXAMPLE USAGE +The following is an example of a client using +.Nm dmoverio +to zero-fill a region of memory. In this example, the application would +be able to perform other work while the hardware-assisted data mover clears +the specified block of memory. +.Bd -literal +int +hw_bzero(void *buf, size_t len) +{ + static uint32_t reqid; + + struct dmio_setfunc dsf; + struct iovec iov; + struct dmio_usrreq req; + struct dmio_usrresp resp; + int fd; + + fd = open("/dev/dmover", O_RDWR, 0666); + if (fd == -1) + return (-1); + + strcpy(dsf.dsf_name, "zero"); + + if (ioctl(fd, DMIO_SETFUNC, &dsf) == -1) { + close(fd); + return (-1); + } + + iov.iov_base = buf; + iov.iov_len = len; + + req.req_outbuf.dmbuf_iov = &iov; + req.req_outbuf.dmbuf_iovcnt = 1; + + if (write(fd, &req, sizeof(req)) != sizeof(req)) { + close(fd); + return (-1); + } + + /* Application can do other work here. */ + + if (read(fd, &resp, sizeof(resp)) != sizeof(resp)) { + close(fd); + return (-1); + } + + if (resp.resp_id != req.req_id) { + close(fd); + return (-1); + } + + if (resp.resp_error != 0) { + close(fd); + return (-1); + } + + close(fd); + return (0); +} +.Ed +.Sh SEE ALSO +.Xr dmover 9 +.Sh HISTORY +The +.Nm dmoverio +device first appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Nm dmoverio +device was designed and implemented by +.An Jason R. Thorpe +.Aq thorpej@wasabisystems.com +and contributed by Wasabi Systems, Inc.