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]: http://www.intel.de/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
19extern "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.
31pub const _XBEGIN_STARTED: u32 = !0;
32
33/// Transaction explicitly aborted with xabort. The parameter passed to xabort is available with
34/// `_xabort_code(status)`.
35#[allow(clippy::identity_op)]
36pub const _XABORT_EXPLICIT: u32 = 1 << 0;
37
38/// Transaction retry is possible.
39pub const _XABORT_RETRY: u32 = 1 << 1;
40
41/// Transaction abort due to a memory conflict with another thread.
42pub const _XABORT_CONFLICT: u32 = 1 << 2;
43
44/// Transaction abort due to the transaction using too much memory.
45pub const _XABORT_CAPACITY: u32 = 1 << 3;
46
47/// Transaction abort due to a debug trap.
48pub const _XABORT_DEBUG: u32 = 1 << 4;
49
50/// Transaction abort in a inner nested transaction.
51pub const _XABORT_NESTED: u32 = 1 << 5;
52
53/// Specifies the start of a restricted transactional memory (RTM) code region and returns a value
54/// indicating status.
55///
56/// [Intel's documentation](https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-xbegin).
57#[inline]
58#[target_feature(enable = "rtm")]
59#[cfg_attr(test, assert_instr(xbegin))]
60pub unsafe fn _xbegin() -> u32 {
61 x86_xbegin() as _
62}
63
64/// Specifies the end of a restricted transactional memory (RTM) code region.
65///
66/// [Intel's documentation](https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-xend).
67#[inline]
68#[target_feature(enable = "rtm")]
69#[cfg_attr(test, assert_instr(xend))]
70pub unsafe fn _xend() {
71 x86_xend()
72}
73
74/// Forces a restricted transactional memory (RTM) region to abort.
75///
76/// [Intel's documentation](https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-xabort).
77#[inline]
78#[target_feature(enable = "rtm")]
79#[cfg_attr(test, assert_instr(xabort, IMM8 = 0x0))]
80#[rustc_legacy_const_generics(0)]
81pub unsafe fn _xabort<const IMM8: u32>() {
82 static_assert_uimm_bits!(IMM8, 8);
83 x86_xabort(IMM8 as i8)
84}
85
86/// Queries whether the processor is executing in a transactional region identified by restricted
87/// transactional memory (RTM) or hardware lock elision (HLE).
88///
89/// [Intel's documentation](https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-xtest).
90#[inline]
91#[target_feature(enable = "rtm")]
92#[cfg_attr(test, assert_instr(xtest))]
93pub unsafe fn _xtest() -> u8 {
94 x86_xtest() as _
95}
96
97/// Retrieves the parameter passed to [`_xabort`] when [`_xbegin`]'s status has the
98/// `_XABORT_EXPLICIT` flag set.
99#[inline]
100pub const fn _xabort_code(status: u32) -> u32 {
101 (status >> 24) & 0xFF
102}
103
104#[cfg(test)]
105mod tests {
106 use stdarch_test::simd_test;
107
108 use crate::core_arch::x86::*;
109
110 #[simd_test(enable = "rtm")]
111 unsafe fn test_xbegin_xend() {
112 let mut x = 0;
113 for _ in 0..10 {
114 let code = rtm::_xbegin();
115 if code == _XBEGIN_STARTED {
116 x += 1;
117 rtm::_xend();
118 assert_eq!(x, 1);
119 break;
120 }
121 assert_eq!(x, 0);
122 }
123 }
124
125 #[simd_test(enable = "rtm")]
126 unsafe fn test_xabort() {
127 const ABORT_CODE: u32 = 42;
128 // aborting outside a transactional region does nothing
129 _xabort::<ABORT_CODE>();
130
131 for _ in 0..10 {
132 let mut x = 0;
133 let code = rtm::_xbegin();
134 if code == _XBEGIN_STARTED {
135 x += 1;
136 rtm::_xabort::<ABORT_CODE>();
137 } else if code & _XABORT_EXPLICIT != 0 {
138 let test_abort_code = rtm::_xabort_code(code);
139 assert_eq!(test_abort_code, ABORT_CODE);
140 }
141 assert_eq!(x, 0);
142 }
143 }
144
145 #[simd_test(enable = "rtm")]
146 unsafe fn test_xtest() {
147 assert_eq!(_xtest(), 0);
148
149 for _ in 0..10 {
150 let code = rtm::_xbegin();
151 if code == _XBEGIN_STARTED {
152 let in_tx = _xtest();
153 rtm::_xend();
154
155 // putting the assert inside the transaction would abort the transaction on fail
156 // without any output/panic/etc
157 assert_eq!(in_tx, 1);
158 break;
159 }
160 }
161 }
162}
163