Add docs for embassy-rp::pio::get_x assumption about autopush.

2 files changed, 18 insertions, 0 deletions

diff --git a/embassy-rp/CHANGELOG.md b/embassy-rp/CHANGELOG.md
index 3b3cb5351..4b0d738a7 100644
--- a/embassy-rp/CHANGELOG.md
+++ b/embassy-rp/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- next-header -->
 ## Unreleased - ReleaseDate
 
+- Add documentation for pio `get_x` about autopush.
 - Fix several minor typos in documentation
 - Add PIO SPI
 - Add PIO I2S input
@@ -114,3 +115,4 @@ Small release fixing a few gnarly bugs, upgrading is strongly recommended.
 - rename the Channel trait to Slice and the PwmPin to PwmChannel
 - i2c: Fix race condition that appears on fast repeated transfers.
 - Add a basic "read to break" function
+
diff --git a/embassy-rp/src/pio/instr.rs b/embassy-rp/src/pio/instr.rs
index b15d507de..304ddb20a 100644
--- a/embassy-rp/src/pio/instr.rs
+++ b/embassy-rp/src/pio/instr.rs
@@ -5,6 +5,10 @@ use crate::pio::{Instance, StateMachine};
 
 impl<'d, PIO: Instance, const SM: usize> StateMachine<'d, PIO, SM> {
     /// Set value of scratch register X.
+    ///
+    /// SAFETY: autopull enabled else it will write undefined data.
+    /// Make sure to have setup the according configuration see
+    /// [shift_out](crate::pio::Config::shift_out) and [auto_fill](crate::pio::ShiftConfig::auto_fill).
     pub unsafe fn set_x(&mut self, value: u32) {
         const OUT: u16 = InstructionOperands::OUT {
             destination: OutDestination::X,
@@ -16,6 +20,10 @@ impl<'d, PIO: Instance, const SM: usize> StateMachine<'d, PIO, SM> {
     }
 
     /// Get value of scratch register X.
+    ///
+    /// SAFETY: autopush enabled else it will read undefined data.
+    /// Make sure to have setup the according configurations see
+    /// [shift_in](crate::pio::Config::shift_in) and [auto_fill](crate::pio::ShiftConfig::auto_fill).
     pub unsafe fn get_x(&mut self) -> u32 {
         const IN: u16 = InstructionOperands::IN {
             source: InSource::X,
@@ -27,6 +35,10 @@ impl<'d, PIO: Instance, const SM: usize> StateMachine<'d, PIO, SM> {
     }
 
     /// Set value of scratch register Y.
+    ///
+    /// SAFETY: autopull enabled else it will write undefined data.
+    /// Make sure to have setup the according configuration see
+    /// [shift_out](crate::pio::Config::shift_out) and [auto_fill](crate::pio::ShiftConfig::auto_fill).
     pub unsafe fn set_y(&mut self, value: u32) {
         const OUT: u16 = InstructionOperands::OUT {
             destination: OutDestination::Y,
@@ -38,6 +50,10 @@ impl<'d, PIO: Instance, const SM: usize> StateMachine<'d, PIO, SM> {
     }
 
     /// Get value of scratch register Y.
+    ///
+    /// SAFETY: autopush enabled else it will read undefined data.
+    /// Make sure to have setup the according configurations see
+    /// [shift_in](crate::pio::Config::shift_in) and [auto_fill](crate::pio::ShiftConfig::auto_fill).
     pub unsafe fn get_y(&mut self) -> u32 {
         const IN: u16 = InstructionOperands::IN {
             source: InSource::Y,