| # stdarch-gen-arm generator guide |
| ## Running the generator |
| |
| Run: `cargo +nightly run --bin=stdarch-gen-arm -- crates/stdarch-gen-arm/spec crates/core_arch/src` |
| |
| NOTE: If you are running this from rust-lang/rust, you must be in the `library/stdarch` |
| working directory. |
| |
| ## Input/Output |
| ### Input files (intrinsic YAML definitions) |
| - `crates/stdarch-gen-arm/spec/<feature>/*.spec.yml` |
| ### Output files |
| - Generated intrinsics: |
| - `crates/core_arch/src/<arch>/<feature>/generated.rs` |
| - Generated load/store tests: |
| - `crates/core_arch/src/<arch>/<feature>/ld_st_tests_<arch>.rs` |
| - Only generated when `test: { load: <idx> }` or `test: { store: <idx> }` is set for SVE/SVE2 intrinsics. |
| ## `.spec.yml` file anatomy |
| ``` |
| --- |
| Configs |
| --- |
| Variable definitions |
| --- |
| |
| Intrinsic definitions |
| |
| --- |
| ``` |
| - If you're new to YAML syntax, consider [reviewing](https://quickref.me/yaml.html) some of the less obvious syntax and features. |
| - For example, mapping an attribute to a sequence can be done in two different ways: |
| ```yaml |
| attribute: [item_a, item_b, item_c] |
| ``` |
| or |
| ```yaml |
| attribute: |
| - item_a |
| - item_b |
| - item_c |
| ``` |
| ## Configs |
| - Mappings defining top-level settings applied to all intrinsics: |
| - `arch_cfgs` |
| - Sequence of mappings specifying `arch_name`, `target_feature` (sequence), and `llvm_prefix`. |
| - `uses_neon_types`(_Optional_) |
| - A boolean specifying whether to emit NEON type imports in generated code. |
| - `auto_big_endian`(_Optional_) |
| - A boolean specifying whether to auto-generate big-endian shuffles when possible. |
| - `auto_llvm_sign_conversion`(_Optional_) |
| - A boolean specifying whether to auto-convert LLVM wrapper args to signed types. |
| ## Variable definitions |
| - Defines YAML anchors/variables to avoid repetition. |
| - Commonly used for stability attributes, cfgs and target features. |
| ## Intrinsic definitions |
| ### Example |
| ```yaml |
| - name: "vtst{neon_type[0].no}" |
| doc: "Signed compare bitwise Test bits nonzero" |
| arguments: ["a: {neon_type[0]}", "b: {neon_type[0]}"] |
| return_type: "{neon_type[1]}" |
| attr: |
| - FnCall: [cfg_attr, [test, {FnCall: [assert_instr, [cmtst]]}]] |
| - FnCall: [stable, ['feature = "neon_intrinsics"', 'since = "1.59.0"']] |
| safety: safe |
| types: |
| - [int64x1_t, uint64x1_t, 'i64x1', 'i64x1::new(0)'] |
| - [int64x2_t, uint64x2_t, 'i64x2', 'i64x2::new(0, 0)'] |
| - [poly64x1_t, uint64x1_t, 'i64x1', 'i64x1::new(0)'] |
| - [poly64x2_t, uint64x2_t, 'i64x2', 'i64x2::new(0, 0)'] |
| compose: |
| - Let: [c, "{neon_type[0]}", {FnCall: [simd_and, [a, b]]}] |
| - Let: [d, "{type[2]}", "{type[3]}"] |
| - FnCall: [simd_ne, [c, {FnCall: [transmute, [d]]}]] |
| ``` |
| |
| ### Explanation of fields |
| - `name` |
| - The name of the intrinsic |
| - Often built from a base name followed by a type suffix |
| - `doc` (_Optional_) |
| - A string explaining the purpose of the intrinsic |
| - `static_defs` (_Optional_) |
| - A sequence of const generics of the format `"const <NAME>: <type>"` |
| - `arguments` |
| - A sequence of strings in the format `"<argname>: <argtype>"` |
| - `return_type` (_Optional_) |
| - A string specifying the return type. If omitted, the intrinsic returns `()`. |
| - `attr` (_Optional_) |
| - A sequence of items defining the attributes to be applied to the intrinsic. Often stability attributes, target features, or `assert_instr` tests. At least one of `attr` or `assert_instr` must be set. |
| - `target_features` (_Optional_) |
| - A sequence of target features to enable for this intrinsic (merged with any global `arch_cfgs` settings). |
| - `assert_instr` (_Optional_) |
| - A sequence of strings expected to be found in the assembly. Required if `attr` is not set. |
| - `safety` (_Optional_) |
| - Use `safe`, or map `unsafe:` to a sequence of unsafety comments: |
| - `custom: "<string>"` |
| - `uninitialized` |
| - `pointer_offset`, `pointer_offset_vnum`, or `dereference` (optionally qualified with `predicated`, `predicated_non_faulting`, or `predicated_first_faulting`) |
| - `unpredictable_on_fault` |
| - `non_temporal` |
| - `neon` |
| - `no_provenance: "<string>"` |
| - `substitutions` (_Optional_) |
| - Mappings of custom wildcard names to either `MatchSize` or `MatchKind` expressions |
| - `types` |
| - A sequence or sequence of sequences specifying the types to use when producing each intrinsic variant. These sequences can then be indexed by wildcards. |
| - `constraints` (_Optional_) |
| - A sequence of mappings. Each specifies a variable and a constraint. The available mappings are: |
| - Assert a variable's value exists in a sequence of i32's |
| - Usage: `{ variable: <name>, any_values: [<i32>,...] }` |
| - Assert a variable's value exists in a range (inclusive) |
| - Usage: `{ variable: <name>, range: [<i32>, <i32>] }` |
| - Assert a variable's value exists in a range via a match (inclusive) |
| - Usage: `{ variable: <name>, range: <MatchSize returning [i32,i32]> }` |
| - Assert a variable's value does not exceed the number of elements in a SVE type `<type>`. |
| - Usage: `{ variable: <name>, sve_max_elems_type: <type> }` |
| - Assert a variable's value does not exceed the number of elements in a vector type `<type>`. |
| - Usage: `{ variable: <name>, vec_max_elems_type: <type> }` |
| - `predication_methods` (_Optional_) |
| - Configuration for predicate-form variants. Only used when the intrinsic name includes an `_m*_` wildcard (e.g., `{_mx}`, `{_mxz}`). |
| - `zeroing_method`: Required when requesting `_z`; either `{ drop: <arg> }` to remove an argument and replace it with a zero initialiser, or `{ select: <predicate_var> }` to select zeros into a predicate. |
| - `dont_care_method`: How `_x` should be implemented (`inferred`, `as_zeroing`, or `as_merging`). |
| - `compose` |
| - A sequence of expressions that make up the body of the intrinsic |
| - `big_endian_inverse` (_Optional_) |
| - A boolean, default false. If true, generates two implementations of each intrinsic variant, one for each endianness, and attempts to automatically generate the required bit swizzles |
| - `visibility` (_Optional_) |
| - Function visibility. One of `public` (default) or `private`. |
| - `n_variant_op` (_Optional_) |
| - Enables generation of an `_n` variant when the intrinsic name includes the `{_n}` wildcard. Set to the operand name that should be splattered for the `_n` form. |
| - `test` (_Optional_) |
| - When set, load/store tests are automatically generated. |
| - A mapping of either `load` or `store` to a number that indexes `types` to specify the type that the test should be addressing in memory. |
| ### Expressions |
| #### Common |
| - `Let` |
| - Defines a variable |
| - Usage: `Let: [<variable>, <type(optional)>, <expression>]` |
| - `Const` |
| - Defines a const |
| - Usage: `Const: [<variable>, <type>, <expression>]` |
| - `Assign` |
| - Performs variable assignment |
| - Usage: `Assign: [<variable>, <expression>]` |
| - `FnCall` |
| - Performs a function call |
| - Usage: `FnCall: [<function pointer: expression>, [<argument: expression>, ... ], [<turbofish argument: expression>, ...](optional), <unsafe wrapper(optional): bool>]` |
| - `MacroCall` |
| - Performs a macro call |
| - Usage: `MacroCall: [<macro name>, <token stream>]` |
| - `MethodCall` |
| - Performs a method call |
| - Usage: `MethodCall: [<object: expression>, <method name>, [<argument: expression>, ... ]]` |
| - `LLVMLink` |
| - Creates an LLVM link and stores the function's name in the wildcard `{llvm_link}` for later use in subsequent expressions. |
| - If left unset, the arguments and return type inherit from the intrinsic's signature by default. The links will also be set automatically if unset. |
| - Usage: |
| ```yaml |
| LLVMLink: |
| name: <name> |
| arguments: [<expression>, ... ](optional) |
| return_type: <return type>(optional) |
| links: (optional) |
| - link: <link> |
| arch: <arch> |
| - ... |
| ``` |
| - `Identifier` |
| - Emits a symbol. Prepend with a `$` to treat it as a scope variable, which engages variable tracking and enables inference. For example, `my_function_name` for a generic symbol or `$my_variable` for a variable. |
| - Usage `Identifier: [<symbol name>, <Variable|Symbol>]` |
| - `CastAs` |
| - Casts an expression to an unchecked type |
| - Usage: `CastAs: [<expression>, <type>]` |
| - `MatchSize` |
| - Allows for conditional generation depending on the size of a specified type |
| - Usage: |
| ```yaml |
| MatchSize: |
| - <type> |
| - default: <expression> |
| byte(optional): <expression> |
| halfword(optional): <expression> |
| doubleword(optional): <expression> |
| ``` |
| - `MatchKind` |
| - Allows for conditional generation depending on the kind of a specified type |
| ```yaml |
| MatchKind: |
| - <type> |
| - default: <expression> |
| float(optional): <expression> |
| unsigned(optional): <expression> |
| ``` |
| #### Rarely Used |
| - `IntConstant` |
| - Constant signed integer expression |
| - Usage: `IntConstant: <i32>` |
| - `FloatConstant` |
| - Constant floating-point expression |
| - Usage: `FloatConstant: <f32>` |
| - `BoolConstant` |
| - Constant boolean expression |
| - Usage: `BoolConstant: <bool>` |
| - `Array` |
| - An array of expressions |
| - Usage: `Array: [<expression>, ...]` |
| - `Multiply` |
| - Simply `*` |
| - Usage: `Multiply: [<expression>, <expression>]` |
| - `Xor` |
| - Simply `^` |
| - Usage: `Xor: [<expression>, <expression>]` |
| - `ConvertConst` |
| - Converts the specified constant to the specified type's kind |
| - Usage: `ConvertConst: [<type>, <i32>]` |
| - `Type` |
| - Yields the given type in the Rust representation |
| - Usage: `Type: [<type>]` |
| |
| ### Wildstrings |
| - Wildstrings let you take advantage of wildcards. |
| - For example, they are often used in intrinsic names `name: "vtst{neon_type[0].no}"` |
| - As shown above, wildcards are identified by the surrounding curly brackets. |
| - Double curly brackets can be used to escape wildcard functionality if you need literal curly brackets in the generated intrinsic. |
| ### Wildcards |
| Wildcards are heavily used in the spec. They let you write generalised definitions for a group of intrinsics that generate multiple variants. The wildcard itself is replaced with the relevant string in each variant. |
| Ignoring endianness, for each row in the `types` field of an intrinsic in the spec, a variant of the intrinsic will be generated. That row's contents can be indexed by the wildcards. Below is the behaviour of each wildcard. |
| - `type[<index: usize>]` |
| - Replaced in each variant with the value in the indexed position in the relevant row of the `types` field. |
| - For unnested sequences of `types` (i.e., `types` is a sequence where each element is a single item, not another sequence), the square brackets can be omitted. Simply: `type` |
| - `neon_type[<index: usize>]` |
| - Extends the behaviour of `type` with some NEON-specific features and inference. |
| - Tuples: This wildcard can also be written as `neon_type_x<n>` where `n` is in the set `{2,3,4}`. This generates the `n`-tuple variant of the (inferred) NEON type. |
| - Suffixes: These modify the behaviour of the wildcard from simple substitution. |
| - `no` - normal behaviour. Tries to do as much work as it can for you, inferring when to emit: |
| - Regular type-size suffixes: `_s8`, `_u16`, `_f32`, ... |
| - `q` variants for double-width (128b) vector types: `q_s8`, `q_u16`, `q_f32`, ... |
| - `_x<n>` variants for tuple vector types: `_s8_x2`, `_u32_x3`, `_f64_x4`, ... |
| - As well as any combination of the above: `q_s16_x16` ... |
| - Most of the other suffixes modify the normal behaviour by disabling features or adding new ones. (See table below) |
| - `sve_type[<index: usize>]` |
| - Similar to `neon_type`, but without the suffixes. |
| - `size[<index: usize>]` |
| - The size (in bits) of the indexed type. |
| - `size_minus_one[<index: usize>]` |
| - Emits the size (in bits) of the indexed type minus one. |
| - `size_literal[<index: usize>]` |
| - The literal representation of the indexed type. |
| - `b`: byte, `h`: halfword, `w`: word, or `d`: double. |
| - `type_kind[<index: usize>]` |
| - The literal representation of the indexed type's kind. |
| - `f`: float, `s`: signed, `u`: unsigned, `p`: polynomial, `b`: boolean. |
| - `size_in_bytes_log2[<index: usize>]` |
| - Log2 of the size of the indexed type in *bytes*. |
| - `predicate[<index: usize>]` |
| - SVE predicate vector type inferred from the indexed type. |
| - `max_predicate` |
| - The same as predicate, but uses the largest type in the relevant `types` sequence/row. |
| - `_n` |
| - Emits the current N-variant suffix when `n_variant_op` is configured. |
| - `<wildcard> as <type>` |
| - If `<wildcard>` evaluates to a vector, it produces a vector of the same shape, but with `<type>` as the base type. |
| - `llvm_link` |
| - If the `LLVMLink` mapping has been set for an intrinsic, this will give the name of the link. |
| - `_m*` |
| - Predicate form masks. Use wildcards such as `{_mx}` or `{_mxz}` to expand merging/don't-care/zeroing variants according to the mask. |
| - `<custom>` |
| - You may simply call upon wildcards defined under `substitutions`. |
| ### neon_type suffixes |
| |
| | suffix | implication | |
| | ----------------- | --------------------------------------------- | |
| | `.no` | Normal | |
| | `.noq` | Never include `q`s | |
| | `.nox` | Never include `_x<n>`s | |
| | `.N` | Include `_n_`, e.g., `_n_s8` | |
| | `.noq_N` | Include `_n_`, but never `q`s | |
| | `.dup` | Include `_dup_`, e.g., `_dup_s8` | |
| | `.dup_nox` | Include `_dup_` but never `_x<n>`s | |
| | `.lane` | Include `_lane_`, e.g., `_lane_s8` | |
| | `.lane_nox` | Include `_lane_`, but never `_x<n>`s | |
| | `.rot90` | Include `_rot90_`, e.g., `_rot90_s8` | |
| | `.rot180` | Include `_rot180_`, e.g., `_rot180_s8` | |
| | `.rot270` | Include `_rot270_`, e.g., `_rot270_s8` | |
| | `.rot90_lane` | Include `_rot90_lane_` | |
| | `.rot180_lane` | Include `_rot180_lane_` | |
| | `.rot270_lane` | Include `_rot270_lane_` | |
| | `.rot90_laneq` | Include `_rot90_laneq_` | |
| | `.rot180_laneq` | Include `_rot180_laneq_` | |
| | `.rot270_laneq` | Include `_rot270_laneq_` | |
| | `.base` | Produce only the size, e.g., `8`, `16` | |
| | `.u` | Produce the type's unsigned equivalent | |
| | `.laneq_nox` | Include `_laneq_`, but never `_x<n>`s | |
| | `.tuple` | Produce only the size of the tuple, e.g., `3` | |
| | `.base_byte_size` | Produce only the size in bytes. | |
| |
