ArchProbe source and example output

.gitignore

@@ -348,3 +348,7 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+build*
+
+!examples

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "third/libopencl-stub"]
+	path = third/libopencl-stub
+	url = https://github.com/ShireFolk/libopencl-stub

CMakeLists.txt

@@ -0,0 +1,50 @@
+cmake_minimum_required (VERSION 3.12)
+
+project ("ArchProbe" LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")
+
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake")
+
+if (NOT CMAKE_BUILD_TYPE)
+    message(STATUS "No build type selected, default to Release")
+    set(CMAKE_BUILD_TYPE "Release" CACHE PATH "Build Type" FORCE)
+endif()
+
+message("-- Looking for libopencl-stub")
+if (EXISTS "${PROJECT_SOURCE_DIR}/third/libopencl-stub")
+    add_compile_definitions(CL_VERSION_2_0)
+    add_subdirectory(third/libopencl-stub)
+    set(OpenCL_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/third/libopencl-stub/include")
+    message("-- OpenCL context enabled")
+else()
+    message("")
+    message("-- OpenCL not found! OpenCL context is disabled")
+    message("")
+endif()
+
+set(LINK_LIBS
+    OpenCL
+)
+set(INC_DIRS
+    "${PROJECT_SOURCE_DIR}/include"
+    ${OpenCL_INCLUDE_DIR}
+    ${CMAKE_SOURCE_DIR}/third/OpenCL-SDK/external/OpenCL-CLHPP/include
+)
+
+# The testbench library.
+include_directories(${INC_DIRS})
+file(GLOB SRCS "${PROJECT_SOURCE_DIR}/src/*")
+file(GLOB INCS "${PROJECT_SOURCE_DIR}/include/*")
+add_library(ArchProbeCore STATIC ${SRCS} ${INCS})
+target_link_libraries(ArchProbeCore ${LINK_LIBS})
+target_compile_definitions(ArchProbeCore PUBLIC CL_TARGET_OPENCL_VERSION=200)
+
+# Testbench apps.
+make_directory("${CMAKE_BINARY_DIR}/assets/")
+add_subdirectory("${PROJECT_SOURCE_DIR}/apps")

README.md

@@ -1,14 +1,48 @@
-# Project
+# ArchProbe
 
-> This repo has been populated by an initial template to help get you started. Please
-> make sure to update the content to build a great experience for community-building.
+ArchProbe is a profiling tool to demythify mobile GPU architectures with great details. The mechanism of ArchProbe is introduced in our technical paper which is still under review.
 
-As the maintainer of this project, please make a few updates:
+![Adreno & Mali Architecture Overview](overview.png)  
+*Architecture details collected with ArchProbe, presented in our technical paper.*
 
-- Improving this README.MD file to provide a great experience
-- Updating SUPPORT.MD with content about this project's support experience
-- Understanding the security reporting process in SECURITY.MD
-- Remove this section from the README
+## How to Use
+
+In a clone of ArchProbe code repository, the following commands build ArchProbe for most mobile devices with a 64-bit ARMv8 architecture.
+
+```powershell
+git submodule update --init --recursive
+mkdir build-android-aarch64 && cd build-android-aarch64
+cmake -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" -DANDROID_ABI="arm64-v8a" -DANDROID_PLATFORM=android-28 -G "Ninja" ..
+cmake --build . -t ArchProbe
+```
+
+To run ArchProbe in command line via `adb shell`, you need to copy the executables to `/data/local/tmp`.
+
+If you are using Windows, the PowerShell scripts in `scripts` can be convenient too:
+
+```powershell
+scripts/Run-Android.ps1 [-Verbose]
+```
+
+### Prebuilt Binaries
+
+Prebuilt binaries will be available [here](https://github.com/PENGUINLIONG/graphi-t/releases).
+
+## How to Interpret Outputs
+
+A GPU hardware has many traits like GFLOPS and cache size. ArchProbe implements a bag of tricks to expose these traits and each implementation is called an *aspect*. Each aspect has its own configurations in `ArchProbe.json`, reports in `ArchProbeReport.json`, and data table of every run of probing kernels in `[ASPECT_NAME].csv`. Currently ArchProbe implements the following aspects:
+
+- `WarpSizeMethod{A|B}` Two methods to detect the warp size of a GPU core;
+- `GFLOPS` Peak computational throughput of the device;
+- `RegCount` Number of registers available to a thread and whether the register file is shared among warps;
+- `BufferVecWidth` Optimal vector width to read the most data in a single memory access;
+- `{Image|Buffer}CachelineSize` Top level cacheline size of image/buffer;
+- `{Image|Buffer}Bandwidth` Peak read-only bandwidth of image/buffer;
+- `{Image|Buffer}CacheHierarchyPChase` Size of each level of cache of image/buffer by the P-chase method.
+
+If the `-v` flag is given, ArchProbe prints extra human-readable logs to `stdout` which is also a good source of information.
+
+Experiment data gathered from Google Pixel 4 can be found [here](examples/adreno640/Google_Pixel_4).
 
 ## Contributing
 

SUPPORT.md

@@ -1,13 +1,3 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/spot](https://aka.ms/spot). CSS will work with/help you to determine next steps. More details also available at [aka.ms/onboardsupport](https://aka.ms/onboardsupport).
-- **Not sure?** Fill out a SPOT intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
 ## How to file issues and get help  
@@ -16,10 +6,6 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc
 issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
-
 ## Microsoft Support Policy  
 
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+Support for this project is limited to the resources listed above.

apps/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(archprobe)

apps/archprobe/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(APP_NAME ArchProbe)
+
+add_executable(${APP_NAME} "app.cpp" "env.cpp")
+target_link_libraries(${APP_NAME} ArchProbeCore)