From 9c7d8401b83b2977f1772a6d4253d6f9d4ea2995 Mon Sep 17 00:00:00 2001
From: Billy Laws <blaws05@gmail.com>
Date: Wed, 13 Jul 2022 20:54:22 +0100
Subject: [PATCH] Add ADPKG format description

---
 tools/ADPKG.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 tools/ADPKG.md

diff --git a/tools/ADPKG.md b/tools/ADPKG.md
new file mode 100644
index 0000000..0cc2bdd
--- /dev/null
+++ b/tools/ADPKG.md
@@ -0,0 +1,96 @@
+# Android Driver Package Format
+
+## Contents
+- `meta.json` that follows `Schema`
+- `<driver>.so` main driver shared library
+- `*.so` all libraries depended on by the main driver library, these must have their sonames altered if they wish to replace the system version of the library
+
+## Example
+`meta.json`:
+```json
+{
+  "schemaVersion": 1,
+  "name": "Qualcomm v615 Vulkan driver",
+  "description": "Proprietary Vulkan driver for Adreno 6xx and Adreno 7xx",
+  "author": "ByLaws",
+  "packageVersion": "2",
+  "vendor": "Qualcomm",
+  "driverVersion": "0.615.0",
+  "minApi": 27,
+  "libraryName": "vulkan.ad0615.so"
+}
+```
+
+`vulkan.ad0615.so`: main patched driver
+`notadreno_utils.so`, `notdmabufheap.so`, `notgsl.so`, `notllvm-glnext.so`, `notllvm-qgl.so`: patched-soname versions of libraries specific to each driver version
+`android.hardware.graphics.mappershim.so`, `vendor.qti.hardware.display.mapperextensionsshim.so`, `vendor.qti.hardware.display.mappershim.so`: qtimapper-shim libs
+
+## Creation
+I recommend running blob-patcher.py to patch a set of blobs from a device dump with mapper ver as 5, then copying in the qtimapper-shim files from the adrenotools releases page.
+```bash
+$ mkdir outpkg
+$ patch.py <device dump> outpkg vulkan.adreno.so vulkan.ad0615.so 5
+$ vim outpkg/meta.json
+$ cp qtimapper-shim-rel/* outpkg
+```
+
+## Schema
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ADPKG Schema",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "example": 1
+    },
+    "name": {
+      "type": "string",
+      "example": "Qualcomm Adreno Driver"
+    },
+    "vendor": {
+      "enum": [
+        "Qualcomm",
+        "Mesa"
+      ],
+    },
+    "driverVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+.[0-9]+.[0-9]+(-.+)?$",
+      "example": "512.604.0"
+    },
+    "author": {
+      "type": "string",
+      "example": "Billy Laws"
+    },
+    "description": {
+      "type": "string",
+      "description": "Additional description of the driver, this shouldn't contain redundant information that is already covered by the other fields such as the version and only denote details important for the user"
+    },
+    "packageVersion": {
+      "type": "string",
+      "example": "3029-bylaws"
+    },
+    "minApi": {
+      "type": "number",
+      "description": "The minimum Android API version required by the driver to function correctly",
+      "example": 27
+    },
+    "libraryName": {
+      "type": "string",
+      "description": "The name of the main shared library object",
+      "example": "vulkan.adreno.so"
+    },
+  },
+  "required": [
+    "schemaVersion",
+    "name",
+    "author",
+    "packageVersion",
+    "vendor",
+    "driverVersion",
+    "minApi",
+  ]
+}
+```