// Copyright (c) 2018, Intel Corporation.
// SPDX-License-Identifier: BSD-3-Clause

ifdef::manpage[]
ipmctl-load-goal(1)
===================
endif::manpage[]

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

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

DESCRIPTION
-----------
Creates a memory allocation goal request from a file onto one or more DCPMMs.

NOTE: Deleting the PCD can be used as a way to prepare individual DCPMMs for provisioning.
See the delete -pcd command.

include::../ipmctl-command-data-loss-warning.txt[]
include::../ipmctl-change-goal-config-note.txt[]

OPTIONS
-------
-f::
-force::
    Reconfiguring DCPMMs 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.

ifdef::os_build[]
-o (text|nvmxml)::
-output (text|nvmxml)::
    Changes the output format. One of: "text" (default) or "nvmxml".
endif::os_build[]

-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 DCPMMs by supplying one or more
  comma separated DCPMM identifiers. This list must include all unconfigured
  DCPMMs on the affected socket(s). The default is to load the memory
  allocation goal onto all manageable DCPMMs.

-socket [SocketIds]::
  Loads the memory allocation goal onto all manageable DCPMMs 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 DCPMMs on all sockets.

EXAMPLES
--------
Loads the configuration settings stored in "config.txt" onto all the DCPMMs in
the system as a memory allocation goal to be applied by the BIOS on the next
reboot.
[verse]
ipmctl load -source config.txt -goal

Loads the configuration settings stored in "config.txt" onto a specified set of
DCPMMs as a memory allocation goal to be applied by the BIOS on the next reboot.
[verse]
ipmctl load -source config.txt -goal -dimm 1,2,3

Loads the configuration settings stored in "config.txt" onto all manageable
DCPMMs on sockets 1 and 2 as a memory allocation goal to be applied by the BIOS
on the next reboot.
[verse]
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 DCPMM(s) must be manageable by the host software and
  must all have the same SKU.

- SKU based maximum total mapped memory is enforced. See section <<Maximum Mapped Memory Limiting>>

- Existing memory allocation goals that have not been applied and any namespaces
  associated with the requested DCPMM(s) must be deleted before running
  this command.

- Goal requests may not be applied by platform firmware (BIOS) if the DCPMM 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 DCPMM is in security state enabled, but care
  must be taken to ensure the DCPMM 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 DCPMMs or sockets, but all DCPMMs
  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, refer
  to the _Intel(R) Optane(TM) DC Persistent Memory Software Memory Allocation Rules_,
  document number 564194. For example:
 - Provisioning DCPMMs for Memory Mode while BIOS is configured for 1LM only
   will result in unused capacity.
 - Provisioning DCPMMs for Memory Mode while not all iMCs have at least one DCPMM
   will result in unused capacity.

RETURN DATA
-----------
If successful, the CLI will display the memory allocation goal stored on each
DCPMM 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 DCPMMs, the process will exit and remove the
memory allocation goal from any DCPMMs that succeeded prior to the failure.
