SGLIST(9)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

okay so bestie, this is the SGLIST(9) page from the Kernel Developer's Manual, and it's basically the group chat for managing a scatter/gather list of physical memory addresses. The whole squad is: sglist, sglist_alloc, sglist_append, sglist_append_bio, sglist_append_mbuf, sglist_append_mbuf_epg, sglist_append_phys, sglist_append_sglist, sglist_append_single_mbuf, sglist_append_uio, sglist_append_user, sglist_append_vmpages, sglist_build, sglist_clone, sglist_consume_uio, sglist_count, sglist_count_mbuf_epg, sglist_count_vmpages, sglist_free, sglist_hold, sglist_init, sglist_join, sglist_length, sglist_reset, sglist_slice, and sglist_split — and they all manage a scatter/gather list of physical memory addresses. iconic behavior, honestly.

✨ SYNOPSIS ✨

here are the exact signatures, no cap — copy them character for character:

#include <sys/types.h>
#include <sys/sglist.h>

struct sglist *
sglist_alloc(int nsegs, int mflags);

int
sglist_append(struct sglist *sg, void *buf, size_t len);

int
sglist_append_bio(struct sglist *sg, struct bio *bp);

int
sglist_append_mbuf_epg(struct sglist *sg, struct mbuf *m, size_t offset,
    size_t len);

int
sglist_append_mbuf(struct sglist *sg, struct mbuf *m);

int
sglist_append_phys(struct sglist *sg, vm_paddr_t paddr, size_t len);

int
sglist_append_sglist(struct sglist *sg, struct sglist *source,
    size_t offset, size_t len);

int
sglist_append_single_mbuf(struct sglist *sg, struct mbuf *m);

int
sglist_append_uio(struct sglist *sg, struct uio *uio);

int
sglist_append_user(struct sglist *sg, void *buf, size_t len,
    struct thread *td);

int
sglist_append_vmpages(struct sglist *sg, vm_page_t *m, size_t pgoff,
    size_t len);

struct sglist *
sglist_build(void *buf, size_t len, int mflags);

struct sglist *
sglist_clone(struct sglist *sg, int mflags);

int
sglist_consume_uio(struct sglist *sg, struct uio *uio, size_t resid);

int
sglist_count(void *buf, size_t len);

int
sglist_count_mbuf_epg(struct mbuf *m, size_t offset, size_t len);

int
sglist_count_vmpages(vm_page_t *m, size_t pgoff, size_t len);

void
sglist_free(struct sglist *sg);

struct sglist *
sglist_hold(struct sglist *sg);

void
sglist_init(struct sglist *sg, int maxsegs, struct sglist_seg *segs);

int
sglist_join(struct sglist *first, struct sglist *second);

size_t
sglist_length(struct sglist *sg);

void
sglist_reset(struct sglist *sg);

int
sglist_slice(struct sglist *original, struct sglist **slice,
    size_t offset, size_t length, int mflags);

int
sglist_split(struct sglist *original, struct sglist **head,
    size_t length, int mflags);

💖 DESCRIPTION 💖

okay so bestie, the sglist API is literally all about managing physical address ranges. Each list has one or more elements, and every element is just a starting physical address plus a length. That's the whole vibe.

Scatter/gather lists are read-only while they are shared. If you wanna alter an existing scatter/gather list and you don't hold the sole reference to it, do not modify it — create a new list instead. no cap.

Every scatter/gather list object has a reference count. New lists are created with a single reference. You grab new references with sglist_hold and release them with sglist_free. 🫶

✨ Allocating and Initializing Lists ✨

Each sglist object is a header structure plus a variable-length array of scatter/gather list elements. iconic.

  • sglist_alloc — allocates a new list with a header and nsegs scatter/gather list elements. The mflags argument can be set to either M_NOWAIT or M_WAITOK.
  • sglist_count — returns the number of scatter/gather list elements needed to describe the physical address ranges mapped by a single kernel virtual address range. That range starts at buf and is len bytes long.
  • sglist_count_mbuf_epg — returns the number of scatter/gather list elements needed to describe the external multipage mbuf buffer m. The ranges start at an offset of offset relative to the start of the buffer and are len bytes long.
  • sglist_count_vmpages — returns the number of scatter/gather list elements needed to describe the physical address ranges of a buffer backed by an array of virtual memory pages m. The buffer starts at an offset of pgoff bytes relative to the first page and is len bytes long.
  • sglist_build — allocates a new scatter/gather list object that describes the physical address ranges mapped by a single kernel virtual address range. The range starts at buf and is len bytes long. The mflags argument can be set to either M_NOWAIT or M_WAITOK.
  • sglist_clone — returns a copy of an existing scatter/gather list object sg. The mflags argument can be set to either M_NOWAIT or M_WAITOK. This is how you get a private copy before modifying it. 💅
  • sglist_init — initializes a scatter/gather list header. The header is pointed to by sg and is initialized to manage an array of maxsegs scatter/gather list elements pointed to by segs.

sglist_init is the move when the header storage wasn't provided by sglist_alloc. In that case, the caller should not call sglist_free to release its own reference, and the caller is responsible for making sure all other references to the list are dropped before it releases the storage for sg and segs. don't forget that part, bestie 😭

🧚 Constructing Scatter/Gather Lists 🧚

The sglist API gives you a whole little family of routines for building a scatter/gather list that describes one or more objects. Specifically, the sglist_append family appends the physical address ranges described by an object to the end of a scatter/gather list.

All of these routines return 0 on success or an error on failure. And if a request to append an address range to a scatter/gather list fails, the scatter/gather list will remain unchanged. slay.

  • sglist_append — appends the physical address ranges described by a single kernel virtual address range to the scatter/gather list sg. The range starts at buf and is len bytes long.
  • sglist_append_bio — appends the physical address ranges described by a single bio bp to the scatter/gather list sg.
  • sglist_append_mbuf_epg — appends the physical address ranges described by the external multipage mbuf(9) buffer ext_pgs to the scatter/gather list sg. The physical address ranges start at offset offset within ext_pgs and continue for len bytes. Note that unlike sglist_append_mbuf, sglist_append_mbuf_epg only adds ranges for a single mbuf, not an entire mbuf chain.
  • sglist_append_mbuf — appends the physical address ranges described by an entire mbuf chain m to the scatter/gather list sg.
  • sglist_append_single_mbuf — appends the physical address ranges described by a single mbuf m to the scatter/gather list sg.
  • sglist_append_phys — appends a single physical address range to the scatter/gather list sg. The physical address range starts at paddr and is len bytes long.
  • sglist_append_sglist — appends physical address ranges described by the scatter/gather list source to the scatter/gather list sg. The physical address ranges start at offset offset within source and continue for len bytes.
  • sglist_append_uio — appends the physical address ranges described by a uio(9) object to the scatter/gather list sg. It is the caller's responsibility to ensure that the pages backing the I/O request are wired for the lifetime of sg. Also note that this routine does not modify uio.
  • sglist_append_user — appends the physical address ranges described by a single user virtual address range to the scatter/gather list sg. The user virtual address range is relative to the address space of the thread td. It starts at buf and is len bytes long. It is the caller's responsibility to ensure that the pages backing the user buffer are wired for the lifetime of sg.
  • sglist_append_vmpages — appends the physical address ranges of a buffer backed by an array of virtual memory pages m. The buffer starts at an offset of pgoff bytes relative to the first page and is len bytes long.
  • sglist_consume_uio — a variation of sglist_append_uio. Like sglist_append_uio, it appends the physical address ranges described by uio to the scatter/gather list sg. Unlike sglist_append_uio, though, sglist_consume_uio modifies the I/O request to indicate that the appended address ranges have been processed, similar to calling uiomove(9). This routine will only append ranges that describe up to resid total bytes in length. If the available segments in the scatter/gather list are exhausted before resid bytes are processed, then the uio structure will be updated to reflect the actual number of bytes processed, and sglist_consume_io will return zero to indicate success. In effect, this function will perform partial reads or writes. The caller can compare the uio_resid member of uio before and after calling sglist_consume_uio to determine the actual number of bytes processed. 🔥

🎀 Manipulating Scatter/Gather Lists 🎀

  • sglist_join — appends physical address ranges from the scatter/gather list second onto first and then resets second to an empty list. It returns zero on success or an error on failure.
  • sglist_split — splits an existing scatter/gather list into two lists. The first length bytes described by the list original are moved to a new list *head. If original describes a total address range that is smaller than length bytes, then all of the address ranges will be moved to the new list at *head and original will be an empty list.

The caller may supply an existing scatter/gather list in *head. If so, the list must be empty. Otherwise, the caller may set *head to NULL, in which case a new scatter/gather list will be allocated. In that case, mflags may be set to either M_NOWAIT or M_WAITOK.

Note that since the original list is modified by this call, it must be a private list with no other references. The sglist_split function returns zero on success or an error on failure.

  • sglist_slice — generates a new scatter/gather list from a sub-range of an existing scatter/gather list original. The sub-range to extract is specified by the offset and length parameters. The new scatter/gather list is stored in *slice.

As with head for sglist_join, the caller may either provide an empty scatter/gather list, or it may set *slice to NULL, in which case sglist_slice will allocate a new list subject to mflags.

Unlike sglist_split, sglist_slice does not modify original and does not require it to be a private list. The sglist_split function returns zero on success or an error on failure. 🦋

🌸 Miscellaneous Routines 🌸

  • sglist_reset — clears the scatter/gather list sg so that it no longer maps any address ranges. This can allow reuse of a single scatter/gather list object for multiple requests.
  • sglist_length — returns the total length of the physical address ranges described by the scatter/gather list sg.

⭐ RETURN VALUES ⭐

  • The sglist_alloc, sglist_build, and sglist_clone functions return a new scatter/gather list on success or NULL on failure.
  • The sglist_append family of functions and the sglist_consume_uio, sglist_join, sglist_slice, and sglist_split functions return zero on success or an error on failure.
  • The sglist_count family of functions return a count of scatter/gather list elements.
  • The sglist_length function returns a count of address space described by a scatter/gather list in bytes.

😭 ERRORS 😭

ok so when things go sideways, these are the errno values that come back at you. bestie, memorize them, they will show up.

🫶 the sglist_append girlies

The sglist_append functions return the following errors on failure:

  • [EINVAL] — the scatter/gather list straight up has zero segments. empty. nothing. nada.
  • [EFBIG] — there aren't enough available segments left in the scatter/gather list to append all the physical address ranges you asked for. ran out of room, tragic.

🌸 sglist_consume_uio

The sglist_consume_uio function returns the following error on failure:

  • [EINVAL] — again, the scatter/gather list has zero segments. she's empty, she can't consume anything.

💜 sglist_join

The sglist_join function returns the following error on failure:

  • [EFBIG] — there are not enough available segments in the scatter/gather list first to append the physical address ranges from second. like trying to merge two friend groups into a venue that's already at capacity 😭

🎀 sglist_slice

The sglist_slice function returns the following errors on failure:

  • [EINVAL] — the original scatter/gather list does not describe enough address space to cover the requested sub-range. you asked for a slice that doesn't exist, bestie.
  • [EINVAL] — the caller-supplied scatter/gather list in *slice is not empty. it has to be empty before you hand it over, that's the rule.
  • [ENOMEM] — an attempt to allocate a new scatter/gather list with M_NOWAIT set in mflags failed. the malloc said no 💀
  • [EFBIG] — there are not enough available segments in the caller-supplied scatter/gather list in *slice to describe the requested physical address ranges.

⭐ sglist_split

The sglist_split function returns the following errors on failure:

  • [EDOOFUS] — the original scatter/gather list has more than one reference. yes, that's really the name, and yes it's iconic — it literally means "you did something dumb" 🙈
  • [EINVAL] — the caller-supplied scatter/gather list in *head is not empty. same vibe as above: empty it first.
  • [ENOMEM] — an attempt to allocate a new scatter/gather list with M_NOWAIT set in mflags failed. again, malloc said no.
  • [EFBIG] — there are not enough available segments in the caller-supplied scatter/gather list in *head to describe the requested physical address ranges.

👀 SEE ALSO 👀

go read these next, they're the whole friend group:

🦋 HISTORY 🦋

This API was first introduced in FreeBSD 8.0. she's been around a minute, lowkey a legend.

and that's the whole page, bestie! 💖 this rendition came to you via Debian, dated May 25, 2021 — so like, keep that in mind when you're citing it. now go forth and manage your scatter/gather lists responsibly ✨🎀

📦 where this page comes from