Struct Subsystem 

pub struct Subsystem<'r> { /* private fields */ }

An NVMe subsystem.

A subsystem groups one or more controllers that share a common identity (NQN, serial, model). For typical single-controller PCIe SSDs the subsystem has exactly one controller; Fabrics and multipath setups can have several.

Implementations

impl<'r> Subsystem<'r>

pub fn name(&self) -> Result<&'r str>

The kernel-assigned subsystem name, e.g. nvme-subsys0.

pub fn nqn(&self) -> Result<&'r str>

The subsystem NVMe Qualified Name (NQN).

pub fn subsystem_type(&self) -> Result<&'r str>

The subsystem type (e.g. nvm, discovery).

pub fn serial(&self) -> Result<&'r str>

The subsystem-level serial number, when reported.

Only present when built against a libnvme that exposes nvme_subsystem_get_serial. Older releases (notably the libnvme 1.8 shipped in Ubuntu 24.04) do not have this symbol; on those builds the method is compiled out.

pub fn model(&self) -> Result<&'r str>

The subsystem-level model string, when reported.

Only present when built against a libnvme that exposes nvme_subsystem_get_model.

pub fn firmware(&self) -> Result<&'r str>

The subsystem-level firmware revision, when reported.

Only present when built against a libnvme that exposes nvme_subsystem_get_fw_rev.

pub fn iopolicy(&self) -> Result<&'r str>

ANA / multipath I/O policy for this subsystem, e.g. numa, round-robin.

Only present when built against a libnvme that exposes nvme_subsystem_get_iopolicy.

pub fn application(&self) -> Result<&'r str>

Application-set tag for this subsystem (used by tools like nvme-cli for grouping). Empty when unset.

Only present when built against a libnvme that exposes nvme_subsystem_get_application.

pub fn controllers(&self) -> Controllers<'r>

Iterate over the controllers in this subsystem.

Examples found in repository

examples/fw_info.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    let mut any = false;
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                any = true;
                print_fw(&ctrl)?;
            }
        }
    }
    if !any {
        println!("(no NVMe controllers found)");
    }
    Ok(())
}

examples/smart_log.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    let mut any = false;
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                any = true;
                print_smart(&ctrl)?;
            }
        }
    }
    if !any {
        println!("(no NVMe controllers found)");
    }
    Ok(())
}

examples/id_ctrl.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    let mut any = false;
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                any = true;
                print_controller(&ctrl)?;
            }
        }
    }
    if !any {
        println!("(no NVMe controllers found)");
    }
    Ok(())
}

examples/list_nvme.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;

    let mut rows: Vec<Row> = Vec::new();
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                let mut had_namespace = false;
                for ns in ctrl.namespaces() {
                    rows.push(Row::from(&ctrl, Some(&ns)));
                    had_namespace = true;
                }
                if !had_namespace {
                    rows.push(Row::from(&ctrl, None));
                }
            }
        }
    }

    if rows.is_empty() {
        println!("(no NVMe devices found)");
        return Ok(());
    }

    print_table(&rows);
    Ok(())
}

examples/format_smoke.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    let mut formatted = 0;
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                let model = ctrl.model().unwrap_or("?").trim();
                if model != QEMU_MODEL {
                    println!(
                        "skipping {}: model {model:?} != {QEMU_MODEL:?} (refusing to format real hardware)",
                        ctrl.name()?
                    );
                    continue;
                }
                for ns in ctrl.namespaces() {
                    let nsid = ns.nsid();
                    let lba_size_before = ns.lba_size();
                    let lba_count_before = ns.lba_count();
                    println!(
                        "about to format {}: NSID={nsid}, {lba_count_before} blocks × {lba_size_before} B",
                        ns.name()?
                    );
                    ns.format()
                        .lba_format(0)
                        .secure_erase(SecureErase::None)
                        .execute()?;
                    println!("  -> format succeeded");
                    formatted += 1;
                }
            }
        }
    }
    if formatted == 0 {
        println!("(no QEMU virtual NVMe controllers found)");
    } else {
        println!("formatted {formatted} namespace(s)");
    }
    Ok(())
}

examples/io_smoke.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    let mut exercised = 0;

    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                let model = ctrl.model().unwrap_or("?").trim();
                if model != QEMU_MODEL {
                    println!(
                        "skipping {}: model {model:?} != {QEMU_MODEL:?} (refusing on real hardware)",
                        ctrl.name()?
                    );
                    continue;
                }

                for ns in ctrl.namespaces() {
                    let lba_size = ns.lba_size();
                    println!(
                        "exercising {} (NSID {}, {} B LBAs)",
                        ns.name()?,
                        ns.nsid(),
                        lba_size
                    );

                    // ---- Write one LBA with a recognizable pattern -----
                    let mut pattern = vec![0u8; lba_size as usize];
                    for (i, b) in pattern.iter_mut().enumerate() {
                        *b = (i & 0xFF) as u8;
                    }
                    ns.write(0, 1, &pattern).fua().execute()?;
                    println!("  write ok");

                    // ---- Read it back ---------------------------------
                    let got = ns.read_to_vec(0, 1)?;
                    assert_eq!(got, pattern, "read did not return the bytes we wrote");
                    println!("  read ok (round-trip matches)");

                    // ---- Compare (should succeed) ---------------------
                    ns.compare(0, 1, &pattern).execute()?;
                    println!("  compare ok");

                    // ---- Verify (controller-side integrity check) -----
                    ns.verify(0, 1).execute()?;
                    println!("  verify ok");

                    // ---- Write zeroes over the LBA --------------------
                    ns.write_zeroes(0, 1).execute()?;
                    let zeroed = ns.read_to_vec(0, 1)?;
                    assert!(zeroed.iter().all(|&b| b == 0), "expected all-zero LBA");
                    println!("  write_zeroes ok");

                    // ---- DSM deallocate (TRIM) ------------------------
                    ns.dsm(DsmAttr::DEALLOCATE)
                        .ranges(&[DsmRange::new(0, 1)])
                        .execute()?;
                    println!("  dsm(deallocate) ok");

                    // ---- Flush ----------------------------------------
                    ns.flush()?;
                    println!("  flush ok");

                    exercised += 1;
                }
            }
        }
    }

    if exercised == 0 {
        println!("(no QEMU virtual NVMe controllers found)");
    } else {
        println!("\nall I/O commands exercised on {exercised} namespace(s)");
    }
    Ok(())
}

Trait Implementations

impl Debug for Subsystem<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.