Why is Pull request 267 necessary?

[wpd]

Working through the book (aside, I didn't have any difficulties obtaining an STM32F4 Discovery board), I too ran into the HardFault exception when running the code for chapter 11. This brings up 2 questions for me...

1. Why is the HardFault triggered? The exception address indicates that the pop instruction triggered the fault, or possibly the b.n instruction immediately prior to that (which was my experience when single stepping through the assembly code). The monkey in me is curious to learn why this exception was triggered...I have much more experience with Cortex-A processors than Cortex-M, but I can't see anything that would have caused the fault, and I'd love to learn from folks with experience in this area than I.
2. Why/How did the code change to cause this exception to occur? One of the things I really liked when I first looked at Rust (just a few weeks ago) was the Cargo.lock file. When I saw that, and saw that I could commit to my git repository the specific versions of the libraries (crates) on which my code depends, I grew very excited about Rust and my ability to presume stability from it. But this is now the second case where I have cloned somebody's repository and tried to run the code, only to learn that it doesn't run anymore. I just noticed now, that the discovery repo .gitignore's Cargo.lock, so now (at least) I have some better understanding of why my code crashes when it doesn't/didn't for the original author. I guess now I'm curious to learn why you chose to .gitignore Cargo.lock. Is that a common practice in the Rust community?
   I'm done asking my questions (for now). I'm looking forward to learning more from you as I continue this journey.

--wpd

[adamgreig]

I haven't looked in to 1 yet but am also interested to find out what's causing it exactly.

2 is sort of simpler. A new version of cortex-m was released (the 0.7 series) which normally wouldn't be used by this code, because it depends on 0.5, and Cargo treats that as "any 0.5.x". However, because it's not allowed to have multiple versions of cortex-m in your build tree at once (as it defines a singleton using a unique symbol name to provide once-only access to all the core peripherals), cortex-m 0.5.11 is a dummy crate that depends on, and mostly re-exports, cortex-m 0.6, which is a compatibility hack to allow people using dependencies that require 0.5 to start using 0.6 themselves, since only the 0.6 crate will really exist. That was seemingly fine too, but cortex-m 0.6.7 does the same trick to depend on 0.7, which means the 0.5 dependency for the old f3 crate involved here really brings in 0.7.2. For some yet-to-be-determined reason, using the new cortex-m version is apparently causing this HardFault.

You're completely right about Cargo.lock - with it committed, Cargo would have kept using the exact old versions of the dependencies, and consequently no breakage would have occurred. It's common to not commit the lock file for libraries (because it wouldn't get used when you depend on a library, only for running its own tests etc), and generally recommended that you do for binaries/applications. I don't know if it was a deliberate choice to not include it in this book, but it probably would have been a good idea (at least in retrospect!).

The best fix for chapter 11 is going to be swapping it to use the newer and maintained stm32f3-discovery board support crate (BSC) and its dependencies stm32f3xx-hal (HAL) and stm32f3 (peripheral access crate, PAC) instead of the old f3 crate and stm32f30x-hal and stm32f30x which are no longer maintained. Swapping fixes the hard fault, but it turns out the write to the TDR field on the UART requires an unsafe block with stm32f3, because it doesn't have enough annotations in the SVD file to generate a safe bits() method. I'm reluctant to put (seemingly needless) unsafe code in the tutorial, but fixing it and pushing that all the way through the dependencies would take a while too. The best solution is probably to replace the tutorial code with something that uses the UART driver in the HAL instead, which would be more idiomatic anyway.

[wpd]

Thank you for the excellent explanation. Would it be correct (if provocative) to say that the author(s) of the cortex-m crate chose to subvert the Semantic Versioning concept and we are seeing the repercussions of that?

[adamgreig]

It's known as a "semver trick" because it doesn't break semantic versioning - only the identical types are re-exported in the old version, so it doesn't introduce breaking changes, but helps avoid fracturing the ecosystem. On balance I think it would be much worse if it didn't do this, because it would make ever upgrading to new versions of cortex-m extremely difficult.

However there definitely have been some unintended repercussions because it's a tricky thing to get right each time, and longer term we'd like to stop doing it.