diff --git a/README.md b/README.md index 6598fde..699d15c 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,60 @@ -# `HWCPipe 2.0` +# About -## Introduction +HWCPipe is a utility that allows applications to sample performance counters from Arm® Immortalis™ +and Arm Mali™ GPUs. This information allows developers to profile and optimize their application +workload using their existing in-house performance tooling, and gives the ability to display +performance data live in the application user interface. -Currently access to Hardware Counters is exposed via ioctl interfaces. That requires some knowledge -about driver internals and sometimes about hardware itself. Software that needs to access Mali -counters needs to interface with internals somwehow. +The HWCPipe 2.x series is a major rewrite of the library, capable of exposing all of the public +performance counters accessible in the Arm Streamline profiler. This version of the library +is not API compatible with the 1.x series, and no longer supports Arm CPU performance counters. -HWCPipe 2.0 is a second version of a currently existing open source solution maintained by Arm. -Its aim is to support an up-to-date way to interface with the latest drivers. The library is -intended to be more modular than its predecessor and support different use-cases while still -exposing a simple API to access GPU counters. +## Supported devices -## Building the Library +This library aims to support all Arm GPU products from the Mali-T700 series onwards, ensuring +developers have coverage of the vast majority of smartphones with Arm GPUs that are in use today. +If you find a device with an Arm GPU which does not work, or gives inaccurate results, please open +an Issue on the GitHub issue tracker. -The library is designed to be embedded into your existing CMake build process. Clone the GitHub +This library only supports devices using the Arm commercial driver. + +## License + +This project is licensed under the MIT license. By downloading any component from this repository +you acknowledge that you accept terms specified in the [LICENSE.md](LICENSE.md) file. + +# Building + +The HWCPipe library is designed to be embedded into existing CMake build process. Clone the GitHub repository and add it as a subdirectory to your CMakeLists.txt. A single library target, called `hwcpipe`, is made available for you to link to your project. -For example, your CMakeLists.txt could contain: +For example, your `CMakeLists.txt` could contain: + ``` add_subdirectory(external/hwcpipe) target_link_libraries(my_project hwcpipe) ``` -## Building the Examples +## Building the example + +A small example demonstrating the API usage is provided in the `examples` folder. To build the +example enable the `HWCPIPE_BUILD_EXAMPLES` CMake build option. + +``` +cmake -DHWCPIPE_BUILD_EXAMPLES=ON -B build . +``` + +# Support + +If you have issues with the library itself, please raise them in the project's GitHub issue tracker. + +If you have any questions about Arm GPUs, application development for Arm GPUs, or general mobile +graphics development or technology please submit them on the [Arm Community graphics forums][1]. -A short example of the API usage is provided in the `examples` folder. Enable the -HWCPIPE_BUILD_EXAMPLES CMake option to build the example program with the library. -Run CMake from the root of the repository: +- - - -```cmake -DHWCPIPE_BUILD_EXAMPLES=ON -B build .``` +_Copyright © 2023, Arm Limited and contributors. All rights reserved._ +[1]: https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum/