Merge changes from topic "gles_layers_updates" (3e42b82b) · Commits · e / os / android_frameworks_native-old

opengl/libs/EGL/GLES_layers.md

0 → 100644

+258 −0

Original line number	Original line	Diff line number	Diff line
			# GLES Layers

			## EGL Loader Initialization
			After standard entrypoints have all been populated unmodified, a GLES LayerLoader will be instantiated. If debug layers are enabled, the LayerLoader will scan specified directories for layers, just like the Vulkan loader does.

			If layering is enabled, the loader will search for and enumerate a specified layer list. The layer list will be specified by colon separated filenames (see [Enabling layers](#Enabling-layers) below).

			The layers will be traversed in the order they are specified, so the first layer will be directly below the application. For each layer, it will track two entrypoints from the layer. `AndroidGLESLayer_Initialize` and `AndroidGLESLayer_GetProcAddress`.
			```cpp
			typedef void* (PFNEGLGETNEXTLAYERPROCADDRESSPROC)(void, const char*);
			void* AndroidGLESLayer_Initialize(void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address))
			```

			`AndroidGLESLayer_Initialize` is a new function that provides an identifier for the layer to use (layer_id) and an entrypoint that can be called to look up functions below the layer. The entrypoint can be used like so:
			```cpp
			const char* func = "eglFoo";
			void* gpa = get_next_layer_proc_address(layer_id, func);
			```

			Note that only GLES2+ entrypoints will be provided. If a layer tries to make independent GLES 1.x calls, they will be routed to GLES2+ libraries, which may not behave as expected. Application calls to 1.x will not be affected.

			AndroidGLESLayer_GetProcAddress is a new function designed for this layering system. It takes the address of the next call in the chain that the layer should call when finished. If there is only one layer, next will point directly to the driver for most functions.
			```cpp
			void* AndroidGLESLayer_GetProcAddress(const char *funcName, EGLFuncPointer next)
			```

			For each layer found, the GLES LayerLoader will call `AndroidGLESLayer_Initialize`, and then walk libEGL’s function lists and call `AndroidGLESLayer_GetProcAddress` for all known functions. The layer can track that next address with any means it wants. If the layer does not intercept the function, `AndroidGLESLayer_GetProcAddress` must return the same function address it was passed. The LayerLoader will then update the function hook list to point to the layer’s entrypoint.

			The layers are not required to do anything with the info provided by `AndroidGLESLayer_Initialize` or get_next_layer_proc_address, but providing them makes it easier for existing layers (like GAPID and RenderDoc) to support Android. That way a layer can look up functions independently (i.e. not wait for calls to `AndroidGLESLayer_GetProcAddress`). Layers must be sure to use gen_next_layer_proc_address if they look up function calls instead of eglGetProcAddress or they will not get an accurate answer. eglGetProcAddress must be passed down the chain to the platform.

			## Placing layers

			Where layers can be found, in order of priority
			1. System location for root
			This requires root access
			```bash
			adb root
			adb disable-verity
			adb reboot
			adb root
			adb shell setenforce 0
			adb shell mkdir -p /data/local/debug/gles
			adb push <layer>.so /data/local/debug/gles/
			```

			2. Application's base directory
			Target application must be debuggable, or you must have root access:
			```bash
			adb push libGLTrace.so /data/local/tmp
			adb shell run-as com.android.gl2jni cp /data/local/tmp/libGLTrace.so .
			adb shell run-as com.android.gl2jni ls \| grep libGLTrace
			libGLTrace.so
			```

			3. External APK
			Determine the ABI of your target application, then install an APK containing the layers you wish to load:
			```bash
			adb install --abi armeabi-v7a layers.apk
			```

			4. In the target application's APK

			## Enabling layers

			### Per application
			Note these settings will persist across reboots:
			```bash
			# Enable layers
			adb shell settings put global enable_gpu_debug_layers 1

			# Specify target application
			adb shell settings put global gpu_debug_app <package_name>

			# Specify layer list (from top to bottom)
			adb shell settings put global gpu_debug_layers_gles <layer1:layer2:layerN>

			# Specify a package to search for layers
			adb shell settings put global gpu_debug_layer_app <layer_package>
			```
			To disable the per-app layers:
			```
			adb shell settings delete global enable_gpu_debug_layers
			adb shell settings delete global gpu_debug_app
			adb shell settings delete global gpu_debug_layers_gles
			adb shell settings delete global gpu_debug_layer_app
			```

			### Globally
			These will be cleared on reboot:
			```bash
			# This will attempt to load layers for all applications, including native executables
			adb shell setprop debug.gles.layers <layer1:layer2:layerN>
			```


			## Creating a layer

			Layers must expose the following two functions described above:
			```cpp
			AndroidGLESLayer_Initialize
			AndroidGLESLayer_GetProcAddress
			```

			For a simple layer that just wants to intercept a handful of functions, a passively initialized layer is the way to go. It can simply wait for the EGL Loader to initialize the function it cares about. See below for an example of creating a passive layer.

			For more formalized layers that need to fully initialize up front, or layers that needs to look up extensions not known to the EGL loader, active layer initialization is the way to go. The layer can utilize get_next_layer_proc_address provided by `AndroidGLESLayer_Initialize` to look up a function at any time. The layer must still respond to `AndroidGLESLayer_GetProcAddress` requests from the loader so the platform knows where to route calls. See below for an example of creating an active layer.

			### Example Passive Layer Initialization
			```cpp
			namespace {

			std::unordered_map<std::string, EGLFuncPointer> funcMap;

			EGLAPI EGLBoolean EGLAPIENTRY glesLayer_eglChooseConfig (
			EGLDisplay dpy, const EGLint attrib_list, EGLConfig configs, EGLint config_size,
			EGLint *num_config) {

			EGLFuncPointer entry = funcMap["eglChooseConfig"];

			typedef EGLBoolean (*PFNEGLCHOOSECONFIGPROC)(
			EGLDisplay, const EGLint, EGLConfig, EGLint, EGLint*);

			PFNEGLCHOOSECONFIGPROC next = reinterpret_cast<PFNEGLCHOOSECONFIGPROC>(entry);

			return next(dpy, attrib_list, configs, config_size, num_config);
			}

			EGLAPI EGLFuncPointer EGLAPIENTRY eglGPA(const char* funcName) {

			#define GETPROCADDR(func) if(!strcmp(funcName, #func)) { \
			return (EGLFuncPointer)glesLayer_##func; }

			GETPROCADDR(eglChooseConfig);

			// Don't return anything for unrecognized functions
			return nullptr;
			}

			EGLAPI void EGLAPIENTRY glesLayer_InitializeLayer(
			void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
			// This function is purposefully empty, since this layer does not proactively
			// look up any entrypoints
			}

			EGLAPI EGLFuncPointer EGLAPIENTRY glesLayer_GetLayerProcAddress(
			const char* funcName, EGLFuncPointer next) {
			EGLFuncPointer entry = eglGPA(funcName);
			if (entry != nullptr) {
			funcMap[std::string(funcName)] = next;
			return entry;
			}
			return next;
			}

			} // namespace

			extern "C" {
			__attribute((visibility("default"))) EGLAPI void AndroidGLESLayer_Initialize(
			void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
			return (void)glesLayer_InitializeLayer(layer_id, get_next_layer_proc_address);
			}
			__attribute((visibility("default"))) EGLAPI void* AndroidGLESLayer_GetProcAddres(
			const char *funcName, EGLFuncPointer next) {
			return (void*)glesLayer_GetLayerProcAddress(funcName, next);
			}
			}
			```

			### Example Active Layer Initialization
			```cpp
			namespace {

			std::unordered_map<std::string, EGLFuncPointer> funcMap;

			EGLAPI EGLBoolean EGLAPIENTRY glesLayer_eglChooseConfig (
			EGLDisplay dpy, const EGLint attrib_list, EGLConfig configs, EGLint config_size,
			EGLint *num_config) {

			EGLFuncPointer entry = funcMap["eglChooseConfig"];

			typedef EGLBoolean (*PFNEGLCHOOSECONFIGPROC)(
			EGLDisplay, const EGLint, EGLConfig, EGLint, EGLint*);

			PFNEGLCHOOSECONFIGPROC next = reinterpret_cast<PFNEGLCHOOSECONFIGPROC>(entry);

			return next(dpy, attrib_list, configs, config_size, num_config);
			}

			EGLAPI EGLFuncPointer EGLAPIENTRY eglGPA(const char* funcName) {

			#define GETPROCADDR(func) if(!strcmp(funcName, #func)) { \
			return (EGLFuncPointer)glesLayer_##func; }

			GETPROCADDR(eglChooseConfig);

			// Don't return anything for unrecognized functions
			return nullptr;
			}

			EGLAPI void EGLAPIENTRY glesLayer_InitializeLayer(
			void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {

			// Note: This is where the layer would populate its function map with all the
			// functions it cares about
			const char* func = “eglChooseConfig”;
			funcMap[func] = get_next_layer_proc_address(layer_id, func);
			}

			EGLAPI EGLFuncPointer EGLAPIENTRY glesLayer_GetLayerProcAddress(
			const char* funcName, EGLFuncPointer next) {
			EGLFuncPointer entry = eglGPA(funcName);
			if (entry != nullptr) {
			return entry;
			}

			return next;
			}

			} // namespace

			extern "C" {
			__attribute((visibility("default"))) EGLAPI void AndroidGLESLayer_Initialize(
			void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
			return (void)glesLayer_InitializeLayer(layer_id, get_next_layer_proc_address);
			}
			__attribute((visibility("default"))) EGLAPI void* AndroidGLESLayer_GetProcAddres(
			const char *funcName, EGLFuncPointer next) {
			return (void*)glesLayer_GetLayerProcAddress(funcName, next);
			}
			}
			```

			## Caveats
			Only supports GLES 2.0+.

			When layering is enabled, GLES 1.x exclusive functions will continue to route to GLES 1.x drivers. But functions shared with GLES 2.0+ (like glGetString) will be routed to 2.0+ drivers, which can cause confusion.

			## FAQ
			- Who can use layers?
			- GLES Layers can be loaded by any debuggable application, or for any application if you have root access
			- How do we know if layers are working on a device?
			- This feature is backed by Android CTS, so you can run `atest CtsGpuToolsHostTestCases`
			- How does a app determine if this feature is supported?
			- There are two ways. First you can check against the version of Android.
			```bash
			# Q is the first that will support this, so look for `Q` or 10 for release
			adb shell getprop ro.build.version.sdk
			# Or look for the SDK version, which should be 29 for Q
			adb shell getprop ro.build.version.sdk
			```
			- Secondly, if you want to determine from an application that can't call out to ADB for this, you can check for the [EGL_ANDROID_GLES_layers](../../specs/EGL_ANDROID_GLES_layers.txt). It simply indicates support of this layering system:
			```cpp
			std::string display_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS);
			if (display_extension.find("EGL_ANDROID_GLES_layers") != std::string::npos)
			{
			// Layers are supported!
			}
			```

opengl/libs/EGL/egl_layers.cpp

+21 −13

Original line number	Original line	Diff line number	Diff line
	@@ -37,9 +37,8 @@ namespace android {
	// 2. If none enabled, check system properties		// 2. If none enabled, check system properties
	//		//
	// - Layer initializing -		// - Layer initializing -
	// TODO: ADD DETAIL ABOUT NEW INTERFACES		// - AndroidGLESLayer_Initialize (provided by layer, called by loader)
	// - InitializeLayer (provided by layer, called by loader)		// - AndroidGLESLayer_GetProcAddress (provided by layer, called by loader)
	// - GetLayerProcAddress (provided by layer, called by loader)
	// - getNextLayerProcAddress (provided by loader, called by layer)		// - getNextLayerProcAddress (provided by loader, called by layer)
	//		//
	// 1. Walk through defs for egl and each gl version		// 1. Walk through defs for egl and each gl version
	@@ -73,27 +72,30 @@ std::vector<FunctionTable> layer_functions;

	const void* getNextLayerProcAddress(void* layer_id, const char* name) {		const void* getNextLayerProcAddress(void* layer_id, const char* name) {
	// Use layer_id to find funcs for layer below current		// Use layer_id to find funcs for layer below current
	// This is the same key provided in InitializeLayer		// This is the same key provided in AndroidGLESLayer_Initialize
	auto next_layer_funcs = reinterpret_cast<FunctionTable*>(layer_id);		auto next_layer_funcs = reinterpret_cast<FunctionTable*>(layer_id);
	EGLFuncPointer val;		EGLFuncPointer val;

			ALOGV("getNextLayerProcAddress servicing %s", name);

	if (func_indices.find(name) == func_indices.end()) {		if (func_indices.find(name) == func_indices.end()) {
	// No entry for this function - it is an extension		// No entry for this function - it is an extension
	// call down the GPA chain directly to the impl		// call down the GPA chain directly to the impl
	ALOGV("getNextLayerProcAddress servicing %s", name);		ALOGV("getNextLayerProcAddress - name(%s) no func_indices entry found", name);

	// Look up which GPA we should use		// Look up which GPA we should use
	int gpaIndex = func_indices["eglGetProcAddress"];		int gpaIndex = func_indices["eglGetProcAddress"];
			ALOGV("getNextLayerProcAddress - name(%s) gpaIndex(%i) <- using GPA from this index", name, gpaIndex);
	EGLFuncPointer gpaNext = (*next_layer_funcs)[gpaIndex];		EGLFuncPointer gpaNext = (*next_layer_funcs)[gpaIndex];
			ALOGV("getNextLayerProcAddress - name(%s) gpaIndex(%i) gpaNext(%llu) <- using GPA at this address", name, gpaIndex, (unsigned long long)gpaNext);

	ALOGV("Calling down the GPA chain (%llu) for %s", (unsigned long long)gpaNext, name);

	// Call it for the requested function		// Call it for the requested function
	typedef void* (PFNEGLGETPROCADDRESSPROC)(const char);		typedef void* (PFNEGLGETPROCADDRESSPROC)(const char);
	PFNEGLGETPROCADDRESSPROC next = reinterpret_cast<PFNEGLGETPROCADDRESSPROC>(gpaNext);		PFNEGLGETPROCADDRESSPROC next = reinterpret_cast<PFNEGLGETPROCADDRESSPROC>(gpaNext);

	val = reinterpret_cast<EGLFuncPointer>(next(name));		val = reinterpret_cast<EGLFuncPointer>(next(name));
	ALOGV("Got back %llu for %s", (unsigned long long)val, name);		ALOGV("getNextLayerProcAddress - name(%s) gpaIndex(%i) gpaNext(%llu) Got back (%llu) from GPA", name, gpaIndex, (unsigned long long)gpaNext, (unsigned long long)val);

	// We should store it now, but to do that, we need to move func_idx to the class so we can		// We should store it now, but to do that, we need to move func_idx to the class so we can
	// increment it separately		// increment it separately
	@@ -101,10 +103,10 @@ const void* getNextLayerProcAddress(void* layer_id, const char* name) {
	return reinterpret_cast<void*>(val);		return reinterpret_cast<void*>(val);
	}		}

	// int index = func_indices[name];		int index = func_indices[name];
	// val = (*next_layer_funcs)[index];		val = (*next_layer_funcs)[index];
	// return reinterpret_cast<void*>(val);		ALOGV("getNextLayerProcAddress - name(%s) index(%i) entry(%llu) - Got a hit, returning known entry", name, index, (unsigned long long)val);
	return reinterpret_cast<void>((next_layer_funcs)[func_indices[name]]);		return reinterpret_cast<void*>(val);
	}		}

	void SetupFuncMaps(FunctionTable& functions, char const* const* entries, EGLFuncPointer* curr,		void SetupFuncMaps(FunctionTable& functions, char const* const* entries, EGLFuncPointer* curr,
	@@ -115,14 +117,20 @@ void SetupFuncMaps(FunctionTable& functions, char const* const* entries, EGLFunc
	// Some names overlap, only fill with initial entry		// Some names overlap, only fill with initial entry
	// This does mean that some indices will not be used		// This does mean that some indices will not be used
	if (func_indices.find(name) == func_indices.end()) {		if (func_indices.find(name) == func_indices.end()) {
			ALOGV("SetupFuncMaps - name(%s), func_idx(%i), No entry for func_indices, assigning now", name, func_idx);
	func_names[func_idx] = name;		func_names[func_idx] = name;
	func_indices[name] = func_idx;		func_indices[name] = func_idx;
			} else {
			ALOGV("SetupFuncMaps - name(%s), func_idx(%i), Found entry for func_indices", name, func_idx);
	}		}

	// Populate layer_functions once with initial value		// Populate layer_functions once with initial value
	// These values will arrive in priority order, starting with platform entries		// These values will arrive in priority order, starting with platform entries
	if (functions[func_idx] == nullptr) {		if (functions[func_idx] == nullptr) {
			ALOGV("SetupFuncMaps - name(%s), func_idx(%i), No entry for functions, assigning (%llu)", name, func_idx, (unsigned long long) *curr);
	functions[func_idx] = *curr;		functions[func_idx] = *curr;
			} else {
			ALOGV("SetupFuncMaps - name(%s), func_idx(%i), Found entry for functions (%llu)", name, func_idx, (unsigned long long) functions[func_idx]);
	}		}

	entries++;		entries++;
	@@ -400,7 +408,7 @@ void LayerLoader::LoadLayers() {
	}		}

	// Find the layer's Initialize function		// Find the layer's Initialize function
	std::string init_func = "InitializeLayer";		std::string init_func = "AndroidGLESLayer_Initialize";
	ALOGV("Looking for entrypoint %s", init_func.c_str());		ALOGV("Looking for entrypoint %s", init_func.c_str());

	layer_init_func LayerInit =		layer_init_func LayerInit =
	@@ -414,7 +422,7 @@ void LayerLoader::LoadLayers() {
	}		}

	// Find the layer's setup function		// Find the layer's setup function
	std::string setup_func = "GetLayerProcAddress";		std::string setup_func = "AndroidGLESLayer_GetProcAddress";
	ALOGV("Looking for entrypoint %s", setup_func.c_str());		ALOGV("Looking for entrypoint %s", setup_func.c_str());

	layer_setup_func LayerSetup =		layer_setup_func LayerSetup =

opengl/libs/EGL/egl_platform_entries.cpp

+2 −1

Original line number	Original line	Diff line number	Diff line
	@@ -139,7 +139,8 @@ char const * const gExtensionString =
	char const * const gClientExtensionString =		char const * const gClientExtensionString =
	"EGL_EXT_client_extensions "		"EGL_EXT_client_extensions "
	"EGL_KHR_platform_android "		"EGL_KHR_platform_android "
	"EGL_ANGLE_platform_angle";		"EGL_ANGLE_platform_angle "
			"EGL_ANDROID_GLES_layers";
	// clang-format on		// clang-format on

	// extensions not exposed to applications but used by the ANDROID system		// extensions not exposed to applications but used by the ANDROID system

opengl/specs/EGL_ANDROID_GLES_layers.txt

0 → 100644

+64 −0

Original line number	Original line	Diff line number	Diff line
			Name

			ANDROID_GLES_layers

			Name Strings

			EGL_ANDROID_GLES_layers

			Contributors

			Cody Northrop

			Contact

			Cody Northrop, Google LLC (cnorthrop 'at' google.com)

			Status

			Draft

			Version

			Version 1, March 3, 2019

			Number

			EGL Extension #132

			Extension Type

			EGL client extension

			Dependencies

			Requires EGL 1.5 or EGL_EXT_client_extensions

			Overview

			This extension indicates the EGL loader supports GLES layering on Android.
			It does not add any requirements to drivers or hardware.

			See frameworks/native/opengl/libs/EGL/GLES_layers.md in Android for
			more information.

			New Types

			None

			New Procedures and Functions

			None

			New Tokens

			None

			Issues

			None

			Revision History

			#1 (Cody Northrop, March 3, 2019)
			- Initial draft.