WAMR User APIs
wasm_c_api.h
Go to the documentation of this file.
1 // WebAssembly C API
2 
10 #ifndef _WASM_C_API_H_
11 #define _WASM_C_API_H_
12 
13 #include <stddef.h>
14 #include <stdint.h>
15 #include <stdbool.h>
16 #include <string.h>
17 #include <assert.h>
18 
19 #ifndef WASM_API_EXTERN
20 #if defined(_MSC_BUILD)
21 #if defined(COMPILING_WASM_RUNTIME_API)
22 #define WASM_API_EXTERN __declspec(dllexport)
23 #else
24 #define WASM_API_EXTERN __declspec(dllimport)
25 #endif
26 #else
27 #define WASM_API_EXTERN
28 #endif
29 #endif
30 
31 #if defined(__GNUC__) || defined(__clang__)
32 #define WASM_API_DEPRECATED __attribute__((deprecated))
33 #elif defined(_MSC_VER)
34 #define WASM_API_DEPRECATED __declspec(deprecated)
35 #else
36 #pragma message("WARNING: You need to implement DEPRECATED for this compiler")
37 #define WASM_API_DEPRECATED
38 #endif
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /* clang-format off */
45 
47 // Auxiliaries
48 
49 // Machine types
50 #if (__STDC_VERSION__) > 199901L
51 inline void assertions(void) {
52  static_assert(sizeof(float) == sizeof(uint32_t), "incompatible float type");
53  static_assert(sizeof(double) == sizeof(uint64_t), "incompatible double type");
54  static_assert(sizeof(intptr_t) == sizeof(uint32_t) ||
55  sizeof(intptr_t) == sizeof(uint64_t),
56  "incompatible pointer type");
57 }
58 #endif
59 
60 typedef char byte_t;
61 typedef float float32_t;
62 typedef double float64_t;
63 
64 
65 // Ownership
66 
67 #define own
68 
69 // The qualifier `own` is used to indicate ownership of data in this API.
70 // It is intended to be interpreted similar to a `const` qualifier:
71 //
72 // - `own wasm_xxx_t*` owns the pointed-to data
73 // - `own wasm_xxx_t` distributes to all fields of a struct or union `xxx`
74 // - `own wasm_xxx_vec_t` owns the vector as well as its elements(!)
75 // - an `own` function parameter passes ownership from caller to callee
76 // - an `own` function result passes ownership from callee to caller
77 // - an exception are `own` pointer parameters named `out`, which are copy-back
78 // output parameters passing back ownership from callee to caller
79 //
80 // Own data is created by `wasm_xxx_new` functions and some others.
81 // It must be released with the corresponding `wasm_xxx_delete` function.
82 //
83 // Deleting a reference does not necessarily delete the underlying object,
84 // it merely indicates that this owner no longer uses it.
85 //
86 // For vectors, `const wasm_xxx_vec_t` is used informally to indicate that
87 // neither the vector nor its elements should be modified.
88 // TODO: introduce proper `wasm_xxx_const_vec_t`?
89 
90 
91 #define WASM_DECLARE_OWN(name) \
92  typedef struct wasm_##name##_t wasm_##name##_t; \
93  \
94  WASM_API_EXTERN void wasm_##name##_delete(own wasm_##name##_t*);
95 
96 
97 // Vectors
98 // size: capacity
99 // num_elems: current number of elements
100 // size_of_elem: size of one elemen
101 #define WASM_DECLARE_VEC(name, ptr_or_none) \
102  typedef struct wasm_##name##_vec_t { \
103  size_t size; \
104  wasm_##name##_t ptr_or_none* data; \
105  size_t num_elems; \
106  size_t size_of_elem; \
107  void *lock; \
108  } wasm_##name##_vec_t; \
109  \
110  WASM_API_EXTERN void wasm_##name##_vec_new_empty(own wasm_##name##_vec_t* out); \
111  WASM_API_EXTERN void wasm_##name##_vec_new_uninitialized( \
112  own wasm_##name##_vec_t* out, size_t); \
113  WASM_API_EXTERN void wasm_##name##_vec_new( \
114  own wasm_##name##_vec_t* out, \
115  size_t, own wasm_##name##_t ptr_or_none const[]); \
116  WASM_API_EXTERN void wasm_##name##_vec_copy( \
117  own wasm_##name##_vec_t* out, const wasm_##name##_vec_t*); \
118  WASM_API_EXTERN void wasm_##name##_vec_delete(own wasm_##name##_vec_t*);
119 
120 
121 // Byte vectors
122 
123 typedef byte_t wasm_byte_t;
124 WASM_DECLARE_VEC(byte, )
125 
126 typedef wasm_byte_vec_t wasm_name_t;
127 
128 #define wasm_name wasm_byte_vec
129 #define wasm_name_new wasm_byte_vec_new
130 #define wasm_name_new_empty wasm_byte_vec_new_empty
131 #define wasm_name_new_new_uninitialized wasm_byte_vec_new_uninitialized
132 #define wasm_name_copy wasm_byte_vec_copy
133 #define wasm_name_delete wasm_byte_vec_delete
134 
135 static inline void wasm_name_new_from_string(
136  own wasm_name_t* out, const char* s
137 ) {
138  wasm_name_new(out, strlen(s), s);
139 }
140 
141 static inline void wasm_name_new_from_string_nt(
142  own wasm_name_t* out, const char* s
143 ) {
144  wasm_name_new(out, strlen(s) + 1, s);
145 }
146 
147 
149 // Runtime Environment
150 
151 // Configuration
152 
153 WASM_DECLARE_OWN(config)
154 
155 #ifndef MEM_ALLOC_OPTION_DEFINED
156 #define MEM_ALLOC_OPTION_DEFINED
157 /* same definition from wasm_export.h */
158 /* Memory allocator type */
159 typedef enum {
160  /* pool mode, allocate memory from user defined heap buffer */
161  Alloc_With_Pool = 0,
162  /* user allocator mode, allocate memory from user defined
163  malloc function */
164  Alloc_With_Allocator,
165  /* system allocator mode, allocate memory from system allocator,
166  or, platform's os_malloc function */
167  Alloc_With_System_Allocator,
168 } mem_alloc_type_t;
169 
170 /* Memory allocator option */
171 typedef union MemAllocOption {
172  struct {
173  void *heap_buf;
174  uint32_t heap_size;
175  } pool;
176  struct {
177  void *malloc_func;
178  void *realloc_func;
179  void *free_func;
180  /* allocator user data, only used when
181  WASM_MEM_ALLOC_WITH_USER_DATA is defined */
182  void *user_data;
183  } allocator;
185 #endif /* MEM_ALLOC_OPTION_DEFINED */
186 
187 /* Runtime configration */
189  mem_alloc_type_t mem_alloc_type;
190  MemAllocOption mem_alloc_option;
191  uint32_t segue_flags;
192  bool enable_linux_perf;
193  /*TODO: wasi args*/
194 };
195 
196 #ifndef INSTANTIATION_ARGS_OPTION_DEFINED
197 #define INSTANTIATION_ARGS_OPTION_DEFINED
198 /* WASM module instantiation arguments */
199 typedef struct InstantiationArgs {
200  uint32_t default_stack_size;
201  uint32_t host_managed_heap_size;
202  uint32_t max_memory_pages;
204 #endif /* INSTANTIATION_ARGS_OPTION_DEFINED */
205 
206 /*
207  * by default:
208  * - mem_alloc_type is Alloc_With_System_Allocator
209  * - mem_alloc_option is all 0
210  * - enable_linux_perf is false
211  */
212 WASM_API_EXTERN own wasm_config_t* wasm_config_new(void);
213 
214 // Embedders may provide custom functions for manipulating configs.
215 WASM_API_EXTERN own wasm_config_t*
216 wasm_config_set_mem_alloc_opt(wasm_config_t *, mem_alloc_type_t, MemAllocOption *);
217 
218 WASM_API_EXTERN own wasm_config_t*
219 wasm_config_set_linux_perf_opt(wasm_config_t *, bool);
220 
229 WASM_API_EXTERN wasm_config_t*
230 wasm_config_set_segue_flags(wasm_config_t *config, uint32_t segue_flags);
231 
232 // Engine
233 
234 WASM_DECLARE_OWN(engine)
235 
236 
249 WASM_API_EXTERN own wasm_engine_t* wasm_engine_new(void);
250 WASM_API_EXTERN own wasm_engine_t* wasm_engine_new_with_config(wasm_config_t*);
251 WASM_API_DEPRECATED WASM_API_EXTERN own wasm_engine_t *
252 wasm_engine_new_with_args(mem_alloc_type_t type, const MemAllocOption *opts);
253 
254 // Store
255 
256 WASM_DECLARE_OWN(store)
257 
258 WASM_API_EXTERN own wasm_store_t* wasm_store_new(wasm_engine_t*);
259 
260 
262 // Type Representations
263 
264 // Type attributes
265 
266 typedef uint8_t wasm_mutability_t;
267 enum wasm_mutability_enum {
268  WASM_CONST,
269  WASM_VAR,
270 };
271 
272 typedef struct wasm_limits_t {
273  uint32_t min;
274  uint32_t max;
275 } wasm_limits_t;
276 
277 static const uint32_t wasm_limits_max_default = 0xffffffff;
278 
279 
280 // Generic
281 
282 #define WASM_DECLARE_TYPE(name) \
283  WASM_DECLARE_OWN(name) \
284  WASM_DECLARE_VEC(name, *) \
285  \
286  WASM_API_EXTERN own wasm_##name##_t* wasm_##name##_copy(const wasm_##name##_t*);
287 
288 
289 // Value Types
290 
291 WASM_DECLARE_TYPE(valtype)
292 
293 #ifndef WASM_VALKIND_T_DEFINED
294 #define WASM_VALKIND_T_DEFINED
295 typedef uint8_t wasm_valkind_t;
296 enum wasm_valkind_enum {
297  WASM_I32,
298  WASM_I64,
299  WASM_F32,
300  WASM_F64,
301  WASM_ANYREF = 128,
302  WASM_FUNCREF,
303 };
304 #endif
305 
306 WASM_API_EXTERN own wasm_valtype_t* wasm_valtype_new(wasm_valkind_t);
307 
308 WASM_API_EXTERN wasm_valkind_t wasm_valtype_kind(const wasm_valtype_t*);
309 
310 static inline bool wasm_valkind_is_num(wasm_valkind_t k) {
311  return k < WASM_ANYREF;
312 }
313 static inline bool wasm_valkind_is_ref(wasm_valkind_t k) {
314  return k >= WASM_ANYREF;
315 }
316 
317 static inline bool wasm_valtype_is_num(const wasm_valtype_t* t) {
318  return wasm_valkind_is_num(wasm_valtype_kind(t));
319 }
320 static inline bool wasm_valtype_is_ref(const wasm_valtype_t* t) {
321  return wasm_valkind_is_ref(wasm_valtype_kind(t));
322 }
323 
324 
325 // Function Types
326 
327 WASM_DECLARE_TYPE(functype)
328 
329 WASM_API_EXTERN own wasm_functype_t* wasm_functype_new(
330  own wasm_valtype_vec_t* params, own wasm_valtype_vec_t* results);
331 
332 WASM_API_EXTERN const wasm_valtype_vec_t* wasm_functype_params(const wasm_functype_t*);
333 WASM_API_EXTERN const wasm_valtype_vec_t* wasm_functype_results(const wasm_functype_t*);
334 
335 
336 // Global Types
337 
338 WASM_DECLARE_TYPE(globaltype)
339 
340 WASM_API_EXTERN own wasm_globaltype_t* wasm_globaltype_new(
341  own wasm_valtype_t*, wasm_mutability_t);
342 
343 WASM_API_EXTERN const wasm_valtype_t* wasm_globaltype_content(const wasm_globaltype_t*);
344 WASM_API_EXTERN wasm_mutability_t wasm_globaltype_mutability(const wasm_globaltype_t*);
345 
346 
347 // Table Types
348 
349 WASM_DECLARE_TYPE(tabletype)
350 
351 WASM_API_EXTERN own wasm_tabletype_t* wasm_tabletype_new(
352  own wasm_valtype_t*, const wasm_limits_t*);
353 
354 WASM_API_EXTERN const wasm_valtype_t* wasm_tabletype_element(const wasm_tabletype_t*);
355 WASM_API_EXTERN const wasm_limits_t* wasm_tabletype_limits(const wasm_tabletype_t*);
356 
357 
358 // Memory Types
359 
360 WASM_DECLARE_TYPE(memorytype)
361 
362 WASM_API_EXTERN own wasm_memorytype_t* wasm_memorytype_new(const wasm_limits_t*);
363 
364 WASM_API_EXTERN const wasm_limits_t* wasm_memorytype_limits(const wasm_memorytype_t*);
365 
366 
367 // Extern Types
368 
369 WASM_DECLARE_TYPE(externtype)
370 
371 typedef uint8_t wasm_externkind_t;
372 enum wasm_externkind_enum {
373  WASM_EXTERN_FUNC,
374  WASM_EXTERN_GLOBAL,
375  WASM_EXTERN_TABLE,
376  WASM_EXTERN_MEMORY,
377 };
378 
379 WASM_API_EXTERN wasm_externkind_t wasm_externtype_kind(const wasm_externtype_t*);
380 
381 WASM_API_EXTERN wasm_externtype_t* wasm_functype_as_externtype(wasm_functype_t*);
382 WASM_API_EXTERN wasm_externtype_t* wasm_globaltype_as_externtype(wasm_globaltype_t*);
383 WASM_API_EXTERN wasm_externtype_t* wasm_tabletype_as_externtype(wasm_tabletype_t*);
384 WASM_API_EXTERN wasm_externtype_t* wasm_memorytype_as_externtype(wasm_memorytype_t*);
385 
386 WASM_API_EXTERN wasm_functype_t* wasm_externtype_as_functype(wasm_externtype_t*);
387 WASM_API_EXTERN wasm_globaltype_t* wasm_externtype_as_globaltype(wasm_externtype_t*);
388 WASM_API_EXTERN wasm_tabletype_t* wasm_externtype_as_tabletype(wasm_externtype_t*);
389 WASM_API_EXTERN wasm_memorytype_t* wasm_externtype_as_memorytype(wasm_externtype_t*);
390 
391 WASM_API_EXTERN const wasm_externtype_t* wasm_functype_as_externtype_const(const wasm_functype_t*);
392 WASM_API_EXTERN const wasm_externtype_t* wasm_globaltype_as_externtype_const(const wasm_globaltype_t*);
393 WASM_API_EXTERN const wasm_externtype_t* wasm_tabletype_as_externtype_const(const wasm_tabletype_t*);
394 WASM_API_EXTERN const wasm_externtype_t* wasm_memorytype_as_externtype_const(const wasm_memorytype_t*);
395 
396 WASM_API_EXTERN const wasm_functype_t* wasm_externtype_as_functype_const(const wasm_externtype_t*);
397 WASM_API_EXTERN const wasm_globaltype_t* wasm_externtype_as_globaltype_const(const wasm_externtype_t*);
398 WASM_API_EXTERN const wasm_tabletype_t* wasm_externtype_as_tabletype_const(const wasm_externtype_t*);
399 WASM_API_EXTERN const wasm_memorytype_t* wasm_externtype_as_memorytype_const(const wasm_externtype_t*);
400 
401 
402 // Import Types
403 
404 WASM_DECLARE_TYPE(importtype)
405 
406 WASM_API_EXTERN own wasm_importtype_t* wasm_importtype_new(
407  own wasm_name_t* module, own wasm_name_t* name, own wasm_externtype_t*);
408 
409 WASM_API_EXTERN const wasm_name_t* wasm_importtype_module(const wasm_importtype_t*);
410 WASM_API_EXTERN const wasm_name_t* wasm_importtype_name(const wasm_importtype_t*);
411 WASM_API_EXTERN const wasm_externtype_t* wasm_importtype_type(const wasm_importtype_t*);
412 WASM_API_EXTERN bool wasm_importtype_is_linked(const wasm_importtype_t*);
413 
414 
415 // Export Types
416 
417 WASM_DECLARE_TYPE(exporttype)
418 
419 WASM_API_EXTERN own wasm_exporttype_t* wasm_exporttype_new(
420  own wasm_name_t*, own wasm_externtype_t*);
421 
422 WASM_API_EXTERN const wasm_name_t* wasm_exporttype_name(const wasm_exporttype_t*);
423 WASM_API_EXTERN const wasm_externtype_t* wasm_exporttype_type(const wasm_exporttype_t*);
424 
425 
427 // Runtime Objects
428 
429 // Values
430 
431 #ifndef WASM_VAL_T_DEFINED
432 #define WASM_VAL_T_DEFINED
433 struct wasm_ref_t;
434 
435 typedef struct wasm_val_t {
436  wasm_valkind_t kind;
437  uint8_t __paddings[7];
438  union {
439  int32_t i32;
440  int64_t i64;
441  float32_t f32;
442  float64_t f64;
443  struct wasm_ref_t* ref;
444  } of;
445 } wasm_val_t;
446 #endif
447 
448 WASM_API_EXTERN void wasm_val_delete(own wasm_val_t* v);
449 WASM_API_EXTERN void wasm_val_copy(own wasm_val_t* out, const wasm_val_t*);
450 
451 WASM_DECLARE_VEC(val, )
452 
453 
454 // References
455 
456 #define WASM_DECLARE_REF_BASE(name) \
457  WASM_DECLARE_OWN(name) \
458  \
459  WASM_API_EXTERN own wasm_##name##_t* wasm_##name##_copy(const wasm_##name##_t*); \
460  WASM_API_EXTERN bool wasm_##name##_same(const wasm_##name##_t*, const wasm_##name##_t*); \
461  \
462  WASM_API_EXTERN void* wasm_##name##_get_host_info(const wasm_##name##_t*); \
463  WASM_API_EXTERN void wasm_##name##_set_host_info(wasm_##name##_t*, void*); \
464  WASM_API_EXTERN void wasm_##name##_set_host_info_with_finalizer( \
465  wasm_##name##_t*, void*, void (*)(void*));
466 
467 #define WASM_DECLARE_REF(name) \
468  WASM_DECLARE_REF_BASE(name) \
469  \
470  WASM_API_EXTERN wasm_ref_t* wasm_##name##_as_ref(wasm_##name##_t*); \
471  WASM_API_EXTERN wasm_##name##_t* wasm_ref_as_##name(wasm_ref_t*); \
472  WASM_API_EXTERN const wasm_ref_t* wasm_##name##_as_ref_const(const wasm_##name##_t*); \
473  WASM_API_EXTERN const wasm_##name##_t* wasm_ref_as_##name##_const(const wasm_ref_t*);
474 
475 #define WASM_DECLARE_SHARABLE_REF(name) \
476  WASM_DECLARE_REF(name) \
477  WASM_DECLARE_OWN(shared_##name) \
478  \
479  WASM_API_EXTERN own wasm_shared_##name##_t* wasm_##name##_share(const wasm_##name##_t*); \
480  WASM_API_EXTERN own wasm_##name##_t* wasm_##name##_obtain(wasm_store_t*, const wasm_shared_##name##_t*);
481 
482 
483 WASM_DECLARE_REF_BASE(ref)
484 
485 
486 // Frames
487 
488 WASM_DECLARE_OWN(frame)
489 WASM_DECLARE_VEC(frame, *)
490 WASM_API_EXTERN own wasm_frame_t* wasm_frame_copy(const wasm_frame_t*);
491 
492 WASM_API_EXTERN struct wasm_instance_t* wasm_frame_instance(const wasm_frame_t*);
493 WASM_API_EXTERN uint32_t wasm_frame_func_index(const wasm_frame_t*);
494 WASM_API_EXTERN size_t wasm_frame_func_offset(const wasm_frame_t*);
495 WASM_API_EXTERN size_t wasm_frame_module_offset(const wasm_frame_t*);
496 
497 
498 // Traps
499 
500 typedef wasm_name_t wasm_message_t; // null terminated
501 
502 WASM_DECLARE_REF(trap)
503 
504 WASM_API_EXTERN own wasm_trap_t* wasm_trap_new(wasm_store_t* store, const wasm_message_t*);
505 
506 WASM_API_EXTERN void wasm_trap_message(const wasm_trap_t*, own wasm_message_t* out);
507 WASM_API_EXTERN own wasm_frame_t* wasm_trap_origin(const wasm_trap_t*);
508 WASM_API_EXTERN void wasm_trap_trace(const wasm_trap_t*, own wasm_frame_vec_t* out);
509 
510 
511 // Foreign Objects
512 
513 WASM_DECLARE_REF(foreign)
514 
515 WASM_API_EXTERN own wasm_foreign_t* wasm_foreign_new(wasm_store_t*);
516 
517 
518 // Modules
519 // WASM_DECLARE_SHARABLE_REF(module)
520 
521 #ifndef WASM_MODULE_T_DEFINED
522 #define WASM_MODULE_T_DEFINED
523 struct WASMModuleCommon;
524 typedef struct WASMModuleCommon *wasm_module_t;
525 #endif
526 
527 
528 WASM_API_EXTERN own wasm_module_t* wasm_module_new(
529  wasm_store_t*, const wasm_byte_vec_t* binary);
530 
531 WASM_API_EXTERN void wasm_module_delete(own wasm_module_t*);
532 
533 WASM_API_EXTERN bool wasm_module_validate(wasm_store_t*, const wasm_byte_vec_t* binary);
534 
535 WASM_API_EXTERN void wasm_module_imports(const wasm_module_t*, own wasm_importtype_vec_t* out);
536 WASM_API_EXTERN void wasm_module_exports(const wasm_module_t*, own wasm_exporttype_vec_t* out);
537 
538 WASM_API_EXTERN void wasm_module_serialize(wasm_module_t*, own wasm_byte_vec_t* out);
539 WASM_API_EXTERN own wasm_module_t* wasm_module_deserialize(wasm_store_t*, const wasm_byte_vec_t*);
540 
541 typedef wasm_module_t wasm_shared_module_t;
542 WASM_API_EXTERN own wasm_shared_module_t* wasm_module_share(wasm_module_t*);
543 WASM_API_EXTERN own wasm_module_t* wasm_module_obtain(wasm_store_t*, wasm_shared_module_t*);
544 WASM_API_EXTERN void wasm_shared_module_delete(own wasm_shared_module_t*);
545 
546 WASM_API_EXTERN bool wasm_module_set_name(wasm_module_t*, const char* name);
547 WASM_API_EXTERN const char *wasm_module_get_name(wasm_module_t*);
548 
549 
550 // Function Instances
551 
552 WASM_DECLARE_REF(func)
553 
554 typedef own wasm_trap_t* (*wasm_func_callback_t)(
555  const wasm_val_vec_t* args, own wasm_val_vec_t *results);
556 typedef own wasm_trap_t* (*wasm_func_callback_with_env_t)(
557  void* env, const wasm_val_vec_t *args, wasm_val_vec_t *results);
558 
559 WASM_API_EXTERN own wasm_func_t* wasm_func_new(
560  wasm_store_t*, const wasm_functype_t*, wasm_func_callback_t);
561 WASM_API_EXTERN own wasm_func_t* wasm_func_new_with_env(
562  wasm_store_t*, const wasm_functype_t* type, wasm_func_callback_with_env_t,
563  void* env, void (*finalizer)(void*));
564 
565 WASM_API_EXTERN own wasm_functype_t* wasm_func_type(const wasm_func_t*);
566 WASM_API_EXTERN size_t wasm_func_param_arity(const wasm_func_t*);
567 WASM_API_EXTERN size_t wasm_func_result_arity(const wasm_func_t*);
568 
569 WASM_API_EXTERN own wasm_trap_t* wasm_func_call(
570  const wasm_func_t*, const wasm_val_vec_t* args, wasm_val_vec_t* results);
571 
572 
573 // Global Instances
574 
575 WASM_DECLARE_REF(global)
576 
577 WASM_API_EXTERN own wasm_global_t* wasm_global_new(
578  wasm_store_t*, const wasm_globaltype_t*, const wasm_val_t*);
579 
580 WASM_API_EXTERN own wasm_globaltype_t* wasm_global_type(const wasm_global_t*);
581 
582 WASM_API_EXTERN void wasm_global_get(const wasm_global_t*, own wasm_val_t* out);
583 WASM_API_EXTERN void wasm_global_set(wasm_global_t*, const wasm_val_t*);
584 
585 
586 // Table Instances
587 
588 WASM_DECLARE_REF(table)
589 
590 typedef uint32_t wasm_table_size_t;
591 
592 WASM_API_EXTERN own wasm_table_t* wasm_table_new(
593  wasm_store_t*, const wasm_tabletype_t*, wasm_ref_t* init);
594 
595 WASM_API_EXTERN own wasm_tabletype_t* wasm_table_type(const wasm_table_t*);
596 
597 WASM_API_EXTERN own wasm_ref_t* wasm_table_get(const wasm_table_t*, wasm_table_size_t index);
598 WASM_API_EXTERN bool wasm_table_set(wasm_table_t*, wasm_table_size_t index, wasm_ref_t*);
599 
600 WASM_API_EXTERN wasm_table_size_t wasm_table_size(const wasm_table_t*);
601 WASM_API_EXTERN bool wasm_table_grow(wasm_table_t*, wasm_table_size_t delta, wasm_ref_t* init);
602 
603 
604 // Memory Instances
605 
606 WASM_DECLARE_REF(memory)
607 
608 typedef uint32_t wasm_memory_pages_t;
609 
610 static const size_t MEMORY_PAGE_SIZE = 0x10000;
611 
612 WASM_API_EXTERN own wasm_memory_t* wasm_memory_new(wasm_store_t*, const wasm_memorytype_t*);
613 
614 WASM_API_EXTERN own wasm_memorytype_t* wasm_memory_type(const wasm_memory_t*);
615 
616 WASM_API_EXTERN byte_t* wasm_memory_data(wasm_memory_t*);
617 WASM_API_EXTERN size_t wasm_memory_data_size(const wasm_memory_t*);
618 
619 WASM_API_EXTERN wasm_memory_pages_t wasm_memory_size(const wasm_memory_t*);
620 WASM_API_EXTERN bool wasm_memory_grow(wasm_memory_t*, wasm_memory_pages_t delta);
621 
622 
623 // Externals
624 
625 WASM_DECLARE_REF(extern)
626 WASM_DECLARE_VEC(extern, *)
627 
628 WASM_API_EXTERN wasm_externkind_t wasm_extern_kind(const wasm_extern_t*);
629 WASM_API_EXTERN own wasm_externtype_t* wasm_extern_type(const wasm_extern_t*);
630 
631 WASM_API_EXTERN wasm_extern_t* wasm_func_as_extern(wasm_func_t*);
632 WASM_API_EXTERN wasm_extern_t* wasm_global_as_extern(wasm_global_t*);
633 WASM_API_EXTERN wasm_extern_t* wasm_table_as_extern(wasm_table_t*);
634 WASM_API_EXTERN wasm_extern_t* wasm_memory_as_extern(wasm_memory_t*);
635 
636 WASM_API_EXTERN wasm_func_t* wasm_extern_as_func(wasm_extern_t*);
637 WASM_API_EXTERN wasm_global_t* wasm_extern_as_global(wasm_extern_t*);
638 WASM_API_EXTERN wasm_table_t* wasm_extern_as_table(wasm_extern_t*);
639 WASM_API_EXTERN wasm_memory_t* wasm_extern_as_memory(wasm_extern_t*);
640 
641 WASM_API_EXTERN const wasm_extern_t* wasm_func_as_extern_const(const wasm_func_t*);
642 WASM_API_EXTERN const wasm_extern_t* wasm_global_as_extern_const(const wasm_global_t*);
643 WASM_API_EXTERN const wasm_extern_t* wasm_table_as_extern_const(const wasm_table_t*);
644 WASM_API_EXTERN const wasm_extern_t* wasm_memory_as_extern_const(const wasm_memory_t*);
645 
646 WASM_API_EXTERN const wasm_func_t* wasm_extern_as_func_const(const wasm_extern_t*);
647 WASM_API_EXTERN const wasm_global_t* wasm_extern_as_global_const(const wasm_extern_t*);
648 WASM_API_EXTERN const wasm_table_t* wasm_extern_as_table_const(const wasm_extern_t*);
649 WASM_API_EXTERN const wasm_memory_t* wasm_extern_as_memory_const(const wasm_extern_t*);
650 
651 
652 // Module Instances
653 
654 WASM_DECLARE_REF(instance)
655 
656 WASM_API_EXTERN own wasm_instance_t* wasm_instance_new(
657  wasm_store_t*, const wasm_module_t*, const wasm_extern_vec_t *imports,
658  own wasm_trap_t** trap
659 );
660 
661 // please refer to wasm_runtime_instantiate(...) in core/iwasm/include/wasm_export.h
662 WASM_API_EXTERN own wasm_instance_t* wasm_instance_new_with_args(
663  wasm_store_t*, const wasm_module_t*, const wasm_extern_vec_t *imports,
664  own wasm_trap_t** trap, const uint32_t stack_size, const uint32_t heap_size
665 );
666 
667 // please refer to wasm_runtime_instantiate_ex(...) in core/iwasm/include/wasm_export.h
668 WASM_API_EXTERN own wasm_instance_t* wasm_instance_new_with_args_ex(
669  wasm_store_t*, const wasm_module_t*, const wasm_extern_vec_t *imports,
670  own wasm_trap_t** trap, const InstantiationArgs *inst_args
671 );
672 
673 WASM_API_EXTERN void wasm_instance_exports(const wasm_instance_t*, own wasm_extern_vec_t* out);
674 
675 
677 // Convenience
678 
679 // Vectors
680 
681 #define WASM_EMPTY_VEC {0, NULL, 0, 0, NULL}
682 #define WASM_ARRAY_VEC(array) {sizeof(array)/sizeof(*(array)), array, sizeof(array)/sizeof(*(array)), sizeof(*(array)), NULL}
683 
684 
685 // Value Type construction short-hands
686 
687 static inline own wasm_valtype_t* wasm_valtype_new_i32(void) {
688  return wasm_valtype_new(WASM_I32);
689 }
690 static inline own wasm_valtype_t* wasm_valtype_new_i64(void) {
691  return wasm_valtype_new(WASM_I64);
692 }
693 static inline own wasm_valtype_t* wasm_valtype_new_f32(void) {
694  return wasm_valtype_new(WASM_F32);
695 }
696 static inline own wasm_valtype_t* wasm_valtype_new_f64(void) {
697  return wasm_valtype_new(WASM_F64);
698 }
699 
700 static inline own wasm_valtype_t* wasm_valtype_new_anyref(void) {
701  return wasm_valtype_new(WASM_ANYREF);
702 }
703 static inline own wasm_valtype_t* wasm_valtype_new_funcref(void) {
704  return wasm_valtype_new(WASM_FUNCREF);
705 }
706 
707 
708 // Function Types construction short-hands
709 
710 static inline own wasm_functype_t* wasm_functype_new_0_0(void) {
711  wasm_valtype_vec_t params, results;
712  wasm_valtype_vec_new_empty(&params);
713  wasm_valtype_vec_new_empty(&results);
714  return wasm_functype_new(&params, &results);
715 }
716 
717 static inline own wasm_functype_t* wasm_functype_new_1_0(
718  own wasm_valtype_t* p
719 ) {
720  wasm_valtype_t* ps[1] = {p};
721  wasm_valtype_vec_t params, results;
722  wasm_valtype_vec_new(&params, 1, ps);
723  wasm_valtype_vec_new_empty(&results);
724  return wasm_functype_new(&params, &results);
725 }
726 
727 static inline own wasm_functype_t* wasm_functype_new_2_0(
728  own wasm_valtype_t* p1, own wasm_valtype_t* p2
729 ) {
730  wasm_valtype_t* ps[2] = {p1, p2};
731  wasm_valtype_vec_t params, results;
732  wasm_valtype_vec_new(&params, 2, ps);
733  wasm_valtype_vec_new_empty(&results);
734  return wasm_functype_new(&params, &results);
735 }
736 
737 static inline own wasm_functype_t* wasm_functype_new_3_0(
738  own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3
739 ) {
740  wasm_valtype_t* ps[3] = {p1, p2, p3};
741  wasm_valtype_vec_t params, results;
742  wasm_valtype_vec_new(&params, 3, ps);
743  wasm_valtype_vec_new_empty(&results);
744  return wasm_functype_new(&params, &results);
745 }
746 
747 static inline own wasm_functype_t* wasm_functype_new_0_1(
748  own wasm_valtype_t* r
749 ) {
750  wasm_valtype_t* rs[1] = {r};
751  wasm_valtype_vec_t params, results;
752  wasm_valtype_vec_new_empty(&params);
753  wasm_valtype_vec_new(&results, 1, rs);
754  return wasm_functype_new(&params, &results);
755 }
756 
757 static inline own wasm_functype_t* wasm_functype_new_1_1(
758  own wasm_valtype_t* p, own wasm_valtype_t* r
759 ) {
760  wasm_valtype_t* ps[1] = {p};
761  wasm_valtype_t* rs[1] = {r};
762  wasm_valtype_vec_t params, results;
763  wasm_valtype_vec_new(&params, 1, ps);
764  wasm_valtype_vec_new(&results, 1, rs);
765  return wasm_functype_new(&params, &results);
766 }
767 
768 static inline own wasm_functype_t* wasm_functype_new_2_1(
769  own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* r
770 ) {
771  wasm_valtype_t* ps[2] = {p1, p2};
772  wasm_valtype_t* rs[1] = {r};
773  wasm_valtype_vec_t params, results;
774  wasm_valtype_vec_new(&params, 2, ps);
775  wasm_valtype_vec_new(&results, 1, rs);
776  return wasm_functype_new(&params, &results);
777 }
778 
779 static inline own wasm_functype_t* wasm_functype_new_3_1(
780  own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3,
781  own wasm_valtype_t* r
782 ) {
783  wasm_valtype_t* ps[3] = {p1, p2, p3};
784  wasm_valtype_t* rs[1] = {r};
785  wasm_valtype_vec_t params, results;
786  wasm_valtype_vec_new(&params, 3, ps);
787  wasm_valtype_vec_new(&results, 1, rs);
788  return wasm_functype_new(&params, &results);
789 }
790 
791 static inline own wasm_functype_t* wasm_functype_new_0_2(
792  own wasm_valtype_t* r1, own wasm_valtype_t* r2
793 ) {
794  wasm_valtype_t* rs[2] = {r1, r2};
795  wasm_valtype_vec_t params, results;
796  wasm_valtype_vec_new_empty(&params);
797  wasm_valtype_vec_new(&results, 2, rs);
798  return wasm_functype_new(&params, &results);
799 }
800 
801 static inline own wasm_functype_t* wasm_functype_new_1_2(
802  own wasm_valtype_t* p, own wasm_valtype_t* r1, own wasm_valtype_t* r2
803 ) {
804  wasm_valtype_t* ps[1] = {p};
805  wasm_valtype_t* rs[2] = {r1, r2};
806  wasm_valtype_vec_t params, results;
807  wasm_valtype_vec_new(&params, 1, ps);
808  wasm_valtype_vec_new(&results, 2, rs);
809  return wasm_functype_new(&params, &results);
810 }
811 
812 static inline own wasm_functype_t* wasm_functype_new_2_2(
813  own wasm_valtype_t* p1, own wasm_valtype_t* p2,
814  own wasm_valtype_t* r1, own wasm_valtype_t* r2
815 ) {
816  wasm_valtype_t* ps[2] = {p1, p2};
817  wasm_valtype_t* rs[2] = {r1, r2};
818  wasm_valtype_vec_t params, results;
819  wasm_valtype_vec_new(&params, 2, ps);
820  wasm_valtype_vec_new(&results, 2, rs);
821  return wasm_functype_new(&params, &results);
822 }
823 
824 static inline own wasm_functype_t* wasm_functype_new_3_2(
825  own wasm_valtype_t* p1, own wasm_valtype_t* p2, own wasm_valtype_t* p3,
826  own wasm_valtype_t* r1, own wasm_valtype_t* r2
827 ) {
828  wasm_valtype_t* ps[3] = {p1, p2, p3};
829  wasm_valtype_t* rs[2] = {r1, r2};
830  wasm_valtype_vec_t params, results;
831  wasm_valtype_vec_new(&params, 3, ps);
832  wasm_valtype_vec_new(&results, 2, rs);
833  return wasm_functype_new(&params, &results);
834 }
835 
836 
837 // Value construction short-hands
838 
839 static inline void wasm_val_init_ptr(own wasm_val_t* out, void* p) {
840 #if UINTPTR_MAX == UINT32_MAX
841  out->kind = WASM_I32;
842  out->of.i32 = (intptr_t)p;
843 #elif UINTPTR_MAX == UINT64_MAX
844  out->kind = WASM_I64;
845  out->of.i64 = (intptr_t)p;
846 #endif
847 }
848 
849 static inline void* wasm_val_ptr(const wasm_val_t* val) {
850 #if UINTPTR_MAX == UINT32_MAX
851  return (void*)(intptr_t)val->of.i32;
852 #elif UINTPTR_MAX == UINT64_MAX
853  return (void*)(intptr_t)val->of.i64;
854 #endif
855 }
856 
857 #define WASM_I32_VAL(i) {.kind = WASM_I32, .__paddings = {0}, .of = {.i32 = i}}
858 #define WASM_I64_VAL(i) {.kind = WASM_I64, .__paddings = {0}, .of = {.i64 = i}}
859 #define WASM_F32_VAL(z) {.kind = WASM_F32, .__paddings = {0}, .of = {.f32 = z}}
860 #define WASM_F64_VAL(z) {.kind = WASM_F64, .__paddings = {0}, .of = {.f64 = z}}
861 #define WASM_REF_VAL(r) {.kind = WASM_ANYREF, .__paddings = {0}, .of = {.ref = r}}
862 #define WASM_INIT_VAL {.kind = WASM_ANYREF, .__paddings = {0}, .of = {.ref = NULL}}
863 
864 #define KILOBYTE(n) ((n) * 1024)
865 
866 // Create placeholders filled in `wasm_externvec_t* imports` for `wasm_instance_new()`
867 WASM_API_EXTERN wasm_extern_t *wasm_extern_new_empty(wasm_store_t *, wasm_externkind_t);
868 
870 
871 #undef own
872 
873 /* clang-format on */
874 
875 #ifdef __cplusplus
876 } // extern "C"
877 #endif
878 
879 #endif // #ifdef _WASM_C_API_H_
wasm_limits_t
Definition: wasm_c_api.h:272
wasm_config_t
Definition: wasm_c_api.h:188
MemAllocOption
Definition: wasm_c_api.h:171
wasm_config_set_segue_flags
WASM_API_EXTERN wasm_config_t * wasm_config_set_segue_flags(wasm_config_t *config, uint32_t segue_flags)
wasm_val_t
Definition: wasm_c_api.h:435
InstantiationArgs
Definition: wasm_c_api.h:199
wasm_engine_new
WASM_API_EXTERN own wasm_engine_t * wasm_engine_new(void)