Manual page for pseudo-device access to hardware-assisted data movers.
This commit is contained in:
thorpej
parent
d09e51c588
commit
a564ee723c
@ -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 \
|
||||
|
||||
243
share/man/man4/dmoverio.4
Normal file
243
share/man/man4/dmoverio.4
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user