core/
arch.rs

1#![doc = include_str!("../../stdarch/crates/core_arch/src/core_arch_docs.md")]
2
3#[allow(
4    // some targets don't have anything to reexport, which
5    // makes the `pub use` unused and unreachable, allow
6    // both lints as to not have `#[cfg]`s
7    //
8    // cf. https://github.com/rust-lang/rust/pull/116033#issuecomment-1760085575
9    unused_imports,
10    unreachable_pub
11)]
12#[stable(feature = "simd_arch", since = "1.27.0")]
13pub use crate::core_arch::arch::*;
14
15/// Inline assembly.
16///
17/// Refer to [Rust By Example] for a usage guide and the [reference] for
18/// detailed information about the syntax and available options.
19///
20/// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html
21/// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html
22#[stable(feature = "asm", since = "1.59.0")]
23#[rustc_builtin_macro]
24pub macro asm("assembly template", $(operands,)* $(options($(option),*))?) {
25    /* compiler built-in */
26}
27
28/// Inline assembly used in combination with `#[naked]` functions.
29///
30/// Refer to [Rust By Example] for a usage guide and the [reference] for
31/// detailed information about the syntax and available options.
32///
33/// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html
34/// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html
35#[unstable(feature = "naked_functions", issue = "90957")]
36#[rustc_builtin_macro]
37pub macro naked_asm("assembly template", $(operands,)* $(options($(option),*))?) {
38    /* compiler built-in */
39}
40
41/// Module-level inline assembly.
42///
43/// Refer to [Rust By Example] for a usage guide and the [reference] for
44/// detailed information about the syntax and available options.
45///
46/// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html
47/// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html
48#[stable(feature = "global_asm", since = "1.59.0")]
49#[rustc_builtin_macro]
50pub macro global_asm("assembly template", $(operands,)* $(options($(option),*))?) {
51    /* compiler built-in */
52}
53
54/// Compiles to a target-specific software breakpoint instruction or equivalent.
55///
56/// This will typically abort the program. It may result in a core dump, and/or the system logging
57/// debug information. Additional target-specific capabilities may be possible depending on
58/// debuggers or other tooling; in particular, a debugger may be able to resume execution.
59///
60/// If possible, this will produce an instruction sequence that allows a debugger to resume *after*
61/// the breakpoint, rather than resuming *at* the breakpoint; however, the exact behavior is
62/// target-specific and debugger-specific, and not guaranteed.
63///
64/// If the target platform does not have any kind of debug breakpoint instruction, this may compile
65/// to a trapping instruction (e.g. an undefined instruction) instead, or to some other form of
66/// target-specific abort that may or may not support convenient resumption.
67///
68/// The precise behavior and the precise instruction generated are not guaranteed, except that in
69/// normal execution with no debug tooling involved this will not continue executing.
70///
71/// - On x86 targets, this produces an `int3` instruction.
72/// - On aarch64 targets, this produces a `brk #0xf000` instruction.
73// When stabilizing this, update the comment on `core::intrinsics::breakpoint`.
74#[unstable(feature = "breakpoint", issue = "133724")]
75#[inline(always)]
76pub fn breakpoint() {
77    core::intrinsics::breakpoint();
78}