'\" t
.\"     Title: usb_buffer_map_sg
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: January 2017
.\"    Manual: USB Core APIs
.\"    Source: Kernel Hackers Manual 4.8.15
.\"  Language: English
.\"
.TH "USB_BUFFER_MAP_SG" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "USB Core APIs"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
usb_buffer_map_sg \- create scatterlist DMA mapping(s) for an endpoint
.SH "SYNOPSIS"
.HP \w'int\ usb_buffer_map_sg('u
.BI "int usb_buffer_map_sg(const\ struct\ usb_device\ *\ " "dev" ", int\ " "is_in" ", struct\ scatterlist\ *\ " "sg" ", int\ " "nents" ");"
.SH "ARGUMENTS"
.PP
\fIdev\fR
.RS 4
device to which the scatterlist will be mapped
.RE
.PP
\fIis_in\fR
.RS 4
mapping transfer direction
.RE
.PP
\fIsg\fR
.RS 4
the scatterlist to map
.RE
.PP
\fInents\fR
.RS 4
the number of entries in the scatterlist
.RE
.SH "RETURN"
.PP
Either < 0 (indicating no buffers could be mapped), or the number of DMA mapping array entries in the scatterlist\&.
.SH "NOTE"
.PP
The caller is responsible for placing the resulting DMA addresses from the scatterlist into URB transfer buffer pointers, and for setting the URB_NO_TRANSFER_DMA_MAP transfer flag in each of those URBs\&.
.PP
Top I/O rates come from queuing URBs, instead of waiting for each one to complete before starting the next I/O\&. This is particularly easy to do with scatterlists\&. Just allocate and submit one URB for each DMA mapping entry returned, stopping on the first error or when all succeed\&. Better yet, use the usb_sg_*() calls, which do that (and more) for you\&.
.PP
This call would normally be used when translating scatterlist requests, rather than
\fBusb_buffer_map\fR, since on some hardware (with IOMMUs) it may be able to coalesce mappings for improved I/O efficiency\&.
.PP
Reverse the effect of this call with
\fBusb_buffer_unmap_sg\fR\&.
.SH "COPYRIGHT"
.br