From 531a38886f97045ff49aefc0cb1cb404b52016f1 Mon Sep 17 00:00:00 2001 From: Michael Platings Date: Fri, 26 Apr 2024 11:09:25 +0000 Subject: [PATCH 1/2] Remove warnings that KleidiCV is preview only Since the warnings were added the project's quality bar has been raised greatly and the warnings are no longer appropriate. --- README.md | 7 ------- SECURITY.md | 8 +------- 2 files changed, 1 insertion(+), 14 deletions(-) diff --git a/README.md b/README.md index 5fde9242c..0fe37cd7c 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,8 @@ SPDX-FileCopyrightText: 2023 - 2024 Arm Limited and/or its affiliates ---- -**NOT SUITABLE FOR DEPLOYMENT OR PRODUCTION USE** ---- - # KleidiCV -This project is in the early stages of development and is not ready for use -except as a preview. - KleidiCV is a library aiming to give high-performing image processing functions on Arm. It is designed to be simple to import into a wide variety of projects. diff --git a/SECURITY.md b/SECURITY.md index f6b559e75..57d3c918f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,13 +4,7 @@ SPDX-FileCopyrightText: 2023 - 2024 Arm Limited and/or its affiliates -This project is in the early stages of development and is not suitable for use except as a preview. - -It is not suitable for deployment or production use. - -This status will change prior to the project's initial release. - -Security bugs can be reported to arm-security@arm.com at any stage of the project's development. +Security bugs can be reported to arm-security@arm.com. Scripts within this project may download and patch third party sources. It is the responsibility of the users of such scripts to track such third party sources for security issues. -- GitLab From 6f7b96405069416bbfa2d13936e2d2b424cbda7e Mon Sep 17 00:00:00 2001 From: Michael Platings Date: Mon, 29 Apr 2024 10:49:03 +0000 Subject: [PATCH 2/2] Rework documentation Move the documentation to a common "doc" folder to make docs more discoverable. Split documentation into multiple pages. Separate Android & Linux build documentation. Android is the primary platform so the build docs now prioritises instructions for Android. Add patch as build prerequisite. Move build.sh documentation inside the script itself. Otherwise remove it from the documentation as it has been found to create more confusion than it solves except for advanced users. Mark KLEIDICV_CHECK_BANNED_FUNCTIONS as internal since there's no particular need for users to touch it. --- Doxyfile | 2 +- README.md | 152 ++---------------- doc/benchmark.md | 13 ++ doc/build.md | 120 ++++++++++++++ .../functionality.md | 34 ++-- .../opencv/doc-opencv.md => doc/opencv.md | 16 +- doc/test.md | 15 ++ kleidicv/CMakeLists.txt | 2 +- kleidicv/include/kleidicv/kleidicv.h | 2 +- scripts/build.sh | 8 + 10 files changed, 207 insertions(+), 157 deletions(-) create mode 100644 doc/benchmark.md create mode 100644 doc/build.md rename kleidicv/src/supported-types.md => doc/functionality.md (70%) rename adapters/opencv/doc-opencv.md => doc/opencv.md (89%) create mode 100644 doc/test.md diff --git a/Doxyfile b/Doxyfile index 9d8e0ca6e..708925d32 100644 --- a/Doxyfile +++ b/Doxyfile @@ -9,7 +9,7 @@ HIDE_UNDOC_CLASSES = YES SHOW_INCLUDE_FILES = NO QUIET = YES WARN_AS_ERROR = FAIL_ON_WARNINGS -INPUT = kleidicv adapters/opencv/kleidicv_hal.h +INPUT = kleidicv adapters/opencv/kleidicv_hal.h doc/functionality.md RECURSIVE = YES EXCLUDE = build VERBATIM_HEADERS = NO diff --git a/README.md b/README.md index 0fe37cd7c..61bd684a9 100644 --- a/README.md +++ b/README.md @@ -6,148 +6,14 @@ SPDX-License-Identifier: Apache-2.0 # KleidiCV -KleidiCV is a library aiming to give high-performing image -processing functions on Arm. It is designed to be simple to import into a wide -variety of projects. +The KleidiCV library provides high-performance image processing functions for AArch64. +It is designed to be simple to integrate into a wide variety of projects. -The library provides a C interface. For details see -[the C API documentation](https://kleidi.sites.arm.com/kleidicv/). +## Documentation -An adapter layer API is currently provided for: -* OpenCV - [available functionality overview](adapters/opencv/doc-opencv.md) - -# Structure - -The directory `kleidicv` contains generic implementation of the library. -Integration with other projects are stored in `adapters` folder. `test` contains -API and unit tests for the library. `benchmark` contains benchmark source. -`conformity` contains checks to compare the library output with different -implementations. All supporting scripts are located in `scripts`. - -# Standalone build using CMake - -The library can be built using CMake: -``` -cmake -S /path/to/kleidicv -B build-kleidicv -cmake --build build-kleidicv --parallel -``` - -To target Android devices the following CMake flags are also required: -``` --DCMAKE_TOOLCHAIN_FILE=/path/to/android-ndk/build/cmake/android.toolchain.cmake \ --DANDROID_ABI=arm64-v8a -``` - -# Standalone build using the provided script - -Build scripts for Linux/macOS are provided for convenience. To build the library run: -``` -scripts/build.sh -``` - -To target Android devices the following command can be used: -``` -BUILD_ID=android \ -CMAKE_TOOLCHAIN_FILE=/path/to/android-ndk/build/cmake/android.toolchain.cmake \ -EXTRA_CMAKE_ARGS="-DANDROID_ABI=arm64-v8a" \ -scripts/build.sh -``` - -The build artifacts are placed in the `build` directory. - -## Build and run tests for Android - -To build all the tests use the target `kleidicv-test`, to also run them use -`check-kleidicv` and set a proper `CMAKE_CROSSCOMPILING_EMULATOR`. - -To build all tests: -``` -BUILD_ID=android \ -CMAKE_TOOLCHAIN_FILE=/path/to/android-ndk/build/cmake/android.toolchain.cmake \ -EXTRA_CMAKE_ARGS="-DANDROID_ABI=arm64-v8a" \ -scripts/build.sh kleidicv-test -``` - -To run the tests: -``` -BUILD_ID=android \ -CMAKE_TOOLCHAIN_FILE=/path/to/android-ndk/build/cmake/android.toolchain.cmake \ -ADB= \ -CMAKE_CROSSCOMPILING_EMULATOR="/scripts/test_android.sh;/build/" \ -EXTRA_CMAKE_ARGS="-DANDROID_ABI=arm64-v8a" \ -scripts/build.sh check-kleidicv -``` - -For further options please refer to the documentation in `./scripts/build.sh` -and `./scripts/test_android.sh`. - -# Building with OpenCV - -## Install - -This library is compatible with [OpenCV](https://opencv.org) version 4.9. (OpenCV 5.x support is experimental.) - -Integration consists of the following steps: -1. Download OpenCV sources: -``` -wget https://github.com/opencv/opencv/archive/refs/tags/4.9.0.tar.gz -tar xf 4.9.0 -cd opencv-4.9.0 -``` -2. Patch OpenCV: -``` -patch -p1 + +SPDX-License-Identifier: Apache-2.0 +--> + +# Benchmarking KleidiCV + +Building of KleidiCV's benchmarks can be enabled with the `cmake` argument `-DKLEIDICV_BENCHMARK=ON`. +The benchmarks are based on [Google Benchmark](https://github.com/google/benchmark). +All the standard Google Benchmark command line arguments can be used. In addition, +the image size on which the tests will be run can be set with the command line +options `--image_width=123` and `--image_height=123`. diff --git a/doc/build.md b/doc/build.md new file mode 100644 index 000000000..26ba2991b --- /dev/null +++ b/doc/build.md @@ -0,0 +1,120 @@ + + +# Building KleidiCV for Android + +## Prerequisites +While the core functionality of the library does not rely on any third-party +libraries, there are build prerequisites that are essential for compiling the +source code and generating the executable. Please ensure that these tools are +installed on your system before proceeding with the build process. + +To successfully build and compile this project for Android, you'll need the following tools: +- [Android NDK](https://developer.android.com/ndk/) +- [CMake](https://cmake.org) version 3.16 or newer (3.21 is recommended) +- `make` or [Ninja](https://ninja-build.org) +- `patch` + +Running tests on Android devices requires [ADB](https://developer.android.com/tools/adb). +ADB is included in [Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools). + +## Building OpenCV & KleidiCV for Android + +For details of which OpenCV function are accelerated by KleidiCV see +[KleidiCV's OpenCV documentation](opencv.md). + +### Get and patch OpenCV source + +KleidiCV is compatible with [OpenCV](https://opencv.org) version 4.9 and later. (OpenCV 5.x support is experimental.) + +Integration consists of the following steps: +1. Download OpenCV sources: +``` +wget https://github.com/opencv/opencv/archive/refs/tags/4.9.0.tar.gz +tar xf 4.9.0 +cd opencv-4.9.0 +``` +2. Patch OpenCV: +``` +patch -p1 -# Functionality exposed to OpenCV via adapter layer +# OpenCV Hardware Acceleration Layer + +[OpenCV](https://github.com/opencv/opencv) can be built with KleidiCV +acceleration via KleidiCV's OpenCV Hardware Acceleration Layer (HAL). +For details of building OpenCV with KleidiCV see [the build documentation](build.md). + +## Performance + +For single-threaded use cases, enabling the KleidiCV OpenCV HAL is likely to +provide a performance boost for the functions that it implements. +Multithreading is planned for KleidiCV but at present it is single-threaded +only. Therefore it is recommended to check the performance yourself in order +to decide whether to enable KleidiCV in a multicore environment. + +## Functionality in KleidiCV OpenCV HAL ### `gray_to_bgr` Converts grayscale images to RGB or RGBA. diff --git a/doc/test.md b/doc/test.md new file mode 100644 index 000000000..a2bebb5ea --- /dev/null +++ b/doc/test.md @@ -0,0 +1,15 @@ + + +# Testing KleidiCV + +[Build](build.md) KleidiCV API tests using the target `kleidicv-api-test`. + +The tests use the [GoogleTest](https://github.com/google/googletest) +testing framework and accept the standard GoogleTest arguments. + +A [coverage report](https://kleidi.sites.arm.com/kleidicv/coverage/coverage_report.html) +is generated based on this testing. diff --git a/kleidicv/CMakeLists.txt b/kleidicv/CMakeLists.txt index 40afc094a..987e61c96 100644 --- a/kleidicv/CMakeLists.txt +++ b/kleidicv/CMakeLists.txt @@ -20,7 +20,7 @@ option( "Enables or disables SVE2 code paths for selected algorithms. Has no effect if KLEIDICV_ENABLE_SVE2 is false." ON ) -option(KLEIDICV_CHECK_BANNED_FUNCTIONS "Check source for deprecated or obsolescent functions" OFF) +option(KLEIDICV_CHECK_BANNED_FUNCTIONS "Internal - Check source for deprecated or obsolescent functions" OFF) option(KLEIDICV_ASSUME_128BIT_SVE2 "Internal - If turned ON 128-bit SVE2 vector length is assumed" OFF) option(KLEIDICV_PREFER_INTERLEAVING_LOAD_STORE "Internal - If turned ON interleaving loads and stores are preferred instead of continuous loads and stores" OFF) option(KLEIDICV_EXPERIMENTAL_FEATURE_CANNY "Internal - Enable experimental Canny algorithm" OFF) diff --git a/kleidicv/include/kleidicv/kleidicv.h b/kleidicv/include/kleidicv/kleidicv.h index fb69d3233..63a9b2771 100644 --- a/kleidicv/include/kleidicv/kleidicv.h +++ b/kleidicv/include/kleidicv/kleidicv.h @@ -18,7 +18,7 @@ /// @file /// @brief For an overview of the functions and their supported types see -/// @ref kleidicv/src/supported-types.md. +/// @ref doc/functionality.md. #ifndef KLEIDICV_H #define KLEIDICV_H diff --git a/scripts/build.sh b/scripts/build.sh index 7dd9406f1..56327eb7b 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -6,9 +6,17 @@ # # Builds a given target. # +# The build artifacts are placed in the `build` directory. +# # Arguments: # 1: Target to build. Defaults to 'kleidicv'. # +# To target Android devices the following command can be used: +# BUILD_ID=android \ +# CMAKE_TOOLCHAIN_FILE=/path/to/android-ndk/build/cmake/android.toolchain.cmake \ +# EXTRA_CMAKE_ARGS="-DANDROID_ABI=arm64-v8a" \ +# scripts/build.sh +# # Options: # BUILD_ID: Identifier of the build, defaults to 'kleidicv'. # BUILD_PATH: Directory for all the files associated with a build. -- GitLab