From 3756cd2fb5165eeb078063e0b8ec6aaca87a7b28 Mon Sep 17 00:00:00 2001 From: Jan Niehusmann Date: Mon, 1 Nov 2021 20:01:20 +0000 Subject: [PATCH 1/4] Rename set_instruction to exec_instruction --- rp2040-hal/src/pio.rs | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/rp2040-hal/src/pio.rs b/rp2040-hal/src/pio.rs index 3326400..a9b4f8d 100644 --- a/rp2040-hal/src/pio.rs +++ b/rp2040-hal/src/pio.rs @@ -473,11 +473,11 @@ impl UninitStateMachine { }); } - /// Set the current instruction. + /// Execute the instruction immediately. // Safety: The Send trait assumes this is the only write to sm_instr while uninitialized. The // initialized `StateMachine` may also use this register. The `UnintStateMachine` is consumed // by `PIOBuilder.build` to create `StateMachine` - fn set_instruction(&mut self, instruction: u16) { + fn exec_instruction(&mut self, instruction: u16) { self.sm() .sm_instr .write(|w| unsafe { w.sm0_instr().bits(instruction) }) @@ -519,10 +519,14 @@ impl StateMachine { self.sm.sm().sm_addr.read().bits() } - /// Set the current instruction. - pub fn set_instruction(&mut self, instruction: u16) { - // TODO: Check if this function is safe to call while the state machine is running. - self.sm.set_instruction(instruction); + ///Execute the instruction immediately. + pub fn exec_instruction(&mut self, instruction: u16) { + // This is allowed even if the state machine is running. + // + // However, the datasheet says: + // "If EXEC instructions are used, instructions written to INSTR must not stall" + // It's unclear what happens if this is violated. + self.sm.exec_instruction(instruction); } /// Check if the current instruction is stalled. @@ -564,7 +568,7 @@ impl StateMachine { .sm() .sm_pinctrl .write(|w| unsafe { w.set_base().bits(pin_num).set_count().bits(1) }); - self.set_instruction( + self.exec_instruction( pio::InstructionOperands::SET { destination: pio::SetDestination::PINS, data: if PinState::High == pin_state { 1 } else { 0 }, @@ -593,7 +597,7 @@ impl StateMachine { .sm() .sm_pinctrl .write(|w| unsafe { w.set_base().bits(pinnum).set_count().bits(1) }); - self.set_instruction( + self.exec_instruction( pio::InstructionOperands::SET { destination: pio::SetDestination::PINDIRS, data: if PinDir::Output == pin_dir { 1 } else { 0 }, @@ -680,7 +684,7 @@ impl StateMachine { // pause the state machine self.sm.set_enabled(false); // revert it to its wrap target - self.sm.set_instruction( + self.sm.exec_instruction( pio::InstructionOperands::JMP { condition: pio::JmpCondition::Always, address: self.program.wrap_target(), @@ -829,7 +833,7 @@ impl Tx { } .encode(); // Safety: The only other place this register is written is - // `UninitStatemachine.set_instruction`, `Tx` is only created after init. + // `UninitStatemachine.exec_instruction`, `Tx` is only created after init. let mask = 1 << SM::id(); while self.register_block().fstat.read().txempty().bits() & mask != mask { self.register_block().sm[SM::id()] @@ -1429,9 +1433,9 @@ impl PIOBuilder

{ sm.restart(); sm.reset_clock(); - // Set starting location by setting the state machine to execute a jmp + // Set starting location by forcing the state machine to execute a jmp // to the beginning of the program we loaded in. - sm.set_instruction( + sm.exec_instruction( pio::InstructionOperands::JMP { condition: pio::JmpCondition::Always, address: offset as u8, From aafa3dd587611af8bc6651147cb18f4c0b016bc1 Mon Sep 17 00:00:00 2001 From: Jan Niehusmann Date: Mon, 1 Nov 2021 21:03:47 +0000 Subject: [PATCH 2/4] Keep old function as a deprecated alternative, for now Mainly so i2c-pio-rs doesn't fail, as it is used by examples. Should be removed once i2c-pio-rs is updated. --- rp2040-hal/src/pio.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rp2040-hal/src/pio.rs b/rp2040-hal/src/pio.rs index a9b4f8d..faf16b1 100644 --- a/rp2040-hal/src/pio.rs +++ b/rp2040-hal/src/pio.rs @@ -519,6 +519,12 @@ impl StateMachine { self.sm.sm().sm_addr.read().bits() } + #[deprecated(note = "Renamed to exec_instruction")] + ///Execute the instruction immediately. + pub fn set_instruction(&mut self, instruction: u16) { + self.exec_instruction(instruction); + } + ///Execute the instruction immediately. pub fn exec_instruction(&mut self, instruction: u16) { // This is allowed even if the state machine is running. From 15c162757f23ce0f0e91bc2b3fd790a07dc7cc4d Mon Sep 17 00:00:00 2001 From: Jan Niehusmann Date: Thu, 25 Nov 2021 17:38:18 +0100 Subject: [PATCH 3/4] Update docs in rp2040-hal/src/pio.rs Co-authored-by: Wilfried Chauveau --- rp2040-hal/src/pio.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rp2040-hal/src/pio.rs b/rp2040-hal/src/pio.rs index faf16b1..bc52b79 100644 --- a/rp2040-hal/src/pio.rs +++ b/rp2040-hal/src/pio.rs @@ -525,13 +525,13 @@ impl StateMachine { self.exec_instruction(instruction); } - ///Execute the instruction immediately. + /// Execute the instruction immediately. + /// + /// While this is allowed even when the state machine is running, the datasheet says: + /// > If EXEC instructions are used, instructions written to INSTR must not stall. + /// It's unclear what happens if this is violated. pub fn exec_instruction(&mut self, instruction: u16) { - // This is allowed even if the state machine is running. - // - // However, the datasheet says: - // "If EXEC instructions are used, instructions written to INSTR must not stall" - // It's unclear what happens if this is violated. + // TODO: clarify what happens if the instruction stalls. self.sm.exec_instruction(instruction); } From bb8531445ea0eed74cc77b9bd37c877207279514 Mon Sep 17 00:00:00 2001 From: Jan Niehusmann Date: Thu, 25 Nov 2021 16:44:57 +0000 Subject: [PATCH 4/4] Fix fmt Thats what happens when editing files directly on github... --- rp2040-hal/src/pio.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rp2040-hal/src/pio.rs b/rp2040-hal/src/pio.rs index bc52b79..839a411 100644 --- a/rp2040-hal/src/pio.rs +++ b/rp2040-hal/src/pio.rs @@ -526,7 +526,7 @@ impl StateMachine { } /// Execute the instruction immediately. - /// + /// /// While this is allowed even when the state machine is running, the datasheet says: /// > If EXEC instructions are used, instructions written to INSTR must not stall. /// It's unclear what happens if this is violated.