From 0ff73c70003bad895e1d0bd5c53aa117eb798900 Mon Sep 17 00:00:00 2001 From: Georgios Pinitas Date: Mon, 22 Mar 2021 04:38:18 +0000 Subject: Create architecture documentation Documentation describing architecture of the library is added. Apart from basic introduction, Context section has been added. Partially Resolves: COMPMID-4200 Signed-off-by: Georgios Pinitas Change-Id: I7a625cab9582aecd066f6c2b61ac5b2a3b0168fa Reviewed-on: https://review.mlplatform.org/c/ml/ComputeLibrary/+/5478 Comments-Addressed: Arm Jenkins Reviewed-by: SiCong Li Tested-by: Arm Jenkins --- docs/08_api.dox | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/Doxyfile | 1 + 2 files changed, 84 insertions(+) create mode 100644 docs/08_api.dox 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/ \ -- cgit v1.2.1