diff options
Diffstat (limited to 'static/netbsd/man4/dmoverio.4 4.html')
| -rw-r--r-- | static/netbsd/man4/dmoverio.4 4.html | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/static/netbsd/man4/dmoverio.4 4.html b/static/netbsd/man4/dmoverio.4 4.html new file mode 100644 index 00000000..aeacc40a --- /dev/null +++ b/static/netbsd/man4/dmoverio.4 4.html @@ -0,0 +1,204 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DMOVERIO(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">DMOVERIO(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">dmoverio</code> — + <span class="Nd">hardware-assisted data mover interface</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">pseudo-device dmoverio</code></p> +<p class="Pp"> + <br/> + <code class="In">#include + <<a class="In">dev/dmover/dmover_io.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">dmoverio</code> pseudo-device driver provides + an interface to hardware-assisted data movers, which the kernel supports + using the <a class="Xr">dmover(9)</a> 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.</p> +<p class="Pp">A <code class="Nm">dmoverio</code> 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 + <code class="Nm">dmoverio</code> functions with the same name will have the + same number of and type inputs.</p> +<p class="Pp">To use <code class="Nm">dmoverio</code>, the client must first + create a session. This is achieved by performing the following steps:</p> +<ul class="Bl-bullet"> + <li>Create a session handle by opening the + <span class="Pa">/dev/dmoverio</span> device.</li> + <li>Select the <code class="Nm">dmoverio</code> function using the + DMIO_SETFUNC ioctl, which takes the following argument: + <div class="Bd Pp Bd-indent Li"> + <pre>#define DMIO_MAX_FUNCNAME 64 +struct dmio_setfunc { + char dsf_name[DMIO_MAX_FUNCNAME]; +};</pre> + </div> + <p class="Pp">If the specified function is not available, the DMIO_SETFUNC + ioctl will fail with an error code of <code class="Er">ESRCH</code>.</p> + </li> +</ul> +<p class="Pp">To submit a request for processing the following steps must be + performed:</p> +<ul class="Bl-bullet"> + <li>Fill in a request structure: + <div class="Bd Pp Bd-indent Li"> + <pre>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 */ +};</pre> + </div> + <p class="Pp" id="req_immediate">For functions which use an immediate value + as an input, the + <a class="permalink" href="#req_immediate"><i class="Em">req_immediate</i></a> + 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.</p> + <p class="Pp" id="req_inbuf">For functions which use input regions, + <a class="permalink" href="#req_inbuf"><i class="Em">req_inbuf</i></a> + should point to an array of <var class="Fa">dmio_buffer</var>'s.</p> + <p class="Pp">The <i class="Em">req_id</i> 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.</p> + </li> + <li>Write the request structure to the session handle using the + <a class="Xr">write(2)</a> system call. Multiple requests may be written + to the session in a single call.</li> + <li>Read the response structure back from the session handle using the + <a class="Xr">read(2)</a> system call. The response structure is defined + as follows: + <div class="Bd Pp Bd-indent Li"> + <pre>struct dmio_usrresp { + uint32_t resp_id; + int resp_error; +};</pre> + </div> + <p class="Pp" id="resp_id">The + <a class="permalink" href="#resp_id"><i class="Em">resp_id</i></a> + corresponds to the <i class="Em">req_id</i> in the request. + <a class="permalink" href="#resp_error"><i class="Em" id="resp_error">resp_error</i></a> + contains 0 if the request succeeded or an <a class="Xr">errno(2)</a> + 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.</p> + </li> +</ul> +<p class="Pp">When a client is finished using a <code class="Nm">dmoverio</code> + session, the session is destroyed by closing the session handle using + <a class="Xr">close(2)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following is an example of a client using + <code class="Nm">dmoverio</code> 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.</p> +<div class="Bd Pp Li"> +<pre>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); +}</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">dmover(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">dmoverio</code> device first appeared in + <span class="Ux">NetBSD 2.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">dmoverio</code> device was designed and + implemented by <span class="An">Jason R. Thorpe</span> + ⟨thorpej@wasabisystems.com⟩ and contributed by Wasabi Systems, + Inc.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 1, 2002</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> |