From f6b34bd64d13401f4241a306bfa4fe8d63d2b3ac Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Sun, 1 Dec 2024 19:07:13 -0800
Subject: [PATCH] Add `core::arch::breakpoint` and test

Approved in [ACP 491](https://github.com/rust-lang/libs-team/issues/491).
---
 library/core/src/arch.rs           | 26 ++++++++++++++++++++++++++
 library/core/src/intrinsics/mod.rs |  4 ++--
 tests/assembly/breakpoint.rs       | 16 ++++++++++++++++
 3 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 tests/assembly/breakpoint.rs

diff --git a/library/core/src/arch.rs b/library/core/src/arch.rs
index 57f456c98b3c6..cb130f60cecf1 100644
--- a/library/core/src/arch.rs
+++ b/library/core/src/arch.rs
@@ -42,3 +42,29 @@ pub macro naked_asm("assembly template", $(operands,)* $(options($(option),*))?)
 pub macro global_asm("assembly template", $(operands,)* $(options($(option),*))?) {
     /* compiler built-in */
 }
+
+/// Compiles to a target-specific software breakpoint instruction or equivalent.
+///
+/// This will typically abort the program. It may result in a core dump, and/or the system logging
+/// debug information. Additional target-specific capabilities may be possible depending on
+/// debuggers or other tooling; in particular, a debugger may be able to resume execution.
+///
+/// If possible, this will produce an instruction sequence that allows a debugger to resume *after*
+/// the breakpoint, rather than resuming *at* the breakpoint; however, the exact behavior is
+/// target-specific and debugger-specific, and not guaranteed.
+///
+/// If the target platform does not have any kind of debug breakpoint instruction, this may compile
+/// to a trapping instruction (e.g. an undefined instruction) instead, or to some other form of
+/// target-specific abort that may or may not support convenient resumption.
+///
+/// The precise behavior and the precise instruction generated are not guaranteed, except that in
+/// normal execution with no debug tooling involved this will not continue executing.
+///
+/// - On x86 targets, this produces an `int3` instruction.
+/// - On aarch64 targets, this produces a `brk #0xf000` instruction.
+// When stabilizing this, update the comment on `core::intrinsics::breakpoint`.
+#[unstable(feature = "breakpoint", issue = "133724")]
+#[inline(always)]
+pub fn breakpoint() {
+    core::intrinsics::breakpoint();
+}
diff --git a/library/core/src/intrinsics/mod.rs b/library/core/src/intrinsics/mod.rs
index 46873fdc0479f..da31d5cf34f6b 100644
--- a/library/core/src/intrinsics/mod.rs
+++ b/library/core/src/intrinsics/mod.rs
@@ -1375,9 +1375,9 @@ pub unsafe fn prefetch_write_instruction<T>(_data: *const T, _locality: i32) {
     unreachable!()
 }
 
-/// Executes a breakpoint trap, for inspection by a debugger.
+/// Compiles to a target-specific software breakpoint instruction or equivalent.
 ///
-/// This intrinsic does not have a stable counterpart.
+/// The (future) stabilized version of this intrinsic is [`core::arch::breakpoint`].
 #[rustc_intrinsic]
 #[rustc_intrinsic_must_be_overridden]
 #[rustc_nounwind]
diff --git a/tests/assembly/breakpoint.rs b/tests/assembly/breakpoint.rs
new file mode 100644
index 0000000000000..93f1c1083c87c
--- /dev/null
+++ b/tests/assembly/breakpoint.rs
@@ -0,0 +1,16 @@
+//@ revisions: aarch64 x86_64
+//@ assembly-output: emit-asm
+//@[aarch64] compile-flags: --target aarch64-unknown-linux-gnu
+//@[aarch64] needs-llvm-components: aarch64
+//@[x86_64] compile-flags: --target x86_64-unknown-linux-gnu -C llvm-args=-x86-asm-syntax=intel
+//@[x86_64] needs-llvm-components: x86
+
+#![feature(breakpoint)]
+#![crate_type = "lib"]
+
+// CHECK-LABEL: use_bp
+// aarch64: brk #0xf000
+// x86_64: int3
+pub fn use_bp() {
+    core::arch::breakpoint();
+}