|
24.07
|
|
24.07
|
The Compute Library is a collection of low level algorithm implementations known as kernels IKernel. These kernels are implemented as operators IOperator that do not allocate any memory (i.e. all the memory allocations/mappings have to be handled by the caller) and are are designed to be embedded in existing projects and applications.
A higher-level interface wraps the operators into functions IFunction that:
For maximum performance, it is expected that the users would re-implement an equivalent to the function interface which suits better their needs (With a more clever multi-threading strategy, load-balancing between Arm® Neon™ and OpenCL, etc.)
Compute Library supports different types of convolution methods, fast-math flag is only used for the Winograd algorithm. When the fast-math flag is enabled, both Arm® Neon™ and CL convolution layers will try to dispatch the fastest implementation available, which may introduce a drop in accuracy as well. The different scenarios involving the fast-math flag are presented below:
Required toolchain: android-ndk-r23-beta5 or later.
To build for BF16: "neon" flag should be set "=1" and "arch" has to be "=armv8.6-a", "=armv8.6-a-sve", or "=armv8.6-a-sve2". For example:
scons arch=armv8.6-a-sve neon=1 opencl=0 extra_cxx_flags="-fPIC" benchmark_tests=0 validation_tests=0 examples=1 os=android Werror=0 toolchain_prefix=aarch64-linux-android29
To enable BF16 acceleration when running FP32 "fast-math" has to be enabled and that works only for Neon convolution layer using cpu gemm. In this scenario on CPU: the CpuGemmConv2d kernel performs the conversion from FP32, type of input tensor, to BF16 at block level to exploit the arithmetic capabilities dedicated to BF16. Then transforms back to FP32, the output tensor type.
Although the library supports multi-threading during workload dispatch, thus parallelizing the execution of the workload at multiple threads, the current runtime module implementation is not thread-safe in the sense of executing different functions from separate threads. This lies to the fact that the provided scheduling mechanism wasn't designed with thread-safety in mind. As it is true with the rest of the runtime library a custom scheduling mechanism can be re-implemented to account for thread-safety if needed and be injected as the library's default scheduler.
All computer vision algorithms in this library have been implemented following the OpenVX 1.1 specifications. Please refer to the Khronos documentation for more information.
Most kernels and functions in the library process images, however, in order to be future proof most of the kernels actually accept tensors. See below for more information about how they are related.
Several algorithms require a neighborhood around the current pixel to compute it's value. This means the algorithm will not be able to process the borders of the image unless you give it more information about how those border pixels should be processed. The BorderMode enum is used for this purpose.
You have 3 types of BorderMode :
Moreover both OpenCL and Arm® Neon™ use vector loads and stores instructions to access the data in buffers, so in order to avoid having special cases to handle for the borders all the images and tensors used in this library must be padded.
There are different ways padding can be calculated:
The full example is provided in examples/neon_scale.cpp
Some kernels (like edge detectors for example) need to read values of neighboring pixels to calculate the value of a given pixel, it is therefore not possible to calculate the values of the pixels on the edges.
Another case is: if a kernel processes 8 pixels per iteration and the image's dimensions are not a multiple of 8 and not enough padding is available then the kernel will not be able to process the pixels near the right edge. As a result these pixels will be left undefined.
In order to know which pixels have been calculated, each kernel sets a valid region for each output image or tensor. See also TensorInfo::valid_region(), ValidRegion
Tensors are multi-dimensional arrays with a maximum of Coordinates::num_max_dimensions dimensions.
Depending on the number of dimensions tensors can be interpreted as various objects. A scalar can be represented as a zero-dimensional tensor and a vector of numbers can be represented as an one-dimensional tensor. Further, an image is actually just a 2D tensor, a 3D tensor can be seen as an array of images and a 4D tensor as a 2D array of images, etc.
Image objects are defined by a Format and dimensions expressed as [width, height, batch]
Tensors are defined by a DataType plus a number of channels (Always expected to be 1 for now) and their dimensions are expressed as [width, height, feature_maps, batch].
In other words, the lower three dimensions of a tensor specify a single input in [width, height, feature_maps], while any other specified dimension represents a batch in the appropriate dimension space. For example, a tensor with dimensions [128, 128, 64, 16] represents a 1D batch space with 16 batches of 128 elements in width and height and 64 feature maps each. Each kernel specifies the expected layout of each of its tensors in its documentation.
For example, to read the element located at the coordinates (x,y) of a float tensor:
The library provides some iterators to access objects' data. Iterators are created by associating a data object (An image or a tensor for example) with an iteration window.
Iteration windows are defined by an array of dimensions, each of which consists of a start, end and step.
The execute_window_loop function takes an execution window, a lambda function and one or more iterators. It will iterate through every element of the execution window and for each element it will update the iterators accordingly and call the lambda function.
Here are a couple of examples of how to use the iterators to fill / read tensors:
Sub-tensors are aliases to existing Tensors, as a result creating a sub-tensor does not result in any underlying memory allocation.
Sub-tensors can be used to access a sub-set of the parent tensor, something that can be useful in case different operations need to be performed on different parts of a tensor.
Moreover, sub-tensors can be used to perform zero copy tensor concatenation.
The API for creating a sub-tensor is the following:
Where parent is the parent tensor which we want to create an alias for, tensor_shape is the shape of the sub-tensor and coords are the starting indexing coordinates of the sub-tensor within the parent tensor.
IMemoryManager is a memory managing interface that can be used to reduce the memory requirements of a given pipeline by recycling temporary buffers.
IMemoryGroup defines the memory managing granularity.
MemoryGroup binds a number of objects to a bucket of memory requirements that need to be fulfilled in order for an operation or list of operations to be executed.
Requesting backing memory for a specific group can be done using IMemoryGroup::acquire and releasing the memory back using IMemoryGroup::release.
IMemoryPool defines a pool of memory that can be used to provide backing memory to a memory group.
IMemoryManager consists of two components:
Using a memory manager to reduce the memory requirements of a pipeline can be summed in the following steps:
Initially a memory manager must be set-up:
Once done, memory groups can be registered to use the memory manager:
Next step is to set objects to be managed by the memory group. It is important though to note that the lifetime of an object is tracked from the MemoryGroup::manage() and the TensorAllocator::allocate calls. MemoryGroup::manage flags that the object will be needed starting now and when TensorAllocator::allocate is called it signals the end of the object lifetime.
When configuration of all the operations is finished then the memory manager have to be populated:
Finally, during execution of the pipeline the memory of the appropriate memory group should be requested before running:
Most of the library's function have been ported to use IMemoryManager for their internal temporary buffers.
If that is the case, a memory manager can be passed to them during construction to reuse memory among these functions.
The implemented TensorAllocator and CLTensorAllocator objects provide an interface capable of importing existing memory to a tensor as backing memory.
A simple Arm® Neon™ example can be the following:
It is important to note the following:
OpenCL kernels when dispatched to the GPU take two arguments:
The LWS can be required by an algorithm (For example if it contains memory barriers or uses local memory) but it can also be used for performance reasons to tweak the performance of a kernel: the execution time of the overall kernel might vary significantly depending on how the GWS is broken down.
However, there is no universal rule regarding which LWS is best for a given kernel, so instead we created the CLTuner.
When the CLTuner is enabled ( Target = 2 for the graph examples), the first time an OpenCL kernel is executed the Compute Library will try to run it with a variety of LWS values and will remember which one performed best for subsequent runs. At the end of the run the graph::Graph will try to save these tuning parameters to a file.
However this process takes quite a lot of time, which is why it cannot be enabled all the time. CLTuner supports three modes of tuning with different trade-offs between the time taken to tune and the kernel execution time achieved using the best LWS found. In the Exhaustive mode, it searches all the supported values of LWS. This mode takes the longest time to tune and is the most likely to find the optimal LWS. Normal mode searches a subset of LWS values to yield a good approximation of the optimal LWS. It takes less time to tune than Exhaustive mode. Rapid mode takes the shortest time to tune and finds an LWS value that is at least as good or better than the default LWS value. The mode affects only the search for the optimal LWS and has no effect when the LWS value is imported from a file.
But, when the CLTuner is disabled ( Target = 1 for the graph examples), the graph::Graph will try to reload the file containing the tuning parameters, then for each executed kernel the Compute Library will use the fine tuned LWS if it was present in the file or use a default LWS value if it's not.
OpenCL 2.1 exposes the cl_khr_priority_hints extensions that if supported by an underlying implementation allows the user to specify priority hints to the created command queues. Is important to note that this does not specify guarantees or the explicit scheduling behavior, this is something that each implementation needs to expose.
In some cases, priority queues can be used when there is an implicit internal priority between graphics and compute queues and thus allow some level of priority control between them. At the moment three priority level can be specified:
Compute Library allows extraction of the internal OpenCL queue or the ability to inject directly a user-defined queue to the CLScheduler. This way the user can utilize this extension to define priorities between the queues and setup the OpenCL scheduler mechanism to utilize them.
IWeightsManager is a weights managing interface that can be used to reduce the memory requirements of a given pipeline by reusing transformed weights across multiple function executions. IWeightsManager is responsible for managing weight tensors alongside with their transformations. ITransformWeights provides an interface for running the desired transform function. This interface is used by the weights manager.
Following is a simple example that uses the weights manager:
Initially a weights manager must be set-up:
Once done, weights can be managed, configured and run:
Functions will automatically allocate the temporary buffers mentioned above, and will automatically multi-thread kernels' executions using the very basic scheduler described in the previous section.
Simple functions only call a single kernel (e.g NEConvolution3x3), while more complex ones consist of several kernels pipelined together (e.g NEFullyConnectedLayer ). Check their documentation to find out which kernels are used by each function.
The Compute Library runtime uses a single command queue and context for all the operations.
The user can get / set this context and command queue through CLScheduler's interface.
The user can get / set the target GPU device through the CLScheduler's interface.
In order to block until all the jobs in the CLScheduler's command queue are done executing the user can call CLScheduler::sync() or create a sync event using CLScheduler::enqueue_sync_event()
You can mix OpenCL and Arm® Neon™ kernels and functions. However it is the user's responsibility to handle the mapping/unmapping of OpenCL objects.
Some of the Compute Library components are modelled as singletons thus posing limitations to supporting some use-cases and ensuring a more client-controlled API. Thus, we are introducing an aggregate service interface IRuntimeContext which will encapsulate the services that the singletons were providing and allow better control of these by the client code. Run-time context encapsulates a list of mechanisms, some of them are: scheduling, memory management, kernel caching and others. Consequently, this will allow finer control of these services among pipelines when Compute Library is integrated in higher level frameworks.
This feature introduces some changes to our API. All the kernels/functions will now accept a Runtime Context object which will allow the function to use the mentioned services.
Finally, we will try to adapt our code-base progressively to use the new mechanism but will continue supporting the legacy mechanism to allow a smooth transition. Changes will apply to all our backends: Neon™ and OpenCL.
Compute Library offers experimental support for CLVK. If CLVK is installed in the system, users can select the backend when running a graph example with –target=clvk. If no target is specified and more that one OpenCL implementations are present, Compute Library will pick the first available.
In this section we present Compute Library's experimental application programming interface (API) architecture along with a detailed explanation of its components. Compute Library's API consists of multiple high-level operators and even more internally distinct computational blocks that can be executed on a command queue. Operators can be bound to multiple Tensor objects and executed concurrently or asynchronously if needed. All operators and associated objects are encapsulated in a Context-based mechanism, which provides all related construction services.
Compute Library consists of a list of fundamental objects that are responsible for creating and orchestrating operator execution. Below we present these objects in more detail.
AclContext or Context acts as a central creational aggregate service. All other objects are bound to or created from a context. It provides, internally, common facilities such as
The followings sections will describe parameters that can be given on the creation of Context.
Context is initialized with a backend target (AclTarget) as different backends might have a different subset of services. Currently the following targets are supported:
An execution mode (AclExecutionMode) can be passed as an argument that affects the operator creation. At the moment the following execution modes are supported:
Context creation can also have a list of capabilities of hardware as one of its parameters. This is currently available only for the CPU backend. A list of architecture capabilities can be passed to influence the selection of the underlying kernels. Such capabilities can be for example the enablement of SVE or the dot product instruction explicitly.
An allocator object that implements AclAllocator can be passed to the Context upon its creation. This user-provided allocator will be used for allocation of any internal backing memory.
A tensor is a mathematical object that can describe physical properties like matrices. It can be also considered a generalization of matrices that can represent arbitrary dimensionalities. AclTensor is an abstracted interface that represents a tensor.
AclTensor, in addition to the elements of the physical properties they represent, also contains the information such as shape, data type, data layout and strides to not only fully describe the characteristics of the physical properties but also provide information how the object stored in memory should be traversed. AclTensorDescriptor is a dedicated object to represent such metadata.
As Tensors can reside in different memory spaces, AclMapTensor and AclUnmapTensor entrypoints are provided to map Tensors in and out of the host memory system, respectively.
AclQueue acts as a runtime aggregate service. It provides facilities to schedule and execute operators using underlying hardware. It also contains services like tuning mechanisms (e.g., Local workgroup size tuning for OpenCL) that can be specified during operator execution.
Internally, Compute Library separates the executable primitives in two categories: kernels and operators which operate in a hierarchical way.
A kernel is the lowest-level computation block whose responsibility is performing a task on a given group of data. For design simplicity, kernels computation does NOT involve the following:
On the other hand, operators combine one or multiple kernels to achieve more complex calculations. The responsibilities of the operators can be summarized as follows:
Selecting multi_isa when building Compute Library, will create a library that contains all the supported ISA features. Based on the CPU support, the appropriate kernel will be selected at runtime for execution. Currently this option is supported in two configurations: (i) with armv8.2-a (ii) with armv8-a. In both cases all the supported ISA features are enabled in the build.
The arch option in a multi_isa build sets the minimum architecture required to run the resulting binary. For example a multi_isa build for armv8-a will run on any armv8-a or later, when the binary is executed on a armv8.2-a device it will use the additional cpu features present in this architecture: FP16 and dot product. In order to have a binary like this (multi_isa+armv8-a) the FP16 and dot product kernels in the library are compiled for the target armv8.2-a and all other common code for armv8-a.
Dependencies for all operators have been explicitly defined, this provides the ability to users to generate Compute Library binaries that include a user-defined list of operators.
An experimental flag 'build_config' has been introduced where a JSON configuration file can be provided and consumed. An example config looks like:
Supported data-types options are:
The list of supported operators can be found in filelist.json in the root of Compute Library repo.
Selecting high_priority when building Compute Library, one new library will be created: libarm_compute_hp and will contain a selected subset of the libary operators. Currently the operators are staticly set.
1.8.17 