diff --git a/crates/stdarch-gen-arm/README.md b/crates/stdarch-gen-arm/README.md new file mode 100644 index 0000000000..4da14bcbb6 --- /dev/null +++ b/crates/stdarch-gen-arm/README.md @@ -0,0 +1,300 @@ +# stdarch-gen-arm generator guide +## Running the generator +- Run: `cargo run --bin=stdarch-gen-arm -- crates/stdarch-gen-arm/spec` +``` +$ cargo run --bin=stdarch-gen-arm -- crates/stdarch-gen-arm/spec + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.18s + Running `target/debug/stdarch-gen-arm crates/stdarch-gen-arm/spec` +``` +## Input/Output +### Input files (intrinsic YAML definitions) + - `crates/stdarch-gen-arm/spec//*.spec.yml` +### Output files + - Generated intrinsics: + - `crates/core_arch/src///generated.rs` + - Generated load/store tests: + - `crates/core_arch/src///ld_st_tests_.rs` + - Only generated when `test: { load: }` or `test: { store: }` 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 : "` +- `arguments` + - A sequence of strings in the format `": "` +- `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: ""` + - `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: ""` +- `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: , any_values: [,...] }` + - Assert a variable's value exists in a range (inclusive) + - Usage: `{ variable: , range: [, ] }` + - Assert a variable's value exists in a range via a match (inclusive) + - Usage: `{ variable: , range: }` + - Assert a variable's value does not exceed the number of elements in a SVE type ``. + - Usage: `{ variable: , sve_max_elems_type: }` + - Assert a variable's value does not exceed the number of elements in a vector type ``. + - Usage: `{ variable: , vec_max_elems_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: }` to remove an argument and replace it with a zero initialiser, or `{ select: }` 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: [, , ]` +- `Const` + - Defines a const + - Usage: `Const: [, , ]` +- `Assign` + - Performs variable assignment + - Usage: `Assign: [, ]` +- `FnCall` + - Performs a function call + - Usage: `FnCall: [, [, ... ], [, ...](optional), ]` +- `MacroCall` + - Performs a macro call + - Usage: `MacroCall: [, ]` +- `MethodCall` + - Performs a method call + - Usage: `MethodCall: [, , [, ... ]]` +- `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: + arguments: [, ... ](optional) + return_type: (optional) + links: (optional) + - link: + 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: [, ]` +- `CastAs` + - Casts an expression to an unchecked type + - Usage: `CastAs: [, ]` +- `MatchSize` + - Allows for conditional generation depending on the size of a specified type + - Usage: +```yaml +MatchSize: + - + - default: + byte(optional): + halfword(optional): + doubleword(optional): +``` +- `MatchKind` + - Allows for conditional generation depending on the kind of a specified type +```yaml +MatchKind: + - + - default: + float(optional): + unsigned(optional): +``` +#### Rarely Used +- `IntConstant` + - Constant signed integer expression + - Usage: `IntConstant: ` +- `FloatConstant` + - Constant floating-point expression + - Usage: `FloatConstant: ` +- `BoolConstant` + - Constant boolean expression + - Usage: `BoolConstant: ` +- `Array` + - An array of expressions + - Usage: `Array: [, ...]` +- `SvUndef` + - Returns the LLVM `undef` symbol + - Usage: `SvUndef` +- `Multiply` + - Simply `*` + - Usage: `Multiply: [, ]` +- `Xor` + - Simply `^` + - Usage: `Xor: [, ]` +- `ConvertConst` + - Converts the specified constant to the specified type's kind + - Usage: `ConvertConst: [, ]` +- `Type` + - Yields the given type in the Rust representation + - Usage: `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[]` + - 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[]` + - Extends the behaviour of `type` with some NEON-specific features and inference. + - Tuples: This wildcard can also be written as `neon_type_x` 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` 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[]` + - Similar to `neon_type`, but without the suffixes. +- `size[]` + - The size (in bits) of the indexed type. +- `size_minus_one[]` + - Emits the size (in bits) of the indexed type minus one. +- `size_literal[]` + - The literal representation of the indexed type. + - `b`: byte, `h`: halfword, `w`: word, or `d`: double. +- `type_kind[]` + - The literal representation of the indexed type's kind. + - `f`: float, `s`: signed, `u`: unsigned, `p`: polynomial, `b`: boolean. +- `size_in_bytes_log2[]` + - Log2 of the size of the indexed type in *bytes*. +- `predicate[]` + - 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. +- ` as ` + - If `` evaluates to a vector, it produces a vector of the same shape, but with `` 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. +- `` + - 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`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`s | +| `.lane` | Include `_lane_`, e.g., `_lane_s8` | +| `.lane_nox` | Include `_lane_`, but never `_x`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`s | +| `.tuple` | Produce only the size of the tuple, e.g., `3` | +| `.base_byte_size` | Produce only the size in bytes. | +