ndctl-create-namespace man page

ndctl-create-namespace ā€” provision or reconfigure a namespace


ndctl create-namespace [<options>]


A REGION, after resolving DPA aliasing and LABEL specified boundaries, surfaces one or more "namespace" devices. The arrival of a "namespace" device currently triggers either the nd_blk or nd_pmem driver to load and register a disk/block device.


Create a maximally sized pmem namespace in memory mode

ndctl create-namespace

Convert namespace0.0 to sector mode

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


-t, --type=

Create a pmem or blk namespace (subject to available capacity). A pmem namespace supports the DAX (direct access) capability to mmap(2) persistent memory directly into a process address space. A blk namespace access persistent memory through a block-window-aperture. Compared to pmem it supports a traditional storage error model (EIO on error rather than a cpu exception on a bad memory access), but it does not support DAX.

-m, --mode=
  • "raw": expose the namespace capacity directly with some limitations. Neither a raw pmem namepace nor raw blk namespace support sector atomicity by default (see "sector" mode below). A raw pmem namespace may have limited support for passing a DAX mapping to other syscalls. I.e. direct-I/O to/from a DAX buffer may fail for a pmem namespace in raw mode.
  • "sector" or "safe": persistent memory, given that it is byte addressable, does not support sector atomicity. The problematic aspect of sector tearing is that most applications do not know they have a 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. Persistent memory devices will always tear and always silently. Until an application is audited to be robust in the presence of sector-tearing "safe" mode is recommended. This imposes some performance overhead and disables the DAX capability.
  • "memory": A pmem namespace in this mode supports direct I/O to/from DAX mappings. Depending on the kernel this mode may come at the cost of allocating per-pmem-page metadata. If that allocation is required the capacity can be allocated from "System RAM" or from a reserved portion of pmem (see the --map= option).
  • "dax": Device DAX is the device-centric analogue of Filesystem DAX (CONFIG_FS_DAX). It allows memory ranges to be allocated and mapped without need of an intervening file system. Device DAX is strict, precise and predictable. Specifically this interface:

    • Guarantees fault granularity with respect to a given page size (pte, pmd, or pud) set at configuration time.
    • Enforces deterministic behavior by being strict about what fault scenarios are supported.
-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 namepsaces the size must be a multiple of the
interleave-width and the namespace alignment (see
-a, --align

Applications that want to establish DAX memory mappings with page table entries greater than 4K in size need a persistent memory namespace that is sufficiently aligned. For "memory" and "dax" mode this defaults to 2M. Note that "dax" mode enforces all mappings to be aligned to this value, i.e. fails unaligned mapping attempts.

-e, --reconfig=

Reconfigure an existing namespace (change the mode, sector size, etc...). All namespace parameters, save uuid, default to the current attributes of the specified namespace. The namespace is then re-created with the specified modifications. The uuid is refreshed to a new value by default whenever the data layout of a namespace is changed, see --uuid= to set a specific uuid.

-u, --uuid=

This option is not recommended as a new uuid should be generated every time a namespace is (re-)created. For recovery scenarios however the uuid may be specified.

-n, --name=

For NVDIMM devices that support namespace labels, specify a human friendly name for a namespace. This name is available as device attribute for use in udev rules or elsewhere.

-l, --sector-size

Specify the logical sector size (LBA size) of the block storage device associated with a namespace.

-M, --map=

A pmem namespace in "memory" mode may require allocation of per-page metadata. The allocation can be drawn from either:

  • "mem": typical system memory
  • "dev": persistent memory reserved from the namespace
-f, --force

Unless this option is specified a reconfigure namespace operation will fail if the namespace is presently active. Specifying --force causes the namespace to be disabled before reconfiguring.

-v, --verbose

Emit debug messages for the namespace creation process

-r, --region=

A regionX device name, or a region id number. The keyword all can be specified to carry out the operation on every region in the system, optionally filtered by bus id (see --bus= option).

-b, --bus=

Enforce that the operation only be carried on devices that are attached to the given bus. Where bus can be a provider name or a bus id number.

See Also

ndctl-zero-labels(1), ndctl-disable-namespace(1), ndctl-enable-namespace(1), NVDIMM Namespace Specification[1]



NVDIMM Namespace Specification

Referenced By

daxctl(1), libpmemblk(3), libpmemlog(3), libpmemobj(3), libvmem(3), ndctl(1), ndctl-destroy-namespace(1), ndctl-list(1).

08/04/2017 ndctl 57.1 ndctl Manual