VirGL Renderer

https://github.com/xuehuihui/virglrenderer
Admin
Tokens:2,755
Snippets:31
Trust Score:3.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Building and Installing Virglrenderer with Meson (sh)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/README.rst

This snippet provides the shell commands to build and install the Virglrenderer project using the Meson build system. It initializes the build directory, changes into it, and then executes the installation.

```sh
$ meson build
$ cd build
$ ninja install
```

--------------------------------

### Starting Perfetto UI Local Service (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

This command starts a local service for the Perfetto UI, allowing visualization of the generated Perfetto trace files. Once started, the UI can be accessed via a web browser at the specified localhost address.

```console
$ perf-testing/perfetto-ui.sh
```

--------------------------------

### Starting VirGL Test Server

Source: https://github.com/xuehuihui/virglrenderer/blob/main/containers/podman.md

This command starts the `virgl_test_server` in a separate terminal. This server component is essential for receiving rendering commands from the container and providing the virtual GPU functionality.

```shell
virgl_test_server
```

--------------------------------

### Starting virgl_test_server with ASAN Symbolizer (Bash)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/docs/ASAN-notes.txt

This Bash command launches the virgl_test_server while setting the ASAN_SYMBOLIZER_PATH environment variable. This configuration directs ASAN to use llvm-symbolizer for resolving memory addresses in crash reports, providing detailed and human-readable stack traces for debugging.

```Bash
ASAN_SYMBOLIZER_PATH=/usr/bin/llvm-symbolizer ./virgl_test_server
```

--------------------------------

### Configuring Vtest Client Environment (Bash)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/docs/ASAN-notes.txt

These Bash commands configure the environment for a vtest client to connect to the virglrenderer server. LIBGL_ALWAYS_SOFTWARE=true forces software rendering, and GALLIUM_DRIVER=virpipe specifies the virpipe Gallium driver, enabling the client to interact correctly with the ASAN-enabled virglrenderer setup.

```Bash
export LIBGL_ALWAYS_SOFTWARE=true
export GALLIUM_DRIVER=virpipe
```

--------------------------------

### Running VirGL-enabled Container

Source: https://github.com/xuehuihui/virglrenderer/blob/main/containers/podman.md

This script command starts the container, which is configured to use the VirGL driver. The `${CONTAINER_ID}` placeholder should be replaced with the actual ID of the built container image.

```shell
./run-container.sh ${CONTAINER_ID}
```

--------------------------------

### Running Trace with Direct Trace File Path (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

This example shows running the trace script where the trace file path is given directly, assuming the root directory is correctly set. This command is functionally equivalent to specifying the traces-db subdirectory path when the traces DB is a subdirectory of the root.

```console
  perf-testing/run_trace-in-container.sh -r $rootdir -t sometrace.trace
```

--------------------------------

### Running Trace with Traces DB Subdirectory Path (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

This example demonstrates running the trace script where the trace file path includes the traces-db subdirectory name. This is a convenience for shell autocompletion users when the traces DB is located as a subdirectory of the specified root.

```console
  perf-testing/run_trace-in-container.sh -r $rootdir -t traces-db/sometrace.trace
```

--------------------------------

### Configuring Tracing Backend in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This combo option allows selecting a backend for emitting traces. It defaults to 'none', with available choices including 'percetto', 'perfetto', 'sysprof', and 'stderr' for various tracing mechanisms.

```Meson
option(
  'tracing',
  type : 'combo',
  value : 'none',
  choices : [ 'percetto', 'perfetto', 'sysprof', 'stderr', 'none' ],
  description : 'enable emitting traces using the selected backend'
)
```

--------------------------------

### Pre-loading ASAN and dlclose Stub (Bash)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/docs/ASAN-notes.txt

This Bash command sets the LD_PRELOAD environment variable to load the ASAN library (libasan.so) and a custom libfake-dlclose.so before other libraries. This ensures ASAN is active and the dlclose override is in place, addressing issues with Mesa driver unloading during ASAN analysis.

```Bash
export LD_PRELOAD="/usr/lib64/gcc/x86_64-pc-linux-gnu/7.3.0/libasan.so $HOME/libfake-dlclose.so"
```

--------------------------------

### Configuring Render Server Context Servicing in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This combo option defines how a context within the render server is serviced. It defaults to 'process', with other choices including 'thread' and 'minijail' for different isolation or concurrency models.

```Meson
option(
  'render-server-worker',
  type : 'combo',
  value : 'process',
  choices : ['process', 'thread', 'minijail'],
  description : 'how a context in render server is serviced'
)
```

--------------------------------

### Configuring Platform Support in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This option defines the graphics platforms to support. It is an array type, defaulting to 'auto' which enables all available platforms. Users can explicitly choose 'egl' or 'glx' for specific platform support.

```Meson
option(
  'platforms',
  type : 'array',
  value : ['auto'],
  choices : [
    'egl', 'glx', 'auto'
  ],
  description : 'Platforms support, set to auto to enable all.'
)
```

--------------------------------

### Building Virglrenderer Target Docker Image (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

This command navigates to the virglrenderer directory and executes a script to build the specific Docker image for the Virglrenderer performance testing environment. This image builds on the previously created base images.

```console
$ cd virglrenderer
$ sh perf-testing/build-dockerimage.sh
```

--------------------------------

### Specifying DRM Native-Context Renderers in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This array option allows specifying a list of DRM native-context renderers to be built. It defaults to an empty list, with available choices including 'amdgpu-experimental' and 'msm'.

```Meson
option(
  'drm-renderers',
  type : 'array',
  value : [],
  choices : [
    'amdgpu-experimental',
    'msm',
  ],
  description : 'List of drm native-context renderers to build'
)
```

--------------------------------

### Building Crosvm Base Docker Images (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

These commands clone the Crosvm repository and execute scripts to build the base Docker images required for the Virgl testing environment. This is a prerequisite for building the target image.

```console
$ git clone https://chromium.googlesource.com/chromiumos/platform/crosvm
$ pushd crosvm
$ sh docker/build_crosvm_base.sh
$ sh docker/build_crosvm.sh
```

--------------------------------

### Configuring Dynamic Vulkan Library Loading in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option determines whether the Vulkan library (libvulkan) is loaded dynamically at runtime or linked at build-time. It defaults to 'false', implying static linking unless enabled.

```Meson
option(
  'vulkan-dload',
  type : 'boolean',
  value : 'false',
  description : 'enable loading libvulkan dynamically at runtime instead of linking to it at build-time'
)
```

--------------------------------

### Configuring Host-Side GL Error Handling in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option dictates whether host-side OpenGL errors are treated as fatal. It is set to 'true' by default, causing the build to fail upon encountering such errors.

```Meson
option(
  'check-gl-errors',
  type : 'boolean',
  value : 'true',
  description : 'treat host-side gl errors as fatal'
)
```

--------------------------------

### Enabling Minigbm Allocation Support in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option controls whether support for minigbm allocations is enabled. It defaults to 'false', meaning minigbm allocation support is disabled by default.

```Meson
option(
  'minigbm_allocation',
  type : 'boolean',
  value : 'false',
  description : 'enable support for minigbm_allocations'
)
```

--------------------------------

### Compiling virglrenderer with ASAN/MSAN (Bash)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/docs/ASAN-notes.txt

This snippet outlines the process to compile virglrenderer with either Address Sanitizer (ASAN) or Memory Sanitizer (MSAN) enabled. It sets CFLAGS and CXXFLAGS to include the -fsanitize flags and -fno-omit-frame-pointer for better stack traces, then uses autogen.sh and make to build the project.

```Bash
export CFLAGS="-fsanitize=address -fno-omit-frame-pointer"
export CXXFLAGS="-fsanitize=address -fno-omit-frame-pointer"
mkdir build && cd build
../autogen.sh --prefix=/home/user/virglrenderer/install --enable-debug
make
```

--------------------------------

### Enabling Valgrind for Unit Tests in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option enables the execution of unit tests with Valgrind, a memory debugging and profiling tool. It defaults to 'false', requiring explicit activation for Valgrind integration.

```Meson
option(
  'valgrind',
  type : 'boolean',
  value : 'false',
  description : 'enable running unit tests with valgrind'
)
```

--------------------------------

### Configuring Render Server (Deprecated) in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option, now deprecated, previously controlled the render server. Its functionality is now automatically enabled when Venus support is active, and it defaults to 'false'.

```Meson
option(
  'render-server',
  type : 'boolean',
  value : 'false',
  description : 'DEPRECATED: render server is enabled by venus automatically'
)
```

--------------------------------

### Enabling Unstable APIs in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option controls the activation of unstable APIs. It defaults to 'false', meaning these experimental APIs are not enabled unless explicitly set.

```Meson
option(
  'unstable-apis',
  type : 'boolean',
  value : 'false',
  description : 'enable unstable apis'
)
```

--------------------------------

### Building VirGL-enabled Container Image

Source: https://github.com/xuehuihui/virglrenderer/blob/main/containers/podman.md

This command builds a container image using a specified Dockerfile. It's used to create a base Ubuntu/RHEL9 container with the latest VirGL OpenGL driver, allowing for accelerated graphics within the container.

```shell
podman build -f Dockerfile.${DISTRO}
```

--------------------------------

### Enabling Venus Support in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option enables or disables support for the Venus Vulkan driver. It is set to 'false' by default, requiring explicit activation.

```Meson
option(
  'venus',
  type : 'boolean',
  value : 'false',
  description : 'enable support for venus'
)
```

--------------------------------

### Enabling Unit Tests in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option controls whether unit tests are enabled for the project. It defaults to 'false', meaning tests are not built or run unless explicitly activated.

```Meson
option(
  'tests',
  type : 'boolean',
  value : 'false',
  description : 'enable unit tests'
)
```

--------------------------------

### Running API Trace in Virglrenderer Container (Console)

Source: https://github.com/xuehuihui/virglrenderer/blob/main/perf-testing/README.md

This command executes the trace runner script within the Virglrenderer Docker container. It requires specifying the root path containing Mesa, Virglrenderer, and traces DB checkouts, along with the API trace file to be run. This initiates the performance tracing process.

```console
$ cd virglrenderer
$ bash perf-testing/run_trace-in-container.sh \
    --root $PATH_THAT_CONTAINS_MESA_CHECKOUT_VIRGLRENDERER_AND_TRACES_DB_CHECKOUT \
    --trace $API_TRACE_TO_RUN
```

--------------------------------

### Enabling Hardware Video Acceleration Support in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option enables or disables support for hardware video acceleration. It is set to 'false' by default, meaning hardware video acceleration is not active unless explicitly enabled.

```Meson
option(
  'video',
  type : 'boolean',
  value : 'false',
  description : 'enable support for hardware video acceleration'
)
```

--------------------------------

### Testing VirGL Driver with glxgears

Source: https://github.com/xuehuihui/virglrenderer/blob/main/containers/podman.md

This command runs `glxgears` with the `-info` flag inside the container to verify that the VirGL driver is being used for rendering. The output should display `GL_RENDERER = virgl`.

```shell
glxgears -info
```

--------------------------------

### C Stub for Overriding dlclose

Source: https://github.com/xuehuihui/virglrenderer/blob/main/docs/ASAN-notes.txt

This C function provides a minimal dlclose implementation that always returns 0. It is used to prevent dynamic libraries, particularly Mesa drivers, from being unloaded prematurely, which can interfere with ASAN's ability to generate complete stack traces at program termination.

```C
int dlclose(void *handle) {
        return 0;
}
```

--------------------------------

### Enabling Venus Validation Layer in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option controls the activation of the validation layer for Venus. By default, it is set to 'false', meaning the validation layer is not enabled.

```Meson
option(
  'venus-validate',
  type : 'boolean',
  value : 'false',
  description : 'enable the validation layer for venus'
)
```

--------------------------------

### Enabling Fuzzer in Meson

Source: https://github.com/xuehuihui/virglrenderer/blob/main/meson_options.txt

This boolean option enables or disables the fuzzer. It defaults to 'false', meaning the fuzzer is not active unless explicitly enabled.

```Meson
option(
  'fuzzer',
  type : 'boolean',
  value : 'false',
  description : 'enable unit tests'
)
```
Tokens:
Raw