Managing Non-Volatile DIMMs with 'ndctl' (with examples)

The ndctl utility is a powerful tool for managing Non-Volatile Dual In-line Memory Modules (NVDIMMs). These are specialized memory modules that retain data during power loss, making them invaluable for applications requiring persistent memory storage. The ndctl command is designed to configure, monitor, and manage these NVDIMMs. With options to create, modify, and check namespaces, as well as list and monitor configurations, ndctl provides comprehensive functionality for administrators and engineers dealing with NVDIMMs and persistent memory solutions.

Create an ‘fsdax’ mode namespace

Code:

ndctl create-namespace --mode=fsdax

Motivation: Creating a namespace in ‘fsdax’ mode is essential for applications that require direct, byte-addressable access to persistent memory. This mode allows the operating system to use the NVDIMM like normal RAM, enabling efficient data operations for in-memory computing tasks.

Explanation:

• create-namespace: This command initializes a new memory namespace, allowing the use of a specified region of NVDIMM as a distinct memory area.
• --mode=fsdax: The ‘fsdax’ mode configures the namespace for filesystem direct access. This allows for efficient input/output operations by letting the file system directly access the memory.

Example output:

{
  "dev":"namespace1.0",
  "mode":"fsdax",
  "size":8589934592,
  "sector_size":512
}

Change the mode of a namespace to ‘raw’

Code:

ndctl create-namespace --reconfigure=namespaceX.Y --mode=raw

Motivation: Changing the mode of a namespace to ‘raw’ might be necessary when there is a need to access the namespace in its original, unformatted state. This is crucial for tasks that involve raw data processing or specific applications that manage memory without interference from system file structures.

Explanation:

• create-namespace: Still used to alter existing configurations of namespaces.
• --reconfigure=namespaceX.Y: This argument targets a specific namespace (namespaceX.Y) for reconfiguration, allowing changes without creating an entirely new namespace.
• --mode=raw: Setting to ‘raw’ mode implies that no file system formatting will be applied, providing access to the underlying storage as unstructured data.

Example output:

{
  "dev":"namespaceX.Y",
  "mode":"raw",
  "size":8589934592,
  "uuid":"123e4567-e89b-12d3-a456-426614174001"
}

Check a sector mode namespace for consistency, and repair if needed

Code:

ndctl check-namespace --repair namespaceX.Y

Motivation: Regular health checks are critical for maintaining data integrity, especially in systems relying on persistent memory. Checking and potentially repairing inconsistencies in a sector mode namespace ensures that the stored data remains reliable and unharmed by potential corruption.

Explanation:

• check-namespace: This command assesses the namespace’s health, particularly looking for any sectors that may be inconsistent.
• --repair: If any inconsistencies or errors are found, this option will attempt to fix them, maintaining the integrity of the stored data.
• namespaceX.Y: The specific identifier of the namespace to be checked and repaired.

Example output:

Checking namespaceX.Y...
Repair successful, no errors found.

List all namespaces, regions, and buses (including disabled ones)

Code:

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

Motivation: Understanding the current configuration and status of all NVDIMMs is crucial for system administrators for effective monitoring and management. This comprehensive listing helps to keep track of active and inactive components, ensuring better resource allocation and maintenance.

Explanation:

• list: Base command to display existing configurations and statuses.
• --namespaces: Includes all configured namespaces in the output.
• --regions: Displays memory regions configured on the system.
• --buses: Lists all memory buses tied to NVDIMMs and their configurations.
• --idle: Ensures that even disabled or inactive components are included in the listing.

Example output:

[
  {
    "dev":"region0",
    "size":34359738368,
    "namespaces":[
      {"dev":"namespace0.0", "mode":"raw"}
    ]
  },
  {
    "dev":"region1",
    "size":34359738368,
    "namespaces":[
      {"dev":"namespace1.0", "mode":"fsdax"}
    ]
  }
]

List a specific namespace and include lots of additional information

Code:

ndctl list -vvv --namespace=namespaceX.Y

Motivation: For detailed troubleshooting, performance analysis, or auditing purposes, it’s important to access in-depth information about a specific namespace. Extended details aid in pinpointing issues or understanding the performance characteristics of the NVDIMM.

Explanation:

• list: Base command for displaying configurations.
• -vvv: This verbosity level ensures that the maximum amount of information about the namespace is outputted, including technical details that are usually not displayed.
• --namespace=namespaceX.Y: The target namespace for which detailed information is required.

Example output:

{
  "dev":"namespaceX.Y",
  "mode":"raw",
  "size":8589934592,
  "align":2097152,
  "blockdev":"pmem0",
  "bd_size":8589934592
  // Additional verbose details...
}

Run a monitor to watch for SMART health events for NVDIMMs on the ‘ACPI.NFIT’ bus

Code:

ndctl monitor --bus=ACPI.NFIT

Motivation: Continuous monitoring of health events is important for preemptive maintenance and data protection. By setting up monitoring, administrators can intervene before potential failures, preserving data integrity and system uptime.

Explanation:

• monitor: Initializes a continuous surveillance session for health events.
• --bus=ACPI.NFIT: Specifies the ACPI.NFIT bus, which is commonly used for communication with NVDIMMs, ensuring that only relevant events are captured.

Example output:

Monitoring ACPI.NFIT...
Health event detected: NVDIMM 0 temperature exceeded threshold.

Remove a namespace (when applicable) or reset it to an initial state

Code:

ndctl destroy-namespace --force namespaceX.Y

Motivation: Removing or resetting namespaces is necessary for reallocating resources or reconfiguring setups when organizational needs change. It’s crucial for maintaining an optimized environment, especially when migrating or decommissioning systems.

Explanation:

• destroy-namespace: Permanently deletes or resets the specified namespace.
• --force: This ensures that the action is executed without prompting for further confirmation, which is useful in automated scripts or when immediate action is required.
• namespaceX.Y: Specifies the namespace that is to be destroyed or reset.

Example output:

Destroying namespaceX.Y...
Namespace successfully destroyed.

Conclusion:

The ndctl command is indispensable for managing and maintaining NVDIMMs, providing comprehensive options for creation, modification, monitoring, and destruction of memory namespaces. Each use case detailed above highlights its versatility and the potential to optimize persistent memory handling, making it an essential tool for system administrators and IT professionals.