share/man/man9/sglist.9

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