diff --git a/ipmctl-user-guide/.gitbook/assets/capture.PNG b/ipmctl-user-guide/.gitbook/assets/capture.PNG new file mode 100644 index 0000000..c0284a4 Binary files /dev/null and b/ipmctl-user-guide/.gitbook/assets/capture.PNG differ diff --git a/ipmctl-user-guide/.gitbook/assets/image.png b/ipmctl-user-guide/.gitbook/assets/image.png new file mode 100644 index 0000000..3d503a8 Binary files /dev/null and b/ipmctl-user-guide/.gitbook/assets/image.png differ diff --git a/ipmctl-user-guide/README.md b/ipmctl-user-guide/README.md index b135384..45b4f67 100644 --- a/ipmctl-user-guide/README.md +++ b/ipmctl-user-guide/README.md @@ -2,26 +2,27 @@ ## Introduction -`ipmctl` is an open source utility created and maintained by Intel to manage Intel® Optane™ DC persistent memory modules. `ipmctl`, which works in both Linux and Windows, is a vendor specific tool, meaning it is not able to be used for managing NVDIMMs from vendors other than Intel. 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™ DC memory modules simply as _modules_ or the _persistent memory modules_. +`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_. `ipmctl` refers to the following interface components: -* `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. +* `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. Functionality includes: -* Discover Intel Optane DC memory modules on the platform +* Discover Intel Optane persistent memory modules on the platform * Provision the platform memory configuration - * Learn more about operating modes in this [video](link) + * 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 -Architecture Diagram: +Architecture Diagram: -![](../.gitbook/assets/capture.PNG) +![](.gitbook/assets/capture.PNG) +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/ipmctl-user-guide/SUMMARY.md b/ipmctl-user-guide/SUMMARY.md new file mode 100644 index 0000000..d146f7e --- /dev/null +++ b/ipmctl-user-guide/SUMMARY.md @@ -0,0 +1,40 @@ +# 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) diff --git a/ipmctl-user-guide/basic-usage.md b/ipmctl-user-guide/basic-usage.md index 2a9df0a..68618f9 100644 --- a/ipmctl-user-guide/basic-usage.md +++ b/ipmctl-user-guide/basic-usage.md @@ -1,10 +1,10 @@ # 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](../getting-started-guide/what-is-ndctl.md). +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: -```text +``` ipmctl COMMAND [OPTIONS] [TARGETS] [PROPERTIES] ``` @@ -12,14 +12,18 @@ Items in square brackets `[..]` are optional. Options, targets, and property val `ipmctl` commands include: +* create +* delete +* dump * help * load * set -* delete * show -* create -* dump * 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/ipmctl-user-guide/debug/README.md b/ipmctl-user-guide/debug/README.md index 66d280a..35eaf0b 100644 --- a/ipmctl-user-guide/debug/README.md +++ b/ipmctl-user-guide/debug/README.md @@ -1,2 +1,36 @@ # 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/ipmctl-user-guide/debug/delete-device-platform-configuration-data.md b/ipmctl-user-guide/debug/delete-device-platform-configuration-data.md index 84bac2e..ac98b73 100644 --- a/ipmctl-user-guide/debug/delete-device-platform-configuration-data.md +++ b/ipmctl-user-guide/debug/delete-device-platform-configuration-data.md @@ -4,24 +4,22 @@ When `Config` is specified, the `Current`, `Input Data Size`, `Output Data Size` > Warning: This command may result in data loss. Data should be backed up to other storage before executing this command. -```text +``` ipmctl delete [OPTIONS] -dimm (DimmIds) -pcd (Config) ``` -### **Targets** +## **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** +## **Examples** Clear the Cin, Cout, Ccur tables from all manageable modules -```text -$ delete -dimm -pcd Config -``` - -### **Limitations** +
$ sudo ipmctl delete -dimm -pcd Config
+
-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. +## **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/ipmctl-user-guide/debug/dump-debug-log.md b/ipmctl-user-guide/debug/dump-debug-log.md index f6041d0..574c0f3 100644 --- a/ipmctl-user-guide/debug/dump-debug-log.md +++ b/ipmctl-user-guide/debug/dump-debug-log.md @@ -2,33 +2,31 @@ Dumps encoded firmware debug logs from specified persistent memory modules and optionally decodes to human readable text. -```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. +## **Targets** - > file\_prefix\_Uid\_Handle\_logsource.\[bin,txt\] +* `-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** +## **Examples** Dump and decode the debug log from persistent memory modules 0x0001 and 0x0011 using the dictionary file. -```text +``` $ sudo ipmctl dump -destination file_prefix -dict nlog_dict.txt -debug -dimm 0x0001,0x0011 ``` -### **Sample Output** +## **Sample Output** -```text +``` 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/ipmctl-user-guide/debug/inject-error.md b/ipmctl-user-guide/debug/inject-error.md index dd16b64..d28def8 100644 --- a/ipmctl-user-guide/debug/inject-error.md +++ b/ipmctl-user-guide/debug/inject-error.md @@ -2,96 +2,133 @@ Injects an error or clears a previously injected error on one or more persistent memory modules for testing purposes. -```text +{% 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** +## **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** +## **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. - +* `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. + * `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. + > 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. +* `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** +## **Examples** Set the media temperature on all manageable modules to 100 degrees Celsius. -```text +``` $ sudo ipmctl set -dimm Temperature=100 ``` Clear the injected media temperature on all manageable modules -```text -$ sudo ipmctl set -dimm Clear=1 Temperature=1 +``` +$ sudo ipmctl set -dimm Temperature=1 Clear=1 ``` -Poison address 0x10000100 on module 1234 +Poison address 0x10000100 on module 0x0001 -```text -$ sudo ipmctl set -dimm 1234 Poison=0x10000200 +``` +$ sudo ipmctl set -dimm 0x0001 Poison=0x10000200 ``` -Clear the injected poison of address 0x10000200 on module 1234. +Clear the injected poison of address 0x10000200 on module 0x0001. -```text -$ sudo ipmctl set -dimm 1234 Poison=0x10000200 Clear=1 +``` +$ sudo ipmctl set -dimm 0x0001 Poison=0x10000200 Clear=1 ``` Trigger an artificial package sparing on all manageable modules. -```text +``` $ 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%. -```text +``` $ 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. -```text +``` $ sudo ipmctl set -dimm PercentageRemaining=10 Clear=1 ``` -Trigger an artificial ADR failure on all manageable modules, which will result in a dirty shutdown on each module on the next reboot. +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. -```text +``` $ 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/ipmctl-user-guide/debug/run-diagnostic.md b/ipmctl-user-guide/debug/run-diagnostic.md index a362628..2c5044e 100644 --- a/ipmctl-user-guide/debug/run-diagnostic.md +++ b/ipmctl-user-guide/debug/run-diagnostic.md @@ -2,11 +2,11 @@ Runs a diagnostic test. -```text +``` ipmctl start [OPTIONS] -diagnostic (Quick|Config|Security|FW) -dimm(DIMMIDs) ``` -### **Targets** +## **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. @@ -16,25 +16,25 @@ ipmctl start [OPTIONS] -diagnostic (Quick|Config|Security|FW) -dimm(DIMMIDs) * 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** +## **Examples** Run all diagnostics -```text +``` $ sudo ipmctl start -diagnostic ``` Run the quick check diagnostic on module 0x0001 -```text +``` $ sudo ipmctl start -diagnostic Quick -dimm 0x0001 ``` -### **Return Data** +## **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: -```text +``` `TestName`: The test name. One of: - `Quick` - `Config` @@ -49,4 +49,3 @@ Each diagnostic generates one or more log messages. A successful test generates `Message`: A free form textual description of the error. ``` - diff --git a/ipmctl-user-guide/debug/show-acpi-tables.md b/ipmctl-user-guide/debug/show-acpi-tables.md index bf261e1..333aced 100644 --- a/ipmctl-user-guide/debug/show-acpi-tables.md +++ b/ipmctl-user-guide/debug/show-acpi-tables.md @@ -2,30 +2,29 @@ Shows the system ACPI tables related to persistent memory modules. -```text +``` ipmctl show [OPTIONS] -system (NFIT|PCAT|PMTT) ``` -### **Targets** +## **Targets** -* `system (NFIT|PCAT|PMTT)`: The system ACPI table\(s\) to display. By default both the NFIT and PCAT tables are displayed. One of: +* `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 + * "PMTT": The Platform Memory Topology Table - Refer to the ACPI specification for detailed information about the ACPI tables. + Refer to the ACPI specification for detailed information about the ACPI tables. -### **Examples** +## **Examples** Show the ACPI NFIT -```text +``` $ sudo ipmctl show -system NFIT ``` -### **Return Data** +## **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/ipmctl-user-guide/debug/show-device-platform-configuration-data.md b/ipmctl-user-guide/debug/show-device-platform-configuration-data.md index 89ca436..68143e3 100644 --- a/ipmctl-user-guide/debug/show-device-platform-configuration-data.md +++ b/ipmctl-user-guide/debug/show-device-platform-configuration-data.md @@ -2,28 +2,27 @@ Shows the platform configuration data for one or more persistent memory modules. -```text +``` ipmctl show [OPTIONS] -dimm (DimmIds) -pcd (Config|LSA) ``` -### **Targets** +## **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** +## **Examples** Show the configuration information from the platform configuration data for all manageable modules -```text +``` $ sudo ipmctl show -dimm -pcd ``` Show the configuration information from the platform configuration data for module 0x0001 -```text +``` ipmctl show -dimm 0x0001 -pcd Config ``` - diff --git a/ipmctl-user-guide/debug/show-error-log.md b/ipmctl-user-guide/debug/show-error-log.md index 4f5d06a..610309c 100644 --- a/ipmctl-user-guide/debug/show-error-log.md +++ b/ipmctl-user-guide/debug/show-error-log.md @@ -2,39 +2,39 @@ Shows thermal or media errors on the specified persistent memory modules. -```text +``` ipmctl show [OPTIONS] -error (Thermal|Media) [TARGETS] [PROPERTIES] ``` -### **Targets** +## **Targets** * `-dimm (DimmIDs)`: Show only the events on specific modules by supplying the DIMM target and one or more comma-separated DimmIDs. -### **Properties** +## **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\) + * "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** +## **Examples** Show all high thermal error log entries -```text +``` $ sudo ipmctl show -error Thermal Level=High ``` Show all low media error log entries -```text +``` $ sudo ipmctl show -error Thermal Level=Low ``` -### **Sample Output** +## **Sample Output** -```text +``` Thermal Error occurred on Dimm (DimmID): System Timestamp : 1527273299 Temperature : 88C @@ -43,7 +43,7 @@ Temperature Type : 0 - Media Temperature Sequence Number : 1 ``` -```text +``` Media Error occurred on Dimm (DimmID): System Timestamp : 1527266471 DPA : 0x000014c0 @@ -54,4 +54,3 @@ Error Flags : DPA Valid Transaction Type : 11 - CSR Write Sequence Number : 2 ``` - diff --git a/ipmctl-user-guide/installing-ipmctl/README.md b/ipmctl-user-guide/installing-ipmctl/README.md new file mode 100644 index 0000000..a972374 --- /dev/null +++ b/ipmctl-user-guide/installing-ipmctl/README.md @@ -0,0 +1,33 @@ +# 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/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md b/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md new file mode 100644 index 0000000..909d7a5 --- /dev/null +++ b/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-from-source-on-linux.md @@ -0,0 +1,773 @@ +# 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/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md b/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md new file mode 100644 index 0000000..9310afa --- /dev/null +++ b/ipmctl-user-guide/installing-ipmctl/building-and-installing-ipmctl-on-microsoft-windows-from-source.md @@ -0,0 +1,14 @@ +# 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/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md b/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md new file mode 100644 index 0000000..a576df4 --- /dev/null +++ b/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-on-microsoft-windows-using-the-msi-installer.md @@ -0,0 +1,11 @@ +# 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/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-packages-on-linux.md b/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-packages-on-linux.md new file mode 100644 index 0000000..cbf6597 --- /dev/null +++ b/ipmctl-user-guide/installing-ipmctl/installing-ipmctl-packages-on-linux.md @@ -0,0 +1,265 @@ +# 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/ipmctl-user-guide/instrumentation/README.md b/ipmctl-user-guide/instrumentation/README.md index 0d0de5e..2a89eec 100644 --- a/ipmctl-user-guide/instrumentation/README.md +++ b/ipmctl-user-guide/instrumentation/README.md @@ -1,2 +1,16 @@ # 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/ipmctl-user-guide/instrumentation/change-sensor-settings.md b/ipmctl-user-guide/instrumentation/change-sensor-settings.md index bef13d4..627b37f 100644 --- a/ipmctl-user-guide/instrumentation/change-sensor-settings.md +++ b/ipmctl-user-guide/instrumentation/change-sensor-settings.md @@ -2,32 +2,31 @@ 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. -```text -ipmctl set [OPTIONS] -sensor (SENSORS) [TARGETS] NonCriticalThreshold=(temperature) EnabledState=(0|1) +``` +$ ipmctl set [OPTIONS] -sensor (SENSORS) [TARGETS] NonCriticalThreshold=(temperature) EnabledState=(0|1) ``` -### **Sensors** +## **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** +## **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** +## **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. +* `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** +## **Examples** Change the media temperature threshold to 51 on the specified module and enable the alarm. -```text +``` ipmctl set -sensor MediaTemperature –dimm 0x0001 NonCriticalThreshold=51 EnabledState=1 ``` - diff --git a/ipmctl-user-guide/instrumentation/show-device-performance.md b/ipmctl-user-guide/instrumentation/show-device-performance.md index 3e668a3..a5cc426 100644 --- a/ipmctl-user-guide/instrumentation/show-device-performance.md +++ b/ipmctl-user-guide/instrumentation/show-device-performance.md @@ -2,11 +2,11 @@ Shows performance metrics for one or more persistent memory modules. -```text +``` ipmctl show [OPTIONS] -performance [METRICS] [TARGETS] ``` -### **Metrics** +## **Metrics** Shows output of a specific performance metric by supplying the metric name. See RETURN DATA for more information. One of: @@ -21,21 +21,20 @@ Shows output of a specific performance metric by supplying the metric name. See The default is to display all performance metrics. -### **Targets** +## **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** +## **Examples** Show all performance metrics for all modules in the server -```text -$ sudo ipmctl show -dimm -performance +``` +$ ipmctl show -dimm -performance ``` Show the number of 64 byte reads since last AC cycle for all modules in the server -```text -$ sudo ipmctl show -dimm -performance MediaReads ``` - +$ ipmctl show -dimm -performance MediaReads +``` diff --git a/ipmctl-user-guide/instrumentation/show-sensor.md b/ipmctl-user-guide/instrumentation/show-sensor.md index 1a6d069..47813fc 100644 --- a/ipmctl-user-guide/instrumentation/show-sensor.md +++ b/ipmctl-user-guide/instrumentation/show-sensor.md @@ -2,11 +2,11 @@ Shows health statistics for one or more persistent memory modules. -```text -ipmctl show [OPTOINS] -sensor [SENSORS] [TARGETS] +``` +$ ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS] ``` -### **Sensors** +## **Sensors** * `Health`: The current module health as reported in the SMART log * `MediaTemperature`: The current module media temperature in Celsius @@ -19,30 +19,30 @@ ipmctl show [OPTOINS] -sensor [SENSORS] [TARGETS] * `PowerCycles`: The number of power cycles over the lifetime of the module * `FwErrorCount`: The total number of firmware error log entries -### **Targets** +## **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** +## **Examples** Get all sensor information for all modules -```text -$ sudo ipmctl show -sensor +``` +$ ipmctl show -sensor ``` Show the media temperature sensor for the specified module -```text -$ sudo ipmctl show -sensor MediaTemperature -dimm 0x0011 +``` +$ ipmctl show -sensor MediaTemperature -dimm 0x0011 ``` -### **Return Data** +## **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: +* `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 @@ -66,4 +66,3 @@ $ sudo ipmctl show -sensor MediaTemperature -dimm 0x0011 * 0: Disabled * 1: Enabled * N/A - diff --git a/ipmctl-user-guide/module-discovery/README.md b/ipmctl-user-guide/module-discovery/README.md index 33f98c3..c062ddd 100644 --- a/ipmctl-user-guide/module-discovery/README.md +++ b/ipmctl-user-guide/module-discovery/README.md @@ -4,28 +4,28 @@ Persistent memory modules are uniquely referenced by one of two IDs: `DimmHandle For example, each of the following are equivalent: -```text -$ sudo ipmctl show -d DimmHandle,DimmUID -dimm 8089-a2-1748-00000001 -$ sudo ipmctl show -d DimmHandle,DimmUID -dimm 0x0001 -$ sudo ipmctl show -d DimmHandle,DimmUID -dimm 1 +``` + $ 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`: -```text -$ sudo 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 +``` + $ 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 +## DimmHandle The `DimmHandle` is equivalent to the `DimmUID` and is formatted as 0xABCD, where A, B, C, and D are defined as follows: @@ -34,12 +34,11 @@ The `DimmHandle` is equivalent to the `DimmUID` and is formatted as 0xABCD, wher * C = Channel * D = Slot -#### DimmUID +## DimmUID -The `DimmUID` is a unique identifier specific to each physical module. The unique identifier of an Intel Optane DC persistent memory module is formatted as VVVV-ML-MMYYSNSNSNSN or VVVV-SNSNSNSN \(if the manufacturing information is not available\) where: +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/ipmctl-user-guide/module-discovery/show-device.md b/ipmctl-user-guide/module-discovery/show-device.md index ced03a0..cff4416 100644 --- a/ipmctl-user-guide/module-discovery/show-device.md +++ b/ipmctl-user-guide/module-discovery/show-device.md @@ -2,21 +2,21 @@ Shows information about one or more Intel Optane DC memory modules. -```text +``` ipmctl show [OPTIONS] -dimm [TARGETS] ``` -### **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** +## **Examples** List a few key fields for each persistent memory module. -```text +``` $ sudo ipmctl show -dimm DimmID | Capacity | HealthState | ActionRequired | LockState | FWVersion @@ -37,13 +37,92 @@ $ sudo ipmctl show -dimm List all properties for module 0x0001. -```text +``` $ 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. -```text +``` $ sudo ipmctl show -d HealthState,LockState -dimm 0x0001 ---DimmID=0x0001--- @@ -51,26 +130,6 @@ $ sudo ipmctl show -d HealthState,LockState -dimm 0x0001 HealthState=Healthy ``` -### **Return Data** - -* `HealthState` Overall module health. One of: - * Healthy - * Noncritical: Maintenance is required. - * Critical: Features or performance are degraded due to failure. - * Fatal: Data loss has occurred or is imminent. In this case, the firmware will disable the media and access to user data and operations that require use of the media will fail. - * Non-functional: The module is present but is non-responsive via the DDRT communication path. It may be possible to communicate with this module via SMBus for a subset of commands. - * Unmanageable: The module is not supported by this version of the software - * Unknown: Unable to determine the module's health state. -* `ActionRequired`: If there are events for this device that require corrective action or acknowledgment. Refer to the command Show Events for more information about events. One of: - * 0: No action required events - * 1: One or more action required events -* `LockState` is the current security state of the persistent memory on the module. One of: - * Unknown - The security state cannot be determined \(e.g., when the module is not manageable by the software\). - * Disabled - Security is not enabled. - * Disabled, Frozen - Security is not enabled. A reboot is required to change the security state. - * Unlocked - Security is enabled and unlocked. - * Unlocked, Frozen - Security is enabled and unlocked. A reboot is required to change the security state. - * Locked - Security is enabled and locked. - * Exceeded - The passphrase limit has been reached. A power cycle is required to change the security state. - * Not Supported - Security is not supported on the module. +## **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/ipmctl-user-guide/module-discovery/show-memory-resources.md b/ipmctl-user-guide/module-discovery/show-memory-resources.md index 1385c3c..d2f040f 100644 --- a/ipmctl-user-guide/module-discovery/show-memory-resources.md +++ b/ipmctl-user-guide/module-discovery/show-memory-resources.md @@ -1,34 +1,70 @@ # Show Memory Resources -Show the total Intel Optane DC persistent memory resource allocation across the host server. +Show the total Intel Optane persistent memory resource allocation across the host server. -```text +``` ipmctl show [OPTIONS] -memoryresources ``` -### **Example** +## **Examples** -Show persistent memory module resource allocation. +### AppDirect -```text -$ sudo ipmctl show -memoryresources +The following shows persistent memory module resource allocation from a system configured in 100% AppDirect mode: -Capacity=1517.0 GiB -MemoryCapacity=0.0 GiB -AppDirectCapacity=1512.0 GiB -UnconfiguredCapacity=0.0 GiB -InaccessibleCapacity=5.0 GiB -ReservedCapacity=0.0 GiB ``` +$ 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). -### **Return Data** +``` +# 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 +``` -* `MemoryCapacity`: Total usable system persistent memory for Memory Mode. -* `AppDirectCapacity`: Total usable system persistent memory for App Direct mode. -* `UnconfiguredCapacity`: Total system persistent memory capacity that is unusable because it has not been configured. -* `ReservedCapacity`: Total system persistent memory 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 \(SPA\) space. -* `InaccessibleCapacity`: Total system persistent memory capacity that is inaccessible due any of: - * Platform configuration prevents accessing this capacity. e.g. MemoryCapacity is configured but MemoryMode is not enabled by platform FW \(current operating 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. - * Intel Optane DC persistent memory is configured but SKU prevents usage. e.g. AppDirectCapacity but SKU is MemoryMode only. +## **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/ipmctl-user-guide/module-discovery/show-socket.md b/ipmctl-user-guide/module-discovery/show-socket.md index d7c5ba8..ac4cc3f 100644 --- a/ipmctl-user-guide/module-discovery/show-socket.md +++ b/ipmctl-user-guide/module-discovery/show-socket.md @@ -2,20 +2,20 @@ Shows basic information about the physical processors in the host server. -```text +``` ipmctl show [OPTIONS] -socket [TARGETS] ``` -### **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** +## **Examples** Display information about all the processors. -```text -$ sudo ipmctl show -socket +``` +# ipmctl show -socket SocketID | MappedMemoryLimit | TotalMappedMemory ================================================== @@ -25,8 +25,8 @@ $ sudo ipmctl show -socket List all properties for socket 1. -```text - ipmctl show -socket 1 +``` +# ipmctl show -socket 1 SocketID | MappedMemoryLimit | TotalMappedMemory ================================================== @@ -35,8 +35,8 @@ List all properties for socket 1. Retrieve specific properties for each processor. -```text -$ sudo ipmctl show -d MappedMemoryLimit -socket +``` +# ipmctl show -d MappedMemoryLimit -socket ---SocketID=0x0000--- MappedMemoryLimit=4608.0 GiB @@ -44,8 +44,7 @@ $ sudo ipmctl show -d MappedMemoryLimit -socket MappedMemoryLimit=4608.0 GiB ``` -### **Return Data** +## **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/ipmctl-user-guide/module-discovery/show-system-capabilities.md b/ipmctl-user-guide/module-discovery/show-system-capabilities.md index 8b7a0e1..80ae7af 100644 --- a/ipmctl-user-guide/module-discovery/show-system-capabilities.md +++ b/ipmctl-user-guide/module-discovery/show-system-capabilities.md @@ -2,14 +2,14 @@ Shows the platform supported Intel Optane DC persistent memory capabilities across the server. -```text +``` ipmctl show [OPTIONS] -system -capabilities ``` -### **Example** +## **Example** -```text -$ sudo ipmctl show -system -capabilities +``` +$ ipmctl show -system -capabilities PlatformConfigSupported=1 Alignment=1.0 GiB @@ -18,7 +18,7 @@ CurrentVolatileMode=1LM AllowedAppDirectMode=App Direct ``` -### **Return Data** +## **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. @@ -36,4 +36,3 @@ AllowedAppDirectMode=App Direct * 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/ipmctl-user-guide/module-discovery/show-topology.md b/ipmctl-user-guide/module-discovery/show-topology.md index 8ba584d..2c1cbc8 100644 --- a/ipmctl-user-guide/module-discovery/show-topology.md +++ b/ipmctl-user-guide/module-discovery/show-topology.md @@ -2,20 +2,22 @@ Shows the topology of DDR and persistent memory modules installed in the host server. -```text +``` ipmctl show [OPTIONS] -topology [TARGETS] ``` -### **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. -### **Example** +## **Examples** + +Display all DDR and Optane persistent memory modules installed in the system -```text -$ sudo ipmctl show -topology +``` +$ ipmctl show -topology DimmID | MemoryType | Capacity | PhysicalID| DeviceLocator ============================================================================== @@ -45,3 +47,32 @@ $ sudo ipmctl show -topology 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/ipmctl-user-guide/provisioning/README.md b/ipmctl-user-guide/provisioning/README.md index 83b2387..1a63343 100644 --- a/ipmctl-user-guide/provisioning/README.md +++ b/ipmctl-user-guide/provisioning/README.md @@ -1,14 +1,17 @@ # Provisioning -Intel Optane DC persistent memory modules can be provisioned into three different operating modes: +Intel Optane persistent memory modules can be provisioned into three different operating modes: -* **App Direct**: Persistent memory exposed as block devices to 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. +* **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). -> **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. +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/ipmctl-user-guide/provisioning/concepts.md b/ipmctl-user-guide/provisioning/concepts.md index 343cfcb..72b879b 100644 --- a/ipmctl-user-guide/provisioning/concepts.md +++ b/ipmctl-user-guide/provisioning/concepts.md @@ -1,18 +1,15 @@ # Concepts -To provision, or change modes, create a **goal configuration** which 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. +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**, or **interleaved set**, 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. +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. +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 hard disk partition SCSI Logical Unit, or an NVM Express namespace. A namespace is the unit of persistent memory storage that appears in the /dev directory as a device which 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. +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) -Namespaces are conceptually similar to a partition, and a **label** is similar to a partition table. Intel persistent memory modules support labels which allow regions to be further divided into namespaces. A label contains metadata stored on an NVDIMM. - - - +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/ipmctl-user-guide/provisioning/create-memory-allocation-goal.md b/ipmctl-user-guide/provisioning/create-memory-allocation-goal.md index b793301..a0909f8 100644 --- a/ipmctl-user-guide/provisioning/create-memory-allocation-goal.md +++ b/ipmctl-user-guide/provisioning/create-memory-allocation-goal.md @@ -1,30 +1,67 @@ # Create Memory Allocation Goal -```text +``` 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. +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** +## **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. +* `-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** +## **Properties** -* `MemoryMode`: Percentage of the total capacity to use in Memory Mode \(0-100\). Default=0. +* `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. + * `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 +* `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. +* `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** +## **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/ipmctl-user-guide/provisioning/delete-memory-allocation-goal.md b/ipmctl-user-guide/provisioning/delete-memory-allocation-goal.md index 58fc844..f6f907a 100644 --- a/ipmctl-user-guide/provisioning/delete-memory-allocation-goal.md +++ b/ipmctl-user-guide/provisioning/delete-memory-allocation-goal.md @@ -2,18 +2,17 @@ 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. -```text -ipmctl delete [OPTIONS] -goal [TARGETS] +``` +$ ipmctl delete [OPTIONS] -goal [TARGETS] ``` -### **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** +## **Example** -```text -$ sudo ipmctl delete -goal ``` - +$ ipmctl delete -goal +``` diff --git a/ipmctl-user-guide/provisioning/dump-memory-allocation-settings.md b/ipmctl-user-guide/provisioning/dump-memory-allocation-settings.md index 41c751c..e4089b1 100644 --- a/ipmctl-user-guide/provisioning/dump-memory-allocation-settings.md +++ b/ipmctl-user-guide/provisioning/dump-memory-allocation-settings.md @@ -2,17 +2,16 @@ 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) -```text -ipmctl dump [OPTIONS] -destination (path) -system -config +``` +$ ipmctl dump [OPTIONS] -destination (path) -system -config ``` -### **Example** +## **Example** -```text -$ sudo ipmctl dump -destination config.txt -system -config +``` +$ ipmctl dump -destination config.txt -system -config ``` -### **Limitations** +## **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/ipmctl-user-guide/provisioning/load-memory-allocation-goal.md b/ipmctl-user-guide/provisioning/load-memory-allocation-goal.md index 54759e3..5e32f7e 100644 --- a/ipmctl-user-guide/provisioning/load-memory-allocation-goal.md +++ b/ipmctl-user-guide/provisioning/load-memory-allocation-goal.md @@ -1,43 +1,44 @@ # Load Memory Allocation Goal -Load a memory allocation goal from a file onto one or more persistent memory modules. +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. -> **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. +{% 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. -```text -ipmctl load [OPTIONS] -source (path) -goal [TARGETS] +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** +## **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** +## **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. -```text -$ sudo ipmctl load -source config.txt -goal +``` +$ 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. -```text -$ sudo ipmctl load -source config.txt -goal -dimm 1,2,3 +``` +$ 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. -```text -$ sudo ipmctl load -source config.txt -goal -socket 1,2 +``` +$ ipmctl load -source config.txt -goal -socket 1,2 ``` -### **Limitations** +## **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/ipmctl-user-guide/provisioning/provision-app-direct.md b/ipmctl-user-guide/provisioning/provision-app-direct.md index ffdf930..93ec51d 100644 --- a/ipmctl-user-guide/provisioning/provision-app-direct.md +++ b/ipmctl-user-guide/provisioning/provision-app-direct.md @@ -2,13 +2,28 @@ Creates a memory allocation goal for App Direct in either one fully interleaved region, or non-interleaved, meaning one region per module. -**Examples** +## **Examples** -```text -$ sudo 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=AppDirect ``` -```text -$ sudo ipmctl create -goal PersistentMemoryType=AppDirectNotInterleaved +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/ipmctl-user-guide/provisioning/provision-memory-mode.md b/ipmctl-user-guide/provisioning/provision-memory-mode.md index f57304f..e5a8f75 100644 --- a/ipmctl-user-guide/provisioning/provision-memory-mode.md +++ b/ipmctl-user-guide/provisioning/provision-memory-mode.md @@ -1,14 +1,13 @@ # 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. +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** +## **Examples** -Configure 100% of the available capacity on each persistent memory module to be in Memory Mode. +Configures all the PMem module capacity in Memory Mode. -```text -$ sudo ipmctl create -goal MemoryMode=100 +``` +$ 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. - +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/ipmctl-user-guide/provisioning/provision-mixed-mode.md b/ipmctl-user-guide/provisioning/provision-mixed-mode.md index 41e7f04..7556837 100644 --- a/ipmctl-user-guide/provisioning/provision-mixed-mode.md +++ b/ipmctl-user-guide/provisioning/provision-mixed-mode.md @@ -1,18 +1,17 @@ # 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. +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** +## **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. -```text -$ sudo ipmctl create -goal MemoryMode=20 PersistentMemoryType=AppDirectNotInterleaved +``` +$ 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. -```text -$ sudo ipmctl create -goal MemoryMode=25 Reserved=25 ``` - +$ ipmctl create -goal MemoryMode=25 Reserved=25 +``` diff --git a/ipmctl-user-guide/provisioning/show-memory-allocation-goal.md b/ipmctl-user-guide/provisioning/show-memory-allocation-goal.md index d626118..531e73a 100644 --- a/ipmctl-user-guide/provisioning/show-memory-allocation-goal.md +++ b/ipmctl-user-guide/provisioning/show-memory-allocation-goal.md @@ -2,7 +2,7 @@ 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. -```text +``` ipmctl show [OPTIONS] -goal [TARGETS] [PROPERTIES] ``` @@ -13,12 +13,12 @@ ipmctl show [OPTIONS] -goal [TARGETS] [PROPERTIES] **Examples** -```text -$ sudo ipmctl show -goal +``` +$ ipmctl show -goal ``` -```text -$ sudo ipmctl show -goal -socket 1 +``` +$ ipmctl show -goal -socket 1 ``` **Return Data** @@ -35,4 +35,3 @@ $ sudo ipmctl show -goal -socket 1 * `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/ipmctl-user-guide/support-and-maintenance/README.md b/ipmctl-user-guide/support-and-maintenance/README.md index 029df60..c5cea2e 100644 --- a/ipmctl-user-guide/support-and-maintenance/README.md +++ b/ipmctl-user-guide/support-and-maintenance/README.md @@ -1,2 +1,12 @@ # 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/ipmctl-user-guide/support-and-maintenance/show-events.md b/ipmctl-user-guide/support-and-maintenance/show-events.md index cc61d6c..86cd314 100644 --- a/ipmctl-user-guide/support-and-maintenance/show-events.md +++ b/ipmctl-user-guide/support-and-maintenance/show-events.md @@ -2,15 +2,15 @@ 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. -```text +``` ipmctl show [OPTIONS] -event [TARGETS] [PROPERTIES] ``` -### **Targets** +## **Targets** * `-dimm [(DimmID)]`: Filter output to events on a specific module by optionally supplying the DIMM target and one or more DimmID. -### **Properties** +## **Properties** * `Category`: Filters output to events of a specific category. One of: * `Diag`: Filters output to diagnostic events. @@ -22,7 +22,7 @@ ipmctl show [OPTIONS] -event [TARGETS] [PROPERTIES] * `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. + * `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. @@ -30,21 +30,21 @@ ipmctl show [OPTIONS] -event [TARGETS] [PROPERTIES] * `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** +## **Examples** Display the 50 most recent events. -```text +``` $ 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`. -```text +``` $ sudo ipmctl show -event count=10 severity=error ``` -### **Return Data** +## **Return Data** This command displays a table with a row for each event matching the provided filters, showing most recent first. @@ -56,4 +56,3 @@ This command displays a table with a row for each event matching the provided fi * `1`: An action is required. * `Code`: The event code defined by the SW Event Log specification * `Message`: The event message - diff --git a/ipmctl-user-guide/support-and-maintenance/version-and-firmware.md b/ipmctl-user-guide/support-and-maintenance/version-and-firmware.md index 35c93e0..6cb9571 100644 --- a/ipmctl-user-guide/support-and-maintenance/version-and-firmware.md +++ b/ipmctl-user-guide/support-and-maintenance/version-and-firmware.md @@ -1,48 +1,45 @@ # Version and Firmware -### Get Version +## Get Version Shows the persistent memory module host software versions -```text -$ sudo ipmctl version +``` +ipmctl version ``` -### Show Device Firmware +## Show Device Firmware Shows detailed information about the firmware on one or more modules -```text -ipmctl show [OPTIONS] -firmware [TARGETS] +``` +$ ipmctl show [OPTIONS] -firmware [TARGETS] ``` -### Update Firmware +## Update Firmware Updates the firmware on one or more modules -```text -ipmctl load [OPTIONS] -source (path) -dimm (DimmIds) [TARGETS] +``` +$ 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: 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** +### **Examples** Update the firmware on all modules in the system to the image in sourcefile.pkg on the next power cycle. -```text +``` $ sudo ipmctl load -source sourcefile.pkg -dimm ``` Check the firmware image in sourcefile.pkg and retrieve the version. -```text +``` $ 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. - - - +> 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.