core/stdarch/crates/core_arch/src/x86/
rtm.rs

1//! Intel's Restricted Transactional Memory (RTM).
2//!
3//! This CPU feature is available on Intel Broadwell or later CPUs (and some Haswell).
4//!
5//! The reference is [Intel 64 and IA-32 Architectures Software Developer's
6//! Manual Volume 2: Instruction Set Reference, A-Z][intel64_ref].
7//!
8//! [Wikipedia][wikipedia_rtm] provides a quick overview of the assembly instructions, and
9//! Intel's [programming considerations][intel_consid] details what sorts of instructions within a
10//! transaction are likely to cause an abort.
11//!
12//! [intel64_ref]: https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf
13//! [wikipedia_rtm]: https://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions#Restricted_Transactional_Memory
14//! [intel_consid]: https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-intel-transactional-synchronization-extensions-intel-tsx-programming-considerations
15
16#[cfg(test)]
17use stdarch_test::assert_instr;
18
19unsafe extern "C" {
20    #[link_name = "llvm.x86.xbegin"]
21    fn x86_xbegin() -> i32;
22    #[link_name = "llvm.x86.xend"]
23    fn x86_xend();
24    #[link_name = "llvm.x86.xabort"]
25    fn x86_xabort(imm8: i8);
26    #[link_name = "llvm.x86.xtest"]
27    fn x86_xtest() -> i32;
28}
29
30/// Transaction successfully started.
31#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
32pub const _XBEGIN_STARTED: u32 = !0;
33
34/// Transaction explicitly aborted with xabort. The parameter passed to xabort is available with
35/// `_xabort_code(status)`.
36#[allow(clippy::identity_op)]
37#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
38pub const _XABORT_EXPLICIT: u32 = 1 << 0;
39
40/// Transaction retry is possible.
41#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
42pub const _XABORT_RETRY: u32 = 1 << 1;
43
44/// Transaction abort due to a memory conflict with another thread.
45#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
46pub const _XABORT_CONFLICT: u32 = 1 << 2;
47
48/// Transaction abort due to the transaction using too much memory.
49#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
50pub const _XABORT_CAPACITY: u32 = 1 << 3;
51
52/// Transaction abort due to a debug trap.
53#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
54pub const _XABORT_DEBUG: u32 = 1 << 4;
55
56/// Transaction abort in a inner nested transaction.
57#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
58pub const _XABORT_NESTED: u32 = 1 << 5;
59
60/// Specifies the start of a restricted transactional memory (RTM) code region and returns a value
61/// indicating status.
62///
63/// [Intel's documentation](https://software.intel.com/sites/landingpage/IntrinsicsGuide/#text=_xbegin)
64#[inline]
65#[target_feature(enable = "rtm")]
66#[cfg_attr(test, assert_instr(xbegin))]
67#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
68pub unsafe fn _xbegin() -> u32 {
69    x86_xbegin() as _
70}
71
72/// Specifies the end of a restricted transactional memory (RTM) code region.
73///
74/// [Intel's documentation](https://software.intel.com/sites/landingpage/IntrinsicsGuide/#text=_xend)
75#[inline]
76#[target_feature(enable = "rtm")]
77#[cfg_attr(test, assert_instr(xend))]
78#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
79pub unsafe fn _xend() {
80    x86_xend()
81}
82
83/// Forces a restricted transactional memory (RTM) region to abort.
84///
85/// [Intel's documentation](https://software.intel.com/sites/landingpage/IntrinsicsGuide/#text=_xabort)
86#[inline]
87#[target_feature(enable = "rtm")]
88#[cfg_attr(test, assert_instr(xabort, IMM8 = 0x0))]
89#[rustc_legacy_const_generics(0)]
90#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
91pub unsafe fn _xabort<const IMM8: u32>() {
92    static_assert_uimm_bits!(IMM8, 8);
93    x86_xabort(IMM8 as i8)
94}
95
96/// Queries whether the processor is executing in a transactional region identified by restricted
97/// transactional memory (RTM) or hardware lock elision (HLE).
98///
99/// [Intel's documentation](https://software.intel.com/sites/landingpage/IntrinsicsGuide/#text=_xtest)
100#[inline]
101#[target_feature(enable = "rtm")]
102#[cfg_attr(test, assert_instr(xtest))]
103#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
104pub unsafe fn _xtest() -> u8 {
105    x86_xtest() as _
106}
107
108/// Retrieves the parameter passed to [`_xabort`] when [`_xbegin`]'s status has the
109/// `_XABORT_EXPLICIT` flag set.
110#[inline]
111#[unstable(feature = "stdarch_x86_rtm", issue = "111138")]
112pub const fn _xabort_code(status: u32) -> u32 {
113    (status >> 24) & 0xFF
114}
115
116#[cfg(test)]
117mod tests {
118    use stdarch_test::simd_test;
119
120    use crate::core_arch::x86::*;
121
122    #[simd_test(enable = "rtm")]
123    fn test_xbegin() {
124        let mut x = 0;
125        for _ in 0..10 {
126            let code = unsafe { _xbegin() };
127            if code == _XBEGIN_STARTED {
128                x += 1;
129                unsafe {
130                    _xend();
131                }
132                assert_eq!(x, 1);
133                break;
134            }
135            assert_eq!(x, 0);
136        }
137    }
138
139    #[simd_test(enable = "rtm")]
140    fn test_xabort() {
141        const ABORT_CODE: u32 = 42;
142        // aborting outside a transactional region does nothing
143        unsafe {
144            _xabort::<ABORT_CODE>();
145        }
146
147        for _ in 0..10 {
148            let mut x = 0;
149            let code = unsafe { _xbegin() };
150            if code == _XBEGIN_STARTED {
151                x += 1;
152                unsafe {
153                    _xabort::<ABORT_CODE>();
154                }
155            } else if code & _XABORT_EXPLICIT != 0 {
156                let test_abort_code = _xabort_code(code);
157                assert_eq!(test_abort_code, ABORT_CODE);
158            }
159            assert_eq!(x, 0);
160        }
161    }
162
163    #[simd_test(enable = "rtm")]
164    fn test_xtest() {
165        assert_eq!(unsafe { _xtest() }, 0);
166
167        for _ in 0..10 {
168            let code = unsafe { _xbegin() };
169            if code == _XBEGIN_STARTED {
170                let in_tx = unsafe { _xtest() };
171                unsafe {
172                    _xend();
173                }
174
175                // putting the assert inside the transaction would abort the transaction on fail
176                // without any output/panic/etc
177                assert_eq!(in_tx, 1);
178                break;
179            }
180        }
181    }
182}
core/stdarch/crates/core_arch/src/x86/rtm.rs

core/stdarch/crates/core_arch/src/x86/
rtm.rs
