docs(vsi/graphics): define the graphics vendor software interface - #766
Open
Ulrond wants to merge 4 commits into
Open
docs(vsi/graphics): define the graphics vendor software interface#766Ulrond wants to merge 4 commits into
Ulrond wants to merge 4 commits into
Conversation
Replaces the placeholder with the vendor-facing graphics contract: - Architectural split between the application-facing GPU userspace and the compositor-facing IGraphicsFbProvider HAL, referencing the Native Apps WG GPU layer spec for library delivery. - Required EGL 1.5 / OpenGL ES 2.0 baseline and the extension set the compositor depends on: dma_buf_import, dma_buf_import_modifiers, surfaceless_context, offscreen platform display, GL_OES_EGL_image and fence sync. - Vulkan ICD delivery plus the external memory, DRM format modifier and external semaphore extensions required for buffer sharing. - ABI requirements against the base package, device access, and conformance criteria.
Ulrond
added
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Defines the VSI Graphics specification document, describing the vendor GPU userspace library capabilities (EGL/GLES/Vulkan) and the compositor-facing IGraphicsFbProvider contract in the Plane Control HAL for DMA-buf based buffer allocation and presentation.
Changes:
- Replaces the placeholder VSI Graphics page with an architecture overview and buffer flow description.
- Documents required EGL/OpenGL ES extensions, offscreen display creation expectations, and Wayland dma-buf import requirements.
- Specifies Vulkan ICD delivery expectations plus required external memory/synchronisation extensions, ABI expectations, device-node access, and conformance criteria.
Comment on lines
+79
to
+83
| GraphicsFbCapabilities getCapabilities(); | ||
| ParcelFileDescriptor createGraphicsFb(in int width, in int height, out GraphicsFbInfo outInfo); | ||
| void destroyGraphicsFb(in int graphicsFbId); | ||
| boolean commitGraphicsFb(in int graphicsFbId); | ||
| } |
…#62) Graphics drivers are resolved by ICD loaders, not by the dynamic linker alone. Vulkan, EGL under libglvnd, OpenCL, VA-API, GBM and DRI each scan search paths compiled into the loader and load the library named by a manifest found there. Those paths are rootfs paths; the drivers live in the vendor layer. - file_system_architecture: add Loader-Discovered Components — the search path table, manifest registration through boot-time symlinks matching the existing ld.so.conf.d strategy, and the discovery policy (absolute library_path, no environment dependency, loader owned outside the layer). - vsi/graphics: add Loader and Driver Discovery, and describe GPU userspace delivery in terms of the vendor layer.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
vsi/filesystem/current/docs/file_system_architecture.md:381
- The paragraph claims VA-API/GBM drivers are discovered via manifests in fixed compiled-in search paths. That is not accurate for the module-style loaders listed later in the table (VA-API, GBM, DRI) which typically load driver modules by searching well-known directories (no manifest). Reword this sentence to distinguish manifest-based discovery (Vulkan/libglvnd/OpenCL) from module directory scanning (VA-API/GBM/DRI), and avoid implying everything is manifest-driven.
The dynamic linker is not the only mechanism that resolves a shared library at runtime. Vulkan, EGL, OpenCL, VA-API and GBM each ship a **loader** that discovers implementations by scanning a set of search paths compiled into the loader itself, reading a JSON or plain-text manifest found there, and loading the library the manifest names.
vsi/graphics/current/docs/graphics.md:129
- This sentence implies all listed loaders (including VA-API/GBM) discover drivers via a manifest and via fixed compiled-in paths. Later sections/table include manifestless module discovery for VA-API/GBM/DRI, so this wording is misleading. Rephrase to distinguish manifest-based discovery (Vulkan/libglvnd/OpenCL) from module directory scanning (VA-API/GBM/DRI) and avoid overstating “compiled-in” given the XDG/env-derived roots listed next.
Graphics drivers are not loaded by the dynamic linker alone. Vulkan, EGL, OpenCL, VA-API and GBM each use an ICD loader that discovers drivers by scanning **fixed search paths compiled into the loader**, then loading the driver named by a manifest found there. Those search paths are rootfs paths; the drivers live in `/vendor`. The layered architecture therefore has to bridge the two.
The block-beta blocks had no edges and no style rules, so they rendered as six floating boxes separated by empty space cells, at uneven widths driven by the label text. Add the connecting arrows and the per-block style rules used by file_system_architecture.md, and shorten the labels.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (1)
vsi/filesystem/current/docs/file_system_architecture.md:421
- The environment-variable list in the discovery policy is inconsistent with
vsi/graphics/current/docs/graphics.md(and the PR description): Vulkan’sVK_ADD_DRIVER_FILESis also an override that is typically ignored in elevated-privilege/minimal-environment scenarios and should be called out here for completeness.
* **No Environment Dependency**: `VK_DRIVER_FILES`, `VK_LAYER_PATH`, `XDG_DATA_DIRS`, `LIBVA_DRIVERS_PATH`, `GBM_BACKENDS_PATH` and `__EGL_VENDOR_LIBRARY_DIRS` each redirect a loader, but user-relative paths and override variables are ignored under setuid, setgid or file capabilities, and are absent from a minimal service environment. The symlinks are the delivery mechanism; the variables are for development and test
…pet (#62) Method order fixes the transaction ordinals, so the documented snippet has to match IGraphicsFbProvider.aidl: getCapabilities, commitGraphicsFb, createGraphicsFb, destroyGraphicsFb.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
vsi/graphics/current/docs/graphics.md:154
- The loader search-path table uses
${libdir}as a placeholder, but this document otherwise uses concrete rootfs paths (e.g./usr/lib/...) and doesn’t define what${libdir}means. For consistency and to avoid ambiguity for vendors, use explicit/usr/lib/...paths here (matching the registration examples below).
| **VA-API** | `${libdir}/dri` | — | `<driver>_drv_video.so` |
| **GBM backends** | `${libdir}/gbm` | — | `<backend>_gbm.so` |
| **Mesa DRI** | `${libdir}/dri` | — | `<driver>_dri.so` |
vsi/filesystem/current/docs/file_system_architecture.md:395
- The loader search-path table uses
${libdir}as a placeholder, but this section otherwise uses concrete rootfs paths (e.g./usr/lib/...) and doesn’t define what${libdir}means. To keep the specification unambiguous for vendors, use explicit/usr/lib/...paths here (matching the manifest-registration examples below).
| **VA-API** | `${libdir}/dri` | — | `<driver>_drv_video.so` |
| **GBM backends** | `${libdir}/gbm` | — | `<backend>_gbm.so` |
| **Mesa DRI** | `${libdir}/dri` | — | `<driver>_dri.so` |
This was referenced Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #62
The VSI Graphics document defines what a vendor must deliver for graphics on an RDK platform, and the file system architecture is extended to cover how ICD loaders find it.
Graphics VSI
Two surfaces, one vendor GPU stack. Application-facing EGL/OpenGL ES/Vulkan userspace delivered in the
/vendorlayer, and the compositor-facingIGraphicsFbProviderin the Plane Control HAL.EGL 1.5 / OpenGL ES 2.0 baseline with the extension set the platform-agnostic compositor depends on —
EGL_EXT_image_dma_buf_import,EGL_EXT_image_dma_buf_import_modifiers,EGL_KHR_surfaceless_context, an offscreen platform display (EGL_MESA_platform_surfacelessorEGL_EXT_platform_device),GL_OES_EGL_imageand fence sync. Without these the offscreen-FBO pluscommitGraphicsFb()path described in the Westeros transformation cannot be implemented.Vulkan ships as an ICD with the loader owned by the platform, plus the external memory, DRM format modifier and external semaphore extensions needed to share buffers with the compositor and video pipeline.
Wayland client buffers are imported through
zwp_linux_dmabuf_v1with the referencelibwayland-egl, so the vendor GPU stack works with the upstream library unmodified.ABI, device access and conformance state what binary compatibility against the base package means, which device nodes rendering requires, and the criteria a platform meets to be conformant.
Loader-discovered components
Graphics drivers are not resolved by the dynamic linker alone. Vulkan, EGL under libglvnd, OpenCL, VA-API, GBM and DRI each scan search paths compiled into the loader and load the library named by a manifest found there. Those search paths are rootfs paths; the drivers live in the vendor layer.
file_system_architecture.mdgains a Loader-Discovered Components section covering the search path table, manifest registration through boot-time symlinks — the same strategy already used forld.so.conf.d— and the discovery policy:library_pathin a manifest is absolute. Loaders resolve a relativelibrary_pathagainst the directory holding the manifest, which under a rootfs symlink is the link location rather than the layer.VK_DRIVER_FILES,XDG_DATA_DIRS,LIBVA_DRIVERS_PATH,GBM_BACKENDS_PATHand__EGL_VENDOR_LIBRARY_DIRSare ignored under setuid/setgid/file capabilities and absent from a minimal service environment.