Description

This API is intended to be used by client drivers to access the VirtIO device and provide the functionality expected of a driver of the given class.

Functions cyg_vio_avail() and cyg_vio_queue_ready() test the state of the queue. The first returns the number of buffer descriptors available for transfer; it can be used to check that there is enough resource to start a transfer before submitting it. The second is used to check that a queue has completed initialization.

The function cyg_vio_submit() submits a transfer to the VirtIO device. All fields in the transfer should be initialized before submission. If the transfer is successfully queued, this function returns CYG_VIO_DONE. If the submission fails, a non-zero error code is returned.

The function cyg_vio_poll() polls a given driver for completed transfers. If a transfer is complete, then its callback function is called. Calling this poll routine is the only way in which transfer completions are recognized. It is the responsibility of the client driver to arrange to call it. This may be done from a thread context if that exists, or may be done from a DSR if the device interrupt has been enabled. When a callback is called, the only fields in the transfer that will have been updated are the head and actual fields; so the transfer may be immediately resubmitted to the driver from the callback with no changes if the same transfer is to be repeated.

The function cyg_vio_driver_init() is called to initialize the common parts of a VirtIO driver. This function will perform startup negotiation with the hypervisor device and initialize all valid queues. On return, the driver will be ready for submission of transfers. If this function is called for a driver that has already been initialized, it will return immediately, so it may be called from multiple locations safely.

The function hal_vio_init() is not supplied by the VirtIO package but is expected to be defined by the variant or platform HAL. The VirtIO package calls this function from a constructor during initialization. This function is responsible for detecting any VirtIO devices, installing base address and interrupt vector values and calling cyg_vio_driver_init() for each. Detection may involve searching a memory area for valid VirtIO devices or scanning a PCI bus. If the VirtIO devices are at known fixed addresses then this function should just call cyg_vio_driver_init() for each device to be initialized.