.\"	$NetBSD: dmoverio.4,v 1.6 2004/04/08 05:49:13 atatat 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 August 1, 2002
.Dt DMOVERIO 4
.Os
.Sh NAME
.Nm dmoverio
.Nd hardware-assisted data mover interface
.Sh SYNOPSIS
.Cd pseudo-device dmoverio
.Pp
.In dev/dmover/dmover_io.h
.Sh DESCRIPTION
The
.Nm
pseudo-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 pattern, and perform simple operations on multiple regions of
memory, such as an XOR, without intervention by the CPU.
.Pp
A
.Nm
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 lengths of each input region and the output
region must be the same.  All
.Nm
functions with the same name will have the same number of and type inputs.
.Pp
To use
.Nm ,
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/dmoverio
device.
.It
Select the
.Nm
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
session, the session is destroyed by closing the session handle using
.Xr close 2 .
.Sh EXAMPLES
The following is an example of a client using
.Nm
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/dmoverio", 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;
	req.req_id = reqid++;

	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
device first appeared in
.Nx 2.0 .
.Sh AUTHORS
The
.Nm
device was designed and implemented by
.An Jason R. Thorpe
.Aq thorpej@wasabisystems.com
and contributed by Wasabi Systems, Inc.