diff --git a/lib/c-api/src/wasm_c_api/unstable/target_lexicon.rs b/lib/c-api/src/wasm_c_api/unstable/target_lexicon.rs index 9b6c858e1d4..d498ce5cc50 100644 --- a/lib/c-api/src/wasm_c_api/unstable/target_lexicon.rs +++ b/lib/c-api/src/wasm_c_api/unstable/target_lexicon.rs @@ -1,4 +1,6 @@ -//! Contains everything to create a target with a triple and CPU featurres. +//! Contains everything to create a target with a triple and CPU features. +//! +//! This is useful for cross-compilation. //! //! # Example //! @@ -9,24 +11,39 @@ //! # #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"); +//! // Declare the target triple. +//! wasm_triple_t* triple; //! -//! wasm_triple_t* triple = wasm_triple_new((wasm_name_t*) &triple_name); -//! assert(triple); +//! { +//! wasm_byte_vec_t triple_name; +//! wasmer_byte_vec_new_from_string(&triple_name, "x86_64-apple-darwin"); //! -//! wasm_byte_vec_t cpu_feature_name; -//! wasmer_byte_vec_new_from_string(&cpu_feature_name, "sse2"); +//! triple = wasm_triple_new((wasm_name_t*) &triple_name); //! +//! wasm_byte_vec_delete(&triple_name); +//! } +//! +//! assert(triple); +//! +//! // Declare the target CPU features. //! wasm_cpu_features_t* cpu_features = wasm_cpu_features_new(); -//! wasm_cpu_features_add(cpu_features, (wasm_name_t*) &cpu_feature_name); //! +//! { +//! 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); +//! } +//! +//! assert(cpu_features); +//! +//! // Create the target! //! wasm_target_t* target = wasm_target_new(triple, cpu_features); //! assert(target); //! //! wasm_target_delete(target); -//! wasm_byte_vec_delete(&cpu_feature_name); -//! wasm_byte_vec_delete(&triple_name); //! //! return 0; //! } @@ -44,12 +61,16 @@ use std::str::FromStr; use wasmer_compiler::{CpuFeature, Target, Triple}; /// Represents a triple + CPU features pair. +/// +/// # Example +/// +/// See the module's documentation. #[allow(non_camel_case_types)] pub struct wasm_target_t { pub(crate) inner: Target, } -/// Createas a new `wasm_target_`. +/// Creates a new [`wasm_target_t`]. /// /// It takes ownership of `triple` and `cpu_features`. /// @@ -69,7 +90,7 @@ pub unsafe extern "C" fn wasm_target_new( })) } -/// Delete a `wasm_target_t`. +/// Delete a [`wasm_target_t`]. /// /// # Example /// @@ -77,11 +98,47 @@ pub unsafe extern "C" fn wasm_target_new( #[no_mangle] pub unsafe extern "C" fn wasm_target_delete(_target: Option>) {} +/// 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`]. #[allow(non_camel_case_types)] pub struct wasm_triple_t { inner: Triple, } +/// Create a new [`wasm_triple_t`] based on a triple string. +/// +/// # Example +/// +/// See [`wasm_triple_t`] or [`wasm_triple_new_from_host`]. #[no_mangle] pub unsafe extern "C" fn wasm_triple_new( triple: Option<&wasm_name_t>, @@ -98,6 +155,30 @@ pub unsafe extern "C" fn wasm_triple_new( })) } +/// 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`]. #[no_mangle] pub unsafe extern "C" fn wasm_triple_new_from_host() -> Box { Box::new(wasm_triple_t { @@ -105,14 +186,80 @@ pub unsafe extern "C" fn wasm_triple_new_from_host() -> Box { }) } +/// Delete a [`wasm_triple_t`]. +/// +/// # Example +/// +/// See [`wasm_triple_t`]. #[no_mangle] pub unsafe extern "C" fn wasm_triple_delete(_triple: Option>) {} +/// 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(); +/// # } +/// ``` #[allow(non_camel_case_types)] pub struct wasm_cpu_features_t { inner: EnumSet, } +/// Create a new [`wasm_cpu_features_t`]. +/// +/// # Example +/// +/// See [`wasm_cpu_features_t`]. #[no_mangle] pub unsafe extern "C" fn wasm_cpu_features_new() -> Box { Box::new(wasm_cpu_features_t { @@ -120,10 +267,21 @@ pub unsafe extern "C" fn wasm_cpu_features_new() -> Box { }) } +/// Delete a [`wasm_cpu_features_t`]. +/// +/// # Example +/// +/// See [`wasm_cpu_features_t`]. #[no_mangle] pub unsafe extern "C" fn wasm_cpu_features_delete(_cpu_features: Option>) { } +/// Add a new CPU feature into the set represented by +/// [`wasm_cpu_features_t`]. +/// +/// # Example +/// +/// See [`wasm_cpu_features_t`]. #[no_mangle] pub unsafe extern "C" fn wasm_cpu_features_add( cpu_features: Option<&mut wasm_cpu_features_t>,