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