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 if possible,
55/// falling back to an alternative trap or an abort.
56///
57/// This will typically abort the program. It may result in a core dump, and/or the system logging
58/// debug information. Additional target-specific capabilities may be possible depending on
59/// debuggers or other tooling; in particular, a debugger may be able to resume execution.
60///
61/// If possible, this will produce an instruction sequence that allows a debugger to resume *after*
62/// the breakpoint, rather than resuming *at* the breakpoint; however, the exact behavior is
63/// target-specific and debugger-specific, and not guaranteed.
64///
65/// If the target platform does not have any kind of debug breakpoint instruction, this may compile
66/// to a trapping instruction (e.g. an undefined instruction) instead, or to some other form of
67/// target-specific abort that may or may not support convenient resumption.
68///
69/// The precise behavior is not guaranteed, it depends on the architecture and operating system.
70/// Not all architectures guarantee that a breakpoint instruction interrupts execution in the absence
71/// of a debugger, and not all operating systems and execution environments guarantee that such an
72/// interrupt aborts the current process. On operating systems where the behavior of the interrupt
73/// can be overwritten by the application (e.g. via a SIGTRAP signal handler), the application
74/// *should* make sure to still abort the process. However, code not fully in control of that
75/// application state (e.g. signal handlers) cannot always rely on that for soundness.
76/// If you do rely on this, such that your code's soundness requires applications to not continue
77/// from your breakpoints, please document that for your users.
78///
79/// The precise instruction is guaranteed only on the following targets:
80/// - On x86 targets, this produces an `int3` instruction.
81/// - On aarch64 targets, this produces a `brk #0xf000` instruction.
82// When adding more items above, also add cases to the test in `tests/assembly-llvm/intrinsics.rs`.
83// When stabilizing this, update the comment on `core::intrinsics::breakpoint`.
84// NOTE: there is an alternative in `process::resumable_breakpoint`. We may or may not
85// actually want to stabilize both of them.
86#[unstable(feature = "breakpoint", issue = "133724")]
87#[inline(always)]
88pub fn breakpoint() {
89    core::intrinsics::breakpoint();
90}
91
92/// 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.
93/// The pointer has no provenance, as if created by `core::ptr::without_provenance`. It cannot be used to read memory (other than ZSTs).
94///
95/// The value returned by the macro depends highly on the architecture and compiler (including any options set).
96/// In particular, it is allowed to be wrong (particularly if inlining is involved), or even contain a nonsense value.
97/// The result of this macro must not be relied upon for soundness or correctness, only for debugging purposes.
98///
99/// As a best effort, if a useful value cannot be determined (for example, due to limitations on the current codegen),
100/// this macro tries to return a null pointer instead of nonsense (this cannot be relied upon for correctness, however).
101///
102/// Formally, this function returns a pointer with a non-deterministic address and no provenance.
103///
104/// This is equivalent to the gcc `__builtin_return_address(0)` intrinsic (other forms of the intrinsic are not supported).
105/// Because the operation can be always performed by the compiler without crashing or causing undefined behaviour, invoking the macro is a safe operation.
106///
107/// ## Example
108/// ```
109/// #![feature(return_address)]
110///
111/// # fn run_test() {
112/// let addr = core::arch::return_address!();
113/// println!("Caller is {addr:p}");
114/// # }
115/// # #[cfg(not(miri))] // FIXME: Figure out how to make miri work before stabilizing this macro
116/// # run_test()
117/// ```
118#[unstable(feature = "return_address", issue = "154966")]
119#[allow_internal_unstable(core_intrinsics)]
120pub macro return_address() {{ core::intrinsics::return_address() }}
core/arch.rs

core/
arch.rs
