Struct SGTable

Source

pub struct SGTable<T: Sealed = Borrowed> { /* private fields */ }

Expand description

A scatter-gather table.

This struct is a wrapper around the kernel’s struct sg_table. It manages a list of DMA-mapped memory segments that can be passed to a device for I/O operations.

The generic parameter T is used as a generic type to distinguish between owned and borrowed tables.

SGTable<Owned>: An owned table created and managed entirely by Rust code. It handles allocation, DMA mapping, and cleanup of all associated resources. See SGTable::new.
[SGTable<Borrowed>} (or simply SGTable): Represents a table whose lifetime is managed externally. It can be used safely via a borrowed reference &'a SGTable, where 'a is the external lifetime.

All SGTable variants can be iterated over the individual SGEntrys.

Implementations§

Source §

impl SGTable

Source

pub unsafe fn from_raw<'a>(ptr: *mut sg_table) -> &'a Self

Creates a borrowed &'a SGTable from a raw struct sg_table pointer.

This allows safe access to an sg_table that is managed elsewhere (for example, in C code).

§Safety

Callers must ensure that:

the struct sg_table pointed to by ptr is valid for the entire lifetime of 'a,
the data behind ptr is not modified concurrently for the duration of 'a.

Source

pub fn iter(&self) -> SGTableIter<'_> ⓘ

Returns an SGTableIter bound to the lifetime of self.

Source §

impl SGTable<Owned>
where for<'a> P: AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

Source

pub fn new( dev: &Device<Bound>, pages: P, dir: DataDirection, flags: Flags, ) -> impl PinInit<Self, Error> + '_

Allocates a new scatter-gather table from the given pages and maps it for DMA.

This constructor creates a new SGTable<Owned> that takes ownership of P. It allocates a struct sg_table, populates it with entries corresponding to the physical pages of P, and maps the table for DMA with the specified Device and dma::DataDirection.

The DMA mapping is managed through Devres, ensuring that the DMA mapping is unmapped once the associated Device is unbound, or when the SGTable<Owned> is dropped.

§Parameters

dev: The Device that will be performing the DMA.
pages: The entity providing the backing pages. It must implement page::AsPageIter. The ownership of this entity is moved into the new SGTable<Owned>.
dir: The dma::DataDirection of the DMA transfer.
flags: Allocation flags for internal allocations (e.g., GFP_KERNEL).

§Examples

use kernel::{
    device::{Bound, Device},
    dma, page,
    prelude::*,
    scatterlist::{SGTable, Owned},
};

fn test(dev: &Device<Bound>) -> Result {
    let size = 4 * page::PAGE_SIZE;
    let pages = VVec::<u8>::with_capacity(size, GFP_KERNEL)?;

    let sgt = KBox::pin_init(SGTable::new(
        dev,
        pages,
        dma::DataDirection::ToDevice,
        GFP_KERNEL,
    ), GFP_KERNEL)?;

    Ok(())
}