1# Graphics Streaming Kit (formerly: Vulkan Cereal)
2
3Graphics Streaming Kit is a code generator that makes it easier to serialize
4and forward graphics API calls from one place to another:
5
6- From a virtual machine guest to host for virtualized graphics
7- From one process to another for IPC graphics
8- From one computer to another via network sockets
9
10# Build: Linux
11
12The latest directions for the standalone Linux build are provided
13[here](https://crosvm.dev/book/appendix/rutabaga_gfx.html).
14
15# Build: Windows
16
17Make sure the latest CMake is installed.  Make sure Visual Studio 2019 is
18installed on your system along with all the Clang C++ toolchain components.
19Then:
20
21    mkdir build
22    cd build
23    cmake . ../ -A x64 -T ClangCL
24
25A solution file should be generated. Then open the solution file in Visual
26studio and build the `gfxstream_backend` target.
27
28# Build: Android for host
29
30Be in the Android build system. Then:
31
32    m libgfxstream_backend
33
34It then ends up in `out/host`
35
36This also builds for Android on-device.
37
38# Output artifacts
39
40    libgfxstream_backend.(dll|so|dylib)
41
42# Regenerating Vulkan code
43
44To re-generate both guest and Vulkan code, please run:
45
46   scripts/generate-gfxstream-vulkan.sh
47
48# Regenerating GLES/RenderControl code
49
50First, build `build/gfxstream-generic-apigen`. Then run:
51
52    scripts/generate-apigen-source.sh
53
54# Tests
55
56## Windows Tests
57
58There are a bunch of test executables generated. They require `libEGL.dll` and `libGLESv2.dll` and `vulkan-1.dll` to be available, possibly from your GPU vendor or ANGLE, in the `%PATH%`.
59
60## Android Host Tests
61
62There are Android mock testa available, runnable on Linux.  To build these tests, run:
63
64    m GfxstreamEnd2EndTests
65
66# Structure
67
68- `CMakeLists.txt`: specifies all host-side build targets. This includes all
69  backends along with client/server setups that live only on the host. Some
70  - Backend implementations
71  - Implementations of the host side of various transports
72  - Frontends used for host-side testing with a mock implementation of guest
73    graphics stack (mainly Android)
74  - Frontends that result in actual Linux/macOS/Windows gles/vk libraries
75    (isolation / fault tolerance use case)
76- `Android.bp`: specifies all guest-side build targets for Android:
77  - Implementations of the guest side of various transports (above the kernel)
78  - Frontends
79- `BUILD.gn`: specifies all guest-side build targets for Fuchsia
80  - Implementations of the guest side of various transports (above the kernel)
81  - Frontends
82- `base/`: common libraries that are built for both the guest and host.
83  Contains utility code related to synchronization, threading, and suballocation.
84- `protocols/`: implementations of protocols for various graphics APIs. May contain
85code generators to make it easy to regen the protocol based on certain things.
86- `host-common/`: implementations of host-side support code that makes it
87  easier to run the server in a variety of virtual device environments.
88  Contains concrete implementations of auxiliary virtual devices such as
89  Address Space Device and Goldfish Pipe.
90- `stream-servers/`: implementations of various backends for various graphics
91  APIs that consume protocol. `gfxstream-virtio-gpu-renderer.cpp` contains a
92  virtio-gpu backend implementation.
93
94# Guest Vulkan design
95
96gfxstream vulkan is the most actively developed component.  Some key commponents of
97the current design include:
98
99- 1:1 threading model - each guest Vulkan encoder thread gets host side decoding thread
100- Support for both virtio-gpu, goldish and testing transports.
101- Support for Android, Fuchsia, and Linux guests.
102- Ring Buffer to stream commands, in the style of io_uring.
103- Mesa embedded to provide [dispatch](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/dispatch.rst)
104  and [objects](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/base-objs.rst).
105- Currently, there are a set of Mesa objects and gfxstream objects.  For example,
106  `struct gfxstream_vk_device` and the gfxstream object `goldfish_device` both are internal
107  representations of Vulkan opaque handle `VkDevice`. The Mesa object is used first, since Mesa
108  provides dispatch.  The Mesa object contains a key to the hash table to get a gfxstream
109  internal object (for example, `gfxstream_vk_device::internal_object`).  Eventually, gfxstream
110  objects will be phased out and Mesa objects used exclusively.
111