// 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
--------
[verse]
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 DCPMM 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 DCPMMs have a consistent security
    state. It's a best practice to enable security on all DCPMMs rather than
    just some.
  - "FW" - This test verifies that all DCPMMs 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 DCPMM model just that
    it's been consistently applied across the system.

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

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

Starts the quick check diagnostic on DCPMM 0x0001
[verse]
ipmctl start -diagnostic Quick -dimm 0x0001

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

RETURN DATA
-----------
Each diagnostic generates one or more log messages. A successful test generates a
single log message per DCPMM 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
|
* Dimm specs
* Duplicate Dimm
* 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[]