[src/trunk]: src/share/man/man4 Manual page for pseudo-device access to hardw...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man4 Manual page for pseudo-device access to hardw...
From: thorpej <thorpej%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 11:48:19 +0000
details:   https://anonhg.NetBSD.org/src/rev/9a20ad6a995f
branches:  trunk
changeset: 534700:9a20ad6a995f
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Fri Aug 02 00:43:12 2002 +0000

description:
Manual page for pseudo-device access to hardware-assisted data movers.

diffstat:

 share/man/man4/Makefile   |    8 +-
 share/man/man4/dmoverio.4 |  243 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 247 insertions(+), 4 deletions(-)

diffs (269 lines):

diff -r 0c481603988d -r 9a20ad6a995f share/man/man4/Makefile
--- a/share/man/man4/Makefile   Fri Aug 02 00:41:53 2002 +0000
+++ b/share/man/man4/Makefile   Fri Aug 02 00:43:12 2002 +0000
@@ -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 @@
        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 -r 0c481603988d -r 9a20ad6a995f share/man/man4/dmoverio.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/dmoverio.4 Fri Aug 02 00:43:12 2002 +0000
@@ -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@localhost
+and contributed by Wasabi Systems, Inc.
Prev by Date: [src/trunk]: src/etc Add wtmpx rotation. Okayed by christos.
Next by Date: [src/trunk]: src/sys/dev/dmover dmover(9) -- an interface to hardware-assiste...
Previous by Thread: [src/trunk]: src/etc Add wtmpx rotation. Okayed by christos.
Next by Thread: [src/trunk]: src/sys/dev/dmover dmover(9) -- an interface to hardware-assiste...
Indexes:
Home | Main Index | Thread Index | Old Index