On 06/24, Dan Williams wrote: > 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
s/an/a/ - but I can fix that up while applying. Looks good otherwise, and reads much better. > + 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
