mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-01 03:45:29 +00:00
0bd384d41b
While we hoped to make the headings consistent over time while doing other edits, we should instead just make the squirrels happy and do them all at once or they'll likely never be made consistent. A python script was used to find the headings, and then a call to https://pypi.org/project/titlecase to transform the title. A visual inspection was used to tweak a few unexpected resulting titles. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
227 lines
8.1 KiB
ReStructuredText
227 lines
8.1 KiB
ReStructuredText
.. _GVT-g_api:
|
|
|
|
ACRN GVT-g APIs
|
|
###############
|
|
|
|
GVT-g is Intel's open source GPU virtualization solution and is up-streamed to
|
|
the Linux kernel. Its implementation over KVM is named KVMGT, over Xen it is
|
|
named XenGT, and over ACRN it is named AcrnGT. GVT-g can exports multiple
|
|
virtual GPU (vGPU) instances for virtual machine system (VM). A VM could be
|
|
assigned one vGPU instance. The guest OS graphic driver needs minor
|
|
modification to drive the vGPU adapter in a VM. Every vGPU instance will adopt
|
|
the full HW GPU's accelerate capability for 3D render and display.
|
|
|
|
In the following document, AcrnGT refers to the glue layer between ACRN
|
|
hypervisor and GVT-g core device model. It works as the agent of
|
|
hypervisor-related services. It is the only layer that needs to get rewritten
|
|
when porting GVT-g to another hypervisor. For simplicity, in the rest of this
|
|
document, GVT is used to refer to the core device model component of GVT-g,
|
|
specifically corresponding to ``gvt.ko`` when built as a module.
|
|
|
|
Core Driver Infrastructure
|
|
**************************
|
|
|
|
This section covers core driver infrastructure API used by both the display
|
|
and the `Graphics Execution Manager(GEM)`_ parts of `i915 driver`_.
|
|
|
|
.. _Graphics Execution Manager(GEM): https://lwn.net/Articles/283798/
|
|
|
|
.. _i915 driver: https://01.org/linuxgraphics/gfx-docs/drm/gpu/i915.html
|
|
|
|
Intel GVT-g Guest Support (vGPU)
|
|
================================
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
|
|
:doc: Intel GVT-g guest support
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
|
|
:internal:
|
|
|
|
Intel GVT-g Host Support (vGPU Device Model)
|
|
============================================
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
|
|
:doc: Intel GVT-g host support
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
|
|
:internal:
|
|
|
|
|
|
VHM APIs Called From AcrnGT
|
|
****************************
|
|
|
|
The Virtio and Hypervisor Service Module (VHM) is a kernel module in the
|
|
Service OS acting as a middle layer to support the device model. (See the
|
|
:ref:`ACRN-io-mediator` introduction for details.)
|
|
|
|
VHM requires an interrupt (vIRQ) number, and exposes some APIs to external
|
|
kernel modules such as GVT-g and the Virtio back-end (BE) service running in
|
|
kernel space. VHM exposes a ``char`` device node in user space, and only
|
|
interacts with DM. The DM routes I/O request and response from and to other
|
|
modules via the ``char`` device to and from VHM. DM may use VHM for hypervisor
|
|
service (including remote memory map). VHM may directly service the request
|
|
such as for the remote memory map, or invoke hypercall. VHM also sends I/O
|
|
responses to user space modules, notified by vIRQ injections.
|
|
|
|
|
|
.. kernel-doc:: include/linux/vhm/vhm_vm_mngt.h
|
|
:functions: put_vm
|
|
vhm_get_vm_info
|
|
vhm_inject_msi
|
|
vhm_vm_gpa2hpa
|
|
|
|
.. kernel-doc:: include/linux/vhm/acrn_vhm_ioreq.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: include/linux/vhm/acrn_vhm_mm.h
|
|
:functions: acrn_hpa2gpa
|
|
map_guest_phys
|
|
unmap_guest_phys
|
|
add_memory_region
|
|
del_memory_region
|
|
write_protect_page
|
|
|
|
.. _MPT_interface:
|
|
|
|
AcrnGT Mediated Passthrough (MPT) Interface
|
|
*******************************************
|
|
|
|
AcrnGT receives request from GVT module through MPT interface. Refer to the
|
|
:ref:`Graphic_mediation` page.
|
|
|
|
A collection of function callbacks in the MPT module will be attached to GVT
|
|
host at the driver loading stage. AcrnGT MPT function callbacks are described
|
|
as below:
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
struct intel_gvt_mpt acrn_gvt_mpt = {
|
|
.host_init = acrngt_host_init,
|
|
.host_exit = acrngt_host_exit,
|
|
.attach_vgpu = acrngt_attach_vgpu,
|
|
.detach_vgpu = acrngt_detach_vgpu,
|
|
.inject_msi = acrngt_inject_msi,
|
|
.from_virt_to_mfn = acrngt_virt_to_mfn,
|
|
.enable_page_track = acrngt_page_track_add,
|
|
.disable_page_track = acrngt_page_track_remove,
|
|
.read_gpa = acrngt_read_gpa,
|
|
.write_gpa = acrngt_write_gpa,
|
|
.gfn_to_mfn = acrngt_gfn_to_pfn,
|
|
.map_gfn_to_mfn = acrngt_map_gfn_to_mfn,
|
|
.dma_map_guest_page = acrngt_dma_map_guest_page,
|
|
.dma_unmap_guest_page = acrngt_dma_unmap_guest_page,
|
|
.set_trap_area = acrngt_set_trap_area,
|
|
.set_pvmmio = acrngt_set_pvmmio,
|
|
.dom0_ready = acrngt_dom0_ready,
|
|
|
|
};
|
|
EXPORT_SYMBOL_GPL(acrn_gvt_mpt);
|
|
|
|
GVT-g core logic will call these APIs through wrap functions with prefix
|
|
``intel_gvt_hypervisor_`` to request specific services from hypervisor through
|
|
VHM.
|
|
|
|
This section describes the wrap functions:
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/gvt/mpt.h
|
|
:functions: intel_gvt_hypervisor_host_init
|
|
intel_gvt_hypervisor_host_exit
|
|
intel_gvt_hypervisor_attach_vgpu
|
|
intel_gvt_hypervisor_detach_vgpu
|
|
intel_gvt_hypervisor_inject_msi
|
|
intel_gvt_hypervisor_virt_to_mfn
|
|
intel_gvt_hypervisor_enable_page_track
|
|
intel_gvt_hypervisor_disable_page_track
|
|
intel_gvt_hypervisor_read_gpa
|
|
intel_gvt_hypervisor_write_gpa
|
|
intel_gvt_hypervisor_gfn_to_mfn
|
|
intel_gvt_hypervisor_map_gfn_to_mfn
|
|
intel_gvt_hypervisor_dma_map_guest_page
|
|
intel_gvt_hypervisor_dma_unmap_guest_page
|
|
intel_gvt_hypervisor_set_trap_area
|
|
intel_gvt_hypervisor_set_pvmmio
|
|
intel_gvt_hypervisor_dom0_ready
|
|
|
|
.. _intel_gvt_ops_interface:
|
|
|
|
GVT-g Intel_gvt_ops Interface
|
|
*****************************
|
|
|
|
This section contains APIs for GVT-g intel_gvt_ops interface. Sources are found
|
|
in the `ACRN kernel GitHub repo`_
|
|
|
|
|
|
.. _ACRN kernel GitHub repo: https://github.com/projectacrn/acrn-kernel/
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
static const struct intel_gvt_ops intel_gvt_ops = {
|
|
.emulate_cfg_read = intel_vgpu_emulate_cfg_read,
|
|
.emulate_cfg_write = intel_vgpu_emulate_cfg_write,
|
|
.emulate_mmio_read = intel_vgpu_emulate_mmio_read,
|
|
.emulate_mmio_write = intel_vgpu_emulate_mmio_write,
|
|
.vgpu_create = intel_gvt_create_vgpu,
|
|
.vgpu_destroy = intel_gvt_destroy_vgpu,
|
|
.vgpu_reset = intel_gvt_reset_vgpu,
|
|
.vgpu_activate = intel_gvt_activate_vgpu,
|
|
.vgpu_deactivate = intel_gvt_deactivate_vgpu,
|
|
};
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/gvt/cfg_space.c
|
|
:functions: intel_vgpu_emulate_cfg_read
|
|
intel_vgpu_emulate_cfg_write
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio.c
|
|
:functions: intel_vgpu_emulate_mmio_read
|
|
intel_vgpu_emulate_mmio_write
|
|
|
|
.. kernel-doc:: drivers/gpu/drm/i915/gvt/vgpu.c
|
|
:functions: intel_gvt_create_vgpn
|
|
intel_gvt_destroy_vgpu
|
|
intel_gvt_reset_vgpu
|
|
intel_gvt_activate_vgpu
|
|
intel_gvt_deactivate_vgpu
|
|
|
|
.. _sysfs_interface:
|
|
|
|
AcrnGT Sysfs Interface
|
|
***********************
|
|
|
|
This section contains APIs for the AcrnGT sysfs interface. Sources are found
|
|
in the `ACRN kernel GitHub repo`_
|
|
|
|
|
|
Sysfs Nodes
|
|
===========
|
|
|
|
In the following examples, all accesses to these interfaces are via bash command
|
|
``echo`` or ``cat``. This is a quick and easy way to get or control things. But
|
|
when these operations fail, it is impossible to get respective error code by
|
|
this way.
|
|
|
|
When accessing sysfs entries, use library functions such as
|
|
``read()`` or ``write()`` instead.
|
|
|
|
On **success**, the returned value of ``read()`` or ``write()`` indicates how
|
|
many bytes have been transferred. On **error**, the returned value is ``-1``
|
|
and the global ``errno`` will be set appropriately. This is the only way to
|
|
figure out what kind of error occurs.
|
|
|
|
|
|
- The ``/sys/kernel/gvt/`` class sub-directory belongs to AcrnGT and provides a
|
|
centralized sysfs interface for configuring vGPU properties.
|
|
|
|
- The ``/sys/kernel/gvt/control/`` sub-directory contains all the necessary
|
|
switches for different purposes.
|
|
|
|
- The ``/sys/kernel/gvt/control/create_gvt_instance`` node is used by ACRN-DM to
|
|
create/destroy a vGPU instance.
|
|
|
|
- After a VM is created, a new sub-directory ``/sys/kernel/GVT/vmN`` ("N" is the VM id) will be
|
|
created.
|
|
|
|
- The ``/sys/kernel/gvt/vmN/vgpu_id`` node is to get vGPU id from VM which id is
|
|
N.
|