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#[stable(feature = "naked_functions", since = "1.88.0")]
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 is not guaranteed, it depends on the architecture and operating system.
69/// Not all architectures guarantee that a breakpoint instruction interrupts execution in the absence
70/// of a debugger, and not all operating systems and execution environments guarantee that such an
71/// interrupt aborts the current process.
72///
73/// The precise instruction is guaranteed only on the following targets:
74/// - On x86 targets, this produces an `int3` instruction.
75/// - On aarch64 targets, this produces a `brk #0xf000` instruction.
76// When adding more items above, also add cases to the test in `tests/assembly-llvm/breakpoint.rs`.
77// When stabilizing this, update the comment on `core::intrinsics::breakpoint`.
78#[unstable(feature = "breakpoint", issue = "133724")]
79#[inline(always)]
80pub fn breakpoint() {
81    core::intrinsics::breakpoint();
82}
83
84/// The `core::arch::return_address!()` macro returns a pointer with an address that corresponds to the caller of the function that invoked the `return_address!()` macro.
85/// The pointer has no provenance, as if created by `core::ptr::without_provenance`. It cannot be used to read memory (other than ZSTs).
86///
87/// The value returned by the macro depends highly on the architecture and compiler (including any options set).
88/// In particular, it is allowed to be wrong (particularly if inlining is involved), or even contain a nonsense value.
89/// The result of this macro must not be relied upon for soundness or correctness, only for debugging purposes.
90///
91/// As a best effort, if a useful value cannot be determined (for example, due to limitations on the current codegen),
92/// this macro tries to return a null pointer instead of nonsense (this cannot be relied upon for correctness, however).
93///
94/// Formally, this function returns a pointer with a non-deterministic address and no provenance.
95///
96/// This is equivalent to the gcc `__builtin_return_address(0)` intrinsic (other forms of the intrinsic are not supported).
97/// Because the operation can be always performed by the compiler without crashing or causing undefined behaviour, invoking the macro is a safe operation.
98///
99/// ## Example
100/// ```
101/// #![feature(return_address)]
102///
103/// # fn run_test() {
104/// let addr = core::arch::return_address!();
105/// println!("Caller is {addr:p}");
106/// # }
107/// # #[cfg(not(miri))] // FIXME: Figure out how to make miri work before stabilizing this macro
108/// # run_test()
109/// ```
110#[unstable(feature = "return_address", issue = "154966")]
111#[allow_internal_unstable(core_intrinsics)]
112pub macro return_address() {{ core::intrinsics::return_address() }}
core/arch.rs

core/
arch.rs
