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
100               Not-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           Device 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
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, refer to the Intel® Optane™ Persistent Memory Software
219           Memory Allocation Rules, document number 564194. For example:
220
221       ·   Provisioning PMem modules for Memory Mode while BIOS is configured
222           for 1LM only will result in unused capacity.
223
224       ·   Provisioning PMem modules for Memory Mode while not all iMCs have
225           at least one PMem module will result in unused capacity.
226
227       ·   PMem modules in population violation can be targeted for goal
228           creation only if PersistentMemoryType=AppDirectNotInterleaved and
229           no volatile memory is requested (100% ADx1).
230

RETURN DATA

232       Minor adjustments (up to 10%) in the requested capacities are sometimes
233       necessary to align properly according to the platform rules. There are
234       also some situations that require additional confirmation from the user
235       because they may result in a non- optimal configuration (i.e., reduced
236       performance). These are described below.:
237
238       The requested goal may result in a non-optimal configuration due to the
239       population of PMem modules in the system.
240       Memory Mode capacity requested but the population of DRAM DIMMs and
241       PMem modules in the system may result in reduced performance (i.e., the
242       ratio of DRAM and PMem modules is not balanced, DRAM and PMem modules
243       are not on the same channel or not all the same size).
244
245       The requested goal may result in a non-optimal configuration due to the
246       population of PMem modules in the system.
247       App Direct capacity requested but the population of PMem modules in the
248       system may result in reduced performance (i.e., PMem modules are not
249       the same size or populated asymmetrically across the socket).
250
251       The requested goal will result in App Direct capacity which is not
252       supported by the host software.
253       App Direct capacity requested but App Direct is not supported by the
254       currently installed host software.
255
256       The requested goal will result in Memory Mode capacity that is unusable
257       with the currently selected platform BIOS volatile mode.
258       Memory Mode capacity requested by the platform BIOS is currently set to
259       1LM Mode.
260
261       The requested goal was adjusted more than 10% to find a valid
262       configuration.
263       > 10% adjustment from the requested goal
264
265       The amount of mapped memory was limited based on the SKU resulting in
266       un-mapped capacity.
267       Mapped memory was limited based on the CPU SKU.
268
269       Therefore, before making any changes to the configuration, a prompt is
270       displayed showing the memory allocation goals that will be created on
271       each PMem module as documented in the command Section [Show Memory
272       Allocation Goal], along with any additional confirmation messages. The
273       force option can be used to override this confirmation and proceed
274       directly with creating the goals.
275
276           The following configuration will be applied:
277           SocketID DimmID MemorySize AppDirect1Size AppDirect2Size (Refer to
278           the command Section <<Show Memory Allocation Goal>>)
279           [Additional Confirmation Messages (see above)] Do you want to
280           continue?
281
282
283
284ipmctl                            2020-05-01             IPMCTL-CREATE-GOAL(1)
Impressum