[aot] Removed unused archs in C-API (#7167)

Issue: # Removed unused archs and added a C++ overload to filter archs in `ti::get_available archs`. Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
taichi-dev · Jan 16, 2023 · 80394e9 · 80394e9
1 parent 05e586c
commit 80394e9
Show file tree

Hide file tree

Showing 7 changed files with 101 additions and 64 deletions.
diff --git a/c_api/docs/taichi/taichi_core.h.md b/c_api/docs/taichi/taichi_core.h.md
@@ -10,14 +10,15 @@ Taichi Core exposes all necessary interfaces for offloading the AOT modules to T
 
 Taichi C-API intends to support the following backends:
 
-|Backend     |Offload Target   |Maintenance Tier |
-|------------|-----------------|-----------------|
-|Vulkan      |GPU              |Tier 1           |
-|CUDA (LLVM) |GPU (NVIDIA)     |Tier 1           |
-|CPU (LLVM)  |CPU              |Tier 1           |
-|OpenGL      |GPU              |Tier 2           |
-|DirectX 11  |GPU (Windows)    |N/A              |
-|Metal       |GPU (macOS, iOS) |N/A              |
+|Backend     |Offload Target   |Maintenance Tier | Stabilized? |
+|------------|-----------------|-----------------|-------------|
+|Vulkan      |GPU              |Tier 1           | Yes         |
+|Metal       |GPU (macOS, iOS) |Tier 2           | No          |
+|CUDA (LLVM) |GPU (NVIDIA)     |Tier 2           | No          |
+|CPU (LLVM)  |CPU              |Tier 2           | No          |
+|OpenGL      |GPU              |Tier 2           | No          |
+|OpenGL ES   |GPU              |Tier 2           | No          |
+|DirectX 11  |GPU (Windows)    |N/A              | No          |
 
 The backends with tier-1 support are being developed and tested more intensively. And most new features will be available on Vulkan first because it has the most outstanding cross-platform compatibility among all the tier-1 backends.
 For the backends with tier-2 support, you should expect a delay in the fixes to minor issues.
@@ -263,11 +264,13 @@ Errors reported by the Taichi C-API.
 
 Types of backend archs.
 
+- `enumeration.arch.vulkan`: Vulkan GPU backend.
+- `enumeration.arch.metal`: Metal GPU backend.
+- `enumeration.arch.cuda`: NVIDIA CUDA GPU backend.
 - `enumeration.arch.x64`: x64 native CPU backend.
 - `enumeration.arch.arm64`: Arm64 native CPU backend.
-- `enumeration.arch.cuda`: NVIDIA CUDA GPU backend.
-- `enumeration.arch.vulkan`: Vulkan GPU backend.
 - `enumeration.arch.opengl`: OpenGL GPU backend.
+- `enumeration.arch.gles`: OpenGL ES GPU backend.
 
 `enumeration.capability`
 
@@ -466,6 +469,8 @@ Gets a list of available archs on the current platform. An arch is only availabl
 
 An available arch has at least one device available, i.e., device index 0 is always available. If an arch is not available on the current platform, a call to `function.create_runtime` with that arch is guaranteed failing.
 
+**WARNING** Please also note that the order or returned archs is *undefined*.
+
 `function.get_last_error`
 
 Gets the last error raised by Taichi C-API invocations. Returns the semantical error code.

diff --git a/c_api/include/taichi/cpp/taichi.hpp b/c_api/include/taichi/cpp/taichi.hpp
@@ -1,5 +1,6 @@
 // C++ wrapper of Taichi C-API
 #pragma once
+#include <algorithm>
 #include <cstddef>
 #include <cstring>
 #include <list>
@@ -18,6 +19,18 @@ inline std::vector<TiArch> get_available_archs() {
   ti_get_available_archs(&narch, archs.data());
   return archs;
 }
+inline std::vector<TiArch> get_available_archs(
+    const std::vector<TiArch> &expect_archs) {
+  std::vector<TiArch> actual_archs = get_available_archs();
+  std::vector<TiArch> out_archs;
+  for (TiArch arch : actual_archs) {
+    auto it = std::find(expect_archs.begin(), expect_archs.end(), arch);
+    if (it != expect_archs.end()) {
+      out_archs.emplace_back(arch);
+    }
+  }
+  return out_archs;
+}
 inline bool is_arch_available(TiArch arch) {
   std::vector<TiArch> archs = get_available_archs();
   for (size_t i = 0; i < archs.size(); ++i) {

diff --git a/c_api/include/taichi/taichi_core.h b/c_api/include/taichi/taichi_core.h
@@ -9,14 +9,15 @@
 //
 // Taichi C-API intends to support the following backends:
 //
-// |Backend     |Offload Target   |Maintenance Tier |
-// |------------|-----------------|-----------------|
-// |Vulkan      |GPU              |Tier 1           |
-// |CUDA (LLVM) |GPU (NVIDIA)     |Tier 1           |
-// |CPU (LLVM)  |CPU              |Tier 1           |
-// |OpenGL      |GPU              |Tier 2           |
-// |DirectX 11  |GPU (Windows)    |N/A              |
-// |Metal       |GPU (macOS, iOS) |N/A              |
+// |Backend     |Offload Target   |Maintenance Tier | Stabilized? |
+// |------------|-----------------|-----------------|-------------|
+// |Vulkan      |GPU              |Tier 1           | Yes         |
+// |Metal       |GPU (macOS, iOS) |Tier 2           | No          |
+// |CUDA (LLVM) |GPU (NVIDIA)     |Tier 2           | No          |
+// |CPU (LLVM)  |CPU              |Tier 2           | No          |
+// |OpenGL      |GPU              |Tier 2           | No          |
+// |OpenGL ES   |GPU              |Tier 2           | No          |
+// |DirectX 11  |GPU (Windows)    |N/A              | No          |
 //
 // The backends with tier-1 support are being developed and tested more
 // intensively. And most new features will be available on Vulkan first because
@@ -226,7 +227,7 @@
 #pragma once
 
 #ifndef TI_C_API_VERSION
-#define TI_C_API_VERSION 1004000
+#define TI_C_API_VERSION 1005000
 #endif  // TI_C_API_VERSION
 
 #include <taichi/taichi.h>
@@ -353,25 +354,21 @@ typedef enum TiError {
 //
 // Types of backend archs.
 typedef enum TiArch {
+  TI_ARCH_RESERVED = 0,
+  // Vulkan GPU backend.
+  TI_ARCH_VULKAN = 1,
+  // Metal GPU backend.
+  TI_ARCH_METAL = 2,
+  // NVIDIA CUDA GPU backend.
+  TI_ARCH_CUDA = 3,
   // x64 native CPU backend.
-  TI_ARCH_X64 = 0,
+  TI_ARCH_X64 = 4,
   // Arm64 native CPU backend.
-  TI_ARCH_ARM64 = 1,
-  TI_ARCH_JS = 2,
-  TI_ARCH_CC = 3,
-  TI_ARCH_WASM = 4,
-  // NVIDIA CUDA GPU backend.
-  TI_ARCH_CUDA = 5,
-  TI_ARCH_METAL = 6,
+  TI_ARCH_ARM64 = 5,
   // OpenGL GPU backend.
-  TI_ARCH_OPENGL = 7,
-  TI_ARCH_DX11 = 8,
-  TI_ARCH_DX12 = 9,
-  TI_ARCH_OPENCL = 10,
-  TI_ARCH_AMDGPU = 11,
-  // Vulkan GPU backend.
-  TI_ARCH_VULKAN = 12,
-  TI_ARCH_GLES = 13,
+  TI_ARCH_OPENGL = 6,
+  // OpenGL ES GPU backend.
+  TI_ARCH_GLES = 7,
   TI_ARCH_MAX_ENUM = 0xffffffff,
 } TiArch;
 
@@ -825,7 +822,8 @@ TI_DLL_EXPORT uint32_t TI_API_CALL ti_get_version();
 // An available arch has at least one device available, i.e., device index 0 is
 // always available. If an arch is not available on the current platform, a call
 // to [`ti_create_runtime`](#function-ti_create_runtime) with that arch is
-// guaranteed failing.
+// guaranteed failing. Please also note that the order or returned archs is
+// **undefined**.
 TI_DLL_EXPORT void TI_API_CALL ti_get_available_archs(uint32_t *arch_count,
                                                       TiArch *archs);
 

diff --git a/c_api/src/taichi_core_impl.cpp b/c_api/src/taichi_core_impl.cpp
@@ -155,8 +155,8 @@ void ti_get_available_archs(uint32_t *arch_count, TiArch *archs) {
     if (is_vulkan_available()) {
       AVAILABLE_ARCHS.emplace_back(TI_ARCH_VULKAN);
     }
-    if (is_opengl_available()) {
-      AVAILABLE_ARCHS.emplace_back(TI_ARCH_OPENGL);
+    if (is_metal_available()) {
+      AVAILABLE_ARCHS.emplace_back(TI_ARCH_METAL);
     }
     if (is_cuda_available()) {
       AVAILABLE_ARCHS.emplace_back(TI_ARCH_CUDA);
@@ -167,6 +167,9 @@ void ti_get_available_archs(uint32_t *arch_count, TiArch *archs) {
     if (is_arm64_available()) {
       AVAILABLE_ARCHS.emplace_back(TI_ARCH_ARM64);
     }
+    if (is_opengl_available()) {
+      AVAILABLE_ARCHS.emplace_back(TI_ARCH_OPENGL);
+    }
   }
 
   size_t n = std::min((size_t)*arch_count, AVAILABLE_ARCHS.size());

diff --git a/c_api/taichi.json b/c_api/taichi.json
@@ -110,7 +110,16 @@
                     "name": "arch",
                     "type": "enumeration",
                     "since": "v1.4.0",
-                    "inc_cases": "PER_ARCH"
+                    "cases": {
+                        "reserved": 0,
+                        "vulkan": 1,
+                        "metal": 2,
+                        "cuda": 3,
+                        "x64": 4,
+                        "arm64": 5,
+                        "opengl": 6,
+                        "gles": 7
+                    }
                 },
                 {
                     "name": "capability",

diff --git a/c_api/tests/c_api_interface_test.cpp b/c_api/tests/c_api_interface_test.cpp
@@ -6,6 +6,18 @@
 TEST_F(CapiTest, DryRunAvailableArchs) {
   std::vector<TiArch> archs = ti::get_available_archs();
 }
+TEST_F(CapiTest, GetAvailableArchsWithFilter) {
+  std::vector<TiArch> expect_archs = ti::get_available_archs();
+  expect_archs.pop_back();
+
+  std::vector<TiArch> actual_archs = ti::get_available_archs(expect_archs);
+
+  TI_ASSERT(actual_archs.size() == expect_archs.size());
+
+  for (size_t i = 0; i < actual_archs.size(); ++i) {
+    TI_ASSERT(actual_archs.at(i) == expect_archs.at(i));
+  }
+}
 
 TEST_F(CapiTest, DryRunRuntime) {
   {

diff --git a/docs/lang/articles/c-api/taichi_core.md b/docs/lang/articles/c-api/taichi_core.md
@@ -10,14 +10,15 @@ Taichi Core exposes all necessary interfaces for offloading the AOT modules to T
 
 Taichi C-API intends to support the following backends:
 
-|Backend     |Offload Target   |Maintenance Tier |
-|------------|-----------------|-----------------|
-|Vulkan      |GPU              |Tier 1           |
-|CUDA (LLVM) |GPU (NVIDIA)     |Tier 1           |
-|CPU (LLVM)  |CPU              |Tier 1           |
-|OpenGL      |GPU              |Tier 2           |
-|DirectX 11  |GPU (Windows)    |N/A              |
-|Metal       |GPU (macOS, iOS) |N/A              |
+|Backend     |Offload Target   |Maintenance Tier | Stabilized? |
+|------------|-----------------|-----------------|-------------|
+|Vulkan      |GPU              |Tier 1           | Yes         |
+|Metal       |GPU (macOS, iOS) |Tier 2           | No          |
+|CUDA (LLVM) |GPU (NVIDIA)     |Tier 2           | No          |
+|CPU (LLVM)  |CPU              |Tier 2           | No          |
+|OpenGL      |GPU              |Tier 2           | No          |
+|OpenGL ES   |GPU              |Tier 2           | No          |
+|DirectX 11  |GPU (Windows)    |N/A              | No          |
 
 The backends with tier-1 support are being developed and tested more intensively. And most new features will be available on Vulkan first because it has the most outstanding cross-platform compatibility among all the tier-1 backends.
 For the backends with tier-2 support, you should expect a delay in the fixes to minor issues.
@@ -368,31 +369,27 @@ Errors reported by the Taichi C-API.
 ```c
 // enumeration.arch
 typedef enum TiArch {
-  TI_ARCH_X64 = 0,
-  TI_ARCH_ARM64 = 1,
-  TI_ARCH_JS = 2,
-  TI_ARCH_CC = 3,
-  TI_ARCH_WASM = 4,
-  TI_ARCH_CUDA = 5,
-  TI_ARCH_METAL = 6,
-  TI_ARCH_OPENGL = 7,
-  TI_ARCH_DX11 = 8,
-  TI_ARCH_DX12 = 9,
-  TI_ARCH_OPENCL = 10,
-  TI_ARCH_AMDGPU = 11,
-  TI_ARCH_VULKAN = 12,
-  TI_ARCH_GLES = 13,
+  TI_ARCH_RESERVED = 0,
+  TI_ARCH_VULKAN = 1,
+  TI_ARCH_METAL = 2,
+  TI_ARCH_CUDA = 3,
+  TI_ARCH_X64 = 4,
+  TI_ARCH_ARM64 = 5,
+  TI_ARCH_OPENGL = 6,
+  TI_ARCH_GLES = 7,
   TI_ARCH_MAX_ENUM = 0xffffffff,
 } TiArch;
 ```
 
 Types of backend archs.
 
+- `TI_ARCH_VULKAN`: Vulkan GPU backend.
+- `TI_ARCH_METAL`: Metal GPU backend.
+- `TI_ARCH_CUDA`: NVIDIA CUDA GPU backend.
 - `TI_ARCH_X64`: x64 native CPU backend.
 - `TI_ARCH_ARM64`: Arm64 native CPU backend.
-- `TI_ARCH_CUDA`: NVIDIA CUDA GPU backend.
-- `TI_ARCH_VULKAN`: Vulkan GPU backend.
 - `TI_ARCH_OPENGL`: OpenGL GPU backend.
+- `TI_ARCH_GLES`: OpenGL ES GPU backend.
 
 ---
 ### Enumeration `TiCapability`
@@ -964,7 +961,7 @@ Gets a list of available archs on the current platform. An arch is only availabl
 1. The Runtime library is compiled with its support;
 2. The current platform is installed with a capable hardware or an emulation software.
 
-An available arch has at least one device available, i.e., device index 0 is always available. If an arch is not available on the current platform, a call to [`ti_create_runtime`](#function-ti_create_runtime) with that arch is guaranteed failing.
+An available arch has at least one device available, i.e., device index 0 is always available. If an arch is not available on the current platform, a call to [`ti_create_runtime`](#function-ti_create_runtime) with that arch is guaranteed failing. Please also note that the order or returned archs is **undefined**.
 
 ---
 ### Function `ti_get_last_error`