XML API

class XML_API(tester_IP, port, target, lun=1, verbose=False, decoding=True, raw_return=0, timeout=60, log_file=None, sanblaze=1, legacy=True)

VU_command_pass_through(opcode, fused_operation=0, reserved_field=0, PRP_SGL=0, nsid=None, cdw2=0, cdw3=0, cdw4=0, cdw5=0, cdw6=0, cdw7=0, cdw8=0, cdw9=0, cdw10=0, cdw11=0, cdw12=0, cdw13=0, cdw14=0, cdw15=0, admin_nvm_flag=0, direction='read', transfer_length=4096, file_name='')

The VU_command_pass_through() function is used to pass through any NVMe commands like Admin, NVM, ZNS and any VU(vendor unique) commands as well.

Parameters:

opcode – The opcode identifies operation the command is to perform. Bits 07:00 in CDW0 and required for this API. Opcode values for Admin commands and I/O commands may overlap without causing a problem because Admin commands go to the Admin queues only and the I/O commands go to the I/O queues only.
fused_operation –
Allow the application to “fuse” two commands together. Bits 09:08 in CDW0 and default as 0. Available values are

Value

Definition

00b

Normal Operation

01b

1st fused command

10b

2nd fused command

11b

Reserved
reserved_field – Reserved field as bits 13:10 in CDW0. Default as 0.
PRP_SGL –
Define if a PRP or SGL description is used for the data buffer. Bits 15:14 in CDW0 and default as 0. Available values are as follows:

Value

Definition

00b

PRP

01b

SGL

10b

SGL

11b

Reserved
nsid – Namespace Identifier. If not specified then it will use the NSID when instantiate the object which is the default. User can specify the nsid as 0, -1 (for all namespaces) or others.
cdw2 – Command Dword 2, default as 0. It is reserved in current NVMe 1.4 specification. Allow user to enter just in case user’s VU commands will use it.
cdw3 – Command Dword 3, default as 0. It is reserved in current NVMe 1.4 specification. Allow user to enter just in case user’s VU commands will use it.
cdw4 – Command Dword 4, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw5 – Command Dword 5, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw6 – Command Dword 6, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw7 – Command Dword 7, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw8 – Command Dword 8, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw9 – Command Dword 9, default as 0. In general user doesn’t have to fill it and it will be filled by driver.
cdw10 – Command Dword 10, default as 0.
cdw11 – Command Dword 11, default as 0.
cdw12 – Command Dword 12, default as 0.
cdw13 – Command Dword 13, default as 0.
cdw14 – Command Dword 14, default as 0.
cdw15 – Command Dword 15, default as 0.
admin_nvm_flag – Specify if the command is an Admin command or I/O command (NVM or ZNS). Default as 0 means it is an Admin command, if it is 1 then it is an I/O command like NVM or ZNS command.
direction – Specify if the command will send data to the drive or read data back from the drive. Default as “read”. If specify as “write” then it will send data to the drive.
transfer_length – data transfer length. Default as 0x1000 which is 4096 bytes.
file_name – filename to do the read into or write from. Default as empty string.

abort(SQID, CID)

The abort() function is used to abort a specific command previously submitted to the Admin Submission Queue or an I/O Submission Queue.

Parameters:

SQID – Submission Queue ID. This field specifies the identifier of the Submission Queue (ASQ or IOSQ) that the command to be aborted is associated with.
CID – Command Identifier. This field specifies the command identifier of the command to be aborted, that was specified in the CDW0.CID field within the command itself.

change_log_page_be_tuple(dict_api)

The change_log_page_be_tuple() function is used to convert log from dictionary to tuple.

Return type:: tuple

compare(start_LBA=0, num_LBAs=1, data_pattern=165, pattern_from_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=7, ref_tag=None, app_tag=None, app_tag_mask=None, fix_dif=True)

The compare() function reads the logical blocks specified by the command from the medium and compares the data read to a comparison data buffer transferred as part of the command. If the data read from the controller and the comparison data buffer are equivalent with no miscompares, then the command completes successfully. If there is any miscompare, the command completes with an error of Compare Failure. Not all SSD supports Compare function. Only if the bit 0 of ONCS (Optional NVM Command Support) set to ‘1’, then the controller supports the Compare command. If cleared to ‘0’, then the controller does not support the Compare command.

Parameters:

start_LBA – the first LBA to compare (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to compare (Recommend to put hex number like 0x01)
data_pattern – data pattern ([numbytes] byte of data) used for comparison
pattern_from_fileName – Data pattern file name to read from the tester in directory /virtualun/lundata/initiator/ and it is used for compare, e.g. pattern_from_fileName=”temp.bin”. It has higher priority than input argument data_pattern above.
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to retrieve the data for comparison.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Compare command, the controller shall: 1) commit that data and metadata, if any, to non-volatile media; and 2) read the data and metadata, if any, from non-volatile media. If cleared to ‘0’, then this bit has no effect.
protection_info – Specifies the protection information action and check field, as defined in Figure 355. The Protection Information Check (PRCHK) field shall be cleared to 000b. Protection Information Action (PRACT). The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information. Protection Information Check (PRCHK). The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.
fix_dif – fix up T10 DIF values prior to write (default as True). Optional values are True or False.

compare_and_write(start_LBA=0, num_LBAs=1, data_pattern=165, pattern_from_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, ref_tag=None, app_tag=None, app_tag_mask=None)

The compare_and_write() fused function compares the contents of the logical block(s) specified in the Compare command to the data stored at the indicated LBA range. If the compare is successful, then the LBA range is updated with the data provided in the Write command. If the Compare operation is not successful, then the Write operation is aborted with a status of Command Aborted due to Failed Fused Command and the contents in the LBA range are not modified. If the Write operation is not successful, the Compare operation completion status is unaffected. Not all SSD supports compare_and_write fused command. Only if the bit 0 of Fused Operation Support (FUSES, byte 523:522 in Identify Controller output) set to ‘1’, then the controller supports the Compare and Write fused operation. If cleared to ‘0’, then the controller does not support the Compare and Write fused operation. Compare shall be the first command in the sequence. If Compare is not supported (bit 0 of ONCS is not 1), then it will output as “Invalid Opcode”. If Compare is supported but Fused is not, then output as “Invalid Field”.

Parameters:

start_LBA – the first LBA to compare and write (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to compare and write (Recommend to put hex number like 0x01)
data_pattern – data pattern ([numbytes] byte of data) used for comparison and write
pattern_from_fileName – Data pattern file name to read from the tester in directory /virtualun/lundata/initiator/ and it is used for compare and write, e.g. pattern_from_fileName=”temp.bin”. It has higher priority than input argument data_pattern above.
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to retrieve the data for comparison.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Compare command, the controller shall: 1) commit that data and metadata, if any, to non-volatile media; and 2) read the data and metadata, if any, from non-volatile media. If cleared to ‘0’, then this bit has no effect.
protection_info – Specifies the protection information action and check field, as defined in Figure 355. The Protection Information Check (PRCHK) field shall be cleared to 000b. Protection Information Action (PRACT). The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information. Protection Information Check (PRCHK). The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

copy(copy_source_file_name, destination_start_LBA, limited_retry=0, FUA=0, PRINFOW=0, STCW=0, DTYPE=0, command_extension_type=0, PRINFOR=0, descriptor_format=0, num_ranges=1, DSPEC=0, command_extension_value=0, LBST=0, ILBRT=0, LBATM=0, LBAT=0)

The copy() function is used by the host to copy data from one or more source logical block ranges to a single consecutive destination logical block range.

Parameters:

copy_source_file_name – File name of the copy source range entries which should be in directory “/virtualun/lundata/initiator/” on the tester. You can use the “copy_source_file_name” generated with API “generate_copy_source_file()” above, but please make sure it is in directory “/virtualun/lundata/initiator/” on the tester.
destination_start_LBA – Destination Starting LBA. Please enter like hex number 0x68050001.
limited_retry – Limited Retry (LR). If set to ‘1’, the controller should apply limited retry efforts for the write portion of the copy operation. If cleared to ‘0’, the controller should apply all available error recovery means to write the data to the NVM.
FUA – Force Unit Access (FUA). If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the write portion of the copy operation, the controller shall write that data and metadata, if any, to non-volatile media before indicating command completion. If cleared to ‘0’, then this bit has no effect.
PRINFOW – Protection Information Field Write (PRINFOW). Specifies the protection information action and check field to be used for the write portion of the copy operation.
STCW – Storage Tag Check Write (STCW). This bit specifies the Storage Tag field shall be checked as part of end-to-end processing. It used for the write portion of the copy operation.
DTYPE – Directive Type (DTYPE). Specifies the Directive Type associated with the Directive Specific field. It is used for the write portion of the copy operation.
command_extension_type – Command Extension Type (CETYPE). Specifies the Command Extension Type that applies to the command. This field is used for the read portion of the copy operation for the LBAs specified in this Source Range entry.
PRINFOR – Protection Information Field Read (PRINFOR). Specifies the protection information action and check field to be used for the read portion of the copy operation specified by each Source Range Entries.
descriptor_format – Descriptor Format. Specifies the format of the Source Range Entries are 0h - The Source Range Entries specify starting LBA, number of logical blocks, and parameters associated with the read portion of the operation., 1h - The Source Range Entries specify starting LBA, number of logical blocks, and parameters associated with the read portion of the operation when PIF1 bit in the DPC field is set to ‘1’., All Others - Reserved
num_ranges – Number of Ranges (NR). Specifies the number of Source Range Entries that are specified in the command.
DSPEC – Directive Specific (DSPEC). Specifies the Directive Specific value associated with the Directive Type field.
command_extension_value – Command Extension Value (CEV). The definition of this field is dependent on the value of the CETYPE field. This field is used for the read portion of the copy operation for the LBAs specified in this Source Range entry.
LBST – The variable sized Logical Block Storage Tag.
ILBRT – Initial Logical Block Reference Tag.
LBATM – Logical Block Application Tag Mask.
LBAT – Logical Block Application Tag.

create_IOCQ(QID, QSIZE=1023, IV=0, IEN=0, PC=1)

The create_IOCQ() function is used to create an I/O Completion Queue specified by QID (default QID = 1), Queue Size (QSIZE), Physically Contiguous (PC), Interrupts Enabled (IEN) and Interrupt Vector (IV). The IEN and IV are specified by the driver so can’t specify with this API. No controller reset needed.

Parameters:

QID – I/O Completion Queue ID. This field indicates the identifier of the Completion Queue to be created. The value of 0h (Admin Submission Queue) shall not be specified.
QSIZE – Queue Size. This field indicates the size of the Completion Queue to be created. 0’s based value and recommend to be less or equal to current QueueDepth value.
IV – Interrupt Vector. This field indicates the interrupt vector to use for this Completion Queue.
IEN – Interrupts Enabled. If set to ‘1’, then interrupts are enabled for this Completion Queue. If cleared to ‘0’, then interrupts are disabled for this Completion Queue.
PC – Physically Contiguous. If set to ‘1’, then the Completion Queue is physically contiguous and PRP Entry 1 (PRP1) is the address of a contiguous physical buffer. If cleared to ‘0’, then the Completion Queue is not physically contiguous and PRP Entry 1 (PRP1) is a PRP List pointer.

create_IOSQ(QID, QSIZE=1023, CQID=1, QPRIO=1, PC=1, NVMSETID=0)

The create_IOSQ() function is used to create an I/O Submission Queue specified by QID, Queue Size (QSIZE), Completion Queue Identifier (CQID), Queue Priority (QPRIO), Physically Contiguous (PC) and NVM Set Identifier (NVMSETID). No controller reset needed.

Parameters:

QID – I/O Submission Queue ID. This field indicates the identifier of the Submission Queue to be created. The value of 0h (Admin Submission Queue) shall not be specified.
QSIZE – Queue Size. This field indicates the size of the Submission Queue to be created. 0’s based value and recommend to be less or equal to current QueueDepth value.
CQID – I/O Completion Queue ID. This field indicates the identifier of the I/O Completion Queue to utilize for any command completions entries associated with this Submission Queue. Please make sure this CQID exists first, or else this API call will fail with “CQ_INVALID”.
QPRIO – Queue Priority. This field indicates the priority class to use for commands within this Submission Queue.
PC – Physically Contiguous. If set to ‘1’, then the Submission Queue is physically contiguous and PRP Entry 1 (PRP1) is the address of a contiguous physical buffer. If cleared to ‘0’, then the Submission Queue is not physically contiguous and PRP Entry 1 (PRP1) is a PRP List pointer.
NVMSETID – NVM Set Identifier. This field indicates the identifier of the NVM Set to be associated with this Submission Queue.

dataset_deallocate(start_LBA=0, num_LBAs=1, num_ranges=1, context_attributes=0)

The dataset_deallocate() function is used to deallocate all provided ranges. Bit 2 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support the Dataset Management command.

Parameters:

start_LBA – the first LBA for dataset_deallocate (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs for dataset_deallocate (Recommend to put hex number like 0x01).
num_ranges – the number of 16 byte range sets that are specified in the command (demial number), each range will be split randomly from num_LBAs above. So please ensure num_ranges <= num_LBAs.
context_attributes – Specified for each range provides information about how the range is intended to be used by host software. The use of this information is optional and the controller is not required to perform any specific action. (32-bits, put hex number like 0x00000300)

dataset_read_hint(start_LBA=0, num_LBAs=1, num_ranges=1, context_attributes=0)

The dataset_read_hint() function is used to specify the dataset should be optimized for read access as an integral unit. The host expects to perform operations on all ranges provided as an integral unit for reads, indicating that if a portion of the dataset is read it is expected that all of the ranges in the dataset are going to be read. Bit 2 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support the Dataset Management command.

Parameters:

start_LBA – the first LBA for dataset_deallocate (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs for dataset_deallocate (Recommend to put hex number like 0x01).
num_ranges – the number of 16 byte range sets that are specified in the command (demial number), each range will be split randomly from num_LBAs above. So please ensure num_ranges <= num_LBAs.
context_attributes – Specified for each range provides information about how the range is intended to be used by host software. The use of this information is optional and the controller is not required to perform any specific action. (32-bits, put hex number like 0x00000300)

dataset_write_hint(start_LBA=0, num_LBAs=1, num_ranges=1, context_attributes=0)

The dataset_write_hint() function is used to specify the dataset should be optimized for write access as an integral unit. The host expects to perform operations on all ranges provided as an integral unit for writes, indicating that if a portion of the dataset is written it is expected that all of the ranges in the dataset are going to be written. Bit 2 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support the Dataset Management command.

Parameters:

start_LBA – the first LBA for dataset_deallocate (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs for dataset_deallocate (Recommend to put hex number like 0x01).
num_ranges – the number of 16 byte range sets that are specified in the command (demial number), each range will be split randomly from num_LBAs above. So please ensure num_ranges <= num_LBAs.
context_attributes – Specified for each range provides information about how the range is intended to be used by host software. The use of this information is optional and the controller is not required to perform any specific action. (32-bits, put hex number like 0x00000300)

delete_IOCQ(QID)

The delete_IOCQ() function is used to delete an I/O Completion Queue specified by QID. No controller reset needed.

Parameters:: QID – This field indicates the identifier of the Completion Queue to be deleted. The value of 0h (Admin Completion Queue) shall not be specified.

delete_IOSQ(QID)

The delete_IOSQ() function is used to delete an I/O Submission Queue specified by QID. No controller reset needed.

Parameters:: QID – This field indicates the identifier of the Submission Queue to be deleted. The value of 0h (Admin Submission Queue) shall not be specified.

device_selftest(selftest_code=1, nsid=None)

The device_selftest() function is used to start or abort self-test (short, or extended, or vendor specific) if supported. The self-test status please check log page 06h.

Parameters:

selftest_code –

user can enter hex or decimal number, and the optional values are as follows:

Value	Definition
0h	Reserved
1h	Start a short device self-test operation
2h	Start an extended device self-test operation
3h to Dh	Reserved
Eh	Vendor specific
Fh	Abort device self-test operation

nsid – Namespace ID. It is decimal number, so don’t enter as hex number like 0x10. 0 for self-test whole controller, 1-FFFFFFFE for specific NS, Only use -1 to mean 0xFFFFFFFF for all NS.

dict_raise_on_duplicates(ordered_pairs): Convert duplicate keys to JSON array.

directive_receive(directive_type=0, directive_operation=1, directive_specific=0, num_namespace_streams_requested=0, num_bytes=4096, nsid=None)

The directive_receive() function returns a data buffer that is dependent on the Directive Type. If directive type is “Identify” then it returns a data structure that contains a bit vector specifying the Directive Types supported by the controller and a bit vector specifying the Directive Types enabled for the namespace. If directive type is “Streams” then it returns a data structure that specifies the features and capabilities supported by the Streams Directive, including namespace specific values. Bit 5 of OACS (Optional Admin Command Support) as ‘1’ shows the controller supports directives.

Parameters:

directive_type – Directive Type (DTYPE). 00h: Identify directive. 01h: Streams directive.
directive_operation – The Directive Operation (DOPER) to perform. The interpretation of this field is Directive Type dependent. For Identify Directive all others are reserved except 01h (Return Parameters). For Streams Directive all others are reserved except 01h (Return Parameters), 02h (Get Status) and 03h (Allocate Resources).
directive_specific – DSPEC. Directive Type dependent. For Identify Directive it is not used. For Streams Directive it specifies the identifier of the stream associated with the data (The DSPEC field is not used for Allocate Resources operation).
num_namespace_streams_requested – NSR. this field specifies the number of stream resources the host is requesting be allocated for exclusive use by the namespace specified. For directive_type = 1 and directive_operation = 3 only. For others it will be ignored
num_bytes – The number of bytes to return (Recommend to put hex number like 0x1000 for 4096 bytes, the API will convert to number of Dwords in the background and minus 1 becasue it is 0’s based value, and get 0x03FF in the ASQ).
nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.

directive_send(directive_type=0, directive_operation=1, directive_specific=0, enable_directive=1, enable_directive_type=1, num_bytes=4096, nsid=None)

The directive_send() function transfers a data buffer that is dependent on the Directive Type to the controller. If directive type is “Identify” then the Enable Directive operation is used to enable a specific Directive for use within a namespace by all controllers that are associated with the same Host Identifier (please notice The Identify Directive is always enabled). If directive type is “Streams” then it releases Identifier (specifies that the stream identifier specified in the DSPEC field in command Dword 11 is no longer in use by the host) or release Resources (release all streams resources allocated for the exclusive use of the namespace attached to all controllers). Bit 5 of OACS (Optional Admin Command Support) as ‘1’ shows the controller supports directives.

Parameters:

directive_type – Directive Type. 00h: Identify directive. 01h: Streams directive.
directive_operation – The Directive Operation to perform. The interpretation of this field is Directive Type dependent. For Identify Directive all others are reserved except 01h (Enable Directive). For Streams Directive all others are reserved except 01h (Release Identifier) and 02h (Release Resources).
directive_specific – Directive Type dependent. For Identify Directive it is not used. For Streams Directive it specifies the identifier of the stream associated with the data.
enable_directive – ENDIR. If set to ‘1’ and the Directive Type is supported, then the Directive is enabled. If cleared to ‘0’, then the Directive is disabled. If this bit is set to ‘1’ for a Directive that is not supported, then a status of Invalid Field in Command shall be returned.
enable_directive_type – DTYPE. This field specifies the Directive Type to enable or disable. If this field specifies the Identify Directive (i.e., 00h), then a status of Invalid Field in Command shall be returned.
num_bytes – The number of bytes to send (Recommend to put hex number like 0x1000 for 4096 bytes, the API will convert to number of Dwords in the background and minus 1 becasue it is 0’s based value, and get 0x03FF in the ASQ).
nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.

dump_nvme_controller_registers(): Dump the current NVMe controller registers.

flush(nsid=None)

The flush() function is used to request that the contents of volatile write cache be made non-volatile.

Parameters:: nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF (If bits 2:1 are set to 11b in the VWC field then it will flush all namespaces, or else it will fail). If not specify and it will be the LUN number when instantiate the object.

generate_copy_source_file(copy_source_file_name, descriptor_format, start_LBA, num_LBAs, command_extension_type=0, command_extension_value=0, ELBST=0, ILBRT=0, ELBAT=0, ELBATM=0)

The generate_copy_source_file() function is used to generate copy source range entry file which is required for copy command issue. copy_source_file_name = File path and name of the copy source range entries.

Parameters:

descriptor_format – Descriptor Format. Specifies the format of the Source Range Entries as follows: 0h - The Source Range Entries specify starting LBA, number of logical blocks, and parameters associated with the read portion of the operation., 1h - The Source Range Entries specify starting LBA, number of logical blocks, and parameters associated with the read portion of the operation when PIF1 bit in the DPC field is set to ‘1’., All Others - Reserved
start_LBA – Source Starting LBA. Please enter like hex number 0x68050001.
num_LBAs – Number of Logical Blocks (NLB): This field indicates the number of logical blocks to be copied. It should be less than or equal to MSSRL (Maximum Single Source Range Length).
command_extension_type – Command Extension Type (CETYPE). Specifies the Command Extension Type that applies to the command. This field is used for the read portion of the copy operation for the LBAs specified in this Source Range entry.
command_extension_value – Command Extension Value (CEV). The definition of this field is dependent on the value of the CETYPE field. This field is used for the read portion of the copy operation for the LBAs specified in this Source Range entry.
ELBST – The variable sized Expected Logical Block Storage Tag.
ILBRT – Expected Initial Logical Block Reference Tag.
ELBAT – Expected Logical Block Application Tag.
ELBATM – Expected Logical Block Application Tag Mask.

get_LBA_status(start_LBA=0, max_num_bytes=4096, range_length=256, action_type=16)

The get_LBA_status() function requests information about Potentially Unrecoverable LBAs. If the Get LBA Status command completes successfully, then the LBA Status Descriptor List is returned in the data buffer for that command. Bit 9 of OACS (Optional Admin Command Support) as ‘1’ shows the controller support Get LBA Status.

Parameters:

start_LBA – The first LBA to get LBA status (Recommend to put hex number like 0x00)
max_num_bytes – The maximum number of bytes to return (Recommend to put hex number like 0x1000 for 4096 bytes, the API will convert to Maximum Number of Dwords in the background and minus 1 becasue it is 0’s based value, and get 0x03FF in the ASQ).
range_length – The length of the range of contiguous LBAs, beginning at Starting LBA (SLBA), that the action specified in the Action Type (ATYPE) field shall be performed on. A value of 0h in this field specifies the length of a range beginning at Starting LBA and ending at Namespace Size (NSZE) minus 1 (Recommend to put hex number like 0x10).
action_type – The mechanism the controller uses in determining the LBA Status Descriptors to return. 10h: Perform a scan and return Untracked LBAs and Tracked LBAs in the specified range, 11h: Return Tracked LBAs in the specified range, All others: Reserved

get_extended_logging(): The get_extended_logging() function is used to get the extended logging results from the port/target/lun if extended_logging is enabled.

get_feature(feature_id, page_control, nsid=None, uuid_index=None)

The get_feature() function is used to retrieve any feature specified by feature_id (enter as hex number like 0x0E for time stamp feature 0x0E) and selected value of the attributes specified by page_control.

Parameters:

page_control – 0 - current, 1 - default, 2 - saved, 3 - supported
nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

get_logpage(log_id, page_control, csi=0, nsid=None, lsid=None, uuid_index=None)

The get_logpage() function is used to retrieve any log page specified by log_id (enter as hex number like 0x80 for log page 0x80) and selected value of the attributes specified by page_control.

Parameters:

page_control – 0 - current, 1 - default, 2 - saved, 3 - supported
nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

get_proc_lun_info(): The get_proc_lun_info() function is used to retrieve namespace information from proc.

get_proc_port_info(): The get_proc_port_info() function is used to retrieve port information from proc.

get_proc_target_info(): The get_proc_target_info() function is used to retrieve controller information from proc.

get_proc_vlun_config(): The get_proc_vlun_config() function is used to retrieve all parameters from proc file /proc/vlun/config.

get_proc_vlun_nvme(): The get_proc_vlun_nvme() function is used to retrieve all parameters from proc file /proc/vlun/nvme.

get_test_results(test_id)

The get_test_results() function is used to get the I/O test results specified by test_id.

Parameters:: test_id – I/O test ID like “Read_1”.

get_vlun_change_test_state(test_id, state, all_targets=0, all_luns=0)

Pauses, resumes or restarts a test of a given port, target (or all targets), lun (or all luns) and test_id (like “Read_1”)

Parameters:

test_id – Test ID as format “IOType_IOName”. The IOType can be Read, Write, Compare, Verify, Rewrite or RrWwZzUu, where r/w/z/u are positive decimal integers. In general get from API “get_vlun_start_test” output
state – pause - pause a running test, unpause - resume a paused test, start - restart a stopped test
all_targets – Default as 0. If set to 1 then change the test state of the specified I/O test on all targets/controllers (including all LUNs under the controllers) in the tester, which means port level I/O test
all_luns – Default as 0. If set to 1 then change the test state of the specified I/O test on all LUNs under the same controller, which means controller level I/O test

get_vlun_clear_counters(action='ClearErrors')

Clear various counters and tests on a given device.

Parameters:

port – the port’s integer value.
target – NVMe controller id.
lun – NVMe namespace id.
action – type of counter to clear: ClearErrors - clear error counters, ClearTests - clear all stopped tests, ClearStats - clear performance counters/errors that occurred during tests, ClearTestErrors - clear test error counters, ALL - clear all of the above at once

get_vlun_delete_tests(): Clear all stopped tests.

get_vlun_error_action(action='BadType', count=0, address=None, eth_type=None, between=None, repetitions=None, lba=None, lba_offset=None, dif_value=None)

Inject certain error condition on a given port. Depending on the error, the possible arguments can differ.

Parameters:

port – physical port number to inject error on (if not specify targt/lun then it will be port level only)
target – target number to inject error on if specified (if not specify then it will be port level only)
lun – LUN number to inject error on if specified (if not specify then it will be port/target level only)
action –
type of error injection to do. Per action arguments can differ.

BadDA - send frame with bad destination address

count - number of frames to corrupt

address - MAC address to inject (ie address=”00:11:22:33:44:55” or address=”11:22:33:44:55:66”)

BadSA - send frame with source address

count - number of frames to corrupt

address - MAC address to inject

BadVLAN - send frame with bad vlan tag

count - number of frames to corrupt

priority - vlan priority to use ( 0 - 7 )

id - vlan id to use

BadType - send frame with bad ethernet type

count - number of frames to corrupt

address - MAC address to inject (ie address=”11:22:33:44:55:66”)

eth_type - ethernet type to use (4 hex digits, 8906 for FCoE like eth_type=1111)

BadSOF - send frame with bad SOF49

count - number of frames to corrupt

sof - sof to use

BadEOF - send frame with bad EOF

count - number of frames to corrupt

eof - eof to use

BadCRCOut - send frame with bad CRC

count - number of frames to corrupt

BadCRCIn - receive frame with bad CRC

count - number of frames to corrupt

BadLenUnder - send frame with underrun

count - number of frames to corrupt

length - length to shorten frame by

BadLenOver - send frame with overrun

count - number of frames to corrupt

length - length to extend frame by

FCoEDrop - drop a specific frame

count - number of frames to corrupt

seq_cnt - frame sequence count (FFFF for don’t care)

offset - frame offset (FFFFFFFF for don’t care)

type - type of frame to drop:

1 - Don’t send/recv FCP_XFER_RDY

2 - Don’t send FCP_DATA, any frame of seq

3 - Don’t recv FCP_DATA, any frame of seq

4 - Don’t send/recv FCP_RSP

5 - Don’t send/recv FCP_CONF

6 - Don’t send/recv FCP_CMND (not task mgmt)

7 - Don’t send FCP_DATA, last frame of seq

8 - Don’t recv FCP_DATA, last frame of seq

9 - Don’t send/recv FCP_CMND (task mgmt)

10 - Don’t send FCP_DATA, first frame of seq

11 - Don’t recv FCP_DATA, first frame of seq

12 - Don’t send FCP_DATA, middle frame of seq

13 - Don’t recv FCP_DATA, middle frame of seq

14 - Don’t recv SRR50

15 - Don’t recv ADISC

16 - Don’t recv FDISC

17 - Ignore recv’d FCP_CMND (not task mgmt)

18 - Reject recv’d FCP_CMND (not task mgmt)

19 - Don’t send FCP_DATA, specific SeqCnt/Offset

20 - Don’t recv FCP_DATA, specific SeqCnt/Offset

21 - Don’t send every N’th FCP frame

22 - Don’t recv every N’th FCP frame

23 - Don’t recv REC

FCoEDelay - delay a specific frame

count - number of frames to corrupt

seq_cnt - frame sequence count (FFFF for don’t care)

offset - frame offset (FFFFFFFF for don’t care)

delay - amout to delay in milliseconds

type - type of delay to inject:

1 - Delay sending FCP_XFER_RDY

2 - Delay sending FCP_DATA, any frame of seq

4 - Delay sending FCP_RSP

5 - Delay sending FCP_CONF

7 - Delay sending FCP_DATA, last frame of seq

10 - Delay sending FCP_DATA, first frame of seq

12 - Delay sending FCP_DATA, middle frame of seq

19 - Delay sending FCP_DATA, specific SeqCnt/Offset

FIPDrop - drop a specific FIP frame

count - number of frames to drop

port_id - specific port_id to use

type - type of frame to drop

1 - Drop all Keep Alives

2 - Drop controller Keep Alives

3 - Drop port Keep Alives

4 - Drop port Keep Alives for a specific PortID

SendPause - send a standard pause frame

count - number of frames to send51

interval - interval between frames in milliseconds

quanta - time quanta to use in frames (0 -ffff)

SendPFCPause - send a PFC pause frame

count - number of frames to send

interval - interval between frames in milliseconds

quanta - time quanta to use in frames ( 0 - ffff)

class - priority class to pause (0 - 7 )

ForceBadDIFGuardIn - insert bad t10 DIF guard tag to incoming data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this Guard value (Hex value)

ForceBadDIFGuardOut - insert bad t10 DIF guard to outgoing data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this Guard value (Hex value)

ForceBadDIFRefTagIn - insert bad t10 DIF ref tag to incoming data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this RefTag value (Hex value)

ForceBadDIFRefTagOut - insert bad t10 DIF ref tag to outgoing data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this RefTag value (Hex value)

ForceBadDIFAppTagIn - insert bad t10 DIF app tag to incoming data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this AppTag value (Hex value)

ForceBadDIFAppTagOut - insert bad t10 DIF app tag to outgoing data

count - number of errors to inject (Decimal value)

between - number of I/Os between errors (Decimal value)

repetitions - Iterations of Count and I/Os Between, when I/Os Between is non-zero; 0 will run forever (Decimal value)

lba - Insert error on access to this LBA (range) (Hex value)

lba_offset - Insert error on this LBA (offset) within an I/O (Hex value)

dif_value - Use this AppTag value (Hex value)

get_vlun_generic_io(IOtype='Inquiry', a=None, app_tag=None, app_tag_mask=None, beg_elem=None, bf=None, bs=None, ms=None, buffer_id=None, count=None, data=None, elem_type=None, file=None, from_elem=None, timeout=None, key=None, lba=None, slba=None, lbas=None, nlb=None, mode=None, num_elem=None, pg=None, pc=None, protect=None, ref_tag=None, saction=None, skey=None, spg=None, to_elem=None, txlen=None, type=None, using_elem=None, lun_am=None, w=None, nsid=None, cns=None, csi=None, data2=None, e=None, o=None, fid=None, lid=None, sa=None, crkey=None, nrkey=None, prkey=None, rtype=None, prinfo=None, fix_dif=None, dif_last=None, bad_guard=None, bad_ref_tag=None, bad_app_tag=None, dix=None, ca=None, fs=None, str_id=None, str_ctl=None, lbaf=None, erase=None, prot=None, chunk=None, only16=None, nr=None, attr=None, x=None, t=None, z=None, mi=None, cdb=None, dir=None, cdb_mod=None, qs=None, abort=None, fork=None, incr=None, v=None, wait=None)

Execute a generic IO command to a given LUN.

Parameters:

IOtype –
command to send. For example CDBs like Inquiry, Read6, … and NVMe commands like:

AsyncEventRequest

DirectiveReceive

Flush

GetFeatures

GetLBAStatus

GetLogPage

IdentifyAllocatedNamespace

IdentifyAllocatedNamespaceIDs

IdentifyAttachedControllerIDs

IdentifyController

IdentifyControllerIDs

IdentifyNamespace

IdentifyNamespaceGranularityList

IdentifyNamespaceIDs

IdentifyNamespaceIdentDescripts

IdentifyPrimaryControllerCapabilities

IdentifySecondaryControllerList

IdentifyZNSNamespace

Identify

Read

ReservationReport

ReservationReportExt

ZoneManagementReceive

Compare

CompareAndWriteFused

DatasetDeallocate

DatasetReadHint

DatasetWriteHint

DeviceSelfTest

DirectiveSend

FirmwareCommit

FirmwareImageDownload

FormatNVM

FormatNVMCryptoErase

FormatNVMSecureErase

NamespaceAttachment

NamespaceManagement

ReservationAcquire

ReservationRegister

ReservationRelease

SanitizeNVM

SetFeatures

SetFeaturesSave

Verify

Write

WriteUncorrectable

WriteZeroes

ZoneAppend

ZoneManagementSend
Optional –
The following are optional parameters which may be passed with the generic IO command:

a = initiator number to send command from (if multiple initiators are created)

app_tag = T10 DIF application tag

app_tag_mask = T10 DIF application task mask

beg_elem = changer first element

bf = buffer content to be written

bs = hex block size in bytes

ms = Hex metadata size in bytes (defaults to 8) for protected reads and writes, or for DIX

buffer_id = buffer id for SCSI firmware download

count = repeat count for command

data = data byte to use for writes

elem_type = changer type element

file = path to file on system to use for read into or write from

from_elem = changer from element (source)

timeout = timeout in seconds to use for command completion

key = persistent reservation key

lba = hexadecimal LBA address

slba = hex starting logical block address, defaults to 0 (NVMe)

lbas = hex number of blocks to read or write

nlb = hex 0-based number of logical blocks to read or write, defaults to 0 (NVMe)

mode = mode to use for SCSI firmware download,

num_elem = changer number of elements,

pg = hexadecimal page number for mode, diag, log and inquiry vpd pages. For NVMe this value corresponds to the FID/LID value.,

pc = page control for mode.

NVMe values

0 - current

1 - default

2 - saved

3 - supported

SCSI values

0 - current

1 - changeable

2 - default56

3 - saved

protect = T10 DIF protection type

ref_tag = T10 DIF reference tag

saction = service action of persistent reservation commands

skey = persistent reservation services key

spg = hexadecimal subpage for mode, diag, log and inquiry vpd pages

to_elem = changer to element (destination)

txlen = hexadecimal size in bytes to read or write

type = persistent reservation type

using_elem = changer using element (transport)

lun_am = lun addressing mode (0 = simple, 1 = flat, 2 = extended flat, 3 = long extended flat)

w = force write, w = 1 means force to write

nsid = name space id (NVMe port only)

cns = Controller/Namespace Structure for Identify (hex number)

csi = Command Set Identifier for Identify (hex number)

data2 = write buffer data

e = erase the output file first, default is append, e = 1 means erase the output file first

o = bytes offset into block to being writing bytes (use with data)

fid = feature id for NVMe

lid = log page id for NVMe

sa = generic service action, hex value from SCSI or NVMe spec

crkey = current key for reservations for NVMe

nrkey = new key for reservations for NVMe

prkey = preempt key for reservations for NVMe

rtype = reservation type, hex value from NVMe spec

prinfo = T10 DIF protection information (PRINFO for NVMe)

fix_dif = fix up T10 DIF values prior to write

dif_last = when fixing up T10 DIF values, the DIF bytes are last in the metadata, not first

bad_guard = X, Y corrupt T10 DIF guard value at block X with value y (use -1, -1 for auto)

bad_ref_tag = X, Y corrupt T10 DIF ref tag value at block X with value y (use -1, -1 for auto)

bad_app_tag = X, Y corrupt T10 DIF app tag value at block X with value y (use -1, -1 for auto)

dix = use DIX mod for T10 DIF (metadata separate from data)

ca = Commit Action for NVMe firmware commit

fs = Firmware Slot for NVMe firmware commit

str_id = Stream ID for WriteStream, StreamControl and StreamStatus commands

str_ctl = Stream Control for StreamControl commands

lbaf = LBA format for NVME format

erase = secure erase type for NVMe format (0 is none, 1 is user data, 2 is crypto)

prot = protection type for SCSI or NVME format

chunk = size in blocks for unmap operations, or bytes for firmware download operations,

only16 = when doing writesame unmap operations, use WriteSame16 (or not) instead of using WriteSame10 when possible,

nr = number of logical block ranges to use for Unmap (SCSI) or DatasetDeallocate (NVMe)

attr = task attribute (0 is simple queue, 1 is head of queue, 2 ordered queue)

x = xml formatted output, x = 1 means enable xml formatted output

t = terse mode when displaying data, suppress zeroes, t = 1 means suppress zeros

z = zero the error logs (./scsistatus ./senskey ./key ./ascq ./asc ./ioerr ./ili ./eom ./eod ./filemark), z = 1 means zero the error logs,

mi = hex bytes for MI request

cdb = 6,10,12,16,32 or 64 hex bytes for custom CDB

dir = data transfer direction (in, out, read or write)

cdb_mod = CDB modifications (comma-separated list):

- byterange[.bitrange]=value[,byterange1[.bitrange1]=value1[,…]]

- byterange is X-Y for bytes X through Y, or just X

- bitrange is X-Y for bits X through Y, or just X

- value is a hex number to replace the bitrange within the byterange

- byterange and value are not optional, but bitrange is optional

example: -cdb_mod 2-3=456,9.1=1

- replace byte 2 with 04, byte 3 with 56, and in byte 9, set bit 1 (SCSI)

- replace byte 2 with 56, byte 3 with 04, and in byte 9, set bit 1 (NVMe)

qs = queue select for NVMe, decimal number

abort = immediately try to abort this I/O after it is issued

fork = number of fork threads to start for overlapping I/O

incr = increment the logical block address for each overlapping I/O

v = verbose mode, v = 1 means enable verbose mode

wait = wait for fork threads to launch, and then finish, when doing overlapping I/O

get_vlun_get_initiator_config()

Report initiator settings for an array, a target or a lun.

Parameters:

port – physical port number of the target or lun to modify. If settings are for an array, parameter is omitted.
target – target id of the target or lun to modify. If settings are for an array, parameter is omitted. Otherwise, the port must be specified prior to this argument.
lun – lun id of the lun to modify. If settings are for an array or target, parameter is omitted. Otherwise, the target must be specified prior to this argument.

get_vlun_get_port_config()

Report port level settings.

Parameters:: port – physical port to get configuration for.

get_vlun_get_port_test_parameters(): Report port level test parameter values. port = physical port to get configuration for.

get_vlun_init_reprobe(probe_type=3, initiator=-1)

Reprobe for connected devices on a given port with different probe_type and specific initiator reprobe from (A value of -1 means for all)

Parameters:

probe_type – type of reprobe to do 1 - lun 0 only 2 - All luns 3 - Report luns
initiator – initiator to reprobe from (-1 for all)

get_vlun_install_kit(filename='VLUN-V8.0-64-Beta27-4.9.107.tz')

Install a specific software build onto the system. Requires a reboot after complete to take effect.

Parameters:: filename – filename of software kit that has been upload to the system root directory “/” already.

get_vlun_iscsi_add_delete(ipport=3260, ipaddress='1.1.1.1', autologin=True, discoverall=True, valid_command='addportal')

Add or Delete an iSCSI portal.

Parameters:

port – port integer value
ipport – the IP port integer value
ipaddress – the IP address for the iSCSI Target
autologin – true or false (mandatory if command is ‘addportal’)
discoverall – true or false. If true and the addportal command is specified, returns all the available portals to the specified target.
valid_command – addportal, delportal

get_vlun_iscsi_get_params(valid_command='global', targets=None)

Get iSCSI session parameters.

Parameters:

port – the integer port value. Optional and applicable only for the target command
valid_command – global or target, if global then don’t need to specify targets below, if choose target then need to specify targets as below
targets – one or more targets for the parameter(s). A list of targets must be separated by commas (,) with no spaces. Ex. < target >, < target >,< target >, …

get_vlun_iscsi_get_session_properties(sid=None)

Obtain iSCSI session information and negotiated iSCSI parameters.

Parameters:

port – port integer value
sid – integer session identifier, an optional argument. If specified, session data for that sid is returned, otherwise data for all sessions is returned

get_vlun_iscsi_log_in_out(target=None, valid_command='login', sid=None)

Log into or out from an iSCSI portal.

Parameters:

port – port integer value
target – the target IQN value (use with login or logout)
valid_command – login, logout
sid – session identifier (use with logout in place of target)

get_vlun_iscsi_probe(ipport=3260, autologin=True, range='1.1.1.*')

Probe the specified subnet for iSCSI targets.

Parameters:

port – port integer value
ipport – the IP port integer value
autologin – true or false
range – x-y or * for all

get_vlun_iscsi_set_params(valid_command='global', targets=None, allowed_ifacesubids=None, authmethod=None, username=None, password=None, initialr2t=None, immediatedata=None, firstburstlength=None, maxburstlength=None, maxrecvdatasegmentlength=None, headerdigest=None, datadigest=None)

Set iSCSI session parameters.

Parameters:

port – the integer port value. Optional and applicable only for the target command
valid_command – global or target, if global then don’t need to specify targets below, if choose target then need to specify targets as below
targets – one or more targets for the parameter(s). A list of targets must be separated by commas (,) with no spaces. Ex. < target >, < target >,< target >, …
param –
one or more parameters to be set. A list of parameters must be separated by a single space. Ex. < parameter >=< value > < parameter >=<value >, …, Supported parameters include:

allowed_ifacesubids

authmethod

username

password

initialr2t

immediatedata

firstburstlength

maxburstlength

maxrecvdatasegmentlength

headerdigest

datadigest

The authmethod, headerdigest and datadigest parameters have default values of none. The authmethod parameter may be set to chap and the headerdigest and datadigest parameters may be set to crc32c.

get_vlun_iscsi_show_portals(reprobe=1)

Show discovered iSCSI target portals.

Parameters:

port – port integer value
reprobe – 0 to disable or 1 to enable

get_vlun_license_info(): Returns system license information such as dongle_status, serial_number, version, vlun_sw_version, supported_features, license_type, number of days before license expires and so on.

get_vlun_link_reset(phy=-1): Link reset a particular port and PHY (A value of -1 means reset all PHYs on the port)

get_vlun_login(keep=1, id=15400992, initiator=0)

Start the login process to a FC device.

Parameters:

port – the port’s integer value.
keep – this tag behaves like a flag whose presence is used to distinguish Logout from Process Logout. If it is omitted or set to a value less than 0, a Process Logout is sent. Otherwise, a logout is sent. The value is used if the port is in target mode. In this case (0) indicates do not keep logged out and a one (1) indicates keep logged out.
id – 3 byte hexadecimal identifier of the device (FC ID)
initiator – the decimal id of the initiator of the login process. In initiator mode, it is the id of the initiator or all the initiators (if -1) on the port. In target mode, it is the id of the target or all the targets (if -1) on the port.

get_vlun_logout(keep=1, id=15400992, initiator=0)

Start the login process to a FC device.

Parameters:

port – the port’s integer value.
keep – this tag behaves like a flag whose presence is used to distinguish Logout from Process Logout. If it is omitted or set to a value less than 0, a Process Logout is sent. Otherwise, a logout is sent. The value is used if the port is in target mode. In this case (0) indicates do not keep logged out and a one (1) indicates keep logged out.
id – 3 byte hexadecimal identifier of the device (FC ID)
initiator –

the decimal id of the initiator of the login process. In initiator mode, it is the id of the initiator or all the initiators (if -1) on the port. In target mode, it is the id of the target
or all the targets (if -1) on the port.

get_vlun_nvme_format_namespace(erase=0, pil=0, mset=1, pi=0, lbaf=0)

Send a command to format a specified NVMe namespace. Bit 1 of OACS (Optional Admin Command Support) if set to ‘1’, then the controller supports the Format NVM command. If cleared to ‘0’, then the controller does not support the Format NVM command.

pil, pi and mset make one magical combination as “prot” which is Protection of Namespace, default as “100” from “~pil ~mset pi”

Parameters:

erase –
Erase type used during the format operation. Defaults to 0 if not specified.

0 - No secure erase operation.

1 - User data Erase

2 - Cryptographic Erase
pil – Protection Information Location. If set to ‘1’ and protection information is enabled, then protection information is transferred as the first eight bytes of metadata. If cleared to ‘0’ and protection information is enabled, then protection information is transferred as the last eight bytes of metadata. This setting is reported in the End-to-end Data Protection Type Settings (DPS) field of the Identify Namespace data structure and is constrained by the End-to-end Data Protection Capabilities (DPC) field of the Identify Namespace data structure.

pi –

Protection Information. This field specifies whether end-to-end data protection is enabled and the type of protection information. The values for this field have the following meanings:

Value	Definition
000b	Protection information is not enabled
001b	Protection information is enabled, Type 1
010b	Protection information is enabled, Type 2
011b	Protection information is enabled, Type 3
100b to 111b	Reserved

When end-to-end data protected is enabled, the host shall specify the appropriate protection information in the Read, Verify, Write, or Compare commands.

mset – Metadata Settings (MSET). This bit is set to ‘1’ if the metadata is transferred as part of an extended data LBA. This bit is cleared to ‘0’ if the metadata is transferred as part of a separate buffer. The metadata may include protection information, based on the Protection Information (PI) field. If the Metadata Size for the LBA Format selected is 0h, then this bit is not applicable.
"prot" –
is the magic combination of pil, pi and mset above, and implemented as following ~pil ~mset pi, but “prot” is not used in this API and it is only used for command line: strcpy(prot, “100”);

if (pil) {

prot[0] = pil[0] ^ 1; // convert “0” to “1” and vice versa

}

if (mset) {

prot[1] = mset[0] ^ 1; // convert “0” to “1” and vice versa

}

if (pi) {

prot[2] = pi[0];

}
lbaf – LBA Format of Namespace. You can find out from identify namespace output

get_vlun_nvme_update_controller(valid_command='ResetController', num_queues=32, queue_depth=1024, aer_count=1, aer_auto=0, offset=None, input_value=None, options_set_using_CMB=None, chunk_size_RD_WD=None, enable_ve=True, num_vqs=None, num_vis=None, num_vfs=None, queue_count=None, num_cqs=None, shutdown_mode=None, reset_type=None, queue_id=None, queue_size=None, queue_priority=None, cq_id=None, physically_contiguous=None, nvm_set_id=None, cq_size=None, cq_physically_contiguous=None, enable_hmb=None, hmb_allocation_size=None, num_hmb_chunks=None, num_urgent_priority_queues=None, num_high_priority_queues=None, num_medium_priority_queues=None, num_low_priority_queues=None)

Send a command to one or all the NVMe controllers.

Parameters:

port – the port’s integer value.
controller – NVMe controller id. Ignored when the AddController is specified. Otherwise, omit or pass -1 for all NVMe controllers on the port.
valid_command –
command to send to the NVMe controller. Valid commands are:

ModifyQueues - modify queue

RescanController - rescan controller

AddController - add controller

RemoveController - remove controller

ResetController - reset controller

ShutdownController - shutdown controller

DisableController - disable controller

NvmeReset - NVM subsystem reset

PciReset - PCI reset

PciFunctionReset - PCI function reset

PcieLinkDown - bring PCIe link down

PcieLinkUp - bring PCIe link up

SecureErase - Perform secure erase

DumpRegs - dump NVMe controller registers

IssueAsyncEventRequests - issue async event requests

AbortAsyncEventRequests - abort async event requests

ShowAsyncEvents - show async events

BorrowCtrl - show up as native NVMe controller

ReturnCtrl - back to block layer (not show up as native NVMe controller)

Read32Reg - read back 32-bit NVMe controller register based on specified offset which is required

Read64Reg - read back 64-bit NVMe controller register based on specified offset which is required

Write32Reg - write 32-bit NVMe controller register based on specified offset and input_value which are required

Write64Reg - write 64-bit NVMe controller register based on specified offset and input_value which are required

SetCcCss - write 32-bit NVMe controller register CC.CSS (Controller Configuration, I/O Command Set Selected) based on specified input_value which is required, require to issue “ResetController” after this command

UnsetCcCss - restore 32-bit NVMe controller register CC.CSS (Controller Configuration, I/O Command Set Selected). Stop forcing and go back to the driver’s calculated CC.CSS value. Require to issue “ResetController” after this command

SetCmb - setup the set of options that are desired to be using CMB and the chunk size when doing RD (read data) and WD (write data)

SetHmb - setup the HMB enable/disable, allocation size and number of chunks

SetUseVirtEnh - Set the specified number of VQs (virtual queues) and VIs (virtual interrupts) which will be used for next VFs creation

SetNumVFs - Create the specified number of VFs (virtual functions) based on the setting by command “SetUseVirtEnh” above

SetQueueCount - Set the desired queue count as the input argument queue_count, after controller restart then current queue count will be changed

SetQueueDepth - Set the desired queue depth as the input argument queue_depth, after controller restart then current queue depth/size will be changed

SetQueuePriority - Set the desired queue priority as the input arguments num_urgent_priority_queues, num_high_priority_queues, num_medium_priority_queues and num_low_priority_queues, after controller restart then current queue priority will be changed

SetNumCQs - Set the number of CQs as the input argument num_cqs, after controller restart then number of CQs will be changed

SetShutDownMode - Set shut down mode for the controller with specified input argument shutdown_mode. Controller reset/restart is needed after setting the shut down mode

SetResetType - Set the controller reset type with the specified input argument reset_type. Controller reset/restart is needed after setting the reset type

DeleteSQ - Delete the SQ based on the specified queue ID

CreateSQ - Create the SQ based on the specified queue ID

ModifySQ - Delete the specified SQ then create one SQ based on the input (ModifySQ first does DeleteSQ, then CreateSQ, so it combines two steps in one)

ShowQueue - Show the queue information based on the specified queue ID

ShowQueues - Show all queues information

DumpCmds - Show the Opcode, CID (command ID) and SQID (Submission Queue ID) of the pending commands
num_queues – number of queues specified with the ModifyQueues command (It is a necessary input for “ModifyQueues” command).
queue_depth – queue depth specified with the ModifyQueues and SetQueueDepth command (It is a necessary input for “ModifyQueues” and “SetQueueDepth” command).
aer_count – number of times to issue Asynchronous Events Requests specified with IssueAsyncEventRequests (It is a necessary input for “IssueAsyncEventRequests” command).
aer_auto – automatically issue new requests as events are received optionally specified with IssueAsyncEventRequests.
offset – NVMe controller register offset. For example CAP has offset = 0, VS has offset = 8, CC has offset = 0x14 and so on. Recommend to put hex value (It is a necessary input for “Read32Reg”, “Read64Reg”, “Write32Reg” and “Write64Reg” commands).
input_value – Input value to be written into NVMe controller register based on offset. Recommend to put hex value. (It is a necessary input for “Write32Reg”, “Write64Reg” and “SetCcCss” commands).
options_set_using_CMB – The set of options that are desired to be using CMB (please enter as hex number like 0x1F. It is a necessary input for “SetCmb” command).
chunk_size_RD_WD – The chunk size when doing RD (read data) and WD (write data) (please enter as decimal number like 1024. It is not a necessary input for “SetCmb” command and default value is 0).
enable_ve – Enable or disable virtualization enhancements. Default value is True so it will enable virtualization enhancements, and recommend to keep it True all the time. Optional input argument for command “SetUseVirtEnh”.
num_vqs – Number of virtual queues (decimal). Necessary input argument for command “SetUseVirtEnh”.
num_vis – Number of virtual interrupts (decimal). Necessary input argument for command “SetUseVirtEnh”.
num_vfs – Number of virtual functions to create (decimal). If clear to 0 and it means to delete all VFs. Necessary input argument for command “SetNumVFs”.
queue_count – Queue count (decimal). Number of Queues will be created after controller restart. Necessary input argument for command “SetQueueCount”.
num_cqs – Number of CQs (decimal). Number of CQs will be created after controller restart. Necessary input argument for command “SetNumCQs”.
shutdown_mode –
shut down mode for controller as follows. Necessary input for command “SetShutDownMode”.

Value

Description

0

Normal shut down (delete queues)

1

Abrupt shut down (don’t delete queues)

2

Normal shut down (don’t delete queues)

3

Abrupt shut down (delete queues)

reset_type –

Controller reset type. Necessary input for command “SetResetType”.

Value	Description
0	Normal (no shut down included)
1	Shut down before reset (includes shut down)
2	Shut down after reset (negative test case, in general user can ignore it)
3	Shut down before/wait after reset (negative test case, in general user can ignore it)

queue_id – Queue ID (decimal). Necessary input argument for command “DeleteSQ”, “CreateSQ”, “ModifySQ” and “ShowQueue”, but optional for command “DumpCmds” (if not provide queue_id in command “DumpCmds” then the default value will be -1 which will show all pending commands in all queues).
queue_size – Queue size. Optional input for “CreateSQ” and “ModifySQ”.
queue_priority – Queue priority. Optional input for “CreateSQ” and “ModifySQ”.
cq_id – Completion queue ID. Optional input for “CreateSQ” and “ModifySQ”.
physically_contiguous – Physically Contiguous. Optional input for “CreateSQ” and “ModifySQ”.
nvm_set_id – NVM Set Identifier. Optional input for “CreateSQ” and “ModifySQ”.
cq_size – Completion queue size. Optional input for “CreateSQ” and “ModifySQ”.
cq_physically_contiguous – Completion Queue Physically Contiguous. Optional input for “CreateSQ” and “ModifySQ”.
enable_hmb – Enable HMB if set to 1. If clear to 0 to disable HMB. Optional input argument for command “SetHmb” and default as 0.
hmb_allocation_size – HMB allocation size in units of 4 KB. Optional input argument for command “SetHmb” and default as 0.
num_hmb_chunks – Number of chunks for HMB. Optional input argument for command “SetHmb” and default as 0.
num_urgent_priority_queues – Number of queues with urgent priority. Necessary/optional input arguments for command “SetQueuePriority”.
num_high_priority_queues – Number of queues with high priority. Necessary/optional input arguments for command “SetQueuePriority”.
num_medium_priority_queues – Number of queues with medium priority. Necessary/optional input arguments for command “SetQueuePriority”.
num_low_priority_queues – Number of queues with low priority. Necessary/optional input arguments for command “SetQueuePriority”.

get_vlun_nvme_update_namespace(valid_command='CreateNamespace', nsid=1, lbaf=0, pil=0, mset=1, pi=0, create_num=1, create_size='1gb', create_priv=0, create_attach=1, csi=0, nvmsetid=0, anagrpid=0, xml_formatted_output=0, endgid=0, handles=0, handle_start=0, handle_incr=0)

Send a command to update one or all NVMe namespaces of a NVMe controller. Bit 3 of OACS (Optional Admin Command Support) if set to ‘1’, then the controller supports the Namespace Management capability. If cleared to ‘0’, then the controller does not support the Namespace Management capability.

pil, pi and mset make one magical combination as “prot” which is Protection of Namespace, default as “100” from “~pil ~mset pi”

Parameters:

valid_command –
command to send to the NVMe controller to update namespace. Valid commands are:

CreateNamespace

DeleteNamespace

AttachNamespace

DetachNamespace

ShowNamespace
nsid – NVMe namespace id. Omit or specify -1 to send to all namespaces. If CreateNamespace you don’t need to specify nsid and it will take the next available nsid number.
lbaf – Format of Namespace. Used for creating Namespace and can find from identify namespace output.
pil – Protection Information Location. If set to ‘1’ and protection information is enabled, then protection information is transferred as the first eight bytes of metadata. If cleared to ‘0’ and protection information is enabled, then protection information is transferred as the last eight bytes of metadata. This setting is reported in the End-to-end Data Protection Type Settings (DPS) field of the Identify Namespace data structure and is constrained by the End-to-end Data Protection Capabilities (DPC) field of the Identify Namespace data structure.

pi –

Protection Information. This field specifies whether end-to-end data protection is enabled and the type of protection information. The values for this field have the following meanings:

Value	Definition
000b	Protection information is not enabled
001b	Protection information is enabled, Type 1
010b	Protection information is enabled, Type 2
011b	Protection information is enabled, Type 3
100b to 111b	Reserved

When end-to-end data protected is enabled, the host shall specify the appropriate protection information in the Read, Verify, Write, or Compare commands.

mset – Metadata Settings (MSET). This bit is set to ‘1’ if the metadata is transferred as part of an extended data LBA. This bit is cleared to ‘0’ if the metadata is transferred as part of a separate buffer. The metadata may include protection information, based on the Protection Information (PI) field. If the Metadata Size for the LBA Format selected is 0h, then this bit is not applicable.
"prot" – is the magic combination of pil, pi and mset above, and implemented as following ~pil ~mset pi, but “prot” is not used in this API and it is only used for command line: strcpy(prot, “100”); | if (pil) { | prot[0] = pil[0] ^ 1; // convert “0” to “1” and vice versa | } | if (mset) { | prot[1] = mset[0] ^ 1; // convert “0” to “1” and vice versa | } | if (pi) { | prot[2] = pi[0]; | }
create_num – Number of new namespaces to create.
create_size – Size of namespace(s) to create. Size of each new Namespace - 0 to use all remaining space, or a number followed by ‘kb’ or ‘mb’ or ‘gb’ or ‘tb’ for a size in bytes, or a number followed by ‘b’ for a size in blocks
create_priv – Whether the created namespace(s) will be private or not. A value of one (1) indicates private. A value of zero (0) indicate not private. Default is 0.
create_attach – Whether the created namespace(s) will be attached or not. A value of one (1) indicates attached. A value of zero (0) indicate not attached. Default is 0.
csi – Command Set Identifier for the namespace to be created. For “CreateNamespace” only and default as 0 so NVM command set is specified. If set to 1 then Key/Value command set is specified. If set to 2 then ZNS command set is specified.
nvmsetid – NVM Set Identifier to be associated with this namespace to be created. For “CreateNamespace” only and default as 0 so the controller determines the NVM Set value to allocate the namespace.
anagrpid – ANA Group Identifier of the ANA group of which the namespace to be created is a member. For “CreateNamespace” only and default as 0 so the controller shall determine the ANAGRPID that is assigned to the namespace.
xml_formatted_output – output as XML formatted. Default as 0 so not output as XML formatted, anything other than 0 will output as XML formatted.

get_vlun_perform_trace(action='StartTracing', port=None, level=2, details=0, trigger_stop='Never', file_mb=100, get_trace=0)

Start or stop a trace session on a port; clear or retrieve the trace log.

Parameters:

action –

StartTracing (default)

StopTracing

ClearTrace
port – Physical port on which to start or stop the tracing session. -1 for all ports. Defaults to the instance port
level –

0 - tracing disabled

1 - trace errors

2 - trace non-R/W I/O (default)

3 - trace everything
details –

0 - do not add additional data (default)

1 - add CDB and user data to the trace log
trigger_stop –

Never - do not stop tracing (default)

OnError - stop tracing when an error occurs

OnFull - stop tracing when trace file reaches the maximum size
file_mb – maximum size of the trace file in MB. 1, 2, 5, 10, 100 (default), or 1024
get_trace –

0 - Do not return the trace log file contents. action will be performed (default)

1 - Return the current trace log file contents. Nothing else will occur

NOTE: If the trace file is large this will block for an extended period.

This is only recommended if tracing was enabled briefly.

get_vlun_port_list(): Returns list of all physical ports in a given system such as num_ports and all port IDs.

get_vlun_port_reset(phy=-1): Link reset a particular port and PHY (A value of -1 means reset all PHYs on the port)

get_vlun_port_status(): Returns port level status and performance data for a given port specified by user during object instantiation.

get_vlun_quarch_configure(addr, add, hostname=None)

Add/remove a quarch device to/from the system.

Parameters:

addr – address of quarch device to add or remove. In the add case, the value can be “usb” to allow all available usb quarch devices to be configured. Otherwise, the usb address must be the full address that would be returned by the vlunQuarchStatus or vlunQuarchSearch xml apis or the address presented in the IP address field of the GUI Quarch pages (i.e. usb(ID 16d0:0449 - Bus 002 Device 008)).
hostname – optional hostname to assign to configured quarch. Default is Quarch.
add –
add or remove quarch device

0 - remove quarch device

1 - add quarch device(s)

get_vlun_quarch_port_configure(slot, valid_command, name=None, delay=None, bounce_period=None, bounce_length=None, duty_cycle=None, enabled=None, timing_source=None, glitch=None, type=None, multiplier=None, length=None, glitch_prbs_rate=None, drive_mapping=None)

Configure a quarch at a specified port and slot. These commands are currently limited to sas and nvme controllers. Power modules and power switches are not supported by this xml api.

Parameters:

port – GUI assigned port id.
slot – slot of the quarch of the attached quarch.
command –
command to execute

ConfigureSource

ConfigureSignal

ConfigureGlitch

ConfigureGlitchPrbs

MapDrive
name – name of source or signal to configure.
delay – configure source delay
bounce_period – configure source bounce period
bounce_length – configure source bounce length
duty_cycle – configure source duty cycle
enabled –
configured source is enabled or disabled

on - enable source

off - disable source
timing_source – configured signal source used for signal timing
glitch –
configured signal glitch enabled or disabled

on - enable glitch

off - disable glitch
type – configure glitch type | single | multi
multiplier – configure glitch multiplier
length – configure glitch length
glitch_prbs_rate – configure glitch prbs rate
drive_mapping – drive mapping

get_vlun_quarch_port_status(slot): Returns the status of the quarch at the specified port and slot number configured quarch devices on the system.

get_vlun_quarch_port_trigger_error(slot=1, valid_command='PowerOff', name=None, setting=None)

Triggers specified quarch error at a specified port and slot.

Parameters:

port – GUI assigned port id.
slot – slot of the quarch of the attached quarch.
valid_command –
command to execute

Power Switch (i.e. QTL1574) only commands

PowerOffAll

PowerOnAll

SleepOnAll

SleepOffAll

Power Module (i.e. OTL1824) and devices attached to Power Switch (i.e. QTL1574) only commands

PowerOff

PowerOn

SleepOn - (power switch only)

SleepOff - (power switch only)

SetVoltage - (power module only)

SAS/NVMe Controller commands

PullDrive

PlugDrive

SingleGlitch

CycleGlitch

PRBSGlitch

StopGlitch

ResetValues
name – name of source or signal.
setting – voltage setting

get_vlun_quarch_search(ipaddr=None)

Reports the quarch devices on the system or at the specified ipv4 address or ipv4 addresses.

Parameters:

ipaddr – If not specified, returns the usb attached quarch devices on the system. Otherwise, returns the quarch information on quarch device at the ipv4 address or ipv4 addresses.

Returns:

a.b.c.d – returns the quarch information for the quarch device at the ipv4 address if a device is present at that address.
a.b.c.x-y – returns the quarch information for quarch devices specified by the subnet range x-y (I.e 192.168.1.110-112 - will check 192.168.1.110, 192.168.1.111 and 192.168.1.112 for quarch devices).

get_vlun_quarch_status(): Returns the configured quarch devices on the system.

get_vlun_search(serial_number='ABCDEFGH')

Search for a LUN using a serial number and return a link to LUN status.

Parameters:

serial_number – The given serial number for a lun that is being searched for. Please note certain special characters require special input handling, depending on how the API is invoked. As an example, let’s consider the presence of the + (plus) character in a serial number and how to handle it with various invocations of the vlunLunSearch API. Using the wget command interactively with - (standard out) requires substituting the hexadecimal value for the + character
port – Limit the search to the specified port. If not specified or -1, all ports the lun is found on shall be returned.

get_vlun_send_cdb(cdb='120000004000', data=None, in_size=None, out_size=None)

Send a user-supplied CDB to a given LUN.

Parameters:

cdb – bytes to send (hex digit string)
optional –

The following are optional parameters which may be passed:

data = bytes to be written, required if out_size is not zero (hex digit string)

in_size = number of input bytes to receive

out_size = number of output bytes to send

init = initiator number to send command from (if multiple initiators are created)

get_vlun_send_els(payload='0,61040008,1,01110f00', paylength=2, send_alias=16777213, dest_id=33, elscode=2)

Send the Extended Link Service (ELS) to non-SAS devices.

Parameters:

port – physical port number
payload – a comma separated list of word, value [, word, value, …] pairs. This argument is optional.
paylength – the decimal payload length in words up to 256
send_alias – the sender ID, equivalent to the number of Initiators or Targets created
dest_id – 3 byte hexadecimal destination ID
elscode – 1 byte hexadecimal ELS command code

get_vlun_set_initiator_config(extended_logging=None, allow_testing=None, latency_start=None, latency_width=None, array_name=None, persist_array_number=None, persist_target_number=None, controller_shutdown=None, use_sgls=None, write_enabled=None, fua=None, naca=None, lr=None)

Change initiator settings for an array, a target or a lun. Only arguments that need to be changed need to be passed in. Options must be passed in an XML file similar to those listed in the Action Interfaces.

Parameters:

port – physical port number of the target or lun to modify. If settings are for an array, parameter is omitted.
target – target id of the target or lun to modify. If settings are for an array, parameter is omitted. Otherwise, the port must be specified prior to this argument.
lun – lun id of the lun to modify. If settings are for an array or target, parameter is omitted. Otherwise, the target must be specified prior to this argument.
extended_logging –
extend logging while testing.

0 - extended logging disabled

1 - extended logging enabled
allow_testing –
allows testing.

0 - testing not allowed

1 - testing allowed
latency_start – allows setting of latency start in microseconds if system has a full feature license.
latency_width – allows setting of latency width in microseconds if system has a full feature license.
array_name – allows the array name for a target or array to be set. To clear the array name specify a value of “none”. If an array name is not set, the array_name value will not be returned by vlunGetInitiatorConfig.
persist_array_number – allows the persistent array number for a target or array to be set. To clear the persistent array number specify a value of -1. If a persistent array number is not set, the persist_array_number value will not be returned by vlunGetInitiatorConfig.
persist_target_number – allows the persistent target number for a target to be set. To clear the persistent target number specify a value of -1. If the persistent target number is not set, the persist_target_number will not be returned by vlunGetInitiatorConfig.
controller_shutdown –
controls how a target that is a NVMe controller shuts down.

0 - normal shutdown,

1 - abrupt shutdown
use_sgls –
tells a target that is a NVMe controller use SGLs instead of PRPs.

0 - off

1 - use SGLs for data only in I/Os

2 - use SGLs for both data and metadata in I/Os
write_enabled –
controls if lun is write enabled or not

0 - writes disabled

1 - writes enabled
fua –
controls if fua is set in writes/read.

0 - fua disabled

1 - fua enabled
naca –
controls if naca is set in writes/read (does not apply to NVMe namespaces).

0 - naca disabled

1 - naca enabled
lr –
controls if lr is set in writes/read for NVMe namespaces.

0 - lr disabled

1 - lr enabled

get_vlun_set_port_config(state=None, speed=None, mode=None, nickname=None, num_initiators=None, num_targets=None, unique_luns_per_initiator=None, discovery_mode=None, auto_reprobe=None, compare_type=None, lba_in_patterns=None, no_t10_dif=None, reserved_start_area=None, reserved_end_area=None, test_limit=None, use_verify=None, use_wsame=None, use_xcopy=None, check_write_overlap=None, no_path_timeout=None, allow_testing=None, extended_logging=None, nvme_timeout=None, default_num_queues=None, default_queue_depth=None, sqes_per_seq=None, controller_shutdown=None, use_sgls=None, base_wwnn=None, base_wwpn=None, oui=None, symbolic_portname=None, enable_fcp2=None, enable_confirm=None, r_a_tov=None, e_d_tov=None, r_t_tov=None, dest_mac=None, tx_crc=None, rx_crc=None, fip_mode=None, fip_version=None, fip_vlan_disc_mode=None, fip_enode_disc_mode=None, fip_fpma_spma_mode=None, fip_vn2vn_mode=None, flogi_mode=None, fake_fc_switch=None, fake_fcid=None, fake_fcf=None, fake_vfid=None, lldp_mode=None, dcbx_version=None, auto_vlan=None, payload_size=None, pause_type=None, send_offload=None, receive_offload=None, fcoe_tx_rate_limit=None, mac_addr=None, ip_addr=None, netmask=None, mtu=None, vlan_id=None, vlan_pri=None, type=None, keep_alive_timeout=None, discovery_behavior=None)

Change port level settings. Only arguments that need to be changed need to be passed in. Options must be passed in an XML file similar to those listed in the Action Interfaces.

Parameters:

port – physical port number to configure (mandatory and must be listed first)
state – (Offline,Online)
speed – (1G,2G,4G,8G,10G,16G)
mode – (Init/Targ)
nickname – nick name assigned to port. If not assigned, this value is not returned in the vlunGetPortConfig call.

Initiator settings

num_initiators: number of initiators to configure (initiator mode)
num_targets: number of targets to configure (target mode)
unique_luns_per_initiator: create up to this many unique LUNs per initiator. 0 means all initiators see the same LUNs
discovery_mode: how to discover targets. 0 - all ports (can be slow), 1 - discover registered targets, 2 - registered/unregistered targets
auto_reprobe: turn off/on auto re-probing of targets
compare_type: compare test behavior. 0 - entire transfer, 1 - first and last blocks, 2 - first and last 4 bytes of each block
lba_in_patterns: use lba in write patterns
no_t10_dif: disable t10 dif support
reserved_start_area: amount of space in MB to reserve at beginning of device
reserved_end_area: amount of space in MB to reserve at end of device
test_limit: amount of space in MB to limit test to
use_verify: use verify for Read-Compare
use_wsame: use SCSI WriteSame for Write
use_xcopy: use SCSI ExtendedCopy for Write
check_write_overlap: checking for write overlap behavior. 0 - do not check for write overlaps, 1 - check write overlaps on other writes, 2 - check write overlaps on other reads and writes
no_path_timeout: number of milliseconds to wait for the path to a device to return
allow_testing: indicates if testing is allowed on this port. 0 - testing not allowed, 1 - testing allowed,
extended_logging: enable extended error logging

NVMe settings

nvme_timeout: timeout used for long NVMe operations
default_num_queues: default setting for number IO queues
default_queue_depth: default setting for depth of IO queues
sqes_per_seq: when using SGLs, number of SGEs per segment
controller_shutdown: control how controller shuts down 0 - normal shutdown, 1 - abrut shutdown,
use_sgls: use SGLs instead of PRPs 0 - off, 1 - use SGLs for data only in I/Os, 2 - use SGLs for both data and metadata in I/Os

FC settings

base_wwnn: base wwnn to seed all initiators from
base_wwpn: base wwpn to seed all initiators from
oui: oui portion of wwn’s to set
symbolic_portname: symbolic port name to use
enable_fcp2: 0 - disable FCP2 retry, 1 - enable FCP2 retry
enable_confirm: 0 - disable sending FCP confirm, 1 - enable sending FCP confirm
r_a_tov: fc r_a_tov value in ms
e_d_tov: fc e_d_tov value in ms
r_t_tov: fc r_t_tov value. 0 for 100ms or 1 for 100us

FCoE settings

dest_mac: FLOGI Mac address
tx_crc: generate tx fc-crc. 0 - off, 1 - on
rx_crc: verify rx fc-crc. 0 - off, 1- on
fip_mode: 0 - off, 1 - auto, 2 - on
fip_version: 0 - version 0, 1 - version 1
fip_vlan_disc_mode: 0 - disabled, 1 - Send Untagged Frames, 2 - Send Tagged Frames, 3 - Send Untagged & Tagged Frames
fip_enode_disc_mode: enable or disable T11/FCoE 09-450v1 (0,1)
fip_fpma_spma_mode: 0 - FPMA and SPMA, 1 - Fabric Provided MAC Address, 2 - Server Provided MAC Address
fip_vn2vn_mode: enable or disable T11/FCoE 10-019v4 (0,1)
flogi_mode: drop flogi (0), or ACC (1)
fake_fc_switch: act as a fake FC switch (0,1)
fake_fcid: starting fc_id to use for fake switch
fake_fcf: act as a fake FCF (0,1)
fake_vfid: virtual fabric id to use when in fake fcf mode
lldp_mode: 0 - disable, 1 - enable, 2 - enable and wait for negotiation
dcbx_version: use dcbx version 1.00 (100) or version 1.01 (101)
auto_vlan: enable or disable auto vlan discovery (0,1)
payload_size: size in bytes of the maximum payload supported
pause_type: 0 - auto, 1 - none, 2 - standard, 3 - PFC
send_offload: 0 - off, 1 - Enable offloading sending data from the adapter
receive_offload: 0 - off, 1 - Enable offloading receiving data from the adapter
fcoe_tx_rate_limit: percentage to limit fcoe traffic transmit tx to

Network settings

mac_addr: ethernet mac address for port (xx:xx:xx:xx:xx:xx)
ip_addr: ip address for port (x.x.x.x)
netmask: netmask to use for port
mtu: Ethernet MTU to use
vlan_id: VLAN id to use if not in auto mode
vlan_pri: VLAN priority to use (0-7) if not in auto mode

Port setting

type: FCoE or iSCSI. This option is applicable only for the cards that support both protocols. The action is to convert the port’s protocol from its current setting to the one passed in the command.
keep_alive_timeout: Keep Alive Timeout value
discovery_behavior: Discovery Behavior. If set to 1 then keep discovery controllers connected (RDMA & TCP only, not FC)

get_vlun_set_port_test_parameters(general_timeout=None, tape_timeout=None, rw_timeout=None, taskmgmt_timeout=None, busy_delay=None, busy_retry=None, onerror_action=None, retry_count=None, queuing_policy=None, test_limits=None, test_control=None, perf_limits=None, burstiness=None, test_alert_script=None, pass_end_delay=None, xcopy_timeout=None, compare_type=None, lba_in_patterns=None, no_path_timeout=None, no_t10_dif=None, reserved_start_area=None, reserved_end_area=None, test_limit=None, use_verify=None, use_wsame=None, use_xcopy=None, check_write_overlap=None, verify_write_buffer=None, use_zone_append=None, stop_after_error_handling=None, jedec_random=None, shadow_threads=None, ios_min=None, mbs_min=None, latency_limits=None, nvme_queue_select=None, dealloc_after_compare=None, stream_identifier=None, verify_writes_mode=None, verify_atomic_writes=None, app_tag=None, nvme_prchk=None, continue_after_miscomp=None, timeout_error_recovery=None, use_cmpwr=None, metadata_pattern=None, verify_timeout=None, unmap_timeout=None, override_fua=None, media_access_timeout=None, read_timeout=None, zone_append_timeout=None, write_verify_timeout=None, write_same_timeout=None, dsm_timeout=None, abort_timeout=None, zone_queue_depth=None, override_naca=None, scsi_protect=None, compare_timeout=None, zone_queue_depth_time_limit=None, write_zeroes_timeout=None, use_wrver=None, write_uncorr_timeout=None, compare_and_write_timeout=None, fast_exit=None, override_lr=None, write_timeout=None, miscompare_limit=None)

Change port level test parameters. Only arguments that need to be changed need to be passed in.

Parameters:

port – physical port number to configure (mandatory)
general_timeout – timeout for general commands (ms)
tape_timeout – timeout for tape movement commands. (non NVMe port)
rw_timeout – timeout for read/write commands
taskmgmt_timeout – timeout for task management commands
busy_delay – delay time before retrying busy commands. (non NVMe port)
busy_retry – number of times to retry commands for busy status. (non NVMe port)
onerror_action –
action to take when error is encountered.

Continue - ignore error and keep test running,

StopThread - stop current test thread,

StopTest - stop all threads under this test,

StopAllTests - stop all tests
retry_count – number of retries to attempt before logging failure
queuing_policy – policy to use when queuing commands. (non NVMe port)
test_limits – size,position,units (0 or 1 for blocks or MBs)
test_control –
Allows user to custom configure what to do in case of various errors conditions (ignore, log, retry, fail). Errors can be chained together with a semicolon between. The syntax for an error condition Type,action,status,key,asc,ascq.

> Type - 1 (Path failed), 2 (Residual mismatch), 3 (SCSI status) or 5 (NVMe status)

> Action - 0 (ignore), 1 (log), 2 (retry), 3 (fail), 4 (alert)

> Status - NVMe/SCSI status

> Key - for SCSI status only, SCSI hex sense key value (non NVMe port)

> ASC/ASCQ - for SCSI status only, SCSI hex ASC/ASCQ value (non NVMe port)
perf_limits – iops limit, MBs limit, type (0 for LUN level, 1 for test level)
burstiness – burst limit, type (0 for LUN level, 1 for test level)
test_alert_script – script to run if test control action is set to alert. Scripts are located on the system in the /virtualun/ lundata/initscriptfiles directory
pass_end_delay – delay in seconds between passes
xcopy_timeout – timeout for ExtendedCopy commands. (non NVMe port)
compare_type –
compare test behavior.

0 - entire transfer

1 - first and last blocks

2 - first and last 4 bytes of each block
lba_in_patterns – use lba in write patterns
no_path_timeout – number of milliseconds to wait for the path to a device to return
no_t10_dif – disable t10 dif support
reserved_start_area – amount of space in MB to reserve at beginning of device
reserved_end_area – amount of space in MB to reserve at end of device
test_limit – amount of space in MB to limit test to
use_verify – use verify for Read-Compare
use_wsame – use SCSI WriteSame for Write
use_xcopy – use SCSI ExtendedCopy for Write
check_write_overlap –
checking for write overlap behavior.

0 - do not check for write overlaps,

1 - check write overlaps on other writes,

2 - check write overlaps on other reads and writes
verify_write_buffer –
Verify Write Buffer.

0 - Disable,

1 - Enable
use_zone_append –
Enable or disable the use NVMe ZoneAppend for zone filling. Optional values:

0 - Disable the use NVMe ZoneAppend for zone filling. It will use NVM Write or other writes.,

1 - Enable the use NVMe ZoneAppend for zone filling. It will NOT use NVM Write or other writes but use zone append instead.
stop_after_error_handling –
when a test is stopped, it should wait until the path returns (or the No Path Timeout expires), and/or it should finish retries, so we know whether that I/O – the one we’re in the middle of – succeeded or not. Optional values:

0 - If an initiator test is signaled to stop, while it is in the middle of error handling for a failed I/O (either waiting for a missing path to return, or in the middle of retries), that test simply exits, and returns status (Passed or Failed) based on previous I/Os, not the current I/O.,

1 - If an initiator test is signaled to stop and the stop will be delayed until any I/O that is currently having errors handled, finishes, and at that point we can decide Passed vs. Failed. (In the interim, the test state will be Stopping.)
jedec_random –
Random I/O size selection algorithm. Optional values:

0 - default, the current random I/O size selection algorithm is used (“random” is selected when a test starts and the I/O size is a negative ,

1 - f 1, and the I/O size is -1, then the JEDEC random I/O size table below will be obeyed.
shadow_threads – When a new test starts, there will always be at least 1 real thread; next, up to N shadow threads are created; then, the remaining thread count will also be real threads. The shadow threads will be distributed across the real threads as evenly as possible (round-robin, essentially) but this distribution is fixed at creation time. If a real thread stops due to an error, its shadow threads will stop also.
ios_min – Minimum required number of I/Os per second.
mbs_min – Minimum required throughput in megabytes per second.
latency_limits – Latency checking as each I/O completes. For example LatencyLimits=A,B,C, check whether its latency exceeds A. If so, log it to tracing, and then if B is not 0, it is a count of how many latency violations are allowed. If C is not 0, then it is a time period in seconds that limits B – there must be B violations within C seconds for an error to occur. If C is 0, then after B violations over the life of the test, an error occurs. When an error occurs, the test stops.
nvme_queue_select –
NVMe Queue selection for R/W IOs (NVMe port). Optional values:

-1: Auto (default),

-2: Round Robin,

-3: Urgent Priority,

-4: High Priority,

-5: Medium Priority,

-6: Low Priority,

1 - 64: Queue number
dealloc_after_compare –
Deallocate written blocks after a compare. These 3 values are dealloc_after_compare, dealloc_verify and dealloc_use_random.

dealloc_after_compare

0 is disable (if you do not want to deallocate written blocks after compare).,

1 is deallocate written blocks using “DatasetMgmt : Unmap”.,

2 is deallocate written blocks using “WriteZeroes/Deallocate : WriteSame/Unmap”.

dealloc_verify

0 means disable (Don’t verify deallocated blocks),

1 means “Verify All Zeroes” (Verify deallocated blocks contain all zeroes),

2 means “Verify All Ones”

(Verify deallocated blocks contain all ones).

dealloc_use_random

0 means not with Multiple Descriptors (for SCSI) or With Multiple Ranges (for NVMe) to deallocate a random number of descriptors.

1 means with Multiple Descriptors (for SCSI) or With Multiple Ranges (for NVMe) to deallocate a random number of descriptors.
stream_identifier –
Indicates a stream identifier should be automatically generated when a write test starts, using a value that is unique per-test, per-device, or perthread. Choices include:

0: None,

-1: Per Test,

-2: Per Device,

-3: Per Thread, and

any number >=1: Custom stream ID
verify_writes_mode –
Path Failure on Write Pass

0: Continue - Retry any write commands interrupted by path failure. The Compare/Verify test will continue with the current write pass.,

1: Verify - Stop existing write pass in the event of a path failure, and begin read/compare pass when a path returns. Continue with next write pass after successful completion of read/compare pass. The Compare/Verify test will stop the write pass and will verify all writes up to the path failure, then continue.,

2: Verify & Stop - Stop existing write pass in the event of a path failure, and begin read/compare pass when a path returns. Stop test upon successful completion of read/compare pass. The Compare/Verify test will stop the write pass and will verify all writes up to the path failure, then stop (instead of continuing).
verify_atomic_writes –
Any write that was not completed yet will be subject to verification if this is enabled. Each block can be in one of two states: (1) New data that was written or (2) Old data that has not yet been written (the write did not complete). New versus old data is determined via the timestamp. If the timestamp matches, it is considered new data, and if not, old data. If the timestamp is new, the entire block must match including the portion that is not timestamped. If the timestamp doesn’t match (the data is old) then none of the rest of the data matches. After looking at the timestamp to verify if it is new or old, this command checks whether it is obeying the atomic write unit as well. These 2 values are Verify Atomic Writes enable/disable and AWU (Atomic Write Unit) size:

First value: Verify Atomic Writes enable/disable. 0 is disable which is default, 1 is enable.

Second value: AWU (Atomic Write Unit) size. Atomic Write Size guides how many blocks in a row to verify if you perform writes of more than one block.

For example, if you have an 8-block write and you set the Atomic Write Unit to 4 blocks, the 8-block write is verified in two chunks of four. (For NVMe, a default value of 0 uses the AWUPF value reported in Identify Controller.)
app_tag –
T10 DIF Application Tag and Application Tag Mask:

T10 DIF Application Tag: application tag value for T10 DIF, default is 0.

T10 DIF Application Tag Mask: application tag mask value for T10 DIF, default is ffff.
nvme_prchk – PRCHK value to use in Read/Write/Compare commands. These 2 values are as follows: Use default PRCHK value: default is 0 (7 for Types 1 and 2; 6 for Type 3) Custom PRCHK value: use custom value for PRCHK.
continue_after_miscomp –
Complete Read Pass on Compare Error.

0: Disable. After a Compare Error, continue read/compare I/Os if doing I/O in passes.

1: Enable. After a Compare Error, immediately stop I/Os.
timeout_error_recovery –
A bitmask of things that are allowed in response to an I/O timing out. It is the handling for timeout error recovery (can combine following options by adding them together, default is 5):

Bit 0: Send Abort Task (SCSI) or Abort (NVMe) to end the timed-out command if set to 1. If that doesn’t work (I/O still outstanding), then

Bit 1: Send Logical Unit Reset (SCSI) to end the timed-out command if set to 1. If that doesn’t work (I/O still outstanding), then

Bit 2: Send Target Reset (SCSI) or Controller Reset (NVMe) to end the timed-out command if set to 1. If that doesn’t work (I/O still outstanding), then fail the test.
use_cmpwr –
When enabled, use NVMe CompareAndWrite to do Read/Compare and then Write operations.

0: Disable,

1: Enable
metadata_pattern –
Specify the Metadata pattern. Choices include:

0: All Zeroes, put all zeros into metadata of each block.

1: All Ones, put all ones into metadata of each block.

2: Test Pattern, extend test pattern into metadata of each block (default value)
verify_timeout – timeout for verify command (ms)
unmap_timeout – timeout for unmap command (ms, SCSI)
override_fua –
Possible values for FUA (Force Unit Access) are:

0: no override, obey the current device setting

1: disable FUA even if enabled in the device

2: enable FUA even if disabled in the device
media_access_timeout – timeout for media access command (ms). It can be set non-0 to override other timeout values. Use MediaAccessTimeout when doing the Read command (for NVMe) or the Test Unit Ready command (for SCSI), in preference to ReadWriteTimeout (for NVMe) or GeneralTimeout (for SCSI).
read_timeout – timeout for read command (ms)
zone_append_timeout – timeout for zone append command (ms, NVMe)
write_verify_timeout – timeout for WriteVerify command (ms, SCSI)
write_same_timeout – timeout for WriteSame command (ms, SCSI)
dsm_timeout – timeout for DSM command (ms, NVMe)
abort_timeout – timeout for abort command (ms)
zone_queue_depth –
This is the QD value, or number of threads per zone. The default is 1. There are some test limitations (for example ZoneQueueDepth=A):

1. The number of threads should be a multiple of A.

2. The number of threads should be less than the Zone Max Active limit (MAR).

3. Passes are not supported and will be silently turned off.
override_naca –
Possible values for NACA (Normal Auto Contingent Allegiance in SCSI) are:

0: no override, obey the current device setting

1: disable NACA even if enabled in the device

2: enable NACA even if disabled in the device
scsi_protect – xxPROTECT value to use in Read/Write/Verify commands, 0 means default Type 0, 1 for Types 1, 2, and 3
compare_timeout – timeout for compare command (ms)
zone_queue_depth_time_limit – This is the time to wait for threads to be “done” before moving from one zone to the next, or to stop the test. The default is 1000 ms.
write_zeroes_timeout – timeout for write zeroes command (ms)
use_wrver –
use SCSI WriteVerify. This command does the write then read then compare steps for us, during a Compare test this is the only command that needs to be issued (and since it’s a “write” command, only the write I/Os and bytes counters will go up). Also, since it does both write and read, the only test that it’s suitable for is “Compare”.

0: Disable,

1: Enable
write_uncorr_timeout – timeout for write uncorrectable command (ms)
compare_and_write_timeout – timeout for compare and write fused command (ms)
fast_exit –
exit setting for stopping an initiator test.

0: Default value. Allows I/Os to finish when stopping a test and using the normal timeout values.

1: When stopping a test, the normal timeout values are overridden with 2 seconds.
override_lr –
Possible values for LR (Limited Retry in NVMe) are:

0: no override, obey the current device setting

1: disable LR even if enabled in the device

2: enable LR even if disabled in the device
write_timeout – timeout for write command (ms)
miscompare_limit – Miscompare Limit. If set to N then N is the number of bytes that are allowed to miscompare when verifying writes during a Compare test, and power is lost and then restored. Some drives apparently have a volatile cache that can lose some amount of data during this test. The knob determines how much data can be lost, and still have the test pass. Since drives should never lose data, the default is 0. If set non-0 will simply suppress the counting of miscompare errors, if the number of bytes miscomparing is less than the given limit.

get_vlun_start_test(test_type='Read', threads=1, blocks=1, ios=0, pass_ios=0, seek_type=0, opcode=0, paused=0, initiator=-1, pattern=0, multipath_mode=0, seed=0, dedup='1:1', comp='1:1', dup_uniq=0, wblocks=1, wskips=1, skip_blocks=0, test_name=None, all_targets=0, all_luns=0, use_defaults=0, override_parameters='')

Start a new test to a given port, target (or all targets) and lun (or all luns).

Parameters:

test_type – Read, Write, Compare, Verify, Rewrite or RrWwZzUu, where r/w/z/u are positive decimal integers, for example R40W30Z20U10; the new ZzUu part can be omitted for backwards compatibility, in which “Z” means Write Zeroes and “U” means Write Uncorrectable.
threads – number of test threads to run
blocks – number of blocks per IO (-1 for random I/O sizes, or -N for Random I/O sizes that are multiples of N blocks, or a number for an I/O size in blocks, or a number followed by a size (‘kb’, ‘mb’) for an I/O size in bytes (e.g., 3.5kb); 0 is invalid)
ios – number of IOs to do (IOs per thread. 0 for unlimited, or a number as a limit in I/Os (e.g., 1000), or a number followed by ‘s’ as a limit in seconds (e.g., 10s), or a number followed by a size (‘kb’, ‘mb’, ‘gb’, ‘tb’) as a limit in bytes, or -N to use N times the device capacity as a test limit)
pass_ios – for compare tests the number of ios to write before reading back (a number followed by a size (‘kb’, ‘mb’, ‘gb’, ‘tb’) as a size per pass, or -1 to use the device capacity as the size per pass)
seek_type – io access type (0 - Sequential, 1 - Random, 2 - Min/Max, 3 - Butterfly)
opcode – opcode to use (6, 10, 12, 16, 0 for random, for SCSI only)
paused – start test in paused state (0 means start I/O test immediately,1 means start I/O test at paused state, and need to send unpause with API get_vlun_change_test_state() to start test)
initiator – initiator test is being run from (-1 for all)
pattern – pattern being used for writes. 0 - random, 1 - 0x00ff00ff, 2 - 0x55aa55aa, 3 - 8-bit incr, 4 - 8-bit walking (1,0), 5 - 0x0000ffff, 6 - 0x5555aaaa, 7 - 16-bit incr, 8 - 16-bit walking (1,0), 9 - 32-bit incr, 10 - Low Frequency 8B/10B, 11 - Med Frequency 8B/10B, 12 - High Frequency 8B/10B, 13 - Jitter (CJPAT), -1 - custom, -2 - existing data (for the following the last to digits can be changed to indicate de-dup percentage). Examples: -100 - random, 0% dup -101 - random, 1% dup -175 - random, 75% dup -199 - random, 99% dup -300 - random, nodup -303 - random, dedup&compression
multipath_mode – if multiple paths to lun are detected, how to handle them 0 - default, 1 - this path, 2 - one path, 3 - all paths, 4 - act/opt paths, 5 - act/non-opt paths
seed – random seed to use
dedup – dedup ratio
comp – compression ratio
dup_uniq – duplicate uniqueness percentage
wblocks – blocks to write (for Rewrite test)
wskips – blocks to skip after writing (for Rewrite test)
skip_blocks – blocks to skip after each IO. Also used for I/O alignment. If alignment is wanted enter the value as a negative value (ex: -4kb)
test_name – the I/O test name you’d like to have. If you don’t provide the name and it will use default test name as “testType_testSeq”
all_targets – Default as 0. If set to 1 then start the specified I/O test on all targets/controllers (including all LUNs under the controllers) in the tester, which means port level I/O test
all_luns – Default as 0. If set to 1 then start the specified I/O test on all LUNs under the same controller, which means controller level I/O test
use_defaults – Default as 0 which means simply starts an I/O test using current parameters. If set to 1 then starts an I/O test using default parameters

override_parameters –

Default as “” which means no override parameters. If set to “LBAInPatterns=3 NoPathTimeout=90” then start an I/O test with these 2 parameters override. Please use space to separate parameters.

use_defaults	override_parameters[2048]	expected I/O test
0	empty_string	simply starts an I/O test using current parameters
0	with input override parameters	starts an I/O test using current parameters but overrides parameters with input
1	empty_string	simply starts an I/O test using default parameters
1	with input override parameters	starts an I/O test using default parameters but overrides parameters with input

get_vlun_status(): Returns status and performance information for a given lun (specified by user during object instantiation).

get_vlun_stop_test(test_id, all_targets=0, all_luns=0)

Stop a currently running test of a given port, target (or all targets), lun (or all luns) and test_id (like “Read_1”)

Parameters:

test_id – Test ID as format “IOType_IOName”. The IOType can be Read, Write, Compare, Verify, Rewrite or RrWwZzUu, where r/w/z/u are positive decimal integers. In general get from API “get_vlun_start_test” output
all_targets – Default as 0. If set to 1 then stop the specified I/O test on all targets/controllers (including all LUNs under the controllers) in the tester, which means port level I/O test
all_luns – Default as 0. If set to 1 then stop the specified I/O test on all LUNs under the same controller, which means controller level I/O test

get_vlun_system_info(): Returns system software revision information such as hostname, software_version, kernel_version, release date and time.

get_vlun_target_apply_profile(profile=None, type=None)

Apply a target profile.

Parameters:

port – the mandatory integer port value or * to apply to all target ports.
target – the mandatory integer target value.
lun – the mandatory integer lun value.
profile – the mandatory profile name.
type – the mandatory profile type: disk, tape, etc.

get_vlun_target_create_profile(name)

Create a target profile.

Parameters:

port – the mandatory integer port value or * to apply to all target ports.
target – the mandatory integer target value.
lun – the mandatory integer lun value.
name – the mandatory profile name.

get_vlun_target_inject_errors(type, count=None, between=None, passes=None, opcode=None, LBA=None, delay=None, badstatustype=None, key=None, asc=None, ascq=None, bbflag=None, bblbn=None)

Inject selected target errors.

Parameters:

port – the mandatory integer port value.
target – the mandatory integer target value.
lun – the mandatory integer lun value.
type –
the (single) type of error to inject or error flag to clear/set.

Group 1

abortrsp

busy

delay

delayrsp

droprsp

outorderdata

queuefull

readcorrupt

readover

readunder

writecorrupt

writeover

writeunder

The Group 1 error types use the following parameters:

count = the number of this the error is to be injected

between = the number of PDUs to pass between errors

passes = the number of times to repeat the count/between cycle

opcode = the SCSI opcode onto which the error will be injected

LBA= logical block address

delay = in milliseconds before injecting the error

Group 2

The Group 2 error types use most of the Group 1 parameters, with the exception of delay. The delay parameter is not used for group 2 error types.

drop

abort

Group 3

badstatus

The Group 3 error type uses all of the Group 1 parameters, with the addition of:

badstatustype = the SCSI hexadecimal status value

Group 4

checkcond

The Group 4 error type uses all of the Group 1 parameters, with the addition of:

key = sense key code

asc = additional sense code

ascq = additional sense code qualifier

Group 5

badblock

The Group 5 error type uses the following parameters:

bbflag = 1 to enable, 0 to disable

bblbn = the hexadecimal LBN to add or remove

The following error types are flags and may be set (1) or cleared (0).

clearerroronLUR

logonerror

The following performs an action:

clearbadblocktable flag - 1 to enable

get_vlun_target_injected_error_status(): Returns the status of injected errors of a given port/target/lun.

get_vlun_target_list(): Returns a list of targets on a given port (specified by user during object instantiation) with links to their status pages.

get_vlun_target_log_on_error(error_log_entries): Returns a number of error log entries for injected errors of a given port/target/lun.

get_vlun_target_lun_config(): Returns target LUN session parameters.

get_vlun_target_lun_smart_config(): Returns target LUN’s Smart parameters.

get_vlun_target_set_lun_config(assignlist=None, badblock=None, bind=None, clearerrors=None, confirmenabled=None, devicename=None, devicetype=None, hardalpa=None, maptarget=None, mirrortarget=None, oui=None, owner=None, productID=None, productRev=None, profile=None, readdelay=None, reqsense=None, restore=None, sasaddress=None, save=None, sensedataformat=None, unmaptarget=None, unmirrortarget=None, vendorCDB=None, vendorID=None, wwnn=None, wwpn=None, xferrdysize=None, blockSize=None, custominquiry=None, echoonerror=None, encserv=None, exists=None, lunmult=None, lunnum=None, luncount=None, mediumrotationrate=None, notready=None, protect=None, qdepth=None, readsize=None, removable=None, thinProvisioned=None, tape=None, uniqueinquiryonmapped=None, writelimithigh=None, writelimitinvert=None, writelimitlow=None, writeprotect=None, writesize=None)

Set target LUN session parameters.

Parameters:

port – the mandatory integer port value.
target – the mandatory integer target value.
lun – the mandatory integer lun value.
param –
one or more parameters to be set. Supported parameters include:

assignlist string

badblock 0 | 1,LBN

bind string - pathname

clearerrors flag - 0 or 1

confirmenabled flag - 0 or 1 FCoE

devicename string SAS

devicetype integer

hardalpa integer pair FCoE

maptarget Args: A_port,A_targ,B_port,B_targ

mirrortarget this & above /portX/port

oui hexadecimal FCoE

owner string

productID string

productRev string

profile string

readdelay integer

reqsense sense key, asc, ascq

restore string - pathname

sasaddress hexadecimal SAS

save string - pathname

sensedataformat string - Fixed or Descriptor

unmaptarget Args: A_port,A_targ,B_port,B_targ

unmirrortarget this & above /portX/port

vendorCDB

vendorID string

wwnn hexadecimal FCoE

wwpn hexadecimal FCoE

xferrdysize integer

blockSize integer

custominquiry flag - 0 or 1

echoonerror flag - 0 or 1

encserv integer

exists flag - 0 or 1

lunmult integer

lunnum integer

luncount integer

mediumrotationrate integer

notready flag - 0 or 1

protect flag - 0 or 1

qdepth integer

readsize integer

removable flag - 0 or 1

thinProvisioned flag - 0 or 1

tape integer

uniqueinquiryonmapped flag - 0 or 1

writelimithigh integer

writelimitinvert flag - 0 or 1

writelimitlow integer

writeprotect flag - 0 or 1

writesize integer

get_vlun_target_set_lun_smart_config(mfgyear=None, mfgweek=None, maxtemp=None, currtemp=None, currtempmin=None, currtempmax=None, currtempincr=None, currtempfreq=None, readerr=None, readerrmin=None, readerrmax=None, readerrincr=None, readerrfreq=None, writeerr=None, writeerrmin=None, writeerrmax=None, writeerrincr=None, writeerrfreq=None, verifyerr=None, verifyerrmin=None, verifyerrmax=None, verifyerrincr=None, verifyerrfreq=None, startstop=None, startstopmin=None, startstopmax=None, startstopincr=None, startstopfreq=None, loadunload=None, loadunloadmin=None, loadunloadmax=None, loadunloadincr=None, loadunloadfreq=None, growndefect=None, growndefectmin=None, growndefectmax=None, growndefectincr=None, growndefectfreq=None, override_log_page_02h=None, override_log_page_03h=None, override_log_page_05h=None, override_log_page_0Dh=None, override_log_page_0Eh=None, override_log_page_2Fh=None, lifeused=None, lifeusedtmin=None, lifeusedmax=None, lifeusedtincr=None, lifeusedfreq=None, override_log_page_11h=None)

Set target LUN’s smart parameters.

Parameters:

port – the mandatory integer port value.
target – the mandatory integer target value.
lun – the mandatory integer lun value.
param –
one or more parameters to be set. Supported parameters include:

mfgyear integer. Manufacturing Year.

mfgweek integer. Manufacturing Week

maxtemp integer. Drive Trip Temperature in Celsius.

currtemp integer. Current Temperature.

currtempmin integer. Minimum Temperature.

currtempmax integer. Maximum Temperature.

currtempincr integer. Increment amount per frequency.

currtempfreq string. Increment frequency. Add ms for millisecond, s for seconds, m for minutes and h for hours

readerr integer. Read Errors

readerrmin integer. Minimum Read Errors

readerrmax integer. Maximum Read Errors

readerrincr integer. Increment amount per frequency.

readerrfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

writeerr integer. Write Errors

writeerrmin integer. Minimum Write Errors

writeerrmax integer. Maximum Write Errors

writeerrincr integer. Increment amount per frequency.

writeerrfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

verifyerr integer. Verify Errors

verifyerrmin integer. Minimum Verify Errors

verifyerrmax integer. Maximum Verify Errors

verifyerrincr integer. Increment amount per frequency.

verifyerrfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

startstop integer. Start Stop Cycles

startstopmin integer. Minimum Start Stop Cycles102

startstopmax integer. Maximum Start Stop Cyles

startstopincr integer. Increment amount per frequency.

startstopfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

loadunload integer. Load Unload Cycles

loadunloadmin integer. Minimum Load Unload Cycles

loadunloadmax integer. Maximum Load Unload Cyles

loadunloadincr integer. Increment amount per frequency.

loadunloadfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

growndefect integer. Grown Defects

growndefectmin integer. Minimum Grown Defects

growndefectmax integer. Maximum Grown Defects

growndefectincr integer. Increment amount per frequency.

growndefectfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

override_log_page_02h flag - 0 or 1. Override Write Error Counters page

override_log_page_03h flag - 0 or 1. Override Read Error Counters page

override_log_page_05h flag - 0 or 1. Override Verify Error Counters page

override_log_page_0Dh flag - 0 or 1. Override Temperature page

override_log_page_0Eh flag - 0 or 1. Override Start-Stop103 Cycle Counter

override_log_page_2Fh flag - 0 or 1. Override Informational Exceptions

Additional parameters for SSD drives

lifeused integer. Life Used

lifeusedtmin integer. Minimum Life Used

lifeusedmax integer. Maximum Life Used

lifeusedtincr integer. Increment amount per frequency.

lifeusedfreq string. Increment frequency. Add ms for milliseconds, s for seconds, m for minutes and h for hours.

override_log_page_11h flag - 0 or 1. Override Solid State Media

get_vlun_target_status(): Returns status information for a given target (specified by user during object instantiation) and a list of luns under that target.

get_vlun_task_management(management_command='ControllerReset', initiator=-1, between=0, passes=1)

Send task management commands from a port to a give target or lun.

Parameters:

management_command –
type of task management to send

BusReset (non NVMe port)

TargetReset (non NVMe port)

LogicialUnitReset (non NVMe port)

ClearTaskSet (non NVMe port)

AbortTaskSet

AbortTask

ControllerReset (NVMe port only)
initiator – initiator to send command from (-1 for all)
between – optional parameter to specify number of seconds to sleep between repeating the Task Management commands. If not specified or 0, the Task Management commands are not repeated.
passes – optional parameter used with between (if it specifies a non zero value) to indicate the number of times to repeat the Task Management command. A value of 0 indicates forever.

get_vlun_test_list(): Returns a list of tests for a given port. Includes both currently active tests and completed tests.

get_vlun_test_status(test_id): Return status and statistics for a given test_id.

get_vlun_update_firmware(firmware_file='drive_FW.bin', action=1, id=1, nvme_operation=0, bpid=False)

Send Firmware commands to a device or devices. Bit 2 of OACS (Optional Admin Command Support) if set to ‘1’, then the controller supports the Firmware Commit and Firmware Image Download commands. If cleared to ‘0’, then the controller does not support the Firmware Commit and Firmware Image Download commands.

Parameters:

port – the port’s integer value.
target – target or NVME controller id. Omit the parameter or pass -1 for all targets or NVMe controllers on the port.
firmware_file – firmware file to download to the target or NVMe controller (only needed for update and download firmware operations). To specify the file in a location other than the default of /virtualun/firmware/nvme for NVMe ports or /virtualun/firmware/scsi for SCSI ports, include the full file path for the firmware file.
action – For non NVMe ports, the action value corresponds to the mode for the firmware update. For NVME ports, the action value corresponds to the commit operation.
id – For non NVMe ports, the value corresponds to the buffer id. For NVMe ports, the value corresponds to the slot used by the commit operation.
nvme_operation –
For NVMe port, identifies the operation to execute.

Zero (0) updates firmware,

one (1) downloads the specified firmware file,

two (2) commits the firmware.
bpid – Boot Partition ID (BPID): Specifies the Boot Partition that shall be used for the Commit Action. Default as False. If specify as True then Boot Partition shall be used for the Commit Action.

get_zone_start_LBA(zone_num=0)

The get_zone_start_LBA() function returns the start LBA (the lowest LBA) of specified zone.

Parameters:: zone_num – the zone number (decimal like 0, 1, 2, …)

hPrint(msg, delimiter='\n'): Function allows overriding, to print somewhere other than stdout. Delimiter-comma weirdness is to be compatible with file-IO, which does not automatically append \n on each print. Printing tuples require special handling on argument side:

thetuple = (1, (8,9,10), 3)

self.hPrint(“this is a tuple: %s” % (thetuple))

identify(cns=0, csi=0, nsid=None, uuid_index=None)

The identify() function is a generic NVMe identify function to return identify data structure with all supported CNS and CSI values of specified in the Namespace Identifier (NSID) field if it is an active NSID.

Parameters:

cns – Controller/Namespace Structure for Identify (hex number)
csi – Command Set Identifier for Identify (hex number)
nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

identify_IO_command_set(uuid_index=None): The identify_IO_command_set() function returns 4096-byte block of data to the host which contains I/O Command Set Data Structure optional feature or command support (CNS = 1Ch).

identify_NS_attached_controller_list(uuid_index=None): The identify_NS_attached_controller_list() function returns controller list of up to 2,047 controller identifiers which contains controller identifier greater than or equal to the value specified in the Controller Identifier (CDW10.CNTID) field. The list contains controller identifiers that are attached to the namespace specified in the Namespace Identifier (NSID) field (CNS = 12h).

identify_NVM_command_set(uuid_index=None): The identify_NVM_command_set() function returns 4096-byte block of data to the host which contains data structure as an ordered list by NVM Set Identifier, starting with the first NVM Set Identifier supported by the NVM subsystem that is equal to or greater than the NVM Set Identifier indicated in CDW11.NVMSETID (CNS = 04h).

identify_ZNS_allocated_namespace(uuid_index=None): The identify_ZNS_allocated_namespace() function returns Identify Namespace data structure to the host for the namespace specified in the Namespace Identifier (NSID) field if it is an allocated NSID. If the specified namespace is an unallocated NSID then the controller returns a zero filled data structure (CNS = 1Bh, CSI = 2).

identify_ZNS_allocated_namespace_IDs(uuid_index=None): The identify_ZNS_allocated_namespace_IDs() function specifies that the device shall send a 4096-byte block of data to the host which contains a list of up to 1,024 allocated NSIDs in increasing order that are greater than 0. All valid namespace IDs are the ones whose value greater than 0 and less than or equal to Number of Namespaces (NN) reported by IdentifyController (CNS = 1Ah, CSI = 02h).

identify_ZNS_controller(uuid_index=None): The identify_ZNS_controller() function returns 4096-byte block of data to the host which contains information describes the NVM controller regarding optional feature or command support (CNS = 06h, CSI = 02h).

identify_ZNS_namespace(nsid=None, uuid_index=None)

The identify_zoned_namespace() function returns Zoned Namespaces Command Set specific Identify Namespace data structure specified in the Namespace Identifier (NSID) field if it is an active NSID (CNS = 05h, CSI = 02h).

Parameters:

nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

identify_ZNS_namespace_IDs(uuid_index=None): The identify_ZNS_namespace_IDs() function specifies that the device shall send a 4096-byte block of data to the host which contains the active namespace ID list which is a valid namespace ID that maps to a namespace. A valid namespace ID is one whose value greater than 0 and less than or equal to Number of Namespaces (NN) reported by Identify Controller (CNS = 07h, CSI = 02h).

identify_active_namespace_IDs(uuid_index=None): The identify_active_namespace_IDs() function specifies that the device shall send a 4096-byte block of data to the host which contains the active namespace ID list which is a valid namespace ID that maps to a namespace. A valid namespace ID is one whose value greater than 0 and less than or equal to Number of Namespaces (NN) reported by Identify Controller (CNS = 02h).

identify_allocated_namespace(uuid_index=None): The identify_allocated_namespace() function returns Identify Namespace data structure to the host for the namespace specified in the Namespace Identifier (NSID) field if it is an allocated NSID. If the specified namespace is an unallocated NSID then the controller returns a zero filled data structure (CNS = 11h).

identify_allocated_namespace_IDs(uuid_index=None): The identify_allocated_namespace_IDs() function specifies that the device shall send a 4096-byte block of data to the host which contains a list of up to 1,024 allocated NSIDs in increasing order that are greater than 0. All valid namespace IDs are the ones whose value greater than 0 and less than or equal to Number of Namespaces (NN) reported by IdentifyController (CNS = 10h).

identify_controller(uuid_index=None): The identify_controller() function returns 4096-byte block of data to the host which contains information describes the NVM controller regarding optional feature or command support (CNS = 01h).

identify_controller_list(uuid_index=None): The identify_controller_list() function specifies that the device shall send a 4096-byte block of data to the host which contains up to 2,047 controller identifiers containing controller identifiers greater than or equal to the value specified in the Controller Identifier (CDW10. CNTID) field. The list contains controller identifiers in the NVM subsystem that may or may not be attached to namespace(s) (CNS = 13h).

identify_namespace(nsid=None, uuid_index=None)

The identify_namespace() function specifies that the device shall send a 4096-byte block of data to the host which contains information describes about the NVM namespace regarding capacity, sector size, data protection and so on (CNS = 00h).

Parameters:

nsid – namespace ID. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

identify_namespace_ID_descripts(uuid_index=None): The identify_namespace_ID_descripts() function returns a list of Namespace Identification Descriptor structures to the host for the namespace specified in the Namespace Identifier (NSID) field if it is an active NSID (CNS = 03h).

identify_namespace_granularity_list(uuid_index=None): The identify_namespace_granularity_list() function returns Namespace Granularity List to the host for up to sixteen namespace granularity descriptors. Require the SSD controller supports reporting of Namespace Granularity (CNS = 16h).

identify_primary_controller_capabilities(uuid_index=None): The identify_primary_controller_capabilities() function returns Primary Controller Capabilities Structur to the host for the primary controller specified. Require SR-IOV is supported in SSD FW which is bit 7 of OACS for Virtualization Management supports (CNS = 14h).

identify_secondary_controller_list(uuid_index=None): The identify_secondary_controller_list() function returns to the host for up to 127 secondary controllers associated with the primary controller processing this command. The list contains entries for controller identifiers greater than or equal to the value specified in the Controller Identifier (CDW10.CNTID) field. Require SR-IOV is supported in SSD FW which is bit 7 of OACS for Virtualization Management supports (CNS = 15h).

range_compare(start_LBA=0, num_LBAs=None, data_pattern=None, transfer_size=None, lba_in_patterns=0, iotype='Compare')

Write in one range then read back to compare with I/O test which is much faster than looping with regular NVM Compare for conventional NS.

Parameters:

start_LBA – the first LBA to write and read back to compare (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs needs to compare (Recommend to put hex number like 0x100). If not specify then it will compare the whole namespace.
data_pattern –
the data pattern needs to write into the namespace for compare. If not specify then it will write random pattern. All supported data patterns are as follows:

0 - random

1 - 0x00ff00ff

2 - 0x55aa55aa

3 - 8-bit incr

4 - 8-bit walking 1,0

5 - 0x0000ffff

6 - 0x5555aaaa

7 - 16-bit incr

8 - 16-bit walking 1,0

9 - 32-bit incr

10 - Low Frequency 8B/10B

11 - Med Frequency 8B/10B

12 - High Frequency 8B/10B

13 - Jitter (CJPAT)

-1 - custom

-2 - existing data

(for the following the last two digits can be changed to indicate de-dup percentage). Examples:

-100 - random, 0% dup

-101 - random, 1% dup

-175 - random, 75% dup

-199 - random, 99% dup

-300 - random, nodup

-303 - random, dedup&compression
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got compared.
lba_in_patterns –
N[,V] Put LBA data into each block of the pattern

Where N specifies the identifying information (starting with the LBA) that will be added to the pattern for every block:

0 - No LBA data

1 - Put LBA (4 bytes) into each block of pattern

2 - Put LBA (plus other info, 16 bytes) into of each block of pattern

3 - Put LBA (plus other info, plus a timestamp, 24 bytes) into of each block of pattern

Optionally specify a second value [,V] a 64-bit / 8 byte value to be added after the resulting identifying information if [,V] is a non-zero value.
iotype – “Compare” or “Reverify”. For Reverify, data_pattern cannot be random

range_filling_with_write(start_LBA=0, num_LBAs=None, data_pattern=None, transfer_size=None, threads=1)

Write in one range with I/O test which is much faster than looping with regular NVM Write for conventional NS.

Parameters:

start_LBA – the first LBA to write to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs needs to write (Recommend to put hex number like 0x100). If not specify then it will fill the whole namespace.
data_pattern –
the data pattern needs to write into the range. If not specify then it will write random pattern. All supported data patterns are as follows:

0 - random

1 - 0x00ff00ff

2 - 0x55aa55aa

3 - 8-bit incr

4 - 8-bit walking 1,0

5 - 0x0000ffff

6 - 0x5555aaaa

7 - 16-bit incr

8 - 16-bit walking 1,0

9 - 32-bit incr

10 - Low Frequency 8B/10B

11 - Med Frequency 8B/10B

12 - High Frequency 8B/10B

13 - Jitter (CJPAT)

-1 - custom

-2 - existing data

(for the following the last two digits can be changed to indicate de-dup percentage). Examples:

-100 - random, 0% dup

-101 - random, 1% dup

-175 - random, 75% dup

-199 - random, 99% dup

-300 - random, nodup

-303 - random, dedup&compression
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

range_filling_with_writeuncorrectable(start_LBA=0, num_LBAs=None, transfer_size=None)

Write Uncorrectable in one range with I/O test which is much faster than looping with regular NVM Write Uncorrectable for conventional NS.

Parameters:

start_LBA – the first LBA to write uncorrectable to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs needs to write uncorrectable (Recommend to put hex number like 0x100). If not specify then it will fill the whole namespace.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

range_filling_with_writezeroes(start_LBA=0, num_LBAs=None, transfer_size=None)

Write Zeroes in one range with I/O test which is much faster than looping with regular NVM Write Zeroes for conventional NS.

Parameters:

start_LBA – the first LBA to write zeroes to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs needs to write zeroes (Recommend to put hex number like 0x100). If not specify then it will fill the whole namespace.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

range_read(start_LBA=0, num_LBAs=None, transfer_size=None)

Read in one range with I/O test which is much faster than looping with regular NVM Read for conventional NS.

Parameters:

start_LBA – the first LBA to read from (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs needs to read (Recommend to put hex number like 0x100). If not specify then it will read the whole namespace.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got read.

read(start_LBA=0, num_LBAs=1, save_to_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, DSM=0, ref_tag=None, app_tag=None, app_tag_mask=None)

The read() function is used to read data and metadata, if applicable, from the I/O controller for the LBAs indicated. The command may specify protection information to be checked as part of the read operation.

Parameters:

start_LBA – the first LBA to read from (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to read (Recommend to put hex number like 0x01)
save_to_fileName – File name to save the read back results to the tester in directory /virtualun/lundata/initiator/, e.g. save_to_fileName=”temp.bin”
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to return the data to the host.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Read command, the controller shall: 1) commit that data and metadata, if any, to non-volatile media; and 2) return the data, and metadata, if any, that are read from non-volatile media. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355. The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.

(DSM) (Dataset Management) –

This field indicates attributes for the LBA(s) being read.

Bits	Attribute	Definition
07	Incompressible	If set to ‘1’, then data is not compressible for the logical blocks indicated.
		If cleared to ‘0’, then no information on compression is provided.
06	Sequential Request	If set to ‘1’, then this command is part of a sequential read that
		includes multiple Read commands.
		If cleared to ‘0’, then no information on sequential access is provided.
05:04	Access Latency	Value Definition
		00b None. No latency information provided.
		01b Idle. Longer latency acceptable.
		10b Normal. Typical latency.
		11b Low. Smallest possible latency.
03:00	Access Frequency	Value Definition
		0h No frequency information provided.
		1h Typical number of reads and writes expected for this LBA range.
		2h Infrequent writes and infrequent reads to the LBA range indicated.
		3h Infrequent writes and frequent reads to the LBA range indicated.
		4h Frequent writes and infrequent reads to the LBA range indicated.
		5h Frequent writes and frequent reads to the LBA range indicated.
		6h One time read. E.g., command is due to virus scan, backup, file copy, or archive.
		7h Speculative read. The command is part of a prefetch operation.
		8h The LBA range is going to be overwritten in the near future.
		9h to Fh Reserved

ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

reservation_acquire(reservation_acquire_action=0, reservation_type=1, ignore_existing_key=0, current_reservation_key=None, preempt_reservation_key=None)

The reservation_acquire() function is used to acquire a reservation on a namespace, preempt a reservation held on a namespace, and abort a reservation held on a namespace. Bit 5 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support reservation, and Identify Namespace RESCAP (byte 31, Reservation Capabilities) as non-zero shows the namespace support reservation.

Parameters:

(RACQA) (reservation_acquire_action) –
This field specifies the action that is performed by the command.

ACQA Value

Description

000b

Acquire

001b

Preempt

010b

Preempt and Abort

011b to 111b

Reserved

(RTYPE) (reservation_type) –

This field specifies the type of reservation to be created. The field is defined as follows:

Value	Description
0h	Reserved
1h	Write Exclusive Reservation
2h	Exclusive Access Reservation
3h	Write Exclusive - Registrants Only Reservation
4h	Exclusive Access - Registrants Only Reservation
5h	Write Exclusive - All Registrants Reservation
6h	Exclusive Access - All Registrants Reservation
7h to FFh	Reserved

ignore_existing_key(IEKEY) – If this bit is set to a ‘1’, the controller shall return an error of Invalid Field In Command. If this bit is cleared to ‘0’, then the Current Reservation Key is checked.
(CRKEY) (current_reservation_key) – The field specifies the current reservation key associated with the host.
(PRKEY) (preempt_reservation_key) – If the Reservation Acquire Action field is set to 001b (i.e., Preempt) or 010b (i.e., Preempt and Abort), then this field specifies the reservation key to be unregistered from the namespace. For all other Reservation Acquire Action values, this field is reserved.

reservation_register(reservation_register_action=0, ignore_existing_key=0, current_reservation_key=None, new_reservation_key=None, change_persist_through_power_loss_state=None)

The reservation_register() function is used to register, unregister, or replace a reservation key. Bit 5 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support reservation, and Identify Namespace RESCAP (byte 31, Reservation Capabilities) as non-zero shows the namespace support reservation.

Parameters:

(RREGA) (reservation_register_action) –
This field specifies the registration action that is performed by the command.

RREGA Value

Description

000b

Register Reservation Key

001b

Unregister Reservation Key

010b

Replace Reservation Key

011b to 111b

Reserved
ignore_existing_key(IEKEY) – If this bit is set to a ‘1’, then Reservation Register Action (RREGA) field values that use the Current Reservation Key (CRKEY) shall succeed regardless of the value of the Current Reservation Key field in the command (i.e., the current reservation key is not checked).
(CRKEY) (current_reservation_key) – If the Reservation Register Action is 001b (i.e., Unregister Reservation Key) or 010b (i.e., Replace Reservation Key), then this field contains the current reservation key associated with the host. For all other Reservation Register Action values, this field is reserved. The controller ignores the value of this field when the Ignore Existing Key (IEKEY) bit is set to ‘1’.
(NRKEY) (new_reservation_key) – If the Reservation Register Action field is cleared to 000b (i.e., Register Reservation Key) or 010b (i.e., Replace Reservation Key), then this field contains the new reservation key associated with the host. For all other Reservation Register Action values, this field is reserved.

(CPTPL) (change_persist_through_power_loss_state) –

This field allows the Persist Through Power Loss (PTPL) state associated with the namespace to be modified as a side effect of processing this command. If a saveable value is supported for the Reservation Persistence Feature , then any change to the PTPL state as a result of processing this command shall be applied to both the current value and the saveable value of that feature.

CPTPL Value	Description
00b	No change to PTPL state
01b	Reserved
10b	Set PTPL state to ‘0’. Reservations are released
	and registrants are cleared on a power on.
11b	Set PTPL state to ‘1’. Reservations and
	registrants persist across a power loss

reservation_release(reservation_release_action=0, reservation_type=1, ignore_existing_key=0, current_reservation_key=None)

The reservation_release() function is used to release or clear a reservation held on a namespace. Bit 5 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support reservation, and Identify Namespace RESCAP (byte 31, Reservation Capabilities) as non-zero shows the namespace support reservation.

Parameters:

(RRELA) (reservation_release_action) –
This field specifies the release action that is performed by the command.

RRELA Value

Description

000b

Release

001b

Clear

010b to 111b

Reserved

(RTYPE) (reservation_type) –

This field specifies the type of reservation created and it is defined as follows. If the Reservation Release Action field is cleared to 000b (i.e., Release), then this field specifies the type of reservation that is being released. The reservation type in this field shall match the current reservation type. If the reservation type in this field does not match the current reservation type, then the controller should return an error of Invalid Field In Command.

Value	Description
0h	Reserved
1h	Write Exclusive Reservation
2h	Exclusive Access Reservation
3h	Write Exclusive - Registrants Only Reservation
4h	Exclusive Access - Registrants Only Reservation
5h	Write Exclusive - All Registrants Reservation
6h	Exclusive Access - All Registrants Reservation
7h to FFh	Reserved

ignore_existing_key(IEKEY) – If this bit is set to a ‘1’, the controller shall return an error of Invalid Field In Command. If this bit is cleared to ‘0’, then the Current Reservation Key is checked.
(CRKEY) (current_reservation_key) – The field specifies the current reservation key associated with the host.

reservation_report(max_num_bytes=4096)

The reservation_report() function returns a Reservation Status data structure to memory that describes the registration and reservation status of a namespace. Bit 5 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support reservation, and Identify Namespace RESCAP (byte 31, Reservation Capabilities) as non-zero shows the namespace support reservation.

Parameters:: max_num_bytes – the maximum number of bytes to return (Recommend to put hex number like 0x1000 for 4096 bytes, the API will convert to Maximum Number of Dwords in the background and minus 1 becasue it is 0’s based value, and get 0x03FF in the ASQ).

reservation_report_extended(max_num_bytes=4096)

The reservation_report_extended() function returns a Reservation Status extended data structure to memory that describes the registration and reservation status of a namespace. Bit 5 of ONCS (Optional NVM Command Support) as ‘1’ shows the controller support reservation, and Identify Namespace RESCAP (byte 31, Reservation Capabilities) as non-zero shows the namespace support reservation.

Parameters:: max_num_bytes – the maximum number of bytes to return (Recommend to put hex number like 0x1000 for 4096 bytes, the API will convert to Maximum Number of Dwords in the background and minus 1 becasue it is 0’s based value, and get 0x03FF in the ASQ).

sanitize(sanitize_action=26, overwrite_pattern=3735928559)

The sanitize(sanitize_action=0x1A, overwrite_pattern=0xdeadbeef) function is used to start a sanitize operation or to recover from a previously failed sanitize operation. The sanitize progress can be checked by dump log page 0x81.

Parameters:

sanitize_action –

Sanitize Command Dword 10 (Recommend to put hex number like 0x1A to start a block erase sanitize operation in unrestricted completion mode with 1 pass)

Bits	Description
31:10	Reserved
09	No Deallocate After Sanitize
08	Overwrite Invert Pattern Between Passes (OIPBP)
07:04	Overwrite Pass Count (OWPASS), ignore if SANACT != 011b
03	Allow Unrestricted Sanitize Exit (AUSE), AUSE=1: unrestricted completion mode
02:00	Sanitize Action (SANACT)
	000 Reserved
	001 Exit Failure Mode
	010 Start a Block Erase sanitize operation
	011 Start an Overwrite sanitize operation
	100 Start a Crypto Erase sanitize operation
	Others Reserved

overwrite_pattern – This field is ignored unless the Sanitize Action field in Command Dword 10 is set to 011b (i.e., Overwrite). This field specifies a 32-bit pattern that is used for the Overwrite sanitize operation(Recommend to put hex number like 0xdeadbeef)

sbexpress_get_all_parameters(): The sbexpress_get_all_parameters() function is used to retrieve all parameters from SBExpress.

sbexpress_get_current_from_target(system_number=1)

The sbexpress_get_current_from_target() function is used to read the current input Current in mA at the specified target slot in the SBExpress system and measured on the motherboard.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_fan_speed(fan_number=1, system_number=1)

The sbexpress_get_fan_speed() function is used to read the speed of each of the six enclosure fans inside the SBExpress. A reading under 100 indicates the fan is not spinning.

Parameters:

fan_number – Fan number between 1 and 6.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_fan_temperature(fan_number=1, system_number=1)

The sbexpress_get_fan_temperature() function is used to read the current temperature at each the six enclosure fans inside the SBExpress. Temperature is in degrees C.

Parameters:

fan_number – Fan number between 1 and 6.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_power_from_target(system_number=1)

The sbexpress_get_power_from_target() function is used to read the current input Power in mW at the specified target slot in the SBExpress system and measured on the motherboard.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_status_set_all_slots_voltage(system_number=1)

The sbexpress_get_status_set_all_slots_voltage() function is used to read the progress/status of the set_load12V command in API sbexpress_set_all_slots_voltage() above from SBExpress. The read back progress/status can be as follows:

Pass: Command has been successfully executed

Fail: Command was attempted but exited with error

Pending: Command has been acknowledged and queued to the SBExpress

Running: Command is currently running

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_voltage_from_target(system_number=1)

The sbexpress_get_voltage_from_target() function is used to read the current input Voltage in mV at the specified target slot in the SBExpress system and measured on the motherboard.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_get_voltage_of_all_slots(system_number=1)

The sbexpress_get_voltage_of_all_slots() function is used to read the current input Voltage for the SBExpress system and measured on the motherboard.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_hot_plug_button(system_number=1)

The sbexpress_hot_plug_button() function is used to press the Hot Plug Button to initiate a controlled hot swap operation on the target drive slot.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_set_PERST(PERST_state=1, system_number=1)

The sbexpress_set_PERST() function is used to hold device in PCIe reset or release reset.

Parameters:

PERST_state – PERST State. If set to 0 then means to hold device in reset which will show the controller is off. If set to 1 then means to release reset to put the controller back to ready.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_set_all_slots_voltage(voltage=12000, system_number=1)

The sbexpress_set_all_slots_voltage() function is used to set the input voltage for the SBExpress system in mV. Voltage will be set and measured on the motherboard and will affect all slots.

Parameters:

voltage – Input voltage for all slots in mV. Default as 12000 mV. The voltage margin is between 11000mv and 13800mv.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_set_power(power_state=1, system_number=1)

The sbexpress_set_power() function is used to turn the power on or off to a target slot.

Parameters:

power_state – Power State. If set to 1 then means power up. If set to 0 then means power off.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_set_present(present_state=1, system_number=1)

The sbexpress_set_present() function is used to remove or restore present signal from target device/controller.

Parameters:

present_state – Present State. If set to 0 then means to remove present signal which will show the controller not present. If set to 1 then means to restore present signal, but require button the drive with API sbexpress_hot_plug_button() call before normal operation.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

sbexpress_toggle_PERST(system_number=1)

The sbexpress_toggle_PERST() function is used to toggle the PERST signal to the device for ~100mS, force hard PCIe reset to target drive/controller.

Parameters:: system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

set_feature(feature_id, page_control, feature_data, data_buffer=None, feature_data_length=None, nsid=None, uuid_index=None)

The set_feature() function is used to set any feature specified by feature_id (enter as hex number like 0x0E for time stamp feature 0x0E) and selected value of the attributes specified by page_control. This function call will not save the attribute so that the attribute will not persist through all power states and resets.

Parameters:

feature_id – Feature ID to set.
page_control – Feature select. 0 - current, 1 - default, 2 - saved, 3 - supported
feature_data – The data to be sent in Command Dword 11, such as APSTE for feature 0Ch (feature_data=1). It corresponds to the -d option of the io program.
data_buffer – the data buffer to be sent with the command (please enter as hex number like 0x10). It corresponds to the -data option of the io program.
feature_data_length – Number of bytes of the feature data (please enter as hex number like 0x1000 for 4096 bytes), most cases you don’t have to specify and it will use the default length.
nsid – namespace ID. Most NVMe features only support changing by controller, not by LUN. If need to set feature for specific LUN and you can specify with nsid. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

set_feature_save(feature_id, page_control, feature_data, data_buffer=None, feature_data_length=None, nsid=None, uuid_index=None)

The set_feature_save() function is used to set any feature specified by feature_id (enter as hex number like 0x0E for time stamp feature 0x0E) and selected value of the attributes specified by page_control. This function call will save the attribute so that the attribute will persist through all power states and resets. Bit 4 of ONCS (Optional NVM Command Support) if set to ‘1’, then the controller supports the Save field set to a non-zero value in the Set Features command and the Select field set to a non-zero value in the Get Features command. If cleared to ‘0’, then the controller does not support the Save field set to a non-zero value in the Set Features command and the Select field set to a nonzero value in the Get Features command.

Parameters:

feature_id – Feature ID to set.
page_control – Feature select. 0 - current, 1 - default, 2 - saved, 3 - supported
feature_data – The data to be sent in Command Dword 11, such as APSTE for feature 0Ch (feature_data=1). It corresponds to the -d option of the io program.
data_buffer – the data buffer to be sent with the command (please enter as hex number like 0x10). It corresponds to the -data option of the io program.
feature_data_length – Number of bytes of the feature data (please enter as hex number like 0x1000 for 4096 bytes), most cases you don’t have to specify and it will use the default length.
nsid – namespace ID. Most NVMe features only support changing by controller, not by LUN. If need to set feature for specific LUN and you can specify with nsid. It is decimal number, so don’t enter as hex number like 0x10. Only use -1 to mean 0xFFFFFFFF.
uuid_index

set_proc_vlun_config(**kwargs)

The set_proc_vlun_config function is used to set all parameters in proc file /proc/vlun/config.

Parameters:: kwargs – any parameters name and value in proc file /proc/vlun/config. For example “TestJobLimit=1”, or “DebugLevel=1, TestJobLimit=1”. If changed TestJobLimit value then it will take effect for the next start I/O test, and won’t affect current running I/O test.

set_proc_vlun_nvme(**kwargs)

The set_proc_vlun_nvme function is used to set all parameters in proc file /proc/vlun/nvme.

Parameters:: kwargs – any parameters name and value in proc file /proc/vlun/nvme. For example “nvme_vlun_affinity=1”, or “nvme_vlun_reset_retries=3, nvme_vlun_affinity=1”. If changed nvme_vlun_affinity value then it will take effect after controller reset although the changes will show up in proc file /proc/vlun/nvme.

show_field_values(t, buf, same_line=False, reverse=True, output_struct=None): Show each field of a structure, right justified, and its current value

test_manager_add_test_to_device(script_name='NVMe_Generic/NVMe_Flush.sh', index_number=-1, number_passes=1, seconds_per_pass=0, system_number=1, system_type=1)

The test_manager_add_test_to_device() function is used to add a test specified by script_name to a device in test manager.

Parameters:

script_name – Script file name, for example NVMe_Generic/NVMe_Flush.sh. They are under directory /virtualun/rest/scripts/
index_number – The order the tests will run if sequenced. Tests given the same index will run at the same time. It is any number >= 1. If set to -1 then means “next available, auto assign”
number_passes – Number of passes. If set to 1 then it means “once”.
seconds_per_pass – Time to run each pass. If set to 0 = “default set by script”
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.
system_type – System type, if set to 1 then it means for SBExpress (default and output as JSON format). If set to 2 then it will output HTML/XML format to be compatible with Jenkins.

test_manager_appy_action_to_all_tests_for_device(action='start', system_number=1)

The test_manager_appy_action_to_all_tests_for_device() function is used to apply test action (start/stop/pause/unpause/clear/delete) to all tests for a device in test manager. You can verify the success of this API results by browsing to the SBExpress web page. The page will reflect the status change without refreshing, but the change can take up to 20 seconds to be reflected on the page. You will see all selected tests to start/stop/pause/unpause/clear/delete. If action is “start” then selected tests will start in sequence order, lowest first. Tests with the same sequence number will run together.

Parameters:

action – The available test actions like “start”, “stop”, “pause”, “unpause”, “clear” or “delete”. Default is “start”.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

test_manager_appy_action_to_test_for_device(index_number, action='start', system_number=1)

The test_manager_appy_action_to_test_for_device() function is used to apply test action (start/stop/pause/unpause/clear/delete) to a test specified by index number for a device in test manager. You can verify the success of this API results by browsing to the SBExpress web page. The page will reflect the status change without refreshing, but the change can take up to 20 seconds to be reflected on the page. You will see the selected test to start/stop/pause/unpause/clear/delete. The selected test will run first, followed by all other selected tests in sequence order. To run a single test alone, unselect all tests, select the target test, issue start to the test. The same applies to all other actions like stop/pause/unpause/clear/delete.

Parameters:

index_number – The order the tests will run if sequenced. It is the test index number when user added the test with API test_manager_add_test_to_device() above.
action – The available test actions like “start”, “stop”, “pause”, “unpause”, “clear” or “delete”. Default is “start”.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

test_manager_generate_test_report_from_device(index_number='all', system_number=1)

The test_manager_generate_test_report_from_device() function is used to generate a test report of a selected test specified by index number or all selected tests from a device in test manager.

Parameters:

index_number – The order the tests will run if sequenced. It is the test index number when user added the test with API test_manager_add_test_to_device() above. Default value is set to “all” and it will generate a test report of all selected tests from the device. If set to one specific test index number and it is selected then it will generate the test report for this selected test.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

test_manager_get_saved_test_reports_list(): The test_manager_get_saved_test_reports_list() function is used to get list of saved test reports.

test_manager_get_saved_test_suites(test_suite_index='all')

The test_manager_get_saved_test_suites() function is used to get a list of saved test suites or specific test suite specified with test_suite_index.

Parameters:: test_suite_index – Test Suite index number. The default value is “all” which means to list all saved/available test suites. If put a number >= 1 then list the detailed information of the specific test suite.

test_manager_get_test_state_from_device(index_number, system_number=1)

The test_manager_get_test_state_from_device() function is used to check the current test state of a test specified by index number from a device in test manager.

Parameters:

index_number – The order the tests will run if sequenced. It is the test index number when user added the test with API test_manager_add_test_to_device() above.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

test_manager_select_unselect_all_tests_for_device(select=1, system_number=1)

The test_manager_select_unselect_all_tests_for_device() function is used to select or unselect all tests for a device in test manager. You can verify the success of this API results by browsing to the SBExpress web page. The page will reflect the change without refreshing, but the change can take up to 20 seconds to be reflected on the page. You will see the check boxes set or clear for all the tests to select/unselect.

Parameters:

select – Select or unselect. If set to 1 then select all tests, if set to 0 then unselect all tests.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

test_manager_select_unselect_test_for_device(index_number, select=1, system_number=1)

The test_manager_select_unselect_test_for_device() function is used to select or unselect a test specified by index number for a device in test manager. You can verify the success of this API results by browsing to the SBExpress web page. The page will reflect the change without refreshing, but the change can take up to 20 seconds to be reflected on the page. You will see the check box set or clear for the test to select/unselect.

Parameters:

index_number – The order the tests will run if sequenced. It is the test index number when user added the test with API test_manager_add_test_to_device() above.
select – Select or unselect. If set to 1 then select the test, if set to 0 then unselect the test.
system_number – System number, see number before “:” on system tab in the SBExpress GUI page. It should be indexed from 1 and max at 8. Default is 1 and it means just one tester.

verify(start_LBA=0, num_LBAs=1, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, ref_tag=None, app_tag=None, app_tag_mask=None)

The verify() function verifies integrity of stored information by reading data and metadata, if applicable, for the LBAs indicated without transferring any data or metadata to the host. A Verify operation consists of the controller actions (e.g., reading) that verify integrity of stored information during execution of a Verify command. The command may specify protection information to be checked as part of the Verify operation. Not all SSD supports Verify function. Only if the bit 7 of ONCS (Optional NVM Command Support) set to ‘1’, then the controller supports the Verify command. If cleared to ‘0’, then the controller does not support the Verify command.

Parameters:

start_LBA – the first LBA to verify (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to verify (Recommend to put hex number like 0x01)
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means before completing the command with failure.
force_unit_access – If set to ‘1’, then the controller shall flush any data and metadata specified by the Verify command from any volatile cache before performing the Verify operation and shall perform the Verify operation on data and metadata that have been committed to nonvolatile media. There is no implied ordering with other commands. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355.

The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
ref_tag (This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use) – end-to-end protection information.
app_tag (This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection) – information.
app_tag_mask (This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end) – protection information.

virtualization_management(controller_id, resource_type, action, num_controller_resource)

The virtualization_management() function is used to modify Flexible Resource allocation for the primary controller, assign Flexible Resources for secondary controllers, and set the Online and Offline state for secondary controllers. It requires the bit 7 of OACS is 1 which means it supports virtualization management.

Parameters:

controller_id – The controller for which controller resources are to be modified. You can find controller_id (CNTLID) from Identify commands. If primary controller then get CNTLID from identify command with CNS=01h or CNS=14h. If secondary controller then get CNTLID from identify command with CNS=15h. Please enter as hex number like 0x41.
resource_type – The type of controller resource to be modified. 0 means VQ Resources, and 1 means VI Resources.

action –

The operation for the command to perform. Please enter as hex number.

Value	Description
0h	Reserved
1h	Primary Controller Flexible Allocation
2h to 6h	Reserved
7h	Secondary Controller Offline
8h	Secondary Controller Assign
9h	Secondary Controller Online
Ah to Fh	Reserved

num_controller_resource – The number of controller resources to allocate or assign. Please enter as hex number.

write(nsid=1, start_LBA=0, num_LBAs=1, data_pattern=165, pattern_from_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, directive_type=0, directive_specific=0, DSM=0, ref_tag=None, app_tag=None, app_tag_mask=None)

The write() function is used to write data and metadata, if applicable, to the I/O controller for the logical blocks indicated. The host may also specify protection information to include as part of the operation.

Parameters:

start_LBA – the first LBA to write to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to write (Recommend to put hex number like 0x01)
data_pattern – data pattern ([numbytes] byte of data) used for write.
pattern_from_fileName – Data pattern file name to read from the tester in directory /virtualun/lundata/initiator/ and it is used for writing, e.g. pattern_from_fileName=”temp.bin”. It has higher priority than input argument data_pattern.
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to return the data to the host.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Write command, the controller shall write that data and metadata, if any, to non-volatile media before indicating command completion. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355.

The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
directive_type – Specifies the Directive Type associated with the Directive Specific field.
directive_specific – Specifies the Directive Specific value associated with the Directive.

(DSM) (Dataset Management) –

This field indicates attributes for the LBA(s) being read.

Bits	Attribute	Definition
07	Incompressible	If set to ‘1’, then data is not compressible for the logical blocks indicated.
		If cleared to ‘0’, then no information on compression is provided.
06	Sequential Request	If set to ‘1’, then this command is part of a sequential read that
		includes multiple Read commands.
		If cleared to ‘0’, then no information on sequential access is provided.
05:04	Access Latency	Value Definition
		00b None. No latency information provided.
		01b Idle. Longer latency acceptable.
		10b Normal. Typical latency.
		11b Low. Smallest possible latency.
03:00	Access Frequency	Value Definition
		0h No frequency information provided.
		1h Typical number of reads and writes expected for this LBA range.
		2h Infrequent writes and infrequent reads to the LBA range indicated.
		3h Infrequent writes and frequent reads to the LBA range indicated.
		4h Frequent writes and infrequent reads to the LBA range indicated.
		5h Frequent writes and frequent reads to the LBA range indicated.
		6h One time read. E.g., command is due to virus scan, backup, file copy, or archive.
		7h Speculative read. The command is part of a prefetch operation.
		8h The LBA range is going to be overwritten in the near future.
		9h to Fh Reserved

ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

write_uncorrectable(start_LBA=0, num_LBAs=1)

The write_uncorrectable() function is used to mark a range of logical blocks as invalid. When the specified logical block(s) are read after this operation, a failure is returned with Unrecovered Read Error status. To clear the invalid logical block status, a write operation is performed on those logical blocks. Bit 1 of ONCS (Optional NVM Command Support) if set to ‘1’, then the controller supports the Write Uncorrectable command. If cleared to ‘0’, then the controller does not support the Write Uncorrectable command.

Parameters:

start_LBA – the first LBA to write to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to write (Recommend to put hex number like 0x01)

write_zeros(start_LBA=0, num_LBAs=1, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, deallocate=0, ref_tag=None, app_tag=None, app_tag_mask=None)

The write_zeros() function is used to set a range of logical blocks to zero. Bit 3 of ONCS (Optional NVM Command Support) if set to ‘1’, then the controller supports the Write Zeroes command. If cleared to ‘0’, then the controller does not support the Write Zeroes command.

Parameters:

start_LBA – the first LBA to write to (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to write (Recommend to put hex number like 0x01)
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to write the data to the NVM.
force_unit_access – If set to ‘1’, then the controller shall write the data, and metadata, if any, to non-volatile media before indicating command completion. There is no implied ordering with other commands. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355.

The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
deallocate – If set to ‘1’, then the host is requesting that the controller deallocate the specified logical blocks. If cleared to ‘0’, then the host is not requesting that the controller deallocate the specified logical blocks.
ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

zone_append(start_LBA=0, num_LBAs=1, data_pattern=165, pattern_from_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, protection_info_remap=0, ref_tag=None, app_tag=None, app_tag_mask=None)

The zone_append() function is used to write data and metadata. Data placement inside the zone is done by the controller so that the data is contiguously placed from the zone start LBA of the zone to the end of the writable capacity of the zone.

Parameters:

start_LBA – the first LBA for zone append (Recommend to put hex number like 0x00)
num_LBAs – the number of LBAs to zone append (Recommend to put hex number like 0x01)
data_pattern – data pattern ([numbytes] byte of data) used for zone append
pattern_from_fileName – Data pattern file name to read from the tester in directory /virtualun/lundata/initiator/ and it is used for zone append, e.g. pattern_from_fileName=”temp.bin”. It has higher priority than input argument data_pattern.
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to return the data to the host.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Zone Append command, the controller shall write that data and metadata, if any, non-volatile media before indicating command completion. There is no implied ordering with other commands. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355.

The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
protection_info_remap – If this bit is set to ‘1’ then the reference tag in the Protection Information is remapped by the controller as described in section 4.4.2. If this bit is cleared to ‘0’, then no remapping of the reference tag is performed by the controller. For Type 1 protection, the controller shall abort the command with a status of Invalid Protection Information if this bit is cleared to ‘0’. For Type 3 protection, the controller shall abort the command with a status of Invalid Protection Information if this bit is set to ‘1’.
ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

zone_append_for_zone(zone_num=0, num_LBAs=1, data_pattern=165, pattern_from_fileName=None, block_size=None, limited_retry=0, force_unit_access=0, protection_info=None, protection_info_remap=0, ref_tag=None, app_tag=None, app_tag_mask=None)

The zone_append_for_zone() function is used to write data and metadata. Data placement inside the zone is done by the controller so that the data is contiguously placed from the zone write pointer of the specified zone to the end of the writable capacity of the zone.

Parameters:

zone_num – the zone number (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs to zone append (Recommend to put hex number like 0x01)
data_pattern – data pattern ([numbytes] byte of data) used for zone append
pattern_from_fileName – Data pattern file name to read from the tester in directory /virtualun/lundata/initiator/ and it is used for one append, e.g. pattern_from_fileName=”temp.bin”. It has higher priority than input argument data_pattern.
block_size – In general user does not have to specify and it will use the namespace formated block size by default, e.g. block_size=None. If need to specify please enter hex number like 0x1000 which is 4096, 0x200 which is 512.
limited_retry – If set to ‘1’, the controller should apply limited retry efforts. If cleared to ‘0’, the controller should apply all available error recovery means to return the data to the host.
force_unit_access – If set to ‘1’, then for data and metadata, if any, associated with logical blocks specified by the Zone Append command, the controller shall write that data and metadata, if any, non-volatile media before indicating command completion. There is no implied ordering with other commands. If cleared to ‘0’, then this bit has no effect.
protection_info –
Specifies the protection information action and check field, as defined in Figure 355.

The Protection Information Check (PRCHK) field shall be cleared to 000b.

Protection Information Action (PRACT): The protection information action bit indicates the action to take for the protection information. This bit is only used if the namespace is formatted to use end-to-end protection information.

Protection Information Check (PRCHK): The protection information check field specifies the fields that shall be checked as part of end-to-end data protection processing. This field is only used if the namespace is formatted to use end-to-end protection information.
protection_info_remap – If this bit is set to ‘1’ then the reference tag in the Protection Information is remapped by the controller as described in section 4.4.2. If this bit is cleared to ‘0’, then no remapping of the reference tag is performed by the controller. For Type 1 protection, the controller shall abort the command with a status of Invalid Protection Information if this bit is cleared to ‘0’. For Type 3 protection, the controller shall abort the command with a status of Invalid Protection Information if this bit is set to ‘1’.
ref_tag – This field indicates the Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag – This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
app_tag_mask – This field indicates the Application Tag Mask value. This field is only used if the namespace is formatted to use end-to-end protection information.

zone_compare(zone_num=0, num_LBAs=None, data_pattern=None, transfer_size=None)

Write in one zone then read back to compare with I/O test which is much faster than looping with regular NVM Compare.

Parameters:

zone_num – the zone number needs to compare (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to compare (Recommend to put hex number like 0x100). If not specify then it will compare the whole zone.
data_pattern –
the data pattern needs to write into the zone for compare. If not specify then it will write random pattern. All supported data patterns are as follows:

0 - random

1 - 0x00ff00ff

2 - 0x55aa55aa

3 - 8-bit incr

4 - 8-bit walking 1,0

5 - 0x0000ffff

6 - 0x5555aaaa

7 - 16-bit incr

8 - 16-bit walking 1,0

9 - 32-bit incr

10 - Low Frequency 8B/10B

11 - Med Frequency 8B/10B

12 - High Frequency 8B/10B

13 - Jitter (CJPAT)

-1 - custom

-2 - existing data

(for the following the last two digits can be changed to indicate de-dup percentage). Examples:

-100 - random, 0% dup

-101 - random, 1% dup

-175 - random, 75% dup

-199 - random, 99% dup

-300 - random, nodup

-303 - random, dedup&compression
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got compared.

zone_filling_with_append(zone_num=0, num_LBAs=None, data_pattern=None, transfer_size=None)

Append in one zone with I/O test which is much faster than looping with regular zone append.

Parameters:

zone_num – the zone number needs to append to (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to append (Recommend to put hex number like 0x100). If not specify then it will fill the whole zone.
data_pattern –
the data pattern needs to append into the zone. If not specify then it will append random pattern. All supported data patterns are as follows:

0 - random

1 - 0x00ff00ff

2 - 0x55aa55aa

3 - 8-bit incr

4 - 8-bit walking 1,0

5 - 0x0000ffff

6 - 0x5555aaaa

7 - 16-bit incr

8 - 16-bit walking 1,0

9 - 32-bit incr

10 - Low Frequency 8B/10B

11 - Med Frequency 8B/10B

12 - High Frequency 8B/10B

13 - Jitter (CJPAT)

-1 - custom

-2 - existing data

(for the following the last two digits can be changed to indicate de-dup percentage). Examples:

-100 - random, 0% dup

-101 - random, 1% dup

-175 - random, 75% dup

-199 - random, 99% dup

-300 - random, nodup

-303 - random, dedup&compression
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

zone_filling_with_write(zone_num=0, num_LBAs=None, data_pattern=None, transfer_size=None)

Write in one zone with I/O test which is much faster than looping with regular NVM Write.

Parameters:

zone_num – the zone number needs to write to (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to write (Recommend to put hex number like 0x100). If not specify then it will fill the whole zone.
data_pattern –
the data pattern needs to write into the zone. If not specify then it will write random pattern. All supported data patterns are as follows:

0 - random

1 - 0x00ff00ff

2 - 0x55aa55aa

3 - 8-bit incr

4 - 8-bit walking 1,0

5 - 0x0000ffff

6 - 0x5555aaaa

7 - 16-bit incr

8 - 16-bit walking 1,0

9 - 32-bit incr

10 - Low Frequency 8B/10B

11 - Med Frequency 8B/10B

12 - High Frequency 8B/10B

13 - Jitter (CJPAT)

-1 - custom

-2 - existing data

(for the following the last two digits can be changed to indicate de-dup percentage). Examples:

-100 - random, 0% dup

-101 - random, 1% dup

-175 - random, 75% dup

-199 - random, 99% dup

-300 - random, nodup

-303 - random, dedup&compression
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

zone_filling_with_writeuncorrectable(zone_num=0, num_LBAs=None, transfer_size=None)

Write Uncorrectable in one zone with I/O test which is much faster than looping with regular NVM Write Uncorrectable.

Parameters:

zone_num – the zone number needs to write uncorrectable to (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to write uncorrectable (Recommend to put hex number like 0x100). If not specify then it will fill the whole zone.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

zone_filling_with_writezeroes(zone_num=0, num_LBAs=None, transfer_size=None)

Write Zeroes in one zone with I/O test which is much faster than looping with regular NVM Write Zeroes.

Parameters:

zone_num – the zone number needs to write zeroes to (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to write zeroes (Recommend to put hex number like 0x100). If not specify then it will fill the whole zone.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got filled.

zone_management_receive(start_LBA=0, return_bytes=4096, receive_action=0)

The zone_management_receive() function returns a data buffer that describes information about zones.

Parameters:

start_LBA – the location of a data buffer where data is transferred from (Recommend to put hex number like 0x00)
return_bytes – number of bytes return (Recommend to put hex number like 0x1000 which is 4096 bytes)

receive_action –

zone receive action specific features (Recommend to put hex number like 0x100 to list all ZSE zones)

Bits	Description
31:17	Reserved
16	Zone Receive Action Specific Features:
	1h Return the Number of Zones field in the Report Zones data structure and in the Extended Report
	Zone data structure indicates the number of fully transferred zone descriptors in the data buffer.
	0h Return the Number of Zones field in the Report Zones data structure and Extended Report Zone
	data structure indicates the number of zone descriptors that match the criteria in the Zone
	Receive Action Specific field.
15:08	Zone Receive Action Specific Field:
	0h List all zones.
	1h List the zones in the ZSE: Empty state.
	2h List the zones in the ZSIO: Implicitly Opened state.
	3h List the zones in the ZSEO: Explicitly Opened state.
	4h List the zones in the ZSC: Closed state.
	5h List the zones in the ZSF: Full state.
	6h List the zones in the ZSRO: Read Only state.
	7h List the zones in the ZSO: Offline state.
	8h-FFh Reserved
07:00	Zone Receive Action (ZRA):
	00h Report Zones: Reports zone descriptor entries through the Report Zones data structure.
	01h Extended Report Zones: Reports zone descriptor entries through the Extended Report Zones
	data structure. This value is supported if the namespace is formatted with a non-zero Zone
	Description Extension Size. Otherwise, the command shall be aborted with a status code of
	Invalid Field in Command.
	02h-FFh: Reserved

zone_management_receive_for_zone(zone_num=0, receive_action=0)

The zone_management_receive_for_zone() function returns a data buffer that describes information about a specified zone.

Parameters:

zone_num – the zone number (decimal like 0, 1, 2, …)

receive_action –

zone receive action specific features (Recommend to put hex number like 0x100 to list all ZSE zones)

Bits	Description
31:17	Reserved
16	Zone Receive Action Specific Features:
	1h Return the Number of Zones field in the Report Zones data structure and in the Extended Report
	Zone data structure indicates the number of fully transferred zone descriptors in the data buffer.
	0h Return the Number of Zones field in the Report Zones data structure and Extended Report Zone
	data structure indicates the number of zone descriptors that match the criteria in the Zone
	Receive Action Specific field.
15:08	Zone Receive Action Specific Field:
	0h List all zones.
	1h List the zones in the ZSE: Empty state.
	2h List the zones in the ZSIO: Implicitly Opened state.
	3h List the zones in the ZSEO: Explicitly Opened state.
	4h List the zones in the ZSC: Closed state.
	5h List the zones in the ZSF: Full state.
	6h List the zones in the ZSRO: Read Only state.
	7h List the zones in the ZSO: Offline state.
	8h-FFh Reserved
07:00	Zone Receive Action (ZRA):
	00h Report Zones: Reports zone descriptor entries through the Report Zones data structure.
	01h Extended Report Zones: Reports zone descriptor entries through the Extended Report Zones
	data structure. This value is supported if the namespace is formatted with a non-zero Zone
	Description Extension Size. Otherwise, the command shall be aborted with a status code of
	Invalid Field in Command.
	02h-FFh: Reserved

zone_management_send(start_LBA=0, send_action=3, buffer_length=0, buffer_file=None, ZRWAA=0)

The zone_management_send() function performs an action on one or more zones.

Parameters:

start_LBA – the lowest LBA of the zone the command operates on (Recommend to put hex number like 0x00)

send_action –

zone send action (Recommend to put hex number like 0x104 to reset all zones)

Bits	Description
09	Zone Random Write Area Allocation (ZRWAA): Controls the allocation of Zone Random Write Areas
	to zones. If the Zone Send Action (ZSA) field specifies Open Zone and no ZRWA
	is currently associated with this zone:
	1 If a ZRWA resource is available, then a ZRWA shall be allocated to this zone upon transitioning
	to the ZSEO:Explicitly Opened state if the zone is in the ZSE: Empty state; or the write pointer
	is on a Zone Random Write Area Commit Granularity boundary and the zone is in the
	ZSIO: Implicitly Opened state.
	0 No ZRWA shall be allocated to this zone upon transitioning to the ZSEO: Explicitly Opened state.
08	Select All:
	If the bit is cleared to ‘0’, then the start_LBA field specifies the lowest logical block of the zone.
	If the bit is set to ‘1’, then the SLBA field shall be ignored.
07:00	00h Reserved
	01h Close Zone: Close one or more zones.
	02h Finish Zone: Finish one or more zones.
	03h Open Zone: Open one or more zones.
	04h Reset Zone: Reset one or more zones.
	05h Offline Zone: Offline one or more zones.
	06h-0Fh Reserved
	10h Set Zone Descriptor Extension: Attach Zone Descriptor Extension data to a zone in the
	ZSE: Empty state and transition the zone to the ZSC:Closed state.
	11h to FFh Reserved

buffer_length – the buffer length will be sent (Recommend to put hex number like 0x80 for 128 bytes)
buffer_file – the buffer file name and path. Please make sure the buffer_file size is the same as buffer_length above. If not specify the path then please put the file in the default directory “/virtualun/lundata/initiator/” on the tester
ZRWAA – Zone Random Write Area Allocation, bit 9 of send_action above and can only be set as 1 or clear to 0 (default value). Create as a separate input argument for user’s convenience

zone_management_send_for_zone(zone_num=0, send_action=3, buffer_length=0, buffer_file=None, ZRWAA=0)

The zone_management_send_for_zone() function performs an action on a specified zone.

Parameters:

zone_num – the zone number (decimal like 0, 1, 2, …)

send_action –

zone send action (Recommend to put hex number like 0x104 to reset all zones)

Bits	Description
09	Zone Random Write Area Allocation (ZRWAA): Controls the allocation of Zone Random Write Areas
	to zones. If the Zone Send Action (ZSA) field specifies Open Zone and no ZRWA
	is currently associated with this zone:
	1 If a ZRWA resource is available, then a ZRWA shall be allocated to this zone upon transitioning
	to the ZSEO:Explicitly Opened state if the zone is in the ZSE: Empty state; or the write pointer
	is on a Zone Random Write Area Commit Granularity boundary and the zone is in the
	ZSIO: Implicitly Opened state.
	0 No ZRWA shall be allocated to this zone upon transitioning to the ZSEO: Explicitly Opened state.
08	Select All:
	If the bit is cleared to ‘0’, then the start_LBA field specifies the lowest logical block of the zone.
	If the bit is set to ‘1’, then the SLBA field shall be ignored.
07:00	00h Reserved
	01h Close Zone: Close one or more zones.
	02h Finish Zone: Finish one or more zones.
	03h Open Zone: Open one or more zones.
	04h Reset Zone: Reset one or more zones.
	05h Offline Zone: Offline one or more zones.
	06h-0Fh Reserved
	10h Set Zone Descriptor Extension: Attach Zone Descriptor Extension data to a zone in the
	ZSE: Empty state and transition the zone to the ZSC:Closed state.
	11h Commit ZRWA: Commit logical blocks from a ZRWA to a zone.
	12h to FFh Reserved

buffer_length – the buffer length will be sent (Recommend to put hex number like 0x80 for 128 bytes)
buffer_file – the buffer file name and path. Please make sure the buffer_file size is the same as buffer_length above. If not specify the path then please put the file in the default directory “/virtualun/lundata/initiator/” on the tester
ZRWAA – Zone Random Write Area Allocation, bit 9 of send_action above and can only be set as 1 or clear to 0 (default value). Create as a separate input argument for user’s convenience

zone_read(zone_num=0, num_LBAs=None, transfer_size=None)

Read in one zone with I/O test which is much faster than looping with regular NVM Read.

Parameters:

zone_num – the zone number needs to read from (decimal like 0, 1, 2, …)
num_LBAs – the number of LBAs needs to read (Recommend to put hex number like 0x100). If not specify then it will read from the whole zone.
transfer_size – the number of LBAs per transfer. If not specified it will pick up the max transfer size supported by the controller and dividable by the num_LBAs, which will ensure all num_LBAs got read.