Quick Start

The ndctl , daxctl, and cxl commands are designed to be user friendly. Once installed, a list of commands can be shown using any of the following:

1) With no arguments or options, ndctl ,daxctl , and cxl show a simple usage message:

$ ndctl 

 usage: ndctl [--version] [--help] COMMAND [ARGS]


 See 'ndctl help COMMAND' for more information on a specific command.
 ndctl --list-cmds to see all available commands

$ daxctl 

 usage: daxctl [--version] [--help] COMMAND [ARGS]


 See 'daxctl help COMMAND' for more information on a specific command.
 daxctl --list-cmds to see all available commands

$ cxl 

 usage: cxl [--version] [--help] COMMAND [ARGS]


 See 'cxl help COMMAND' for more information on a specific command.
 cxl --list-cmds to see all available commands

2) Using ndctl help ,daxctl help , and cxl help displays basic help and syntax information for the sub-command. Below is an example of using the ndctl help command to launch the create-namespace man page:

$ ndctl help create-namespace

3) Using ndctl --list-cmds daxctl --list-cmds, and cxl --list-cmds lists all commands as a single list.

$ ndctl --list-cmds
version
enable-namespace
disable-namespace
create-namespace
destroy-namespace
read-infoblock
write-infoblock
check-namespace
clear-errors
enable-region
disable-region
enable-dimm
disable-dimm
zero-labels
read-labels
write-labels
init-labels
check-labels
inject-error
update-firmware
inject-smart
wait-scrub
activate-firmware
start-scrub
setup-passphrase
update-passphrase
remove-passphrase
freeze-security
sanitize-dimm
load-keys
wait-overwrite
list
monitor
help

$ daxctl --list-cmds
version
list
help
split-acpi
migrate-device-model
create-device
destroy-device
reconfigure-device
online-memory
offline-memory
disable-device
enable-device

$ cxl --list-cmds
version
list
help
zero-labels
read-labels
write-labels

An alternative method for listing commands uses the TAB key completion feature. By typingndctl <TAB> <TAB> ,daxctl <TAB> <TAB> , or cxl <TAB> <TAB> we can list the available commands, eg:

$ ndctl <TAB> <TAB>
activate-firmware   freeze-security     setup-passphrase
check-labels        help                start-scrub
check-namespace     init-labels         update-firmware
clear-errors        inject-error        update-passphrase
create-namespace    inject-smart        version
destroy-namespace   list                wait-overwrite
disable-dimm        load-keys           wait-scrub
disable-namespace   monitor             write-infoblock
disable-region      read-infoblock      write-labels
enable-dimm         read-labels         zero-labels
enable-namespace    remove-passphrase
enable-region       sanitize-dimm

$ daxctl <TAB> <TAB>
help                   version
list                   split-acpi
migrate-device-model   create-device
destroy-device         reconfigure-device
online-memory          offline-memory
disable-device         enable-device

$ cxl <TAB> <TAB>
help                   version
list                   zero-labels
read-labels            write-labels

TAB Command and Argument Completion

ndctl and daxctlsupports command completion using the TAB key. For example, typing ndctl enable-<TAB> lists all commands beginning with 'enable', eg:

# ndctl enable-<TAB>
enable-dimm        enable-namespace   enable-region

TAB completion also works with command arguments. For example, typing ndctl enable-dimm <TAB> will show all available command arguments. For example, the 'enable-dimm' command can enable one, more than one, or all NVDIMMs. It will list all available NVDIMMs (nmem) devices when using the TAB completion, eg:

# ndctl enable-dimm <TAB>
all      nmem10   nmem3    nmem6    nmem9
nmem0    nmem11   nmem4    nmem7
nmem1    nmem2    nmem5    nmem8

Getting Help

NDCTL ships with a man page for each command. Each man page describes the required arguments and features in detail. Man pages can be found and accessed using the man or ndctl utilities. The following man -k ndctl searches for any man page containing the "ndctl" keyword:

$ man -k ndctl 
ndctl (1)            - Manage "libnvdimm" subsystem devices (Non-volatile Memory)
ndctl-activate-firmware (1) - activate staged firmware on memory devices
ndctl-check-labels (1) - determine if the given dimms have a valid namespace index block
ndctl-check-namespace (1) - check namespace metadata consistency
ndctl-clear-errors (1) - clear all errors (badblocks) on the given namespace
ndctl-create-namespace (1) - provision or reconfigure a namespace
ndctl-destroy-namespace (1) - destroy the given namespace(s)
ndctl-disable-dimm (1) - disable one or more idle dimms
ndctl-disable-namespace (1) - disable the given namespace(s)
ndctl-disable-region (1) - disable the given region(s) and all descendant namespaces
ndctl-enable-dimm (1) - enable one more dimms
ndctl-enable-namespace (1) - enable the given namespace(s)
ndctl-enable-region (1) - enable the given region(s) and all descendant namespaces
ndctl-freeze-security (1) - Set the given DIMM(s) to reject future security operations
ndctl-init-labels (1) - initialize the label data area on a dimm or set of dimms
ndctl-inject-error (1) - inject media errors at a namespace offset
ndctl-inject-smart (1) - perform smart threshold/injection operations on a DIMM
ndctl-list (1)       - dump the platform nvdimm device topology and attributes in json
ndctl-load-keys (1)  - load the kek and encrypted passphrases into the keyring
ndctl-monitor (1)    - Monitor the smart events of nvdimm objects
ndctl-read-infoblock (1) - read and optionally parse the info-block a namespace
ndctl-read-labels (1) - read out the label area on a dimm or set of dimms
ndctl-remove-passphrase (1) - Stop a DIMM from locking at power-loss and requiring a passphrase to access media
ndctl-sanitize-dimm (1) - Perform a cryptographic destruction or overwrite of the contents of the given NVDIMM(s)
ndctl-setup-passphrase (1) - setup and enable the security passphrase for an NVDIMM
ndctl-start-scrub (1) - start an Address Range Scrub (ARS) operation
ndctl-update-firmware (1) - update the firmware the given device
ndctl-update-passphrase (1) - update the security passphrase for an NVDIMM
ndctl-wait-overwrite (1) - wait for an overwrite operation to complete
ndctl-wait-scrub (1) - wait for an Address Range Scrub (ARS) operation to complete
ndctl-write-infoblock (1) - generate and write an infoblock
ndctl-write-labels (1) - write data to the label area on a dimm
ndctl-zero-labels (1) - zero out the label area on a dimm or set of dimms

$ man -k daxctl 
daxctl (1)           - Provides enumeration and provisioning commands for the Linux kernel Device-DAX facility
daxctl-create-device (1) - Create a devdax device
daxctl-destroy-device (1) - Destroy a devdax device
daxctl-disable-device (1) - Disables a devdax device
daxctl-enable-device (1) - Enable a devdax device
daxctl-list (1)      - dump the platform Device-DAX regions, devices, and attributes in json.
daxctl-migrate-device-model (1) - Opt-in to the /sys/bus/dax device-model, allow for alternative Device-DAX instance drivers.
daxctl-offline-memory (1) - Offline the memory for a device that is in system-ram mode
daxctl-online-memory (1) - Online the memory for a device that is in system-ram mode
daxctl-reconfigure-device (1) - Reconfigure a dax device into a different mode

$ man -k cxl 
cxl (1)              - Provides enumeration and provisioning commands for CXL platforms
cxl-list (1)         - List CXL capable memory devices, and their attributes in json.
cxl-read-labels (1)  - read out the label area on a CXL memdev
cxl-write-labels (1) - write data to the label area on a memdev
cxl-zero-labels (1)  - zero out the label area on a set of memdevs
cxl_new (3)          - Create a new library context object that acts as a handle for all library operations
libcxl (3)           - A library to interact with CXL devices through sysfs(5) and ioctl(2) interfaces

Note: If man -k ndctl returns "ndctl: nothing appropriate." or similar, see the Troubleshooting section to manually build the indexes.

Additionally, executing ndctl help <command> can be used to display the man page for the command, eg:

$ ndctl help enable-dimm

A list of man pages is available online. See NDCTL Man Pages, DAXCTL Man Pages, and CXL Man Pages for a complete list.

Displaying Bus, NVDIMM, Region, and Namespace Information

The ndctl list command is a very powerful and feature rich command. A list of options is shown below:

$ ndctl list -?
  Error: unknown switch `?'

 usage: ndctl list [<options>]

    -b, --bus <bus-id>    filter by bus
    -r, --region <region-id>
                          filter by region
    -d, --dimm <dimm-id>  filter by dimm
    -n, --namespace <namespace-id>
                          filter by namespace id
    -m, --mode <namespace-mode>
                          filter by namespace mode
    -t, --type <region-type>
                          filter by region-type
    -U, --numa-node <numa node>
                          filter by numa node
    -B, --buses           include bus info
    -D, --dimms           include dimm info
    -F, --firmware        include firmware info
    -H, --health          include dimm health
    -R, --regions         include region info
    -N, --namespaces      include namespace info (default)
    -X, --device-dax      include device-dax info
    -C, --capabilities    include region capability info
    -i, --idle            include idle devices
    -c, --configured      include configured namespaces, disabled or not
    -M, --media-errors    include media errors
    -u, --human           use human friendly number formats 
    -v, --verbose         increase output detail

Using the filters is a powerful way to limit the output.

Examples

To list all active/enabled namespaces:

# ndctl list -N

To list all active/enabled regions:

# ndctl list -R

To list all active/enabled NVDIMMs:

# ndctl list -D

To list all active/enabled NVDIMMs, Regions, and Namespaces:

# ndctl list -DRN

To list all active/enabled and disabled/inactive (idle) NVDIMMs, Regions, and Namespaces:

# ndctl list -DRNi

To list all active/enabled and disabled/inactive (idle) NVDIMMs, Regions, and Namespaces with human readable values:

# ndctl list -iNuRD

Increasing output verbosity

The -v, --verbose option increases the output verbosity of the command. Using -vv or --vvv further increases the output and verbosity.