SANBlaze Test API Actions¶

AER_clear(dut)¶

Clear the AER counters for the target

Parameters

dut (XML_API) – The controller to clear the AER register from

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

Example

Clear the AER counters:

result = AER_clear(dut)

Note

Two other functions related to AER are AER_enable and AER_read

AER_enable(value)¶

Enable Advanced Error Reporting (AER). By default is this set to 0 (disabled)

Parameters

value (int) –

Desired setting of AER enable

1: Enable

2: Disable

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

Examples

Enable AER:

result = AER_enable(dut, 1)

Disable AER:

result = AER_disable(dut, 0)

Note

Two other functions related to AER are AER_clear and AER_read

AER_read(dut, fail_type='error')¶

Read the AER registers for the target.

Parameters

dut (XML_API) – The controller to read the AER register from
fail_type (int or str) –

Specifies the action to be taken if the read fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

status: int: 0 for success, 1 for failure
result: str: The current AER register content of the device
reason: str: A brief explanation of the result

Return type

dict

Example

Read the AER entries:

result = AER_read(dut)

Note

Two other functions related to AER are AER_enable and AER_clear

ASPM_enable(dut, state, fail_type='error', skip_type='action')¶

ASPM_enable provides access to Advance State Power Management control. It disables the watchdog when a low power state is requested and resumes the watchdog when the state is exited through this command.

ASPM enable will only change the state of the drive if the following feature is set:

dut.set_feature(feature_id=0x02, page_control=0, feature_data=3)

Parameters

dut (XML_API) – The controller to change ASPM enable on
state (int or str) –
0 : ASPM not enabled

1 : L0s is enabled

2 : L1 is enabled

3 : L0s and L1 are both enabled
fail_type (int or str) –

Specifies the action to be taken if the enable fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

Example

Enable the L1 power state:

result = ASPM_enable(dut, 2)

Disable ASPM:

result = ASPM_enable(dut, 0)

Note

Two other functions related to ASPM are get_ASPM_state and get_ASPM_support

L1PM_enable(dut, state, fail_type='error', skip_type='action')¶

Enable L1.1 and L1.2 power states through either PM or ASPM. Valid state values are 0-9 and A-F.

Parameters

dut (XML_API) – The controller to enable the L1PM state on
state (byte) –
bit 0 : PM L1.2 Enable

bit 1 : PM L1.1 Enable

bit 2 : ASPM L1.2 Enable

bit 3 : ASPM L1.1 Enable
fail_type (int or str) –

Specifies the action to be taken if the enable fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

Example

ASPM L1.2 Enable and PM L1.1 Enable (binary: 0110):

result = L1PM_enable(dut, 6)

ASPM L1.1 Enable:

result = L1PM_enable(dut, 8)

ASPM L1.1 Enable and PM L1.1 Enable (binary: 1010):

result = L1PM_enable(dut, ‘A’)

OR

result = L1PM_enable(dut, ‘a’)

Note

Two other functions related to L1PM are get_L1PM_support and get_L1PM_state

PM_enable(dut, state, fail_type='error', skip_type='action')¶

PM_enable provides access to Power Management control. States 0 through 3, or D0 through D3 can be enabled.

Parameters

dut (XML_API) – The controller enable PM states on
state (int) –
0 : PM state D0

1 : PM state D1

2 : PM state D2

3 : PM state D3
fail_type (int or str) –

Specifies the action to be taken if the enable fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

Examples

Enable the D1 power state:

result = PM_enable(dut, 1)

Enable D3 hot entry:

result = PM_enable(dut, state=3)

Note

Two other functions related to PM are get_PM_state and get_PM_support

attach_namespace(dut, nsid, fail_type='error', skip_type='action')¶

Attach the namespace with NSID equal to nsid to dut

Parameters

dut (XML_API) – The controller to attach the namespace to
nsid (int) – The NSID of the namespace to attach
fail_type (int or str) –

Specifies the action to be taken if the attachment fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if namespace management is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status: int: 0 if the attach succeeded, 1 if it failed
reason: str: A brief explanation of the result

Return type

dict

create_namespace(dut, config, fail_type='error', skip_type='action')¶

Create namespaces with the settings defined in config

Parameters

dut (XML_API) – The controller under which the namespaces will be created
config (dict) – A dictionary containing configuration parameters for the new namespaces
fail_type (int or str) –

Specifies the action to be taken if the creation fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if namespace management is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

statusint: 0 if the creation was successful, 1 otherwise
nsidslist of int: A list containing the newly created NSIDs. Empty if none created
reasonstr: A brief explanation of the result

Return type

dict

Example

Create 3 private 1GB namespaces:

configuration = {
    'create_num': 3,
    'create_size': '1gb',
    'create_priv': 1
}

create_namespace(dut, configuration)

create_submission_queue(dut, fail_type='error')¶

Create a submission queue with ID 1

Parameters

dut (XML_API) – The controller on which to create the submission queue
fail_type (int or str) –

Specifies the action to be taken if creation fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

delete_submission_queue(dut, fail_type='error')¶

Delete the submission queue with ID 1

Parameters

dut (XML_API) – The controller on which to delete the submission queue
fail_type (int or str) –

Specifies the action to be taken if the deletion fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

detach_namespace(dut, nsid, fail_type='error', skip_type='action')¶

Detach the namespace with NSID equal to nsid from dut

Parameters

dut (XML_API) – The controller to attach the namespace to
nsid (int) – The NSID of the namespace to attach
fail_type (int or str) –

Specifies the action to be taken if the detachment fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if namespace management is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status: int: 0 if the detach succeeded, 1 if it failed
reason: str: A brief explanation of the result

Return type

dict

do_write(dut, num_blocks, hex_data, error_code, method=1)¶

Write num_blocks worth of hex_data to dut. Expect error_code

Parameters

dut (XML_API) – The dut to write the data to
num_blocks (int) – The number of LBAs to write to
hex_data (str) – The data to write
error_code (str) – The expected error code
method (int) – 1 : Don’t expect failure, 2 : expect failure

Returns

Return type

None

get_ASPM_state(dut)¶

Provides the current enabled ASPM state. Possible states are 0 thorough 3, which correspond to

0 : ASPM not enabled

1 : L0s is enabled

2 : L1 is enabled

3 : L0s and L1 are both enabled

Parameters

dut (XML_API) – The controller to read the ASPM state from

Returns

status: int: 0 for success, 1 for failure
state: str: ASPM state
reason: str: A brief explanation of the result

Return type

dict

Example

Get the current ASPM state:

state = find_in(get_ASPM_state(dut), 'state')

Note

Two other functions related to ASPM are ASPM_enable and get_ASPM_support

get_ASPM_support(dut, fail_type='error')¶

Provides the controller level of support for PM control. Valid values are 0 through 3, which correspond to the values listed below.

Parameters

fail_type –
dut (XML_API) – The controller to get ASPM support from

Returns

status: int

0 for success, 1 for failure

support: int

Integer with the details of the ASPM support

0 : ASPM not enabled

1 : L0s is enabled

2 : L1 is enabled

3 : L0s and L1 are both enabled

reason: str

A brief explanation of the result

Return type

dict

Example

Get the supported ASPM states for the controller:

support = find_in(get_ASPM_state(dut), 'support')

Note

Two other functions related to ASPM are ASPM_enable and get_ASPM_state

get_L1PM_state(dut)¶

Provides the current enabled L1PM state. Possible states are 0x0 thorough 0xF, which correspond to

bit 0 : PM L1.2 Enable

bit 1 : PM L1.1 Enable

bit 2 : ASPM L1.2 Enable

bit 3 : ASPM L1.1 Enable

Parameters

dut (XML_API) – The controller to read the L1PM state from

Returns

status: int: 0 for success, 1 for failure
state: str: L1PM state
reason: str: A brief explanation of the result

Return type

dict

Example

Get the current L1PM state:

state = find_in(get_L1PM_state(dut), 'state')

Note

Two other functions related to L1PM are L1PM_enable and get_L1PM_support

get_L1PM_support(dut)¶

Provides the controller level of support for PM control. Valid values are 0 through 3, which correspond to the values listed below.

Parameters

dut (XML_API) – The controller to read the L1PM support from

Returns

status: int

0 for success, 1 for failure

support: str

Binary string with the details of the L1PM support

Bit 0 : PM L1.2 Enable

Bit 1 : PM L1.1 Enable

Bit 2 : ASPM L1.2 Enable

Bit 3 : ASPM L1.1 Enable

reason: str

A brief explanation of the result

Return type

dict

Example

Get the supported L1PM states for the controller:

support = find_in(get_L1PM_state(dut), 'support')

Note

Two other functions related to L1PM are L1PM_enable and get_L1PM_state

get_PM_state(dut)¶

Provides the current enabled PM power state. Possible states are 0 thorough 3, which correspond to power states D0 through D3.

Parameters

dut (XML_API) – The controller to read the PM state from

Returns

status: int: 0 for success, 1 for failure
state: str: PM state
reason: str: A brief explanation of the result

Return type

dict

Example

Get the current PM state:

state = find_in(get_PM_state(dut), 'state')

Note

Two other functions related to PM are PM_enable and get_PM_support

get_PM_support(dut)¶

Provides the controller level of support for PM control. Valid values are 0x0 through 0xF, which correspond to the bit mask values listed below.

Parameters

dut (XML_API) – The controller to get the PM support from

Returns

status: int

0 for success, 1 for failure

support: int

Binary string with the details of the PM support (0: not supported, 1: supported)

Bit 0 : PM support of state D1

Bit 1 : PM support of state D1

Bit 2 : PM support of state D2

Bit 3 : PM support of state D3

reason: str

A brief explanation of the result

Return type

dict

Example

Get the supported PM states for the controller:

support = find_in(get_PM_state(dut), 'support')

Note

Two other functions related to PM are PM_enable and get_PM_state

get_current_link_speed(dut)¶

Get the current link speed as an integer from bits[3:0] of the Link Status Register.

The supported link speeds are 1, 2, 3, 4, and 5 which are correlated to PCIe Gen1 (2.5GT/s), Gen2 (5.0GT/s), Gen3 (8.0GT/s), Gen4 (16.0GT/s) and Gen5 (32.0GT/s) speed

Parameters

dut (XML_API) – Controller on which to get the link speed

Returns

-1 (int) – Could not determine link speed
1, 2, 3, 4, 5 (int) – Link speed

Example

Get the link speed of a controller:

link_speed = get_link_speed(dut)

get_current_link_width(dut, fail_type='error')¶

Get the current link width as an integer.

The supported link widths are 1, 2, and 4 which are correlated with the link width 1x, 2x, and 4x.

Parameters

dut (XML_API) – Controller on which to get the link speed
fail_type (int or str) –

Specifies the action to be taken if getting the link width fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

-1 (int) – Could not determine link width
1, 2, 3 (int) – link width

Example

Get the link width of the controller:

link_width = get_link_width(dut)

Note

Two other functions related to link width are set_link_width and get_max_link_width

get_max_link_speed(dut, fail_type='test')¶

Parameters: dut (XML_API) – Controller on which to get the link speed
Returns: 1, 2, 3, 4, 5 – Link Speed
Return type: int

Example

Get the max link speed of a controller:

max_link_speed = get_max_link_speed(dut)

get_max_link_width(dut)¶

Get the maximum link width supported by the device

Parameters: dut (XML_API) – Controller on which to get the link width
Returns: 1, 2, 4 – Max link width
Return type: int

Example

Get the max link width of a controller:

max_link_width = get_max_link_width(dut)

Note

Two other functions related to link width are get_current_link_width and set_link_width

iSleep(sleeptime, quiet=0)¶

Pause test execution for sleeptime ms but remain responsive to commands

Parameters

sleeptime (int) – Time of interruptable sleep, in ms
quiet (int) – 0 or 1, whether to log a message when the sleep begins

Returns

The time spent sleeping

Return type

int

Examples

Sleep for 10 seconds without quiet enabled:

iSleep(10000)

Logged message:

Mon Sep 13 15:19:46 2021 DETAIL: iSleep for 10.0S

issue_reset(dut, reset, reset_type=None, shutdown_mode=None, fail_type='error', skip_type='action')¶

Issue the specified reset on the given dut

Issue a controller reset, NVM subsystem reset, PCIe conventional reset, or PCI function reset. If a controller reset is being issued, reset_type and shutdown_mode may be specified. In other cases they will be ignored.

Parameters

dut (XML_API) – Controller on which to issue the reset
reset (int or str) – The type of reset to be performed
reset_type (int) – 0-3, specifies behavior of controller reset
shutdown_mode (int) – 0-3, specifies behavior of shutdown if applicable
fail_type (int or str) –

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 warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if the specified reset is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

statusint: 0 or 1, indicating success or failure respectively
reasonstr: Explanation of the result

Return type

dict

Notes

Any string passed into reset will be converted to lowercase and have all whitespace removed:

"ContRoller ResEt  " -> "controllerreset"

Examples

Issuing a controller reset with reset_type of 1:

issue_reset(dut, "ControllerReset", 1)

Issuing a PCIe function reset, using the shortened name:

issue_reset(dut, "flr")

power_cycle(dut, wait=True, fail_type='test', ready_wait_time=120)¶

Perform a graceful power cycle of a single or dual port device. If a quarch is connected and specified using the ‘use_quarch’ keyword in /virtualun/python.conf, then the function redirects to power_Cycle_quarch.

Parameters

dut –
wait –
fail_type –

Returns

Return type

None

power_cycle_quarch(dut, sn=None, wait=True, fail_type='test', ready_wait_time=120)¶

Power cycle the device using the connected quarch device and the DOWN and UP commands.

Parameters

dut –
wait –
fail_type –

Returns

Return type

None

read_bits(dut, offset=0, start=0, end=None, fail_type='error')¶

Read bits [start, end] from the controller property at offset

Parameters

dut (XML_API) – The device from which to read the bits
offset (int) – Hexadecimal offset to read from. MUST take form 0x.. or be equivalent decimal value
start (int) – 0-63. Starting bit of range to read
end (int) – 0-63. Ending bit of range to read. Optional
fail_type (int or str) –

Specifies the action to be taken if the reading the bits fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

Value of bits read, or None if read failed

Return type

int

read_ltssm_state(dut, fail_type='error')¶

Read and return the PCIe LTSSM state of the device specified by dut

Parameters

dut (XML_API) – The controller to read the LTSSM state from
fail_type (int or str) –

Specifies the action to be taken if state cannot be read
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

status: int: 0 for success, 1 for failure
state: str: The current LTSSM state of the device
substate: str: The current LTSSM substate of the device
reason: str: A brief explanation of the result

Return type

dict

ready_controller(dut, skip_if_ready=1, fail_type='test')¶

Use hot plug button to return controller to ready state (green)

Parameters

dut (XML_API) – The controller to be returned to ready state
skip_if_ready (int) – If 1, return immediately if controller is ready. If 0, don’t check
fail_type (int or str) –

Specifies the action to be taken if the operation fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Notes

skip_if_ready=0 allows the function to be used to cycle the controller. The function will always end with the controller in a ready state.

Returns
Return type: None

self_test(dut, _type, nsid=1, timeout=300, fail_type='error')¶

Performs the device self test indicated and wait for test completion. If test percent complete does not advance in ‘timeout’ time, the action will fail with the fail_type indicated.

When the test is complete, the Self Test Result will be checked to verify that bits 3:0 are 0.

Parameters

dut (XML_API) – The controller to run the self-test on
_type (int) – Version of self test to run. 1: short, 2: extended
nsid (int) – The namespace to run the self test on
timeout (int) – Seconds to wait for the percent complete to advance. Defaults to 300s
fail_type (int or str) –

Specifies the action to be taken if the detachment fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

send_pme_turn_off(dut, timeout=60, fail_type='error')¶

Send PCIe PME_Turn_Off for the device specified by dut

Parameters

dut (XML_API) – The controller on which to issue the PME_Turn_Off
timeout (int) – The duration to wait for the turn off to complete before failing
fail_type (int or str) –

Specifies the action to be taken if the send fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

status: int: 0 for success, 1 for failure
reason: str: A brief explanation of the result

Return type

dict

set_PERST(dut, write, glitch_usec=None, fail_type='error', wait=False, timeout=60)¶

Set PERST to write. Set to original state after glitch_usec if specified.

Parameters

dut (XML_API) – Controller on which to set PERST
write (int) – 0 or 1, the state to be written to PERST
glitch_usec (int) – Number of microseconds to hold written state if specified
fail_type (int or str) –

Specifies the action to be taken if setting PERST fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

statusint: 0 or 1, indicating success or failure respectively
reasonstr: Explanation of the result

Return type

dict

Examples

Setting PERST to 0:

set_PERST(dut, 0)

Setting PERST to 0 for 0.1 seconds:

set_PERST(dut, 0, 100000)

set_link_speed(dut, speed)¶

Set the link speed to a supported value. The supported link speeds are 1, 2, 3, 4, 5 which are correlated to PCIe Gen1 (2.5GT/s), Gen2 (5.0GT/s), Gen3 (8.0GT/s) Gen4 (16.0GT/s) and Gen5(32.0GT/s) speed. Any value for speed other than 1, 2, 3, 4, 5 will raise a ValueError.

Parameters

dut (XML_API) – Controller on which to get the link speed
speed (int) – The desired link speed of the device (1, 2, 3, 4, 5)

Example

Retrain the link width to 4:

set_link_speed(dut, 4)

set_link_width(dut, requested_link_width, fail_type='error', skip_type='action')¶

Train the link width to a supported value. The supported link widths are 1, 2, and 4 which are correlated to 1x, 2x, and 4x link widths. Any value for width other than 1, 2, 4 will raise a ValueError.

Parameters

dut (XML_API) – Controller on which to get the link width
requested_link_width (int) –
The desired link width of the device (1, 2, 4)

1: 1x

2: 2x

4: 4x
fail_type (int or str) –

Specifies the action to be taken if setting the link width fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if the link width is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Example

Retrain the link width to 4:

set_link_width(dut, 4)

Note

Two other functions related to link width are get_current_link_width and get_max_link_width

set_queues(dut, sq_count=0, cq_count=0, queue_depth=0, fail_type='error', skip_type='test')¶

Sets the queue count and queue depth for an NVMe controller. After the queue count is updated, the controller is reset and the reset is verified. As a final step this interrogates the controller to verify the new queue count and queue depth.

If any part of this process fails, the fail_type action will occur.

Parameters

dut (XML_API) – Controller on which to set queues
cq_count (Int) – Desired completion queue count (Optional, defaults to 0: 1:1 queue pair)
sq_count (Int) – Desired submission queue count (Optional, defaults to 0: PCIe NVMe: number of CPUs, Fabric NVMe: 4)
queue_depth (Int) – Desired queue depth (Optional, defaults to 0: PCIe NVMe:1024, Fabric NVMe:124)
fail_type (int or str) –

Specifies the action to be taken if setting the queues fails
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test
skip_type (int or str) –

Specifies the skip behavior if the queue configuration is not supported
0 or 'none' : Do not skip. Proceed with the action
1 or 'action' : Log a SKIPPED message and return immediately
2 or 'test' : Immediately skip the remainder of the entire test

Returns

status – 1

Return type

int

Notes

After the queue count is updated, the controller is reset and the reset is verified. As a final step this interrogates the controller to verify the new queue count and queue depth.

If any part of this process fails, the script will fail and exit.

Examples

Create a 1:1 queue pair with 6 queues and a queue depth of 256:

set_queues( dut, sq_count=6, cq_count=6, queue_depth=256)

Set the submission queue count to 1, the completion queue count to 1, don’t modify the queue depth:

set_queues(dut)                                          # Use default parameters
set_queues(dut, sq_count=1, cq_count=1, queue_depth=1)   # Specify parameters explicitly

Set the submission queue count to 6, the completion queue count to 1 and don’t modify the queue depth:

set_queues(dut, sq_count=6, cq_count=1)

surprise_power_cycle(dut, fail_type='test')¶

Perform a surprise power cycle of a single or dual port device (this is a slightly modified version of power_cycle() from sanblaze_test_api_actions.py)

Parameters

dut (XML_API) – Device object under test
fail_type (str) – At which level to fail the test

Returns

Return type

None

wait_for_controller(dut, timeout, fail_type='error')¶

Delay program execution until control responds to a controller ready signal

Parameters

dut (XML_API) – Controller on which to issue the reset
timeout (int) – Max time to wait for controller to return(s)
fail_type (int or str) –

Specifies the action to be taken if the function times out
0 or 'pass' : Log a PASS
1 or 'notify' : Log a NOTE
2 or 'warn' : Log a WARNING and increment warnings counter
3 or 'error' : Log an ERROR and increment errors counter
4 or 'test' : Log an ERROR and immediately fail the entire test

Returns

0 if controller became ready, 1 if timeout was reached

Return type

int

Notes

To determine if the controller is ready, program waits for a valid status from the following call:

result = dut.get_proc_target_info()

The result is then analyzed. If find_in(result, "ControllerReady") == 1, the controller is ready and program execution continues. A message is logged indicating that the controller is ready.

If the call was not successful, an error message is logged and add_error() is called.

Example

Issue FLR and wait up to 20 seconds for the controller to be ready:

issue_reset(dut, 'flr')
wait_for_controller(20)

watchdog_disable(dut)¶

Disable the system watchdog

Parameters: dut –
Returns
Return type: None