From patchwork Fri Feb 23 12:54:48 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Aishwarya Pant X-Patchwork-Id: 10237607 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 E7683602DC for ; Fri, 23 Feb 2018 12:54:58 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D18B52957A for ; Fri, 23 Feb 2018 12:54:58 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C600F2957C; Fri, 23 Feb 2018 12:54:58 +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.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_NONE, T_DKIM_INVALID autolearn=no 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 060F22957A for ; Fri, 23 Feb 2018 12:54:57 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 9F5152034D8C0; Fri, 23 Feb 2018 04:48:55 -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=2607:f8b0:400e:c05::243; helo=mail-pg0-x243.google.com; envelope-from=aishpant@gmail.com; receiver=linux-nvdimm@lists.01.org Received: from mail-pg0-x243.google.com (mail-pg0-x243.google.com [IPv6:2607:f8b0:400e:c05::243]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id ACE0F22436923 for ; Fri, 23 Feb 2018 04:48:54 -0800 (PST) Received: by mail-pg0-x243.google.com with SMTP id f6so3319087pgs.10 for ; Fri, 23 Feb 2018 04:54:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :user-agent; bh=aZUDLgmM3F8h8ycVRF3MxdaBKUOHKuI+KS/+6UcRmLQ=; b=tlbxBMLpBLKAzfUGjWH41sgt0WaOU7dF080MiWk3IXc3usfjCJMh98X01c6TkXcs9T k7m6BV1pkY4/vpMaMb3O2/ONek+7P+26+GffihRRXhC6hO4NWgWyh5O7Yno9llV2Zw/G zUJDmHamTNg5Eaw0N+xY0Gr8AZO5KBpyoO96kd1vcxG223h3uz+XSjY7UPlEro9u6q15 4HhbHwFDHCsdklxKtcmeWd82KC9iGBI6eH2vaqVhGSm80RqoO7mBZjtgIgE/1I/0AOEu scFiQCRrVkgNhfyRscLbsVRbu/7Cni3VadVvruCAcZBVwXGQcOrKS48tBjQjC11x3IvT /Hdw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:user-agent; bh=aZUDLgmM3F8h8ycVRF3MxdaBKUOHKuI+KS/+6UcRmLQ=; b=Q/UdT1yLX10lW8HLCefH8X+Yau2+vau7QrkedBEGqLPHX7LX0x7U47qLmqlK3JVvXb zEj5nMC/iGR7Kd82Wvim9/QazDQjOD5hhvtHlwO+KW459lBLuEA5cnYen/b4AWUzxgJq vJM7xINdqQyLsctRW5sqTcGNS3tnQdBrBUN3xgLz5nz2VfpmAOX1DIzOCkf6VcYGBugj WtATGO9DLQM038s4X3FZNbA9TtVwQnxvoy0D8p6eGGJc00Nqz0j0hDc8snv0BXrN9Ya8 1320sfVOnpB3wLDA02riwXvXLeplIXI8wit5zBu9aNHRpXNi5LoOKiYAYaeXg+OMEwWH QyqQ== X-Gm-Message-State: APf1xPDgrBxgvoenOUs9lB2YbvA0/2YP5kcMMMy8y9Q6QJfUDcmhi0Qu beM7Q7TnvMBrOe28Obez0KY= X-Google-Smtp-Source: AH8x225bRPElxHzRuN4Ee7QyZAJGt5t3fvudGf7jAeCPPQLe7VU3W4+EXuB3AOncevzDxjlLl6jqIQ== X-Received: by 10.99.120.201 with SMTP id t192mr1382067pgc.39.1519390494923; Fri, 23 Feb 2018 04:54:54 -0800 (PST) Received: from mordor.localdomain ([183.82.19.191]) by smtp.gmail.com with ESMTPSA id 202sm3002703pgd.32.2018.02.23.04.54.50 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 23 Feb 2018 04:54:54 -0800 (PST) Date: Fri, 23 Feb 2018 18:24:48 +0530 From: Aishwarya Pant To: Dan Williams , "Rafael J. Wysocki" , Len Brown , linux-nvdimm@lists.01.org, linux-acpi@vger.kernel.org, linux-kernel@vger.kernel.org, Jonathan Corbet , Greg KH Subject: [PATCH v2] acpi: nfit: document sysfs interface Message-ID: <20180223125448.GA16909@mordor.localdomain> MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.9.3 (2018-01-21) X-BeenThere: linux-nvdimm@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Linux-nvdimm developer list." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Julia Lawall Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" X-Virus-Scanned: ClamAV using ClamSMTP This is an attempt to document the nfit sysfs interface. The descriptions have been collected from git commit logs and the ACPI specification 6.2. Signed-off-by: Aishwarya Pant --- Changes in v2: - Add descriptions for range_index and ecc_unit_size - Edit various descriptions as suggested Documentation/ABI/testing/sysfs-bus-nfit | 233 +++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-nfit diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit new file mode 100644 index 000000000000..619eb8ca0f99 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -0,0 +1,233 @@ +For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware +Interface Table (NFIT)' section in the ACPI specification +(http://www.uefi.org/specifications) for more details. + +What: /sys/bus/nd/devices/nmemX/nfit/serial +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Serial number of the NVDIMM (non-volatile dual in-line + memory module), assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/handle +Date: Apr, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The address (given by the _ADR object) of the device on its + parent bus of the NVDIMM device containing the NVDIMM region. + + +What: /sys/bus/nd/devices/nmemX/nfit/device +Date: Apr, 2015 +KernelVersion: v4.1 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Device id for the NVDIMM, assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/rev_id +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Revision of the NVDIMM, assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/phys_id +Date: Apr, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Handle (i.e., instance number) for the SMBIOS (system + management BIOS) Memory Device structure describing the NVDIMM + containing the NVDIMM region. + + +What: /sys/bus/nd/devices/nmemX/nfit/flags +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The flags in the NFIT memory device sub-structure indicate + the state of the data on the nvdimm relative to its energy + source or last "flush to persistence". + + The attribute is a translation of the 'NVDIMM State Flags' field + in section 5.2.25.3 'NVDIMM Region Mapping' Structure of the + ACPI specification 6.2. + + The health states are "save_fail", "restore_fail", "flush_fail", + "not_armed", "smart_event", "map_fail" and "smart_notify". + + +What: /sys/bus/nd/devices/nmemX/nfit/format +What: /sys/bus/nd/devices/nmemX/nfit/format1 +What: /sys/bus/nd/devices/nmemX/nfit/formats +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The interface codes indicate support for persistent memory + mapped directly into system physical address space and / or a + block aperture access mechanism to the NVDIMM media. + The 'formats' attribute displays the number of supported + interfaces. + + This layout is compatible with existing libndctl binaries that + only expect one code per-dimm as they will ignore + nmemX/nfit/formats and nmemX/nfit/formatN. + + +What: /sys/bus/nd/devices/nmemX/nfit/vendor +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Vendor id of the NVDIMM. + + +What: /sys/bus/nd/devices/nmemX/nfit/dsm_mask +Date: May, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The bitmask indicates the supported device specific control + functions relative to the NVDIMM command family supported by the + device + + +What: /sys/bus/nd/devices/nmemX/nfit/family +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Displays the NVDIMM family command sets. Values + 0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL, + NVDIMM_FAMILY_HPE1, NVDIMM_FAMILY_HPE2 and NVDIMM_FAMILY_MSFT + respectively. + + See the specifications for these command families here: + http://pmem.io/documents/NVDIMM_DSM_Interface-V1.6.pdf + https://github.com/HewlettPackard/hpe-nvm/blob/master/Documentation/ + https://msdn.microsoft.com/library/windows/hardware/mt604741" + + +What: /sys/bus/nd/devices/nmemX/nfit/id +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) ACPI specification 6.2 section 5.2.25.9, defines an + identifier for an NVDIMM, which refelects the id attribute. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system vendor id of the NVDIMM non-volatile memory + subsystem controller. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem + controller, assigned by the non-volatile memory subsystem + controller vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_device +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system device id for the NVDIMM non-volatile memory + subsystem controller, assigned by the non-volatile memory + subsystem controller vendor. + + +What: /sys/bus/nd/devices/ndbusX/nfit/revision +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) ACPI NFIT table revision number. + + +What: /sys/bus/nd/devices/ndbusX/nfit/scrub +Date: Sep, 2016 +KernelVersion: v4.9 +Contact: linux-nvdimm@lists.01.org +Description: + (RW) This shows the number of full Address Range Scrubs (ARS) + that have been completed since driver load time. Userspace can + wait on this using select/poll etc. A '+' at the end indicates + an ARS is in progress + + Writing a value of 1 triggers an ARS scan. + + +What: /sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub +Date: Sep, 2016 +KernelVersion: v4.9 +Contact: linux-nvdimm@lists.01.org +Description: + (RW) Provides a way to toggle the behavior between just adding + the address (cache line) where the MCE happened to the poison + list and doing a full scrub. The former (selective insertion of + the address) is done unconditionally. + + This attribute can have the following values written to it: + + '0': Switch to the default mode where an exception will only + insert the address of the memory error into the poison and + badblocks lists. + '1': Enable a full scrub to happen if an exception for a memory + error is received. + + +What: /sys/bus/nd/devices/ndbusX/nfit/dsm_mask +Date: Jun, 2017 +KernelVersion: v4.13 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The bitmask indicates the supported bus specific control + functions. See the section named 'NVDIMM Root Device _DSMs' in + the ACPI specification. + + +What: /sys/bus/nd/devices/regionX/nfit/range_index +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) A unique number provided by the BIOS to identify an address + range. Used by NVDIMM Region Mapping Structure to uniquely refer + to this structure. Value of 0 is reserved and not used as an + index. + + +What: /sys/bus/nd/devices/regionX/nfit/ecc_unit_size +Date: Aug, 2017 +KernelVersion: v4.14 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Size of a write request to a DIMM that will not incur a + read-modify-write cycle at the memory controller. + + When the nfit driver initializes it runs an ARS (Address Range + Scrub) operation across every pmem range. Part of that process + involves determining the ARS capabilities of a given address + range. One of the capabilities that is reported is the 'Clear + Uncorrectable Error Range Length Unit Size' (see: ACPI 6.2 + section 9.20.7.4 Function Index 1 - Query ARS Capabilities). + This property indicates the boundary at which the NVDIMM may + need to perform read-modify-write cycles to maintain ECC (Error + Correcting Code) blocks.