diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png deleted file mode 100644 index 3d503a8..0000000 Binary files a/.gitbook/assets/image.png and /dev/null differ diff --git a/README.md b/README.md index 45b4f67..440e6df 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,29 @@ -# IPMCTL User Guide +# Persistent Memory Documentation -## Introduction +## **Introductory Materials** -`ipmctl` is an open source utility created and maintained by Intel to manage Intel® Optane™ persistent memory modules. `ipmctl`, works on both Linux and Windows. The full project is open source and can be seen on [GitHub](https://github.com/intel/ipmctl). In this guide we will refer to Intel® Optane™ memory modules simply as _modules_ or _persistent memory modules_. +This [USENIX ;login: article](https://www.usenix.org/system/files/login/articles/login\_summer17\_07\_rudoff.pdf), published in the Summer of 2017, provides an overview of the persistent memory programming model and the related software work that has been taking place. It includes a very high-level description of programming with [PMDK](http://pmem.io/pmdk/), although it refers to it by the old name, [NVM Libraries](http://pmem.io/2017/12/11/NVML-is-now-PMDK.html). This article is actually a follow-on to an [earlier article](https://www.usenix.org/system/files/login/articles/08\_rudoff\_040-045\_final.pdf), published in the Summer 2013 issue of USENIX ;login:. -`ipmctl` refers to the following interface components: +The [Persistent Memory Summit 2018](https://www.snia.org/pm-summit), held January 24th, 2018, provided a day full of informative talks and panels on persistent memory (slides and videos of the sesssions are available at above link). -* `libipmctl`: An Application Programming Interface (API) library for managing persistent memory modules. -* `ipmctl`: A Command Line Interface (CLI) application for configuring and managing persistent memory modules from the command line. -* `ipmctl-monitor`: A monitor daemon/system service for monitoring the health and status of persistent memory modules. +The projects on this site, like [PMDK](http://pmem.io/pmdk/), are product-neutral, meant to work on any product that provides the persistent memory programming model. One such product is Intel’s [3D XPoint](https://www.youtube.com/watch?v=Wgk4U4qVpNY). Intel has assembled a collection of persistent memory programming documentation, webinars, videos, and related materials on the [Intel Developer Zone](https://software.intel.com/en-us/persistent-memory). -Functionality includes: +Dozens of companies have collaborated on a common persistent memory programming model in the SNIA NVM Programming Technical Workgroup (TWG). SNIA provides a [persistent memory page](http://www.snia.org/PM) on their web site with links to recent presentations, persistent memory standards and white papers, etc. The SNIA activity continues to be very active, working on areas like remote persistent memory and security. The original programming model specification put forward the basic idea that applications access persistent memory as _memory-mapped files_, a concept which has appeared as the **DAX** feature (Direct Access) on both [Linux](https://nvdimm.wiki.kernel.org/) and [Windows](https://channel9.msdn.com/Events/Build/2016/P470). -* Discover Intel Optane persistent memory modules on the platform -* Provision the platform memory configuration - * Learn more about operating modes in this [video](https://www.youtube.com/watch?v=gqo3gty-R4s) -* View and update module firmware -* Configure data-at-rest security -* Monitor module health -* Track performance of modules -* Debug and troubleshoot modules +## **Standards** -Architecture Diagram: +The [SNIA NVM Programming Model](https://www.snia.org/sites/default/files/technical\_work/final/NVMProgrammingModel\_v1.2.pdf) standard describes the basic programming model used for persistent memory programming. -![](.gitbook/assets/capture.PNG) +The [ACPI Specification](http://www.uefi.org/specifications), starting with version 6.0, defines the _NVDIMM Firmware Interface Table_ (NFIT) which is how the existence of persistent memory is communicated to operating systems. The specification also describes how NVDIMMs are partitioned into _namespaces_, methods for communicating with NVDIMMs, etc. -To learn more about how ipmctl works with the hardware see the [Intel® Optane™ Persistent Memory OS Provisioning Specification](https://cdrdv2.intel.com/v1/dl/getContent/634430), which describes all the firmware interface commands used for this operation. +The [UEFI Specification](http://www.uefi.org/specifications), covers other NVDIMM-related topics such as the _Block Translation Table_ (BTT) which allows an NVDIMM to provide block device semantics. + +Before the above two standards were developed, the [NVDIMM Namespace Specification](http://pmem.io/documents/NVDIMM\_Namespace\_Spec.pdf) described the namespace and BTT mechanisms. The link to the outdated document is maintained here for reference. + +## **Related Specifications** + +The [NVDIMM Driver Writers Guide](http://pmem.io/documents/NVDIMM\_DriverWritersGuide-July-2016.pdf) is targeted to driver writers for NVDIMMs that adhere to the NFIT tables in the Advanced Configuration and Power Interface (ACPI) V6.0 specification, the Device Specific Method (DSM) specification, and the NVDIMM Namespace Specification. This document specifically discusses the block window HW interface and persistent memory interface that Intel is proposing for NVDIMMs. A version of the document with [change bars](http://pmem.io/documents/NVDIMM\_DriverWritersGuide-July-2016\_wChanges.pdf) \[pdf] from the previous version is also available. + +The [Intel Optane PMem DSM Interface](https://pmem.io/documents/IntelOptanePMem\_DSM\_Interface-V3.0.pdf), Version 3.0, describes the NVDIMM Device Specific Methods (\_DSM) that pertain to Optane PMem modules. This document is provided as a reference for BIOS and OS driver writers supporting NVDIMMs and similar devices that appear in the ACPI NFIT table. + +The [Dirty Shutdown Handling guide](https://pmem.io/documents/Dirty\_Shutdown\_Handling-V1.0.pdf) describes the (hopefully rare) error case where flushes to persistent memory did not go as expected on power failure or system crash. The guide describes how this failure is detected, and how it is communicated to applications via the dirty shutdown count**.** diff --git a/SUMMARY.md b/SUMMARY.md index d146f7e..a01d635 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,40 +1,30 @@ # Table of contents -* [IPMCTL User Guide](README.md) -* [Installing IPMCTL](installing-ipmctl/README.md) - * [Installing IPMCTL packages on Linux](installing-ipmctl/installing-ipmctl-packages-on-linux.md) - * [Building and Installing IPMCTL from Source on Linux](installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md) - * [Installing IPMCTL on Microsoft Windows using the MSI Installer](installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md) - * [Building and Installing IPMCTL on Microsoft Windows from Source](installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md) -* [Basic Usage](basic-usage.md) -* [Module Discovery](module-discovery/README.md) - * [Show System Capabilities](module-discovery/show-system-capabilities.md) - * [Show Socket](module-discovery/show-socket.md) - * [Show Topology](module-discovery/show-topology.md) - * [Show Memory Resources](module-discovery/show-memory-resources.md) - * [Show Device](module-discovery/show-device.md) -* [Provisioning](provisioning/README.md) - * [Concepts](provisioning/concepts.md) - * [Create Memory Allocation Goal](provisioning/create-memory-allocation-goal.md) - * [Provision App Direct](provisioning/provision-app-direct.md) - * [Provision Memory Mode](provisioning/provision-memory-mode.md) - * [Provision Mixed Mode](provisioning/provision-mixed-mode.md) - * [Show Memory Allocation Goal](provisioning/show-memory-allocation-goal.md) - * [Dump Memory Allocation Settings](provisioning/dump-memory-allocation-settings.md) - * [Load Memory Allocation Goal](provisioning/load-memory-allocation-goal.md) - * [Delete Memory Allocation Goal](provisioning/delete-memory-allocation-goal.md) -* [Instrumentation](instrumentation/README.md) - * [Show Sensor](instrumentation/show-sensor.md) - * [Change Sensor Settings](instrumentation/change-sensor-settings.md) - * [Show Device Performance](instrumentation/show-device-performance.md) -* [Debug](debug/README.md) - * [Run Diagnostic](debug/run-diagnostic.md) - * [Show Error Log](debug/show-error-log.md) - * [Dump Debug Log](debug/dump-debug-log.md) - * [Show ACPI Tables](debug/show-acpi-tables.md) - * [Show Device Platform Configuration Data](debug/show-device-platform-configuration-data.md) - * [Delete Device Platform Configuration Data](debug/delete-device-platform-configuration-data.md) - * [Inject Error](debug/inject-error.md) -* [Support and Maintenance](support-and-maintenance/README.md) - * [Show Events](support-and-maintenance/show-events.md) - * [Version and Firmware](support-and-maintenance/version-and-firmware.md) +* [Persistent Memory Documentation](README.md) +* [Getting Started Guide](getting-started-guide/README.md) + * [Introduction](getting-started-guide/introduction.md) + * [PMDK Introduction](getting-started-guide/what-is-pmdk.md) + * [NDCTL Introduction](getting-started-guide/what-is-ndctl.md) + * [System Requirements](getting-started-guide/system-requirements.md) + * [Creating Development Environments](getting-started-guide/creating-development-environments/README.md) + * [Linux Environments](getting-started-guide/creating-development-environments/linux-environments/README.md) + * [Using the memmap Kernel Option](getting-started-guide/creating-development-environments/linux-environments/linux-memmap.md) + * [Advanced Topics](getting-started-guide/creating-development-environments/linux-environments/advanced-topics/README.md) + * [Partitioning Namespaces](getting-started-guide/creating-development-environments/linux-environments/advanced-topics/partitioning-namespaces.md) + * [I/O Alignment Considerations](getting-started-guide/creating-development-environments/linux-environments/advanced-topics/i-o-alignment-considerations.md) + * [Windows Environments](getting-started-guide/creating-development-environments/windows-environments.md) + * [Virtualization](getting-started-guide/creating-development-environments/virtualization/README.md) + * [Windows Server Hyper-V](getting-started-guide/creating-development-environments/virtualization/windows-server-hyper-v.md) + * [Using QEMU Virtualization](getting-started-guide/creating-development-environments/virtualization/qemu.md) + * [VMware VSphere/ESXi](getting-started-guide/creating-development-environments/virtualization/vmware-vsphere-esxi.md) + * [Cloud Environments](getting-started-guide/creating-development-environments/cloud-environments/README.md) + * [Microsoft Azure Cloud](getting-started-guide/creating-development-environments/cloud-environments/microsoft-azure-cloud.md) + * [Google Cloud Platform (GCP)](getting-started-guide/creating-development-environments/cloud-environments/google-cloud-platform-gcp.md) + * [Installing NDCTL](getting-started-guide/installing-ndctl.md) + * [Installing PMDK](getting-started-guide/installing-pmdk/README.md) + * [PMDK Directory Structure](getting-started-guide/installing-pmdk/pmdk-directory-structure.md) + * [Installing PMDK using Linux Packages](getting-started-guide/installing-pmdk/installing-pmdk-using-linux-packages.md) + * [Installing PMDK from Source on Linux](getting-started-guide/installing-pmdk/compiling-pmdk-from-source.md) + * [Installing PMDK on Windows](getting-started-guide/installing-pmdk/installing-pmdk-on-windows.md) +* [IPMCTL User Guide](https://docs.pmem.io/ipmctl-user-guide/) +* [NDCTL User Guide](https://docs.pmem.io/ndctl-user-guide/) diff --git a/basic-usage.md b/basic-usage.md deleted file mode 100644 index 68618f9..0000000 --- a/basic-usage.md +++ /dev/null @@ -1,29 +0,0 @@ -# Basic Usage - -The `ipmctl` utility has many options. A complete list of commands can be shown by executing `ipmctl` with no arguments, `ipmctl help`, or reading the `ipmctl(1)` man page. Running `ipmctl`requires root privileges. `ipmctl` can also be used from UEFI. Namespaces are created using `ipmctl` at UEFI level or the [ndctl utility](https://github.com/sscargal/pmem-docs-ipmctl-user-guide/tree/f25a04768fa69975fc7b10ea1818b460255f1b79/getting-started-guide/what-is-ndctl.md). - -Usage: - -``` -ipmctl COMMAND [OPTIONS] [TARGETS] [PROPERTIES] -``` - -Items in square brackets `[..]` are optional. Options, targets, and property values are separated by a pipe `|` meaning "or", and the default value is italicized. Items in parenthesis `(..)` indicate a user supplied value. - -`ipmctl` commands include: - -* create -* delete -* dump -* help -* load -* set -* show -* start -* version - -More information can be shown for each command using the `-verbose` flag, which is helpful for debugging. - -A video recorded by Lenovo shows [How to use ipmctl commands to monitor Intel® Optane™ DC Persistent Memory Module health status on Microsoft Windows](https://www.youtube.com/watch?v=pzSsdcfL-vg). It provides an introduction to using ipmctl. The commands are the same on Linux. - -To learn more about how ipmctl works with the hardware see the [Intel® Optane™ Persistent Memory OS Provisioning Specification](https://cdrdv2.intel.com/v1/dl/getContent/634430), which describes all the firmware interface commands used for this operation. diff --git a/debug/README.md b/debug/README.md deleted file mode 100644 index 35eaf0b..0000000 --- a/debug/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# Debug - -The ipmctl utility provides several debugging features for persistent memory modules. - -For an in-depth explanation for how ipmctl works with the hardware see the [Intel® Optane™ Persistent Memory OS Provisioning Specification](https://cdrdv2.intel.com/v1/dl/getContent/634430), which describes all the firmware interface commands used for this operation. - -Here are the articles in this section: - -{% content-ref url="run-diagnostic.md" %} -[run-diagnostic.md](run-diagnostic.md) -{% endcontent-ref %} - -{% content-ref url="show-error-log.md" %} -[show-error-log.md](show-error-log.md) -{% endcontent-ref %} - -{% content-ref url="dump-debug-log.md" %} -[dump-debug-log.md](dump-debug-log.md) -{% endcontent-ref %} - -{% content-ref url="show-acpi-tables.md" %} -[show-acpi-tables.md](show-acpi-tables.md) -{% endcontent-ref %} - -{% content-ref url="show-device-platform-configuration-data.md" %} -[show-device-platform-configuration-data.md](show-device-platform-configuration-data.md) -{% endcontent-ref %} - -{% content-ref url="delete-device-platform-configuration-data.md" %} -[delete-device-platform-configuration-data.md](delete-device-platform-configuration-data.md) -{% endcontent-ref %} - -{% content-ref url="inject-error.md" %} -[inject-error.md](inject-error.md) -{% endcontent-ref %} - diff --git a/debug/delete-device-platform-configuration-data.md b/debug/delete-device-platform-configuration-data.md deleted file mode 100644 index ac98b73..0000000 --- a/debug/delete-device-platform-configuration-data.md +++ /dev/null @@ -1,25 +0,0 @@ -# Delete Device Platform Configuration Data - -When `Config` is specified, the `Current`, `Input Data Size`, `Output Data Size` and `Start Offset` values in the Configuration header are set to zero, making those tables invalid. This action can be useful before moving modules from one system to another, as goal creation rules may restrict provisioning dimms with an existing configuration. - -> Warning: This command may result in data loss. Data should be backed up to other storage before executing this command. - -``` -ipmctl delete [OPTIONS] -dimm (DimmIds) -pcd (Config) -``` - -## **Targets** - -* `-dimm (DimmIDs)`: Deletes the PCD data on specific persistent memory modules by supplying the DIMM target and one or more comma-separated DimmIDs. The default is to delete the PCD data for all manageable modules. -* `-pcd Config`: Clears the configuration management information - -## **Examples** - -Clear the Cin, Cout, Ccur tables from all manageable modules - -
$ sudo ipmctl delete -dimm -pcd Config
-
- -## **Limitations** - -The specified module(s) must be manageable by the host software, and if data-at-rest security is enabled, the modules must be unlocked. Any existing namespaces associated with the requested module(s) should be deleted before running this command. diff --git a/debug/dump-debug-log.md b/debug/dump-debug-log.md deleted file mode 100644 index 574c0f3..0000000 --- a/debug/dump-debug-log.md +++ /dev/null @@ -1,32 +0,0 @@ -# Dump Debug Log - -Dumps encoded firmware debug logs from specified persistent memory modules and optionally decodes to human readable text. - -``` -ipmctl dump [OPTIONS] -destination (file_prefix) [-dict (file)] -debug -dimm (DimmIDs) [PROPERTIES] -``` - -## **Targets** - -* `-destination (file_prefix)`: The command will create files that use the given filename as a prefix and append the DIMM UID, DIMM handle, debug log source, and the appropriate file type (.bin for encoded logs, .txt for decoded logs) onto the end. - - > file\_prefix\_Uid\_Handle\_logsource.\[bin,txt] -* `-dict (path)`: Optional file path to the dictionary file. If supplied, the command will create both the binary debug log and a text file with decoded log data with the file prefix specified by destination. -* `-dimm (DimmIDs)`: Dumps the debug logs from the specified modules. - -## **Examples** - -Dump and decode the debug log from persistent memory modules 0x0001 and 0x0011 using the dictionary file. - -``` -$ sudo ipmctl dump -destination file_prefix -dict nlog_dict.txt -debug -dimm 0x0001,0x0011 -``` - -## **Sample Output** - -``` -Dumped media FW debug logs to file -(file_prefix_8089-A1-1816-00000016_0x0001_media.bin) -Decoded 456 records to file (file_prefix_8089-A1-1816-00000016_0x0001_media.txt) -No spi FW debug logs found -``` diff --git a/debug/inject-error.md b/debug/inject-error.md deleted file mode 100644 index d28def8..0000000 --- a/debug/inject-error.md +++ /dev/null @@ -1,134 +0,0 @@ -# Inject Error - -Injects an error or clears a previously injected error on one or more persistent memory modules for testing purposes. - -{% hint style="info" %} -Note: Error Injection is disabled by default in the BIOS, and may not be available on all platforms. Consult your server documentation or vendor before proceeding. -{% endhint %} - -``` -ipmctl set [OPTIONS] -dimm (DimmIDs) [PROPERTIES] -``` - -## **Targets** - -* `-dimm (DimmIDs)`: Injects or clears an error on a specified module by supplying the DIMM target and one or more comma-separated DimmIDs. The default is to inject the error on all manageable modules. - -## **Properties** - -This command supports setting or clearing one type of error at a time - -* `Clear=1`: Clears a previously injected error. This property must be combined with one of the other properties indicating the previously injected error to clear. -* `Temperature`: Injects an artificial media temperature in degrees Celsius into the module. The firmware that is monitoring the temperature of the module will then be alerted and take necessary precautions to preserve the module. The value is injected immediately and will override the firmware from reading the actual media temperature of the device, directing it to use this value instead. This may cause adverse reactions by the firmware and result in an alert or log. - - > Note: The injected temperature value will remain until the next reboot or it is cleared. The media temperature is an artificial temperature and will not cause harm to the part, although firmware actions due to improper temperature injections may cause adverse effects on the module. If the Critical Shutdown Temperature or higher is passed in, this may cause the module firmware to perform a shutdown in order to preserve the part and data. The temperature value will be ignored on clear. -* `Poison`: The physical address to poison. - - > Note: The address must be 256 byte aligned (e.g., 0x10000000, 0x10000100, 0x10000200...). - > - > Poison is not possible for any address in the PM region if the PM region is locked. Injected poison errors are only triggered on a subsequent read of the poisoned address, in which case an error log will be generated by the firmware. No alerts will be sent. - > - > This command can be used to clear non-injected poison errors. The data will be zero’d after clearing. There is no requirement to enable error injection prior to request to clear poison errors. - > - > The caller is responsible for keeping a list of injected poison errors in order to properly clear the injected errors afterwards. Simply disabling injection does not clear injected poison errors. Injected poison errors are persistent across power cycles and system resets. -* `PoisonType`: The type of memory to poison. One of: - * `PatrolScrub`: Injects a poison error at the specified address simulating an error found during a patrol scrub operation, which is indifferent to how the memory is currently allocated. This is the default. - * `MemoryMode`: Injects a poison error at the specified address currently allocated in Memory Mode. - * `AppDirect`: Injects a poison error at the specified address currently allocated as App Direct. - - > Note: If the address to poison is not currently allocated as the specified memory type, an error is returned. -* `PackageSparing=1`: Triggers an artificial package sparing. If package sparing is enabled and the module still has spares remaining, this will cause the firmware to report that there are no spares remaining. -* `PercentageRemaining`: Injects an artificial module life remaining percentage into the persistent memory module. This will cause the firmware to take appropriate action based on the value and if necessary generate an error log and an alert and update the health status. -* `FatalMediaError=1`: Injects a fake media fatal error which will cause the firmware to generate an error log and an alert. - - > NOTE: When a fatal media error is injected, the BSR Media Disabled status bit will be set, indicating a media error. Use the disable trigger input parameter to clear the injected fatal error. - > - > NOTE: Injecting a fatal media error is unsupported on Windows. Please contact Microsoft for assistance in performing this action. -* `DirtyShutdown=1`: Injects an ADR failure, which will result in a dirty shutdown upon reboot. - -## **Examples** - -Set the media temperature on all manageable modules to 100 degrees Celsius. - -``` -$ sudo ipmctl set -dimm Temperature=100 -``` - -Clear the injected media temperature on all manageable modules - -``` -$ sudo ipmctl set -dimm Temperature=1 Clear=1 -``` - -Poison address 0x10000100 on module 0x0001 - -``` -$ sudo ipmctl set -dimm 0x0001 Poison=0x10000200 -``` - -Clear the injected poison of address 0x10000200 on module 0x0001. - -``` -$ sudo ipmctl set -dimm 0x0001 Poison=0x10000200 Clear=1 -``` - -Trigger an artificial package sparing on all manageable modules. - -``` -$ sudo ipmctl set -dimm PackageSparing=1 -``` - -Trigger an artificial package sparing on module 0x0001. - -``` -$ sudo ipmctl set -dimm 0x0001 PackageSparing=1 -``` - -Set the life remaining percentage on all manageable modules to 10%. - -``` -$ sudo ipmctl set -dimm PercentageRemaining=10 -``` - -Set the life remaining percentage module 0x0001 to 10%. - -``` -$ sudo ipmctl set -dimm 0x0001 PercentageRemaining=10 -``` - -Clear the injected remaining life percentage on all manageable modules. The value of PercentageRemaining is irrelevant. - -``` -$ sudo ipmctl set -dimm PercentageRemaining=10 Clear=1 -``` - -Trigger an artificial Asynchronous DRAM Refresh (ADR) failure on all manageable modules, which will result in a dirty shutdown on each module on the next reboot. - -``` -$ sudo ipmctl set -dimm DirtyShutdown=1 -``` - -Trigger an artificial Asynchronous DRAM Refresh (ADR) failure on module 0x0001, which will result in a dirty shutdown on each module on the next reboot. - -``` -$ sudo ipmctl set -dimm 0x0001 DirtyShutdown=1 -``` - -Simulate a Fatal Media Error on PMem module 0x2001. - -{% hint style="danger" %} -**WARNING**: Injecting a Fatal Media Error may cause the host to crash. Linux hosts may enter emergency mode if there are PMem mount points in /etc/fstab. Additional recovery activities may be required. - -Clearing the fault will not cause any data loss. -{% endhint %} - -``` -$ sudo ipmctl set -dimm 0x2001 FatalMediaError=1 -``` - -Clear the Fatal Media Error on PMem module 0x20001 - -``` -$ sudo ipmctl set -dimm 0x2001 FatalMediaError=1 Clear=1 -``` - diff --git a/debug/run-diagnostic.md b/debug/run-diagnostic.md deleted file mode 100644 index 2c5044e..0000000 --- a/debug/run-diagnostic.md +++ /dev/null @@ -1,51 +0,0 @@ -# Run Diagnostic - -Runs a diagnostic test. - -``` -ipmctl start [OPTIONS] -diagnostic (Quick|Config|Security|FW) -dimm(DIMMIDs) -``` - -## **Targets** - -* `-diagnostic (Quick|Config|Security|FW)`: Run a specific test by supplying its name. By default all tests are run. One of: - * `Quick` - This test verifies that the persistent memory module host mailbox is accessible and that basic health indicators can be read and are currently reporting acceptable values. - * `Config` - This test verifies that the BIOS platform configuration matches the installed hardware and the platform configuration conforms to best known practices. - * `Security` - This test verifies that all modules have a consistent security state. It’s a best practice to enable security on all modules rather than just some. - * `FW` - This test verifies that all modules of a given model have consistent firmware installed and other firmware modifiable attributes are set in accordance with best practices. - * Note that the test does not have a means of verifying that the installed firmware is the optimal version for a given Intel Optane DC memory module model - just that it’s been consistently applied across the system. -* `dimm (DimmIDs)`: Runs a diagnostic test on specific modules by supplying one or more comma-separated DimmIDs. The default is to run the specified tests on all manageable modules. Only valid for the `Quick` diagnostic test. - -## **Examples** - -Run all diagnostics - -``` -$ sudo ipmctl start -diagnostic -``` - -Run the quick check diagnostic on module 0x0001 - -``` -$ sudo ipmctl start -diagnostic Quick -dimm 0x0001 -``` - -## **Return Data** - -Each diagnostic generates one or more log messages. A successful test generates a single log message per module indicating that no errors were found. A failed test might generate multiple log messages each highlighting a specific error with all the relevant details. Each log contains the following information: - -``` -`TestName`: The test name. One of: -- `Quick` -- `Config` -- `Security` -- `FW` - -`State`: The severity of the error. One of: -- `Ok` -- `Warning` -- `Failed` -- `Aborted` - -`Message`: A free form textual description of the error. -``` diff --git a/debug/show-acpi-tables.md b/debug/show-acpi-tables.md deleted file mode 100644 index 333aced..0000000 --- a/debug/show-acpi-tables.md +++ /dev/null @@ -1,30 +0,0 @@ -# Show ACPI Tables - -Shows the system ACPI tables related to persistent memory modules. - -``` -ipmctl show [OPTIONS] -system (NFIT|PCAT|PMTT) -``` - -## **Targets** - -* `system (NFIT|PCAT|PMTT)`: The system ACPI table(s) to display. By default both the NFIT and PCAT tables are displayed. One of: - * "NFIT": The NVDIMM Firmware Interface Table - * "PCAT": The Platform Capabilities Table - * "PMTT": The Platform Memory Topology Table - - Refer to the ACPI specification for detailed information about the ACPI tables. - -## **Examples** - -Show the ACPI NFIT - -``` -$ sudo ipmctl show -system NFIT -``` - -## **Return Data** - -Returns the formatted data from the requested ACPI tables and their sub-tables. Refer to the ACPI specification for detailed information about the format of the ACPI tables. - -> Note: All data is presented in ACPI little endian format. diff --git a/debug/show-device-platform-configuration-data.md b/debug/show-device-platform-configuration-data.md deleted file mode 100644 index 68143e3..0000000 --- a/debug/show-device-platform-configuration-data.md +++ /dev/null @@ -1,28 +0,0 @@ -# Show Device Platform Configuration Data - -Shows the platform configuration data for one or more persistent memory modules. - -``` -ipmctl show [OPTIONS] -dimm (DimmIds) -pcd (Config|LSA) -``` - -## **Targets** - -* `-dimm (DimmIDs)`: Show the platform configuration data on specific modules by supplying the DIMM target and one or more comma-separated DimmIDs. The default is to display the platform configuration data for all manageable modules. -* `-pcd (Config|LSA)`: Restricts output to a specific partition of the platform configuration data. The default is to display both. One of: - * `Config`: Configuration management information - * `LSA`: Namespace label storage area - -## **Examples** - -Show the configuration information from the platform configuration data for all manageable modules - -``` -$ sudo ipmctl show -dimm -pcd -``` - -Show the configuration information from the platform configuration data for module 0x0001 - -``` -ipmctl show -dimm 0x0001 -pcd Config -``` diff --git a/debug/show-error-log.md b/debug/show-error-log.md deleted file mode 100644 index 610309c..0000000 --- a/debug/show-error-log.md +++ /dev/null @@ -1,56 +0,0 @@ -# Show Error Log - -Shows thermal or media errors on the specified persistent memory modules. - -``` -ipmctl show [OPTIONS] -error (Thermal|Media) [TARGETS] [PROPERTIES] -``` - -## **Targets** - -* `-dimm (DimmIDs)`: Show only the events on specific modules by supplying the DIMM target and one or more comma-separated DimmIDs. - -## **Properties** - -* `SequenceNumber`: Error log entries are stored with a sequence number starting with 1 and rolling over back to 1 after 65535. Limit the error log entries returned by providing a sequence number. Only errors with a sequence number equal to or higher than that provided will be returned. The default is 1. -* `Level`: Severity level of errors to be fetched. One of: - * "High": high severity errors (default) - * "Low": Low severity errors -* `Count`: Max number of error entries to be fetched and printed. The default is 8 for media errors and 16 for thermal errors. - -## **Examples** - -Show all high thermal error log entries - -``` -$ sudo ipmctl show -error Thermal Level=High -``` - -Show all low media error log entries - -``` -$ sudo ipmctl show -error Thermal Level=Low -``` - -## **Sample Output** - -``` -Thermal Error occurred on Dimm (DimmID): -System Timestamp : 1527273299 -Temperature : 88C -Reported : 4 - Critical -Temperature Type : 0 - Media Temperature -Sequence Number : 1 -``` - -``` -Media Error occurred on Dimm (DimmID): -System Timestamp : 1527266471 -DPA : 0x000014c0 -PDA : 0x00000600 -Range : 4B -Error Type : 4 - Locked/Illegal Access -Error Flags : DPA Valid -Transaction Type : 11 - CSR Write -Sequence Number : 2 -``` diff --git a/installing-ipmctl/README.md b/installing-ipmctl/README.md deleted file mode 100644 index a972374..0000000 --- a/installing-ipmctl/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# Installing IPMCTL - -ipmctl is available for both Linux and Microsoft Windows. Follow the links below for step-by-step instructions to install using available packages, binaries, or build and install from source code if you require the most recent version. - -### Linux - -{% content-ref url="installing-ipmctl-packages-on-linux.md" %} -[installing-ipmctl-packages-on-linux.md](installing-ipmctl-packages-on-linux.md) -{% endcontent-ref %} - -{% content-ref url="building-and-installing-ipmctl-from-source-on-linux.md" %} -[building-and-installing-ipmctl-from-source-on-linux.md](building-and-installing-ipmctl-from-source-on-linux.md) -{% endcontent-ref %} - -### Microsoft Windows - -{% content-ref url="installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md" %} -[installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md](installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md) -{% endcontent-ref %} - -{% content-ref url="building-and-installing-ipmctl-on-microsoft-windows-from-source.md" %} -[building-and-installing-ipmctl-on-microsoft-windows-from-source.md](building-and-installing-ipmctl-on-microsoft-windows-from-source.md) -{% endcontent-ref %} - -## Releases - -ipmctl supports all product generations for Intel Optane persistent memory and is backward compatible with older generations. The table describes the ipmctl version required for each product generation. - -| ipmctl version | Intel Optane Persistent Memory Generation | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 01.00.00.xxxx |

1st Generation Intel Optane Persistent Memory Series 100

Code name: Apache Pass

| -| 02.00.00.xxxx |

1st Generation Intel Optane Persistent Memory Series 100

Code name: Apache Pass
Recommend using v02.00.00.3693 or later


2nd Generation Intel Optane Persistent Memory Series 200

Code Name: Barlow Pass

| - diff --git a/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md b/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md deleted file mode 100644 index 909d7a5..0000000 --- a/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md +++ /dev/null @@ -1,773 +0,0 @@ -# Building and Installing IPMCTL from Source on Linux - -Building ipmctl from source code if your Linux package repository does not provide package or it contains a old version. - -{% tabs %} -{% tab title="Fedora" %} -This procedure provides the steps for building and installing ipmctl on Fedora. - -### Prerequisites - -ipmctl has a dependency on libsafec-devel, libndctl-devel and rubygem-asciidoctor. Steps to install these packages is provided below. - -#### Install the required utilities - -This procedure requires the following utilities - -* wget -* git -* cmake -* gcc -* gcc-c++ -* glibc -* glibc-static - -``` -sudo dnf install wget git cmake gcc gcc-c++ glibc glibc-static -``` - -#### libsafec - -libsafec is available as a package in the EPEL repository (Extra Packages for Enterprise Linux). - -Alternately, when compiling ipmctl from source code, use the `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON` option to download safelibc source and build it as a static library with ipmctl. See the Build section below for more information. - -Verify the `libsafec` package can be found - -``` -dnf info libsafec libsafec-devel -``` - -Example: - -``` -$ dnf info libsafec libsafec-devel - -Available Packages -Name : libsafec -Version : 3.3 -Release : 5.fc31 -Architecture : i686 -Size : 82 k -Source : libsafec-3.3-5.fc31.src.rpm -Repository : fedora -Summary : Safec fork with all C11 Annex K functions -URL : https://github.com/rurban/safeclib -License : MIT -Description : Safec fork with all C11 Annex K functions - -Name : libsafec-devel -Version : 3.3 -Release : 5.fc31 -Architecture : i686 -Size : 19 k -Source : libsafec-3.3-5.fc31.src.rpm -Repository : fedora -Summary : Development packages for libsafec -URL : https://github.com/rurban/safeclib -License : MIT -Description : Development files for libsafec -``` - -Install the libsafec and libsafec-devel packages - -``` -sudo dnf install libsafec libsafec-devel -``` - -#### libndctl-devel - -The development files can be installed from source code or packages. See '[Installing NDCTL & DAXCTL](https://docs.pmem.io/ndctl-user-guide/installing-ndctl)' in the ndctl user guide for detailed instructions. - -To install the package: - -``` -sudo dnf install ndctl-devel -``` - -#### Asciidoctor - -The `rubygem-asciidoctor` package can be found in the EPEL (Extra Package for Enterprise Linux) repository. - -Install the rubygem-asciidoctor and optional rubygem-asciidoctor-pdf packages - -``` -sudo dnf install rubygem-asciidoctor rubygem-asciidoctor-pdf -``` - -### - -### Build - -Create a temporary build area - -``` -mkdir ~/downloads -cd ~/downloads -``` - -Clone the ipmctl GitHub repository - -``` -git clone https://github.com/intel/ipmctl -cd ipmctl -``` - -{% hint style="info" %} -**Optional**: To build a different release version, use git to checkout the version branch, eg: - -List all available branches using the following. It shows a master\_1\_0 and master\_2\_0 for version 1.x and 2.x respectively. This represents the current version for each release. - -``` -$ # git branch -a | grep master -* master - remotes/origin/HEAD -> origin/master - remotes/origin/master - remotes/origin/master_1_0 - remotes/origin/master_2_0 -``` - -Example: Checkout the version 1.x branch and continue the build process: - -``` -$ git checkout remotes/origin/master_1_0 -Switched to a new branch 'remotes/origin/master_1_0' -``` - -To build a specific version, list the tags: - -``` -$ git tag -[...] -v01.00.00.3481 -v01.00.00.3494 -v01.00.00.3497 -[...] -v02.00.00.3781 -v02.00.00.3785 -v02.00.00.3791 -``` - -Create a new branch from a specific tagged version, use the following and continue with the build process: - -``` -$ git checkout tags/v02.00.00.3791 -b v02.00.00.3791 -Switched to a new branch 'v02.00.00.3791' -``` -{% endhint %} - -If you installed the safelibc package, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - -To have ipmctl cmake download and statically build safelibc, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - -### - -### Install - -Install ipmctl using: - -``` -sudo make install -``` -{% endtab %} - -{% tab title="RHEL & CENTOS" %} -This procedure provides the steps for building and installing ipmctl on RHEL, CENTOS, and RHEL for SAP HANA 7.5 and later. - -### Prerequisites - -ipmctl has a dependency on libsafec-devel, libndctl-devel and rubygem-asciidoctor. Steps to install these packages is provided below. - -#### EPEL Package Repository - -Several packages required by ipmctl are available in the EPEL (Extra Packages for Enterprise Linux). The epel repository must be installed and enabled. - -Verify the EPEL repository is available and enabled: - -``` -yum repolist -``` - -Example: - -``` -$ yum repolist -repo id repo name status -epel/x86_64 Extra Packages for Enterprise Linux 7 - x86_64 13,220 -``` - -If the EPEL repository is not listed, install and enable it using: - -``` -sudo yum install epel-release -``` - -#### Enable the PowerTools repository - -``` -sudo yum config-manager --set-enabled PowerTools -``` - -#### Install the required utilities - -This procedure requires the following utilities - -* wget -* git -* cmake -* gcc -* gcc-c++ -* glibc -* glibc-static - -``` -sudo yum install wget git cmake gcc gcc-c++ glibc glibc-static -``` - -#### libsafec - -libsafec is available as a package in the EPEL repository (Extra Packages for Enterprise Linux). - -Alternately, when compiling ipmctl from source code, use the `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON` option to download safelibc source and build it as a static library with ipmctl. See the Build section below for more information. - -Verify the `libsafec` package can be found - -``` -yum info libsafec libsafec-devel -``` - -Example: - -``` -$ yum info libsafec* - -Available Packages -Name : libsafec -Arch : x86_64 -Version : 3.3 -Release : 5.el7 -Size : 69 k -Repo : epel/x86_64 -Summary : Safec fork with all C11 Annex K functions -URL : https://github.com/rurban/safeclib -License : MIT -Description : Safec fork with all C11 Annex K functions - -Name : libsafec-devel -Arch : x86_64 -Version : 3.3 -Release : 5.el7 -Size : 74 k -Repo : installed -From repo : epel -Summary : Development packages for libsafec -URL : https://github.com/rurban/safeclib -License : MIT -Description : Development files for libsafec -``` - -Install the libsafec and libsafec-devel packages - -``` -sudo yum install libsafec libsafec-devel -``` - -#### libndctl-devel - -The development files can be installed from source code or packages. See '[Installing NDCTL & DAXCTL](https://docs.pmem.io/ndctl-user-guide/installing-ndctl)' in the ndctl user guide for detailed instructions. - -To install the package: - -``` -sudo yum install ndctl-devel -``` - -#### Asciidoctor - -The `rubygem-asciidoctor` package can be found in the EPEL (Extra Package for Enterprise Linux) repository. - -Install the rubygem-asciidoctor package - -``` -sudo yum install rubygem-asciidoctor -``` - -**\[Optional]** PDF documents can be built if `asciidoctor-pdf` is installed. This is completely optional. Warnings during the cmake make occur but can be ignored. Asciidoctor-pdf is installed using the `gem` utility. Asciidoctor-pdf requires Ruby 2.1 or later. CentOS 7 provides Ruby 2.0. See [How to Install Ruby on CentOS/RHEL 7/6](https://tecadmin.net/install-ruby-latest-stable-centos/) for instructions to install a current Ruby version. - -With Ruby >2.1 installed, install asciidoctor-pdf - -``` -sudo gem install asciidoctor-pdf -``` - -### - -### Build - -Create a temporary build area - -``` -mkdir ~/downloads -cd ~/downloads -``` - -Clone the ipmctl GitHub repository - -``` -git clone https://github.com/intel/ipmctl -cd ipmctl -``` - -{% hint style="info" %} -**Optional**: To build a different release version, use git to checkout the version branch, eg: - -List all available branches using the following. It shows a master\_1\_0 and master\_2\_0 for version 1.x and 2.x respectively. This represents the current version for each release. - -``` -$ # git branch -a | grep master -* master - remotes/origin/HEAD -> origin/master - remotes/origin/master - remotes/origin/master_1_0 - remotes/origin/master_2_0 -``` - -Example: Checkout the version 1.x branch and continue the build process: - -``` -$ git checkout remotes/origin/master_1_0 -Switched to a new branch 'remotes/origin/master_1_0' -``` - -To build a specific version, list the tags: - -``` -$ git tag -[...] -v01.00.00.3481 -v01.00.00.3494 -v01.00.00.3497 -[...] -v02.00.00.3781 -v02.00.00.3785 -v02.00.00.3791 -``` - -Create a new branch from a specific tagged version, use the following and continue with the build process: - -``` -$ git checkout tags/v02.00.00.3791 -b v02.00.00.3791 -Switched to a new branch 'v02.00.00.3791' -``` -{% endhint %} - -If you installed the safelibc package, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - -To have ipmctl cmake download and statically build safelibc, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - -### - -### Install - -Install ipmctl using: - -``` -sudo make install -``` -{% endtab %} - -{% tab title="Ubuntu" %} -This procedure provides the steps for building and installing ipmctl on Ubuntu. - -### Prerequisites - -ipmctl has a dependency on libsafec-devel, libndctl-devel and ruby-asciidoctor. Steps to install these packages is provided below. - -#### Install the required utilities - -This procedure requires the following utilities - -* wget -* git -* cmake -* pkg-config -* autoconf -* doxygen -* libtool -* gcc -* gcc-c++ -* glibc -* asciidoctor - -``` -sudo apt update -sudo apt install wget git cmake pkg-config autoconf doxygen libtool build-essential -``` - -#### libsafec - -libsafec is available as a package in the default package repository for Ubuntu 19.10 (Eoan) or later. For earlier releases, use the `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON` option to download safelibc source and build it as a static library with ipmctl. See the Build section below for more information. - -Verify the `libsafec` package can be found - -``` -sudo apt info libsafec* libsafec-dev* -``` - -Install the libsafec and libsafec-devel packages - -``` -sudo apt install libsafec-3.5.3 libsafec-dev -``` - - - -#### libndctl-devel - -The development files can be installed from source code or packages. See '[Installing NDCTL & DAXCTL](https://docs.pmem.io/ndctl-user-guide/installing-ndctl)' in the ndctl user guide for detailed instructions. - -To install the package: - -``` -sudo apt install libndctl-dev -``` - - - -#### Asciidoctor - -**Ubuntu 16.04 & 18.04** - -Install asciidoctor using the ruby gems - -``` -sudo apt install ruby -sudo gem install asciidoctor asciidoctor-pdf --pre -``` - -**Ubuntu 19.04 or later** - -The `ruby-asciidoctor` package can be found in the default package repository. - -Install the ruby-asciidoctor and optional ruby-asciidoctor-pdf packages - -``` -sudo apt install ruby-asciidoctor ruby-asciidoctor-pdf asciidoctor -``` - - - -### Build - -Create a temporary build area - -``` -mkdir ~/downloads -cd ~/downloads -``` - -Clone the ipmctl GitHub repository - -``` -git clone https://github.com/intel/ipmctl -``` - -{% hint style="info" %} -**Optional**: To build a different release version, use git to checkout the version branch, eg: - -List all available branches using the following. It shows a master\_1\_0 and master\_2\_0 for version 1.x and 2.x respectively. This represents the current version for each release. - -``` -$ # git branch -a | grep master -* master - remotes/origin/HEAD -> origin/master - remotes/origin/master - remotes/origin/master_1_0 - remotes/origin/master_2_0 -``` - -Example: Checkout the version 1.x branch and continue the build process: - -``` -$ git checkout remotes/origin/master_1_0 -Switched to a new branch 'remotes/origin/master_1_0' -``` - -To build a specific version, list the tags: - -``` -$ git tag -[...] -v01.00.00.3481 -v01.00.00.3494 -v01.00.00.3497 -[...] -v02.00.00.3781 -v02.00.00.3785 -v02.00.00.3791 -``` - -Create a new branch from a specific tagged version, use the following and continue with the build process: - -``` -$ git checkout tags/v02.00.00.3791 -b v02.00.00.3791 -Switched to a new branch 'v02.00.00.3791' -``` -{% endhint %} - -If you installed the safelibc package, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - -To have ipmctl cmake download and statically build safelibc, use: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON -DCMAKE_INSTALL_PREFIX=/ .. -make -j all -``` - - - -### Install - -Install ipmctl using: - -``` -sudo make install -``` -{% endtab %} - -{% tab title="SLES/OpenSUSE" %} -This procedure provides the steps for building and installing ipmctl on SUSE Linux for Enterprise (SLES) and OpenSUSE (Leap). - -### Prerequisites - -ipmctl has a dependency on libsafec-devel, libndctl-devel and rubygem-asciidoctor. Steps to install these packages is provided below. - -#### Install the required utilities - -This procedure requires the following utilities - -* wget -* git -* cmake -* gcc -* gcc-c++ -* gem -* glibc -* glibc-static - -``` -sudo zypper install wget git cmake gcc gcc-c++ gem glibc glibc-static -``` - -#### libsafec - -When compiling ipmctl from source code, use the `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON` option to download safelibc source and build it as a static library with ipmctl. See the Build section below for more information. - -#### libndctl-devel - -The development files can be installed from source code or packages. See '[Installing NDCTL & DAXCTL](https://docs.pmem.io/ndctl-user-guide/installing-ndctl)' in the ndctl user guide for detailed instructions. If you installed ndctl using the packages, install the ndctl-devel package using: - -``` -sudo zypper install libndctl-devel -``` - -If you built ndctl from the source code, the required header files should already be available. - -#### Asciidoctor - -Install the rubygem-asciidoctor and optional rubygem-asciidoctor-pdf packages using the gem command - -``` -sudo gem install asciidoctor asciidoctor-pdf -``` - -### Build - -Create a temporary build area - -``` -mkdir ~/downloads -cd ~/downloads -``` - -Clone the ipmctl GitHub repository - -``` -git clone https://github.com/intel/ipmctl -cd ipmctl -``` - -{% hint style="info" %} -**Optional**: To build a different release version, use git to checkout the version branch, eg: - -List all available branches using the following. It shows a master\_1\_0 and master\_2\_0 for version 1.x and 2.x respectively. This represents the current version for each release. - -``` -$ # git branch -a | grep master -* master - remotes/origin/HEAD -> origin/master - remotes/origin/master - remotes/origin/master_1_0 - remotes/origin/master_2_0 -``` - -Example: Checkout the version 1.x branch and continue the build process: - -``` -$ git checkout remotes/origin/master_1_0 -Switched to a new branch 'remotes/origin/master_1_0' -``` - -To build a specific version, list the tags: - -``` -$ git tag -[...] -v01.00.00.3481 -v01.00.00.3494 -v01.00.00.3497 -[...] -v02.00.00.3781 -v02.00.00.3785 -v02.00.00.3791 -``` - -Create a new branch from a specific tagged version, use the following and continue with the build process: - -``` -$ git checkout tags/v02.00.00.3791 -b v02.00.00.3791 -Switched to a new branch 'v02.00.00.3791' -``` -{% endhint %} - -The following cmake command will download and statically build safelibc: - -``` -mkdir output && cd output -cmake -DRELEASE=ON -DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON -DCMAKE_INSTALL_PREFIX=/usr/local .. -make -j all -``` - -### Install - -Install ipmctl using: - -``` -sudo make install -``` -{% endtab %} -{% endtabs %} - - - - - - - -Go to the [Basic Usage](../basic-usage.md) section of this user guide for more information. - - - -### Troubleshooting - -The following lists common issues and errors encountered during the cmake process and how to resolve them - -#### Issue: -- Could NOT find asciidoctor-pdf (missing: ASCIIDOCTOR\_PDF\_BINARY) - -You may see a warning during the cmake process referencing a missing asciidoctor-pdf binary. - -``` --- Could NOT find asciidoctor-pdf (missing: ASCIIDOCTOR_PDF_BINARY) -asciidoctor-pdf not found -``` - -#### **Solution:** - -PDF documents can be built if asciidoctor-pdf is installed. This is completely optional. Warnings during the cmake make occur but can be ignored. Asciidoctor-pdf is installed using the gem utility. Asciidoctor-pdf requires Ruby 2.1 or later. CentOS 7 provides Ruby 2.0. See How to Install Ruby on CentOS/RHEL 7/6 for instructions to install a later version of Ruby. With Ruby >2.1 installed, install asciidoctor-pdf: - -``` -sudo gem install asciidoctor-pdf -``` - -#### - -#### Issue: -- Could NOT find asciidoc (missing: ASCIIDOC\_BINARY) - -#### Solution: - -If asciidoctor is installed, ascidoc is not required. This message can be safely ignored.--- - - - -#### Issue: -- Could NOT find a2x (missing: A2X\_BINARY) - -#### Solution: - -The `a2x` binary is delivered with the asciidoc package. a2x converts Asciidoc text file to PDF, XHTML, HTML Help, manpage or plain text. If the asciidoc package is not installed, this message can be safely ignored. Asciidoctor will be used instead to build the documentation. - -#### Issue: -- package 'safec-3.3>=03032018.0-g570fa5' not found - -Example: - -``` --- package 'safec-3.3>=03032018.0-g570fa5' not found -CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:279 (message): - A required package was not found -Call Stack (most recent call first): - /usr/share/cmake/Modules/FindPkgConfig.cmake:333 (_pkg_check_modules_internal) - CMakeLists.txt:87 (pkg_check_modules) -``` - -You should not encounter this message when using the `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON` cmake option. - -#### Solution: - -The issue can occur if the libsafec and libsafec-devel packages are not installed. See the 'Prerequisites' section at the top of this page. - -If you installed the libsafec package from a repository other than EPEL, remove and re-install the libsafec package using the epel repository. Follow the instructions in the 'libsafec' section above. - -If you built and installed libsafec from source code, the error is caused by a missing pkgconfig (pc) file. Update your LD\_LIBRARY\_PATH and PKG\_CONFIG\_PATH to include the path you installed libsafec to. For example, the following adds the common install locaitons to your shell environment. You will need to add these to your shell environment file (eg: \~/.bashrc) for them to become permanent. - -``` -export LD_LIBRARY_PATH=/usr/lib:/usr/lib64:/usr/local/lib:/usr/local/lib64:${LD_LIBRARY_PATH} -export PKG_CONFIG_PATH=/usr/lib64/pkgconfig:/usr/lib/pkgconfig:usr/local/lib64/pkgconfig:/usr/local/lib/pkgconfig:/usr/share/pkgconfig:${PKG_CONFIG_PATH} -``` - -Alternatively, add `-DSAFECLIB_SRC_DOWNLOAD_AND_STATIC_LINK=ON`to the cmake file to download and build the static version of libsafec. - -#### Issue: -- cc: internal compiler error: Killed (program cc1) - -**Solution:** - -Running make -j all runs lots of processes, which use more memory. The problem above occurs when your system runs out of memory. Use `make` instead of `make -j all`. diff --git a/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md b/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md deleted file mode 100644 index 9310afa..0000000 --- a/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md +++ /dev/null @@ -1,14 +0,0 @@ -# Building and Installing IPMCTL on Microsoft Windows from Source - -Step 1) Install Visual Studio 2017 (or newer). Install these optional components: - -* Workloads -> Desktop Development with C++ -* Individual Components -> Compilers, build tools, and runtimes -> Visual C++ tools for CMake - -Step 2) Download the [ipmctl source code from GitHub](https://github.com/intel/ipmctl) - -Step 3) Open the ipmctl folder as a CMake project. See: [https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio) - -Step 4) Begin the build process - -Step 5) Once installed, go to the [Basic Usage](../basic-usage.md) section of this user guide for more information. diff --git a/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md b/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md deleted file mode 100644 index a576df4..0000000 --- a/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md +++ /dev/null @@ -1,11 +0,0 @@ -# Installing IPMCTL on Microsoft Windows using the MSI Installer - -Step 1) The latest ipmctl Windows installer can be downloaded from the “Releases” section of the GutHub project page ([https://github.com/intel/ipmctl/releases](https://github.com/intel/ipmctl/releases)) as shown in Figure 1. - -![Figure 1: ipmctl releases on GitHub](../.gitbook/assets/image.png) - -Download the `ipmctl_windows_install-.exe` file. - -Step 2) Run the `ipmctl_windows_install-.exe` file. The installer makes the ipmctl utility available in the powershell available to the system administrator. - -Step 3) Go to the [Basic Usage](../basic-usage.md) section of this user guide for more information. diff --git a/installing-ipmctl/installing-ipmctl-packages-on-linux.md b/installing-ipmctl/installing-ipmctl-packages-on-linux.md deleted file mode 100644 index cbf6597..0000000 --- a/installing-ipmctl/installing-ipmctl-packages-on-linux.md +++ /dev/null @@ -1,265 +0,0 @@ -# Installing IPMCTL packages on Linux - -The `ipmctl` utility is available in many Linux distribution package repositories. This approach is the easiest to install and maintain, compared with [building and installing ipmctl from source](building-and-installing-ipmctl-from-source-on-linux.md). However, the version of ipmctl available in the package repository may not be current. - -{% tabs %} -{% tab title="Fedora" %} -The ipmctl package for v02.00.00.xxxx or later is available in the default package repository on Fedora. - -Step 1) Query the package repository to confirm that ipmctl is available: - -``` -dnf search ipmctl -dnf info ipmctl -``` - -Example: - -``` -$ dnf search ipmctl -Last metadata expiration check: 1:24:31 ago on Fri 27 Mar 2020 06:27:17 PM MDT. -================================================== Name Exactly Matched: ipmctl ================================================== -ipmctl.x86_64 : Utility for managing Intel Optane DC persistent memory modules -================================================= Name & Summary Matched: ipmctl ================================================= -libipmctl-devel.x86_64 : Development packages for libipmctl -ipmctl-debugsource.x86_64 : Debug sources for package ipmctl -ipmctl-debuginfo.x86_64 : Debug information for package ipmctl -libipmctl-debuginfo.x86_64 : Debug information for package libipmctl -ipmctl-monitor-debuginfo.x86_64 : Debug information for package ipmctl-monitor -====================================================== Name Matched: ipmctl ====================================================== -libipmctl.x86_64 : Library for Intel DCPMM management -ipmctl-monitor.x86_64 : Daemon for monitoring the status of Intel DCPMM - -$ dnf info ipmctl -Last metadata expiration check: 1:25:19 ago on Fri 27 Mar 2020 06:27:17 PM MDT. -Installed Packages -Name : ipmctl -Version : 02.00.00.3446 -Release : 1.el7 -Architecture : x86_64 -Size : 65 k -Source : ipmctl-02.00.00.3446-1.el7.src.rpm -Repository : @System -From repo : jhli-ipmctl -Summary : Utility for managing Intel Optane DC persistent memory modules -URL : https://github.com/intel/ipmctl -License : BSD -Description : Utility for managing Intel Optane DC persistent memory modules - : Supports functionality to: - : Discover DCPMMs on the platform. - : Provision the platform memory configuration. - : View and update the firmware on DCPMMs. - : Configure data-at-rest security on DCPMMs. - : Monitor DCPMM health. - : Track performance of DCPMMs. - : Debug and troubleshoot DCPMMs. - -``` - -Step 2) Install the ipmctl package: - -``` -sudo dnf install ipmctl -``` - -Step 3) Review the help and man pages or continue to the [Basic Usage](../basic-usage.md) section of this user guide for a quick introduction and more information. - -``` -$ sudo ipmctl help -``` -{% endtab %} - -{% tab title="RHEL & CentOS" %} -The ipmctl package is available on CentOS, RHEL, and RHEL for SAP HANA v7.5 or later in the EPEL repository (Extra Packages for Enterprise Linux). - -Step 1) Verify the EPEL repository is active: - -``` -$ yum repolist -``` - -Example: - -``` -$ sudo yum repolist -repo id repo name status -epel/x86_64 Extra Packages for Enterprise Linux 7 - x86_64 13,217 -``` - -If the EPEL repository is not listed, install and activate it using: - -``` -$ sudo yum install epel-release -``` - -Step 2) Query the package repository to confirm that ipmctl is available: - -``` -sudo yum info ipmctl -``` - -Example: - -``` -$ sudo yum info ipmctl - -Available Packages -Name : ipmctl -Arch : x86_64 -Version : 01.00.00.3474 -Release : 2.el7 -Size : 70 k -Repo : epel/x86_64 -Summary : Utility for managing Intel Optane DC persistent memory modules -URL : https://github.com/intel/ipmctl -License : BSD -Description : Utility for managing Intel Optane DC persistent memory modules - : Supports functionality to: - : Discover DCPMMs on the platform. - : Provision the platform memory configuration. - : View and update the firmware on DCPMMs. - : Configure data-at-rest security on DCPMMs. - : Monitor DCPMM health. - : Track performance of DCPMMs. - : Debug and troubleshoot DCPMMs. -``` - -Step 3) Install the ipmctl package: - -``` -sudo yum install ipmctl -``` - -Step 4) Review the help and man pages or continue to the [Basic Usage](../basic-usage.md) section of this user guide for a quick introduction and more information. - -``` -$ sudo ipmctl help -``` -{% endtab %} - -{% tab title="SLES & OpenSUSE" %} -The ipmctl package is available in the default package repository on SUSE, OpenSUSE, and SUSE for SAP HANA 12.4 or later. - -Step 1) Query the package repository to confirm that ipmctl is available: - -``` -sudo zypper info ipmctl -``` - -Example: - -``` -$ sudo zypper info ipmctl - -Information for package ipmctl: -------------------------------- -Repository : SLES12-SP4-Updates -Name : ipmctl -Version : 01.00.00.3440-3.8.2 -Arch : x86_64 -Vendor : SUSE LLC -Support Level : Level 3 -Installed Size : 3.2 MiB -Installed : No -Status : not installed -Source package : ipmctl-01.00.00.3440-3.8.2.src -Summary : Utility for managing Intel Optane DC persistent memory modules -Description : - Utility for managing Intel Optane DC persistent memory modules - Supports functionality to: - * Discover PMMs on the platform. - * Provision the platform memory configuration. - * View and update the firmware on PMMs. - * Configure data-at-rest security on PMMs. - * Monitor PMM health. - * Track performance of PMMs. - * Debug and troubleshoot PMMs. -``` - -3\) Install the ipmctl package: - -``` -sudo zypper install ipmctl -``` - -4\) Review the help and man pages or continue to the [Basic Usage](../basic-usage.md) section of this user guide for a quick introduction and more information. - -``` -$ sudo ipmctl help -``` -{% endtab %} - -{% tab title="Ubuntu" %} -The ipmctl package for v02.00.00.xxxx or later is available in the Universe package repository on Ubuntu 19.10 (Eoan Ermine) or later. - -Step 1) Query the package repository to confirm that ipmctl is available: - -``` -apt update -apt search ipmctl -apt info ipmctl -``` - -Example: - -``` -$ apt search ipmctl -Sorting... Done -Full Text Search... Done -ipmctl/eoan 02.00.00.3474+really01.00.00.3469-1 amd64 - utility for configuring and managing Intel Optane DC persistent memory modules - -ipmctl-monitor/eoan 02.00.00.3474+really01.00.00.3469-1 amd64 - daemon for monitoring health and status of Intel Optane DC modules - -libipmctl-dev/eoan 02.00.00.3474+really01.00.00.3469-1 amd64 - library for managing Intel Optane DC persistent memory modules - devel - -libipmctl3/eoan 02.00.00.3474+really01.00.00.3469-1 amd64 - library for managing Intel Optane DC persistent memory modules - - -$ apt info ipmctl -Package: ipmctl -Version: 02.00.00.3474+really01.00.00.3469-1 -Priority: optional -Section: universe/admin -Origin: Ubuntu -Maintainer: Ubuntu Developers -Original-Maintainer: Adam Borowski -Bugs: https://bugs.launchpad.net/ubuntu/+filebug -Installed-Size: 105 kB -Depends: libc6 (>= 2.2.5), libipmctl3 (>= 02.00.00.3474+really01.00.00.3469) -Homepage: https://github.com/intel/ipmctl -Download-Size: 65.5 kB -APT-Sources: http://us-central1.gce.archive.ubuntu.com/ubuntu eoan/universe amd64 Packages -Description: utility for configuring and managing Intel Optane DC persistent memory modules - This package provides a CLI with the following functionality: - * Discover PMMs on the platform. - * Provision the platform memory configuration. - * View and update the firmware on PMMs. - * Configure data-at-rest security on PMMs. - * Monitor PMM health. - * Track performance of PMMs. - * Debug and troubleshoot PMMs. -``` - - - -Step 2) Install the ipmctl package: - -``` -sudo apt install ipmctl -``` - -Step 3) Review the help and man pages or continue to the [Basic Usage](../basic-usage.md) section of this user guide for a quick introduction and more information. - -``` -$ sudo ipmctl help -``` -{% endtab %} -{% endtabs %} - -### Using ipmctl - -Go to the [Basic Usage](../basic-usage.md) section of this user guide for more information. diff --git a/instrumentation/README.md b/instrumentation/README.md deleted file mode 100644 index 2a89eec..0000000 --- a/instrumentation/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# Instrumentation - -The instrumentation feature allows access to and monitoring of sensors on the persistent memory modules. Here are the articles in this section: - -{% content-ref url="show-sensor.md" %} -[show-sensor.md](show-sensor.md) -{% endcontent-ref %} - -{% content-ref url="change-sensor-settings.md" %} -[change-sensor-settings.md](change-sensor-settings.md) -{% endcontent-ref %} - -{% content-ref url="show-device-performance.md" %} -[show-device-performance.md](show-device-performance.md) -{% endcontent-ref %} - diff --git a/instrumentation/change-sensor-settings.md b/instrumentation/change-sensor-settings.md deleted file mode 100644 index 627b37f..0000000 --- a/instrumentation/change-sensor-settings.md +++ /dev/null @@ -1,32 +0,0 @@ -# Change Sensor Settings - -Changes the non-critical threshold or enabled state for one or more persistent memory module sensors. Use the command [Show Sensor](show-sensor.md) to view the current settings. - -``` -$ ipmctl set [OPTIONS] -sensor (SENSORS) [TARGETS] NonCriticalThreshold=(temperature) EnabledState=(0|1) -``` - -## **Sensors** - -* `MediaTemperature`: The current module media temperature in Celsius. Valid values: 0-2047. -* `ControllerTemperature`: The current module controller temperature in Celsius. Valid values 0-2047. -* `PercentageRemaining`: Remaining module life as a percentage value of factory expected life span. Valid values: 1-99. - -## **Targets** - -* `dimm (DimmIDs)`: Show the sensors on specific modules by supplying one or more comma-separated DimmIDs. The default is to display sensors for all manageable modules. - -## **Properties** - -* `NonCriticalThreshold`: The upper (for temperatures) or lower (for spare capacity) non-critical alarm threshold of the sensor. If the current value of the sensor is at or above for thermal, or below for capacity, the threshold value, then the sensor will indicate a "NonCritical" state. Temperatures may be specified in degrees Celsius to a precision of 1/16 a degree. -* `EnabledState`: Enable or disable the non-critical threshold alarm. One of: - * "0": Disable - * "1": Enable - -## **Examples** - -Change the media temperature threshold to 51 on the specified module and enable the alarm. - -``` -ipmctl set -sensor MediaTemperature –dimm 0x0001 NonCriticalThreshold=51 EnabledState=1 -``` diff --git a/instrumentation/show-device-performance.md b/instrumentation/show-device-performance.md deleted file mode 100644 index a5cc426..0000000 --- a/instrumentation/show-device-performance.md +++ /dev/null @@ -1,40 +0,0 @@ -# Show Device Performance - -Shows performance metrics for one or more persistent memory modules. - -``` -ipmctl show [OPTIONS] -performance [METRICS] [TARGETS] -``` - -## **Metrics** - -Shows output of a specific performance metric by supplying the metric name. See RETURN DATA for more information. One of: - -* `MediaReads`: Number of 64 byte reads from media on the module since last AC cycle. -* `MediaWrites`: Number of 64 byte writes to media on the module since last AC cycle. -* `ReadRequests`: Number of DDRT read transactions the module has serviced since last AC cycle. -* `WriteRequests`: Number of DDRT write transactions the module has serviced since last AC cycle. -* `TotalMediaReads`: Number of 64 byte reads from media on the module over its lifetime. -* `TotalMediaWrites`: Number of 64 byte writes to media on the module over its lifetime. -* `TotalReadRequests`: Number of DDRT read transactions the module has serviced over its lifetime. -* `TotalWriteRequests`: Number of DDRT write transactions the module has serviced over its lifetime. - -The default is to display all performance metrics. - -## **Targets** - -* `dimm (DimmIDs)`: Show the performance metrics of specific modules by supplying one or more comma-separated DimmIDs. The default is to display sensors for all manageable modules. - -## **Examples** - -Show all performance metrics for all modules in the server - -``` -$ ipmctl show -dimm -performance -``` - -Show the number of 64 byte reads since last AC cycle for all modules in the server - -``` -$ ipmctl show -dimm -performance MediaReads -``` diff --git a/instrumentation/show-sensor.md b/instrumentation/show-sensor.md deleted file mode 100644 index 47813fc..0000000 --- a/instrumentation/show-sensor.md +++ /dev/null @@ -1,68 +0,0 @@ -# Show Sensor - -Shows health statistics for one or more persistent memory modules. - -``` -$ ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS] -``` - -## **Sensors** - -* `Health`: The current module health as reported in the SMART log -* `MediaTemperature`: The current module media temperature in Celsius -* `ControllerTemperature`: The current module controller temperature in Celsius -* `PercentageRemaining`: Remaining module life as a percentage value of factory expected life span -* `LatchedDirtyShutdownCount`: The number of shutdowns without notification over the lifetime of the module -* `Unlatched DirtyShutdownCount`: The number of shutdowns without notification over the lifetime of the module. This counter is the same as LatchedDirtyShutdownCount except it will always be incremented on a dirty shutdown, even if Latch System Shutdown Status was not enabled. -* `PowerOnTime`: The total power-on time over the lifetime of the module -* `UpTime`: The total power-on time since the last power cycle of the module -* `PowerCycles`: The number of power cycles over the lifetime of the module -* `FwErrorCount`: The total number of firmware error log entries - -## **Targets** - -* `dimm (DimmIDs)`: Show only the sensors on specific modules by supplying the DIMM target and one or more comma-separated DimmIDs. The default is to display sensors for all manageable modules. - -## **Examples** - -Get all sensor information for all modules - -``` -$ ipmctl show -sensor -``` - -Show the media temperature sensor for the specified module - -``` -$ ipmctl show -sensor MediaTemperature -dimm 0x0011 -``` - -## **Return Data** - -* `DimmID`: The persistent memory module identifier -* `Type`: The sensor type. Refer to the Sensors list above -* `CurrentValue`: The current reading followed by the units of measurement (e.g., 57 °C or 25%) -* `CurrentState`: The current value in relation to the threshold settings (if supported). One of: - * `Unknown`: The state cannot be determined - * `Normal`: The current reading is within the normal range. This is the default when the sensor does not support thresholds - * `NonCritical`: The current reading is within the non-critical range. For example, an alarm threshold has been reached - * `Critical`: The current reading is within the critical range. For example, the firmware has begun throttling down traffic to the persistent memory module due to the temperature - * `Fatal`: The current reading is within the fatal range. For example, the firmware is shutting down the module due to the temperature -* `LowerThresholdNonCritical`: The threshold value below which the state is considered "NonCritical". -* `UpperThresholdNonCritical`: The threshold value at or above which the state is considered "NonCritical". -* `LowerThresholdCritical`: The threshold value below which the state is considered "Critical". -* `UpperThresholdCritical`: The threshold value at or above which the state is considered "Critical". -* `UpperThresholdFatal`: The threshold value at or above which the state is considered "Fatal". -* `SettableThresholds`: A list of user settable thresholds. Zero or more of: - * `LowerThresholdNonCritical` - * `UpperThresholdNonCritical` -* `SupportedThresholds`: A list of supported thresholds. Zero or more of: - * `LowerThresholdNonCritical` - * `UpperThresholdNonCritical` - * `LowerThresholdCritical` - * `UpperThresholdCritical` - * `UpperThresholdFatal` -* `EnabledState`: Whether the critical threshold alarm is enabled, disabled or not applicable. One of: - * 0: Disabled - * 1: Enabled - * N/A diff --git a/ipmctl-user-guide/instrumentation/show-sensor.md b/ipmctl-user-guide/instrumentation/show-sensor.md index 03ea84f..47813fc 100644 --- a/ipmctl-user-guide/instrumentation/show-sensor.md +++ b/ipmctl-user-guide/instrumentation/show-sensor.md @@ -3,7 +3,7 @@ Shows health statistics for one or more persistent memory modules. ``` -ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS] +$ ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS] ``` ## **Sensors** @@ -28,13 +28,13 @@ ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS] Get all sensor information for all modules ``` -$ sudo ipmctl show -sensor +$ ipmctl show -sensor ``` Show the media temperature sensor for the specified module ``` -$ sudo ipmctl show -sensor MediaTemperature -dimm 0x0011 +$ ipmctl show -sensor MediaTemperature -dimm 0x0011 ``` ## **Return Data** diff --git a/module-discovery/README.md b/module-discovery/README.md deleted file mode 100644 index c062ddd..0000000 --- a/module-discovery/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Module Discovery - -Persistent memory modules are uniquely referenced by one of two IDs: `DimmHandle` or `DimmUID`. Either ID may be used for commands that utilize the `-dimm` flag to perform operations on a single module or set of modules. The default is to operate on all modules, which does not require the use of `-dimm`. - -For example, each of the following are equivalent: - -``` - $ ipmctl show -d DimmHandle,DimmUID -dimm 8089-a2-1748-00000001 - $ ipmctl show -d DimmHandle,DimmUID -dimm 0x0001 - $ ipmctl show -d DimmHandle,DimmUID -dimm 1 -``` - -For simplicity, this document will primarily use `DimmUID`. - -The `-dimm` option accepts a single DimmUID or a comma separated list of DimmUIDs to filter the results. For example, the following `ipmctl show` command displays the `DimmHandle` and `DimmUID` properties for two modules with IDs of `0x0001` and `0x1001`: - -``` - $ ipmctl show -d DimmHandle,DimmUID -dimm 0x0001,0x1001 - - ---DimmID=0x0001--- - DimmHandle=0x0001 - DimmUID=8089-a2-1748-00000001 - ---DimmID=0x1001--- - DimmHandle=0x1001 - DimmUID=8089-a2-1748-00000002 -``` - -## DimmHandle - -The `DimmHandle` is equivalent to the `DimmUID` and is formatted as 0xABCD, where A, B, C, and D are defined as follows: - -* A = Socket -* B = Memory Controller -* C = Channel -* D = Slot - -## DimmUID - -The `DimmUID` is a unique identifier specific to each physical module. The unique identifier of an Intel Optane persistent memory module is formatted as VVVV-ML-MMYYSNSNSNSN or VVVV-SNSNSNSN (if the manufacturing information is not available) where: - -* VVVV = VendorID -* ML = Manufacturing Location -* MMYY = Manufacturing Date -* SNSNSNSN = Serial Number diff --git a/module-discovery/show-device.md b/module-discovery/show-device.md deleted file mode 100644 index cff4416..0000000 --- a/module-discovery/show-device.md +++ /dev/null @@ -1,135 +0,0 @@ -# Show Device - -Shows information about one or more Intel Optane DC memory modules. - -``` -ipmctl show [OPTIONS] -dimm [TARGETS] -``` - -## **Targets** - -* `-dimm (DimmIDs)`: Restricts output to specific modules by supplying the DIMM target and one or more comma-separated DimmIDs. The default is to display all DCPMMs. -* `-socket (SocketIDs)`: Restricts output to the modules installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets. - * If ACPI PMTT table is not present, then DDR4 memory will not be displayed in the filtered socket list. - -## **Examples** - -List a few key fields for each persistent memory module. - -``` -$ sudo ipmctl show -dimm - - DimmID | Capacity | HealthState | ActionRequired | LockState | FWVersion -============================================================================== - 0x0001 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x0011 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x0021 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x0101 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x0111 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x0121 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1001 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1011 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1021 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1101 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1111 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 - 0x1121 | 126.4 GiB | Healthy | 0 | Disabled | 01.02.00.5310 -``` - -List all properties for module 0x0001. - -``` -$ sudo ipmctl show -a -dimm 0x0001 ----DimmID=0x0001--- - Capacity=252.454 GiB - LockState=Disabled - S3Resume=Unknown - HealthState=Healthy - HealthStateReason=None - FWVersion=01.02.00.5417 - FWAPIVersion=01.15 - InterfaceFormatCode=0x0301 (Non-Energy Backed Byte Addressable) - ManageabilityState=Manageable - PopulationViolationState=Is in supported configuration. - PhysicalID=0x0026 - DimmHandle=0x0001 - DimmUID=8089-a2-1837-00000be8 - SocketID=0x0000 - MemControllerID=0x0000 - ChannelID=0x0000 - ChannelPos=1 - MemoryType=Logical Non-Volatile Device - Manufacturer=Intel - VendorID=0x8089 - DeviceID=0x5141 - RevisionID=0x0000 - SubsystemVendorID=0x8089 - SubsystemDeviceID=0x097a - SubsystemRevisionID=0x0018 - DeviceLocator=CPU1_DIMM_A2 - ManufacturingInfoValid=1 - ManufacturingLocation=0xa2 - ManufacturingDate=18-37 - SerialNumber=0x00000be8 - PartNumber=NMA1XBD256GQS - BankLabel=NODE 1 - DataWidth=64 b - TotalWidth=72 b - Speed=2666 MT/s - FormFactor=DIMM - ManufacturerID=0x8089 - ControllerRevisionID=B0, 0x0020 - MemoryCapacity=0.000 GiB - AppDirectCapacity=252.000 GiB - UnconfiguredCapacity=0.000 GiB - InaccessibleCapacity=0.454 GiB - ReservedCapacity=0.000 GiB - PackageSparingCapable=1 - PackageSparingEnabled=1 - PackageSparesAvailable=1 - IsNew=0 - ViralPolicy=0 - ViralState=0 - PeakPowerBudget=20000 mW - AvgPowerLimit=18000 mW - MaxAveragePowerLimit=18000 mW - LatchedLastShutdownStatus=PM ADR Command Received, DDRT Power Fail Command Received, PMIC 12V/DDRT 1.2V Power Loss (PLI), Controller's FW State Flush Complete, Write Data Flush Complete - UnlatchedLastShutdownStatus=PMIC 12V/DDRT 1.2V Power Loss (PLI), PM Warm Reset Received, Controller's FW State Flush Complete, Write Data Flush Complete, PM Idle Received - ThermalThrottleLossPercent=N/A - LastShutdownTime=Sat May 30 00:49:03 UTC 2020 - ModesSupported=Memory Mode, App Direct - SecurityCapabilities=Encryption, Erase - MasterPassphraseEnabled=0 - ConfigurationStatus=Valid - SKUViolation=0 - ARSStatus=Completed - OverwriteStatus=Unknown - AitDramEnabled=1 - BootStatus=Success - BootStatusRegister=0x00000004_985d00f0 - ErrorInjectionEnabled=0 - MediaTemperatureInjectionEnabled=0 - SoftwareTriggersEnabled=0 - SoftwareTriggersEnabledDetails=None - PoisonErrorInjectionsCounter=0 - PoisonErrorClearCounter=0 - MediaTemperatureInjectionsCounter=0 - SoftwareTriggersCounter=0 - MaxControllerTemperature=81 C - MaxMediaTemperature=78 C - MixedSKU=0 - -``` - -Retrieve specific properties for each module. - -``` -$ sudo ipmctl show -d HealthState,LockState -dimm 0x0001 - ----DimmID=0x0001--- - LockState=Disabled - HealthState=Healthy -``` - -## **Return Data** - -See the ipmctl-show-device(1) man page for a detailed explanation of all fields displayed by `ipmctl-show-device`. diff --git a/module-discovery/show-memory-resources.md b/module-discovery/show-memory-resources.md deleted file mode 100644 index d2f040f..0000000 --- a/module-discovery/show-memory-resources.md +++ /dev/null @@ -1,70 +0,0 @@ -# Show Memory Resources - -Show the total Intel Optane persistent memory resource allocation across the host server. - -``` -ipmctl show [OPTIONS] -memoryresources -``` - -## **Examples** - -### AppDirect - -The following shows persistent memory module resource allocation from a system configured in 100% AppDirect mode: - -``` -$ ipmctl show -memoryresources - MemoryType | DDR | PMemModule | Total -========================================================== - Volatile | 381.500 GiB | 0.000 GiB | 381.500 GiB - AppDirect | - | 3024.000 GiB | 3024.000 GiB - Cache | 0.000 GiB | - | 0.000 GiB - Inaccessible | 2.500 GiB | 5.452 GiB | 7.952 GiB - Physical | 384.000 GiB | 3029.452 GiB | 3413.452 GiB -``` - -### Human Readable Output - -Show persistent memory module resource allocation with human-readable output (MiB and TiB). - -``` -# ipmctl show -units MiB -memoryresources - MemoryType | DDR | PMemModule | Total -=================================================================== - Volatile | 390656.000 MiB | 0.000 MiB | 390656.000 MiB - AppDirect | - | 3096576.000 MiB | 3096576.000 MiB - Cache | 0.000 MiB | - | 0.000 MiB - Inaccessible | 2560.000 MiB | 5583.000 MiB | 8143.000 MiB - Physical | 393216.000 MiB | 3102159.000 MiB | 3495375.000 MiB - - - # ipmctl show -units TiB -memoryresources - MemoryType | DDR | PMemModule | Total -=================================================== - Volatile | 0.373 TiB | 0.000 TiB | 0.373 TiB - AppDirect | - | 2.953 TiB | 2.953 TiB - Cache | 0.000 TiB | - | 0.000 TiB - Inaccessible | 0.002 TiB | 0.005 TiB | 0.008 TiB - Physical | 0.375 TiB | 2.958 TiB | 3.333 TiB -``` - -## **Return Data** - -* `Volatile DDR Capacity`: Total DDR capacity that is used as volatile memory. -* `Volatile PMem module Capacity`: Total PMem module capacity that is used as volatile memory. -* `Total Volatile Capacity`: Total DDR and PMem module capacity that is used as volatile memory. -* `AppDirect PMem module Capacity`: Total PMem module capacity used as persistent memory. -* `Total AppDirect Capacity`: Total DDR and PMem module capacity used as persistent memory. -* `Cache DDR Capacity`: Total DDR capacity used as a cache for PMem modules. -* `Total Cache Capacity`: Total DDR capacity used as a cache for PMem modules. -* `Inaccessible DDR Capacity`: Total DDR capacity that is inaccessible. -* `InaccessibleCapacity`: Total system persistent memory capacity that is inaccessible due to any of: - * Platform configuration prevents accessing this capacity. For example, MemoryCapacity is configured but MemoryMode is not enabled by platform FW (current Memory Mode is 1LM). - * Capacity is inaccessible because it is not mapped into the System Physical Address space (SPA). This is usually due to platform firmware memory alignment requirements. - * Persistent capacity that is reserved. This capacity is the persistent memory partition capacity (rounded down for alignment) less any App Direct capacity. Reserved capacity typically results from a Memory Allocation Goal request that specified the Reserved property. This capacity is not mapped to System Physical Address space (SPA). - * Capacity that is unusable because it has not been configured. - * PMem module configured capacity but SKU prevents usage. For example, AppDirectCapacity but PMem module SKU is MemoryMode only. -* `Total Inaccessible Capacity`: Total capacity of DDR and PMem module that is inaccessible. -* `Physical DDR Capacity`: Total physical DDR capacity populated on the platform. -* `Physical PMem module Capacity`: Total physical PMem module capacity populated on the platform. -* `Total Physical Capacity`: Total physical capacity populated on the platform. diff --git a/module-discovery/show-socket.md b/module-discovery/show-socket.md deleted file mode 100644 index ac4cc3f..0000000 --- a/module-discovery/show-socket.md +++ /dev/null @@ -1,50 +0,0 @@ -# Show Socket - -Shows basic information about the physical processors in the host server. - -``` -ipmctl show [OPTIONS] -socket [TARGETS] -``` - -## **Targets** - -* `-socket (SocketIDs)`: Restricts output to the DIMMs installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets. - -## **Examples** - -Display information about all the processors. - -``` -# ipmctl show -socket - - SocketID | MappedMemoryLimit | TotalMappedMemory -================================================== - 0x0000 | 4608.0 GiB | 851.0 GiB - 0x0001 | 4608.0 GiB | 850.5 GiB -``` - -List all properties for socket 1. - -``` -# ipmctl show -socket 1 - - SocketID | MappedMemoryLimit | TotalMappedMemory -================================================== - 0x0001 | 4608.0 GiB | 850.5 GiB -``` - -Retrieve specific properties for each processor. - -``` -# ipmctl show -d MappedMemoryLimit -socket - ----SocketID=0x0000--- - MappedMemoryLimit=4608.0 GiB ----SocketID=0x0001--- - MappedMemoryLimit=4608.0 GiB -``` - -## **Return Data** - -* The `MappedMemoryLimit` is the maximum amount of memory that is allowed to be mapped into the system physical address space for this processor based on its SKU. -* `TotalMappedMemory` is the total amount of memory that is currently mapped into the system physical address space for this processor. diff --git a/module-discovery/show-system-capabilities.md b/module-discovery/show-system-capabilities.md deleted file mode 100644 index 80ae7af..0000000 --- a/module-discovery/show-system-capabilities.md +++ /dev/null @@ -1,38 +0,0 @@ -# Show System Capabilities - -Shows the platform supported Intel Optane DC persistent memory capabilities across the server. - -``` -ipmctl show [OPTIONS] -system -capabilities -``` - -## **Example** - -``` -$ ipmctl show -system -capabilities - -PlatformConfigSupported=1 -Alignment=1.0 GiB -AllowedVolatileMode=Memory Mode -CurrentVolatileMode=1LM -AllowedAppDirectMode=App Direct -``` - -## **Return Data** - -* `PlatformConfigSupported`: Whether the platform level configuration of persistent memory modules can be modified with the host software. One of: - * 0: Changes must be made in the BIOS. - * 1: The command Create Memory Allocation Goal is supported. -* `Alignment`: Capacity alignment requirement for all memory types as reported by the BIOS. -* `AllowedVolatileMode`: The volatile mode allowed as determined by BIOS setup. One of: - * 1LM: One-level volatile mode. All memory resources in the platform are independently accessible, and not captive of the other resources. - * Memory Mode: Modules act as system memory under the control of the operating system. In Memory Mode, any DDR in the platform will act as a cache working in conjunction with the persistent memory modules. - * Unknown: The allowed volatile mode cannot be determined. -* `CurrentVolatileMode`: The current volatile mode. One of: - * 1LM: One-level volatile mode. All memory resources in the platform are independently accessible, and not captive of the other resources. - * Memory Mode: Modules act as system memory under the control of the operating system. In Memory Mode, any DDR in the platform will act as a cache working in conjunction with the persistent memory modules. - * Unknown: The current volatile mode cannot be determined. -* `AllowedAppDirectMode`: The App Direct mode allowed as determined by BIOS setup. One of: - * Disabled: App Direct support is currently disabled by the BIOS. - * App Direct: App Direct support is currently enabled by the BIOS. - * Unknown: The current App Direct support cannot be determined. diff --git a/module-discovery/show-topology.md b/module-discovery/show-topology.md deleted file mode 100644 index 2c1cbc8..0000000 --- a/module-discovery/show-topology.md +++ /dev/null @@ -1,78 +0,0 @@ -# Show Topology - -Shows the topology of DDR and persistent memory modules installed in the host server. - -``` -ipmctl show [OPTIONS] -topology [TARGETS] -``` - -## **Targets** - -* `-dimm [(DimmIDs)]`: Restricts output to specific DIMMs by optionally supplying the DIMM target and one or more comma-separated DIMM identifiers. The default is to display all DIMMs. -* `-socket (SocketIDs)`: Restricts output to the DIMMs installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets. - * If ACPI PMTT table is not present, then DDR4 memory will not be displayed in the filtered socket list. - -## **Examples** - -Display all DDR and Optane persistent memory modules installed in the system - -``` -$ ipmctl show -topology - - DimmID | MemoryType | Capacity | PhysicalID| DeviceLocator -============================================================================== - 0x0001 | Logical Non-Volatile Device | 126.3 GiB | 0x0028 | CPU1_DIMM_A2 - 0x0011 | Logical Non-Volatile Device | 126.3 GiB | 0x002c | CPU1_DIMM_B2 - 0x0021 | Logical Non-Volatile Device | 126.3 GiB | 0x0030 | CPU1_DIMM_C2 - 0x0101 | Logical Non-Volatile Device | 126.3 GiB | 0x0036 | CPU1_DIMM_D2 - 0x0111 | Logical Non-Volatile Device | 126.3 GiB | 0x003a | CPU1_DIMM_E2 - 0x0121 | Logical Non-Volatile Device | 126.3 GiB | 0x003e | CPU1_DIMM_F2 - 0x1001 | Logical Non-Volatile Device | 126.3 GiB | 0x0044 | CPU2_DIMM_A2 - 0x1011 | Logical Non-Volatile Device | 126.3 GiB | 0x0048 | CPU2_DIMM_B2 - 0x1021 | Logical Non-Volatile Device | 126.3 GiB | 0x004c | CPU2_DIMM_C2 - 0x1101 | Logical Non-Volatile Device | 126.3 GiB | 0x0052 | CPU2_DIMM_D2 - 0x1111 | Logical Non-Volatile Device | 126.3 GiB | 0x0056 | CPU2_DIMM_E2 - 0x1121 | Logical Non-Volatile Device | 126.3 GiB | 0x005a | CPU2_DIMM_F2 - N/A | DDR4 | 16.0 GiB | 0x0026 | CPU1_DIMM_A1 - N/A | DDR4 | 16.0 GiB | 0x002a | CPU1_DIMM_B1 - N/A | DDR4 | 16.0 GiB | 0x002e | CPU1_DIMM_C1 - N/A | DDR4 | 16.0 GiB | 0x0034 | CPU1_DIMM_D1 - N/A | DDR4 | 16.0 GiB | 0x0038 | CPU1_DIMM_E1 - N/A | DDR4 | 16.0 GiB | 0x003c | CPU1_DIMM_F1 - N/A | DDR4 | 16.0 GiB | 0x0042 | CPU2_DIMM_A1 - N/A | DDR4 | 16.0 GiB | 0x0046 | CPU2_DIMM_B1 - N/A | DDR4 | 16.0 GiB | 0x004a | CPU2_DIMM_C1 - N/A | DDR4 | 16.0 GiB | 0x0050 | CPU2_DIMM_D1 - N/A | DDR4 | 16.0 GiB | 0x0054 | CPU2_DIMM_E1 - N/A | DDR4 | 16.0 GiB | 0x0058 | CPU2_DIMM_F1 -``` - -Display all DDR and Optane persistent memory installed in CPU Socket 0 - -``` -# ipmctl show -topology -socket 0 - DimmID | MemoryType | Capacity | PhysicalID| DeviceLocator -================================================================================ - 0x0001 | Logical Non-Volatile Device | 252.438 GiB | 0x0026 | CPU1_DIMM_A2 - 0x0011 | Logical Non-Volatile Device | 252.438 GiB | 0x0028 | CPU1_DIMM_B2 - 0x0021 | Logical Non-Volatile Device | 252.438 GiB | 0x002a | CPU1_DIMM_C2 - 0x0101 | Logical Non-Volatile Device | 252.438 GiB | 0x002c | CPU1_DIMM_D2 - 0x0111 | Logical Non-Volatile Device | 252.438 GiB | 0x002e | CPU1_DIMM_E2 - 0x0121 | Logical Non-Volatile Device | 252.438 GiB | 0x0030 | CPU1_DIMM_F2 - N/A | DDR4 | 32.000 GiB | 0x0025 | CPU1_DIMM_A1 - N/A | DDR4 | 32.000 GiB | 0x0027 | CPU1_DIMM_B1 - N/A | DDR4 | 32.000 GiB | 0x0029 | CPU1_DIMM_C1 - N/A | DDR4 | 32.000 GiB | 0x002b | CPU1_DIMM_D1 - N/A | DDR4 | 32.000 GiB | 0x002d | CPU1_DIMM_E1 - N/A | DDR4 | 32.000 GiB | 0x002f | CPU1_DIMM_F1 -``` - - Display information for Optane persistent memory modules 0x0001 and 0x101 - -``` -# ipmctl show -topology -dimm 0x0001,0x0101 - DimmID | MemoryType | Capacity | PhysicalID| DeviceLocator -================================================================================ - 0x0001 | Logical Non-Volatile Device | 252.438 GiB | 0x0026 | CPU1_DIMM_A2 - 0x0101 | Logical Non-Volatile Device | 252.438 GiB | 0x002c | CPU1_DIMM_D2 -``` diff --git a/provisioning/README.md b/provisioning/README.md deleted file mode 100644 index 1a63343..0000000 --- a/provisioning/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Provisioning - -Intel Optane persistent memory modules can be provisioned into three different operating modes: - -* **App Direct**: Persistent memory exposed as block devices to the operating system and DRAM is used as main memory. -* **Memory Mode**: Uses persistent memory as main memory and DRAM is used as a cache not explicitly managed by the operating system. Data placement is managed by the memory controller. -* **Mixed Mode**: A combination of App Direct and Memory Modes where a percentage of total memory is allocated for Memory Mode, and the rest is used for App Direct. - -You can learn more about each operating mode and which is right for your application in this [video](https://www.youtube.com/watch?v=gqo3gty-R4s). - -To learn more about how ipmctl works with the hardware see the [Intel® Optane™ Persistent Memory OS Provisioning Specification](https://cdrdv2.intel.com/v1/dl/getContent/634430), which describes all the firmware interface commands used for this operation. - -{% hint style="warning" %} -**WARNING:** Provisioning or changing modes may result in data loss. Data should be backed up to other storage before executing this command. - -Changing a memory allocation goal modifies how the platform firmware maps persistent memory in the system address space which may result in data loss or inaccessible data, but does not explicitly delete or modify user data found in persistent memory. -{% endhint %} diff --git a/provisioning/concepts.md b/provisioning/concepts.md deleted file mode 100644 index 72b879b..0000000 --- a/provisioning/concepts.md +++ /dev/null @@ -1,15 +0,0 @@ -# Concepts - -To provision or change modes, create a **goal configuration** that will take effect after a system reboot. Goals specify which operating mode the modules are to be used in. The goal is stored on the persistent memory modules for the BIOS to read on the next reboot. - -A **region** is a grouping of one or more persistent memory modules. Regions can be created as either non-interleaved, meaning one region per persistent memory module, or interleaved, which creates one large region over all modules in a CPU socket. Regions cannot be created across CPU sockets. - -![Non-interleaved](https://user-images.githubusercontent.com/21182867/59884137-2a7b8580-936c-11e9-8f6a-e16aa3efcb19.png) ![Fully interleaved](https://user-images.githubusercontent.com/21182867/59884182-5991f700-936c-11e9-88dc-5f483f1d433a.png) - -Many users choose to have one fully-interleaved set across their memory modules because this allows for increased bandwidth performance. Regions can be created or modified using the `ipmctl -create -goal` command, or via an option in the BIOS. - -Regions can be divided up into one or more **namespaces**. A namespace defines a contiguously addressed range of non-volatile memory conceptually similar to a disk partition, or an NVM Express namespace. A namespace is the unit of persistent memory storage that appears in the /dev directory as a device that can be used for input and output or partitioned further. Intel recommends using the [ndctl utility](https://docs.pmem.io/ndctl-users-guide) for creating namespaces in Linux and the native PowerShell commands in Microsoft Windows. Namespaces can further be partitioned using commands such as fdisk and parted on Linux or native Microsoft Windows commands and utilities. - -![Namespaces](https://user-images.githubusercontent.com/21182867/59884230-94942a80-936c-11e9-8b66-ab911a240fb0.png) - -A **label** is similar to a partition table. Intel persistent memory modules support labels that allow regions to be further divided into namespaces. A label contains metadata stored on a persistent memory module. diff --git a/provisioning/create-memory-allocation-goal.md b/provisioning/create-memory-allocation-goal.md deleted file mode 100644 index a0909f8..0000000 --- a/provisioning/create-memory-allocation-goal.md +++ /dev/null @@ -1,67 +0,0 @@ -# Create Memory Allocation Goal - -``` -ipmctl create [OPTIONS] -goal [TARGETS] [PROPERTIES] -``` - -The `ipmctl create -goal` command has many options. A complete list of options can be shown by executing `ipmctl create -help`, or reading the `ipmctl(1)` man page. Once a goal is created, it does not take effect until the system is rebooted. After a reboot, the BIOS configures the requested goal and clears the goal. - -## **Targets** - -* `-dimm [(DimmIDs)]`: Creates a memory allocation goal on specific persistent memory modules by optionally supplying one or more comma-separated DimmIDs. The default is to configure all manageable modules on all sockets. -* `-socket (SocketIds)`: Creates a memory allocation goal on specific modules by supplying one or more comma-separated SocketIds. The default is to configure all manageable modules on all sockets. - -## **Properties** - -* `MemoryMode`: Percentage of the total capacity to use in Memory Mode (0-100). Default=0. -* `PersistentMemoryType`: If MemoryMode is not 100%, specify the type of persistent memory to create: - * `AppDirect`: (default) Create App Direct capacity utilizing hardware interleaving across the requested modules. - * `AppDirectNotInterleaved`: Create App Direct capacity that is not interleaved with any other modules. -* `NamespaceLabelVersion`: The version of the namespace label storage area (LSA) index block: - * `1.2`: (default) Defined in UEFI 2.7a - sections 13.19 - * `1.1`: Legacy 1.1 namespace label support -* `Reserved`: Reserve a percentage (0-100) of the requested persistent memory App Direct capacity that will not be mapped into the system physical address space and will be presented as `ReservedCapacity` with Show Device and Show Memory Resources commands. - -## **Limitations** - -* The caller must have appropriate privileges. -* The specified modules must be manageable by the host software and must all have the same SKU. -* Existing memory allocation goals that have not been applied and any namespaces associated with the requested modules must be deleted before running this command. - -## Examples - -Configures all the PMem module capacity in Memory Mode: - -``` -ipmctl create -goal MemoryMode=100 -``` - -Configures all the PMem module capacity as App Direct: - -``` -ipmctl create -goal PersistentMemoryType=AppDirect -``` - -Configures the capacity on each PMem module with 20% of the capacity in Memory Mode and the remaining as App Direct capacity that does not use hardware interleaving: - -``` -ipmctl create -goal MemoryMode=20 PersistentMemoryType=AppDirectNotInterleaved -``` - -Configures the PMem module capacity across the entire system with 50% in AppDirect (Interleaved) and 50% reserved: - -``` -ipmctl create -goal PersistentMemoryType=AppDirect Reserved=50 -``` - -Configures the PMem module capacity across the entire system with 25% of the capacity in Memory Mode, 25% reserved, and the remaining 50% as App Direct. Configures the PMem module capacity across the entire system with 25% of the capacity in Memory Mode and the remaining 75% as App Direct. - -``` -ipmctl create -goal MemoryMode=25 PersistentMemoryType=AppDirect Reserved=25 -``` - -Create an Interleaved AppDirect goal using all modules in Socket0: - -``` -$ ipmctl create -goal -socket 0x0000 PersistentMemoryType=AppDirect -``` diff --git a/provisioning/delete-memory-allocation-goal.md b/provisioning/delete-memory-allocation-goal.md deleted file mode 100644 index f6f907a..0000000 --- a/provisioning/delete-memory-allocation-goal.md +++ /dev/null @@ -1,18 +0,0 @@ -# Delete Memory Allocation Goal - -Deletes the memory allocation goal from one or more persistent memory modules. This command deletes a memory allocation goal request that has not yet been processed by the BIOS. - -``` -$ ipmctl delete [OPTIONS] -goal [TARGETS] -``` - -## **Targets** - -* `-dimm [(DimmIDs)]`: Restricts output to specific DIMMs by optionally supplying the DIMM target and one or more comma-separated DIMM identifiers. The default is to display all manageable modules. -* `-socket (SocketIDs)`: Restricts output to the DIMMs installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets. - -## **Example** - -``` -$ ipmctl delete -goal -``` diff --git a/provisioning/dump-memory-allocation-settings.md b/provisioning/dump-memory-allocation-settings.md deleted file mode 100644 index e4089b1..0000000 --- a/provisioning/dump-memory-allocation-settings.md +++ /dev/null @@ -1,17 +0,0 @@ -# Dump Memory Allocation Settings - -Store the currently configured memory allocation settings for all persistent memory modules in the system to a file in order to replicate the configuration elsewhere. Apply the stored memory allocation settings using the command [Load Memory Allocation Goal](load-memory-allocation-goal.md) - -``` -$ ipmctl dump [OPTIONS] -destination (path) -system -config -``` - -## **Example** - -``` -$ ipmctl dump -destination config.txt -system -config -``` - -## **Limitations** - -Only memory allocation settings for manageable persistent memory modules that have been successfully applied by the BIOS are stored in the file. Unconfigured modules are not included, nor are memory allocation goals that have not been applied. diff --git a/provisioning/load-memory-allocation-goal.md b/provisioning/load-memory-allocation-goal.md deleted file mode 100644 index 5e32f7e..0000000 --- a/provisioning/load-memory-allocation-goal.md +++ /dev/null @@ -1,44 +0,0 @@ -# Load Memory Allocation Goal - -Load a memory allocation goal from a file collected by the [dump command](dump-memory-allocation-settings.md) onto one or more persistent memory modules. - -{% hint style="warning" %} -**WARNING:** Provisioning or changing modes may result in data loss. Data should be backed up to other storage before executing this command. - -Changing a memory allocation goal modifies how the platform firmware maps persistent memory in the system address space (SPA), which may result in data loss or inaccessible data, but does not explicitly delete or modify user data found in persistent memory. -{% endhint %} - -``` -$ ipmctl load [OPTIONS] -source (path) -goal [TARGETS] -``` - -## **Targets** - -* `-dimm [(DimmIDs)]`: Restricts output to specific DIMMs by optionally supplying the DIMM target and one or more comma-separated DIMM identifiers. The default is to display all manageable persistent memory modules. -* `-socket (SocketIDs)`: Restricts output to the DIMMs installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets. - -## **Examples** - -Load the configuration settings stored in "config.txt" onto all modules in the system as a memory allocation goal to be applied by the BIOS on the next reboot. - -``` -$ ipmctl load -source config.txt -goal -``` - -Load the configuration settings stored in "config.txt" onto modules 1, 2, and 3 in the system as a memory allocation goal to be applied by the BIOS on the next reboot. - -``` -$ ipmctl load -source config.txt -goal -dimm 1,2,3 -``` - -Load the configuration settings stored in "config.txt" onto all manageable modules on sockets 1 and 2 as a memory allocation goal to be applied by the BIOS on the next reboot. - -``` -$ ipmctl load -source config.txt -goal -socket 1,2 -``` - -## **Limitations** - -* The caller must have appropriate privileges. -* The specified modules must be manageable by the host software and must all have the same SKU. -* Existing memory allocation goals that have not been applied and any namespaces associated with the requested modules must be deleted before running this command. diff --git a/provisioning/provision-app-direct.md b/provisioning/provision-app-direct.md deleted file mode 100644 index 93ec51d..0000000 --- a/provisioning/provision-app-direct.md +++ /dev/null @@ -1,29 +0,0 @@ -# Provision App Direct - -Creates a memory allocation goal for App Direct in either one fully interleaved region, or non-interleaved, meaning one region per module. - -## **Examples** - -Configures all the PMem module capacity in **** AppDirect mode with all modules in an interleaved set: - -``` -$ ipmctl create -goal PersistentMemoryType=AppDirect -``` - -Configures all the PMem module capacity in **** AppDirect mode with all modules in an interleaved set: - -``` -$ ipmctl create -goal PersistentMemoryType=AppDirectNotInterleaved -``` - -Configures the PMem module capacity across the entire system with 50% in AppDirect (Interleaved) and 50% reserved: - -``` -ipmctl create -goal PersistentMemoryType=AppDirect Reserved=50 -``` - -Create an Interleaved AppDirect goal using all modules in Socket0: - -``` -$ ipmctl create -goal -socket 0x0000 PersistentMemoryType=AppDirect -``` diff --git a/provisioning/provision-memory-mode.md b/provisioning/provision-memory-mode.md deleted file mode 100644 index e5a8f75..0000000 --- a/provisioning/provision-memory-mode.md +++ /dev/null @@ -1,13 +0,0 @@ -# Provision Memory Mode - -Creates a memory allocation goal for a percentage (0-100) of total capacity to be used in Memory Mode and the rest to be either reserved or used for App Direct mode. - -## **Examples** - -Configures all the PMem module capacity in Memory Mode. - -``` -$ ipmctl create -goal MemoryMode=100 -``` - -By default, if a goal is set for any percentage less than 100%, the remaining capacity will be configured to App Direct mode. See the [Mixed Mode](provision-mixed-mode.md) section for examples. diff --git a/provisioning/provision-mixed-mode.md b/provisioning/provision-mixed-mode.md deleted file mode 100644 index 7556837..0000000 --- a/provisioning/provision-mixed-mode.md +++ /dev/null @@ -1,17 +0,0 @@ -# Provision Mixed Mode - -Creates a memory allocation goal for a percentage (0-100) of total capacity to be used in Memory Mode and the rest to be either reserved or used for App Direct mode. - -## **Examples** - -Configure 20% of the available capacity on each persistent memory module to be in Memory Mode and the remaining will be not-interleaved App Direct. - -``` -$ ipmctl create -goal MemoryMode=20 PersistentMemoryType=AppDirectNotInterleaved -``` - -Configure the persistent memory modules with 25% of the capacity in Memory Mode, 25% reserved, and the remaining 50% as interleaved App Direct by default. - -``` -$ ipmctl create -goal MemoryMode=25 Reserved=25 -``` diff --git a/provisioning/show-memory-allocation-goal.md b/provisioning/show-memory-allocation-goal.md deleted file mode 100644 index 531e73a..0000000 --- a/provisioning/show-memory-allocation-goal.md +++ /dev/null @@ -1,37 +0,0 @@ -# Show Memory Allocation Goal - -Shows the memory allocation goal on one or more persistent memory modules. Once the goal is successfully applied by the BIOS, it is no longer displayed. Use the command Show Memory Resources to view the system-wide memory resources. - -``` -ipmctl show [OPTIONS] -goal [TARGETS] [PROPERTIES] -``` - -**Targets** - -* `-dimm [(DimmIDs)]`: Restricts output to specific DIMMs by optionally supplying the DIMM target and one or more comma-separated DIMM identifiers. The default is to display all manageable persistent memory modules with memory allocation goals. -* `-socket (SocketIDs)`: Restricts output to the DIMMs installed on specific sockets by supplying the socket target and one or more comma-separated socket identifiers. The default is to display all sockets with memory allocation goals. - -**Examples** - -``` -$ ipmctl show -goal -``` - -``` -$ ipmctl show -goal -socket 1 -``` - -**Return Data** - -* `SocketID`: The processor socket identifier where the module is installed. -* `DimmID`: The persistent memory module identifier. -* `MemorySize`: The module capacity that will be configured in Memory Mode. -* `AppDirect1Size`: The persistent module capacity that will be configured as the first App Direct interleave set if applicable. -* `AppDirect2Size`: The persistent memory module capacity that will be configured as the second App Direct interleave set if applicable. -* `Status`: The status of the memory allocation goal. One of: - * `Unknown`: The status cannot be determined. - * `New`: A reboot is required for the memory allocation goal to be processed by the BIOS. - * `Failed - Bad Request`: The BIOS failed to process the memory allocation goal because it was invalid. - * `Failed - Not enough resources`: There were not enough resources for the BIOS to process the memory allocation goal. - * `Failed - Firmware error`: The BIOS failed to process the memory allocation goal due to a firmware error. - * `Failed - Unknown`: The BIOS failed to process the memory allocation goal due to an unknown error. diff --git a/support-and-maintenance/README.md b/support-and-maintenance/README.md deleted file mode 100644 index c5cea2e..0000000 --- a/support-and-maintenance/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Support and Maintenance - -The ipmctl utility provides support and maintenance commands. Here are the articles in this section: - -{% content-ref url="show-events.md" %} -[show-events.md](show-events.md) -{% endcontent-ref %} - -{% content-ref url="version-and-firmware.md" %} -[version-and-firmware.md](version-and-firmware.md) -{% endcontent-ref %} - diff --git a/support-and-maintenance/show-events.md b/support-and-maintenance/show-events.md deleted file mode 100644 index 86cd314..0000000 --- a/support-and-maintenance/show-events.md +++ /dev/null @@ -1,58 +0,0 @@ -# Show Events - -Shows persistent memory module related events. The options, targets, and properties can be used to filter the events. If no filters are provided, the default is to display up to 50 events. Refer to the Event Log Specification for detailed information about events. - -``` -ipmctl show [OPTIONS] -event [TARGETS] [PROPERTIES] -``` - -## **Targets** - -* `-dimm [(DimmID)]`: Filter output to events on a specific module by optionally supplying the DIMM target and one or more DimmID. - -## **Properties** - -* `Category`: Filters output to events of a specific category. One of: - * `Diag`: Filters output to diagnostic events. - * `FW`: Filters output to FW consistency diagnostic test events. - * `Config`: Filters output to platform config diagnostic test events. - * `PM`: Filters output to PM meta data diagnostic test events. - * `Quick`: Filters output to quick diagnostic test events. - * `Security`: Filters output to security diagnostic test events. - * `Health`: Filters output to device health events. - * `Mgmt`: Filters output to management software generated events. -* `Severity`: Filters output of events based on the severity of the event. One of: - * `Info`: (Default) Shows informational, warning, and error severity events. - * `Warning`: Shows warning and error events. - * `Error`: Shows error events. -* `ActionRequired`: Filters output to events that require corrective action or acknowledgment. - * `0`: Filters output to only show non-ActionRequired events. - * `1`: Filters output to only show ActionRequired events. -* `Count`: Filters output of events limited to the specified count, starting with the most recent. Count may be a value from 1 to 2,147,483,647. Default = 50. - -## **Examples** - -Display the 50 most recent events. - -``` -$ sudo ipmctl show -event -``` - -Show the 10 most recent error events. With the exception that this call limits the output to 10, this is equivalent to calling `ipmctl show -error`. - -``` -$ sudo ipmctl show -event count=10 severity=error -``` - -## **Return Data** - -This command displays a table with a row for each event matching the provided filters, showing most recent first. - -* `Time`: Time of the event in the format MM:dd:yyyy:hh:mm:ss. -* `EventID`: The event identifier -* `Severity`: The severity of the event -* `ActionRequired` A flag indicating that the event requires corrective action or acknowledgment. One of: - * `0`: A action is not required. - * `1`: An action is required. -* `Code`: The event code defined by the SW Event Log specification -* `Message`: The event message diff --git a/support-and-maintenance/version-and-firmware.md b/support-and-maintenance/version-and-firmware.md deleted file mode 100644 index 6cb9571..0000000 --- a/support-and-maintenance/version-and-firmware.md +++ /dev/null @@ -1,45 +0,0 @@ -# Version and Firmware - -## Get Version - -Shows the persistent memory module host software versions - -``` -ipmctl version -``` - -## Show Device Firmware - -Shows detailed information about the firmware on one or more modules - -``` -$ ipmctl show [OPTIONS] -firmware [TARGETS] -``` - -## Update Firmware - -Updates the firmware on one or more modules - -``` -$ ipmctl load [OPTIONS] -source (path) -dimm (DimmIds) [TARGETS] -``` - -> NOTE: If Address Range Scrub (ARS) is in progress on any target DIMM, an attempt will be made to abort ARS and the proceed with the firmware update. -> -> NOTE: A reboot is required to activate the updated firmware image and is recommended to ensure ARS runs to completion. - -### **Examples** - -Update the firmware on all modules in the system to the image in sourcefile.pkg on the next power cycle. - -``` -$ sudo ipmctl load -source sourcefile.pkg -dimm -``` - -Check the firmware image in sourcefile.pkg and retrieve the version. - -``` -$ sudo ipmctl load -examine -source sourcefile.pkg -dimm -``` - -> NOTE: Once a firmware image is staged for execution, a power cycle is required before another firmware image of the same type (production or debug) can be staged for execution using this command.