Provide more background information on namespace mechanics, the mode types, and expected usage models.
Signed-off-by: Dan Williams <[email protected]> --- Documentation/ndctl/namespace-description.txt | 56 +++++++++++++++++++++--- Documentation/ndctl/ndctl-create-namespace.txt | 1 2 files changed, 51 insertions(+), 6 deletions(-) diff --git a/Documentation/ndctl/namespace-description.txt b/Documentation/ndctl/namespace-description.txt index 32ab5cd83983..33d32277b885 100644 --- a/Documentation/ndctl/namespace-description.txt +++ b/Documentation/ndctl/namespace-description.txt @@ -1,8 +1,52 @@ // SPDX-License-Identifier: GPL-2.0 -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. +THEORY OF OPERATION +------------------- +The capacity of an NVDIMM REGION (contiguous span of persistent memory) +is accessed via one or more NAMESPACE devices. REGION is the Linux term +for what ACPI and UEFI call a DIMM-interleave-set, or a +system-physical-address-range that is striped (by the memory controller) +across one or more memory modules. + +The UEFI specification defines the 'NVDIMM Label Protocol' as the +combination of label area access methods and a data format for +provisioning one or more NAMESPACE objects from a REGION. Note that +label support is optional and if Linux does not detect the label +capability it will automatically instantiate a "label-less" namespace +per region. Examples of label-less namespaces are the ones created by +the kernel's 'memmap=ss!nn' command line option (see the nvdimm wiki on +kernel.org), or NVDIMMs without a valid 'namespace index' in their label +area. + +A namespace can be provisioned to operate in one of 4 modes, 'fsdax', +'devdax', 'sector', and 'raw'. Here are the expected usage models for +these modes: + - fsdax: Filesystem-DAX mode is the default mode of a namespace + when specifying 'ndctl create-namespace' with no options. It creates + a block device (/dev/pmemX[.Y]) that supports the DAX capabilities + of Linux filesystems (xfs and ext4 to date). DAX removes the page + cache from the I/O path and allows mmap(2) to establish direct + mappings to persistent memory media. The DAX capability enables + workloads / working-sets that would exceed the capacity of the page + cache to scale up to the capacity of persistent memory. Workloads + that fit in page cache or perform bulk data transfers may not see + benefit from DAX. When in doubt, pick this mode. + + - devdax: Device-DAX mode enables similar mmap(2) DAX mapping + capabilities as Filesystem-DAX. However, instead of a block-device + that can support a DAX-enabled filesystem, this mode emits a single + character device file (/dev/daxX.Y). Use this mode to assign + persistent memory to a virtual-machine, register persistent memory + for RDMA, or when gigantic mappings are needed. + + - sector: Use this mode to host legacy filesystems that do + not checksum metadata or applications that are not prepared for torn + sectors after a crash. Expected usage for this mode is for small + boot volumes. This mode is compatible with other operating systems. + + - raw: Raw mode is effectively just a memory disk that does + not support DAX. Typically this indicates an namespace that was + created by tooling or another operating system that did not know how + to create a Linux 'fsdax' or 'devdax' mode namespace. This mode is + compatible with other operating systems, but again, does not support + DAX operation. diff --git a/Documentation/ndctl/ndctl-create-namespace.txt b/Documentation/ndctl/ndctl-create-namespace.txt index 14c5409f059b..4b8b0d1c3eac 100644 --- a/Documentation/ndctl/ndctl-create-namespace.txt +++ b/Documentation/ndctl/ndctl-create-namespace.txt @@ -219,3 +219,4 @@ 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] _______________________________________________ Linux-nvdimm mailing list [email protected] https://lists.01.org/mailman/listinfo/linux-nvdimm
