zephyr: clippy: Add Safety sections to documentation

As flagged by clippy, add `# Safety` sections to public documentation of
functions that are marked as `unsafe`.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/src/device/gpio.rs

@@ -24,8 +24,13 @@ pub struct GpioToken(());
 static GPIO_TOKEN: Unique = Unique::new();
 
 impl GpioToken {
-    /// Retrieves the gpio token.  This is unsafe because lots of code in zephyr operates on the
-    /// gpio drivers.
+    /// Retrieves the gpio token.
+    ///
+    /// # Safety
+    /// This is unsafe because lots of code in zephyr operates on the gpio drivers.  The user of the
+    /// gpio subsystem, in general should either coordinate all gpio access across the system (the
+    /// token coordinates this only within Rust code), or verify that the particular gpio driver and
+    /// methods are thread safe.
     pub unsafe fn get_instance() -> Option<GpioToken> {
         if !GPIO_TOKEN.once() {
             return None;
@@ -112,6 +117,12 @@ impl GpioPin {
     }
 
     /// Configure a single pin.
+    ///
+    /// # Safety
+    ///
+    /// The `_token` enforces single threaded use of gpios from Rust code.  However, many drivers
+    /// within Zephyr use GPIOs, and to use gpios safely, the caller must ensure that there is
+    /// either not simultaneous use, or the gpio driver in question is thread safe.
     pub unsafe fn configure(&mut self, _token: &mut GpioToken, extra_flags: raw::gpio_flags_t) {
         // TODO: Error?
         unsafe {
@@ -124,6 +135,12 @@ impl GpioPin {
     }
 
     /// Toggle pin level.
+    ///
+    /// # Safety
+    ///
+    /// The `_token` enforces single threaded use of gpios from Rust code.  However, many drivers
+    /// within Zephyr use GPIOs, and to use gpios safely, the caller must ensure that there is
+    /// either not simultaneous use, or the gpio driver in question is thread safe.
     pub unsafe fn toggle_pin(&mut self, _token: &mut GpioToken) {
         // TODO: Error?
         unsafe {

zephyr/src/logging/impl_printk.rs

@@ -35,8 +35,10 @@ static PRINTK_LOGGER: PrintkLogger = PrintkLogger;
 
 /// Set the log handler to log messages through printk in Zephyr.
 ///
+/// # Safety
+///
 /// This is unsafe due to racy issues in the log framework on targets that do not support atomic
-/// pointers.
+/// pointers.  As long as this is called ever by a single thread, it is safe to use.
 pub unsafe fn set_logger() -> Result<(), SetLoggerError> {
     super::set_logger_internal(&PRINTK_LOGGER)
 }

zephyr/src/object.rs

@@ -167,9 +167,13 @@ impl<T> StaticKernelObject<T>
 where
     StaticKernelObject<T>: Wrapped,
 {
-    /// Construct an empty of these objects, with the zephyr data zero-filled.  This is safe in the
-    /// sense that Zephyr we track the initialization, they start in the uninitialized state, and
-    /// the zero value of the initialize atomic indicates that it is uninitialized.
+    /// Construct an empty of these objects, with the zephyr data zero-filled.
+    ///
+    /// # Safety
+    ///
+    /// This is safe in the sense that Zephyr we track the initialization, they start in the
+    /// uninitialized state, and the zero value of the initialize atomic indicates that it is
+    /// uninitialized.
     pub const unsafe fn new() -> StaticKernelObject<T> {
         StaticKernelObject {
             value: unsafe { mem::zeroed() },

zephyr/src/sys/queue.rs

@@ -50,6 +50,16 @@ impl Queue {
     /// safely.
     ///
     /// [`Message`]: crate::sync::channel::Message
+    ///
+    /// # Safety
+    ///
+    /// Zephyr has specific requirements on the memory given in data, which can be summarized as:
+    /// - The memory must remain valid until after the data is returned, via recv.
+    /// - The first `usize` in the pointed data will be mutated by Zephyr to manage structures.
+    /// - This first field must not be modified by any code while the message is enqueued.
+    ///
+    /// These are easiest to satisfy by ensuring the message is Boxed, and owned by the queue
+    /// system.
     pub unsafe fn send(&self, data: *mut c_void) {
         k_queue_append(self.item.get(), data)
     }
@@ -64,6 +74,11 @@ impl Queue {
     /// [`Forever`]: crate::time::Forever
     /// [`NoWait`]: crate::time::NoWait
     /// [`Duration`]: crate::time::Duration
+    ///
+    /// # Safety
+    ///
+    /// Once an item is received from a queue, ownership is returned to the caller, and Zephyr no
+    /// longer depends on it not being freed, or the first `usize` field being for its use.
     pub unsafe fn recv<T>(&self, timeout: T) -> *mut c_void
     where
         T: Into<Timeout>,

zephyr/src/sys/thread.rs

@@ -227,6 +227,12 @@ impl Thread {
 
     /// Simple thread spawn.  This is unsafe because of the raw values being used.  This can be
     /// useful in systems without an allocator defined.
+    ///
+    /// # Safety
+    ///
+    /// Safe use follows similar requirements to using this safely from within C code.  Passing Rust
+    /// values through this interface is difficult to get right, and it is generally recommended to
+    /// use [`spawn`].
     pub unsafe fn simple_spawn(
         mut self,
         child: k_thread_entry_t,