OpenVX ICD Extension  76df2d2
 All Functions Typedefs Groups Pages
The OpenVX Installable Client Driver Loader Extension

Overview

The vx_khr_icd extension defines a simple mechanism through which the Khronos installable client driver loader (ICD Loader) may expose multiple separate vendor installable client drivers (Vendor ICDs) for OpenVX. An application written against the ICD Loader will be able to access all vx_platform exposed by all vendor implementations with the ICD Loader acting as a demultiplexer.

Dependencies

OpenVX 1.0.1 or later

External Interface

The ICD Loader interface can be accessed by application using:

#include <VX/vx_khr_icd.h>

The VX/vx_khr_icd.h includes definition of a new object vx_platform and new functions vxIcdGetPlatforms, vxQueryPlatform, vxCreateContextFromPlatform. An ICD compatible vendor implementation is required to implement the function vxCreateContextFromPlatform. And the implementation of vxIcdGetPlatforms, vxQueryPlatform, and struct _vx_platform will be part of ICD Loader source. See OpenVX ICD Loader API for further details.

Inferring Vendor ICD Calls from Arguments

At every OpenVX function call, the ICD Loader infers the Vendor ICD function to call from the ICD compatible object that is passed as the first argument. All OpenVX objects are said to be ICD compatible if the struct _vx_reference contains a placeholder for vx_platform as it’s first field, as shown below:

struct _vx_reference {
struct _vx_platform * platform;
// ... remainder of internal data
};

The structure _vx_platform has a function pointer dispatch table which is used to make direct calls to a particular vendor implementation. All objects created from ICD compatible objects must be ICD compatible.

Functions which do not take ICD compatible object or a pointer to ICD compatible object as it’s first argument needs to be implemented by ICD Loader. The OpenVX functions that are required for an implementation in ICD Loader source are:

void * VX_API_CALL vxFormatImagePatchAddress1d(void *ptr, vx_uint32 index, const vx_imagepatch_addressing_t *addr);
void * VX_API_CALL vxFormatImagePatchAddress2d(void *ptr, vx_uint32 index, const vx_imagepatch_addressing_t *addr);
vx_context VX_API_CALL vxCreateContext();

The ICD Loader’s vxCreateContext implementation is required to pick the default platform and to call the vendor specific implementation of vxCreateContextFromPlatform.

The ICD Loader’s vxHint implementation is required to check the OpenVX version of the vendor implementation and handle function signature changes between OpenVX 1.0.1 and OpenVX 1.1.

Vendor Enumerations on Linux

To enumerate vendor ICDs on Linux, the ICD Loader scans the files under /etc/OpenVX/vendors. For each file in this path, the ICD Loader opens the file as a text file. The expected format for the file is a single line of text which specifies the Vendor ICD’s library. If the Vendor ICD comes with a separate library for immediate mode functions (VXU), the expected format for the file is a single line of text with OpenVX and VXU libraries separated by semi-colon(;) in that order.

The ICD Loader will attempt to open that file as a shared object using dlopen(). Note that the library specified may be an absolute path or just a file name.
EXAMPLE

If the following file exists
/etc/OpenVX/vendors/VendorA.icd
and contains the text
libopenvx.so;libvxu.so
then the ICD Loader will load the libraries "libopenvx.so" and "libvxu.so"

Vendor Enumerations on Android

To enumerate vendor ICDs on Android, the ICD Loader scans the files under /system/vendor/Khronos/OpenVX/vendors/. For each file in this path, the ICD Loader opens the file as a text file. The expected format for the file is a single line of text which specifies the Vendor ICD’s library. If the Vendor ICD comes with a separate library for immediate mode functions (VXU), the expected format for the file is a single line of text with OpenVX and VXU libraries separated by semi-colon(;) in that order.

The ICD Loader will attempt to open that file as a shared object using dlopen(). Note that the library specified may be an absolute path or just a file name.
EXAMPLE

If the following file exists
/system/vendor/Khronos/OpenVX/vendors/VendorA.icd
and contains the text
libopenvx.so
then the ICD Loader will load the library "libopenvx.so"

Vendor Enumerations on Windows

To enumerate Vendor ICDs on Windows, the ICD Loader scans the values in the registry key HKEY_LOCAL_MACHINE. For each value in this key which has DWORD data set to 0, the ICD Loader opens the dynamic link library specified by the name of the value using LoadLibraryA. If the Vendor ICD comes with a separate library for immediate mode functions (VXU), the expected format for the name of the value is a single line of text with OpenVX and VXU libraries separated by semi-colon(;) in that order.
EXAMPLE

If the registry contains the following value
[HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenVX\Vendors]
"c:\\vendor_a\\openvx.dll;c:\\vendor_a\\vxu.dll"=dword:00000000
then the ICD will open the libraries "c:\vendor_a\openvx.dll" and "c:\vendor_a\vxu.dll"

ICD Compatible Khronos Sample Implementation

To make the sample implementation compatible with ICD implementation, the following two changes are required:

1. Add "struct _vx_platform * platform;" as first field to "struct _vx_reference"
2. Every derived reference should copy "platform" from it's parent:
add "ref->platform = context ? context->base.platform : NULL;" statement to vxInitReference()
3. Create a new vxCreateContextFromPlatform() which initializes context->base.platform with
the function argument and performs same functionality as vxCreateContext().

Sample Implementation of ICD Loader

An implementation of ICD Loader is available in vx_khr_icd folder of sample implementation tree. Use cmake to build ICD Loader library to a static library with the name “openvx”. Applications that use ICD Loader library can use any ICD compatible vendor implementation picked during run-time.
Example: Build and Run Conformance Tests using ICD Loader

# Build ICD Loader sample implementation from vx_khr_icd folder
% pushd <path-to-sample-implementation-trunk>
% export OPENVX_DIR=$PWD
% popd
% mkdir -p build/vx_khr_icd
% cd build/vx_khr_icd
% cmake $OPENVX_DIR/vx_khr_icd
% make
% export VX_KHR_ICD_LIB=$PWD
% cd ../..
# Build OpenVX Conformance Tests using ICD Loader
% mkdir -p build/conformance_tests
% cd build/conformance_tests
% cmake -DOPENVX_INCLUDES=$OPENVX_DIR/include \
-DOPENVX_LIBRARIES=$VX_KHR_ICD_LIB/libopenvx.a\;pthread\;dl\;m \
$OPENVX_DIR/conformance_tests
% make
# Run Conformance Tests
# Note: use of sample implementation requires LD_LIBRARY_PATH to be set properly
% export VX_TEST_DATA_PATH=$OPENVX_DIR/conformance_tests/test_data
% <build binary path>/vx_test_conformance

Updates to ICD Loader source code

The sample implementation tree has a python script vx_khr_icd/vx_khr_icd.py to update ICD Loader source code from OpenVX header files in include/VX folder.

# To update vx_dispatch.h, vx_dispatch.c, and ../include/VX/vx_khr_icd.h files
# with the API in VX/vx_api.h, VX/vx_nodes.h, VX/vxu.h, and VX/vx_compatibility.h,
# run below command from vx_khr_icd folder
% python vx_khr_icd.py \
../include/VX/vx_api.h ../include/VX/vx_nodes.h \
../include/VX/vxu.h \
../include/VX/vx_compatibility.h
# To create ICD Loader source code for OpenVX 1.0.1:
# - unzip extract openvx_sample_1.0.1.tar.bz2 in openvx_sample folder
# - copy vx_khr_icd folder into openvx_sample folder
# - run below command from openvx_sample/vx_khr_icd folder
% python vx_khr_icd.py
../include/VX/vx_api.h ../include/VX/vx_nodes.h \
../include/VX/vxu.h

Contributors