diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/08_api.dox | 83 | ||||
-rw-r--r-- | docs/Doxyfile | 1 |
2 files changed, 84 insertions, 0 deletions
diff --git a/docs/08_api.dox b/docs/08_api.dox new file mode 100644 index 0000000000..a73b1bd351 --- /dev/null +++ b/docs/08_api.dox @@ -0,0 +1,83 @@ +/// +/// Copyright (c) 2021 Arm Limited. +/// +/// SPDX-License-Identifier: MIT +/// +/// Permission is hereby granted, free of charge, to any person obtaining a copy +/// of this software and associated documentation files (the "Software"), to +/// deal in the Software without restriction, including without limitation the +/// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +/// sell copies of the Software, and to permit persons to whom the Software is +/// furnished to do so, subject to the following conditions: +/// +/// The above copyright notice and this permission notice shall be included in all +/// copies or substantial portions of the Software. +/// +/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +/// SOFTWARE. +/// +namespace arm_compute +{ +/** +@page api Application Programming Interface + +@tableofcontents + +@section api_overview Overview + +In this section we present Compute Library's 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. + +@section api_objects Fundamental objects + +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. + +@subsection api_objects_context @ref AclContext or @ref Context + +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 +- allocators for object creation or backing memory allocation +- serialization interfaces +- any other modules that affect the construction of objects (e.g., program cache for OpenCL). + +The followings sections will describe parameters that can be given on the creation of Context. + +@subsubsection api_object_context_target @ref AclTarget +Context is initialized with a backend target (AclTarget) as different backends might have a different subset of services. +Currently the following targets are supported: +- #AclCpu: a generic CPU target that accelerates primitives through SIMD technologies +- #AclGpuOcl: a target for GPU acceleration using OpenCL + +@subsubsection api_object_context_execution_mode @ref AclExecutionMode +An execution mode (AclExecutionMode) can be passed as an argument that affects the operator creation. +At the moment the following execution modes are supported: +- #AclPreferFastRerun: Provides faster re-run. It can be used when the operators are expected to be executed multiple +times under the same execution context +- #AclPreferFastStart: Provides faster single execution. It can be used when the operators will be executed only once, +thus reducing their latency is important (Currently, it is not implemented) + +@subsubsection api_object_context_capabilitys @ref AclTargetCapabilities +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. +@note The underlying hardware should support the given capability list. + +@subsubsection api_object_context_allocator Allocator +An allocator object that implements @ref AclAllocator can be passed to the Context upon its creation. +This user-provided allocator will be used for allocation of any internal backing memory. + +@note To enable interoperability with OpenCL, additional entrypoints are provided +to extract (@ref AclGetClContext) or set (@ref AclSetClContext) the internal OpenCL context. +*/ +} // namespace arm_compute diff --git a/docs/Doxyfile b/docs/Doxyfile index fa16a5414b..9d711486c0 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -776,6 +776,7 @@ INPUT = ./docs/00_introduction.dox \ ./docs/05_contribution_guidelines.dox \ ./docs/06_functions_list.dox \ ./docs/07_errata.dox \ + ./docs/08_api.dox \ ./docs/ComputeLibrary.dir \ ./arm_compute/ \ ./src/ \ |