Update safety text for per-peripheral steal()

Author: adamgreig

src/generate/peripheral.rs

@@ -96,7 +96,15 @@ pub fn render(p_original: &Peripheral, index: &Index, config: &Config) -> Result
                         ///
                         ///# Safety
                         ///
-                        ///Make sure that [`Peripherals::steal`] is already called
+                        /// Ensure that the new instance of the peripheral cannot be used in a way
+                        /// that may race with any existing instances, for example by only
+                        /// accessing read-only or write-only registers, or by consuming the
+                        /// original peripheral and using critical sections to coordinate
+                        /// access between multiple new instances.
+                        ///
+                        /// Additionally, other software such as HALs may rely on only one
+                        /// peripheral instance existing to ensure memory safety; ensure
+                        /// no stolen instances are passed to such software.
                         pub unsafe fn steal() -> Self {
                             Self { _marker: PhantomData }
                         }
@@ -161,10 +169,18 @@ pub fn render(p_original: &Peripheral, index: &Index, config: &Config) -> Result
                     }
 
                     ///Steal an instance of this peripheral
-                        ///
-                        ///# Safety
-                        ///
-                        ///Make sure that [`Peripherals::steal`] is already called
+                    ///
+                    ///# Safety
+                    ///
+                    /// Ensure that the new instance of the peripheral cannot be used in a way
+                    /// that may race with any existing instances, for example by only
+                    /// accessing read-only or write-only registers, or by consuming the
+                    /// original peripheral and using critical sections to coordinate
+                    /// access between multiple new instances.
+                    ///
+                    /// Additionally, other software such as HALs may rely on only one
+                    /// peripheral instance existing to ensure memory safety; ensure
+                    /// no stolen instances are passed to such software.
                     pub unsafe fn steal() -> Self {
                         Self { _marker: PhantomData }
                     }

src/lib.rs

@@ -186,9 +186,9 @@
 //! use the implementation provided by the target crate like `cortex-m`, `riscv` and `*-hal` crates.
 //! See more details in the [`critical-section`](https://crates.io/crates/critical-section) crate documentation.
 //!
-//! The singleton property can be *unsafely* bypassed using the `ptr` static method which is
-//! available on all the peripheral types. This method is useful for implementing safe higher
-//! level abstractions.
+//! The singleton property can be *unsafely* bypassed using the `ptr` or `steal` static methods
+//! which are available on all the peripheral types. This method is useful for implementing safe
+//! higher level abstractions.
 //!
 //! ```ignore
 //! struct PA0 { _0: () }