1# Graphics Streaming Kit (formerly: Vulkan Cereal) 2 3Graphics Streaming Kit (colloquially known as Gfxstream) is a code generator 4that makes it easier to serialize and forward graphics API calls from one place 5to another: 6 7- From a virtual machine guest to host for virtualized graphics 8- From one process to another for IPC graphics 9- From one computer to another via network sockets 10 11# Build: Linux 12 13The latest directions for the standalone Linux build are provided 14[here](https://crosvm.dev/book/appendix/rutabaga_gfx.html). 15 16# Build: Windows 17 18Make sure the latest CMake is installed. Make sure Visual Studio 2019 is 19installed on your system along with all the Clang C++ toolchain components. 20Then: 21 22``` 23mkdir build 24cd build 25cmake . ../ -A x64 -T ClangCL 26``` 27 28A solution file should be generated. Then open the solution file in Visual 29studio and build the `gfxstream_backend` target. 30 31# Build: Android for host 32 33Be in the Android build system. Then: 34 35``` 36m libgfxstream_backend 37``` 38 39It then ends up in `out/host` 40 41This also builds for Android on-device. 42 43# Output artifacts 44 45``` 46libgfxstream_backend.(dll|so|dylib) 47``` 48 49# Regenerating Vulkan code 50 51To re-generate both guest and Vulkan code, please run: 52 53scripts/generate-gfxstream-vulkan.sh 54 55# Regenerating GLES/RenderControl code 56 57First, build `build/gfxstream-generic-apigen`. Then run: 58 59``` 60scripts/generate-apigen-source.sh 61``` 62 63# Tests 64 65## Windows Tests 66 67There are a bunch of test executables generated. They require `libEGL.dll` and 68`libGLESv2.dll` and `vulkan-1.dll` to be available, possibly from your GPU 69vendor or ANGLE, in the `%PATH%`. 70 71## Android Host Tests 72 73There are Android mock testa available, runnable on Linux. To build these tests, 74run: 75 76``` 77m GfxstreamEnd2EndTests 78``` 79 80# Features 81 82## Tracing 83 84The host renderer has optional support for Perfetto tracing which can be enabled 85by defining `GFXSTREAM_BUILD_WITH_TRACING` (enabled by default on Android 86builds). 87 88The `perfetto` and `traced` tools from Perfetto should be installed. Please see 89the [Perfetto Quickstart](https://perfetto.dev/docs/quickstart/linux-tracing) or 90follow these short form instructions: 91 92``` 93cd <your Android repo>/external/perfetto 94 95./tools/install-build-deps 96 97./tools/gn gen --args='is_debug=false' out/linux 98 99./tools/ninja -C out/linux traced perfetto 100``` 101 102To capture a trace on Linux, start the Perfetto daemon: 103 104``` 105./out/linux/traced 106``` 107 108Then, run Gfxstream with 109[Cuttlefish](https://source.android.com/docs/devices/cuttlefish): 110 111``` 112cvd start --gpu_mode=gfxstream_guest_angle_host_swiftshader 113``` 114 115Next, start a trace capture with: 116 117``` 118./out/linux/perfetto --txt -c gfxstream_trace.cfg -o gfxstream_trace.perfetto 119``` 120 121with `gfxstream_trace.cfg` containing the following or similar: 122 123``` 124buffers { 125 size_kb: 4096 126} 127data_sources { 128 config { 129 name: "track_event" 130 track_event_config { 131 } 132 } 133} 134``` 135 136Next, end the trace capture with Ctrl + C. 137 138Finally, open https://ui.perfetto.dev/ in your webbrowser and use "Open trace 139file" to view the trace. 140 141# Design Notes 142 143## Guest Vulkan 144 145gfxstream vulkan is the most actively developed component. Some key commponents 146of the current design include: 147 148- 1:1 threading model - each guest Vulkan encoder thread gets host side 149 decoding thread 150- Support for both virtio-gpu, goldish and testing transports. 151- Support for Android, Fuchsia, and Linux guests. 152- Ring Buffer to stream commands, in the style of io_uring. 153- Mesa embedded to provide 154 [dispatch](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/dispatch.rst) 155 and 156 [objects](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/base-objs.rst). 157- Currently, there are a set of Mesa objects and gfxstream objects. For 158 example, `struct gfxstream_vk_device` and the gfxstream object 159 `goldfish_device` both are internal representations of Vulkan opaque handle 160 `VkDevice`. The Mesa object is used first, since Mesa provides dispatch. The 161 Mesa object contains a key to the hash table to get a gfxstream internal 162 object (for example, `gfxstream_vk_device::internal_object`). Eventually, 163 gfxstream objects will be phased out and Mesa objects used exclusively. 164 165# Project Ideas 166gfxstream is a first class open source project, and welcomes new contributors. 167There are many interesting projects available, for new and experienced software 168enthusiasts. Some ideas include: 169 1701) New OS support (Windows, Haiku, MacOS) support for gfxstream guest 1712) Rewriting the gfxstream protocol using python templates and working 172 with other FOSS projects to de-duplicate 1733) Guided performance optimizations 1744) KVM or hypervisor integration to close gap between HW GPU virtualization 1755) Improving rutabaga integrations 1766) Improving display virtualization 177 178Please reach out to your local gfxstreamist today if you are interested! 179