* [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation'
@ 2018-06-24 21:31 Dan Williams
2018-06-25 5:21 ` Vishal Verma
2018-06-25 16:20 ` Dave Jiang
0 siblings, 2 replies; 3+ messages in thread
From: Dan Williams @ 2018-06-24 21:31 UTC (permalink / raw)
To: vishal.l.verma; +Cc: linux-nvdimm
Provide more background information on namespace mechanics, the mode
types, and expected usage models.
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
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
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation'
2018-06-24 21:31 [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation' Dan Williams
@ 2018-06-25 5:21 ` Vishal Verma
2018-06-25 16:20 ` Dave Jiang
1 sibling, 0 replies; 3+ messages in thread
From: Vishal Verma @ 2018-06-25 5:21 UTC (permalink / raw)
To: Dan Williams; +Cc: linux-nvdimm
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 <dan.j.williams@intel.com>
> ---
> 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
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation'
2018-06-24 21:31 [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation' Dan Williams
2018-06-25 5:21 ` Vishal Verma
@ 2018-06-25 16:20 ` Dave Jiang
1 sibling, 0 replies; 3+ messages in thread
From: Dave Jiang @ 2018-06-25 16:20 UTC (permalink / raw)
To: Dan Williams, vishal.l.verma; +Cc: linux-nvdimm
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 <dan.j.williams@intel.com>
Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> ---
> 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
> Linux-nvdimm@lists.01.org
> https://lists.01.org/mailman/listinfo/linux-nvdimm
>
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2018-06-25 16:20 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-06-24 21:31 [ndctl PATCH] ndctl, Documentation: Add namespace 'theory of operation' Dan Williams
2018-06-25 5:21 ` Vishal Verma
2018-06-25 16:20 ` Dave Jiang
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).