gpu

Overview ¶

Package gpu is a pure-Go virtio-gpu (2D framebuffer) driver. It drives a modern (Virtio 1.0+) PCI virtio-gpu device through the transport interfaces defined in github.com/go-virtio/common; the same code drives a UEFI-backed device, a bare-metal device, or a virtio-mmio device depending on which common.Transport implementation the caller supplies.

Scope — two paths. The 2D framebuffer path (OpenVirtioGPU) negotiates exactly VIRTIO_F_VERSION_1 and drives the device in plain 2D mode (Virtio 1.1 §5.7). The 3D path (OpenVirtioGPU3D + ClearScreen, in gpu3d.go) additionally negotiates VIRTIO_GPU_F_VIRGL (bit 0) and offloads a host-GPU scanout clear to virglrenderer via a hand-encoded virgl command stream — still pure Go, CGO=0. What remains out of scope is a FULL OpenGL/Vulkan implementation in Go (the Mesa-class GL→TGSI stack needed to generate arbitrary command streams from an application API); the 3D path hand-authors only the fixed command streams it needs.

The driver owns device bring-up, the control virtqueue (controlq), the cursor virtqueue (cursorq, set up but unused), and the on-the-wire virtio-gpu control protocol (every command is a 2-descriptor chain: a read-only request followed by a device-writable response). It exposes a scanout-enumeration + framebuffer API:

• DisplayInfo lists the device's scanouts (GET_DISPLAY_INFO).
• SetupFramebuffer creates a host resource, attaches guest backing, and binds it to a scanout (RESOURCE_CREATE_2D + RESOURCE_ATTACH_BACKING + SET_SCANOUT). The returned Framebuffer's Pix is a BGRA byte buffer the caller draws into.
• Framebuffer.Flush pushes the drawn pixels to the host and refreshes the scanout (TRANSFER_TO_HOST_2D + RESOURCE_FLUSH).

References:

• Virtio 1.1 §5.7 "GPU Device" — device-type 16 binding.
• Virtio 1.1 §5.7.4 "Device configuration layout" — virtio_gpu_config.
• Virtio 1.1 §5.7.6 "Device Operation" — control + cursor queues, struct virtio_gpu_ctrl_hdr and the 2D command structs.
• Virtio 1.1 §3.1.1 "Device Initialization".

3D / virgl extension of the virtio-gpu driver (Milestone 1). This file is purely additive: it does NOT touch the 2D OpenVirtioGPU / SetupFramebuffer / Flush / DisplayInfo path. It adds a second constructor, OpenVirtioGPU3D, that negotiates VIRTIO_GPU_F_VIRGL in addition to VERSION_1, and a single high-level operation, ClearScreen, that clears a scanout to a solid colour using the HOST GPU via virglrenderer.

M1 scope is deliberately tiny: stand up a virgl context, create a 3D render-target resource, submit a 3-command virgl buffer (CREATE SURFACE + SET_FRAMEBUFFER_STATE + CLEAR), pull the result back into the guest backing, and bind+flush it to a scanout. No Mesa is needed because the virgl command buffer for a flat clear is short enough to hand-encode.

References:

• Linux uapi linux/virtio_gpu.h — the 3D control structs and command codes (VIRTIO_GPU_CMD_*_3D, VIRTIO_GPU_F_VIRGL).
• virgl_protocol.h — VIRGL_CMD0 header layout, VIRGL_OBJECT_SURFACE, VIRGL_CCMD_* opcodes, VIRGL_OBJ_SURFACE_* / clear field order.
• virgl_encode.c — the canonical encoders this hand-encoding mirrors.

3D / virgl extension of the virtio-gpu driver (Milestone 2). This file is purely additive: it does NOT touch the 2D path (OpenVirtioGPU / SetupFramebuffer / Flush / DisplayInfo) nor the M1 ClearScreen path in gpu3d.go. It adds a single high-level operation, DrawTriangle, that renders one flat-shaded triangle into a virtio-gpu scanout using the HOST GPU via virglrenderer — still pure Go, CGO=0.

Why this is the "hard part". A clear (M1) only needs three virgl commands and no shaders. A *draw* needs the whole Gallium draw pipeline encoded by hand: two shaders, four pipeline-state objects (vertex-elements, rasterizer, blend, depth-stencil-alpha), a vertex buffer with guest backing, and the DRAW_VBO itself — all in one SUBMIT_3D virgl command buffer. The crux is the shader encoding. virglrenderer does NOT take binary TGSI tokens over the wire: virgl_encode_shader_state() in Mesa (gallium/drivers/virgl) calls tgsi_dump_str() and ships the shader as a NUL-terminated ASCII TGSI *text* dump; the host (vrend_decode_create_shader -> vrend_create_shader -> tgsi_text_translate) re-parses that text into tokens. So this driver hand-authors TGSI text, which the host parser accepts (str_match_nocase_whole on "VERT"/"FRAG", "DCL", "IMM", "MOV", "END"; see gallium/auxiliary/tgsi/tgsi_text.c). This sidesteps the binary token format entirely.

Authoritative sources (every encoding below is annotated with the file + symbol it was derived from):

• virgl_protocol.h (virglrenderer src/) — enum virgl_context_cmd, enum virgl_object_type, and the VIRGL_OBJ_*/VIRGL_SET_*/VIRGL_DRAW_VBO_* field-offset + size macros.
• virgl_encode.c (Mesa gallium/drivers/virgl) — virgl_encode_shader_state, virgl_emit_shader_header, virgl_emit_shader_streamout, virgl_encoder_create_vertex_elements, virgl_encode_rasterizer_state, virgl_encode_blend_state, virgl_encode_dsa_state, virgl_encoder_set_vertex_buffers, virgl_encoder_draw_vbo, virgl_encoder_set_viewport_states, virgl_encoder_create_surface, virgl_encoder_set_framebuffer_state, virgl_encode_bind_object.
• tgsi_text.c (Mesa gallium/auxiliary/tgsi) — accepted TGSI text syntax.
• p_defines.h (Mesa gallium/include/pipe) — PIPE_SHADER_*, PIPE_BUFFER, PIPE_PRIM_TRIANGLES.
• virgl_hw.h (virglrenderer src/) — VIRGL_BIND_*, VIRGL_FORMAT_*.

See the gpu3d_draw_test.go header and the package REPORT for the per-dword derivation and the UNCERTAINTIES that still need hardware validation.

3D / virgl extension of the virtio-gpu driver (Milestone 3). This file is purely additive: it does NOT touch the 2D path (OpenVirtioGPU / SetupFramebuffer / Flush / DisplayInfo), the M1 ClearScreen path in gpu3d.go, nor the M2 DrawTriangle path in gpu3d_draw.go. It adds a single high-level operation, DrawTexturedTriangle, that renders one triangle whose fragments are sampled from a host-side texture, into a virtio-gpu scanout using the HOST GPU via virglrenderer — still pure Go, CGO=0.

M3 = M2 (DrawTriangle) + a sampled texture. On top of the M2 draw pipeline it adds, per Mesa's virgl encoder + virglrenderer protocol:

• a sampled-texture resource (RGBA8, VIRGL_BIND_SAMPLER_VIEW) with a guest backing the caller's texels are written into + TRANSFER_TO_HOST_3D;
• CREATE_OBJECT(SAMPLER_VIEW=6) over that texture (format + texture-layer + texture-level + swizzle dwords);
• CREATE_OBJECT(SAMPLER_STATE=7) (wrap/filter packing);
• SET_SAMPLER_VIEWS(FRAGMENT, slot 0) + BIND_SAMPLER_STATES(FRAGMENT, slot 0);
• a 2-element VERTEX_ELEMENTS layout (position R32G32B32_FLOAT @0 + texcoord R32G32_FLOAT @12, stride 20);
• texturing TGSI shaders: the VS forwards a GENERIC[0] texcoord, the FS declares SAMP[0]/SVIEW[0] and TEX-samples OUT[0] COLOR.

Authoritative sources (each encoding below cites the file + symbol it was derived from; line numbers are from the notaz/mesa mirror of Mesa, branch master, fetched 2026-06-10):

• virgl_protocol.h (Mesa src/gallium/drivers/virgl) — enum virgl_object_type (SAMPLER_VIEW=6, SAMPLER_STATE=7), enum virgl_context_cmd (SET_SAMPLER_VIEWS=10, BIND_SAMPLER_STATES=18), and the VIRGL_OBJ_SAMPLER_VIEW_* / VIRGL_OBJ_SAMPLE_STATE_S0_* / VIRGL_SET_SAMPLER_VIEWS_* / VIRGL_BIND_SAMPLER_STATES_* macros.
• virgl_encode.c (Mesa src/gallium/drivers/virgl) — virgl_encode_sampler_view, virgl_encode_sampler_state, virgl_encode_set_sampler_views, virgl_encode_bind_sampler_states.
• virgl_hw.h (Mesa src/gallium/drivers/virgl) — VIRGL_FORMAT_R32G32_FLOAT =29, VIRGL_FORMAT_R8G8B8A8_UNORM=67, VIRGL_BIND_SAMPLER_VIEW=(1<<3).
• tgsi_text.c / tgsi_strings.c / tgsi_info.c (Mesa src/gallium/auxiliary/tgsi) — the DCL SAMP / DCL SVIEW grammar, the TEX instruction operand order, and the "2D"/"FLOAT"/"GENERIC" token names.
• p_defines.h (Mesa src/gallium/include/pipe) — PIPE_SWIZZLE_*, PIPE_TEX_WRAP_*, PIPE_TEX_FILTER_*, PIPE_TEX_MIPFILTER_*.

See the gpu3d_tex_test.go header and the package REPORT for the per-dword derivation and the LOUD UNCERTAINTIES that still need hardware validation.