NAME

       ipmctl-load-goal - Creates a memory allocation goal request from a file

SYNOPSIS

           ipmctl load [OPTIONS] -source (path) -goal [TARGETS]

DESCRIPTION

       Creates a memory allocation goal request from a file onto one or more PMem modules.

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

       -lpmb
           Used to specify large transport payload size for the current invocation of ipmctl.

       -spmb
           Used to specify small transport payload size for the current invocation of ipmctl.

           Note

           The -lpmb and -spmb 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]
           Loads the memory allocation goal onto specific PMem modules by supplying one or more comma separated
           PMem module identifiers. This list must include all unconfigured PMem modules on the affected
           sockets. The default is to load the memory allocation goal onto all manageable PMem modules.

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

EXAMPLES

       Loads the configuration settings stored in "config.txt" onto all the PMem modules in the system as a
       memory allocation goal to be applied by the BIOS on the next reboot.

           ipmctl load -source config.txt -goal

       Loads the configuration settings stored in "config.txt" onto a specified set of PMem modules as a memory
       allocation goal to be applied by the BIOS on the next reboot.

           ipmctl load -source config.txt -goal -dimm 1,2,3

       Loads the configuration settings stored in "config.txt" onto all manageable PMem modules on sockets 1 and
       2 as a memory allocation goal to be applied by the BIOS on the next reboot.

           ipmctl load -source config.txt -goal -socket 1,2

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

       •   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 Specification 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.

RETURN DATA

       If successful, the CLI will display the memory allocation goal stored on each PMem module as documented
       in the command Section [Show Memory Allocation Goal]. If a failure occurs, an error code and message will
       be displayed. If a failure occurs when configuring multiple PMem modules, the process will exit and
       remove the memory allocation goal from any PMem modules that succeeded prior to the failure.

ipmctl                                             2024-04-22                                IPMCTL-LOAD-GOAL(1)