Changeset View
Standalone View
share/man/man4/ioat.4
- This file was added.
.\" Copyright (c) 2015 EMC / Isilon Storage Division | |||||
.\" All rights reserved. | |||||
jimharris: share/man/man4/Makefile needs to be updated to include this man page. Suggest only installing… | |||||
Not Done Inline ActionsRight. Will do. Yes, I noticed other tools/tools/*/*.8 exist but aren't hooked up to the build (e.g. cxgbetool). I'll leave that be. cem: Right. Will do.
Yes, I noticed other tools/tools/*/*.8 exist but aren't hooked up to the build… | |||||
.\" | |||||
.\" 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. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE AUTHORS OR CONTRIBUTORS 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. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd August 24, 2015 | |||||
.Dt IOAT 4 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm I/OAT | |||||
.Nd Intel I/O Acceleration Technology | |||||
.Sh SYNOPSIS | |||||
.Cd "device ioat" | |||||
In | |||||
.Xr loader.conf 5 : | |||||
.Pp | |||||
.Cd hw.ioat.force_legacy_interrupts=0 | |||||
.Pp | |||||
In | |||||
Done Inline ActionsSince you added ioat to sys/modules/Makefile, ioat.ko will be built unless MODULES_OVERRIDE is set. If a user is setting MODULES_OVERRIDE, then they need to modify MODULES_OVERRIDE for _any_ kernel module that they want to build, which implies that every single driver man page should mention MODULES_OVERRIDE (and none of them do). For consistency, I would just remove the reference to it. If you disagree and want to keep it, it should also be noted that MODULES_OVERRIDE can be set in the kernel configuration file with "makeoptions", as a (very handy) alternative to make.conf. markj: Since you added ioat to sys/modules/Makefile, ioat.ko will be built unless MODULES_OVERRIDE is… | |||||
Not Done Inline ActionsOh, ok. Will drop that part then. cem: Oh, ok. Will drop that part then. | |||||
.Xr loader.conf 5 or | |||||
.Xr sysctl.conf 5 : | |||||
.Pp | |||||
.Cd hw.ioat.enable_ioat_test=0 | |||||
.Cd hw.ioat.debug_level=0 | |||||
(only critical errors; maximum of 3) | |||||
.Pp | |||||
.Ft typedef void | |||||
.Fn (*bus_dmaengine_callback_t) "void *arg" | |||||
.Pp | |||||
.Ft bus_dmaengine_t | |||||
.Fn ioat_get_dmaengine "uint32_t channel_index" | |||||
.Ft void | |||||
.Fn ioat_acquire "bus_dmaengine_t dmaengine" | |||||
.Ft void | |||||
.Fn ioat_release "bus_dmaengine_t dmaengine" | |||||
.Ft struct bus_dmadesc * | |||||
.Fo ioat_copy | |||||
.Fa "bus_dmaengine_t dmaengine" | |||||
.Fa "bus_addr_t dst" | |||||
.Fa "bus_addr_t src" | |||||
.Fa "bus_size_t len" | |||||
.Fa "bus_dmaengine_callback_t callback_fn" | |||||
.Fa "void *callback_arg" | |||||
.Fa "uint32_t flags" | |||||
.Fc | |||||
.Ft struct bus_dmadesc * | |||||
.Fo ioat_null | |||||
.Fa "bus_dmaengine_t dmaengine" | |||||
.Fa "bus_dmaengine_callback_t callback_fn" | |||||
.Fa "void *callback_arg" | |||||
.Fa "uint32_t flags" | |||||
.Fc | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm | |||||
driver provides a kernel API to a variety of DMA engines on some Intel server | |||||
platforms. | |||||
.Pp | |||||
There is a number of DMA channels per CPU package. | |||||
(Typically 4 or 8.) | |||||
Each may be used independently. | |||||
Operations on a single channel proceed sequentially. | |||||
.Pp | |||||
Done Inline Actions"on a some" markj: "on a some" | |||||
Copy operations may be used to offload memory copies to the DMA engines. | |||||
Done Inline ActionsCould you qualify "newer"? markj: Could you qualify "newer"? | |||||
Not Done Inline ActionsSandybridge+. I will add a blurb to the page. cem: Sandybridge+. I will add a blurb to the page. | |||||
Done Inline ActionsTylersburg and Jasper Forest are pre-Sandy Bridge. (On Tylersburg, it was actually in the chipset, not the CPU.) Also, these are only on Xeon-based CPUs.. Maybe just simplify this to "on some Intel server platforms" and avoid the extra complexity? jimharris: Tylersburg and Jasper Forest are pre-Sandy Bridge. (On Tylersburg, it was actually in the… | |||||
.Pp | |||||
Not Done Inline ActionsCan do. cem: Can do. | |||||
Null operations do nothing, but may be used to test the interrupt and callback | |||||
mechanism. | |||||
.Pp | |||||
All operations can optionally trigger an interrupt at completion with the | |||||
.Ar DMA_EN_INT | |||||
flag. | |||||
For example, a user might submit multiple operations to the same channel and | |||||
only enable an interrupt and callback for the last operation. | |||||
Done Inline ActionsTrigger an interrupt under what condition? markj: Trigger an interrupt under what condition? | |||||
Not Done Inline ActionsSuccessful completion of the null operation with DMA_INT_EN flagged. I'll note the flag. cem: Successful completion of the null operation with `DMA_INT_EN` flagged. I'll note the flag. | |||||
.Sh USAGE | |||||
A typical user will lookup the DMA engine object for a given channel with | |||||
Done Inline ActionsWhat does "grab" mean? Does it give the caller exclusive access to the channel? markj: What does "grab" mean? Does it give the caller exclusive access to the channel? | |||||
Not Done Inline ActionsNo; I was trying to avoid 'acquire' because that has some baggage too. Really the caller just uses ioat_get_dmaengine() to look up the bus_dmaengine_t for a given channel index, which is just a number. There is no refcount or exclusive access semantics here. I'll reword. cem: No; I was trying to avoid 'acquire' because that has some baggage too.
Really the caller just… | |||||
.Fn ioat_get_dmaengine . | |||||
When the user wants to offload a copy, they will first | |||||
.Fn ioat_acquire | |||||
the | |||||
.Ar bus_dmaengine_t | |||||
Done Inline ActionsWhat's a submission lock? markj: What's a submission lock? | |||||
Not Done Inline ActionsExclusive access to submit operations on the given channel / DMA engine. cem: Exclusive access to submit operations on the given channel / DMA engine. | |||||
object for exclusive access to enqueue operations on that channel. | |||||
Then, they will submit one or more operations using | |||||
.Fn ioat_copy | |||||
or | |||||
.Fn ioat_null . | |||||
Finally, they will | |||||
.Fn ioat_release | |||||
the | |||||
.Ar bus_dmaengine_t | |||||
to drop their exclusive access to the channel. | |||||
The routine they provided for the | |||||
.Fa callback_fn | |||||
argument will be invoked with the provided | |||||
.Fa callback_arg | |||||
when the operation is complete. | |||||
.Pp | |||||
For an example of usage, see | |||||
.Pa src/sys/dev/ioat/ioat_test.c . | |||||
.Sh FILES | |||||
.Bl -tag -compat | |||||
.It Pa /dev/ioat_test | |||||
test device for | |||||
.Xr ioatcontrol 8 | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr ioatcontrol 8 | |||||
.Sh HISTORY | |||||
The | |||||
.Nm | |||||
driver first appeared in | |||||
.Fx 11.0 . | |||||
.Sh AUTHORS | |||||
The | |||||
.Nm | |||||
driver was developed by | |||||
.An \&Jim Harris Aq Mt jimharris@FreeBSD.org , | |||||
and | |||||
.An \&Carl Delsey Aq Mt carl.r.delsey@intel.com . | |||||
This manual page was written by | |||||
.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . | |||||
.Sh CAVEATS | |||||
Copy operation takes bus addresses as parameters, not virtual addresses. | |||||
.Pp | |||||
Copies larger than max transfer size (1MB) are not supported. | |||||
Future versions will likely support this by breaking up the transfer into | |||||
smaller sizes. | |||||
.Sh BUGS | |||||
The | |||||
.Nm | |||||
driver only supports copy and null operations at this time. | |||||
The driver does not yet support advanced DMA modes, such as XOR, that some | |||||
I/OAT devices support. |
share/man/man4/Makefile needs to be updated to include this man page. Suggest only installing it on amd64.
I would not add ioatcontrol.8 to share/man/man8/Makefile, since ioatcontrol is not part of the standard build.