Provided by: ipmctl_03.00.00.0485-1build1_amd64 
NAME
ipmctl-create-goal - Creates a memory allocation goal on one or more PMem modules
SYNOPSIS
ipmctl create [OPTIONS] -goal [TARGETS] [PROPERTIES]
DESCRIPTION
Creates a memory allocation goal on one or more for the BIOS to read on the next reboot in order to map
the PMem module capacity into the system address space. Persistent memory can then be utilized by
creating a namespace.
Note
The capacity values presented by this command are a target goal or request to platform firmware. The
actual capacity values are subject to change due to rounding and alignment requirements. If the goal
request is invalid or not possible it may be rejected by platform firmware.
Note
Deleting the PCD can be used as a way to prepare individual PMem modules for provisioning. See the
delete -pcd command.
Warning
This command may result in data loss. Data should be backed up to other storage before executing this
command.
Note
Changing a memory allocation goal modifies how the platform firmware maps persistent memory in the
System Physical 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.
OPTIONS
-f, -force
Reconfiguring PMem modules is a destructive operation which requires confirmation from the user.
This option suppresses the confirmation. This option can also be used to recover/override corrupted
Platform Configuration Data (PCD). The force flag will also suppress the security enabled warning as
well as all other warning prompts.
-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.
-o (text|nvmxml), -output (text|nvmxml)
Changes the output format. One of: "text" (default) or "nvmxml". The "nvmxml" format implies the
"-force" flag.
-u (B|MB|MiB|GB|GiB|TB| TiB), -units (B|MB|MiB|GB|GiB|TB| TiB)
Changes the units that capacities are displayed in for this command. One of: bytes (B), megabytes
(MB), mebibytes (MiB), gigabytes (GB), gibibytes (GiB), terabytes (TB) or tebibytes (TiB).
TARGETS
-dimm [DimmIDs]
Creates a memory allocation goal on specific PMem modules by optionally supplying one or more comma
separated PMem module identifiers. This list must meet one of the following criteria:
1. Target all PMem modules on a given socket.
• For example, all PMem modules located within a single socket may be specified together using
the dimm target.
2. Target all unconfigured PMem modules
• For example, when PMem modules have had their PCD deleted, then these PMem modules may all be
specified together using the dimm target.
3. Target PMem modules for 100% MemoryMode with all unspecified PMem modules configured for
MemoryMode only
• For example, when existing PMem modules are 100% MM, then any newly added PMem modules may
all be specified together using the dimm target and configured as 100% MM to match the
existing configuration.
4. Target PMem modules for App Direct Not Interleaved with all unspecified PMem modules configured
for App Direct Not Interleaved only
• For example, when existing PMem modules are 100% App Direct Not Interleaved, then any newly
added PMem modules may all be specified together using the dimm target and configured as 100%
App Direct Not Interleaved to match the existing configuration.
Note
If the dimm target is not specified, the default is to configure all manageable PMem modules on
all sockets.
-socket [SocketIDs]
Loads the memory allocation goal onto all manageable PMem modules on specific sockets by supplying
the socket target and one or more comma separated socket identifiers. The default is to load the
memory allocation goal onto all manageable PMem modules on all sockets.
PROPERTIES
MemoryMode
Percentage of the total capacity to use in Memory Mode (0-100). Default = 0.
PersistentMemoryType
If MemoryMode is not 100%, the type of persistent memory to create.
• "AppDirect": (Default) Create App Direct capacity utilizing hardware interleaving across the
requested PMem modules if applicable given the specified target.
• "AppDirectNotInterleaved": Create App Direct capacity that is not interleaved any other PMem
modules.
NamespaceLabelVersion
The version of the namespace label storage area (LSA) index block
• "1.2": (Default) Defined in UEFI 2.7a - sections 13.19
• "1.1": Legacy 1.1 namespace label support
Reserved
Reserve a percentage (0-100) of the requested PMem module App Direct capacity that will not be mapped
into the system physical address space and will be presented as Reserved Capacity with [Show Dimm]
and [Show Memory Resources] commands.
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 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
LIMITATIONS
In order to successfully execute this command:
• The caller must have the appropriate privileges.
• The specified PMem modules must be manageable by the host software and must all have the same SKU.
• SKU based maximum total mapped memory is enforced. See section [CPU Maximum Mapped Memory Limiting].
• If no PMem modules are specified, all PMem modules in a non-functional or unmanageable state will not
be included in the goal’s creation.
• If the goal request is for an interleaved set, PMem modules in population violation will not be
included in the goal’s creation.
• Existing memory allocation goals that have not been applied and any namespaces associated with the
requested PMem modules must be deleted before running this command.
• Goal requests may not be applied by platform firmware (BIOS) if the PMem module is in security
enabled, locked state.
Note
It is recommended to disable security prior to reboot if requesting a new goal.
Note
A goal request may be initiated even if a target PMem module is in security state enabled, but care
must be taken to ensure the PMem module is in either unlocked or disabled security state prior to the
platform firmware (BIOS) provisioning flow following a reboot. In addition, a warning will be
presented to the user: WARNING: Goal will not be applied unless security is disabled prior to
platform firmware (BIOS) provisioning!
• Changing the memory configuration is a destructive operation which results in loss of data stored in
the persistent memory region. Therefore, data should be backed up to other storage before executing
this command. Targets may be limited to individual PMem modules or sockets, but all PMem modules on
affected sockets must be configured when the command finishes. If the selected targets make this
impossible, the command will be rejected. Refer to [Show System Capabilities] for a list of BIOS
supported modes.
• Some requests are dependent on BIOS and/or platform configuration. For details, see the Intel®
Optane™ DC Persistent Memory Software Memory Allocation Rules for Windows, Linux and UEFI, document
number 564194. For example:
• Provisioning PMem modules for Memory Mode while BIOS is configured for 1LM only will result in
unused capacity.
• Provisioning PMem modules for Memory Mode while not all iMCs have at least one PMem module will
result in unused capacity.
• PMem modules in population violation can be targeted for goal creation only if
PersistentMemoryType=AppDirectNotInterleaved and no volatile memory is requested (100% ADx1).
RETURN DATA
Minor adjustments (up to 10%) in the requested capacities are sometimes necessary to align properly
according to the platform rules. There are also some situations that require additional confirmation from
the user because they may result in a non- optimal configuration (i.e., reduced performance). These are
described below.:
The requested goal may result in a non-optimal configuration due to the population of PMem modules in the
system.
Memory Mode capacity requested but the population of DRAM DIMMs and PMem modules in the system may result
in reduced performance (i.e., the ratio of DRAM and PMem modules is not balanced, DRAM and PMem modules
are not on the same channel or not all the same size).
The requested goal may result in a non-optimal configuration due to the population of PMem modules in the
system.
App Direct capacity requested but the population of PMem modules in the system may result in reduced
performance (i.e., PMem modules are not the same size or populated asymmetrically across the socket).
The requested goal will result in App Direct capacity which is not supported by the host software.
App Direct capacity requested but App Direct is not supported by the currently installed host software.
The requested goal will result in Memory Mode capacity that is unusable with the currently selected
platform BIOS volatile mode.
Memory Mode capacity requested by the platform BIOS is currently set to 1LM Mode.
The requested goal was adjusted more than 10% to find a valid configuration.
> 10% adjustment from the requested goal
The amount of mapped memory was limited based on the SKU resulting in un-mapped capacity.
Mapped memory was limited based on the CPU SKU.
Therefore, before making any changes to the configuration, a prompt is displayed showing the memory
allocation goals that will be created on each PMem module as documented in the command Section [Show
Memory Allocation Goal], along with any additional confirmation messages. The force option can be used to
override this confirmation and proceed directly with creating the goals.
The following configuration will be applied:
SocketID DimmID MemorySize AppDirect1Size AppDirect2Size (Refer to
the command Section <<Show Memory Allocation Goal>>)
[Additional Confirmation Messages (see above)] Do you want to
continue?
ipmctl 2024-04-22 IPMCTL-CREATE-GOAL(1)