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