API core
- class API(controller, port=0, display=False, nvme_version=None, remote_address=None)
- create_io_completion_queue(qid, qsize=1023, iv=None, ien=None, pc=1)
Issue the Create I/O Completion Queue NVMe Admin Command
- Parameters:
qid (int) – The identifier to assign to the completion queue to be created
qsize (int) – Size of the completion queue to be created. 0’s based value.
iv (int) – Transport specific value described in the applicable NVMe Transport binding specification.
ien (int) – 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 (int) –
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.
If this bit is cleared to ‘0’ and CAP.CQR is set to ‘1’, then the controller should return an error of Invalid Field in Command.
- create_io_submission_queue(qid, cqid, qsize=1023, pc=1, qprio=None, nvmsetid=None)
Issue the Create I/O Submission Queue NVMe Admin Command
- Parameters:
qid (int) – The identifier to assign to the submission queue to be created
cqid (int) – This field indicates the identifier of the I/O Completion Queue to utilize for any command completions entries associated with this Submission Queue.
qsize (int) – Size of the completion queue to be created. 0’s based value.
pc (int) – 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.
qprio (int) – This field indicates the priority class to use for commands within this Submission Queue.
nvmsetid (int) – This field indicates the identifier of the NVM Set to be associated with this Submission Queue.
- dataset_management(nsid, nr=0, ad=None, idw=None, idr=None, data=None)
Execute the Dataset Management NVM Command Set Command
- Parameters:
nsid (int) – Namespace Identifier
nr (int) – Number of Ranges. 0 based.
ad (int) – Attribute - Deallocate. 0 or 1.
idw (int) – Attribute - Integral Dataset for Write. 0 or 1.
idr (int) – Attribute - Integral Dataset for Read. 0 or 1.
data (int) – The data to be sent in the memory buffer for the command.
- delete_io_completion_queue(qid)
Issue a Delete I/O Completion Queue NVMe Admin Command
- Parameters:
qid (int) – This field indicates the identifier of the Completion Queue to be deleted.
- delete_io_submission_queue(qid)
Issue a Delete I/O Submission Queue NVMe Admin Command
- Parameters:
qid (int) – This field indicates the identifier of the Submission Queue to be deleted.
- directive_receive(nsid, dtype, doper=None)
Execute the directive receive command.
- Parameters:
nsid (int) – Namespace Identifier
dtype (int) – Directive Type (DTYPE) 00h: Identify directive. 01h: Streams directive.
doper (int) – Directive Operation (DOPER) The interpretation of this field is Directive Type dependent. Identify (00h): 01h (Return Parameters). Streams (01h): 01h (Return Parameters), 02h (Get Status) and 03h (Allocate Resources).
dspec (int) – Directive Specific (DSPEC) The interpretation of this field is Directive Type dependent. Identify (00h): this field is not used. Streams (01h): specifies the Stream Identifier, the identifier of the stream associated with the data.
- directive_send(nsid, dtype, doper=None, endir=None, directive=None, dspec=None)
Execute the directive send command.
- Parameters:
nsid (int) – Namespace Identifier
dtype (int) – Directive Type (DTYPE) 00h: Identify directive. 01h: Streams directive.
doper (int) – Directive Operation (DOPER) The interpretation of this field is Directive Type dependent. Identify (00h): 01h (Enable Directive). Streams (01h): 01h (Release Identifier) and 02h (Release Resources).
endir (int) – 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.
directive (int) – Directive Type (DTYPE) 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.
dspec (int) – Directive Specific (DSPEC) The interpretation of this field is Directive Type dependent. Identify (00h): this field is not used. Streams (01h): specifies the Stream Identifier, the identifier of the stream associated with the data.
- firmware_commit(ca, fs=None, bpid=None)
Execute the Firmware Commit NVMe Admin Command.
- Parameters:
ca (int) –
- Commit Action
000b: Replace, do not activate. 001b: Replace, activate at controller reset. 010b: Activate existing at controller reset. 011b: Replace if applicable, activate immediately. 110b: Replace Boot Partition specified by BPID. 111b: Mark Boot Partition as active. Update BPINFO.ABPID.
fs (int) – Firmware Slot. If 0h, controller shall choose.
bpid (int) – Boot Partition ID
- firmware_image_download(file, numd=None, ofst=None)
Execute the Firmware Image Download NVMe Admin Command.
- Parameters:
file (str) – The path of the firmware file to be downloaded.
numd (int) – Number of Dwords to be transferred.
ofst (int) – Number of Dwords offset from the start of the image.
- format_nvm(nsid, lbaf=None, ses=None, pil=None, pi=None, mset=None, timeout=None)
Execute the Format NVM NVMe Admin Command.
- Parameters:
nsid (int) – Namespace Identifier. Decimal or 0xFFFFFFFF.
lbaf (int) – The LBA format to apply to the NVM media.
ses (int) –
- Secure Erase Settings
000b: No secure erase operation 001b: User Data Erase 010b: Cryptographic Erase
pil (int) –
- Protection Information Location
0b: Last 8 bytes of metadata 1b: First 8 bytes of metadata
pi (int) –
- Protection Information
000b: Not Enabled 001b: Enabled, Type 1 010b: Enabled, Type 2 011b: Enabled, Type 3
mset (int) –
- Metadata Settings
0b: Transfer as part of separate buffer. 1b: Transfer as part of extended data LBA.
- get_features(fid, sel=0, nsid=None, uuidx=None, cdw11=None)
Execute the NVMe Get Features command
- Parameters:
fid (int) – Feature Identifier. Hexadecimal.
sel (int) –
- Select
000b: Current 001b: Default 010b: Saved 011b: Supported Capabilities
nsid (int) – Namespace Identifier
uuidx (int) – UUID Index
cdw11 (int) – Feature specific Command Dword 11. Hexadecimal.
- get_log_page(lid, csi=0, nsid=None, lsp=None, lsid=None, rae=None, lpo=None, ot=None, uuidx=None, numdl=None, numdu=None, legacy=False, silent=False)
Execute the Get Log Page admin command with the given fields.
- Parameters:
lid (int) – Log Page Identifier. Hexadecimal.
csi (int) – Command Set Identifier. Hexadecimal.
nsid (int) – Namespace Identifier. Decimal.
lsp (int) – Log Specific Field
lsid (int) – Log Specific Identifier
rae (int) – Retain Asynchronous Event. 0 or 1
lpo (int) – Log Page Offset. 8 bytes. Combines LPOU and LPOL.
ot (int) – Offset Type. 0 for byte offset, 1 for index
uuidx (int) – UUID Index
numdl (int) – Number of Dwords Lower. Decimal. Combined with NUMDU to form a 0’s based number.
numdu (int) – Number of Dwords Upper. Decimal. Combined with NUMDL to form a 0’s based number.
legacy (bool) – Legacy Mode. If set to True, data will be returned as an XML_API dict. If false, data will be returned as a regular formatted dict.
silent (bool) – Print and log the passing command. If set to True, passing command will not be printed and logged. If false, the passing command will be printed and logged as usual.
- identify(cns, nsid=None, cntid=None, csi=None, cnssid=None, uuidx=None)
Issue the Identify command with the given fields
- Parameters:
cns (int) – Controller or Namespace Structure
nsid (int) – Namespace Identifier
cntid (int) – Controller Identifier
csi (int) – Command Set Identifier
cnssid (int) – CNS Specific Identifier
uuidx (int) – UUID Index
- io_management_receive(nsid, operation, specific=None)
Execute the I/O management receive command.
- Parameters:
nsid (int) – Namespace Identifier
operation (int) – Management Operation (MO) Reclaim Unit Handle Status (01h): The Reclaim Unit Handle Status management operation is used to provide information about Reclaim Unit Handles (refer to section 1.5.75) that are accessible by the specified namespace.
specific (Hexadecimal) – Management Operation Specific (MOS) The definition of this field is specific to the value of the MO field.
- io_management_send(nsid, operation, specific=None, data=None)
Execute the I/O management send command.
- Parameters:
nsid (int) – Namespace Identifier
operation (int) – Management Operation (MO) Reclaim Unit Handle Update (01h): The Reclaim Unit Handle Update management operation for the I/O Management Send command provides a list of Placement Identifiers. The reference to the Reclaim Unit specified by each Placement Identifier shall be modified to reference a different Reclaim Unit if the currently referenced Reclaim Unit has been written with user data (i.e., the referenced Reclaim Unit is empty (refer to section 3.2.4)).
specific (Hexadecimal) – Management Operation Specific (MOS) The definition of this field is specific to the value of the MO field. Reclaim Unit Handle Update (01h): Number of Placement Identifiers (NPID): Indicates the number of Placement Identifiers that are specified in the command. This is a 0s based value.
data (int) – The data to be sent in the memory buffer for the command. Reclaim Unit Handle Update (01h): Placement Identifier List: The reference to the Reclaim Unit specified by each Placement Identifier shall be modified to reference a different Reclaim Unit if the currently referenced Reclaim Unit has been written with user data.
- namespace_attachment(command, nsid)
Issues the NVM Namespace Management Admin Command with the specified fields.
The Namespace Attachment command is used to attach and detach controllers from a namespace.
- Parameters:
command (string) – This field selects the type of attachment to perform. The valid parameters for this field are ‘attach’ and ‘detach’.
nsid (int) – Namespace Identifier
- namespace_management(command, nsid=None, num=1, csi=0, size='1gb', lbaf=0, private=False, attach=True, anagrpid=None, nvmsetid=None, endgid=None, handles=None, handle_start=None, handle_incr=None, handle_list=None)
Issues the NVM Namespace Management Admin Command with the specified fields.
The Namespace Management command is used to manage namespaces, including create and delete operations.
- Parameters:
command (string) – This field selects the type of management operation to perform. The valid parameters for this field are ‘create’ and ‘delete’.
nsid (int) – Namespace Identifier. Create: The NSID field is reserved for this operation; host software clears this field to a value of 0h. The controller shall select an available Namespace Identifier to use for the operation. Delete: This field specifies a previously created namespace to delete in this operation. Specifying a value of -1 is used to delete all namespaces in the NVM subsystem.
num (int) – The number of namespaces to create. This field is unused for the delete operation.
csi (int) – For a create operation, this field specifies the I/O Command Set for the created namespace. A CSI value of 0h creates a namespace using the NVM Command Set. For all other operations this field is reserved.
size (string) – Namespace Size. Indicates the size of each namespace to create. 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
output. (lbaf = Format of Namespace. Used for creating Namespace and can find from identify namespace)
private (bool) – This field indicates whether the created namespace(s) will be private or not. If set to True, all namespaces created by the namespace management command will be private, and vice versa if set to False.
attach (bool) – This field indicates whether the created namespace(s) will be attached or not. If set to True, all namespaces created by the namespace management command will be atatched, and vice versa if set to False.
anagrpid (hexadecimal) – ANA Group Identifier. For NSID other than FFFFFFFh, this field indicates the ANA Group Identifier of the ANA group of which the namespace(s) created is a member. If set to 0h, the controller will determine the ANAGRPID to assign to the namespace.
nvmsetid (hexadecimal) – NVM Set Identifier. For NSID other than FFFFFFFFh, this field indicates the NVM Set with which this namespace is associated. If set to 0h, the controller will determine the NVM Set Identifier to assign to the namespace.
endgid (hexadecimal or int) – Endurance Group Identifier. For NSID other than FFFFFFFFh, this field indicates the Endurance Group with which this namespace is associated. If set to 0h, the controller will determine the Endurance Group Identifier to assign to the namespace.
handles (int) – Number of Placement Handles (NPHNDLS). This field specifies the number of Placement Handles included in the Placement Handle List.
handle_start (int) – Handle Start (nvme-ns-mgmt parameter).
handle_incr (int) – Handle Increment (nvme-ns-mgmt parameter).
handle_list (list) – Handle List (nvme-ns-mgmt parameter) This field specifies a list of Placement Handles to pass as the Placement Handle List. Can be used as an alternative to handles, handle_start, and handle_incr parameters. Use one or the other to specify a Placement Handle List, but not both.
- raw(fields=None)
Context manager to specify fields to be parsed as raw inegers.
In the NVMe specification many fields are defined as having subfields, such as Status Field (SF) in the Common Completion Queue Entry. Using this context manager prevents specified fields from being divided into subfields during parsing.
- Parameters:
fields (str or list of str) – The field(s) to be parsed as inetegers
- read(nsid, slba=0, nlb=1, lr=0, fua=0, prinfo=None, stc=None, dsm=None, elbst=None, eilbrt=None, elbatm=None, elbat=None)
Execute the NVM Command Set Read command with the given fields
The Read command reads data and metadata, if applicable, from the I/O controller for the LBAs indicated.
- Parameters:
nsid (int) – Namespace Identifier
slba (Hexadecimal) – Starting LBA. The address of the first logical block to be written to.
nlb (Hexadecimal) – Number of Logical Blocks. The number of logical blocks to be written. This is a 0’s based value.
lr (int) – 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.
fua (int) – Forced 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 commit that data and metadata, if any, to non-volatile media; and return the data, and metadata, if any, that are read from non-volatile media. If cleared to ‘0’, then this bit has no effect.
prinfo (Hexadecimal) – Protection Information. Specifies the protection information and action check field.
stc (int) – Storage Tag Check. This bit specifies the Storage Tag field shall be checked as part of end-to-end data protection processing as defined in Figure 12 (see NVMe 2.0 Base spec)
dsm (Hexadecimal) – Dataset Management. This field indicates attributes for the LBA(s) being read.
elbst (Hexadecimal) – Expected Logical Block Storage Tag. This field indicates the Expected Logical Block Storage Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
eilbrt (Hexadecimal) – Expected Initial Logical Block Reference Tag. This field indicates the Expected Initial Logical Block Reference Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
elbatm (Hexadecimal) – Expected Logical Block Application Tag Mask. This field indicates the Application Tag expected value. This field is only used if the namespace is formatted to use end-to-end protection information.
elbat (Hexadecimal) – Expected Logical Block Application Tag. This field indicates the Application Tag Mask expected value. This field is only used if the namespace is formatted to use end-to-end protection information.
- set_features(fid, sv=0, nsid=None, uuidx=None, cdw11=None, cdw12=None, cdw13=None, cdw15=None, data=None, override_data_length=None)
Execute the Set Features admin command.
- Parameters:
fid (int) – Feature Identifier. The feature to set. Hexadecimal.
sv (int) – Save. Whether to save the set attribute. 0 or 1.
nsid (int) – Namespace Identifier. The NSID to set the feature for. Decimal or 0xFFFFFFFF.
uuidx (int) – UUID Index
cdw11 (int) – Feature specific Command Dword 11. Hexadecimal.
cdw12 (int) – Feature specific Command Dword 12. Hexadecimal.
cdw13 (int) – Feature specific Command Dword 13. Hexadecimal.
cdw15 (int) – Feature specific Command Dword 15. Hexadecimal.
data (int) – The data to be sent in the memory buffer. Hexadecimal.
- txlen(num_bytes)
Context manager to specify a custom data size during commands.
- Parameters:
num_bytes (int) – The length of the data in bytes to be sent or requested.
- write(nsid, data=165, slba=0, nlb=0, lr=0, fua=0, prinfo=None, stc=None, dtype=None, dspec=None, dsm=None, lbst=None, ilbrt=None, lbatm=None, lbat=None, legacy=False, **kwargs)
Executes the NVM Command Set Write command with the given fields.
The Write command 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:
nsid (int) – Namespace Identifier
data (Hexadecimal) – The data pattern to be written to the I/O controller for the logical blocks indicated.
slba (Hexadecimal) – Starting LBA. The address of the first logical block to be written to.
nlb (Hexadecimal) – Number of Logical Blocks. The number of logical blocks to be written. This is a 0’s based number.
lr (int) – 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.
fua (int) – Forced 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.
prinfo (Hexadecimal) – Protection Information. Specifies the protection information and action check field.
stc (int) – Storage Tag Check (STC). This bit specifies the Storage Tag field shall be checked as part of end-to-end data protection processing as defined in Figure 12 (see NVMe 2.0 Base spec)
dtype (int) – Directive Type. Specifies the Directive Type associated with the Directive Specific field.
dspec (int) – Directive Specific. Specifies the Directive Specific value associated with the Directive.
dsm (Hexadecimal) – Dataset Management. This field indicates attributes for the LBA(s) being read.
lbst (Hexadecimal) – Logical Block Storage Tag. This field indicates the Logical Block Storage Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
ilbrt (Hexadecimal) – Initial Logical Block Reference 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.
lbatm (Hexadecimal) – Logical Block Application Tag Mask. This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
lbat (Hexadecimal) – Logical Block Application Tag. 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.
legacy (bool) – Legacy Mode. If set to True, data will be returned as an XML_API dict. If false, data will be returned as a regular formatted dict.
- write_uncorrectable(nsid, slba=0, nlb=0, dtype=None, dspec=None, legacy=False, **kwargs)
Executes the NVM Command Set Write Uncorrectable command with the given fields.
The Write Uncorrectable command 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.
- Parameters:
nsid (int) – Namespace Identifier
slba (Hexadecimal) – Starting LBA. The address of the first logical block to be written to.
nlb (Hexadecimal) – Number of Logical Blocks. The number of logical blocks to be written.
dtype (int) – Directive Type. Specifies the Directive Type associated with the Directive Specific field.
dspec (int) – Directive Specific. Specifies the Directive Specific value associated with the Directive.
legacy (bool) – Legacy Mode. If set to True, data will be returned as an XML_API dict. If false, data will be returned as a regular formatted dict.
- write_zeroes(nsid, slba=0, nlb=0, lr=0, fua=0, deac=0, prinfo=None, dtype=None, dspec=None, lbst=None, ilbrt=None, lbatm=None, lbat=None, legacy=False, **kwargs)
Executes the NVM Command Set Write Zeroes command with the given fields.
The Write Zeroes command is used to set a range of logical blocks to zero.
- Parameters:
nsid (int) – Namespace Identifier
slba (Hexadecimal) – Starting LBA. The address of the first logical block to be written to.
nlb (Hexadecimal) – Number of Logical Blocks. The number of logical blocks to be written. This is a 0’s based number.
lr (int) – 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.
fua (int) – Forced 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.
prinfo (Hexadecimal) – Protection Information. Specifies the protection information and action check field.
deac (int) – Deallocate. If set to ‘1’, request 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.
dtype (int) – Directive Type. Specifies the Directive Type associated with the Directive Specific field.
dspec (int) – Directive Specific. Specifies the Directive Specific value associated with the Directive.
lbst (Hexadecimal) – Logical Block Storage Tag. This field indicates the Logical Block Storage Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
ilbrt (Hexadecimal) – Initial Logical Block Reference 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.
lbatm (Hexadecimal) – Logical Block Application Tag Mask. This field indicates the Application Tag value. This field is only used if the namespace is formatted to use end-to-end protection information.
lbat (Hexadecimal) – Logical Block Application Tag. 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.
legacy (bool) – Legacy Mode. If set to True, data will be returned as an XML_API dict. If false, data will be returned as a regular formatted dict.