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