Finished with the assembling section

canonical · Apr 17, 2024 · f169b90 · f169b90
1 parent e9cdb35
commit f169b90
Showing 1 changed file with 100 additions and 31 deletions.
diff --git a/doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md b/doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md
@@ -144,14 +144,14 @@ the `graphics/lib` directory, where they are expected to be.
 
 ```yaml
 vendor-drivers:
-    plugin: make
-    source: libmali
-    make-parameters:
-      - LIBDIR=$SNAPCRAFT_PART_INSTALL/lib
-    organize:
-      'lib/*.so*': graphics/lib/
-    prime:
-      - graphics/lib/*
+  plugin: make
+  source: libmali
+  make-parameters:
+    - LIBDIR=$SNAPCRAFT_PART_INSTALL/lib
+  organize:
+    'lib/*.so*': graphics/lib/
+  prime:
+    - graphics/lib/*
 
 slots:
   graphics-core20:
@@ -162,31 +162,100 @@ slots:
 
 ### How to supply the remaining libraries
 As mentioned before, you should be able to get the remaining libraries from
-the Ubuntu archive.
+the Ubuntu archive. The part below can supply these libraries. Please note
+again that these libraries are organized into `graphics/lib`.
 
 ```yaml
+parts:
+  ...
   dependencies:
-	plugin: nil
-	stage-packages:
-  	- libdrm2
-  	- libx11-xcb1
-  	- libxau6
-  	- libxcb-dri2-0
-  	- libxcb-dri3-0
-  	- libxcb-present0
-  	- libxcb1
-  	- libxcb-sync1
-  	- libxcb-xfixes0
-  	- libxdmcp6
-  	- libxshmfence1
-	- libwayland-client0
-	- libwayland-server0
-	organize:
-  	'usr/lib/aarch64-linux-gnu': graphics/lib/
-	prime:
-  	- graphics/lib/*
+    plugin: nil
+    stage-packages:
+    - libdrm2
+    - libx11-xcb1
+    - libxau6
+    - libxcb-dri2-0
+    - libxcb-dri3-0
+    - libxcb-present0
+    - libxcb1
+    - libxcb-sync1
+    - libxcb-xfixes0
+    - libxdmcp6
+    - libxshmfence1
+    - libwayland-client0
+    - libwayland-server0
+    organize:
+      'usr/lib/aarch64-linux-gnu': graphics/lib/
+    prime:
+    - graphics/lib/*
 ```
 
-### Example
-For an example of a `graphics-core22` snap, check out
-[this file](https://github.com/canonical/mesa-core22/blob/main/snap/snapcraft.yaml).
+### Possible complications
+There are a number of ways the vendor drivers can differ from this simplest case, requiring different solutions.
+Let's explore a few of them.
+
+#### Vendor drivers require libraries newer than core22 provides
+Some vendor driver binaries might be built against newer libraries than are provided in the 
+Ubuntu 20.04 repositories. Particularly, the core `libwayland` libraries have introduced new
+features since 20.04 that vendor binaries might require. This will manifest as missing 
+symbol errors at runtime.
+
+Generally, new version requirements for libraries can be handled by adding a snapcraft
+part building the required library version. An example of this for `libwayland` is:
+
+```yaml
+parts:
+  ...
+  wayland:
+    plugin: meson
+    meson-parameters:
+      - -Ddocumentation=false
+      - -Dtests=false
+    build-packages:
+      - libxml2-dev
+      - libffi-dev
+      - libexpat1-dev
+      - pkg-config
+    override-build: |
+      snapcraftctl build
+      # We use the libwayland-egl from the vendor-drivers part.
+      # We remove this here, as otherwise snapcraft will complain that we have two
+      # different files trying to provide libwayland-egl.so
+      rm $SNAPCRAFT_PART_INSTALL/usr/local/lib/aarch64-linux-gnu/libwayland-egl*
+    source: https://gitlab.freedesktop.org/wayland/wayland.git
+    source-type: git
+    source-tag: 1.21.0
+    organize:
+      'usr/local/lib/aarch64-linux-gnu': graphics/lib/
+    prime:
+      - graphics/lib/*
+```
+
+#### Vendor driver uses a $VENDOR_dri.so DRI driver
+Some vendor drivers (internally based on Mesa) retain the separate DRI driver component. If
+a vendor driver is missing its DRI component then running a program using EGL will generate
+a `libGL` warning about failure to load `$VENDOR_dri.so`, followed by either program failure
+or possibly the program continuing with CPU rendering.
+
+Any vendor DRI driver should be provided under the top-level dri/ directory. An example
+from the `imx-gpu-viv` driver is:
+
+```yaml
+# TODO: What is the context here?
+organize:
+  imx-gpu-viv-6.4.3.p0.0-aarch64/gpu-core/usr/lib/dri/* : graphics/dri/
+```
+
+Snaps which use the `graphics-core22` interface will set the necessary environment variables
+to point the DRI loader at the top-level `dri/` path under the path exported by the
+`graphics-core22` slot.
+
+#### Vendor drivers use libglvnd
+Some drivers might use the `libglvnd` vendor-neutral GL/EGL library. In this case the vendor
+drivers will ship an `egl_vendor.d/$SOMETHING.json` file, pointing to their vendor EGL library.
+The [mesa-core22](https://github.com/canonical/mesa-core22/blob/main/snap/snapcraft.yaml)
+`snapcraft.yaml` provides an example of this sort of driver; the `egl_vendor.d`
+directory is shipped in a top-level `glvnd` path, under the path exported by the
+`graphics-core22` slot.
+
+.