1IPMCTL-CREATE-GOAL(1)               ipmctl               IPMCTL-CREATE-GOAL(1)
2
3
4

NAME

6       ipmctl-create-goal - Creates a memory allocation goal on one or more
7       PMem modules
8

SYNOPSIS

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

DESCRIPTION

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
18           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
25           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
29           Warning
30           This command may result in data loss. Data should be backed up to
31           other storage before executing this command.
32
33           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

OPTIONS

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
49       -h, -help
50           Displays help for the command.
51
52       -ddrt
53           Used to specify DDRT as the desired transport protocol for the
54           current invocation of ipmctl.
55
56       -smbus
57           Used to specify SMBUS as the desired transport protocol for the
58           current invocation of ipmctl.
59
60           Note
61           The -ddrt and -smbus options are mutually exclusive and may not be
62           used together.
63
64       -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
68       -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

TARGETS

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
79            1. Target all PMem modules on a given socket.
80
81               •   For example, all PMem modules located within a single
82                   socket may be specified together using the dimm target.
83
84            2. Target all unconfigured PMem modules
85
86               •   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
90            3. Target PMem modules for 100% MemoryMode with all unspecified
91               PMem modules configured for MemoryMode only
92
93               •   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
98            4. Target PMem modules for App Direct Not Interleaved with all
99               unspecified PMem modules configured for App Direct Not
100               Interleaved only
101
102               •   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
108               Note
109               If the dimm target is not specified, the default is to
110               configure all manageable PMem modules on all sockets.
111
112       -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

PROPERTIES

120       MemoryMode
121           Percentage of the total capacity to use in Memory Mode (0-100).
122           Default = 0.
123
124       PersistentMemoryType
125           If MemoryMode is not 100%, the type of persistent memory to create.
126
127           •   "AppDirect": (Default) Create App Direct capacity utilizing
128               hardware interleaving across the requested PMem modules if
129               applicable given the specified target.
130
131           •   "AppDirectNotInterleaved": Create App Direct capacity that is
132               not interleaved any other PMem modules.
133
134       NamespaceLabelVersion
135           The version of the namespace label storage area (LSA) index block
136
137           •   "1.2": (Default) Defined in UEFI 2.7a - sections 13.19
138
139           •   "1.1": Legacy 1.1 namespace label support
140
141       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

EXAMPLES

148       Configures all the PMem module capacity in Memory Mode.
149
150           ipmctl create -goal MemoryMode=100
151
152       Configures all the PMem module capacity as App Direct.
153
154           ipmctl create -goal PersistentMemoryType=AppDirect
155
156       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
160           ipmctl create -goal MemoryMode=20 PersistentMemoryType=AppDirectNotInterleaved
161
162       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
168           ipmctl create -goal MemoryMode=25 PersistentMemoryType=AppDirect Reserved=25
169

LIMITATIONS

171       In order to successfully execute this command:
172
173       •   The caller must have the appropriate privileges.
174
175       •   The specified PMem modules must be manageable by the host software
176           and must all have the same SKU.
177
178       •   SKU based maximum total mapped memory is enforced. See section [CPU
179           Maximum Mapped Memory Limiting].
180
181       •   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
185       •   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
188       •   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
192       •   Goal requests may not be applied by platform firmware (BIOS) if the
193           PMem module is in security enabled, locked state.
194
195           Note
196           It is recommended to disable security prior to reboot if requesting
197           a new goal.
198
199           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
208       •   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
217       •   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
222           •   Provisioning PMem modules for Memory Mode while BIOS is
223               configured for 1LM only will result in unused capacity.
224
225           •   Provisioning PMem modules for Memory Mode while not all iMCs
226               have at least one PMem module will result in unused capacity.
227
228       •   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

RETURN DATA

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
239       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
246       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
252       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
257       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
262       The requested goal was adjusted more than 10% to find a valid
263       configuration.
264       > 10% adjustment from the requested goal
265
266       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
270       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
277           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?
282
283
284
285ipmctl                            2023-07-20             IPMCTL-CREATE-GOAL(1)
Impressum