diff --git a/lib/c-api/build.rs b/lib/c-api/build.rs index 6fcc41b64..7181d1989 100644 --- a/lib/c-api/build.rs +++ b/lib/c-api/build.rs @@ -427,8 +427,20 @@ fn exclude_items_from_wasm_c_api(builder: Builder) -> Builder { .exclude_item("wasi_version_t") .exclude_item("wasm_config_set_compiler") .exclude_item("wasm_config_set_engine") + .exclude_item("wasm_config_set_target") + .exclude_item("wasm_cpu_features_add") + .exclude_item("wasm_cpu_features_delete") + .exclude_item("wasm_cpu_features_new") + .exclude_item("wasm_cpu_features_t") .exclude_item("wasm_module_name") .exclude_item("wasm_module_set_name") + .exclude_item("wasm_target_delete") + .exclude_item("wasm_target_new") + .exclude_item("wasm_target_t") + .exclude_item("wasm_triple_delete") + .exclude_item("wasm_triple_new") + .exclude_item("wasm_triple_new_from_host") + .exclude_item("wasm_triple_t") .exclude_item("wasmer_compiler_t") .exclude_item("wasmer_engine_t") .exclude_item("wat2wasm") diff --git a/lib/c-api/wasmer_wasm.h b/lib/c-api/wasmer_wasm.h index 8b09b83d0..db88c4e99 100644 --- a/lib/c-api/wasmer_wasm.h +++ b/lib/c-api/wasmer_wasm.h @@ -162,13 +162,108 @@ typedef struct wasi_config_t wasi_config_t; typedef struct wasi_env_t wasi_env_t; #endif +/** + * Represents a set of CPU features. + * + * CPU features are identified by their stringified names. The + * reference is the GCC options: + * + * * , + * * , + * * . + * + * At the time of writing this documentation (it might be outdated in + * the future), the supported features are the following: + * + * * `sse2`, + * * `sse3`, + * * `ssse3`, + * * `sse4.1`, + * * `sse4.2`, + * * `popcnt`, + * * `avx`, + * * `bmi`, + * * `bmi2`, + * * `avx2`, + * * `avx512dq`, + * * `avx512vl`, + * * `lzcnt`. + * + * # Example + * + * ```rust + * # use inline_c::assert_c; + * # fn main() { + * # (assert_c! { + * # #include "tests/wasmer_wasm.h" + * # + * int main() { + * // Create a new CPU feature set. + * wasm_cpu_features_t* cpu_features = wasm_cpu_features_new(); + * + * // Create a new feature name, here `sse2`, and add it to the set. + * { + * wasm_byte_vec_t cpu_feature_name; + * wasmer_byte_vec_new_from_string(&cpu_feature_name, "sse2"); + * + * wasm_cpu_features_add(cpu_features, (wasm_name_t*) &cpu_feature_name); + * + * wasm_byte_vec_delete(&cpu_feature_name); + * } + * + * wasm_cpu_features_delete(cpu_features); + * + * return 0; + * } + * # }) + * # .success(); + * # } + * ``` + */ typedef struct wasm_cpu_features_t wasm_cpu_features_t; /** * Represents a triple + CPU features pair. + * + * # Example + * + * See the module's documentation. */ typedef struct wasm_target_t wasm_target_t; +/** + * A target “triple”. + * + * Historically such things had three fields, though they have added + * additional fields over time. + * + * # Example + * + * ```rust + * # use inline_c::assert_c; + * # fn main() { + * # (assert_c! { + * # #include "tests/wasmer_wasm.h" + * # + * int main() { + * wasm_byte_vec_t triple_name; + * wasmer_byte_vec_new_from_string(&triple_name, "x86_64-apple-darwin"); + * + * wasm_triple_t* triple = wasm_triple_new((wasm_name_t*) &triple_name); + * assert(triple); + * + * wasm_triple_delete(triple); + * wasm_byte_vec_delete(&triple_name); + * + * return 0; + * } + * # }) + * # .success(); + * # } + * ``` + * + * See also [`wasm_triple_new_from_host`]. + */ typedef struct wasm_triple_t wasm_triple_t; #ifdef __cplusplus @@ -346,10 +441,74 @@ void wasm_config_set_compiler(wasm_config_t *config, wasmer_compiler_t compiler) */ void wasm_config_set_engine(wasm_config_t *config, wasmer_engine_t engine); +/** + * Updates the configuration to specify a particular target for the engine. + * + * # Example + * + * ```rust + * # use inline_c::assert_c; + * # fn main() { + * # (assert_c! { + * # #include "tests/wasmer_wasm.h" + * # + * int main() { + * // Create the configuration. + * wasm_config_t* config = wasm_config_new(); + * + * // Set the target. + * { + * wasm_triple_t* triple = wasm_triple_new_from_host(); + * wasm_cpu_features_t* cpu_features = wasm_cpu_features_new(); + * wasm_target_t* target = wasm_target_new(triple, cpu_features); + * + * wasm_config_set_target(config, target); + * } + * + * // Create the engine. + * wasm_engine_t* engine = wasm_engine_new_with_config(config); + * + * // Check we have an engine! + * assert(engine); + * + * // Free everything. + * wasm_engine_delete(engine); + * + * return 0; + * } + * # }) + * # .success(); + * # } + * ``` + */ +void wasm_config_set_target(wasm_config_t *config, wasm_target_t *target); + +/** + * Add a new CPU feature into the set represented by + * [`wasm_cpu_features_t`]. + * + * # Example + * + * See [`wasm_cpu_features_t`]. + */ bool wasm_cpu_features_add(wasm_cpu_features_t *cpu_features, const wasm_name_t *feature); +/** + * Delete a [`wasm_cpu_features_t`]. + * + * # Example + * + * See [`wasm_cpu_features_t`]. + */ void wasm_cpu_features_delete(wasm_cpu_features_t *_cpu_features); +/** + * Create a new [`wasm_cpu_features_t`]. + * + * # Example + * + * See [`wasm_cpu_features_t`]. + */ wasm_cpu_features_t *wasm_cpu_features_new(void); /** @@ -474,7 +633,7 @@ void wasm_module_name(const wasm_module_t *module, wasm_name_t *out); bool wasm_module_set_name(wasm_module_t *module, const wasm_name_t *name); /** - * Delete a `wasm_target_t`. + * Delete a [`wasm_target_t`]. * * # Example * @@ -483,7 +642,7 @@ bool wasm_module_set_name(wasm_module_t *module, const wasm_name_t *name); void wasm_target_delete(wasm_target_t *_target); /** - * Createas a new `wasm_target_`. + * Creates a new [`wasm_target_t`]. * * It takes ownership of `triple` and `cpu_features`. * @@ -493,10 +652,50 @@ void wasm_target_delete(wasm_target_t *_target); */ wasm_target_t *wasm_target_new(wasm_triple_t *triple, wasm_cpu_features_t *cpu_features); +/** + * Delete a [`wasm_triple_t`]. + * + * # Example + * + * See [`wasm_triple_t`]. + */ void wasm_triple_delete(wasm_triple_t *_triple); +/** + * Create a new [`wasm_triple_t`] based on a triple string. + * + * # Example + * + * See [`wasm_triple_t`] or [`wasm_triple_new_from_host`]. + */ wasm_triple_t *wasm_triple_new(const wasm_name_t *triple); +/** + * Create the [`wasm_triple_t`] for the current host. + * + * # Example + * + * ```rust + * # use inline_c::assert_c; + * # fn main() { + * # (assert_c! { + * # #include "tests/wasmer_wasm.h" + * # + * int main() { + * wasm_triple_t* triple = wasm_triple_new_from_host(); + * assert(triple); + * + * wasm_triple_delete(triple); + * + * return 0; + * } + * # }) + * # .success(); + * # } + * ``` + * + * See also [`wasm_triple_new`]. + */ wasm_triple_t *wasm_triple_new_from_host(void); /**