NVMe Driver and IOCTLs#

The default for xNVMe is to communicate with devices via the operating system NVMe driver IOCTLs, specifically on Windows the following are used:

  • IOCTL_STORAGE_QUERY_PROPERTY

  • IOCTL_STORAGE_SET_PROPERTY

  • IOCTL_STORAGE_REINITIALIZE_MEDIA

  • IOCTL_SCSI_PASS_THROUGH_DIRECT

You can check that this interface is behaving as expected by running:

xnvme.exe info \\.\PhysicalDrive0

Which should yield output equivalent to:

xnvme_dev:
  xnvme_ident:
    uri: '\\.\PhysicalDrive0'
    dtype: 0x2
    nsid: 0x1
    csi: 0x0
    subnqn: 'nqn.1994-11.com.samsung:nvme:980M.2:S649NL0T973010L     '
  xnvme_be:
    admin: {id: 'nvme'}
    sync: {id: 'nvme'}
    async: {id: 'iocp'}
    attr: {name: 'windows'}

This tells you that xNVMe can communicate with the given device identifier and it informs you that it utilizes nvme_ioctl for synchronous command execution and it uses iocp for asynchronous command execution. This method can be used for raw devices via \.PhysicalDrive<disk number> device path.

Below mentioned commands are currently supported by xNVMe using IOCTL path:

  • Admin Commands

    • Get Log Page

    • Identify

    • Get Feature

    • Format NVM

  • I/O Commands

    • Read

    • Write

Note on Errors#

Some commands may be issued through ioctl that are invalid. While most commands will still be issued to the drive and the error relayed back to the user, some violations may be picked up by the kernel cause the ioctl to fail with -1 and GetLastError() set to Invalid Argument.

In this case, the backend will transform such errors into the NVMe equivalent. See the documentation on xnvme_cmd_ctx.

On this page