Add Android support, CMake build system, and cross-framework refactoring

.gitignore

@@ -30,3 +30,23 @@
 *.exe
 *.out
 *.app
+
+#vscode
+.vscode/
+
+#cmake build
+**/build/
+**/build-android/
+
+
+**/extern/*
+!**/extern/.gitkeep
+
+
+
+# OpenCL Dependency Downloads
+**/opencl/opencl_headers/
+**/opencl/tmp/
+
+**/android/include/*.h
+**/android/include/CL/

README.md

@@ -1,74 +1,110 @@
-# **GPU4S Bench - OBPMark-Kernel**
-## **Authors**
-- Ivan Rodriguez Ferrandez (UPC-BSC)
-- Alvaro Jover-Alvarez (UPC-BSC)
-- Leonidas Kosmidis (BSC-UPC)
-- David Steenari (ESA)
+# GPU4S Benchmark Suite documentation
+
+## Introduction
+GPU4S is a benchmarking suite that rely on OBPMark-Kernel to test perfomance and reliability of GPUs and multi-threaded processors for space applications. 
+
+The benchmarking suites have been developed in order to be compatible with heterogeneous platforms:
 
-### **Version: 1.0**  
+- Computer (x86_64, x86_32) 
+- Android (ARM64, ARM32)
+- Nvidia Xavier/TX2 (ARM64) (currently in development)
 
-<br/>
+<details>
+<summary><b style="font-size: 1em;">List of tested devices</b></summary>
+Up to this date, the suite has been successfully compiled and executed on the following devices:
 
-## **Description**
-Embedded  GPUs  have  been  identified  from  both private  and  government  space  agencies  as  promising  hardware technologies to satisfy the increased needs of payload processing.The GPU4S (GPU for Space) project funded from the EuropeanSpace  Agency  (ESA)  has  explored  in  detail  the  feasibility  and the  benefit  of  using  them  for  space  workloads.  Currently  at  the closing phases of the project, in this paper we describe the main project outcomes and explain the lessons we learnt. In addition,we  provide  some  guidelines  for  the  next  steps  towards  their adoption  in  space.
+| Platform | Operating System | CPU | GPU | Frameworks Tested |
+| :--- | :--- | :--- | :--- | :--- |
+| **High-end Laptop (x86_64)** | Fedora | AMD Ryzen 7 7840HS | NVIDIA GeForce RTX 4060 Laptop | CPU, OpenMP, CUDA, OpenCL, HIP |
+| **Smartphone (ARM64)** | Android 5 | Qualcomm Snapdragon 810 | Adreno 430 | CPU, OpenMP, OpenCL |
+</details>
+<br>
 
 
-## **Implemented Languages**
-- Standard C
+The benchmark uses a couple of different programming languages, libraries and frameworks to be able to compare perfomance of the same benchmark across most of devices: 
+- Standard C/C++
 - CUDA
+- HIP
 - OpenCL
 - OpenMP
-- HIP
-
-## **Benchmark List and Basic Description**
-
-For most of the benchmark suite there is a naïve, optimize and library versions. The benchmarks with their implementations are listed below.
-- Cifar 10
-  - Naïve,optimize and library (only for CUDA)
-- Cifar 10 Multiple
-  - Naïve,optimize and library (only for CUDA)
-- Convolution 2D
-  - Naïve,optimize and library (only for CUDA)
-- Correlation 2D
-  - Naïve,optimize
-- Fast fourier transform 2D bench
-  - Library
-- Fast fourier transform
-  - Naïve,optimize and library 
-- Fast fourier transform Window
-  - Naïve,optimize and library
-- Finite impulse response filter
-  - Naïve
-- Local response normalization (LRN)
-  - Naïve,optimize and library (only for CUDA)
-- Matrix multiplication
-  - Naïve,optimize and library
-- Max pooling bench
-  - Naïve,optimize and library (only for CUDA)
-- Memory Bandwidth 
-  - Naïve
-- Relu
-  - Naïve,optimize and library (only for CUDA)
-- Softmax
-  - Naïve,optimize and library (only for CUDA)
-- Wavelet transform
-  - Naïve,optimize
-
-
-## **Benchmark Compilation**
-For compile each of the benchmarks first you need to go to the folder for the specific benchmark that you want to compile.
-Inside of the folder you can call the Makefile for compilation. All of the Makefiles behaves the same for compilation. 
-
-There is three parts for the make file. 
-First is the type of benchmark that you want to compile, that could be *cuda* (this will compile cuda naïve) will be the same for the rest of the languages, for different version will be will the suffixes -opt, -lib for the optimize and library versions, example cuda-opt, opencl-lib.
-
-The second part is the definition of the data type, for all of the benchmarks float and double is supported and some of the benchmarks supports also integer. For specify the data type you need to add *-DATATYPE=(language)* for the languages the naming is in capital letters and are FLOAT,DOUBLE and INT. 
-
-The last parameter is the block size, this is only needed for the GPU code versions (OpenMP does not need this parameter). For the Makefile you need to provide *-BLOCKSIZE=(SIZE)* the block size is use square of the size that you provide, the recommended values are 4,8,16,32.
-
-A full example will be as follows
-
-``` make opencl-opt DATATYPE=FLOAT BLOCKSIZE=16 ```
-
-The compiled binary will be in the bin folder.
 
+
+## Background
+
+Embedded GPUs have been identified by both private companies and government space agencies as a promising technology to meet the growing demands of payload processing. The GPU4S (GPU for Space) project, funded by the European Space Agency (ESA), explores the feasibility and benefits of using embedded GPUs for space workloads, and provides guidelines for their adoption in space applications.
+
+## Benchmark List and Basic Description
+
+For most of the benchmark suite there is a naïve, optimized and library version. The benchmarks with their implementations are listed below.
+
+| Benchmark | Naïve | Optimized | Library |
+|---|:---:|:---:|:---:|
+| Cifar 10 | ✅ | ✅ | ✅ (CUDA only) |
+| Cifar 10 Multiple | ✅ | ✅ | ✅ (CUDA only) |
+| Convolution 2D | ✅ | ✅ | ✅ (CUDA only) |
+| Correlation 2D | ✅ | ✅ | ❌ |
+| Fast Fourier Transform 2D | ❌ | ❌ | ✅ |
+| Fast Fourier Transform | ✅ | ✅ | ✅ |
+| Fast Fourier Transform Window | ✅ | ✅ | ✅ |
+| Finite Impulse Response Filter | ✅ | ❌ | ❌ |
+| Local Response Normalization (LRN) | ✅ | ✅ | ✅ (CUDA only) |
+| Matrix Multiplication | ✅ | ✅ | ✅ |
+| Max Pooling | ✅ | ✅ | ✅ (CUDA only) |
+| Memory Bandwidth | ✅ | ❌ | ❌ |
+| ReLU | ✅ | ✅ | ✅ (CUDA only) |
+| Softmax | ✅ | ✅ | ✅ (CUDA only) |
+| Wavelet Transform | ✅ | ✅ | ❌ |
+
+## Quick Start
+
+If you already have the basic C/C++ programming tools installed (GCC/Clang, CMake ≥ 3.24, Git — see [**Prerequisites**](./docs/INSTALL.md) if not), you can try to compile and run the CPU version of the matrix multiplication benchmark in 3 steps:
+
+```bash
+# 1. Go to the benchmark directory
+cd gpu4s_benchmark/matrix_multiplication_bench
+
+# 2. Generate build files and compile the matrix_mult CPU target
+cmake -B build
+cmake --build build --target cpu -j$(nproc)
+
+# 3. Run it
+./build/bin/matrix_mult_cpu -s 512 -t
+```
+
+- `-s 512` runs the benchmark on a 512x512 matrix
+- `-t` prints the execution time
+
+Congratulations! You have successfully built and run your first GPU4S benchmark.
+
+> Wanting to build with CUDA, HIP, OpenCL, or for Android? See [docs/INSTALL.md](docs/INSTALL.md) for prerequisites and [docs/BUILD_AND_RUN.md](docs/BUILD_AND_RUN.md) for building targets and check the runtime options.
+
+
+
+## Road map
+**Main focus**:
+
+- [X] fix issue of correctness between cpu and gpu in some benchmarks
+- [X] refactor to extract the common of frameworks
+- [X] fix of the clock to be executed in runtime + kernerCLK->deviceOBJ
+- [X] Check for cl error during memory copy to host and clean
+- [X] add UMA implementation for Android
+- [X] Big cmake to compile everything 
+- [ ] be compatible with jetson board + add UMA for jetson board
+
+**Bonus**:
+- [ ] create a test with vulkan for android to have best performance (with softmax ?)
+- [ ] add map for verification of the result (ANDROID UMA)
+- [ ] refactor main, cuda, hip, opencl, OpenMP, -> create common 
+- [ ] refactor cpu function -> create common  (most important and easier)
+- [ ] add a get elapsed time function that print in this cpu function
+
+## The Authors
+- Ivan Rodriguez Ferrandez (BSC-UPC)
+- Alvaro Jover-Alvarez (BSC-UPC)
+- Leonidas Kosmidis (BSC-UPC)
+- Noah Perret (BSC-Centrale Nantes)
+- David Steenari (ESA)
+
+## License
+
+[ESA-PL Strong Copyleft – v2.5](./LICENSE)

docs/BUILD&RUN.md

@@ -0,0 +1,177 @@
+# GPU4S: Build & Usage Guide
+This document describes how to build and run all the benchmarks of GPU4S. For general information about the project, check the main [README](../README.md).
+
+## Build Instructions
+
+GPU4S Bench can be built with 2 different methods:
+
+- **globally**: all 17 benchmarks at once, from the `gpu4s` root
+- **standalone**: single benchmark, from its own subfolder 
+
+Both follow the same two steps: configure with CMake, then build.
+
+### 1. Configure
+
+**Host (x86_64 / Linux):**
+```bash
+cmake -B build
+```
+**Android:**
+```bash 
+cmake -B build-android \
+  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_HOME/ndk/27.3.13750724/build/cmake/android.toolchain.cmake \
+  -DANDROID_ABI=arm64-v8a \
+  -DANDROID_PLATFORM=android-21   
+```
+
+
+>**Notes**: You can name the build directory however you like, which makes it easy to keep multiple configurations side by side:
+> ```bash
+> cmake -B build-float-256 -DDATATYPE=FLOAT -DBLOCKSIZE=256
+> cmake -B build-double-128 -DDATATYPE=DOUBLE -DBLOCKSIZE=128
+> ```
+
+<br>
+
+
+### 2. Build
+
+**Build every target:**
+```bash
+cmake --build build -j$(nproc)            # host
+cmake --build build-android -j$(nproc)    # android
+```
+
+>**Notes**: The option `-j$(nproc)` forces your CPU to use all of its core to speed up the process.
+
+
+**Build a specific target (optional):**
+```bash
+# Standalone (e.g.: from inside matrix_multiplication_bench/)
+cmake --build build --target cpu
+cmake --build build --target all-opencl
+cmake --build build --target cuda-opt
+
+# Global (from gpu4s_benchmark/ root)
+cmake --build build --target matrix_mult-cpu
+cmake --build build --target matrix_mult-all-opencl
+cmake --build build --target matrix_mult-cuda-opt
+```
+>**Notes**: The option `--target` can be used to select a specific target.
+
+
+<details>
+<summary><b style="font-size: 1.25em;">📋 List of Target Shortcuts</b></summary>
+
+- **CPU**: `cpu`, `CPU`
+- **HIP**: `hip-`, `HIP`, `hip-opt`, `HIP-opt`, `all-hip`
+- **CUDA**: `cuda`, `CUDA`, `cuda-opt`, `CUDA-opt`, `cuda-lib`, `CUDA-lib`, `all-cuda`
+- **OpenCL**: `cl`, `OpenCL`, `opencl-opt`, `OpenCL-opt`, `opencl-lib`, `OpenCL-lib`, `all-opencl`
+- **OpenMP**: `openmp`, `OpenMP`, `openmp-opt`, `OpenMP-opt`, `openmp-lib`, `OpenMP-lib`, `all-openmp`
+</details>
+
+<br>
+
+### 3. Compile options
+
+You can customize compilation options during the configuration step by adding `-D<PARAMETER>=<VALUE>` to `cmake -B ...`:
+
+#### Available Parameters
+
+| Parameter | Default | Allowed Values | Description |
+| :--- | :--- | :--- | :--- |
+| `DATATYPE` | `FLOAT` | `FLOAT`, `DOUBLE`, `INT` | Data type used in computations |
+| `BLOCKSIZE` | `16` | `4`, `8`, `16`, `32`, etc. | 2D tile/block size for GPU kernels |
+| `OPT_FLAG` | `-O3` | `-O2`, `-O3`, `-Ofast` | Host compiler optimization level |
+| `CUDA_ARCH` | `native` | `native`, `sm_70`, `sm_75`, `sm_80`, `sm_86`, etc. | NVIDIA GPU compute architecture |
+| `OPENCL_VERSION` | `300` | `200`, `210`, `220`, `300`, `310` | OpenCL target API version |
+| `BLA_VENDOR` | `OpenBLAS` | `OpenBLAS`, `ATLAS`, `Generic` | BLAS library vendor for OpenMP-lib |
+| `NSTREAMS` | `4` | Integer $\ge 1$ | Number of concurrent streams (`cifar_10_multiple`) |
+
+
+<details>
+<summary><b style="font-size: 1.25em;">Usage examples</b></summary>
+
+**Simple — change the data type:**
+
+```bash
+# e.g. Use double precision instead of float
+cmake -B build -DDATATYPE=DOUBLE
+```
+**Combined — fully customize multiple parameters:**
+
+Chain multiple `-D` flags to customize data type, tuning, and target hardware in a single command. Example: double precision, 32x32 block size, targeting an Ampere GPU with `-Ofast`:
+
+```bash
+cmake -B build \
+  -DDATATYPE=DOUBLE \
+  -DBLOCKSIZE=32 \
+  -DCUDA_ARCH=sm_86 \
+  -DOPT_FLAG=-Ofast
+```
+</details>
+
+<br>
+
+### 4. Cleaning up the workspace
+In order to reset your build environment, you can remove all generated build directories and start fresh:
+
+```bash
+rm -rf build*
+```
+
+## Usage
+
+Once compiled, the executables are located in `./<build-directory>/bin`.
+
+
+### 1. Running on Host (Linux / PC)
+
+To execute a benchmark on your local machine, simply launch the generated executable from the terminal. 
+
+```bash
+# General syntax
+./build/bin/<target_name> [arguments]
+
+# Example: Running the standard CPU matrix multiplication
+./build/bin/matrix_mult_cpu -s 1024
+
+# Example: Running the optimized CUDA version
+./build/bin/matrix_mult_cuda_opt -s 2048
+```
+
+### 2. Running on Android
+
+The launch command is the same, but you first need to push the executable file to your phone, then you can execute it through `adb shell`.
+
+
+```bash
+# Push all binaries to the device
+adb push ./build-android/bin/* /data/local/tmp/
+
+# Grant execution permissions to the binaries
+adb shell chmod 755 /data/local/tmp/*
+
+# Execute the benchmarks on the Android device
+adb shell /data/local/tmp/matrix_mult_opencl -s 1024 -t -v
+```
+
+### Runtime Parameters
+
+All devices share the same set of flags. For most benchmarks, you will need to provide at bare minimum a size flag (`-s`), which indicates how demanding the benchmark will be by changing the size of the calculation, and at least one of the timing/profiling output flags (`-t`, `-c`, `-C`) so the benchmark actually returns some result.
+
+| Flag | Name | Description |
+| :--- | :--- | :--- |
+| `-s <size>` | **Size** | Sets the X and Y dimensions for the benchmark (e.g., matrix size $N \times N$). |
+| `-v` | **Verify** | Executes a CPU baseline calculation and compares it with the GPU output to verify correctness. |
+| `-t` | **Timing** | Prints the elapsed execution time to the console. |
+| `-c` / `-C` | **CSV format** | Prints timing results in CSV format. Use `-C` to include a timestamp. |
+| `-u` | **Unified Memory** | Enables Unified Memory mapping (Zero-Copy). **Highly recommended for Android and Jetson** platforms to prevent unnecessary memory transfers. |
+| `-p` | **Profiling** | Enables internal clock profiling for more granular hardware timing. |
+| `-d <id>` | **Device ID** | Selects the specific GPU device ID to use (default is usually 0). |
+| `-o` | **Print Output** | Prints the resulting matrix or array directly to the terminal. |
+| `-f` | **Mute** | Mutes all standard print messages (useful for batch testing scripts). |
+| `-i <fileA> <fileB>`| **Input Files** | Loads custom hexadecimal input files instead of using randomized data generation. |
+| `-g` / `-e` | **Export** | `-g` exports the GPU result to `gpu_file.out`. `-e` exports both GPU and CPU results in hex format (automatically enables `-v`). |
+| `-k <size>` | **Kernel Size** | *(Specific to `convolution_2D`, `FIR_filter`)* Defines the size of the convolution filter / mask ($K \times K$) or FIR tap length. |
+| `-l <stride>`| **Stride Size** | *(Specific to `max_pooling`)* Defines the horizontal and vertical step size of the pooling sliding window. |