The Led and Delay abstractions

Now, I’m going to introduce two high level abstractions that we’ll use to implement the LED rouletteapplication.

The auxiliary crate, aux5, exposes an initialization function called init. When called thisfunction returns two values packed in a tuple: a Delay value and a Leds value.

Delay can be used to block your program for a specified amount of milliseconds.

Leds is actually an array of eight Leds. Each Led represents one of the LEDs on the F3 board,and exposes two methods: on and off which can be used to turn the LED on or off, respectively.

Let’s try out these two abstractions by modifying the starter code to look like this:

  1. #![deny(unsafe_code)]
  2. #![no_main]
  3. #![no_std]
  5. use aux5::{entry, prelude::*, Delay, Leds};
  7. #[entry]
  8. fn main() -> ! {
  9.     let (mut delay, mut leds): (Delay, Leds) = aux5::init();
  11.     let half_period = 500_u16;
  13.     loop {
  14.         leds[0].on();
  15.         delay.delay_ms(half_period);
  17.         leds[0].off();
  18.         delay.delay_ms(half_period);
  19.     }
  20. }

Now build it:

  1. $ cargo build --target thumbv7em-none-eabihf

NOTE It’s possible to forget to rebuild the program before starting a GDB session; thisomission can lead to very confusing debug sessions. To avoid this problem you can call cargo runinstead of cargo build; cargo run will build and start a debug session ensuring you neverforget to recompile your program.

Now, we’ll repeat the flashing procedure that we did in the previous section:

  1. $ # this starts a GDB session of the program; no need to specify the path to the binary
  2. $ arm-none-eabi-gdb -q target/thumbv7em-none-eabihf/debug/led-roulette
  3. Reading symbols from target/thumbv7em-none-eabihf/debug/led-roulette...done.
  4. (gdb) target remote :3333
  5. Remote debugging using :3333
  6. (..)
  8. (gdb) load
  9. Loading section .vector_table, size 0x188 lma 0x8000000
  10. Loading section .text, size 0x3fc6 lma 0x8000188
  11. Loading section .rodata, size 0xa0c lma 0x8004150
  12. Start address 0x8000188, load size 19290
  13. Transfer rate: 19 KB/sec, 4822 bytes/write.
  15. (gdb) break main
  16. Breakpoint 1 at 0x800018c: file src/05-led-roulette/src/main.rs, line 9.
  18. (gdb) continue
  19. Continuing.
  20. Note: automatically using hardware breakpoints for read-only addresses.
  22. Breakpoint 1, main () at src/05-led-roulette/src/main.rs:9
  23. 9           let (mut delay, mut leds): (Delay, Leds) = aux5::init();

OK. Let’s step through the code. This time, we’ll use the next command instead of step. Thedifference is that the next command will step over function calls instead of going inside them.

  1. (gdb) next
  2. 11          let half_period = 500_u16;
  4. (gdb) next
  5. 13          loop {
  7. (gdb) next
  8. 14              leds[0].on();
  10. (gdb) next
  11. 15              delay.delay_ms(half_period);

After executing the leds[0].on() statement, you should see a red LED, the one pointing North,turn on.

Let’s continue stepping over the program:

  1. (gdb) next
  2. 17              leds[0].off();
  4. (gdb) next
  5. 18              delay.delay_ms(half_period);

The delay_ms call will block the program for half a second but you may not notice because thenext command also takes some time to execute. However, after stepping over the leds[0].off()statement you should see the red LED turn off.

You can already guess what this program does. Let it run uninterrupted using the continue command.

  1. (gdb) continue
  2. Continuing.

Now, let’s do something more interesting. We are going to modify the behavior of our program usingGDB.

First, let’s stop the infinite loop by hitting Ctrl+C. You’ll probably end up somewhere insideLed::on, Led::off or delay_ms:

  1. Program received signal SIGINT, Interrupt.
  2. 0x080033f6 in core::ptr::read_volatile (src=0xe000e010) at /checkout/src/libcore/ptr.rs:472
  3. 472     /checkout/src/libcore/ptr.rs: No such file or directory.

In my case, the program stopped its execution inside a read_volatile function. GDB output showssome interesting information about that: core::ptr::read_volatile (src=0xe000e010). This meansthat the function comes from the core crate and that it was called with argument src = 0xe000e010.

Just so you know, a more explicit way to show the arguments of a function is to use the info argscommand:

  1. (gdb) info args
  2. src = 0xe000e010

Regardless of where your program may have stopped you can always look at the output of thebacktrace command (bt for short) to learn how it got there:

  1. (gdb) backtrace
  2. #0  0x080033f6 in core::ptr::read_volatile (src=0xe000e010)
  3.     at /checkout/src/libcore/ptr.rs:472
  4. #1  0x08003248 in <vcell::VolatileCell<T>>::get (self=0xe000e010)
  5.     at $REGISTRY/vcell-0.1.0/src/lib.rs:43
  6. #2  <volatile_register::RW<T>>::read (self=0xe000e010)
  7.     at $REGISTRY/volatile-register-0.2.0/src/lib.rs:75
  8. #3  cortex_m::peripheral::syst::<impl cortex_m::peripheral::SYST>::has_wrapped (self=0x10001fbc)
  9.     at $REGISTRY/cortex-m-0.5.7/src/peripheral/syst.rs:124
  10. #4  0x08002d9c in <stm32f30x_hal::delay::Delay as embedded_hal::blocking::delay::DelayUs<u32>>::delay_us (self=0x10001fbc, us=500000)
  11.     at $REGISTRY/stm32f30x-hal-0.2.0/src/delay.rs:58
  12. #5  0x08002cce in <stm32f30x_hal::delay::Delay as embedded_hal::blocking::delay::DelayMs<u32>>::delay_ms (self=0x10001fbc, ms=500)
  13.     at $REGISTRY/stm32f30x-hal-0.2.0/src/delay.rs:32
  14. #6  0x08002d0e in <stm32f30x_hal::delay::Delay as embedded_hal::blocking::delay::DelayMs<u16>>::delay_ms (self=0x10001fbc, ms=500)
  15.     at $REGISTRY/stm32f30x-hal-0.2.0/src/delay.rs:38
  16. #7  0x080001ee in main () at src/05-led-roulette/src/main.rs:18

backtrace will print a trace of function calls from the current function down to main.

Back to our topic. To do what we are after, first, we have to return to the main function. We cando that using the finish command. This command resumes the program execution and stops it againright after the program returns from the current function. We’ll have to call it several times.

  1. (gdb) finish
  2. cortex_m::peripheral::syst::<impl cortex_m::peripheral::SYST>::has_wrapped (self=0x10001fbc)
  3.     at $REGISTRY/cortex-m-0.5.7/src/peripheral/syst.rs:124
  4. 124             self.csr.read() & SYST_CSR_COUNTFLAG != 0
  5. Value returned is $1 = 5
  7. (gdb) finish
  8. Run till exit from #0  cortex_m::peripheral::syst::<impl cortex_m::peripheral::SYST>::has_wrapped (
  9.     self=0x10001fbc)
  10.     at $REGISTRY/cortex-m-0.5.7/src/peripheral/syst.rs:124
  11. 0x08002d9c in <stm32f30x_hal::delay::Delay as embedded_hal::blocking::delay::DelayUs<u32>>::delay_us (
  12.     self=0x10001fbc, us=500000)
  13.     at $REGISTRY/stm32f30x-hal-0.2.0/src/delay.rs:58
  14. 58              while !self.syst.has_wrapped() {}
  15. Value returned is $2 = false
  17. (..)
  19. (gdb) finish
  20. Run till exit from #0  0x08002d0e in <stm32f30x_hal::delay::Delay as embedded_hal::blocking::delay::DelayMs<u16>>::delay_ms (self=0x10001fbc, ms=500)
  21.     at $REGISTRY/stm32f30x-hal-0.2.0/src/delay.rs:38
  22. 0x080001ee in main () at src/05-led-roulette/src/main.rs:18
  23. 18              delay.delay_ms(half_period);

We are back in main. We have a local variable in here: half_period

  1. (gdb) info locals
  2. half_period = 500
  3. delay = (..)
  4. leds = (..)

Now, we are going to modify this variable using the set command:

  1. (gdb) set half_period = 100
  3. (gdb) print half_period
  4. $1 = 100

If you let program run free again using the continue command, you should see that the LED willblink at a much faster rate now!

Question! What happens if you keep lowering the value of half_period? At what value ofhalf_period you can no longer see the LED blink?

Now, it’s your turn to write a program.