1IPMCTL-CREATE-GOAL(1) ipmctl IPMCTL-CREATE-GOAL(1)
2
6 ipmctl-create-goal - Creates a memory allocation goal on one or more
7 PMem modules
8
10 ipmctl create [OPTIONS] -goal [TARGETS] [PROPERTIES]
11
13 Creates a memory allocation goal on one or more for the BIOS to read on
14 the next reboot in order to map the PMem module capacity into the
15 system address space. Persistent memory can then be utilized by
16 creating a namespace.
17 Note
19 The capacity values presented by this command are a target goal or
20 request to platform firmware. The actual capacity values are
21 subject to change due to rounding and alignment requirements. If
22 the goal request is invalid or not possible it may be rejected by
23 platform firmware.
24 Note
26 Deleting the PCD can be used as a way to prepare individual PMem
27 modules for provisioning. See the delete -pcd command.
28 Warning
30 This command may result in data loss. Data should be backed up to
31 other storage before executing this command.
32 Note
34 Changing a memory allocation goal modifies how the platform
35 firmware maps persistent memory in the System Physical Address
36 space (SPA) which may result in data loss or inaccessible data, but
37 does not explicitly delete or modify user data found in persistent
38 memory.
39
41 -f, -force
42 Reconfiguring PMem modules is a destructive operation which
43 requires confirmation from the user. This option suppresses the
44 confirmation. This option can also be used to recover/override
45 corrupted Platform Configuration Data (PCD). The force flag will
46 also suppress the security enabled warning as well as all other
47 warning prompts.
48 -h, -help
50 Displays help for the command.
51 -ddrt
53 Used to specify DDRT as the desired transport protocol for the
54 current invocation of ipmctl.
55 -smbus
57 Used to specify SMBUS as the desired transport protocol for the
58 current invocation of ipmctl.
59 Note
61 The -ddrt and -smbus options are mutually exclusive and may not be
62 used together.
63 -o (text|nvmxml), -output (text|nvmxml)
65 Changes the output format. One of: "text" (default) or "nvmxml".
66 The "nvmxml" format implies the "-force" flag.
67 -u (B|MB|MiB|GB|GiB|TB| TiB), -units (B|MB|MiB|GB|GiB|TB| TiB)
69 Changes the units that capacities are displayed in for this
70 command. One of: bytes (B), megabytes (MB), mebibytes (MiB),
71 gigabytes (GB), gibibytes (GiB), terabytes (TB) or tebibytes (TiB).
72
74 -dimm [DimmIDs]
75 Creates a memory allocation goal on specific PMem modules by
76 optionally supplying one or more comma separated PMem module
77 identifiers. This list must meet one of the following criteria:
78 1. Target all PMem modules on a given socket.
80 • For example, all PMem modules located within a single
82 socket may be specified together using the dimm target.
83 2. Target all unconfigured PMem modules
85 • For example, when PMem modules have had their PCD deleted,
87 then these PMem modules may all be specified together using
88 the dimm target.
89 3. Target PMem modules for 100% MemoryMode with all unspecified
91 PMem modules configured for MemoryMode only
92 • For example, when existing PMem modules are 100% MM, then
94 any newly added PMem modules may all be specified together
95 using the dimm target and configured as 100% MM to match
96 the existing configuration.
97 4. Target PMem modules for App Direct Not Interleaved with all
99 unspecified PMem modules configured for App Direct Not
100 Interleaved only
101 • For example, when existing PMem modules are 100% App Direct
103 Not Interleaved, then any newly added PMem modules may all
104 be specified together using the dimm target and configured
105 as 100% App Direct Not Interleaved to match the existing
106 configuration.
107 Note
109 If the dimm target is not specified, the default is to
110 configure all manageable PMem modules on all sockets.
111 -socket [SocketIDs]
113 Loads the memory allocation goal onto all manageable PMem modules
114 on specific sockets by supplying the socket target and one or more
115 comma separated socket identifiers. The default is to load the
116 memory allocation goal onto all manageable PMem modules on all
117 sockets.
118
120 MemoryMode
121 Percentage of the total capacity to use in Memory Mode (0-100).
122 Default = 0.
123 PersistentMemoryType
125 If MemoryMode is not 100%, the type of persistent memory to create.
126 • "AppDirect": (Default) Create App Direct capacity utilizing
128 hardware interleaving across the requested PMem modules if
129 applicable given the specified target.
130 • "AppDirectNotInterleaved": Create App Direct capacity that is
132 not interleaved any other PMem modules.
133 NamespaceLabelVersion
135 The version of the namespace label storage area (LSA) index block
136 • "1.2": (Default) Defined in UEFI 2.7a - sections 13.19
138 • "1.1": Legacy 1.1 namespace label support
140 Reserved
142 Reserve a percentage (0-100) of the requested PMem module App
143 Direct capacity that will not be mapped into the system physical
144 address space and will be presented as Reserved Capacity with [Show
145 Dimm] and [Show Memory Resources] commands.
146
148 Configures all the PMem module capacity in Memory Mode.
149 ipmctl create -goal MemoryMode=100
151 Configures all the PMem module capacity as App Direct.
153 ipmctl create -goal PersistentMemoryType=AppDirect
155 Configures the capacity on each PMem module with 20% of the capacity in
157 Memory Mode and the remaining as App Direct capacity that does not use
158 hardware interleaving.
159 ipmctl create -goal MemoryMode=20 PersistentMemoryType=AppDirectNotInterleaved
161 Configures the PMem module capacity across the entire system with 25%
163 of the capacity in Memory Mode, 25% reserved and the remaining 50% as
164 App Direct. Configures the PMem module capacity across the entire
165 system with 25% of the capacity in Memory Mode and the remaining 75% as
166 App Direct.
167 ipmctl create -goal MemoryMode=25 PersistentMemoryType=AppDirect Reserved=25
169
171 In order to successfully execute this command:
172 • The caller must have the appropriate privileges.
174 • The specified PMem modules must be manageable by the host software
176 and must all have the same SKU.
177 • SKU based maximum total mapped memory is enforced. See section [CPU
179 Maximum Mapped Memory Limiting].
180 • If no PMem modules are specified, all PMem modules in a
182 non-functional or unmanageable state will not be included in the
183 goal’s creation.
184 • If the goal request is for an interleaved set, PMem modules in
186 population violation will not be included in the goal’s creation.
187 • Existing memory allocation goals that have not been applied and any
189 namespaces associated with the requested PMem modules must be
190 deleted before running this command.
191 • Goal requests may not be applied by platform firmware (BIOS) if the
193 PMem module is in security enabled, locked state.
194 Note
196 It is recommended to disable security prior to reboot if requesting
197 a new goal.
198 Note
200 A goal request may be initiated even if a target PMem module is in
201 security state enabled, but care must be taken to ensure the PMem
202 module is in either unlocked or disabled security state prior to
203 the platform firmware (BIOS) provisioning flow following a reboot.
204 In addition, a warning will be presented to the user: WARNING: Goal
205 will not be applied unless security is disabled prior to platform
206 firmware (BIOS) provisioning!
207 • Changing the memory configuration is a destructive operation which
209 results in loss of data stored in the persistent memory region.
210 Therefore, data should be backed up to other storage before
211 executing this command. Targets may be limited to individual PMem
212 modules or sockets, but all PMem modules on affected sockets must
213 be configured when the command finishes. If the selected targets
214 make this impossible, the command will be rejected. Refer to [Show
215 System Capabilities] for a list of BIOS supported modes.
216 • Some requests are dependent on BIOS and/or platform configuration.
218 For details, see the Intel® Optane™ DC Persistent Memory Software
219 Memory Allocation Rules for Windows, Linux and UEFI, document
220 number 564194. For example:
221 • Provisioning PMem modules for Memory Mode while BIOS is
223 configured for 1LM only will result in unused capacity.
224 • Provisioning PMem modules for Memory Mode while not all iMCs
226 have at least one PMem module will result in unused capacity.
227 • PMem modules in population violation can be targeted for goal
229 creation only if PersistentMemoryType=AppDirectNotInterleaved and
230 no volatile memory is requested (100% ADx1).
231
233 Minor adjustments (up to 10%) in the requested capacities are sometimes
234 necessary to align properly according to the platform rules. There are
235 also some situations that require additional confirmation from the user
236 because they may result in a non- optimal configuration (i.e., reduced
237 performance). These are described below.:
238 The requested goal may result in a non-optimal configuration due to the
240 population of PMem modules in the system.
241 Memory Mode capacity requested but the population of DRAM DIMMs and
242 PMem modules in the system may result in reduced performance (i.e., the
243 ratio of DRAM and PMem modules is not balanced, DRAM and PMem modules
244 are not on the same channel or not all the same size).
245 The requested goal may result in a non-optimal configuration due to the
247 population of PMem modules in the system.
248 App Direct capacity requested but the population of PMem modules in the
249 system may result in reduced performance (i.e., PMem modules are not
250 the same size or populated asymmetrically across the socket).
251 The requested goal will result in App Direct capacity which is not
253 supported by the host software.
254 App Direct capacity requested but App Direct is not supported by the
255 currently installed host software.
256 The requested goal will result in Memory Mode capacity that is unusable
258 with the currently selected platform BIOS volatile mode.
259 Memory Mode capacity requested by the platform BIOS is currently set to
260 1LM Mode.
261 The requested goal was adjusted more than 10% to find a valid
263 configuration.
264 > 10% adjustment from the requested goal
265 The amount of mapped memory was limited based on the SKU resulting in
267 un-mapped capacity.
268 Mapped memory was limited based on the CPU SKU.
269 Therefore, before making any changes to the configuration, a prompt is
271 displayed showing the memory allocation goals that will be created on
272 each PMem module as documented in the command Section [Show Memory
273 Allocation Goal], along with any additional confirmation messages. The
274 force option can be used to override this confirmation and proceed
275 directly with creating the goals.
276 The following configuration will be applied:
278 SocketID DimmID MemorySize AppDirect1Size AppDirect2Size (Refer to
279 the command Section <<Show Memory Allocation Goal>>)
280 [Additional Confirmation Messages (see above)] Do you want to
281 continue?
282ipmctl 2023-07-20 IPMCTL-CREATE-GOAL(1)