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 'memory' mode
[verse]
ndctl create-namespace

Convert namespace0.0 to 'sector' mode
[verse]
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 linkndctl: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
	below).

-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=::
include::xable-region-options.txt[]

COPYRIGHT
---------
Copyright (c) 2016 - 2017, 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
--------
linkndctl:ndctl-zero-labels[1],
linkndctl:ndctl-disable-namespace[1],
linkndctl:ndctl-enable-namespace[1],
http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace
Specification]
