Struct FaultConfiguration

pub struct FaultConfiguration {
    pub fault_active: Cell<bool>,
    pub admin_fault: AdminQueueFaultConfig,
    pub pci_fault: PciFaultConfig,
    pub namespace_fault: NamespaceFaultConfig,
    pub io_fault: Arc<IoQueueFaultConfig>,
}

Fault configuration for the NVMe fault controller.

This struct defines behaviors that inject faults into the NVMe fault controller logic, such as delaying or dropping commands, triggering namespace change notifications, or customizing completion payloads. Fault injection is controlled by the fault_active flag, unless specified otherwise in the fault description. fault_active is managed by the test via [mesh::CellUpdater]. An exception to the fault_active check is the NamespaceFaultConfig which is processed regardless of fault_active state. (See nvme_test crate for details on how the faults are applied.)

Example

Panic when a command that matches CREATE_IO_COMPLETION_QUEUE is seen in the admin queue:

use mesh::CellUpdater;
use nvme_resources::fault::FaultConfiguration;
use nvme_resources::fault::AdminQueueFaultConfig;
use nvme_resources::fault::CommandMatch;
use nvme_spec::Command;
use nvme_resources::fault::AdminQueueFaultBehavior;
use nvme_resources::NvmeFaultControllerHandle;
use guid::Guid;
use zerocopy::FromZeros;
use zerocopy::IntoBytes;

pub fn example_fault() {
    let mut fault_start_updater = CellUpdater::new(false);

    // Setup command matches
    let mut command = Command::new_zeroed();
    let mut mask = Command::new_zeroed();

    command.cdw0 = command.cdw0.with_opcode(nvme_spec::AdminOpcode::CREATE_IO_COMPLETION_QUEUE.0);
    mask.cdw0 = mask.cdw0.with_opcode(u8::MAX);

    let fault_configuration = FaultConfiguration::new(fault_start_updater.cell())
        .with_admin_queue_fault(
            AdminQueueFaultConfig::new().with_submission_queue_fault(
                CommandMatch {
                    command: command,
                    mask: mask.as_bytes().try_into().expect("mask should be 64 bytes"),
                },
                AdminQueueFaultBehavior::Panic("Received a CREATE_IO_COMPLETION_QUEUE command".to_string()),
            )
        );
    let fault_controller_handle = NvmeFaultControllerHandle {
        subsystem_id: Guid::new_random(),
        msix_count: 10,
        max_io_queues: 10,
        namespaces: vec![
            // Define NamespaceDefinitions here
        ],
        fault_config: fault_configuration,
    };
    // Pass the controller handle in to the vm config to create and attach the fault controller. At this point the fault is inactive.
    fault_start_updater.set(true); // Activate the fault injection.
    // ... run test ...
    fault_start_updater.set(false); // Deactivate the fault injection.
}

Fields

fault_active: Cell<bool>

Fault active state

admin_fault: AdminQueueFaultConfig

Fault to apply to the admin queues

pci_fault: PciFaultConfig

Fault to apply to management layer of the controller

namespace_fault: NamespaceFaultConfig

Fault for test triggered namespace change notifications

io_fault: Arc<IoQueueFaultConfig>

Fault to apply to all IO queues

Implementations

impl FaultConfiguration

pub fn new(fault_active: Cell<bool>) -> Self

Create a new empty fault configuration

pub fn with_pci_fault(self, pci_fault: PciFaultConfig) -> Self

Add a PCI fault configuration to the fault configuration

pub fn with_admin_queue_fault(self, admin_fault: AdminQueueFaultConfig) -> Self

Add an admin queue fault configuration to the fault configuration

pub fn with_io_queue_fault(self, io_fault: IoQueueFaultConfig) -> Self

Add an IO queue fault configuration to the fault configuration

pub fn with_namespace_fault(self, namespace_fault: NamespaceFaultConfig) -> Self

Add a namespace fault configuration to the fault configuration

Trait Implementations

impl DefaultEncoding for FaultConfiguration

type Encoding = TableEncoder

The encoding to use for the serialization.

impl<'encoding> StructDecodeMetadata<'encoding, Resource> for FaultConfiguration

const DECODERS: &'static [ErasedDecoderEntry]

The list of decoder vtables.

impl StructEncodeMetadata<Resource> for FaultConfiguration

const ENCODERS: &'static [ErasedEncoderEntry]

The list of encoder vtables.

impl StructMetadata for FaultConfiguration

const NUMBERS: &'static [u32]

The field numbers for each field.

const OFFSETS: &'static [usize]

The byte offset to each field within the struct.