IPMCTL-CREATE-GOAL(1)

NAME 💖

ipmctl-create-goal — creates a memory allocation goal on one or more PMem modules. bestie, this is the whole vibe of the page ✨

SYNOPSIS ✨

ipmctl create [OPTIONS] -goal [TARGETS] [PROPERTIES]

DESCRIPTION 🦋

Okay so this command creates a memory allocation goal on one or more PMem modules, and the BIOS reads it on the next reboot so it can map the PMem module capacity into the system address space. Then you can use the persistent memory by creating a namespace. periodt 💅

Note The capacity values this command presents 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. ngl, firmware said “we’ll see” 🙈

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. bestie, back it up, fr fr 😭

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 💖

1. Configures all the PMem module capacity in Memory Mode. 🧠

ipmctl create -goal MemoryMode=100

2. Configures all the PMem module capacity as App Direct. 💫

ipmctl create -goal PersistentMemoryType=AppDirect

3. 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

4. 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 🌸

okay bestie so here's the tea on what comes back at you 💅 Sometimes the capacities you asked for get nudged by up to 10% — that's just the platform rules needing stuff to line up all pretty. And sometimes the tool is gonna side-eye your request and ask for extra confirmation, because what you asked for could land you in a non-optimal configuration (aka reduced performance, aka not the vibe 😭). All of those situations are listed right here:

• The requested goal may result in a non-optimal configuration due to the population of PMem modules in the system. Memory Mode capacity was requested, but the way the DRAM DIMMs and PMem modules are populated in the system may result in reduced performance — like, the ratio of DRAM and PMem modules isn't balanced, or the DRAM and PMem modules aren't on the same channel, or they're 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 was requested, but the population of PMem modules in the system may result in reduced performance — i.e., the PMem modules aren't the same size, or they're 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 was requested, but App Direct isn't 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 was requested, but the platform BIOS is currently set to 1LM Mode. 😬
• The requested goal was adjusted more than 10% to find a valid configuration. So: > 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. ✨

---

So before anything gets changed in your configuration, a prompt pops up showing you the memory allocation goals that are gonna be created on each PMem module — exactly like the command Section [Show Memory Allocation Goal] documents — plus any of those extra confirmation messages from above. If you're feeling brave (or reckless 🫣), the force option lets you skip that confirmation entirely and go straight to 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?

---

and that's the whole page bestie, we ate that up fr fr 👑💖 this was ipmctl, version dated 2024-04-22, and you were reading IPMCTL-CREATE-GOAL(1) — now go forth and create those goals responsibly, mwah 🎀🦋