// SPDX-License-Identifier: GPL-2.0

ndctl-create-namespace(1)
=========================

NAME
----
ndctl-create-namespace - provision or reconfigure a namespace

SYNOPSIS
--------
[verse]
'ndctl create-namespace' [<options>]

include::namespace-description.txt[]

EXAMPLES
--------

Create a maximally sized pmem namespace in 'fsdax' mode (the
default)
[verse]
ndctl create-namespace

Convert namespace0.0 to 'sector' mode
[verse]
ndctl create-namespace -f -e namespace0.0 --mode=sector

OPTIONS
-------
-m::
--mode=::
	- "raw": expose the namespace capacity directly with
	  limitations. A raw pmem namepace namespace does not support
	  sector atomicity (see "sector" mode below). A raw pmem
	  namespace may have limited to no dax support depending the
	  kernel. In other words operations like direct-I/O targeting a
	  dax buffer may fail for a pmem namespace in raw mode or
	  indirect through a page-cache buffer.  See "fsdax" and
	  "devdax" mode for dax operation.


	- "sector": 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. (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). This mode
	  comes at the cost of allocating per-page metadata. The
	  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 allows memory ranges to be mapped without need of 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 namepsaces the size must be a multiple of the
	interleave-width and the namespace alignment (see
	below).

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

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

-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 a device attribute for use in udev rules.

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

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

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

-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
	  is in active use. The --autolabel option is implied by
	  default, 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

-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 useful to have the label and
	info-block state preserved after a failure.

-v::
--verbose::
	Emit debug messages for the namespace creation process

-r::
--region=::
include::xable-region-options.txt[]

-b::
--bus=::
include::xable-bus-options.txt[]

include::../copyright.txt[]

SEE ALSO
--------
linkndctl:ndctl-zero-labels[1],
linkndctl:ndctl-init-labels[1],
linkndctl:ndctl-disable-namespace[1],
linkndctl:ndctl-enable-namespace[1],
http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol]
https://nvdimm.wiki.kernel.org[Linux Persistent Memory Wiki]
