NDCTL-CREATE-NAMESPACE(1)

📦
version 85 · 16 versions
, in fedora 43, fedora 44

✨ NAME ✨

ndctl-create-namespace — provision or reconfigure a namespace. Bestie, this is the ndctl-create-namespace(1) manual page and we are going to make it make sense, fr fr.

🎀 SYNOPSIS 🎀

ndctl create-namespace [<options>]

🌈 THEORY OF OPERATION 🌈

Okay so boom: the capacity of an NVDIMM REGION (which is literally just a contiguous span of persistent memory) gets accessed through one or more NAMESPACE devices. And REGION? That's the Linux term for what ACPI and UEFI call a DIMM-interleave-set, or a system-physical-address-range that is striped (by the memory controller) across one or more memory modules. The way that works is very main character energy, ngl.

The UEFI specification defines the NVDIMM Label Protocol as the combination of label area access methods and a data format for provisioning one or more NAMESPACE objects from a REGION. Lowkey important: label support is optional, and if Linux does not detect the label capability it will automatically instantiate a "label-less" namespace per region. Examples of label-less namespaces are the ones created by the kernel's memmap=ss!nn command line option (see the nvdimm wiki on kernel.org), or NVDIMMs without a valid namespace index in their label area.

Note 📌 Label-less namespaces lack many of the features of their label-rich cousins. For example, their size cannot be modified, or they cannot be fully destroyed (i.e. the space reclaimed). A destroy operation will zero any mode-specific metadata. Finally, for create-namespace operations on label-less namespaces, ndctl bypasses the region capacity availability checks, and always satisfies the request using the full region capacity. The only reconfiguration operation supported on a label-less namespace is changing its mode. So don't expect the full label-rich experience, bestie.

A namespace can be provisioned to operate in one of 4 modes, fsdax, devdax, sector, and raw. Here are the expected usage models for these modes, and yes we're going through all of them:

  • fsdax — Filesystem-DAX mode is the default mode of a namespace when specifying ndctl create-namespace with no options. It creates a block device (/dev/pmemX[.Y]) that supports the DAX capabilities of Linux filesystems (xfs and ext4 to date). DAX removes the page cache from the I/O path and allows mmap(2) to establish direct mappings to persistent memory media. The DAX capability enables workloads / working-sets that would exceed the capacity of the page cache to scale up to the capacity of persistent memory. Workloads that fit in page cache or perform bulk data transfers may not see benefit from DAX. When in doubt, pick this mode. Periodt, this is the default for a reason.
  • devdax — Device-DAX mode enables similar mmap(2) DAX mapping capabilities as Filesystem-DAX. However, instead of a block-device that can support a DAX-enabled filesystem, this mode emits a single character device file (/dev/daxX.Y). Use this mode to assign persistent memory to a virtual-machine, register persistent memory for RDMA, or when gigantic mappings are needed. It's giving direct device energy.
  • sector — Use this mode to host legacy filesystems that do not checksum metadata or applications that are not prepared for torn sectors after a crash. Expected usage for this mode is for small boot volumes. This mode is compatible with other operating systems. Old-school but valid.
  • raw — Raw mode is effectively just a memory disk that does not support DAX. Typically this indicates a namespace that was created by tooling or another operating system that did not know how to create a Linux fsdax or devdax mode namespace. This mode is compatible with other operating systems, but again, does not support DAX operation. No DAX, no cap.

💅 EXAMPLES 💅

Create a maximally sized pmem namespace in fsdax mode (the default):

ndctl create-namespace

Convert namespace0.0 to sector mode:

ndctl create-namespace -f -e namespace0.0 --mode=sector

✨ OPTIONS ✨

  • -m, --mode= — bestie this is THE big one, it picks what kind of namespace you're making. Here are your choices:
    • "raw" — exposes the namespace capacity directly, but with limitations, okay? A raw pmem namespace does not support sector atomicity (go peek at "sector" mode below 👀). It may also have limited-to-no dax support depending on the kernel. Translation: operations like direct-I/O targeting a dax buffer may fail for a pmem namespace in raw mode, or go indirect through a page-cache buffer. Want dax? Go look at "fsdax" and "devdax" mode instead 💅
    • "sector" — so persistent memory, given that it's byte addressable, does not support sector atomicity. The messy part of sector tearing is that most applications don't even know they have an atomic sector update dependency 😭 At least a disk rarely ever tears sectors, and if it does it almost certainly returns a checksum error on access. But persistent memory devices will always tear, and always silently. So until an application is audited to be robust in the presence of sector-tearing, "safe" mode is recommended. The trade-off: it imposes some performance overhead and disables the dax capability. (also known as "safe" or "btt" mode 🫶)
    • "fsdax" — a pmem namespace in this mode supports dax operation with a block-device based filesystem (in previous ndctl releases this mode was named "memory" mode, throwback ✨). The catch? It costs you per-page metadata allocation. That capacity can be allocated from "System RAM", or from a reserved portion of "Persistent Memory" (see the --map= option). NOTE: a filesystem that supports DAX is required for dax operation — if the raw block device (/dev/pmemX) is used directly without a filesystem, it will use the page cache. See "devdax" mode for raw device access that supports dax 👑
    • "devdax" — the device-dax character device interface is a statically allocated / raw access analogue of filesystem-dax (in previous ndctl releases this mode was named "dax" mode). It lets memory ranges be mapped without needing an intervening filesystem. The device-dax is interface strict, precise and predictable. Specifically the interface:
      • Guarantees fault granularity with respect to a given page size (4K, 2M, or 1G on x86) set at configuration time.
      • Enforces deterministic behavior by being strict about what fault scenarios are supported. I.e. if a device is configured with a 2M alignment, an attempt to fault a 4K aligned offset will result in SIGBUS. 💀

Note: both fsdax and devdax mode require 16MiB physical alignment to be cross-arch compatible. By default ndctl will block attempts to create namespaces in these modes when the physical starting address of the namespace is not 16MiB aligned. The --force option tries to override this constraint if the platform supports a smaller alignment, but this is not recommended.

  • -s, --size= — for NVDIMM devices that support namespace labels, set the namespace size in bytes. Otherwise it defaults to the maximum size specified by platform firmware. This option supports the suffixes "k" or "K" for KiB, "m" or "M" for MiB, "g" or "G" for GiB and "t" or "T" for TiB 🎀

For pmem namespaces the size must be a multiple of the interleave-width and the namespace alignment (see below). No cap, math is math.

  • -a, --align — applications that want to establish dax memory mappings with page table entries greater than system base page size (4K on x86) need a persistent memory namespace that is sufficiently aligned. For "fsdax" and "devdax" mode this defaults to 2M. Note that "devdax" mode enforces all mappings to be aligned to this value — i.e. it fails unaligned mapping attempts 🚫 The "fsdax" alignment setting determines the starting alignment of filesystem extents and may limit the possible granularities; if a large mapping is not possible it will silently fall back to a smaller page size. She's flexible like that 💁
  • -e, --reconfig= — reconfigure an existing namespace. This option is a shortcut for the following sequence:
    • Read all parameters from @victim_namespace
    • Destroy @victim_namespace
    • Create @new_namespace merging old parameters with new ones
Note that the major implication of a destroy-create cycle is that data from @victim_namespace is not preserved in @new_namespace. The attributes transferred from @victim_namespace are the geometry, mode, and name (not uuid without --uuid=). No attempt is made to preserve the data, and any old data that is visible in @new_namespace is by coincidence, not convention. "Backup and restore" is the only reliable method to populate @new_namespace with data from @victim_namespace. 😭 protect your data bestie
  • -u, --uuid= — this option is not recommended, because a new uuid should be generated every time a namespace is (re-)created. For recovery scenarios however, the uuid may be specified. iykyk 🩹
  • -n, --name= — for NVDIMM devices that support namespace labels, specify a human friendly name for a namespace. This name is available as a device attribute for use in udev rules. Cute AND functional 🌸
  • -l, --sector-size — specify the logical sector size (LBA size) of the Linux block device associated with an namespace.
  • -M, --map= — a pmem namespace in "fsdax" or "devdax" mode requires allocation of per-page metadata. The allocation can be drawn from either:
    • "mem": typical system memory
    • "dev": persistent memory reserved from the namespace

Given relative capacities of "Persistent Memory" to "System RAM" the allocation defaults to reserving space out of the namespace directly (--map=dev). The overhead is 64-bytes per 4K (16GB per 1TB) on x86. do with that what you will 💸

  • -c, --continue — do not stop after creating one namespace. Instead, greedily create as many namespaces as possible within the given --bus and --region filter restrictions. This will abort if any creation attempt results in an error, unless --force is also supplied. she's greedy, we love her 🔥
  • -f, --force — unless this option is specified, the reconfigure namespace operation will fail if the namespace is presently active. Specifying --force causes the namespace to be disabled before the operation is attempted. However, if the namespace is mounted then the disable namespace and reconfigure namespace operations will be aborted — the namespace must be unmounted before being reconfigured. When used in conjunction with --continue, continue the namespace creation loop even if an error is encountered for intermediate namespaces. ⚠️ unmount first fr fr
  • -L, --autolabel, --no-autolabel — legacy NVDIMM devices do not support namespace labels. In that case the kernel creates region-sized namespaces that can not be deleted. Their mode can be changed, but they can not be resized smaller than their parent region. This is termed a "label-less namespace". In contrast, NVDIMMs and hypervisors that support the ACPI 6.2 label area definition (ACPI 6.2 Section 6.5.10 NVDIMM Label Methods) support "labelled namespace" operation. ✨
    • There are two cases where the kernel will default to label-less operation:
      • NVDIMM does not support labels
      • The NVDIMM supports labels, but the Label Index Block (see UEFI 2.7) is not present.
    • In the latter case the configuration can be upgraded to labelled operation by writing an index block on all DIMMs in a region and re-enabling that region. The autolabel capability of ndctl create-namespace --reconfig tries to do this by default if it can determine that all DIMM capacity is referenced by the namespace being reconfigured. It will otherwise fail to autolabel and remain in label-less mode if it finds a DIMM contributes capacity to more than one region. This check prevents inadvertent data loss of that other region if it is in active use. The --autolabel option is implied by default, and the --no-autolabel option can be used to disable this behavior. When automatic labeling fails and labelled operation is still desired, the safety policy can be bypassed by the following commands — note that all data on all regions is forfeited by running these commands:
ndctl disable-region all
ndctl init-labels all
ndctl enable-region all
🚨 all data on all regions is forfeited. like gone gone. read twice, run once.
  • -R, --autorecover, --no-autorecover — by default, if a namespace creation attempt fails, ndctl will cleanup the partially initialized namespace. Use --no-autorecover to disable this behavior for debug and development scenarios where it's useful to have the label and info-block state preserved after a failure. 🧪
  • -v, --verbose — emit debug messages for the namespace creation process. she's telling you everything 👀
  • -r, --region= — a regionX device name, or a region id number. Restrict the operation to the specified region(s). The keyword all can be specified to indicate the lack of any restriction, however this is the same as not supplying a --region option at all.
  • -b, --bus= — a bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict the operation to the specified bus(es). The keyword all can be specified to indicate the lack of any restriction, however this is the same as not supplying a --bus option at all.

Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL version 2 http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

🌈 SEE ALSO 🌈

ndctl-zero-labels(1), ndctl-init-labels(1), ndctl-disable-namespace(1), ndctl-enable-namespace(1), UEFI NVDIMM Label Protocol <http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf> Linux Persistent Memory Wiki <https://nvdimm.wiki.kernel.org>

and that's the whole thing bestie, you ate 💅 this was ndctl version 2026-07-07 of NDCTL-CREATE-NAMESPACE(1) — go forth and namespace responsibly 🦋💖

📦 where this page comes from