[DRAFT] intrinsics for all architectures appear in rustdoc (#1104)

Author: Byron

crates/core_arch/src/aarch64/armclang.rs

@@ -0,0 +1,23 @@
+//! ARM compiler specific intrinsics
+//!
+//! # References
+//!
+//! - [ARM Compiler v 6.10 - armclang Reference Guide][arm_comp_ref]
+//!
+//! [arm_comp_ref]: https://developer.arm.com/docs/100067/0610
+
+#[cfg(test)]
+use stdarch_test::assert_instr;
+
+/// Inserts a breakpoint instruction.
+///
+/// `VAL` is a compile-time constant integer in range `[0, 65535]`.
+///
+/// The breakpoint instruction inserted is `BRK` on A64.
+#[cfg_attr(test, assert_instr(brk, VAL = 0))]
+#[inline(always)]
+#[rustc_legacy_const_generics(0)]
+pub unsafe fn __breakpoint<const VAL: i32>() {
+    static_assert_imm16!(VAL);
+    asm!("brk {}", const VAL);
+}

crates/core_arch/src/aarch64/mod.rs

@@ -21,7 +21,11 @@ pub use self::crc::*;
 mod prefetch;
 pub use self::prefetch::*;
 
-pub use super::acle::*;
+pub use super::arm_shared::*;
+
+mod armclang;
+
+pub use self::armclang::*;
 
 #[cfg(test)]
 use stdarch_test::assert_instr;

crates/core_arch/src/aarch64/neon/mod.rs

@@ -10,7 +10,7 @@ pub use self::generated::*;
 // FIXME: replace neon with asimd
 
 use crate::{
-    core_arch::{arm::*, simd::*, simd_llvm::*},
+    core_arch::{arm_shared::*, simd::*, simd_llvm::*},
     hint::unreachable_unchecked,
     mem::{transmute, zeroed},
 };
@@ -2812,7 +2812,7 @@ pub unsafe fn vsriq_n_p16<const N: i32>(a: poly16x8_t, b: poly16x8_t) -> poly16x
 #[cfg(test)]
 mod tests {
     use crate::core_arch::aarch64::test_support::*;
-    use crate::core_arch::arm::test_support::*;
+    use crate::core_arch::arm_shared::test_support::*;
     use crate::core_arch::{aarch64::neon::*, aarch64::*, simd::*};
     use std::mem::transmute;
     use stdarch_test::simd_test;
@@ -4261,13 +4261,13 @@ mod tests {
 
 #[cfg(test)]
 #[cfg(target_endian = "little")]
-#[path = "../../arm/neon/table_lookup_tests.rs"]
+#[path = "../../arm_shared/neon/table_lookup_tests.rs"]
 mod table_lookup_tests;
 
 #[cfg(test)]
-#[path = "../../arm/neon/shift_and_insert_tests.rs"]
+#[path = "../../arm_shared/neon/shift_and_insert_tests.rs"]
 mod shift_and_insert_tests;
 
 #[cfg(test)]
-#[path = "../../arm/neon/load_tests.rs"]
+#[path = "../../arm_shared/neon/load_tests.rs"]
 mod load_tests;

crates/core_arch/src/aarch64/test_support.rs

@@ -1,4 +1,4 @@
-use crate::core_arch::{aarch64::neon::*, arm::*, simd::*};
+use crate::core_arch::{aarch64::neon::*, arm_shared::*, simd::*};
 use std::{i16, i32, i8, mem::transmute, u16, u32, u8, vec::Vec};
 
 macro_rules! V_u64 {

crates/core_arch/src/arm/armclang.rs

@@ -9,20 +9,6 @@
 #[cfg(test)]
 use stdarch_test::assert_instr;
 
-/// Inserts a breakpoint instruction.
-///
-/// `VAL` is a compile-time constant integer in range `[0, 65535]`.
-///
-/// The breakpoint instruction inserted is `BRK` on A64.
-#[cfg(all(target_arch = "aarch64", not(doc)))]
-#[cfg_attr(test, assert_instr(brk, VAL = 0))]
-#[inline(always)]
-#[rustc_legacy_const_generics(0)]
-pub unsafe fn __breakpoint<const VAL: i32>() {
-    static_assert_imm16!(VAL);
-    asm!("brk {}", const VAL);
-}
-
 /// Inserts a breakpoint instruction.
 ///
 /// `VAL` is a compile-time constant integer in range `[0, 255]`.
@@ -40,8 +26,6 @@ pub unsafe fn __breakpoint<const VAL: i32>() {
 /// The current implementation only accepts values in range `[0, 255]`.
 ///
 /// [arm_docs]: https://developer.arm.com/docs/100067/latest/compiler-specific-intrinsics/__breakpoint-intrinsic
-#[cfg(any(target_arch = "arm", doc))]
-#[doc(cfg(target_arch = "arm"))]
 #[cfg_attr(test, assert_instr(bkpt, VAL = 0))]
 #[inline(always)]
 #[rustc_legacy_const_generics(0)]

crates/core_arch/src/acle/dsp.rs renamed to crates/core_arch/src/arm/dsp.rs

@@ -8,6 +8,7 @@
 #[cfg(any(
     all(target_feature = "v6k", not(target_feature = "mclass")), // excludes v6-M
     all(target_feature = "v7", target_feature = "mclass"), // v7-M
+    doc
 ))]
 pub unsafe fn __clrex() {
     extern "C" {
@@ -21,9 +22,10 @@ pub unsafe fn __clrex() {
 /// Executes a exclusive LDR instruction for 8 bit value.
 // Supported: v6K, v7-M, v7-A, v7-R
 // Not supported: v5, v6, v6-M
-#[cfg(
+#[cfg(any(
     target_feature = "v6k", // includes v7-M but excludes v6-M
-)]
+    doc
+))]
 pub unsafe fn __ldrexb(p: *const u8) -> u8 {
     extern "C" {
         #[link_name = "llvm.arm.ldrex.p0i8"]
@@ -36,9 +38,10 @@ pub unsafe fn __ldrexb(p: *const u8) -> u8 {
 /// Executes a exclusive LDR instruction for 16 bit value.
 // Supported: v6K, v7-M, v7-A, v7-R, v8
 // Not supported: v5, v6, v6-M
-#[cfg(
+#[cfg(any(
     target_feature = "v6k", // includes v7-M but excludes v6-M
-)]
+    doc
+))]
 pub unsafe fn __ldrexh(p: *const u16) -> u16 {
     extern "C" {
         #[link_name = "llvm.arm.ldrex.p0i16"]
@@ -54,6 +57,7 @@ pub unsafe fn __ldrexh(p: *const u16) -> u16 {
 #[cfg(any(
     all(target_feature = "v6", not(target_feature = "mclass")), // excludes v6-M
     all(target_feature = "v7", target_feature = "mclass"), // v7-M
+    doc
 ))]
 pub unsafe fn __ldrex(p: *const u32) -> u32 {
     extern "C" {
@@ -69,9 +73,10 @@ pub unsafe fn __ldrex(p: *const u32) -> u32 {
 /// Returns `0` if the operation succeeded, or `1` if it failed
 // supported: v6K, v7-M, v7-A, v7-R
 // Not supported: v5, v6, v6-M
-#[cfg(
+#[cfg(any(
     target_feature = "v6k", // includes v7-M but excludes v6-M
-)]
+    doc
+))]
 pub unsafe fn __strexb(value: u32, addr: *mut u8) -> u32 {
     extern "C" {
         #[link_name = "llvm.arm.strex.p0i8"]
@@ -86,9 +91,11 @@ pub unsafe fn __strexb(value: u32, addr: *mut u8) -> u32 {
 /// Returns `0` if the operation succeeded, or `1` if it failed
 // Supported: v6K, v7-M, v7-A, v7-R, v8
 // Not supported: v5, v6, v6-M
-#[cfg(
+#[cfg(target_feature = "aarch64")]
+#[cfg(any(
     target_feature = "v6k", // includes v7-M but excludes v6-M
-)]
+    doc
+))]
 pub unsafe fn __strexh(value: u16, addr: *mut u16) -> u32 {
     extern "C" {
         #[link_name = "llvm.arm.strex.p0i16"]
@@ -106,6 +113,7 @@ pub unsafe fn __strexh(value: u16, addr: *mut u16) -> u32 {
 #[cfg(any(
     all(target_feature = "v6", not(target_feature = "mclass")), // excludes v6-M
     all(target_feature = "v7", target_feature = "mclass"), // v7-M
+    doc
 ))]
 pub unsafe fn __strex(value: u32, addr: *mut u32) -> u32 {
     extern "C" {

crates/core_arch/src/acle/ex.rs renamed to crates/core_arch/src/arm/ex.rs

@@ -5,40 +5,81 @@
 //!
 //! [arm_ref]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf
 //! [arm_dat]: https://developer.arm.com/technologies/neon/intrinsics
-#![allow(non_camel_case_types)]
 
 mod armclang;
-
 pub use self::armclang::*;
 
 mod v6;
 pub use self::v6::*;
 
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-mod v7;
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-pub use self::v7::*;
+// Supported arches: 6, 7-M. See Section 10.1 of ACLE (e.g. SSAT)
+#[cfg(any(target_feature = "v6", doc))]
+mod sat;
+
+#[cfg(any(target_feature = "v6", doc))]
+pub use self::sat::*;
+
+// Supported arches: 5TE, 7E-M. See Section 10.1 of ACLE (e.g. QADD)
+// We also include the A profile even though DSP is deprecated on that profile as of ACLE 2.0 (see
+// section 5.4.7)
+// Here we workaround the difference between LLVM's +dsp and ACLE's __ARM_FEATURE_DSP by gating on
+// '+v5te' rather than on '+dsp'
+#[cfg(any(
+    // >= v5TE but excludes v7-M
+    all(target_feature = "v5te", not(target_feature = "mclass")),
+    // v7E-M
+    all(target_feature = "mclass", target_feature = "dsp"),
+    doc,
+))]
+pub mod dsp;
+
+#[cfg(any(
+    // >= v5TE but excludes v7-M
+    all(target_feature = "v5te", not(target_feature = "mclass")),
+    // v7E-M
+    all(target_feature = "mclass", target_feature = "dsp"),
+    doc,
+))]
+pub use self::dsp::*;
+
+// Deprecated in ACLE 2.0 for the A profile but fully supported on the M and R profiles, says
+// Section 5.4.9 of ACLE. We'll expose these for the A profile even if deprecated
+#[cfg(any(
+    // v7-A, v7-R
+    all(target_feature = "v6", not(target_feature = "mclass")),
+    // v7E-M
+    all(target_feature = "mclass", target_feature = "dsp"),
+    doc,
+))]
+mod simd32;
 
-#[cfg(any(target_arch = "aarch64", target_feature = "v7", doc))]
-mod neon;
-#[cfg(any(target_arch = "aarch64", target_feature = "v7", doc))]
-pub use self::neon::*;
+#[cfg(any(
+    // v7-A, v7-R
+    all(target_feature = "v6", not(target_feature = "mclass")),
+    // v7E-M
+    all(target_feature = "mclass", target_feature = "dsp"),
+    doc,
+))]
+pub use self::simd32::*;
 
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-mod crc;
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-pub use self::crc::*;
+#[cfg(any(target_feature = "v7", doc))]
+mod v7;
+#[cfg(any(target_feature = "v7", doc))]
+pub use self::v7::*;
 
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-mod crypto;
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-pub use self::crypto::*;
+mod ex;
+pub use self::ex::*;
 
-pub use crate::core_arch::acle::*;
+pub use crate::core_arch::arm_shared::*;
 
 #[cfg(test)]
 use stdarch_test::assert_instr;
 
+#[cfg(any(target_feature = "v7", doc))]
+pub(crate) mod neon;
+#[cfg(any(target_feature = "v7", doc))]
+pub use neon::*;
+
 /// Generates the trap instruction `UDF`
 #[cfg(target_arch = "arm")]
 #[cfg_attr(test, assert_instr(udf))]
@@ -47,6 +88,26 @@ pub unsafe fn udf() -> ! {
     crate::intrinsics::abort()
 }
 
-#[cfg(test)]
-#[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
-pub(crate) mod test_support;
+/// Generates a DBG instruction.
+///
+/// This provides a hint to debugging and related systems. The argument must be
+/// a constant integer from 0 to 15 inclusive. See implementation documentation
+/// for the effect (if any) of this instruction and the meaning of the
+/// argument. This is available only when compliling for AArch32.
+// Section 10.1 of ACLE says that the supported arches are: 7, 7-M
+// "The DBG hint instruction is added in ARMv7. It is UNDEFINED in the ARMv6 base architecture, and
+// executes as a NOP instruction in ARMv6K and ARMv6T2." - ARM Architecture Reference Manual ARMv7-A
+// and ARMv7-R edition (ARM DDI 0406C.c) sections D12.4.1 "ARM instruction set support" and D12.4.2
+// "Thumb instruction set support"
+#[cfg(any(target_feature = "v7", doc))]
+#[inline(always)]
+#[rustc_legacy_const_generics(0)]
+pub unsafe fn __dbg<const IMM4: i32>() {
+    static_assert_imm4!(IMM4);
+    dbg(IMM4);
+}
+
+extern "C" {
+    #[link_name = "llvm.arm.dbg"]
+    fn dbg(_: i32);
+}