// 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. By default all tests are run.
  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 conforms 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[]