From patchwork Thu Nov 16 02:17:44 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Williams X-Patchwork-Id: 10060581 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 4ACFA604D4 for ; Thu, 16 Nov 2017 02:26:02 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2C5062A545 for ; Thu, 16 Nov 2017 02:26:02 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1FFFC2A4EB; Thu, 16 Nov 2017 02:26:02 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from ml01.01.org (ml01.01.org [198.145.21.10]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 33EC42A4EB for ; Thu, 16 Nov 2017 02:26:01 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id CD52620356863; Wed, 15 Nov 2017 18:21:51 -0800 (PST) X-Original-To: linux-nvdimm@lists.01.org Delivered-To: linux-nvdimm@lists.01.org Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=134.134.136.65; helo=mga03.intel.com; envelope-from=dan.j.williams@intel.com; receiver=linux-nvdimm@lists.01.org Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id A67772034BBC0 for ; Wed, 15 Nov 2017 18:21:49 -0800 (PST) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 15 Nov 2017 18:25:58 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.44,402,1505804400"; d="scan'208";a="5502299" Received: from dwillia2-desk3.jf.intel.com (HELO dwillia2-desk3.amr.corp.intel.com) ([10.54.39.16]) by orsmga001.jf.intel.com with ESMTP; 15 Nov 2017 18:25:58 -0800 Subject: [ndctl PATCH 4/4] ndctl, create-namespace: document autolabel operation From: Dan Williams To: linux-nvdimm@lists.01.org Date: Wed, 15 Nov 2017 18:17:44 -0800 Message-ID: <151079866442.25456.15054015233088377884.stgit@dwillia2-desk3.amr.corp.intel.com> In-Reply-To: <151079864874.25456.11655607153151633382.stgit@dwillia2-desk3.amr.corp.intel.com> References: <151079864874.25456.11655607153151633382.stgit@dwillia2-desk3.amr.corp.intel.com> User-Agent: StGit/0.17.1-9-g687f MIME-Version: 1.0 X-BeenThere: linux-nvdimm@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: "Linux-nvdimm developer list." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kelly Couch Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" X-Virus-Scanned: ClamAV using ClamSMTP Write up how the autolabel mechanism operates, when it is used, and what to do when it fails. Reported-by: Kelly Couch Signed-off-by: Dan Williams --- Documentation/ndctl/ndctl-check-labels.txt | 3 +- Documentation/ndctl/ndctl-check-namespace.txt | 3 +- Documentation/ndctl/ndctl-create-namespace.txt | 47 +++++++++++++++++++++++- Documentation/ndctl/ndctl-init-labels.txt | 4 +- Documentation/ndctl/ndctl-read-labels.txt | 3 +- Documentation/ndctl/ndctl-write-labels.txt | 3 +- Documentation/ndctl/ndctl-zero-labels.txt | 3 +- 7 files changed, 52 insertions(+), 14 deletions(-) diff --git a/Documentation/ndctl/ndctl-check-labels.txt b/Documentation/ndctl/ndctl-check-labels.txt index 210eb23caf66..a7c8a5f2dcbd 100644 --- a/Documentation/ndctl/ndctl-check-labels.txt +++ b/Documentation/ndctl/ndctl-check-labels.txt @@ -28,5 +28,4 @@ the extent permitted by law. SEE ALSO -------- -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol] diff --git a/Documentation/ndctl/ndctl-check-namespace.txt b/Documentation/ndctl/ndctl-check-namespace.txt index 07fe15ac5485..49353b1b217f 100644 --- a/Documentation/ndctl/ndctl-check-namespace.txt +++ b/Documentation/ndctl/ndctl-check-namespace.txt @@ -67,5 +67,4 @@ SEE ALSO -------- linkndctl:ndctl-disable-namespace[1], linkndctl:ndctl-enable-namespace[1], -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol] diff --git a/Documentation/ndctl/ndctl-create-namespace.txt b/Documentation/ndctl/ndctl-create-namespace.txt index 0910edd753ab..c8b1c99c5229 100644 --- a/Documentation/ndctl/ndctl-create-namespace.txt +++ b/Documentation/ndctl/ndctl-create-namespace.txt @@ -159,6 +159,48 @@ OPTIONS namespace' operations will be aborted. The namespace must be unmounted before being reconfigured. +-L:: +--autolabel:: +--no-autolabel:: + Legacy NVDIMM devices do not support namespace labels. In that + case the kernel creates region-sized namespaces that can not + be deleted. Their mode can be changed, but they can not be + resized smaller than their parent region. This is termed a + "label-less namespace". In contrast, NVDIMMs and hypervisors + that support the ACPI 6.2 label area definition (ACPI 6.2 + Section 6.5.10 NVDIMM Label Methods) support "labelled + namespace" operation. + + There are two cases where the kernel will default to + label-less operation: + + * NVDIMM does not support labels + + * The NVDIMM supports labels, but the Label Index Block (see + UEFI 2.7) is not present and there is no capacity aliasing + between 'blk' and 'pmem' regions. + + In the latter case the configuration can be upgraded to + labelled operation by writing an index block on all DIMMs in a + region and re-enabling that region. The 'autolabel' capability + of 'ndctl create-namespace --reconfig' tries to do this by + default if it can determine that all DIMM capacity is + referenced by the namespace being reconfigured. It will + otherwise fail to autolabel and remain in label-less mode if + it finds a DIMM contributes capacity to more than one region. + This check prevents inadvertent data loss of that other region + is in active use. The --autolabel option is implied by + default, the --no-autolabel option can be used to disable this + behavior. When automatic labeling fails and labelled operation + is still desired the safety policy can be bypassed by the + following commands, note that all data on all regions is + forfeited by running these commands: + + [verse] + ndctl disable-region all + ndctl init-labels all + ndctl enable-region all + -v:: --verbose:: Emit debug messages for the namespace creation process @@ -177,7 +219,8 @@ the extent permitted by law. SEE ALSO -------- linkndctl:ndctl-zero-labels[1], +linkndctl:ndctl-init-labels[1], linkndctl:ndctl-disable-namespace[1], linkndctl:ndctl-enable-namespace[1], -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol +] diff --git a/Documentation/ndctl/ndctl-init-labels.txt b/Documentation/ndctl/ndctl-init-labels.txt index a5c0c127e279..d30ccc5fed0d 100644 --- a/Documentation/ndctl/ndctl-init-labels.txt +++ b/Documentation/ndctl/ndctl-init-labels.txt @@ -85,5 +85,5 @@ the extent permitted by law. SEE ALSO -------- -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +linkndctl:ndctl-create-namespace[1], +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol] diff --git a/Documentation/ndctl/ndctl-read-labels.txt b/Documentation/ndctl/ndctl-read-labels.txt index a1640d6ff566..a15e0f1061d6 100644 --- a/Documentation/ndctl/ndctl-read-labels.txt +++ b/Documentation/ndctl/ndctl-read-labels.txt @@ -34,5 +34,4 @@ the extent permitted by law. SEE ALSO -------- -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol] diff --git a/Documentation/ndctl/ndctl-write-labels.txt b/Documentation/ndctl/ndctl-write-labels.txt index bace46fba160..5e54cece95ca 100644 --- a/Documentation/ndctl/ndctl-write-labels.txt +++ b/Documentation/ndctl/ndctl-write-labels.txt @@ -25,5 +25,4 @@ include::labels-options.txt[] SEE ALSO -------- -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol] diff --git a/Documentation/ndctl/ndctl-zero-labels.txt b/Documentation/ndctl/ndctl-zero-labels.txt index 56dacf1c1714..4d56696b1933 100644 --- a/Documentation/ndctl/ndctl-zero-labels.txt +++ b/Documentation/ndctl/ndctl-zero-labels.txt @@ -27,5 +27,4 @@ the extent permitted by law. SEE ALSO -------- -http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace -Specification] +http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol]