// WebAssembly C API #ifndef __WASM_H #define __WASM_H #include <stddef.h> #include <stdint.h> #include <stdbool.h> #include <string.h> #include <assert.h> #ifdef __cplusplus extern "C" { #endif /////////////////////////////////////////////////////////////////////////////// // Auxiliaries // Machine types inline void assertions() { static_assert(sizeof(float) == sizeof(uint32_t), "incompatible float type"); static_assert(sizeof(double) == sizeof(uint64_t), "incompatible double type"); static_assert(sizeof(intptr_t) == sizeof(uint32_t) || sizeof(intptr_t) == sizeof(uint64_t), "incompatible pointer type"); } typedef char byte_t; typedef float float32_t; typedef double float64_t; // Ownership #define own // The qualifier `own` is used to indicate ownership of data in this API. // It is intended to be interpreted similar to a `const` qualifier: // // - `own wasm_xxx_t*` owns the pointed-to data // - `own wasm_xxx_t` distributes to all fields of a struct or union `xxx` // - `own wasm_xxx_vec_t` owns the vector as well as its elements(!) // - an `own` function parameter passes ownership from caller to callee // - an `own` function result passes ownership from callee to caller // - an exception are `own` pointer parameters named `out`, which are copy-back // output parameters passing back ownership from callee to caller // // Own data is created by `wasm_xxx_new` functions and some others. // It must be released with the corresponding `wasm_xxx_delete` function. // // Deleting a reference does not necessarily delete the underlying object, // it merely indicates that this owner no longer uses it. // // For vectors, `const wasm_xxx_vec_t` is used informally to indicate that // neither the vector nor its elements should be modified. // TODO: introduce proper `wasm_xxx_const_vec_t`? #define WASM_DECLARE_OWN(name) \ typedef struct wasm_##name##_t wasm_##name##_t; \ \ void wasm_##name##_delete(own wasm_##name##_t*); // Vectors #define WASM_DECLARE_VEC(name, ptr_or_none) \ typedef struct wasm_##name##_vec_t { \ size_t size; \ wasm_##name##_t ptr_or_none* data; \ } wasm_##name##_vec_t; \ \ void wasm_##name##_vec_new_empty(own wasm_##name##_vec_t* out); \ void wasm_##name##_vec_new_uninitialized( \ own wasm_##name##_vec_t* out, size_t); \ void wasm_##name##_vec_new( \ own wasm_##name##_vec_t* out, \ size_t, own wasm_##name##_t ptr_or_none const[]); \ void wasm_##name##_vec_copy( \ own wasm_##name##_vec_t* out, wasm_##name##_vec_t*); \ void wasm_##name##_vec_delete(own wasm_##name##_vec_t*); // Byte vectors typedef byte_t wasm_byte_t; WASM_DECLARE_VEC(byte, ) typedef wasm_byte_vec_t wasm_name_t; #define wasm_name wasm_byte_vec #define wasm_name_new wasm_byte_vec_new #define wasm_name_new_empty wasm_byte_vec_new_empty #define wasm_name_new_new_uninitialized wasm_byte_vec_new_uninitialized #define wasm_name_copy wasm_byte_vec_copy #define wasm_name_delete wasm_byte_vec_delete static inline void wasm_name_new_from_string( own wasm_name_t* out, const char* s ) { wasm_name_new(out, strlen(s) + 1, s); } /////////////////////////////////////////////////////////////////////////////// // Runtime Environment // Configuration WASM_DECLARE_OWN(config) own wasm_config_t* wasm_config_new(); // Embedders may provide custom functions for manipulating configs. // Engine WASM_DECLARE_OWN(engine) own wasm_engine_t* wasm_engine_new(); own wasm_engine_t* wasm_engine_new_with_config(own wasm_config_t*); // Store WASM_DECLARE_OWN(store) own wasm_store_t* wasm_store_new(wasm_engine_t*); /////////////////////////////////////////////////////////////////////////////// // Type Representations // Type attributes typedef uint8_t wasm_mutability_t; enum wasm_mutability_enum { WASM_CONST, WASM_VAR, }; typedef struct wasm_limits_t { uint32_t min; uint32_t max; } wasm_limits_t; static const uint32_t wasm_limits_max_default = 0xffffffff; // Generic #define WASM_DECLARE_TYPE(name) \ WASM_DECLARE_OWN(name) \ WASM_DECLARE_VEC(name, *) \ \ own wasm_##name##_t* wasm_##name##_copy(wasm_##name##_t*); // Value Types WASM_DECLARE_TYPE(valtype) typedef uint8_t wasm_valkind_t; enum wasm_valkind_enum { WASM_I32, WASM_I64, WASM_F32, WASM_F64, WASM_ANYREF = 128, WASM_FUNCREF, }; own wasm_valtype_t* wasm_valtype_new(wasm_valkind_t); wasm_valkind_t wasm_valtype_kind(const wasm_valtype_t*); static inline bool wasm_valkind_is_num(wasm_valkind_t k) { return k < WASM_ANYREF; } static inline bool wasm_valkind_is_ref(wasm_valkind_t k) { return k >= WASM_ANYREF; } static inline bool wasm_valtype_is_num(const wasm_valtype_t* t) { return wasm_valkind_is_num(wasm_valtype_kind(t)); } static inline bool wasm_valtype_is_ref(const wasm_valtype_t* t) { return wasm_valkind_is_ref(wasm_valtype_kind(t)); } // Function Types WASM_DECLARE_TYPE(functype) own wasm_functype_t* wasm_functype_new( own wasm_valtype_vec_t* params, own wasm_valtype_vec_t* results); const wasm_valtype_vec_t* wasm_functype_params(const wasm_functype_t*); const wasm_valtype_vec_t* wasm_functype_results(const wasm_functype_t*); // Global Types WASM_DECLARE_TYPE(globaltype) own wasm_globaltype_t* wasm_globaltype_new( own wasm_valtype_t*, wasm_mutability_t); const wasm_valtype_t* wasm_globaltype_content(const wasm_globaltype_t*); wasm_mutability_t wasm_globaltype_mutability(const wasm_globaltype_t*); // Table Types WASM_DECLARE_TYPE(tabletype) own wasm_tabletype_t* wasm_tabletype_new( own wasm_valtype_t*, const wasm_limits_t*); const wasm_valtype_t* wasm_tabletype_element(const wasm_tabletype_t*); const wasm_limits_t* wasm_tabletype_limits(const wasm_tabletype_t*); // Memory Types WASM_DECLARE_TYPE(memorytype) own wasm_memorytype_t* wasm_memorytype_new(const wasm_limits_t*); const wasm_limits_t* wasm_memorytype_limits(const wasm_memorytype_t*); // Extern Types WASM_DECLARE_TYPE(externtype) typedef uint8_t wasm_externkind_t; enum wasm_externkind_enum { WASM_EXTERN_FUNC, WASM_EXTERN_GLOBAL, WASM_EXTERN_TABLE, WASM_EXTERN_MEMORY, }; wasm_externkind_t wasm_externtype_kind(const wasm_externtype_t*); wasm_externtype_t* wasm_functype_as_externtype(wasm_functype_t*); wasm_externtype_t* wasm_globaltype_as_externtype(wasm_globaltype_t*); wasm_externtype_t* wasm_tabletype_as_externtype(wasm_tabletype_t*); wasm_externtype_t* wasm_memorytype_as_externtype(wasm_memorytype_t*); wasm_functype_t* wasm_externtype_as_functype(wasm_externtype_t*); wasm_globaltype_t* wasm_externtype_as_globaltype(wasm_externtype_t*); wasm_tabletype_t* wasm_externtype_as_tabletype(wasm_externtype_t*); wasm_memorytype_t* wasm_externtype_as_memorytype(wasm_externtype_t*); const wasm_externtype_t* wasm_functype_as_externtype_const(const wasm_functype_t*); const wasm_externtype_t* wasm_globaltype_as_externtype_const(const wasm_globaltype_t*); const wasm_externtype_t* wasm_tabletype_as_externtype_const(const wasm_tabletype_t*); const wasm_externtype_t* wasm_memorytype_as_externtype_const(const wasm_memorytype_t*); const wasm_functype_t* wasm_externtype_as_functype_const(const wasm_externtype_t*); const wasm_globaltype_t* wasm_externtype_as_globaltype_const(const wasm_externtype_t*); const wasm_tabletype_t* wasm_externtype_as_tabletype_const(const wasm_externtype_t*); const wasm_memorytype_t* wasm_externtype_as_memorytype_const(const wasm_externtype_t*); // Import Types WASM_DECLARE_TYPE(importtype) own wasm_importtype_t* wasm_importtype_new( own wasm_name_t* module, own wasm_name_t* name, own wasm_externtype_t*); const wasm_name_t* wasm_importtype_module(const wasm_importtype_t*); const wasm_name_t* wasm_importtype_name(const wasm_importtype_t*); const wasm_externtype_t* wasm_importtype_type(const wasm_importtype_t*); // Export Types WASM_DECLARE_TYPE(exporttype) own wasm_exporttype_t* wasm_exporttype_new( own wasm_name_t*, own wasm_externtype_t*); const wasm_name_t* wasm_exporttype_name(const wasm_exporttype_t*); const wasm_externtype_t* wasm_exporttype_type(const wasm_exporttype_t*); /////////////////////////////////////////////////////////////////////////////// // Runtime Objects // Values struct wasm_ref_t; typedef struct wasm_val_t { wasm_valkind_t kind; union { int32_t i32; int64_t i64; float32_t f32; float64_t f64; struct wasm_ref_t* ref; } of; } wasm_val_t; void wasm_val_delete(own wasm_val_t* v); void wasm_val_copy(own wasm_val_t* out, const wasm_val_t*); WASM_DECLARE_VEC(val, ) // References #define WASM_DECLARE_REF_BASE(name) \ WASM_DECLARE_OWN(name) \ \ own wasm_##name##_t* wasm_##name##_copy(const wasm_##name##_t*); \ bool wasm_##name##_same(const wasm_##name##_t*, const wasm_##name##_t*); \ \ void* wasm_##name##_get_host_info(const wasm_##name##_t*); \ void wasm_##name##_set_host_info(wasm_##name##_t*, void*); \ void wasm_##name##_set_host_info_with_finalizer(wasm_##name##_t*, void*, \ void (*)(void*)); #define WASM_DECLARE_REF(name) \ WASM_DECLARE_REF_BASE(name) \ \ wasm_ref_t* wasm_##name##_as_ref(wasm_##name##_t*); \ wasm_##name##_t* wasm_ref_as_##name(wasm_ref_t*); \ const wasm_ref_t* wasm_##name##_as_ref_const(const wasm_##name##_t*); \ const wasm_##name##_t* wasm_ref_as_##name##_const(const wasm_ref_t*); #define WASM_DECLARE_SHARABLE_REF(name) \ WASM_DECLARE_REF(name) \ WASM_DECLARE_OWN(shared_##name) \ \ own wasm_shared_##name##_t* wasm_##name##_share(const wasm_##name##_t*); \ own wasm_##name##_t* wasm_##name##_obtain(wasm_store_t*, const wasm_shared_##name##_t*); WASM_DECLARE_REF_BASE(ref) // Frames WASM_DECLARE_OWN(frame) WASM_DECLARE_VEC(frame, *) own wasm_frame_t* wasm_frame_copy(const wasm_frame_t*); struct wasm_instance_t* wasm_frame_instance(const wasm_frame_t*); uint32_t wasm_frame_func_index(const wasm_frame_t*); size_t wasm_frame_func_offset(const wasm_frame_t*); size_t wasm_frame_module_offset(const wasm_frame_t*); // Traps typedef wasm_name_t wasm_message_t; // null terminated WASM_DECLARE_REF(trap) own wasm_trap_t* wasm_trap_new(wasm_store_t* store, const wasm_message_t*); void wasm_trap_message(const wasm_trap_t*, own wasm_message_t* out); own wasm_frame_t* wasm_trap_origin(const wasm_trap_t*); void wasm_trap_trace(const wasm_trap_t*, own wasm_frame_vec_t* out); // Foreign Objects WASM_DECLARE_REF(foreign) own wasm_foreign_t* wasm_foreign_new(wasm_store_t*); // Modules WASM_DECLARE_SHARABLE_REF(module) own wasm_module_t* wasm_module_new( wasm_store_t*, const wasm_byte_vec_t* binary); bool wasm_module_validate(wasm_store_t*, const wasm_byte_vec_t* binary); void wasm_module_imports(const wasm_module_t*, own wasm_importtype_vec_t* out); void wasm_module_exports(const wasm_module_t*, own wasm_exporttype_vec_t* out); void wasm_module_serialize(const wasm_module_t*, own wasm_byte_vec_t* out); own wasm_module_t* wasm_module_deserialize(wasm_store_t*, const wasm_byte_vec_t*); // Function Instances WASM_DECLARE_REF(func) typedef own wasm_trap_t* (*wasm_func_callback_t)( const wasm_val_t args[], wasm_val_t results[]); typedef own wasm_trap_t* (*wasm_func_callback_with_env_t)( void* env, const wasm_val_t args[], wasm_val_t results[]); own wasm_func_t* wasm_func_new( wasm_store_t*, const wasm_functype_t*, wasm_func_callback_t); own wasm_func_t* wasm_func_new_with_env( wasm_store_t*, const wasm_functype_t* type, wasm_func_callback_with_env_t, void* env, void (*finalizer)(void*)); own wasm_functype_t* wasm_func_type(const wasm_func_t*); size_t wasm_func_param_arity(const wasm_func_t*); size_t wasm_func_result_arity(const wasm_func_t*); own wasm_trap_t* wasm_func_call( const wasm_func_t*, const wasm_val_t args[], wasm_val_t results[]); // Global Instances WASM_DECLARE_REF(global) own wasm_global_t* wasm_global_new( wasm_store_t*, const wasm_globaltype_t*, const wasm_val_t*); own wasm_globaltype_t* wasm_global_type(const wasm_global_t*); void wasm_global_get(const wasm_global_t*, own wasm_val_t* out); void wasm_global_set(wasm_global_t*, const wasm_val_t*); // Table Instances WASM_DECLARE_REF(table) typedef uint32_t wasm_table_size_t; own wasm_table_t* wasm_table_new( wasm_store_t*, const wasm_tabletype_t*, wasm_ref_t* init); own wasm_tabletype_t* wasm_table_type(const wasm_table_t*); own wasm_ref_t* wasm_table_get(const wasm_table_t*, wasm_table_size_t index); bool wasm_table_set(wasm_table_t*, wasm_table_size_t index, wasm_ref_t*); wasm_table_size_t wasm_table_size(const wasm_table_t*); bool wasm_table_grow(wasm_table_t*, wasm_table_size_t delta, wasm_ref_t* init); // Memory Instances WASM_DECLARE_REF(memory) typedef uint32_t wasm_memory_pages_t; static const size_t MEMORY_PAGE_SIZE = 0x10000; own wasm_memory_t* wasm_memory_new(wasm_store_t*, const wasm_memorytype_t*); own wasm_memorytype_t* wasm_memory_type(const wasm_memory_t*); byte_t* wasm_memory_data(wasm_memory_t*); size_t wasm_memory_data_size(const wasm_memory_t*); wasm_memory_pages_t wasm_memory_size(const wasm_memory_t*); bool wasm_memory_grow(wasm_memory_t*, wasm_memory_pages_t delta); // Externals WASM_DECLARE_REF(extern) WASM_DECLARE_VEC(extern, *) wasm_externkind_t wasm_extern_kind(const wasm_extern_t*); own wasm_externtype_t* wasm_extern_type(const wasm_extern_t*); wasm_extern_t* wasm_func_as_extern(wasm_func_t*); wasm_extern_t* wasm_global_as_extern(wasm_global_t*); wasm_extern_t* wasm_table_as_extern(wasm_table_t*); wasm_extern_t* wasm_memory_as_extern(wasm_memory_t*); wasm_func_t* wasm_extern_as_func(wasm_extern_t*); wasm_global_t* wasm_extern_as_global(wasm_extern_t*); wasm_table_t* wasm_extern_as_table(wasm_extern_t*); wasm_memory_t* wasm_extern_as_memory(wasm_extern_t*); const wasm_extern_t* wasm_func_as_extern_const(const wasm_func_t*); const wasm_extern_t* wasm_global_as_extern_const(const wasm_global_t*); const wasm_extern_t* wasm_table_as_extern_const(const wasm_table_t*); const wasm_extern_t* wasm_memory_as_extern_const(const wasm_memory_t*); const wasm_func_t* wasm_extern_as_func_const(const wasm_extern_t*); const wasm_global_t* wasm_extern_as_global_const(const wasm_extern_t*); const wasm_table_t* wasm_extern_as_table_const(const wasm_extern_t*); const wasm_memory_t* wasm_extern_as_memory_const(const wasm_extern_t*); // Module Instances WASM_DECLARE_REF(instance) own wasm_instance_t* wasm_instance_new( wasm_store_t*, const wasm_module_t*, const wasm_extern_t* const imports[], own wasm_trap_t** ); void wasm_instance_exports(const wasm_instance_t*, own wasm_extern_vec_t* out); /////////////////////////////////////////////////////////////////////////////// // Convenience // Value Type construction short-hands static inline own wasm_valtype_t* wasm_valtype_new_i32() { return wasm_valtype_new(WASM_I32); } static inline own wasm_valtype_t* wasm_valtype_new_i64() { return wasm_valtype_new(WASM_I64); } static inline own wasm_valtype_t* wasm_valtype_new_f32() { return wasm_valtype_new(WASM_F32); } static inline own wasm_valtype_t* wasm_valtype_new_f64() { return wasm_valtype_new(WASM_F64); } static inline own wasm_valtype_t* wasm_valtype_new_anyref() { return wasm_valtype_new(WASM_ANYREF); } static inline own wasm_valtype_t* wasm_valtype_new_funcref() { return wasm_valtype_new(WASM_FUNCREF); } // Function Types construction short-hands static inline own wasm_functype_t* wasm_functype_new_0_0() { wasm_valtype_vec_t params, results; wasm_valtype_vec_new_empty(¶ms); wasm_valtype_vec_new_empty(&results); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_1_0( own wasm_valtype_t* p ) { wasm_valtype_t* ps[1] = {p}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 1, ps); wasm_valtype_vec_new_empty(&results); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_2_0( own wasm_valtype_t* p1, own wasm_valtype_t* p2 ) { wasm_valtype_t* ps[2] = {p1, p2}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 2, ps); wasm_valtype_vec_new_empty(&results); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_3_0( own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3 ) { wasm_valtype_t* ps[3] = {p1, p2, p3}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 3, ps); wasm_valtype_vec_new_empty(&results); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_0_1( own wasm_valtype_t* r ) { wasm_valtype_t* rs[1] = {r}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new_empty(¶ms); wasm_valtype_vec_new(&results, 1, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_1_1( own wasm_valtype_t* p, own wasm_valtype_t* r ) { wasm_valtype_t* ps[1] = {p}; wasm_valtype_t* rs[1] = {r}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 1, ps); wasm_valtype_vec_new(&results, 1, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_2_1( own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* r ) { wasm_valtype_t* ps[2] = {p1, p2}; wasm_valtype_t* rs[1] = {r}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 2, ps); wasm_valtype_vec_new(&results, 1, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_3_1( own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3, own wasm_valtype_t* r ) { wasm_valtype_t* ps[3] = {p1, p2, p3}; wasm_valtype_t* rs[1] = {r}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 3, ps); wasm_valtype_vec_new(&results, 1, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_0_2( own wasm_valtype_t* r1, own wasm_valtype_t* r2 ) { wasm_valtype_t* rs[2] = {r1, r2}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new_empty(¶ms); wasm_valtype_vec_new(&results, 2, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_1_2( own wasm_valtype_t* p, own wasm_valtype_t* r1, own wasm_valtype_t* r2 ) { wasm_valtype_t* ps[1] = {p}; wasm_valtype_t* rs[2] = {r1, r2}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 1, ps); wasm_valtype_vec_new(&results, 2, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_2_2( own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* r1, own wasm_valtype_t* r2 ) { wasm_valtype_t* ps[2] = {p1, p2}; wasm_valtype_t* rs[2] = {r1, r2}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 2, ps); wasm_valtype_vec_new(&results, 2, rs); return wasm_functype_new(¶ms, &results); } static inline own wasm_functype_t* wasm_functype_new_3_2( own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3, own wasm_valtype_t* r1, own wasm_valtype_t* r2 ) { wasm_valtype_t* ps[3] = {p1, p2, p3}; wasm_valtype_t* rs[2] = {r1, r2}; wasm_valtype_vec_t params, results; wasm_valtype_vec_new(¶ms, 3, ps); wasm_valtype_vec_new(&results, 2, rs); return wasm_functype_new(¶ms, &results); } // Value construction short-hands static inline void wasm_val_init_ptr(own wasm_val_t* out, void* p) { #if UINTPTR_MAX == UINT32_MAX out->kind = WASM_I32; out->of.i32 = (intptr_t)p; #elif UINTPTR_MAX == UINT64_MAX out->kind = WASM_I64; out->of.i64 = (intptr_t)p; #endif } static inline void* wasm_val_ptr(const wasm_val_t* val) { #if UINTPTR_MAX == UINT32_MAX return (void*)(intptr_t)val->of.i32; #elif UINTPTR_MAX == UINT64_MAX return (void*)(intptr_t)val->of.i64; #endif } /////////////////////////////////////////////////////////////////////////////// #undef own #ifdef __cplusplus } // extern "C" #endif #endif // #ifdef __WASM_H