Skip to content

Commit

Permalink
[aot] C-API breaking changes! (#6955)
Browse files Browse the repository at this point in the history 
Issue: #6693, taichi-dev/taichi-aot-demo#101,
taichi-dev/taichi-unity2#9

### Brief Summary

This PR introduced the breaking changes listed in #6693.

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
@PENGUINLIONG @pre-commit-ci
PENGUINLIONG and pre-commit-ci[bot] authored Dec 23, 2022
1 parent bbe38aa commit aa46e71
Show file tree
Hide file tree
Showing 25 changed files with 62 additions and 651 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/scripts/aot-demo.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ set -ex
export TI_SKIP_VERSION_CHECK=ON
export TI_CI=1

export TAICHI_AOT_DEMO_URL=https://github.com/taichi-dev/taichi-aot-demo
export TAICHI_AOT_DEMO_BRANCH=master
export TAICHI_AOT_DEMO_URL=https://github.com/PENGUINLIONG/taichi-aot-demo
export TAICHI_AOT_DEMO_BRANCH=fix-cgraph-demo

export TAICHI_UNITY2_URL=https://github.com/taichi-dev/taichi-unity2
export TAICHI_UNITY2_BRANCH=main
export TAICHI_UNITY2_BRANCH=fix-include

export TAICHI_UNITY_EXAMPLE_URL=https://github.com/taichi-dev/Taichi-UnityExample
export TAICHI_UNITY_EXAMPLE_BRANCH=main
Expand Down
34 changes: 9 additions & 25 deletions c_api/docs/taichi/taichi_core.h.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ The following section provides a brief introduction to the Taichi C-API.
You *must* create a runtime instance before working with Taichi, and *only* one runtime per thread. Currently, we do not officially claim that multiple runtime instances can coexist in a process, but please feel free to [file an issue with us](https://github.com/taichi-dev/taichi/issues) if you run into any problem with runtime instance coexistence.

```cpp
TiRuntime runtime = ti_create_runtime(TI_ARCH_VULKAN);
// Create a Taichi Runtime on Vulkan device at index 0.
TiRuntime runtime = ti_create_runtime(TI_ARCH_VULKAN, 0);
```

When your program runs to the end, ensure that:
Expand Down Expand Up @@ -116,7 +117,7 @@ TiAotModule aot_module = ti_load_aot_module(runtime, "/path/to/aot/module");

`/path/to/aot/module` should point to the directory that contains a `metadata.tcb`.

You can destroy an unused AOT module, but please ensure that there is no kernel or compute graph related to it pending to [`ti_submit`](#function-ti_submit).
You can destroy an unused AOT module, but please ensure that there is no kernel or compute graph related to it pending to [`ti_flush`](#function-ti_flush).

```cpp
ti_destroy_aot_module(aot_module);
Expand Down Expand Up @@ -177,10 +178,10 @@ named_arg2.argument = args[2];
ti_launch_compute_graph(runtime, compute_graph, named_args.size(), named_args.data());
```

When you have launched all kernels and compute graphs for this batch, you should `function.submit` and `function.wait` for the execution to finish.
When you have launched all kernels and compute graphs for this batch, you should `function.flush` and `function.wait` for the execution to finish.

```cpp
ti_submit(runtime);
ti_flush(runtime);
ti_wait(runtime);
```
Expand Down Expand Up @@ -467,6 +468,9 @@ Sets the provided error as the last error raised by Taichi C-API invocations. It
Creates a Taichi Runtime with the specified `enumeration.arch`.
- `function.create_runtime.arch`: Arch of Taichi Runtime.
- `function.create_runtime.device_index`: The index of device in `function.create_runtime.arch` to create Taichi Runtime on.
`function.destroy_runtime`
Destroys a Taichi Runtime.
Expand Down Expand Up @@ -502,14 +506,6 @@ Allocates a device image with provided parameters.
Frees an image allocation.
`function.create_event`
Creates an event primitive.
`function.destroy_event`
Destroys an event primitive.
`function.copy_memory_device_to_device`
Copies the data in a contiguous subsection of the device memory to another subsection. The two subsections *must not* overlap.
Expand All @@ -534,19 +530,7 @@ Launches a Taichi kernel with the provided arguments. The arguments *must* have
Launches a Taichi compute graph with provided named arguments. The named arguments *must* have the same count, names, and types as in the source code.
`function.signal_event`
Sets an event primitive to a signaled state so that the queues waiting for it can go on execution. If the event has been signaled, you *must* call `function.reset_event` to reset it; otherwise, an undefined behavior would occur.
`function.reset_event`
Sets a signaled event primitive back to an unsignaled state.
`function.wait_event`
Waits until an event primitive transitions to a signaled state. The awaited event *must* be signaled by an external procedure or a previous invocation to `function.reset_event`; otherwise, an undefined behavior would occur.
`function.submit`
`function.flush`
Submits all previously invoked device commands to the offload device for execution.
Expand Down
64 changes: 6 additions & 58 deletions c_api/include/taichi/cpp/taichi.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -685,60 +685,6 @@ class AotModule {
}
};

class Event {
TiRuntime runtime_{TI_NULL_HANDLE};
TiEvent event_{TI_NULL_HANDLE};
bool should_destroy_{false};

public:
constexpr bool is_valid() const {
return event_ != nullptr;
}
inline void destroy() {
if (should_destroy_) {
ti_destroy_event(event_);
event_ = TI_NULL_HANDLE;
should_destroy_ = false;
}
}

Event() {
}
Event(const Event &) = delete;
Event(Event &&b) : event_(b.event_), should_destroy_(b.should_destroy_) {
}
Event(TiRuntime runtime, TiEvent event, bool should_destroy)
: runtime_(runtime), event_(event), should_destroy_(should_destroy) {
}
~Event() {
destroy();
}

Event &operator=(const Event &) = delete;
Event &operator=(Event &&b) {
event_ = detail::move_handle(b.event_);
should_destroy_ = std::exchange(b.should_destroy_, false);
return *this;
}

void reset(TiEvent event_) {
ti_reset_event(runtime_, event_);
}
void signal(TiEvent event_) {
ti_signal_event(runtime_, event_);
}
void wait(TiEvent event_) {
ti_wait_event(runtime_, event_);
}

constexpr TiEvent event() const {
return event_;
}
constexpr operator TiEvent() const {
return event_;
}
};

class CapabilityLevelConfigBuilder;
class CapabilityLevelConfig {
public:
Expand Down Expand Up @@ -937,8 +883,10 @@ class Runtime {
runtime_(detail::move_handle(b.runtime_)),
should_destroy_(std::exchange(b.should_destroy_, false)) {
}
Runtime(TiArch arch)
: arch_(arch), runtime_(ti_create_runtime(arch)), should_destroy_(true) {
Runtime(TiArch arch, uint32_t device_index = 0)
: arch_(arch),
runtime_(ti_create_runtime(arch, device_index)),
should_destroy_(true) {
}
Runtime(TiArch arch, TiRuntime runtime, bool should_destroy)
: arch_(arch), runtime_(runtime), should_destroy_(should_destroy) {
Expand Down Expand Up @@ -1071,8 +1019,8 @@ class Runtime {
ti_transition_image(runtime_, image, layout);
}

void submit() {
ti_submit(runtime_);
void flush() {
ti_flush(runtime_);
}
void wait() {
ti_wait(runtime_);
Expand Down
14 changes: 0 additions & 14 deletions c_api/include/taichi/taichi.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,14 @@
#include "taichi/taichi_core.h"

#ifdef TI_WITH_VULKAN
#ifndef TI_NO_VULKAN_INCLUDES
#include <vulkan/vulkan.h>
#endif // TI_NO_VULKAN_INCLUDES

#include "taichi/taichi_vulkan.h"
#endif // TI_WITH_VULKAN

#ifdef TI_WITH_OPENGL
#ifndef TI_NO_OPENGL_INCLUDES
#include <GL/gl.h>
#endif // TI_NO_OPENGL_INCLUDES

#include "taichi/taichi_opengl.h"
#endif // TI_WITH_OPENGL

#ifdef TI_WITH_CUDA
#ifndef TI_NO_CUDA_INCLUDES
// Only a few CUDA types is needed, including the entire <cuda.h> is overkill
// for this
typedef void *CUdeviceptr;
#endif // TI_NO_CUDA_INCLUDES

#include "taichi/taichi_cuda.h"
#endif // TI_WITH_CUDA

Expand Down
58 changes: 13 additions & 45 deletions c_api/include/taichi/taichi_core.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@
// any problem with runtime instance coexistence.
//
// ```cpp
// TiRuntime runtime = ti_create_runtime(TI_ARCH_VULKAN);
// // Create a Taichi Runtime on Vulkan device at index 0.
// TiRuntime runtime = ti_create_runtime(TI_ARCH_VULKAN, 0);
// ```
//
// When your program runs to the end, ensure that:
Expand Down Expand Up @@ -144,7 +145,7 @@
//
// You can destroy an unused AOT module, but please ensure that there is no
// kernel or compute graph related to it pending to
// [`ti_submit`](#function-ti_submit).
// [`ti_flush`](#function-ti_flush).
//
// ```cpp
// ti_destroy_aot_module(aot_module);
Expand Down Expand Up @@ -211,11 +212,11 @@
// ```
//
// When you have launched all kernels and compute graphs for this batch, you
// should [`ti_submit`](#function-ti_submit) and [`ti_wait`](#function-ti_wait)
// should [`ti_flush`](#function-ti_flush) and [`ti_wait`](#function-ti_wait)
// for the execution to finish.
//
// ```cpp
// ti_submit(runtime);
// ti_flush(runtime);
// ti_wait(runtime);
// ```
//
Expand Down Expand Up @@ -281,12 +282,6 @@ typedef struct TiRuntime_t *TiRuntime;
// kernels and compute graphs.
typedef struct TiAotModule_t *TiAotModule;

// Handle `TiEvent`
//
// A synchronization primitive to manage device execution flows in multiple
// queues.
typedef struct TiEvent_t *TiEvent;

// Handle `TiMemory`
//
// A contiguous allocation of device memory.
Expand Down Expand Up @@ -845,7 +840,12 @@ TI_DLL_EXPORT void TI_API_CALL ti_set_last_error(
// Function `ti_create_runtime`
//
// Creates a Taichi Runtime with the specified [`TiArch`](#enumeration-tiarch).
TI_DLL_EXPORT TiRuntime TI_API_CALL ti_create_runtime(TiArch arch);
TI_DLL_EXPORT TiRuntime TI_API_CALL ti_create_runtime(
// Arch of Taichi Runtime.
TiArch arch,
// The index of device in `function.create_runtime.arch` to create Taichi
// Runtime on.
uint32_t device_index);

// Function `ti_destroy_runtime`
//
Expand Down Expand Up @@ -915,16 +915,6 @@ ti_create_sampler(TiRuntime runtime, const TiSamplerCreateInfo *create_info);
TI_DLL_EXPORT void TI_API_CALL ti_destroy_sampler(TiRuntime runtime,
TiSampler sampler);

// Function `ti_create_event`
//
// Creates an event primitive.
TI_DLL_EXPORT TiEvent TI_API_CALL ti_create_event(TiRuntime runtime);

// Function `ti_destroy_event`
//
// Destroys an event primitive.
TI_DLL_EXPORT void TI_API_CALL ti_destroy_event(TiEvent event);

// Function `ti_copy_memory_device_to_device` (Device Command)
//
// Copies the data in a contiguous subsection of the device memory to another
Expand Down Expand Up @@ -980,33 +970,11 @@ ti_launch_compute_graph(TiRuntime runtime,
uint32_t arg_count,
const TiNamedArgument *args);

// Function `ti_signal_event` (Device Command)
//
// Sets an event primitive to a signaled state so that the queues waiting for it
// can go on execution. If the event has been signaled, you *must* call
// [`ti_reset_event`](#function-ti_reset_event-device-command) to reset it;
// otherwise, an undefined behavior would occur.
TI_DLL_EXPORT void TI_API_CALL ti_signal_event(TiRuntime runtime,
TiEvent event);

// Function `ti_reset_event` (Device Command)
//
// Sets a signaled event primitive back to an unsignaled state.
TI_DLL_EXPORT void TI_API_CALL ti_reset_event(TiRuntime runtime, TiEvent event);

// Function `ti_wait_event` (Device Command)
//
// Waits until an event primitive transitions to a signaled state. The awaited
// event *must* be signaled by an external procedure or a previous invocation to
// [`ti_reset_event`](#function-ti_reset_event-device-command); otherwise, an
// undefined behavior would occur.
TI_DLL_EXPORT void TI_API_CALL ti_wait_event(TiRuntime runtime, TiEvent event);

// Function `ti_submit`
// Function `ti_flush`
//
// Submits all previously invoked device commands to the offload device for
// execution.
TI_DLL_EXPORT void TI_API_CALL ti_submit(TiRuntime runtime);
TI_DLL_EXPORT void TI_API_CALL ti_flush(TiRuntime runtime);

// Function `ti_wait`
//
Expand Down
24 changes: 0 additions & 24 deletions c_api/include/taichi/taichi_vulkan.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,15 +89,6 @@ typedef struct TiVulkanImageInteropInfo {
VkImageUsageFlags usage;
} TiVulkanImageInteropInfo;

// Structure `TiVulkanEventInteropInfo`
//
// Necessary detail to share the same Vulkan event synchronization primitive
// between Taichi and the user application.
typedef struct TiVulkanEventInteropInfo {
// Vulkan event handle.
VkEvent event;
} TiVulkanEventInteropInfo;

// Function `ti_create_vulkan_runtime_ext`
//
// Creates a Vulkan Taichi runtime with user-controlled capability settings.
Expand Down Expand Up @@ -153,21 +144,6 @@ ti_export_vulkan_image(TiRuntime runtime,
TiImage image,
TiVulkanImageInteropInfo *interop_info);

// Function `ti_import_vulkan_event`
//
// Imports the Vulkan event owned by Taichi to external procedures.
TI_DLL_EXPORT TiEvent TI_API_CALL
ti_import_vulkan_event(TiRuntime runtime,
const TiVulkanEventInteropInfo *interop_info);

// Function `ti_export_vulkan_event`
//
// Exports a Vulkan event from external procedures to Taichi.
TI_DLL_EXPORT void TI_API_CALL
ti_export_vulkan_event(TiRuntime runtime,
TiEvent event,
TiVulkanEventInteropInfo *interop_info);

#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
Loading

0 comments on commit aa46e71

Please sign in to comment.