ndctl-create-namespace (1) - Linux Manuals

ndctl-create-namespace: provision or reconfigure a namespace

NAME

ndctl-create-namespace - provision or reconfigure a namespace

SYNOPSIS

ndctl create-namespace [<options>]

DESCRIPTION

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.

EXAMPLES

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

OPTIONS

-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. Otherwise it defaults to the maximum size specified by platform firmware.

-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.

NOTES

1.

NVDIMM Namespace Specification

http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf