// Copyright (c) 2018, Intel Corporation.
// SPDX-License-Identifier: BSD-3-Clause

ifdef::manpage[]
ipmctl-dump-goal(1)
===================
endif::manpage[]

NAME
----
ipmctl-dump-goal - Stores the current configured memory allocation settings to a file

SYNOPSIS
--------
[listing]
ipmctl dump [OPTIONS] -destination (path) -system -config

DESCRIPTION
-----------
Store the currently configured memory allocation settings for all PMem modules in the
system to a file in order to replicate the configuration elsewhere. Apply the
stored memory allocation settings using the command Section
<<Load Memory Allocation Goal>>.

OPTIONS
-------
-h::
-help::
    Displays help for the command.

-ddrt::
  Used to specify DDRT as the desired transport protocol for the current invocation of ipmctl.

-smbus::
  Used to specify SMBUS as the desired transport protocol for the current invocation of ipmctl.

NOTE: The -ddrt and -smbus options are mutually exclusive and may not be used together.

-lpmb::
  Used to specify large transport payload size for the current invocation of ipmctl.

-spmb::
  Used to specify small transport payload size for the current invocation of ipmctl.

NOTE: The -lpmb and -spmb options are mutually exclusive and may not be used together.

ifdef::os_build[]
-o (text|nvmxml)::
-output (text|nvmxml)::
  Changes the output format. One of: "text" (default) or "nvmxml".
endif::os_build[]

EXAMPLES
--------
Stores the memory allocation settings from all the PMem modules into the file "config.txt".
[listing]
ipmctl dump -destination config.txt -system -config

LIMITATIONS
-----------
In order to successfully execute this command:

- The caller must have the appropriate privileges.

- Only memory allocation settings for manageable PMem modules that have been
  successfully applied by the BIOS are stored in the file. Unconfigured PMem modules are
  not included, nor are memory allocation goals that have not been applied.

RETURN DATA
-----------
The CLI will indicate the overall status of the operation when complete. If a
failure occurs when dumping the memory allocation from multiple PMem modules, the
process will stop and the output file will be removed.

The output file is formatted as an ASCII file with one row per PMem module containing
the following comma-separated values.

SocketID::
  Identifier for the socket the PMem module is associated with.

DimmHandle::
  PMem module device handle.

Capacity::
  Total capacity of the PMem module in GiB.

MemorySize::
  Capacity of the PMem module allocated as Memory Mode in GiB.

AppDirect1Size::
  Capacity of the PMem module allocated for the first App
  Direct interleave set in GiB.

AppDirect1Format::
  Bit mask representing the interleave format of the first
  App Direct interleave set.

AppDirect1Mirrored::
  State indicating if the first App Direct interleave set is mirrored.
  * 0 - The first App Direct interleave set is not mirrored.
  * 1 - The first App Direct interleave set is mirrored.

AppDirect1Index::
  Unique index of the first App Direct interleave set.

AppDirect2Size::
  Capacity of the PMem module allocated for the second App
  Direct interleave set in GiB.

AppDirect2Format::
  Bit mask representing the interleave format of the second
  App Direct interleave set.

AppDirect2Mirrored::
  State indicating if the second App Direct interleave set is mirrored.
  * 0 - The second App Direct interleave set is not mirrored.
  * 1 - The second App Direct interleave set is mirrored.

AppDirect2Index::
  Unique index of the second App Direct interleave set.

SAMPLE OUTPUT
-------------
[listing]
Successfully dumped system configuration to file: config.csv

config.csv contents:
[listing]
#SocketID,DimmHandle,Capacity,MemorySize,AppDirect1Size,AppDirect
1Format,AppDirect
1Mirrored,AppDirect1Index,AppDirect2Size,AppDirect2Format,AppDire
ct2Mirrored,AppDirect2Index
1,4385,64,64,0,0,0,0,0,0,0,0
1,4401,64,64,0,0,0,0,0,0,0,0
1,4417,64,64,0,0,0,0,0,0,0,0
1,4433,64,64,0,0,0,0,0,0,0,0
1,4449,64,64,0,0,0,0,0,0,0,0
