add "the path towards stable" announcement #96

japaric · 2018-05-12T11:24:26Z

this is an announcement I'm preparing and that I'll (hopefully) post later today on u.r-l.o (*).
First, it announces that library development is possible on beta, then it explains what's missing to
make application development possible on stable. Then it covers the ongoing migration of the
Cortex-M ecosystem to stable on how you can help; in particular, it covers how to update device
crates, driver crates and HAL implementation crates. In ends by explaining what these changes mean
to current and future users; and what's the state of other architectures.

Any feedback is appreciated! cc @thejpster @jamesmunns @hannobraun @jcsoo @pftbest @dvc94ch
@dylanmckay

Note that several links are currently broken as I haven't finished publishing stuff but I'll fix
them all before posting the announcement.

(*) I plan to release the next newsletter on Tuesday including a link to this announcement so that
it sort gets extended coverage / exposition.

japaric · 2018-05-12T20:04:57Z

All the groundwork is done and the links have been updated. I'll publish this tomorrow morning as it's already late here.

therealprof · 2018-05-12T20:35:06Z

in particular, it covers how to update device crates, driver crates and HAL implementation crates.

I'm updating my set of stm32f042 crates at the moment. I'd be happy to try another set with your instructions...

therealprof · 2018-05-12T21:15:20Z

Weird:

cargo build --release --examples
   Compiling cortex-m-rt v0.5.0
   Compiling stm32f042 v0.5.3 (file:///Users/egger/OSS/stm32f042)
error: requires `start` lang_item

error: aborting due to previous error

error: Could not compile `stm32f042`.
warning: build failed, waiting for other jobs to finish...
error[E0015]: calls in statics are limited to constant functions, tuple structs and tuple variants
  --> examples/flash_systick_hsi48.rs:18:58
   |
18 | static GPIOA: Mutex<RefCell<Option<stm32f042::GPIOA>>> = Mutex::new(RefCell::new(None));
   |                                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to previous error

For more information about this error, try `rustc --explain E0015`.
error: Could not compile `stm32f042`.

To learn more, run the command again with --verbose.

I've used both the #![no_main] and entry!(main); features and the GPIO sharing problem is also new and makes me wonder how share peripheral resources into exception/interrupt handlers with the new stable approach?

jamesmunns · 2018-05-12T21:16:06Z

newsletters/2018-05-12-the-path-towards-stable.md

+
+> 2018-05-12
+
+We are happy to announce that *library* development for the Cortex-M targets is now possible on the


It might be good to have a tl;dr at the top for those that are passively watching the ecosystem. I would suggest something like this:

Larger TL;DR:

> **TL;DR** > > As we make progress to getting embedded development as a first class member of the > Rust ecosystem, we are making (necessary) changes which may break a number of crates > in the short term. Once we have landed all of the changes to make stable embedded > development possible, we expect this breakage to stop. > > If you are an embedded crate maintainer, keep an eye out for changes that affect your > crates (see below for more details). Make sure to test your crates on the current > `beta` release, and ping someone on the #rust-embedded IRC channel if you see something > broken!

Shorter TL;DR:

> **TL;DR** > > * We are making breaking changes in order to move towards stable development > * Some crates will break with these changes, if you notice something, file an issue and/or ping us on the #rust-embedded IRC channel > * These breaking changes will slow down once we have landed necessary features in stable > * If you are a crate maintainer, make sure you test your crates with the new versions of `cortex-m` (and similar) on the current `beta` release of Rust > * Thanks for your patience!

Thanks @jamesmunns. I think this a great idea; I'll add one of those.

I think something that should be explicitly noted is that stability / breakage is mainly referring to the compiler and language features, and that the libraries are not becoming stable in the 1.0 sense so more iteration with breaking changes in new minor version releases will continue to happen.

therealprof · 2018-05-12T22:33:02Z

So I was able to work around the peripheral sharing issue by reading through the bare-metal code to figure out that const-fn has been turned into an opt-in due to not being available in stable. Not being able to share resources with interrupt handlers in stable weakens the already underwhelming interrupt story...

There's still tons of other weird stuff like:

# cargo build --release --examples
   Compiling cortex-m-rt v0.5.0
   Compiling stm32f042 v0.5.3 (file:///Users/egger/OSS/stm32f042)
error: requires `start` lang_item

error: aborting due to previous error

error: Could not compile `stm32f042`.
warning: build failed, waiting for other jobs to finish...
error: build failed

Great, where's that start lang_item missing exactly?

Also the amount of boilerplate required is going through the roof which is very annoying, especially for example authors and teaching embedded Rust programming.

japaric · 2018-05-13T09:43:02Z

@therealprof Thanks for the input

So I was able to work around the peripheral sharing issue by reading through the bare-metal code to figure out that const-fn has been turned into an opt-in due to not being available in stable

I'll note the const fn issue in the announcement.

Not being able to share resources with interrupt handlers in stable ...

cortex-m-rtfm will work on beta / stable as soon as macros 1.2 (i.e. procedural bang! macros) is stabilized.

Great, where's that start lang_item missing exactly?

I'll add this to the cortex-m-quickstart troubleshooting guide and to the announcement.

There's still tons of other weird stuff like:

Could you be more specific and list a few of the items in this "tons of other weird stuff"?

Also the amount of boilerplate required is going through the roof

I believe the only new boilerplate is #![no_main] and entry!. Specifying the hard fault and default exception handlers is not boilerplate; like the panic handler, they define the core behavior of the program and must be tailored for the application.

We could certainly add a fallback for HardFault and DefaultHandler, in cortex-m-rt, if none was specified but I can't think of a good "one size fits all" default. Take for instance the handlers used in the quickstart examples: they are not good defaults; if the microcontroller is not attached to a debugger the HardFault handler goes into infinite recursion when invoked (bkpt raises a HardFault exception); same thing if you change the panic handler from panic_semihosting to panic_abort (abort raises a HardFault exception). CMSIS sets DefaultHandler to an infinite loop and calls it a day but I think that's hard to debug and beginner unfriendly.

If you have suggestions we can discuss them in a cortex-m-rt issue.

especially for example authors and teaching embedded Rust programming.

You can refactor the handlers into a crate -- the same way is done for e.g. panic-semihosting -- if you are going to reuse the code across several examples / programs.

therealprof · 2018-05-13T10:09:28Z

@japaric

I'll add this to the cortex-m-quickstart troubleshooting guide and to the announcement.

I'm pretty sure it's in one of the examples because the library itself compiles fine as does the one example I've already adapted but I'm a bit confused why it doesn't mention which example.

I believe the only new boilerplate is #![no_main] and entry!. Specifying the hard fault and default exception handlers is not boilerplate; like the panic handler, they define the core behavior of the program and must be tailored for the application.

The previous defaults were just fine and now they need to be explicitly specified also requiring additional mucking with use statements, so for me that is pretty much boilerplating...

CMSIS sets DefaultHandler to an infinite loop and calls it a day but I think that's hard to debug and beginner unfriendly.

Funny, because that's very much what I would expect and CMSIS seems to be golden standard that has to be followed to the character everywhere in Rust land now. 😏

I don't think an endless loop is at all debugger unfriendly and hard to debug, it always allows you to interrupt the program with the debugger, check the fault and walk it back. And that is also what is taught in MCU 101 classes, too. Other options would be reset (which is rather annoying and surprising) or using BKPT which is rather annoying because it will lockup the MCU if no debugger is attached at that point thwarting post-mortem debugging while an endless loop won't.

You can refactor the handlers into a crate -- the same way is done for e.g. panic-semihosting -- if you are going to reuse the code across several examples / programs.

It's not really about me but about beginners who might be intimidated about such things if they're no provided out of the box.

therealprof · 2018-05-13T19:11:42Z

Something's still odd about the build.rs scripts of cortex-m-rt and peripheral crates generated by svd2rust; they're rebuilding every single time here.

therealprof · 2018-05-13T21:59:39Z

So I've just ported the complete set of STM32F042 crates (and a few others that clashed randomly, cf. rust-embedded/embedded-hal#81). As far as I could test, everything seems to work, and the binaries have shrunk, cf. attached bloatlogs before and after the change:
bloat_log_before
bloat_log_after

So apart from the tedious new boilerplate which gets a bit long in the tooth after the 20th or so file (BTW: The signature change on the entry function also meant that I had to introduce an additional loop {} in each entry function) as well as the vastly increased compile times it's looking very good now. 👍

japaric · 2018-05-14T14:09:57Z

I'm a bit confused why it doesn't mention which example.

I think this is a missing Cargo feature, or a bug. It doesn't say which example failed to build when you use --examples.

they're rebuilding every single time here.

do you have steps to reproduce the problem?

therealprof · 2018-05-14T14:34:08Z

do you have steps to reproduce the problem?

Which one?

For the missing example name problem: Fetch my stm32f042-hal crate, remove entry stuff from an example and build them:

# cargo build --release --examples
   Compiling cortex-m-rt v0.5.0
   Compiling stm32f042 v0.6.0
   Compiling stm32f042-hal v0.4.0 (file:///Users/egger/OSS/stm32f042-hal)
error: requires `start` lang_item

error: aborting due to previous error

error: Could not compile `stm32f042-hal`.
warning: build failed, waiting for other jobs to finish...
error: build failed

For the re-compilation you can also use my stm32f042-hal crate and the included script tools/capture_example_bloat.sh to record the current binary sizes:

# tools/capture_example_bloat.sh
Processing example blinky
   Compiling stm32f042 v0.6.0
   Compiling bare-metal v0.2.0
   Compiling vcell v0.1.0
   Compiling cast v0.2.2
   Compiling void v1.0.2
   Compiling aligned v0.2.0
   Compiling cc v1.0.15
   Compiling numtoa v0.0.7
   Compiling panic-abort v0.1.1
   Compiling r0 v0.2.2
   Compiling nb v0.1.1
   Compiling volatile-register v0.2.0
   Compiling embedded-hal v0.2.0
   Compiling ina260 v0.2.0
   Compiling cortex-m-rt v0.5.0
   Compiling cortex-m v0.5.1
   Compiling stm32f042-hal v0.4.0 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 34.79 secs
Processing example blinky_delay
   Compiling cortex-m-rt v0.5.0
   Compiling stm32f042 v0.6.0
   Compiling stm32f042-hal v0.4.0 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 38.39 secs
...

therealprof · 2018-05-14T14:36:36Z

For comparison, with the previous version:

Processing example blinky
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Compiling cortex-m v0.3.1
   Compiling cortex-m v0.4.3
   Compiling aligned v0.1.2
   Compiling untagged-option v0.1.1
   Compiling bare-metal v0.1.2
   Compiling cortex-m-rt v0.4.0
   Compiling embedded-hal v0.1.2
   Compiling ina260 v0.1.1
   Compiling stm32f042 v0.5.3
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 27.68 secs
Processing example blinky_delay
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 1.4 secs
Processing example flash_systick
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 0.94 secs
Processing example i2c_hal_ina260reader
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 1.7 secs
Processing example i2c_hal_ina260serial
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 1.15 secs
Processing example i2c_hal_ssd1306alphabeter
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 1.0 secs
Processing example serial_echo
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 0.97 secs
Processing example spi_hal_apa102c
   Compiling stm32f042-hal v0.3.7 (file:///Users/egger/OSS/stm32f042-hal)
    Finished release [optimized + debuginfo] target(s) in 0.98 secs
Captures bloat for all examples into bloat_log_2018-05-14T16:34+02:00.txt

japaric · 2018-05-14T15:06:53Z

@therealprof the recompilation issue has been fixed in cortex-m-rt v0.5.1

therealprof · 2018-05-14T15:09:22Z

@japaric Thanks a bunch.

therealprof · 2018-05-14T15:10:27Z

Does svd2rust also need updating?

japaric · 2018-05-14T15:14:39Z

@therealprof no, only cortex-m-rt needs to be updated.

japaric added 2 commits May 12, 2018 13:21

add "the path towards stable" announcement

c486c54

update / fix links

30a87d5

jamesmunns reviewed May 12, 2018

View reviewed changes

address review comments

cddf3a8

japaric merged commit 6a10701 into master May 13, 2018

japaric deleted the the-path-towards-stable branch May 13, 2018 11:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add "the path towards stable" announcement #96

add "the path towards stable" announcement #96

japaric commented May 12, 2018

japaric commented May 12, 2018

therealprof commented May 12, 2018

therealprof commented May 12, 2018 •

edited

Loading

jamesmunns May 12, 2018 •

edited

Loading

japaric May 13, 2018

therealprof commented May 12, 2018

japaric commented May 13, 2018

therealprof commented May 13, 2018

therealprof commented May 13, 2018

therealprof commented May 13, 2018

japaric commented May 14, 2018

therealprof commented May 14, 2018

therealprof commented May 14, 2018

japaric commented May 14, 2018

therealprof commented May 14, 2018

therealprof commented May 14, 2018

japaric commented May 14, 2018


		> 2018-05-12

		We are happy to announce that library development for the Cortex-M targets is now possible on the

add "the path towards stable" announcement #96

add "the path towards stable" announcement #96

Conversation

japaric commented May 12, 2018

japaric commented May 12, 2018

therealprof commented May 12, 2018

therealprof commented May 12, 2018 • edited Loading

jamesmunns May 12, 2018 • edited Loading

Choose a reason for hiding this comment

japaric May 13, 2018

Choose a reason for hiding this comment

therealprof commented May 12, 2018

japaric commented May 13, 2018

therealprof commented May 13, 2018

therealprof commented May 13, 2018

therealprof commented May 13, 2018

japaric commented May 14, 2018

therealprof commented May 14, 2018

therealprof commented May 14, 2018

japaric commented May 14, 2018

therealprof commented May 14, 2018

therealprof commented May 14, 2018

japaric commented May 14, 2018

therealprof commented May 12, 2018 •

edited

Loading

jamesmunns May 12, 2018 •

edited

Loading