From 02428431af394ed9033eb1d76cd791547c7bf2f8 Mon Sep 17 00:00:00 2001 From: "Matias N. Goldberg" Date: Fri, 5 Apr 2024 13:24:08 -0300 Subject: [PATCH] Improve documentation with important information This avoids common mistakes --- include/adrenotools/driver.h | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/include/adrenotools/driver.h b/include/adrenotools/driver.h index b09b4db..f81e8fe 100644 --- a/include/adrenotools/driver.h +++ b/include/adrenotools/driver.h @@ -12,11 +12,18 @@ extern "C" { /** * @brief Opens a new libvulkan.so instance according to `flags` + * @remark IMPORTANT: The app MUST be packaged w/ useLegacyPackaging = true. The reason for this is + * that we install the hook in hookLibDir; but this folder won't be set correctly when useLegacyPackaging == false + * because Android expects to read the *.so directly from the apk (instead of decompressing them into nativeLibraryDir). * @param dlopenMode The dlopen mode to use when opening libvulkan * @param featureFlags Which adrenotools driver features to enable * @param tmpLibDir A writable directory to hold patched libraries, only used on api < 29 due to the lack of memfd support. If nullptr is passed and the API version is < 29 memfd usage will be attempted and if unsupported nullptr will be returned - * @param hookLibDir The directory holding the built hooks - * @param customDriverDir The directory to load a custom GPU driver named according to `customDriverName` from. Only used if ADRENOTOOLS_DRIVER_CUSTOM is set in `featureFlags` + * @param hookLibDir The directory holding the built hooks. + * IMPORTANT: This path MUST point to whatever `getApplicationInfo().nativeLibraryDir` (Kotlin code) returns. + * Failing to do so will result in this function returning a valid ptr but then the hook will fail and either the original driver is loaded as fallback, or vkEnumeratePhysicalDevices returns 0 devices. + * @param customDriverDir The directory to load a custom GPU driver named according to `customDriverName` from. Only used if ADRENOTOOLS_DRIVER_CUSTOM is set in `featureFlags`. + * IMPORTANT: This path MUST NOT be on sdcard/storage. i.e. use ANativeActivity::internalDataPath and often looks like "/data/user/0/com.example.app/files/". + * Otherwise you will get permission denied because dlopen() can't be done on *.so libraries that any random user or application can manipulate (which would be a security risk). * @param customDriverName The soname of the custom driver to load. Only used if ADRENOTOOLS_DRIVER_CUSTOM is set in `featureFlags` * @param fileRedirectDir The directory which to redirect all file accesses performed by the driver to. Only used if ADRENOTOOLS_DRIVER_FILE_REDIRECT is set in `featureFlags` * @param userMappingHandle A pointer to a void* which will be set to the mapping handle if ADRENOTOOLS_DRIVER_GPU_MAPPING_IMPORT is set in `featureFlags`