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
andAER_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
andAER_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
andAER_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
andget_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
andget_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
andget_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
- 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
andget_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
andget_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
andget_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
andget_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
andget_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
andget_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
andget_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
andset_link_width
- get_power(dut)
Get the slot power using sb_i2c
- Parameters:
dut (API object)
- get_voltage(dut, retries=0)
Get the slot voltage using sb_i2c
- Parameters:
dut (API object)
retries (int) – Number of times try to collect the voltage before failing. Default 0
- 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
- 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
- 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.
- 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
andget_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
- Return type:
None
- wait_for_controller(dut, timeout, fail_type='error', delay=5)
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
delay (int) – Specifies the additional delay after controller and probes are ready.
- 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
- Return type:
None