Vulkan: add docs for the framework generation scripts
Bug: 134185757
Test: ./scripts/code_generator.py && build
Change-Id: I108412fdc672c5513f570ddac9221074a0027cd0
diff --git a/vulkan/scripts/api_generator.py b/vulkan/scripts/api_generator.py
index d1fff42..7c39075 100644
--- a/vulkan/scripts/api_generator.py
+++ b/vulkan/scripts/api_generator.py
@@ -13,13 +13,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the functions required for generating the
-# vulkan api framework directly from the vulkan registry (vk.xml)
+
+"""Generates the api_gen.h and api_gen.cpp.
+"""
import os
import generator_common as gencom
+# Functions intercepted at vulkan::api level.
_INTERCEPTED_COMMANDS = [
'vkCreateDevice',
'vkDestroyDevice',
@@ -30,6 +31,8 @@
def gen_h():
+ """Generates the api_gen.h file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'api_gen.h')
@@ -100,6 +103,12 @@
def _define_extension_stub(cmd, f):
+ """Emits a stub for an exported extension function.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
if (cmd in gencom.extension_dict and gencom.is_function_exported(cmd)):
ext_name = gencom.extension_dict[cmd]
ret = gencom.return_type_dict[cmd]
@@ -121,6 +130,11 @@
def _is_intercepted(cmd):
+ """Returns true if a function is intercepted by vulkan::api.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if gencom.is_function_supported(cmd):
if gencom.is_globally_dispatched(cmd) or cmd in _INTERCEPTED_COMMANDS:
return True
@@ -128,6 +142,11 @@
def _intercept_instance_proc_addr(f):
+ """Emits code for vkGetInstanceProcAddr for function interception.
+
+ Args:
+ f: Output file handle.
+ """
f.write("""\
// global functions
if (instance == VK_NULL_HANDLE) {\n""")
@@ -180,6 +199,11 @@
def _intercept_device_proc_addr(f):
+ """Emits code for vkGetDeviceProcAddr for function interception.
+
+ Args:
+ f: Output file handle.
+ """
f.write("""\
if (device == VK_NULL_HANDLE) {
ALOGE("invalid vkGetDeviceProcAddr(VK_NULL_HANDLE, ...) call");
@@ -220,6 +244,12 @@
def _api_dispatch(cmd, f):
+ """Emits code to dispatch a function.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
assert not _is_intercepted(cmd)
f.write(gencom.indent(1))
@@ -233,6 +263,8 @@
def gen_cpp():
+ """Generates the api_gen.cpp file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'api_gen.cpp')
diff --git a/vulkan/scripts/code_generator.py b/vulkan/scripts/code_generator.py
index 378a9c0..2a017d2 100755
--- a/vulkan/scripts/code_generator.py
+++ b/vulkan/scripts/code_generator.py
@@ -13,9 +13,9 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the main function for generating
-# vulkan framework directly from the vulkan registry (vk.xml).
+
+"""Generates vulkan framework directly from the vulkan registry (vk.xml).
+"""
import api_generator
import driver_generator
diff --git a/vulkan/scripts/driver_generator.py b/vulkan/scripts/driver_generator.py
index 5fff83e..1f3fd8e 100644
--- a/vulkan/scripts/driver_generator.py
+++ b/vulkan/scripts/driver_generator.py
@@ -13,13 +13,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the functions for generating the
-# vulkan driver framework directly from the vulkan registry (vk.xml).
+
+"""Generates the driver_gen.h and driver_gen.cpp.
+"""
import os
import generator_common as gencom
+# Extensions intercepted at vulkan::driver level.
_INTERCEPTED_EXTENSIONS = [
'VK_ANDROID_native_buffer',
'VK_EXT_debug_report',
@@ -34,12 +35,14 @@
'VK_KHR_swapchain',
]
+# Extensions known to vulkan::driver level.
_KNOWN_EXTENSIONS = _INTERCEPTED_EXTENSIONS + [
'VK_ANDROID_external_memory_android_hardware_buffer',
'VK_KHR_bind_memory2',
'VK_KHR_get_physical_device_properties2',
]
+# Functions needed at vulkan::driver level.
_NEEDED_COMMANDS = [
# Create functions of dispatchable objects
'vkCreateDevice',
@@ -76,6 +79,7 @@
'vkBindImageMemory2KHR',
]
+# Functions intercepted at vulkan::driver level.
_INTERCEPTED_COMMANDS = [
# Create functions of dispatchable objects
'vkCreateInstance',
@@ -106,6 +110,11 @@
def _is_driver_table_entry(cmd):
+ """Returns true if a function is needed by vulkan::driver.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if gencom.is_function_supported(cmd):
if cmd in _NEEDED_COMMANDS:
return True
@@ -117,16 +126,28 @@
def _is_instance_driver_table_entry(cmd):
+ """Returns true if a instance-dispatched function is needed by vulkan::driver.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return (_is_driver_table_entry(cmd) and
gencom.is_instance_dispatched(cmd))
def _is_device_driver_table_entry(cmd):
+ """Returns true if a device-dispatched function is needed by vulkan::driver.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return (_is_driver_table_entry(cmd) and
gencom.is_device_dispatched(cmd))
def gen_h():
+ """Generates the driver_gen.h file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'driver_gen.h')
@@ -214,6 +235,11 @@
def _is_intercepted(cmd):
+ """Returns true if a function is intercepted by vulkan::driver.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if gencom.is_function_supported(cmd):
if cmd in _INTERCEPTED_COMMANDS:
return True
@@ -224,6 +250,11 @@
def _need_proc_hook_stub(cmd):
+ """Returns true if a function needs a ProcHook stub.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if _is_intercepted(cmd) and gencom.is_device_dispatched(cmd):
if cmd in gencom.extension_dict:
if not gencom.is_extension_internal(gencom.extension_dict[cmd]):
@@ -232,6 +263,12 @@
def _define_proc_hook_stub(cmd, f):
+ """Emits a stub for ProcHook::checked_proc.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
if _need_proc_hook_stub(cmd):
return_type = gencom.return_type_dict[cmd]
ext_name = gencom.extension_dict[cmd]
@@ -259,6 +296,12 @@
def _define_global_proc_hook(cmd, f):
+ """Emits definition of a global ProcHook.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
assert cmd not in gencom.extension_dict
f.write(gencom.indent(1) + '{\n')
@@ -272,6 +315,12 @@
def _define_instance_proc_hook(cmd, f):
+ """Emits definition of a instance ProcHook.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
f.write(gencom.indent(1) + '{\n')
f.write(gencom.indent(2) + '\"' + cmd + '\",\n')
f.write(gencom.indent(2) + 'ProcHook::INSTANCE,\n')
@@ -298,6 +347,12 @@
def _define_device_proc_hook(cmd, f):
+ """Emits definition of a device ProcHook.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
f.write(gencom.indent(1) + '{\n')
f.write(gencom.indent(2) + '\"' + cmd + '\",\n')
f.write(gencom.indent(2) + 'ProcHook::DEVICE,\n')
@@ -326,6 +381,8 @@
def gen_cpp():
+ """Generates the driver_gen.cpp file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'driver_gen.cpp')
diff --git a/vulkan/scripts/generator_common.py b/vulkan/scripts/generator_common.py
index 03993e2..bc37b84 100644
--- a/vulkan/scripts/generator_common.py
+++ b/vulkan/scripts/generator_common.py
@@ -13,14 +13,15 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the common functions for generating the
-# vulkan framework directly from the vulkan registry (vk.xml).
+
+"""Provide the utilities for framework generation.
+"""
import os
import subprocess
import xml.etree.ElementTree as element_tree
+# Extensions unsupported on Android.
_BLACKLISTED_EXTENSIONS = [
'VK_EXT_acquire_xlib_display',
'VK_EXT_direct_mode_display',
@@ -52,6 +53,7 @@
'VK_NVX_image_view_handle',
]
+# Extensions having functions exported by the loader.
_EXPORTED_EXTENSIONS = [
'VK_ANDROID_external_memory_android_hardware_buffer',
'VK_KHR_android_surface',
@@ -59,11 +61,13 @@
'VK_KHR_swapchain',
]
+# Functions optional on Android even if extension is advertised.
_OPTIONAL_COMMANDS = [
'vkGetSwapchainGrallocUsageANDROID',
'vkGetSwapchainGrallocUsage2ANDROID',
]
+# Dict for mapping dispatch table to a type.
_DISPATCH_TYPE_DICT = {
'VkInstance ': 'Instance',
'VkPhysicalDevice ': 'Instance',
@@ -72,19 +76,40 @@
'VkCommandBuffer ': 'Device'
}
+# Dict for mapping a function to its alias.
alias_dict = {}
+
+# List of all the Vulkan functions.
command_list = []
+
+# Dict for mapping a function to an extension.
extension_dict = {}
+
+# Dict for mapping a function to all its parameters.
param_dict = {}
+
+# Dict for mapping a function to its return type.
return_type_dict = {}
+
+# Dict for mapping a function to the core Vulkan API version.
version_dict = {}
def indent(num):
+ """Returns the requested indents.
+
+ Args:
+ num: Number of the 4-space indents.
+ """
return ' ' * num
def copyright_and_warning(year):
+ """Returns the standard copyright and warning codes.
+
+ Args:
+ year: An integer year for the copyright.
+ """
return """\
/*
* Copyright """ + str(year) + """ The Android Open Source Project
@@ -108,19 +133,41 @@
def run_clang_format(args):
+ """Run clang format on the file.
+
+ Args:
+ args: The file to be formatted.
+ """
clang_call = ['clang-format', '--style', 'file', '-i', args]
subprocess.check_call(clang_call)
def is_extension_internal(extension_name):
+ """Returns true if an extension is internal to the loader and drivers.
+
+ The loader should not enumerate this extension.
+
+ Args:
+ extension_name: Vulkan extension name.
+ """
return extension_name == 'VK_ANDROID_native_buffer'
def base_name(cmd):
+ """Returns a function name without the 'vk' prefix.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return cmd[2:]
def is_function_supported(cmd):
+ """Returns true if a function is core or from a supportable extension.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if cmd not in extension_dict:
return True
else:
@@ -130,6 +177,11 @@
def get_dispatch_table_type(cmd):
+ """Returns the dispatch table type for a function.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if cmd not in param_dict:
return None
@@ -139,23 +191,55 @@
def is_globally_dispatched(cmd):
+ """Returns true if the function is global, which is not dispatched.
+
+ Only global functions and functions handled in the loader top without calling
+ into lower layers are not dispatched.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return is_function_supported(cmd) and get_dispatch_table_type(cmd) == 'Global'
def is_instance_dispatched(cmd):
+ """Returns true for functions that can have instance-specific dispatch.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return (is_function_supported(cmd) and
get_dispatch_table_type(cmd) == 'Instance')
def is_device_dispatched(cmd):
+ """Returns true for functions that can have device-specific dispatch.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return is_function_supported(cmd) and get_dispatch_table_type(cmd) == 'Device'
def is_extension_exported(extension_name):
+ """Returns true if an extension has functions exported by the loader.
+
+ E.g. applications can directly link to an extension function.
+
+ Args:
+ extension_name: Vulkan extension name.
+ """
return extension_name in _EXPORTED_EXTENSIONS
def is_function_exported(cmd):
+ """Returns true if a function is exported from the Android Vulkan library.
+
+ Functions in the core API and in loader extensions are exported.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if is_function_supported(cmd):
if cmd in extension_dict:
return is_extension_exported(extension_dict[cmd])
@@ -164,6 +248,11 @@
def is_instance_dispatch_table_entry(cmd):
+ """Returns true if a function is exported and instance-dispatched.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if cmd == 'vkEnumerateDeviceLayerProperties':
# deprecated, unused internally - @dbd33bc
return False
@@ -171,10 +260,21 @@
def is_device_dispatch_table_entry(cmd):
+ """Returns true if a function is exported and device-dispatched.
+
+ Args:
+ cmd: Vulkan function name.
+ """
return is_function_exported(cmd) and is_device_dispatched(cmd)
def init_proc(name, f):
+ """Emits code to invoke INIT_PROC or INIT_PROC_EXT.
+
+ Args:
+ name: Vulkan function name.
+ f: Output file handle.
+ """
f.write(indent(1))
if name in extension_dict:
f.write('INIT_PROC_EXT(' + extension_dict[name][3:] + ', ')
@@ -197,6 +297,15 @@
def parse_vulkan_registry():
+ """Parses Vulkan registry into the below global variables.
+
+ alias_dict
+ command_list
+ extension_dict
+ param_dict
+ return_type_dict
+ version_dict
+ """
registry = os.path.join(os.path.dirname(__file__), '..', '..', '..', '..',
'external', 'vulkan-headers', 'registry', 'vk.xml')
tree = element_tree.parse(registry)
diff --git a/vulkan/scripts/null_generator.py b/vulkan/scripts/null_generator.py
index 2a99a1d..e9faef6 100644
--- a/vulkan/scripts/null_generator.py
+++ b/vulkan/scripts/null_generator.py
@@ -13,13 +13,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the functions for generating the null driver
-# framework directly from the vulkan registry (vk.xml).
+
+"""Generates the null_driver_gen.h and null_driver_gen.cpp.
+"""
import os
import generator_common as gencom
+# Extensions implemented by the driver.
_DRIVER_EXTENSION_DICT = {
'VK_ANDROID_native_buffer',
'VK_EXT_debug_report',
@@ -28,12 +29,19 @@
def _is_driver_function(cmd):
+ """Returns true if the function is implemented by the driver.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if cmd in gencom.extension_dict:
return gencom.extension_dict[cmd] in _DRIVER_EXTENSION_DICT
return True
def gen_h():
+ """Generates the null_driver_gen.h file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'nulldrv', 'null_driver_gen.h')
@@ -72,6 +80,8 @@
def gen_cpp():
+ """Generates the null_driver_gen.cpp file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'nulldrv', 'null_driver_gen.cpp')