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

ifdef::manpage[]
ipmctl-run-diagnostic(1)
========================
endif::manpage[]

NAME
----
ipmctl-start-diagnostic - Starts a diagnostic test

ifndef::manpage[]
For a complete list of diagnostic test results, refer to addendum
section <<Diagnostic Events>>.
endif::manpage[]

SYNOPSIS
--------
[listing]
ipmctl start [OPTIONS] -diagnostic [TARGETS]

DESCRIPTION
-----------
Starts a diagnostic test.

OPTIONS
-------
-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[]

TARGETS
-------
-diagnostic [Quick|Config|Security|FW]::
  Start a specific test by supplying its name. All tests are run by default.
  One of:
  - "Quick" - This test verifies that the PMem module host mailbox is accessible and
    that basic health indicators can be read and are currently reporting
    acceptable values.
  - "Config" - This test verifies that the BIOS platform configuration matches
    the installed hardware and the platform configuration conform to best known
    practices.
  - "Security" - This test verifies that all PMem modules have a consistent security
    state. It is a best practice to enable security on all PMem modules rather than
    just some.
  - "FW" - This test verifies that all PMem modules of a given model have consistent
    FW installed and other FW modifiable attributes are set in accordance with
    best practices. +
    Note that the test does not have a means of verifying that
    the installed FW is the optimal version for a given PMem module model just that
    it has been consistently applied across the system.

-dimm [DimmIDS]::
  Starts a diagnostic test on specific PMem modules by optionally supplying one or more
  comma separated PMem module identifiers. The default is to start the specified tests
  on all manageable PMem modules. Only valid for the Quick diagnostic test.

EXAMPLES
--------
Starts all diagnostics.
[listing]
ipmctl start -diagnostic

Starts the quick check diagnostic on PMem module 0x0001.
[listing]
ipmctl start -diagnostic Quick -dimm 0x0001

LIMITATIONS
-----------
If a PMem module is unmanageable, then Quick test will report the reason, while
Config, Security and FW tests will skip unmanageable PMem modules.

RETURN DATA
-----------
Each diagnostic generates one or more log messages. A successful test generates a
single log message per PMem module indicating that no errors were found. A failed test
might generate multiple log messages each highlighting a specific error with all
the relevant details. Each log contains the following information.

Test::
  The test name along with overall execution result. One of:
  - "Quick"
  - "Config"
  - "Security"
  - "FW"

State::
  The collective result state for each test. One of:
  - "Ok"
  - "Warning"
  - "Failed"
  - "Aborted"

Message::
  The message indicates the status of the test. One of:
  - "Ok"
  - "Failed"

SubTestName::
  The subtest name for given Test.
[cols="1,2a", options="header"]
|===
|Test Name
|Valid SubTest Names

|Quick
|
* Manageability
* Boot status
* Health

|Config
|
* PMem module specs
* Duplicate PMem module
* System Capability
* Namespace LSA
* PCD

|Security
|
* Encryption status
* Inconsistency

|FW
|
* FW Consistency
* Viral Policy
* Threshold check
* System Time
|===

State::
  The severity of the error for each sub-test displayed with SubTestName. One of:
  - "Ok"
  - "Warning"
  - "Failed"
  - "Aborted"

ifdef::manpage[]
include::ipmctl-diagnostic-events.txt[leveloffset=+1]
endif::manpage[]