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

ifdef::manpage[]
ipmctl-erase-device-data(1)
===========================
endif::manpage[]

NAME
----
ifndef::os_build[]
ipmctl-erase-device-data - Erases the persistent data on one or more PMem modules
endif::os_build[]
ifdef::os_build[]
ipmctl-erase-device-data - Erases the persistent data on one or more PMem modules on supported OS
endif::os_build[]

SYNOPSIS
--------
[verse]
ipmctl delete [OPTIONS] -dimm [TARGETS] Passphrase=(string)

DESCRIPTION
-----------
Erases the persistent data on one or more PMem modules. This commands invokes the PMem module 'Secure Erase'
command.

NOTE: This command does not zero out the persistent data, but instead randomizes the data.

ifdef::os_build[]
NOTE: This command is subject to OS Vendor (OSV) support. It will return "Not Supported."
endif::os_build[]

OPTIONS
-------
-f::
-force::
  Erasing PMem module data is a destructive operation which requires confirmation from
  the user for each PMem module. This option suppresses the confirmation.

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

-master::
  Erases PMem modules using master passphrase. Valid only if master passphrase is enabled on specified
  PMem modules (see MasterPassphraseEnabled attribute in section <<Show Device>>).

-default::
  Use this option when the current master passphrase is set to the default value. Valid only
  if used along with the '-master' option. May not be combined with the Passphrase property.

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

-source (path)::
  File path to a local file containing the new passphrase (1-32 characters).

TARGETS
-------
-dimm [DimmIDs]::
Erases specific PMem modules by supplying one or more comma-separated PMem module
identifiers. However, this is not recommended as it may put the system in an
undesirable state. The default is to erase all manageable PMem modules.

PROPERTIES
----------
Passphrase::
  If security state is disabled, then passphrase is not required and will be ignored
  if supplied. +
  If security state is enabled, then a passphrase must be supplied. +
  The current passphrase (1-32 characters). For better passphrase protection, specify
  an empty string (e.g., Passphrase="") to be prompted for the passphrase or to use a
  file containing the passphrase with the source option.

EXAMPLES
--------
Security disabled PMem modules: Erases all the persistent data on all PMem modules in the
system.
[verse]
ipmctl delete -dimm

Security enabled specifics: Erases all the persistent data on all PMem modules in the
system.
[verse]
ipmctl delete -dimm Passphrase=123

Security enabled specifics: Erases all the persistent data on all PMem modules in the
system using the default master passphrase.
[verse]
ipmctl delete -master -default -dimm

Security enabled specifics: Erases all the persistent data on all PMem modules in the
system using the master passphrase.
[verse]
ipmctl delete -master -dimm Passphrase=masterpassphrase

Erases all the persistent data on all PMem modules by having the CLI prompt for
the current passphrase.
[verse]
ipmctl delete -dimm Passphrase=""

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, not be
  in the "Frozen" or "Exceeded" lock states and any namespaces associated with the
  requested PMem modules must be deleted before running this command.

ifdef::os_build[]
The command is subject to OS Vendor (OSV) support. If OSV does not provide
support, the command will return "Not Supported."
endif::os_build[]

RETURN DATA
-----------
If an empty string is provided for the passphrase property and the source option is not
included, the user will be prompted (once for all PMem modules) to enter the current
passphrase. The passphrase characters are hidden.

Current passphrase: ****

For each PMem module, the CLI will indicate the status of the security state change.
If a failure occurs when changing multiple PMem modules, the process will exit and
not continue updating the remaining PMem modules.

SAMPLE OUTPUT
-------------
[verse]
Erase PMem module (DimmID): Success
Erase PMem module (DimmID): Error (Code) - (Description)
