share/man/man9/sglist.9

   1 .\"
   2 .\" Copyright (c) 2009 Advanced Computing Technologies LLC
   3 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   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.
  14 .\"
  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
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd May 15, 2009
  30 .Dt SGLIST 9
  31 .Os
  32 .Sh NAME
  33 .Nm sglist ,
  34 .Nm sglist_alloc ,
  35 .Nm sglist_append ,
  36 .Nm sglist_append_mbuf ,
  37 .Nm sglist_append_phys ,
  38 .Nm sglist_append_uio ,
  39 .Nm sglist_append_user ,
  40 .Nm sglist_build ,
  41 .Nm sglist_clone ,
  42 .Nm sglist_consume_uio ,
  43 .Nm sglist_count ,
  44 .Nm sglist_free ,
  45 .Nm sglist_hold ,
  46 .Nm sglist_init ,
  47 .Nm sglist_join ,
  48 .Nm sglist_length ,
  49 .Nm sglist_reset ,
  50 .Nm sglist_slice ,
  51 .Nm sglist_split
  52 .Nd manage a scatter/gather list of physical memory addresses
  53 .Sh SYNOPSIS
  54 .In sys/types.h
  55 .In sys/sglist.h
  56 .Ft struct sglist *
  57 .Fn sglist_alloc "int nsegs" "int mflags"
  58 .Ft int
  59 .Fn sglist_append "struct sglist *sg" "void *buf" "size_t len"
  60 .Ft int
  61 .Fn sglist_append_mbuf "struct sglist *sg" "struct mbuf *m"
  62 .Ft int
  63 .Fn sglist_append_phys "struct sglist *sg" "vm_paddr_t paddr" "size_t len"
  64 .Ft int
  65 .Fn sglist_append_uio "struct sglist *sg" "struct uio *uio"
  66 .Ft int
  67 .Fn sglist_append_user "struct sglist *sg" "void *buf" "size_t len" "struct thread *td"
  68 .Ft struct sglist *
  69 .Fn sglist_build "void *buf" "size_t len" "int mflags"
  70 .Ft struct sglist *
  71 .Fn sglist_clone "struct sglist *sg" "int mflags"
  72 .Ft int
  73 .Fn sglist_consume_uio "struct sglist *sg" "struct uio *uio" "int resid"
  74 .Ft int
  75 .Fn sglist_count "void *buf" "size_t len"
  76 .Ft void
  77 .Fn sglist_free "struct sglist *sg"
  78 .Ft struct sglist *
  79 .Fn sglist_hold "struct sglist *sg"
  80 .Ft void
  81 .Fn sglist_init "struct sglist *sg" "int maxsegs" "struct sglist_seg *segs"
  82 .Ft int
  83 .Fn sglist_join "struct sglist *first" "struct sglist *second"
  84 .Ft size_t
  85 .Fn sglist_length "struct sglist *sg"
  86 .Ft void
  87 .Fn sglist_reset "struct sglist *sg"
  88 .Ft int
  89 .Fn sglist_slice "struct sglist *original" "struct sglist **slice" "size_t offset" "size_t length" "int mflags"
  90 .Ft int
  91 .Fn sglist_split "struct sglist *original" "struct sglist **head" "size_t length" "int mflags"
  92 .Sh DESCRIPTION
  93 The
  94 .Nm
  95 API manages physical address ranges.
  96 Each list contains one or more elements.
  97 Each element contains a starting physical address and a length.
  98 Scatter/gather lists are read-only while they are shared.
  99 If one wishes to alter an existing scatter/gather list and does not hold the
 100 sole reference to the list,
 101 then one should create a new list instead of modifying the existing list.
 102 .Pp
 103 Each scatter/gather list object contains a reference count.
 104 New lists are created with a single reference.
 105 New references are obtained by calling
 106 .Nm sglist_hold
 107 and are released by calling
 108 .Nm sglist_free .
 109 .Ss Allocating and Initializing Lists
 110 Each
 111 .Nm
 112 object consists of a header structure and a variable-length array of
 113 scatter/gather list elements.
 114 The
 115 .Nm sglist_alloc
 116 function allocates a new list that contains a header and
 117 .Fa nsegs
 118 scatter/gather list elements.
 119 The
 120 .Fa mflags
 121 argument can be set to either
 122 .Dv M_NOWAIT
 123 or
 124 .Dv M_WAITOK .
 125 .Pp
 126 The
 127 .Nm sglist_count
 128 function returns the number of scatter/gather list elements needed to describe
 129 the physical address ranges mapped by a single kernel virtual address range.
 130 The kernel virtual address range starts at
 131 .Fa buf
 132 and is
 133 .Fa len
 134 bytes long.
 135 .Pp
 136 The
 137 .Nm sglist_build
 138 function allocates a new scatter/gather list object that describes the physical
 139 address ranges mapped by a single kernel virtual address range.
 140 The kernel virtual address range starts at
 141 .Fa buf
 142 and is
 143 .Fa len
 144 bytes long.
 145 The
 146 .Fa mflags
 147 argument can be set to either
 148 .Dv M_NOWAIT
 149 or
 150 .Dv M_WAITOK .
 151 .Pp
 152 The
 153 .Nm sglist_clone
 154 function returns a copy of an exising scatter/gather list object
 155 .Fa sg .
 156 The
 157 .Fa mflags
 158 argument can be set to either
 159 .Dv M_NOWAIT
 160 or
 161 .Dv M_WAITOK .
 162 This can be used to obtain a private copy of a scatter/gather list before
 163 modifying it.
 164 .Pp
 165 The
 166 .Nm sglist_init
 167 function initializes a scatter/gather list header.
 168 The header is pointed to by
 169 .Fa sg
 170 and is initialized to manage an array of
 171 .Fa maxsegs
 172 scatter/gather list elements pointed to by
 173 .Fa segs .
 174 This can be used to initialize a scatter/gather list header whose storage
 175 is not provided by
 176 .Nm sglist_alloc .
 177 In that case, the caller should not call
 178 .Nm sglist_free
 179 to release its own reference and is responsible for ensuring all other
 180 references to the list are dropped before it releases the storage for
 181 .Fa sg
 182 and
 183 .Fa segs .
 184 .Ss Constructing Scatter/Gather Lists
 185 The
 186 .Nm
 187 API provides several routines for building a scatter/gather list to describe
 188 one or more objects.
 189 Specifically, the
 190 .Nm sglist_append
 191 family of routines can be used to append the physical address ranges described
 192 by an object to the end of a scatter/gather list.
 193 All of these routines return 0 on success or an error on failure.
 194 .Pp
 195 The
 196 .Nm sglist_append
 197 function appends the physical address ranges described by a single kernel
 198 virtual address range to the scatter/gather list
 199 .Fa sg .
 200 The kernel virtual address range starts at
 201 .Fa buf
 202 and is
 203 .Fa len
 204 bytes long.
 205 .Pp
 206 The
 207 .Nm sglist_append_mbuf
 208 function appends the physical address ranges described by an entire mbuf
 209 chain
 210 .Fa m
 211 to the scatter/gather list
 212 .Fa sg .
 213 .Pp
 214 The
 215 .Nm sglist_append_phys
 216 function appends a single physical address range to the scatter/gather list
 217 .Fa sg .
 218 The physical address range starts at
 219 .Fa paddr
 220 and is
 221 .Fa len
 222 bytes long.
 223 .Pp
 224 The
 225 .Nm sglist_append_uio
 226 function appends the physical address ranges described by a
 227 .Xr uio 9
 228 object to the scatter/gather list
 229 .Fa sg .
 230 Note that it is the caller's responsibility to ensure that the pages backing
 231 the I/O request are wired for the lifetime of
 232 .Fa sg .
 233 Note also that this routine does not modify
 234 .Fa uio .
 235 .Pp
 236 The
 237 .Nm sglist_append_user
 238 function appends the physical address ranges described by a single user
 239 virtual address range to the scatter/gather list
 240 .Fa sg .
 241 The user virtual address range is relative to the address space of the thread
 242 .Fa td .
 243 It starts at
 244 .Fa buf
 245 and is
 246 .Fa len
 247 bytes long.
 248 Note that it is the caller's responsibility to ensure that the pages backing
 249 the user buffer are wired for the lifetime of
 250 .Fa sg .
 251 .Pp
 252 The
 253 .Nm sglist_consume_uio
 254 function is a variation of
 255 .Nm sglist_append_uio .
 256 As with
 257 .Nm sglist_append_uio ,
 258 it appends the physical address ranges described by
 259 .Fa uio
 260 to the scatter/gather list
 261 .Fa sg .
 262 Unlike
 263 .Nm sglist_append_uio ,
 264 however,
 265 .Nm sglist_consume_uio
 266 modifies the I/O request to indicate that the appended address ranges have
 267 been processed similar to calling
 268 .Xr uiomove 9 .
 269 This routine will only append ranges that describe up to
 270 .Fa resid
 271 total bytes in length.
 272 If the available segments in the scatter/gather list are exhausted before
 273 .Fa resid
 274 bytes are processed,
 275 then the
 276 .Fa uio
 277 structure will be updated to reflect the actual number of bytes processed,
 278 and
 279 .Nm sglist_consume_io
 280 will return zero to indicate success.
 281 In effect, this function will perform partial reads or writes.
 282 The caller can compare the
 283 .Fa uio_resid
 284 member of
 285 .Fa uio
 286 before and after calling
 287 .Nm sglist_consume_uio
 288 to determine the actual number of bytes processed.
 289 .Ss Manipulating Scatter/Gather Lists
 290 The
 291 .Nm sglist_join
 292 function appends physical address ranges from the scatter/gather list
 293 .Fa second
 294 onto
 295 .Fa first
 296 and then resets
 297 .Fa second
 298 to an empty list.
 299 It returns zero on success or an error on failure.
 300 .Pp
 301 The
 302 .Nm sglist_split
 303 function splits an existing scatter/gather list into two lists.
 304 The first
 305 .Fa length
 306 bytes described by the list
 307 .Fa original
 308 are moved to a new list
 309 .Fa *head .
 310 If
 311 .Fa original
 312 describes a total address range that is smaller than
 313 .Fa length
 314 bytes,
 315 then all of the address ranges will be moved to the new list at
 316 .Fa *head
 317 and
 318 .Fa original
 319 will be an empty list.
 320 The caller may supply an existing scatter/gather list in
 321 .Fa *head .
 322 If so, the list must be empty.
 323 Otherwise, the caller may set
 324 .Fa *head
 325 to
 326 .Dv NULL
 327 in which case a new scatter/gather list will be allocated.
 328 In that case,
 329 .Fa mflags
 330 may be set to either
 331 .Dv M_NOWAIT
 332 or
 333 .Dv M_WAITOK .
 334 Note that since the
 335 .Fa original
 336 list is modified by this call, it must be a private list with no other
 337 references.
 338 The
 339 .Nm sglist_split
 340 function returns zero on success or an error on failure.
 341 .Pp
 342 The
 343 .Nm sglist_slice
 344 function generates a new scatter/gather list from a sub-range of an existing
 345 scatter/gather list
 346 .Fa original .
 347 The sub-range to extract is specified by the
 348 .Fa offset
 349 and
 350 .Fa length
 351 parameters.
 352 The new scatter/gather list is stored in
 353 .Fa *slice .
 354 As with
 355 .Fa head
 356 for
 357 .Nm sglist_join ,
 358 the caller may either provide an empty scatter/gather list,
 359 or it may set
 360 .Fa *slice
 361 to
 362 .Dv NULL
 363 in which case
 364 .Nm sglist_slice
 365 will allocate a new list subject to
 366 .Fa mflags .
 367 Unlike
 368 .Nm sglist_split ,
 369 .Nm sglist_slice
 370 does not modify
 371 .Fa original
 372 and does not require it to be a private list.
 373 The
 374 .Nm sglist_split
 375 function returns zero on success or an error on failure.
 376 .Ss Miscellaneous Routines
 377 The
 378 .Nm sglist_reset
 379 function clears the scatter/gather list
 380 .Fa sg
 381 so that it no longer maps any address ranges.
 382 This can allow reuse of a single scatter/gather list object for multiple
 383 requests.
 384 .Pp
 385 The
 386 .Nm sglist_length
 387 function returns the total length of the physical address ranges described
 388 by the scatter/gather list
 389 .Fa sg .
 390 .Sh RETURN VALUES
 391 The
 392 .Nm sglist_alloc ,
 393 .Nm sglist_build ,
 394 and
 395 .Nm sglist_clone
 396 functions return a new scatter/gather list on success or
 397 .Dv NULL
 398 on failure.
 399 .Pp
 400 The
 401 .Nm sglist_append
 402 family of functions and the
 403 .Nm sglist_consume_uio ,
 404 .Nm sglist_join ,
 405 .Nm sglist_slice ,
 406 and
 407 .Nm sglist_split
 408 functions return zero on success or an error on failure.
 409 .Pp
 410 The
 411 .Nm sglist_count
 412 function returns a count of scatter/gather list elements.
 413 .Pp
 414 The
 415 .Nm sglist_length
 416 function returns a count of address space described by a scatter/gather list
 417 in bytes.
 418 .Sh ERRORS
 419 The
 420 .Nm sglist_append
 421 functions return the following errors on failure:
 422 .Bl -tag -width Er
 423 .It Bq Er EINVAL
 424 The scatter/gather list has zero segments.
 425 .It Bq Er EFBIG
 426 There are not enough available segments in the scatter/gather list to append
 427 the specified physical address ranges.
 428 .El
 429 .Pp
 430 The
 431 .Nm sglist_consume_uio
 432 function returns the following error on failure:
 433 .Bl -tag -width Er
 434 .It Bq Er EINVAL
 435 The scatter/gather list has zero segments.
 436 .El
 437 .Pp
 438 The
 439 .Nm sglist_join
 440 function returns the following error on failure:
 441 .Bl -tag -width Er
 442 .It Bq Er EFBIG
 443 There are not enough available segments in the scatter/gather list
 444 .Fa first
 445 to append the physical address ranges from
 446 .Fa second .
 447 .El
 448 The
 449 .Nm sglist_slice
 450 function returns the following errors on failure:
 451 .Bl -tag -width Er
 452 .It Bq Er EINVAL
 453 The
 454 .Fa original
 455 scatter/gather list does not describe enough address space to cover the
 456 requested sub-range.
 457 .It Bq Er EINVAL
 458 The caller-supplied scatter/gather list in
 459 .Fa *slice
 460 is not empty.
 461 .It Bq Er ENOMEM
 462 An attempt to allocate a new scatter/gather list with
 463 .Dv M_NOWAIT
 464 set in
 465 .Fa mflags
 466 failed.
 467 .It Bq Er EFBIG
 468 There are not enough available segments in the caller-supplied scatter/gather
 469 list in
 470 .Fa *slice
 471 to describe the requested physical address ranges.
 472 .El
 473 The
 474 .Nm sglist_split
 475 function returns the following errors on failure:
 476 .Bl -tag -width Er
 477 .It Bq Er EDOOFUS
 478 The
 479 .Fa original
 480 scatter/gather list has more than one reference.
 481 .It Bq Er EINVAL
 482 The caller-supplied scatter/gather list in
 483 .Fa *head
 484 is not empty.
 485 .It Bq Er ENOMEM
 486 An attempt to allocate a new scatter/gather list with
 487 .Dv M_NOWAIT
 488 set in
 489 .Fa mflags
 490 failed.
 491 .It Bq Er EFBIG
 492 There are not enough available segments in the caller-supplied scatter/gather
 493 list in
 494 .Fa *head
 495 to describe the requested physical address ranges.
 496 .El
 497 .Sh SEE ALSO
 498 .Xr malloc 9 ,
 499 .Xr mbuf 9 ,
 500 .Xr uio 9
 501 .Sh HISTORY
 502 This API was first introduced in
 503 .Fx 8.0 .