1NDCTL-CREATE-NAMESPACE(1) ndctl Manual NDCTL-CREATE-NAMESPACE(1)
2
6 ndctl-create-namespace - provision or reconfigure a namespace
7
9 ndctl create-namespace [<options>]
10
12 The capacity of an NVDIMM REGION (contiguous span of persistent memory)
13 is accessed via one or more NAMESPACE devices. REGION is the Linux term
14 for what ACPI and UEFI call a DIMM-interleave-set, or a
15 system-physical-address-range that is striped (by the memory
16 controller) across one or more memory modules.
17 The UEFI specification defines the NVDIMM Label Protocol as the
19 combination of label area access methods and a data format for
20 provisioning one or more NAMESPACE objects from a REGION. Note that
21 label support is optional and if Linux does not detect the label
22 capability it will automatically instantiate a "label-less" namespace
23 per region. Examples of label-less namespaces are the ones created by
24 the kernel’s memmap=ss!nn command line option (see the nvdimm wiki on
25 kernel.org), or NVDIMMs without a valid namespace index in their label
26 area.
27 Note
29 Label-less namespaces lack many of the features of their label-rich
30 cousins. For example, their size cannot be modified, or they cannot
31 be fully destroyed (i.e. the space reclaimed). A destroy operation
32 will zero any mode-specific metadata. Finally, for create-namespace
33 operations on label-less namespaces, ndctl bypasses the region
34 capacity availability checks, and always satisfies the request
35 using the full region capacity. The only reconfiguration operation
36 supported on a label-less namespace is changing its mode.
37 A namespace can be provisioned to operate in one of 4 modes, fsdax,
39 devdax, sector, and raw. Here are the expected usage models for these
40 modes:
41 · fsdax: Filesystem-DAX mode is the default mode of a namespace when
43 specifying ndctl create-namespace with no options. It creates a
44 block device (/dev/pmemX[.Y]) that supports the DAX capabilities of
45 Linux filesystems (xfs and ext4 to date). DAX removes the page
46 cache from the I/O path and allows mmap(2) to establish direct
47 mappings to persistent memory media. The DAX capability enables
48 workloads / working-sets that would exceed the capacity of the page
49 cache to scale up to the capacity of persistent memory. Workloads
50 that fit in page cache or perform bulk data transfers may not see
51 benefit from DAX. When in doubt, pick this mode.
52 · devdax: Device-DAX mode enables similar mmap(2) DAX mapping
54 capabilities as Filesystem-DAX. However, instead of a block-device
55 that can support a DAX-enabled filesystem, this mode emits a single
56 character device file (/dev/daxX.Y). Use this mode to assign
57 persistent memory to a virtual-machine, register persistent memory
58 for RDMA, or when gigantic mappings are needed.
59 · sector: Use this mode to host legacy filesystems that do not
61 checksum metadata or applications that are not prepared for torn
62 sectors after a crash. Expected usage for this mode is for small
63 boot volumes. This mode is compatible with other operating systems.
64 · raw: Raw mode is effectively just a memory disk that does not
66 support DAX. Typically this indicates a namespace that was created
67 by tooling or another operating system that did not know how to
68 create a Linux fsdax or devdax mode namespace. This mode is
69 compatible with other operating systems, but again, does not
70 support DAX operation.
71
73 Create a maximally sized pmem namespace in fsdax mode (the default)
74 ndctl create-namespace
76 Convert namespace0.0 to sector mode
78 ndctl create-namespace -f -e namespace0.0 --mode=sector
80
82 -t, --type=
83 Create a pmem or blk namespace (subject to available capacity). A
84 pmem namespace supports the dax (direct access) capability to
85 mmap(2) persistent memory directly into a process address space. A
86 blk namespace access persistent memory through a
87 block-window-aperture. Compared to pmem it supports a traditional
88 storage error model (EIO on error rather than a cpu exception on a
89 bad memory access), but it does not support dax.
90 -m, --mode=
92 · "raw": expose the namespace capacity directly with limitations.
94 Neither a raw pmem namepace nor raw blk namespace support
95 sector atomicity by default (see "sector" mode below). A raw
96 pmem namespace may have limited to no dax support depending the
97 kernel. In other words operations like direct-I/O targeting a
98 dax buffer may fail for a pmem namespace in raw mode or
99 indirect through a page-cache buffer. See "fsdax" and "devdax"
100 mode for dax operation.
101 · "sector": persistent memory, given that it is byte addressable,
103 does not support sector atomicity. The problematic aspect of
104 sector tearing is that most applications do not know they have
105 a atomic sector update dependency. At least a disk rarely ever
106 tears sectors and if it does it almost certainly returns a
107 checksum error on access. Persistent memory devices will always
108 tear and always silently. Until an application is audited to be
109 robust in the presence of sector-tearing "safe" mode is
110 recommended. This imposes some performance overhead and
111 disables the dax capability. (also known as "safe" or "btt"
112 mode)
113 · "fsdax": A pmem namespace in this mode supports dax operation
115 with a block-device based filesystem (in previous ndctl
116 releases this mode was named "memory" mode). This mode comes at
117 the cost of allocating per-page metadata. The capacity can be
118 allocated from "System RAM", or from a reserved portion of
119 "Persistent Memory" (see the --map= option). NOTE: A filesystem
120 that supports DAX is required for dax operation. If the raw
121 block device (/dev/pmemX) is used directly without a
122 filesystem, it will use the page cache. See "devdax" mode for
123 raw device access that supports dax.
124 · "devdax": The device-dax character device interface is a
126 statically allocated / raw access analogue of filesystem-dax
127 (in previous ndctl releases this mode was named "dax" mode). It
128 allows memory ranges to be mapped without need of an
129 intervening filesystem. The device-dax is interface strict,
130 precise and predictable. Specifically the interface:
131 · Guarantees fault granularity with respect to a given page
133 size (4K, 2M, or 1G on x86) set at configuration time.
134 · Enforces deterministic behavior by being strict about what
136 fault scenarios are supported. I.e. if a device is
137 configured with a 2M alignment an attempt to fault a 4K
138 aligned offset will result in SIGBUS.
139 -s, --size=
141 For NVDIMM devices that support namespace labels, set the namespace
142 size in bytes. Otherwise it defaults to the maximum size specified
143 by platform firmware. This option supports the suffixes "k" or "K"
144 for KiB, "m" or "M" for MiB, "g" or "G" for GiB and "t" or "T" for
145 TiB.
146 For pmem namepsaces the size must be a multiple of the
148 interleave-width and the namespace alignment (see
149 below).
150 -a, --align
152 Applications that want to establish dax memory mappings with page
153 table entries greater than system base page size (4K on x86) need a
154 persistent memory namespace that is sufficiently aligned. For
155 "fsdax" and "devdax" mode this defaults to 2M. Note that "devdax"
156 mode enforces all mappings to be aligned to this value, i.e. it
157 fails unaligned mapping attempts. The "fsdax" alignment setting
158 determines the starting alignment of filesystem extents and may
159 limit the possible granularities, if a large mapping is not
160 possible it will silently fall back to a smaller page size.
161 -e, --reconfig=
163 Reconfigure an existing namespace (change the mode, sector size,
164 etc...). All namespace parameters, save uuid, default to the
165 current attributes of the specified namespace. The namespace is
166 then re-created with the specified modifications. The uuid is
167 refreshed to a new value by default whenever the data layout of a
168 namespace is changed, see --uuid= to set a specific uuid.
169 -u, --uuid=
171 This option is not recommended as a new uuid should be generated
172 every time a namespace is (re-)created. For recovery scenarios
173 however the uuid may be specified.
174 -n, --name=
176 For NVDIMM devices that support namespace labels, specify a human
177 friendly name for a namespace. This name is available as a device
178 attribute for use in udev rules.
179 -l, --sector-size
181 Specify the logical sector size (LBA size) of the Linux block
182 device associated with an namespace.
183 -M, --map=
185 A pmem namespace in "fsdax" or "devdax" mode requires allocation of
186 per-page metadata. The allocation can be drawn from either:
187 · "mem": typical system memory
189 · "dev": persistent memory reserved from the namespace
191 Given relative capacities of "Persistent Memory" to "System
193 RAM" the allocation defaults to reserving space out of the
194 namespace directly ("--map=dev"). The overhead is 64-bytes per
195 4K (16GB per 1TB) on x86.
196 -c, --continue
198 Do not stop after creating one namespace. Instead, greedily create
199 as many namespaces as possible within the given --bus and --region
200 filter restrictions. This will abort if any creation attempt
201 results in an error unless --force is also supplied.
202 -f, --force
204 Unless this option is specified the reconfigure namespace operation
205 will fail if the namespace is presently active. Specifying --force
206 causes the namespace to be disabled before the operation is
207 attempted. However, if the namespace is mounted then the disable
208 namespace and reconfigure namespace operations will be aborted. The
209 namespace must be unmounted before being reconfigured. When used in
210 conjunction with --continue, continue the namespace creation loop
211 even if an error is encountered for intermediate namespaces.
212 -L, --autolabel, --no-autolabel
214 Legacy NVDIMM devices do not support namespace labels. In that case
215 the kernel creates region-sized namespaces that can not be deleted.
216 Their mode can be changed, but they can not be resized smaller than
217 their parent region. This is termed a "label-less namespace". In
218 contrast, NVDIMMs and hypervisors that support the ACPI 6.2 label
219 area definition (ACPI 6.2 Section 6.5.10 NVDIMM Label Methods)
220 support "labelled namespace" operation.
221 · There are two cases where the kernel will default to label-less
223 operation:
224 · NVDIMM does not support labels
226 · The NVDIMM supports labels, but the Label Index Block (see
228 UEFI 2.7) is not present and there is no capacity aliasing
229 between blk and pmem regions.
230 · In the latter case the configuration can be upgraded to
232 labelled operation by writing an index block on all DIMMs in a
233 region and re-enabling that region. The autolabel capability of
234 ndctl create-namespace --reconfig tries to do this by default
235 if it can determine that all DIMM capacity is referenced by the
236 namespace being reconfigured. It will otherwise fail to
237 autolabel and remain in label-less mode if it finds a DIMM
238 contributes capacity to more than one region. This check
239 prevents inadvertent data loss of that other region is in
240 active use. The --autolabel option is implied by default, the
241 --no-autolabel option can be used to disable this behavior.
242 When automatic labeling fails and labelled operation is still
243 desired the safety policy can be bypassed by the following
244 commands, note that all data on all regions is forfeited by
245 running these commands:
246 ndctl disable-region all
248 ndctl init-labels all
249 ndctl enable-region all
250 -v, --verbose
252 Emit debug messages for the namespace creation process
253 -r, --region=
255 A regionX device name, or a region id number. Restrict the
256 operation to the specified region(s). The keyword all can be
257 specified to indicate the lack of any restriction, however this is
258 the same as not supplying a --region option at all.
259 -b, --bus=
261 A bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict
262 the operation to the specified bus(es). The keyword all can be
263 specified to indicate the lack of any restriction, however this is
264 the same as not supplying a --bus option at all.
265
267 Copyright (c) 2016 - 2019, Intel Corporation. License GPLv2: GNU GPL
268 version 2 <http://gnu.org/licenses/gpl.html>. This is free software:
269 you are free to change and redistribute it. There is NO WARRANTY, to
270 the extent permitted by law.
271
273 ndctl-zero-labels(1), ndctl-init-labels(1), ndctl-disable-namespace(1),
274 ndctl-enable-namespace(1), UEFI NVDIMM Label Protocol <http://
275 www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf> Linux
276 Persistent Memory Wiki <https://nvdimm.wiki.kernel.org>
277ndctl 2019-10-28 NDCTL-CREATE-NAMESPACE(1)