2 .\" Copyright (c) 2009 Advanced Computing Technologies LLC
3 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" $FreeBSD: src/share/man/man9/sglist.9,v 1.4 2010/07/31 10:01:15 joel Exp $
36 .Nm sglist_append_mbuf ,
37 .Nm sglist_append_phys ,
38 .Nm sglist_append_uio ,
39 .Nm sglist_append_user ,
42 .Nm sglist_consume_uio ,
52 .Nd manage a scatter/gather list of physical memory addresses
58 .Fn sglist_alloc "int nsegs" "int mflags"
60 .Fn sglist_append "struct sglist *sg" "void *buf" "size_t len"
62 .Fn sglist_append_mbuf "struct sglist *sg" "struct mbuf *m"
64 .Fn sglist_append_phys "struct sglist *sg" "vm_paddr_t paddr" "size_t len"
66 .Fn sglist_append_uio "struct sglist *sg" "struct uio *uio"
68 .Fn sglist_append_user "struct sglist *sg" "void *buf" "size_t len" "struct thread *td"
70 .Fn sglist_build "void *buf" "size_t len" "int mflags"
72 .Fn sglist_clone "struct sglist *sg" "int mflags"
74 .Fn sglist_consume_uio "struct sglist *sg" "struct uio *uio" "size_t resid"
76 .Fn sglist_count "void *buf" "size_t len"
78 .Fn sglist_free "struct sglist *sg"
80 .Fn sglist_hold "struct sglist *sg"
82 .Fn sglist_init "struct sglist *sg" "u_short maxsegs" "struct sglist_seg *segs"
84 .Fn sglist_join "struct sglist *first" "struct sglist *second"
86 .Fn sglist_length "struct sglist *sg"
88 .Fn sglist_reset "struct sglist *sg"
90 .Fn sglist_slice "struct sglist *original" "struct sglist **slice" "size_t offset" "size_t length" "int mflags"
92 .Fn sglist_split "struct sglist *original" "struct sglist **head" "size_t length" "int mflags"
96 API manages physical address ranges.
97 Each list contains one or more elements.
98 Each element contains a starting physical address and a length.
99 Scatter/gather lists are read-only while they are shared.
100 If one wishes to alter an existing scatter/gather list and does not hold the
101 sole reference to the list,
102 then one should create a new list instead of modifying the existing list.
104 Each scatter/gather list object contains a reference count.
105 New lists are created with a single reference.
106 New references are obtained by calling
108 and are released by calling
110 .Ss Allocating and Initializing Lists
113 object consists of a header structure and a variable-length array of
114 scatter/gather list elements.
117 function allocates a new list that contains a header and
119 scatter/gather list elements.
122 argument can be set to either
129 function returns the number of scatter/gather list elements needed to describe
130 the physical address ranges mapped by a single kernel virtual address range.
131 The kernel virtual address range starts at
139 function allocates a new scatter/gather list object that describes the physical
140 address ranges mapped by a single kernel virtual address range.
141 The kernel virtual address range starts at
148 argument can be set to either
155 function returns a copy of an existing scatter/gather list object
159 argument can be set to either
163 This can be used to obtain a private copy of a scatter/gather list before
168 function initializes a scatter/gather list header.
169 The header is pointed to by
171 and is initialized to manage an array of
173 scatter/gather list elements pointed to by
175 This can be used to initialize a scatter/gather list header whose storage
178 In that case, the caller should not call
180 to release its own reference and is responsible for ensuring all other
181 references to the list are dropped before it releases the storage for
185 .Ss Constructing Scatter/Gather Lists
188 API provides several routines for building a scatter/gather list to describe
192 family of routines can be used to append the physical address ranges described
193 by an object to the end of a scatter/gather list.
194 All of these routines return 0 on success or an error on failure.
195 If a request to append an address range to a scatter/gather list fails,
196 the scatter/gather list will remain unchanged.
200 function appends the physical address ranges described by a single kernel
201 virtual address range to the scatter/gather list
203 The kernel virtual address range starts at
210 .Nm sglist_append_mbuf
211 function appends the physical address ranges described by an entire mbuf
214 to the scatter/gather list
218 .Nm sglist_append_phys
219 function appends a single physical address range to the scatter/gather list
221 The physical address range starts at
228 .Nm sglist_append_uio
229 function appends the physical address ranges described by a
231 object to the scatter/gather list
233 Note that it is the caller's responsibility to ensure that the pages backing
234 the I/O request are wired for the lifetime of
236 Note also that this routine does not modify
240 .Nm sglist_append_user
241 function appends the physical address ranges described by a single user
242 virtual address range to the scatter/gather list
244 The user virtual address range is relative to the address space of the thread
251 Note that it is the caller's responsibility to ensure that the pages backing
252 the user buffer are wired for the lifetime of
256 .Nm sglist_consume_uio
257 function is a variation of
258 .Nm sglist_append_uio .
260 .Nm sglist_append_uio ,
261 it appends the physical address ranges described by
263 to the scatter/gather list
266 .Nm sglist_append_uio ,
268 .Nm sglist_consume_uio
269 modifies the I/O request to indicate that the appended address ranges have
270 been processed similar to calling
272 This routine will only append ranges that describe up to
274 total bytes in length.
275 If the available segments in the scatter/gather list are exhausted before
280 structure will be updated to reflect the actual number of bytes processed,
282 .Nm sglist_consume_io
283 will return zero to indicate success.
284 In effect, this function will perform partial reads or writes.
285 The caller can compare the
289 before and after calling
290 .Nm sglist_consume_uio
291 to determine the actual number of bytes processed.
292 .Ss Manipulating Scatter/Gather Lists
295 function appends physical address ranges from the scatter/gather list
302 It returns zero on success or an error on failure.
306 function splits an existing scatter/gather list into two lists.
309 bytes described by the list
311 are moved to a new list
315 describes a total address range that is smaller than
318 then all of the address ranges will be moved to the new list at
322 will be an empty list.
323 The caller may supply an existing scatter/gather list in
325 If so, the list must be empty.
326 Otherwise, the caller may set
330 in which case a new scatter/gather list will be allocated.
339 list is modified by this call, it must be a private list with no other
343 function returns zero on success or an error on failure.
347 function generates a new scatter/gather list from a sub-range of an existing
350 The sub-range to extract is specified by the
355 The new scatter/gather list is stored in
361 the caller may either provide an empty scatter/gather list,
368 will allocate a new list subject to
375 and does not require it to be a private list.
378 function returns zero on success or an error on failure.
379 .Ss Miscellaneous Routines
382 function clears the scatter/gather list
384 so that it no longer maps any address ranges.
385 This can allow reuse of a single scatter/gather list object for multiple
390 function returns the total length of the physical address ranges described
391 by the scatter/gather list
399 functions return a new scatter/gather list on success or
405 family of functions and the
406 .Nm sglist_consume_uio ,
411 functions return zero on success or an error on failure.
415 function returns a count of scatter/gather list elements.
419 function returns a count of address space described by a scatter/gather list
424 functions return the following errors on failure:
427 The scatter/gather list has zero segments.
429 There are not enough available segments in the scatter/gather list to append
430 the specified physical address ranges.
434 .Nm sglist_consume_uio
435 function returns the following error on failure:
438 The scatter/gather list has zero segments.
443 function returns the following error on failure:
446 There are not enough available segments in the scatter/gather list
448 to append the physical address ranges from
454 function returns the following errors on failure:
459 scatter/gather list does not describe enough address space to cover the
462 The caller-supplied scatter/gather list in
466 An attempt to allocate a new scatter/gather list with
472 There are not enough available segments in the caller-supplied scatter/gather
475 to describe the requested physical address ranges.
480 function returns the following errors on failure:
485 scatter/gather list has more than one reference.
487 The caller-supplied scatter/gather list in
491 An attempt to allocate a new scatter/gather list with
497 There are not enough available segments in the caller-supplied scatter/gather
500 to describe the requested physical address ranges.
507 This API was first introduced in