View source for OpenCL and MPI Termux Troubleshooting

Dokumentasi proses menjalankan '''OpenCL + MPI''' secara bersamaan di [[https://termux.dev/en/ Termux]] pada perangkat Android yang sudah di-root, lengkap dengan '''semua error yang ditemui, penyebabnya, dan cara memperbaikinya'''. Hasil akhir: sebuah program C++ yang membagi vektor lewat MPI ke beberapa proses, lalu tiap proses menghitung bagiannya di GPU Adreno lewat OpenCL.

== Lingkungan ==

{| class="wikitable"
! Komponen !! Keterangan
|-
| Perangkat || Redmi Note 12 4G (rooted)
|-
| SoC || Qualcomm Snapdragon 685
|-
| GPU || Adreno 610 (OpenCL 2.0 device, driver melaporkan OpenCL 3.0)
|-
| Userland || Termux
|-
| ICD loader || <code>ocl-icd</code> ("OCL Icd free software")
|-
| Driver OpenCL || <code>/vendor/lib64/libOpenCL.so</code> (milik vendor/Qualcomm)
|-
| MPI || OpenMPI (paket <code>openmpi</code> Termux)
|-
| <code>$PREFIX</code> || <code>/data/data/com.termux/files/usr</code>
|}

Paket yang dibutuhkan:

<syntaxhighlight lang="bash">
pkg install clang make cmake openmpi opencl-headers ocl-icd clinfo
</syntaxhighlight>

== Ringkasan masalah ==

{| class="wikitable"
! # !! Gejala (error) !! Penyebab singkat !! Fix singkat
|-
| 1 || <code>clinfo</code>: Number of platforms = 0 || Loader ocl-icd tidak menemukan driver vendor || Daftarkan [[ICD]] / muat driver vendor langsung
|-
| 2 || clang: <code>cannot locate symbol _ZNSt6__ndk1...</code> || <code>LD_LIBRARY_PATH</code> global menarik libc++ Android || Jangan set <code>LD_LIBRARY_PATH</code> global; pisah env build vs run
|-
| 3 || <code>use of undeclared identifier 'cl'</code> || Header C++ <code>&lt;CL/opencl.hpp&gt;</code> tidak ada; <code>&lt;CL/cl.h&gt;</code> tidak punya namespace <code>cl::</code> || Pakai C API dari C++, atau pasang <code>opencl-clhpp</code>
|-
| 4 || <code>mpirun ... signal 31 (Bad system call)</code> || seccomp Android memblokir syscall binding hwloc saat <code>MPI_Init</code> || <code>--mca hwloc_base_binding_policy none</code>
|-
| 5 || Program C++: <code>No OpenCL platform</code> || Driver Adreno bukan ICD-compliant → loader gagal enumerate || Muat driver vendor langsung (vendor-first) + <code>LD_PRELOAD</code> libc++ Termux
|}

== Masalah 1: clinfo melaporkan 0 platform ==

=== Gejala ===

<syntaxhighlight lang="text">
Number of platforms                               0
  ICD loader Name                                 OpenCL ICD Loader
  ICD loader Vendor                               OCL Icd free software
</syntaxhighlight>

Loader-nya kebaca, tapi tidak ada platform OpenCL sama sekali.

=== Penyebab ===

Loader <code>ocl-icd</code> terpasang, tetapi tidak ada driver vendor yang terdaftar. Loader mencari berkas <code>*.icd</code> di <code>$PREFIX/etc/OpenCL/vendors/</code>; kalau kosong, hasilnya 0 platform.

'''Catatan penting:''' driver Adreno <code>/vendor/lib64/libOpenCL.so</code> ternyata '''bukan driver ICD yang patuh''' (tidak meng-export <code>clIcdGetPlatformIDsKHR</code>). Jadi mendaftarkannya ke loader saja '''tidak selalu cukup'''; lihat [[#Masalah 5: "No OpenCL platform" saat program C++ dijalankan|Masalah 5]] untuk gambaran lengkapnya. Cara paling andal adalah memuat driver vendor '''langsung'''.

=== Solusi ===

1. Cari lokasi driver:

<syntaxhighlight lang="bash">
ls -l /vendor/lib64/libOpenCL.so /system/vendor/lib64/libOpenCL.so 2>/dev/null
find /vendor /system -iname 'libOpenCL*.so' 2>/dev/null
</syntaxhighlight>

2. (Opsional, untuk loader) daftarkan ICD:

<syntaxhighlight lang="bash">
mkdir -p $PREFIX/etc/OpenCL/vendors
echo /vendor/lib64/libOpenCL.so > $PREFIX/etc/OpenCL/vendors/adreno.icd
</syntaxhighlight>

3. Saat menjalankan, arahkan loader ke library vendor:

<syntaxhighlight lang="bash">
export LD_LIBRARY_PATH=/vendor/lib64:/system/vendor/lib64:/system/lib64
clinfo
</syntaxhighlight>

Dengan <code>LD_LIBRARY_PATH</code> vendor-first, <code>libOpenCL.so</code> yang dimuat adalah library vendor (driver Adreno) langsung, dan <code>clinfo</code> akan melihat platform "QUALCOMM Snapdragon" / "Adreno (TM) 610".

'''PERINGATAN:''' meng-export <code>LD_LIBRARY_PATH</code> secara '''global''' (mis. di <code>~/.bashrc</code>) akan menimbulkan [[#Masalah 2: clang rusak (cannot locate symbol __ndk1)|Masalah 2]]. Set hanya saat dibutuhkan.

== Masalah 2: clang rusak (cannot locate symbol __ndk1) ==

=== Gejala ===

Setelah meng-export <code>LD_LIBRARY_PATH</code> untuk OpenCL, <code>clang</code>/<code>clang++</code> berhenti bekerja:

<syntaxhighlight lang="text">
CANNOT LINK EXECUTABLE "clang": cannot locate symbol
"_ZNSt6__ndk122__libcpp_verbose_abortEPKcz" referenced by ...
</syntaxhighlight>

Simbol itu kalau di-demangle: <code>std::__ndk1::__libcpp_verbose_abort(char const*, ...)</code>.

=== Penyebab ===

<code>LD_LIBRARY_PATH=/vendor/lib64:/system/lib64</code> yang di-set global membuat Termux memuat '''libc++ milik Android''' dari <code>/system/lib64</code> alih-alih libc++ milik Termux. Keduanya memakai ''inline namespace'' yang berbeda:

* libc++ Termux → <code>std::__ndk1</code>
* libc++ Android → <code>std::__1</code>

clang Termux dikompilasi terhadap <code>__ndk1</code>, sehingga ketika libc++ Android (<code>__1</code>) yang termuat, simbol <code>__ndk1</code> hilang dan clang gagal jalan.

=== Solusi ===

Konfirmasi dulu:

<syntaxhighlight lang="bash">
unset LD_LIBRARY_PATH
clang --version    # kalau jalan lagi, terbukti LD_LIBRARY_PATH penyebabnya
</syntaxhighlight>

'''Prinsipnya: pisahkan environment untuk COMPILE dan RUN.'''

* Saat '''compile/cmake/make''' → <code>LD_LIBRARY_PATH</code> harus '''kosong''' (biar libc++ Termux yang dipakai). Caranya pakai <code>env -u</code>:
<syntaxhighlight lang="bash">
env -u LD_LIBRARY_PATH clang -lOpenCL main.c -o app
env -u LD_LIBRARY_PATH cmake --build build
</syntaxhighlight>
* Saat '''run''' → baru set <code>LD_LIBRARY_PATH</code> ke library vendor, sebagai prefix satu perintah agar otomatis hilang setelahnya:
<syntaxhighlight lang="bash">
LD_LIBRARY_PATH=/vendor/lib64:/system/vendor/lib64:/system/lib64 ./app
</syntaxhighlight>

Jangan menaruh <code>export LD_LIBRARY_PATH=...</code> di <code>~/.bashrc</code>. Untuk compile, driver vendor '''tidak''' dibutuhkan; <code>-lOpenCL</code> hanya butuh loader ocl-icd di <code>$PREFIX/lib</code>; library vendor hanya perlu saat runtime.

== Masalah 3: header C++ OpenCL tidak ada (use of undeclared identifier 'cl') ==

=== Gejala ===

Saat memakai OpenCL C++ bindings, <code>&lt;CL/opencl.hpp&gt;</code> tidak ditemukan. Lalu setelah diganti ke <code>&lt;CL/cl.h&gt;</code>, muncul:

<syntaxhighlight lang="text">
error: use of undeclared identifier 'cl'
static cl::Device pick_gpu(...) { ... }
       ^
error: missing 'template' keyword prior to dependent template name 'getInfo'
</syntaxhighlight>

=== Penyebab ===

Dua hal berbeda:

* <code>&lt;CL/cl.h&gt;</code> adalah header '''C'''; isinya fungsi <code>clGetPlatformIDs</code>, <code>clCreateContext</code>, dst. Header ini '''tidak punya namespace <code>cl::</code>''' sama sekali. Maka semua <code>cl::Platform</code>, <code>cl::Device</code>, dsb. menjadi "undeclared".
* Class <code>cl::*</code> hanya ada di <code>&lt;CL/opencl.hpp&gt;</code> (OpenCL C++ bindings), yang merupakan header '''terpisah''' (paket <code>opencl-clhpp</code>) dan '''bukan''' bagian dari <code>opencl-headers</code>. Header ini sering belum terpasang di Termux.

=== Solusi ===

Dua pilihan:

'''A. Pakai OpenCL C API dari C++''' (paling andal — hanya butuh <code>&lt;CL/cl.h&gt;</code> yang sudah ada). Tetap C++ (pakai <code>std::vector</code>, <code>std::string</code>, <code>iostream</code>), tapi panggil fungsi C:

<syntaxhighlight lang="cpp">
#define CL_TARGET_OPENCL_VERSION 300
#include <CL/cl.h>
// cl_context ctx = clCreateContext(...); dst.
</syntaxhighlight>

'''B. Sediakan header C++ bindings''' kalau memang ingin gaya <code>cl::</code>:

<syntaxhighlight lang="bash">
pkg install opencl-clhpp        # kalau tersedia di repo
# atau ambil manual (header tunggal, hanya butuh cl.h):
mkdir -p CL
curl -L -o CL/opencl.hpp \
  https://github.com/KhronosGroup/OpenCL-CLHPP/raw/main/include/CL/opencl.hpp
</syntaxhighlight>

lalu tambahkan <code>target_include_directories(... PRIVATE ${CMAKE_SOURCE_DIR})</code> di CMake.

== Masalah 4: mpirun signal 31 (Bad system call / SIGSYS) ==

=== Gejala ===

<syntaxhighlight lang="text">
mpirun: Forwarding signal 31 to job
mpirun noticed that process rank 3 with PID 0 on node localhost
exited on signal 31 (Bad system call).
</syntaxhighlight>

Tidak ada output program sama sekali sebelum crash (mati di dalam <code>MPI_Init</code>).

=== Penyebab ===

Signal 31 = '''SIGSYS''' = "Bad system call". Kernel Android memasang filter '''seccomp''' yang memblokir syscall tertentu; saat proses memanggil syscall yang diblokir, proses langsung dibunuh dengan sinyal 31.

Pemicunya: OpenMPI memakai '''hwloc''' untuk mengikat (binding) proses ke core CPU saat <code>MPI_Init</code>, dan binding itu memanggil syscall yang diblokir seccomp Android. Karena ini terjadi saat init (sebelum komunikasi), '''mengganti transport tidak menolong'''.

'''Yang TIDAK menyelesaikan''' (sudah dicoba): <code>--mca btl self,tcp</code> dan <code>--mca btl_vader_single_copy_mechanism none</code> — keduanya tentang ''transport'', padahal masalahnya di ''binding''.

=== Solusi ===

Matikan binding hwloc:

<syntaxhighlight lang="bash">
mpirun -np 4 --oversubscribe \
  --mca hwloc_base_binding_policy none \
  --mca btl tcp,self \
  ./app
</syntaxhighlight>

* <code>--mca hwloc_base_binding_policy none</code> → '''kunci'''-nya; matikan binding yang memicu SIGSYS.
* <code>--mca btl tcp,self</code> → komunikasi lewat TCP loopback (untuk demo ini datanya kecil, jadi tidak masalah).
* <code>--oversubscribe</code> → izinkan proses lebih banyak daripada slot terdeteksi.

Verifikasi cepat dengan program "hello world" MPI minimal sebelum menggabungkan dengan OpenCL.

== Masalah 5: "No OpenCL platform" saat program C++ dijalankan ==

=== Gejala ===

MPI sudah jalan (banner tampil, 4 rank start), tapi tiap rank gagal di OpenCL:

<syntaxhighlight lang="text">
[rank 0] No OpenCL platform
[rank 1] No OpenCL platform
...
</syntaxhighlight>

Anehnya:
* <code>clinfo</code> '''polos''' (env shell vendor-first) → '''menemukan''' Adreno.
* <code>clinfo</code> dengan <code>$PREFIX/lib</code> di depan → '''0 platform'''.

=== Penyebab ===

Ini inti persoalannya. Demi libc++ (Masalah 2), program C++ menaruh <code>$PREFIX/lib</code> '''paling depan''' di <code>LD_LIBRARY_PATH</code>. Akibatnya <code>libOpenCL.so</code> yang termuat adalah '''loader ocl-icd''' (di <code>$PREFIX/lib</code>), bukan driver vendor.

Masalahnya: driver Adreno <code>/vendor/lib64/libOpenCL.so</code> '''bukan driver ICD yang patuh''' — ia adalah implementasi OpenCL lengkap yang berdiri sendiri, tetapi '''tidak meng-export entry point ICD''' (<code>clIcdGetPlatformIDsKHR</code>) yang dipakai loader untuk meng-enumerasi platform. Maka:

* Lewat '''loader''' (saat <code>$PREFIX/lib</code> di depan) → loader bisa memuat driver tapi '''tidak bisa enumerate''' → 0 platform.
* Dimuat '''langsung''' (saat <code>/vendor/lib64</code> di depan) → berhasil, karena fungsi <code>clGetPlatformIDs</code> dipanggil langsung ke driver vendor.

Jadi driver model ini '''harus dimuat langsung''', bukan lewat loader. Tetapi itu berbenturan dengan kebutuhan libc++ Termux yang menuntut <code>$PREFIX/lib</code> di depan.

=== Solusi ===

Muat driver vendor langsung (vendor-first) '''dan''' paksa libc++ Termux lewat <code>LD_PRELOAD</code>:

<syntaxhighlight lang="bash">
LD_LIBRARY_PATH=/vendor/lib64:/system/vendor/lib64:/system/lib64:$PREFIX/lib \
LD_PRELOAD=$PREFIX/lib/libc++_shared.so \
  mpirun --oversubscribe --mca hwloc_base_binding_policy none --mca btl tcp,self \
  -np 4 ./app
</syntaxhighlight>

Cara kerjanya:

* <code>/vendor/lib64</code> di depan → <code>libOpenCL.so</code> menyangkut ke driver Adreno langsung → platform ketemu.
* <code>$PREFIX/lib</code> di paling belakang → cadangan untuk library Termux lain (mis. <code>libmpi.so</code>), yang juga ditemukan lewat RUNPATH binary.
* <code>LD_PRELOAD=$PREFIX/lib/libc++_shared.so</code> → memaksa libc++ Termux (<code>__ndk1</code>) dimuat lebih dulu, sehingga simbol C++ program ter-resolve dengan benar (mencegah crash <code>__ndk1</code>).

'''Catatan:''' cara ini bekerja selama driver vendor memakai <code>libc++.so</code> (platform, soname berbeda) dan/atau tidak meng-link <code>libc++_shared.so</code> secara dinamis. Untuk mengecek dependensi driver:

<syntaxhighlight lang="bash">
readelf -d /vendor/lib64/libOpenCL.so | grep NEEDED
</syntaxhighlight>

Jika di sana muncul <code>libc++_shared.so</code> (akan bentrok dengan preload), alternatifnya adalah '''static-link libc++''' ke binary (tambah <code>-static-libstdc++</code> di kompilasi) sehingga binary tidak butuh libc++ shared sama sekali, lalu <code>LD_PRELOAD</code> bisa dilepas.

== Konfigurasi runtime final ==

Ringkasan resep yang terbukti bekerja end-to-end:

'''Build''' (libc++ Termux, <code>LD_LIBRARY_PATH</code> dibuang):

<syntaxhighlight lang="bash">
env -u LD_LIBRARY_PATH cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
env -u LD_LIBRARY_PATH cmake --build build -j
</syntaxhighlight>

'''Cek GPU''' (driver vendor langsung):

<syntaxhighlight lang="bash">
LD_LIBRARY_PATH=/vendor/lib64:/system/vendor/lib64:/system/lib64:$PREFIX/lib \
  clinfo | head -n 25
</syntaxhighlight>

'''Run''' (driver vendor langsung + libc++ Termux + binding hwloc dimatikan):

<syntaxhighlight lang="bash">
LD_LIBRARY_PATH=/vendor/lib64:/system/vendor/lib64:/system/lib64:$PREFIX/lib \
LD_PRELOAD=$PREFIX/lib/libc++_shared.so \
TMPDIR=$PREFIX/tmp \
  mpirun --oversubscribe --mca hwloc_base_binding_policy none --mca btl tcp,self \
  -np 4 ./build/app <arg...>
</syntaxhighlight>

Tiga prinsip kunci:
# '''Build pakai env bersih''' (<code>env -u LD_LIBRARY_PATH</code>), '''run pakai env vendor''' — jangan dicampur, jangan di-global.
# '''OpenCL''': muat driver vendor '''langsung''' (vendor-first), karena driver Adreno bukan ICD-compliant.
# '''C++ + vendor-first''': pakai <code>LD_PRELOAD</code> libc++ Termux supaya tidak bentrok namespace.

== Catatan ==

* '''"Max clock 1 MHz" dan "1 compute unit"''' yang dilaporkan device '''bukan error/bug kode''' — driver Adreno memang sering melaporkan <code>CL_DEVICE_MAX_CLOCK_FREQUENCY</code> dengan nilai placeholder, dan Adreno meng-expose 1 ''compute unit'' ke OpenCL (normal untuk arsitekturnya). Kernel tetap berjalan paralel di banyak ALU di dalamnya.
* '''Paralelisme''': dengan hanya '''1 GPU''', menjalankan banyak rank MPI tidak mempercepat sisi GPU — rangkaian kernel dari tiap rank di-''serialize'' oleh driver pada GPU yang sama. Sisi CPU (generate data, verifikasi, reduksi) tetap paralel. Paralelisme GPU nyata baru tercapai bila ada '''beberapa GPU''' (mis. cluster beberapa perangkat Android via MPI/TCP), satu rank per GPU.
* <code>$PREFIX</code> Termux = <code>/data/data/com.termux/files/usr</code>. Variabel <code>$PREFIX</code> sudah otomatis ter-set di Termux.

== Lihat pula ==

* [https://github.com/OCL-dev/ocl-icd ocl-icd] — OpenCL ICD loader
* [https://www.open-mpi.org/ Open MPI]
* [https://github.com/KhronosGroup/OpenCL-CLHPP OpenCL-CLHPP] — C++ bindings
* [https://registry.khronos.org/OpenCL/ Spesifikasi OpenCL (Khronos)]