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.