WindowsGuestDrivers/viostor/documentation

STORPORT miniport driver for VIRTIO based SCSI controller

Scope

VirtIO miniport driver works together with the Storport driver. Storport miniport driver is a vendor-supplied driver used to access hardware. The following document describes VirtIO Storport miniport driver design goals and implementation. Detailed description of VirtIO itself is out of the scope and will not be covered in this document.

Code tour

File	Description
virtio_store.c	Main source module for the miniport.
virtio_store.h	Main include file for the miniport.
virtio_store.rc	Resource definitions.
virtio_store_utils.c	Source file for print to COM port routine.
virtio_store_utils.h	Include file containing debugging and debugging print related definitions.
virtio_store_hw_helper.c	Source file containing some "HW" related routines.
virtio_store_hw_helper.h	Include file containing definitions for some "HW" related routines.
osdep.h	Include OS dependent definitions.
VirtIO.h	Include file containing VirtIO queue related definitions.
virtio_pci.c	Source file for VirtIO PCI device routines.
virtio_pci.h	Include file for VirtIO PCI device.
virtio_ring.c	Source file for VirtIO ring routines.
virtio_ring.h	Include file for VirtIO ring definitions.
txtsetup.oem	Windows Server 2003 text-mode setup file.
wlh.inf	Windows Server 2008 INF file.
wnet.inf	Windows Server 2003 INF file.

Main Declarations and Data Structures

VirtIO block device configuration descriptor

typedef struct virtio_blk_config {

   u64 capacity;                      /* The capacity (in 512-byte sectors). */
   u32 size_max;                      /* The maximum segment size (if VIRTIO_BLK_F_SIZE_MAX) */
   u32 seg_max;                       /* The maximum number of segments (if VIRTIO_BLK_F_SEG_MAX) */
   struct virtio_blk_geometry {       /* geometry the device (if VIRTIO_BLK_F_GEOMETRY) */
       u16 cylinders;
       u8 heads;
       u8 sectors;
   } geometry;
   u32 blk_size;                      /* block size of device (if VIRTIO_BLK_F_BLK_SIZE) */

}blk_config, *pblk_config;

Miniport driver's per-HBA extension

typedef struct _ADAPTER_EXTENSION {

   ULONG_PTR             device_base; /* device base address */
   virtio_pci_vq_info    pci_vq_info; /* pci virtual queue information block*/
   vring_virtqueue*      virtqueue;   /* virtual queue pointer*/
   INQUIRYDATA           inquiry_data;/* inquiry data block */
   blk_config            info;        /* block device configutation block */
   ULONG                 breaks_number;/* number of phisical breaks to adjust the PORT_CONFIGURATION_INFORMATION */
   ULONG                 transfer_size;/* maximum transfer size to adjust the PORT_CONFIGURATION_INFORMATION */
   ULONG                 queue_depth; /* maximum depth of the device queue */
   BOOLEAN               dump_mode;   /* runningin crash-dump mode*/

}ADAPTER_EXTENSION, *PADAPTER_EXTENSION;

VirtIO request header

typedef struct virtio_blk_outhdr {

   u32 type;                          /* VIRTIO_BLK_T* */
   u32 ioprio;                        /* io priority. Always 0*/
   u64 sector;                        /* Sector (ie. 512 byte offset) */

}blk_outhdr, *pblk_outhdr;

VirtIO request descriptor

typedef struct virtio_blk_req {

   struct list_head list;             /* currently not in use*/
   struct request *req;               /* pointer to SRB*/
   blk_outhdr out_hdr;                /* runningin crash-dump mode*/
   u8     status;                     /* request completion status */
   VIO_SG sg[VIRTIO_MAX_SG];          /* buffer that holdes scatter-gather list*/

}blk_req, *pblk_req;

Miniport driver's per-SRB extension

typedef struct _RHEL_SRB_EXTENSION {

   blk_req               vbr;         /* request descriptor block */
   ULONG                 out;         /* number of OUT elements */
   ULONG                 in;          /* number of IN elements */

}RHEL_SRB_EXTENSION, *PRHEL_SRB_EXTENSION;

Functions

VirtIO Storport miniport driver routines

VirtIoFindAdapter

The VirtIoFindAdapter routine uses the supplied configuration to determine whether a VirtIO HBA is supported and, if it is, to return configuration information about that adapter

ULONG VirtIoFindAdapter(

   IN PVOID DeviceExtension,
   IN PVOID HwContext,
   IN PVOID BusInformation,
   IN PCHAR ArgumentString,
   IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo,
   OUT PBOOLEAN Again
   );

VirtIoHwInitialize

The VirtIoHwInitialize routine initializes the miniport driver after system reboot or power failure occurs. It is called by StorPort after VirtIoFindAdapter successfully returns. VirtIoHwInitialize initializes the VirtIO HBA.

BOOLEAN VirtIoHwInitialize(

   IN PVOID DeviceExtension
   );

VirtIoBuildIo

The VirtIoBuildIo routine processes the SRB with unsynchronized access to shared system data structures before passing it to VirtIoStartIo.

BOOLEAN VirtIoBuildIo(

   IN PVOID DeviceExtension,
   IN PSCSI_REQUEST_BLOCK Srb
   );

VirtIoStartIo

The Storport driver calls the VirtIoStartIo routine one time for each incoming I/O request.

BOOLEAN VirtIoStartIo(

   IN PVOID DeviceExtension,
   IN PSCSI_REQUEST_BLOCK Srb
   );

VirtIoInterrupt

The Storport driver calls the VirtIoInterrupt routine after the VirtIO HBA generates an interrupt request.

BOOLEAN VirtIoInterrupt(

   IN PVOID DeviceExtension
   );

VirtIoResetBus

The VirtIoResetBus routine is called by the port driver to clear error conditions.

BOOLEAN VirtIoResetBus(

   IN PVOID DeviceExtension,
   IN ULONG PathId
   );

VirtIoAdapterControl

The VirtIoAdapterControl routine is called to perform synchronous operations to control the state or behavior of an adapter, such as stopping or restarting the VirtIO HBA for power management.

SCSI_ADAPTER_CONTROL_STATUS VirtIoAdapterControl(

   IN PVOID DeviceExtension,
   IN SCSI_ADAPTER_CONTROL_TYPE ControlType,
   IN PVOID Parameters
   );

How to build

Run the appropriated WDK build environment. Go to the viostor project directory and run "build –cegZ" command.

Useful information

Find everything you need here: Storport Miniport Drivers

VirtIO block for XP

An old style, SCSIPort driver, can be created by building the code in XP environment. However, due to the lack of resources SCSIPort driver has never been fully tested and currently is unsupported.