Issuing Resets

There are two ways to issue resets within your scripts.
The recommended method is to use the function issue_reset in the Test API.
The other option is to use the XML API, with the function get_vlun_nvme_update_controller.

issue_reset

issue_reset provides a wrapper around XML_API.get_vlun_nvme_update_controller.

It automatically handles and reports any errors that occur during execution, and parses the XML API response into a form that is easier to use.

issue_reset(dut, reset, reset_type=None, shutdown_mode=None, fail_type='error', skip_type='action')
dut : XML_API
The DUT the reset will be executed on.
reset : int or str
An integer 0-3 or string indicating which reset will be performed. See Reset Options
reset_type : int Optional
An integer 0-3 specifying the reset type (controller reset only):
0 : Normal (no shutdown)
1 : Shut down before reset
2 : Shut down after reset
3 : Shut down before and wait after reset
shutdown_mode : int Optional
An integer 0-3 specifying the shutdown mode (controller reset only):
0 : Normal, delete queues
1 : Abrupt, preserve queues
2 : Normal, preserve queues
3 : Abrupt, delete queues
fail_type : int or str Optional
Specifies the action to be taken if the reset fails:
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment the warnings counter
3 or 'error' : Log an ERROR and increment the errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type : int or str Optional
Specifies the skip behavior if the reset is not supported:
0 or 'none' : Do not skip. Proceed and attempt the reset
1 or 'action' : Do not attempt the reset. Return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Reset Options

issue_reset supports Controller Resets, NVM Subsystem Resets, PCIe Conventional Resets, and PCIe Function Resets.

For your convenience, there are multiple valid arguments that can be passed into the reset parameter for each reset type.

The simplest method is to use an integer from 0-3. They will result in the following:

0 : Controller Reset
1 : NVM Subsystem Reset
2 : PCIe Conventional Reset
3 : PCIe Function Reset

If you would like to be more descriptive, any passed string will be converted to lowercase and have all whitespace removed before being compared against the following options:

Controller Reset:
ncr controller controllerreset resetcontroller

NVM Subsystem Reset:
nvm nvme nssr nvmsubsystem nvmesubsystem nvmreset nvmereset

PCI Conventional Reset:
pci pcie pciconventional pcieconventional pciereset pcireset

PCI Function Reset:
flr pcifunction pciefunction pciefunctionreset pcifunctionreset

All of the following are valid:

issue_reset(dut)
issue_reset(dut, 2)
issue_reset(dut, "ncr")
issue_reset(dut, "n   v   m   e")
issue_reset(dut, "PCIe Reset")
issue_reset(dut, "pci FUNCTION reset")
issue_reset(dut, "pcireset")

Successful Reset

Here is a simple example of a NVM Subsystem Reset being issued in a single-port test:

# .. Test settings ..

def main(test_config):
    @setup(test_config)
    def test(dut):

        result = issue_reset(dut, "NSSR")

        print(result)

Printed result:

{'status': 0, 'reason': 'Successfully issued NVM subsystem reset on target 100'}

Logged messages:

Mon Jan 03 10:49:44 2022 ACTION: Issuing NVM subsystem reset on target 100
Mon Jan 03 10:49:44 2022 ACTION: Issuing API command: get_vlun_nvme_update_controller(valid_command='NvmeReset')
Mon Jan 03 10:49:45 2022 DETAIL: Successfully issued NVM subsystem reset on target 100