riscv: deprecate intrinsics that cannot be used from Rust

Author: RalfJung

crates/core_arch/src/riscv_shared/mod.rs

@@ -531,6 +531,15 @@ pub unsafe fn hinval_gvma_all() {
 
 /// Reads the floating-point control and status register `fcsr`
 ///
+/// Note that Rust makes no guarantees whatsoever about the contents of this register: Rust
+/// floating-point operations may or may not result in this register getting updated with exception
+/// state, and the register can change between two invocations of this function even when no
+/// floating-point operations appear in the source code (since floating-point operations appearing
+/// earlier or later can be reordered).
+///
+/// If you need to perform some floating-point operations and check whether they raised an
+/// exception, use an inline assembly block for the entire sequence of operations.
+///
 /// Register `fcsr` is a 32-bit read/write register that selects the dynamic rounding mode
 /// for floating-point arithmetic operations and holds the accrued exception flag.
 ///
@@ -549,6 +558,10 @@ pub unsafe fn hinval_gvma_all() {
 /// [`frflags`]: fn.frflags.html
 #[inline]
 #[unstable(feature = "stdsimd", issue = "27731")]
+#[deprecated(
+    since = "1.75.0",
+    note = "see `frcsr` documentation - use inline assembly instead"
+)]
 pub fn frcsr() -> u32 {
     let value: u32;
     unsafe { asm!("frcsr {}", out(reg) value, options(nomem, nostack)) };
@@ -557,10 +570,24 @@ pub fn frcsr() -> u32 {
 
 /// Swaps the floating-point control and status register `fcsr`
 ///
+/// Note that modifying the masking flags, rounding mode, or denormals-are-zero mode flags leads to
+/// **immediate Undefined Behavior**: Rust assumes that these are always in their default state and
+/// will optimize accordingly. This even applies when the register is altered and later reset to its
+/// original value without any floating-point operations appearing in the source code between those
+/// operations (since floating-point operations appearing earlier or later can be reordered).
+///
+/// If you need to perform some floating-point operations under a different masking flags, rounding
+/// mode, or denormals-are-zero mode, use an inline assembly block and make sure to restore the
+/// original `fcsr` register state before the end of the block.
+///
 /// This function swaps the value in `fcsr` by copying the original value to be returned,
 /// and then writing a new value obtained from input variable `value` into `fcsr`.
 #[inline]
 #[unstable(feature = "stdsimd", issue = "27731")]
+#[deprecated(
+    since = "1.75.0",
+    note = "see `fscsr` documentation - use inline assembly instead"
+)]
 pub fn fscsr(value: u32) -> u32 {
     let original: u32;
     unsafe { asm!("fscsr {}, {}", out(reg) original, in(reg) value, options(nomem, nostack)) }
@@ -597,6 +624,10 @@ pub fn frrm() -> u32 {
 /// input variable `value` into `frm`.
 #[inline]
 #[unstable(feature = "stdsimd", issue = "27731")]
+#[deprecated(
+    since = "1.75.0",
+    note = "see `fscsr` documentation - use inline assembly instead"
+)]
 pub fn fsrm(value: u32) -> u32 {
     let original: u32;
     unsafe { asm!("fsrm {}, {}", out(reg) original, in(reg) value, options(nomem, nostack)) }
@@ -621,6 +652,10 @@ pub fn fsrm(value: u32) -> u32 {
 /// | 0 | NX | Inexact |
 #[inline]
 #[unstable(feature = "stdsimd", issue = "27731")]
+#[deprecated(
+    since = "1.75.0",
+    note = "see `frcsr` documentation - use inline assembly instead"
+)]
 pub fn frflags() -> u32 {
     let value: u32;
     unsafe { asm!("frflags {}", out(reg) value, options(nomem, nostack)) };
@@ -634,6 +669,10 @@ pub fn frflags() -> u32 {
 /// input variable `value` into `fflags`.
 #[inline]
 #[unstable(feature = "stdsimd", issue = "27731")]
+#[deprecated(
+    since = "1.75.0",
+    note = "see `frcsr` documentation - use inline assembly instead"
+)]
 pub fn fsflags(value: u32) -> u32 {
     let original: u32;
     unsafe { asm!("fsflags {}, {}", out(reg) original, in(reg) value, options(nomem, nostack)) }