On 06/24/2018 02:31 PM, Dan Williams wrote:
> Provide more background information on namespace mechanics, the mode
> types, and expected usage models.
>
> Signed-off-by: Dan Williams <[email protected]>
Reviewed-by: Dave Jiang <[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
>
_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm
