ndctl

Create an 'fsdax' mode namespace

$ ndctl create-namespace --mode=[fsdax]

$ ndctl create-namespace --reconfigure=[namespaceX.Y] --mode=[raw]

$ ndctl check-namespace --repair [namespaceX.Y]

$ ndctl list --namespaces --regions --buses --idle

$ ndctl list -vvv --namespace=[namespaceX.Y]

$ ndctl monitor --bus=[ACPI.NFIT]

$ ndctl destroy-namespace --force [namespaceX.Y]

ndctl [OPTIONS] COMMAND [ARGS...]

--json
    Output information in JSON format, useful for programmatic parsing.

--human
    Display output in a human-readable format, often with sizes formatted (e.g., 1.5GB).

--unit=<units>
    Specify output units for sizes (e.g., B, kB, MB, GB, TB). Overrides --human if both are used.

--terse
    Suppress verbose output for commands like create, enable, disable, or zero, showing only essential information.

--force
    Force an operation that might otherwise be rejected due to safety checks or warnings.

--debug
    Enable debug messages, providing more detailed output for troubleshooting.

--version
    Display the ndctl utility's version information and exit.

--help
    Show a help message for the command or a specific subcommand.

ndctl is a command-line utility in Linux for managing NVDIMM (Non-Volatile Dual In-line Memory Module) devices and their associated persistent memory regions. It provides a comprehensive set of tools to discover, configure, and monitor NVDIMM hardware. Administrators use ndctl to create, modify, and delete persistent memory namespaces, which are addressable regions of non-volatile memory that applications can directly access. These namespaces can be configured in various modes, such as fsdax (file system DAX) for use with file systems like XFS or EXT4, or devdax (device DAX) for raw block device-like access. ndctl also allows inspecting NVDIMM health, firmware details, and interleave sets, crucial for performance and reliability in persistent memory computing environments.

Incorrect configuration of NVDIMM devices using ndctl can lead to data loss, inaccessible memory, or system instability. Many operations require elevated privileges (root user or sudo). Utilizing persistent memory effectively often requires applications to be specifically designed for direct access (DAX) programming models, which differ from traditional block storage I/O.

ndctl operates using a subcommand-driven interface, where specific actions are performed via distinct commands. Common subcommands include: list (to enumerate detected NVDIMM devices, regions, and namespaces), create-namespace, destroy-namespace (to manage logical persistent memory devices), enable-region, disable-region (to control the active state of physical NVDIMM regions), and zero-namespace (to securely clear data within a specified namespace).

ndctl primarily manages two key persistent memory concepts: regions and namespaces. Regions represent physical NVDIMM memory areas, often spanning multiple physical NVDIMM modules. From these regions, namespaces are carved out as logical persistent memory devices, which can then be exposed to the operating system. Namespaces can be configured in fsdax mode (allowing file systems like XFS or EXT4 to leverage direct access for mmap-ed files) or devdax mode (providing raw device-like access for direct application memory-mapping), influencing how applications interact with the persistent memory.

ndctl is a core component of the libndctl project, a user-space library and tools suite developed to standardize the management of NVDIMM devices and persistent memory within the Linux ecosystem. Its development closely tracks the upstream Linux kernel's persistent memory support, emerging to provide robust, vendor-agnostic configuration and utilization capabilities as non-volatile memory technologies became more prevalent.

daxctl(1), ipmctl(8), lsblk(8), lsmem(1)