Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reformat inline-assembly chapter as a spec chapter. #1523

Closed
wants to merge 32 commits into from
Closed
Changes from 1 commit
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
7f86242
Start reformat for inline-assembly chapter
chorman0773 Jun 19, 2024
72df943
Remove rule prefix from section header ids
chorman0773 Jul 2, 2024
5a75b51
Add [dynamic.asm.template] and [dynamic.asm.operands]
chorman0773 Jul 3, 2024
0397d44
Add dynamic.asm.options
chorman0773 Jul 4, 2024
2fdf1fb
Finish dynamic.asm.evaluation and dynamic.asm.directives
chorman0773 Jul 9, 2024
320b414
Format dynamic.asm.registers
chorman0773 Jul 9, 2024
80bf3cf
Format dynamic.asm.template
chorman0773 Jul 9, 2024
bf615a9
Add examples/tests to the inline-assembly chapter
chorman0773 Jul 9, 2024
6512bc6
Fix doc links in dynamic.asm.operands.types
chorman0773 Jul 9, 2024
2a9f58d
Edit styling of dynamic.asm and fix test failures
chorman0773 Jul 10, 2024
1d9770f
Merge branch 'master' into spec-reformat-asm
chorman0773 Jul 10, 2024
c3af3ca
Change chapter identifier to be `asm` rather than `dynamic.asm`
chorman0773 Jul 11, 2024
a82d8f9
Switch link for `__m128` and `__m256`
chorman0773 Jul 11, 2024
3563e5a
Remove colour from .target-specific
chorman0773 Jul 16, 2024
38d2dae
Fix inline assembly tests to be handled "properly" off of x86_64
chorman0773 Jul 16, 2024
a464e1a
Apply suggestions from PR Review
chorman0773 Jul 17, 2024
f69509b
Apply suggestions from code review
chorman0773 Jul 17, 2024
15db17f
Finish applying suggestions from PR review
chorman0773 Jul 17, 2024
b362778
Change wording for asm.safety note
chorman0773 Jul 18, 2024
3633034
Use `that` instead of `which` in asm.safety note
chorman0773 Jul 18, 2024
7a320d3
Fix global_asm tests to actually run
chorman0773 Jul 18, 2024
012d7f6
Use *asm block* and *global asm block* instead of "Expansion of [`cor…
chorman0773 Jul 18, 2024
f886a47
Fix extraneous `r` in "Template Modifiers" header
chorman0773 Jul 18, 2024
b6f4bbb
Apply suggestions from code review
chorman0773 Jul 18, 2024
88a3964
Fix code block formatting and use "fails to compile" instead of "ill-…
chorman0773 Jul 18, 2024
13884d0
Remove trailing spaces from markdown source lines
chorman0773 Jul 18, 2024
5c0e505
Don't link to a rule that does not yet exist
chorman0773 Jul 18, 2024
e2a7a47
Properly fix end of line spaces
chorman0773 Jul 18, 2024
457e1d6
Change link to inline-assembly.html to point to asm.evaluation
chorman0773 Jul 18, 2024
d59ad1f
Update src/inline-assembly.md
chorman0773 Jul 25, 2024
9b78523
Merge branch 'master' into spec-reformat-asm
chorman0773 Jul 25, 2024
90ef108
Remove added claims from inline-assembly document.
chorman0773 Jul 26, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Fix code block formatting and use "fails to compile" instead of "ill-…
…formed"
  • Loading branch information
chorman0773 committed Jul 18, 2024
commit 88a39645562293a49081b1b9fdc3bfcb3a1ce215
58 changes: 36 additions & 22 deletions src/inline-assembly.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The macros [`core::arch::asm!`] and [`core::arch::global_asm!`] are defined to s
> The expansion of the macros has no stable syntax equivalent. This section will refer to the expansion of the macro, rather than the surface syntax.

r[asm.safety]
The macro [`core::arch::asm!`] shall be expanded only within an `unsafe` block.
The macro [`core::arch::asm!`] shall be invoked only within an `unsafe` block.

> [!NOTE]
> Inline assembly is inherently unsafe.
Expand All @@ -18,13 +18,13 @@ The macro [`core::arch::asm!`] shall be expanded only within an `unsafe` block.

```rust,compile_fail
# #[cfg(target_arch = "x86_64")] {
use core::arch::asm;
asm!("/*inline assembly is inherently unsafe*/");
use core::arch::asm;
asm!("/*inline assembly is inherently unsafe*/");
# }
```

r[asm.support]
Inline assembly is supported only when compiling for a target using one of the following architectures. A program that contains inline assembly is ill-formed on any other target:
Inline assembly is supported only when compiling for a target using one of the following architectures. A program that contains inline assembly fails to compile on any other target:
- x86 and x86-64
- ARM
- AArch64
Expand Down Expand Up @@ -83,8 +83,10 @@ format_escape := "{{" / "}}"
asm_string_piece := non_format_char / format_specifier / format_escape
asm_string_content := [*asm_string_piece]

exposition-only_asm = /*asm-block*/ "(" asm_inner ")" // Exposition Only
exposition-only_global_asm = /*global-asm*/ "(" asm_inner ")" // Exposition Only
// Exposition Only, not valid in rust code
asm-block = /*asm-block*/ "(" asm_inner ")"
// Exposition Only, not valid in rust code
global-asm-block = /*global-asm*/ "(" asm_inner ")"
```

## Invocation
Expand Down Expand Up @@ -135,14 +137,14 @@ Unless the `raw` option is specified, each `format_string` input to the [`core::


r[asm.invocation.concat]
If multiple `format_string` inputs are provided, then they are concatenated as though by the [`core::concat!`] macro, separating each `format_string` with a string containing a single newline character. If any `format_string` begins a `format_specifier` that is not terminated before the end of the `format_string`, the program is ill-formed. The resulting string is known as the *joined asm-string*
If multiple `format_string` inputs are provided, then they are concatenated as though by the [`core::concat!`] macro, separating each `format_string` with a string containing a single newline character. If any `format_string` begins a `format_specifier` that is not terminated before the end of the `format_string`, the program fails to compile. The resulting string is known as the *joined asm-string*

```rust
# #[cfg(target_arch = "x86_64")] {unsafe{
let mut x: i32;
// The following lines are equivalent
core::arch::asm!("mov rax, 5", "mov rcx, rax", out("rax") x, out("rcx") _);
core::arch::asm!("mov rax, 5\nmov rcx, rax", out("rax") x, out("rcx") _);
core::arch::asm!("mov rax, 5", "mov rcx, rax", out("rax") x, out("rcx") _);
core::arch::asm!("mov rax, 5\nmov rcx, rax", out("rax") x, out("rcx") _);
# }}
```

Expand All @@ -154,7 +156,7 @@ Each operand, other than an explicit register operand ([asm.operands.register])
core::arch::asm!("", in(reg) 5i64);
# }}
# #[cfg(not(target_arch = "x86_64"))]
# core::compile_error!("asm tests are not yet available off of x86_64");
# core::compile_error!("asm tests are not yet available off of x86_64");
```

r[asm.invocation.positional]
Expand Down Expand Up @@ -305,7 +307,8 @@ struct Foo{x: i32}
let x: Foo;
core::arch::asm!("mov {output}, {input}", input = in(reg) 5i64, out("eax") x);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

```rust,compile_fail
Expand All @@ -314,7 +317,8 @@ core::arch::asm!("mov {output}, {input}", input = in(reg) 5i64, out("eax") x);
let x: *mut [i32];
core::arch::asm!("mov {output}, {input}", input = in(reg) 5i64, out("eax") x);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```


Expand All @@ -340,7 +344,8 @@ Each reference type, where the pointee type has no metadata-type, and each funct
# #[cfg(target_arch = "x86_64")] { unsafe{
let x = 5;
let y: i32;
core::arch::asm!("mov eax, dword ptr [{}]", in(reg) &x, out("eax") y); // equivalent to asm!("mov eax, dword ptr [{}]", in(reg) (&x) as *const i32, out("eax") y);
core::arch::asm!("mov eax, dword ptr [{}]", in(reg) &x, out("eax") y);
// equivalent to asm!("mov eax, dword ptr [{}]", in(reg) (&x) as *const i32, out("eax") y);
# }}
```

Expand All @@ -349,7 +354,8 @@ core::arch::asm!("mov eax, dword ptr [{}]", in(reg) &x, out("eax") y); // equiva
let y: &mut i32;
core::arch::asm!("mov {}, 0", out(reg) 5);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```


Expand All @@ -364,7 +370,8 @@ An `output_expr` shall be the placeholder expression `_` or a (potentially unini
let x: i32 = 0;
core::arch::asm!("", out("eax") x);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

r[asm.operands.inout-expr]
Expand Down Expand Up @@ -403,7 +410,7 @@ core::arch::asm!("mov eax, 5", out("eax") _);
```

r[asm.operands.sym-expr]
A sym-expr is a path-expr. If the `path-expr` does not refer to a `static` item or a `fn` item, the program is ill-formed.
A sym-expr is a path-expr. If the `path-expr` does not refer to a `static` item or a `fn` item, the program fails to compile.

> [!NOTE]
> the path-expr may have any type, including a type that isn't an *asm operand type*, and may be either mutable or immutable.
Expand Down Expand Up @@ -440,7 +447,8 @@ The program shall not use an operand, other than a sym operand, in the expansion
```rust,compile_fail
# #[cfg(target_arch = "x86_64")]
core::arch::global_asm!("", in("eax") 5);
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");

# fn main(){}
```
Expand Down Expand Up @@ -582,7 +590,8 @@ Certain registers and register classes are *clobbers only*. Such register names
let x: i64;
core::arch::asm!("mov {}, 5", out("k0") x);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

r[asm.register.small-values]
Expand Down Expand Up @@ -699,7 +708,8 @@ Certain registers are reserved registers. Reserved Registers shall not be named
# #[cfg(target_arch = "x86_64")] { unsafe{
core::arch::asm!("mov rsp, 5", out("rsp") x);
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

## Template modifiers
Expand Down Expand Up @@ -890,7 +900,8 @@ An *asm block* shall not specify both the `nomem` and `readonly` options.
# #[cfg(target_arch = "x86_64")] { unsafe{
core::arch::asm!("mov dword ptr [FOO+rip], 3", options(readonly, nomem));
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

r[asm.options.pure]
Expand Down Expand Up @@ -975,7 +986,8 @@ core::arch::asm!("", options(noreturn));
let x: i32;
core::arch::asm!("xor edi, edi", "call exit@plt", out("edi") x, options(noreturn));
# }}
# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");
```

r[asm.options.global]
Expand All @@ -985,7 +997,8 @@ A program shall not specify an option, other than the `att_syntax` or `raw` opti
# #[cfg(target_arch = "x86_64")]
core::arch::global_asm!("", options(noreturn));

# #[cfg(not(target_arch = "x86_64"))] compile_error!("Inline Assembly Tests are not supported off of x86_64");
# #[cfg(not(target_arch = "x86_64"))]
# compile_error!("Inline Assembly Tests are not supported off of x86_64");

# fn main(){}
```
Expand Down Expand Up @@ -1099,6 +1112,7 @@ r[asm.directives.x86]

r[asm.directives.arm]

> [!TARGET-SPECIFIC]
> The following directives are guaranteed to be supported on 32-bit ARM platforms
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this [!TARGET-SPECIFIC] too?

> - `.even`
> - `.fnstart`
Expand Down