Split libtock into core and high level library

[torfmaster]

Summary

In order to address #160 we decided to do a first draft of splitting the library into parts.

The idea is that there are two layers:

• libtock-core
• libtock-rs

(names tbd). Libtock-core contains the panic handler, the entry point, the allocator and the syscall interfaces. libtock-rs uses libtock-core and the interface stays as usual.

Possible Extensions

We deleted the "blink" code from the panic handler. This saves more than 1kbytes in the text segment. If this feature is still wanted we could implement the following:

• provide a feature in libtock-core to opt-out the panic handler in libtock-core
• provide a feature for libtock-rs to opt-out the panic handler in libtock-core and using a blinking panic handler.

In the long run the (default) panic handler could exit the app and send debug information to the kernel which could print it for example. This could be implemented once the kernel functionality is in place.

Open questions

The current implementation of the panic handler more or less silently fails if there is a panic. Panics can be identified by enabling the "trace_syscall" option in the kernel. How should this be tackled?
Should there be a default panic handling or should it be customizable and if yes how should it be customized?

[jrvanwhy]

Regarding your open question: If we can build libcore using cargo (see https://www.github.com/tock/tock/issues/1682) then we should be able to enable the panic_immediate_abort feature (see rust-lang/rust#55011), which should help us remove a lot of `panic!()'s machinery. That would remove the call to the panic handler entirely, so it becomes a moot point.

If panic handling is customizable then I think it should be customized through panic handler crates (as is already the case for other platforms). We would need to add a cargo feature to libtock-core to prevent libtock-core from providing its panic handler.

[torfmaster]

Regarding your open question: If we can build libcore using cargo (see https://www.github.com/tock/tock/issues/1682) then we should be able to enable the panic_immediate_abort feature (see rust-lang/rust#55011), which should help us remove a lot of `panic!()'s machinery. That would remove the call to the panic handler entirely, so it becomes a moot point.

Okay, but that's probably something for the remote future, right?

[torfmaster]

If panic handling is customizable then I think it should be customized through panic handler crates (as is already the case for other platforms).

Do you mean adding a crate only containing the panic handler here (and turning off the panic handler in libtock-core)?

[jrvanwhy]

Regarding your open question: If we can build libcore using cargo (see https://www.github.com/tock/tock/issues/1682) then we should be able to enable the panic_immediate_abort feature (see rust-lang/rust#55011), which should help us remove a lot of `panic!()'s machinery. That would remove the call to the panic handler entirely, so it becomes a moot point.

Okay, but that's probably something for the remote future, right?

Oh, I misunderstood your question as referring to the future. Yes, my comment was out of scope for this PR.

[jrvanwhy]

If panic handling is customizable then I think it should be customized through panic handler crates (as is already the case for other platforms).

Do you mean adding a crate only containing the panic handler here (and turning off the panic handler in libtock-core)?

That's what I meant. However, when I look around I think my assertion that panic handler crates were in use on other platforms was incorrect.

I'm not strongly opinionated on whether panic behavior is controlled by swapping crates or whether it is controlled through cargo features, other than I think we need a "no libtock-rs panic handler" feature so applications can overwrite things themselves. I would prefer to use interchangable panic handler crates rather than cargo features to control behavior.

[alistair23]

This is great! Do you have any idea what the split looks like size wise?

[alistair23]

Does this mean the new libtock-rs doesn't need the nightly toolchain?

[torfmaster]

Unfortunately not. Its dependencies need it, still. In libtock-core it should be in principle possible to remove the necessity for the nightly compiler (as in https://github.com/rust-embedded/cortex-m-rt), however I am not sure whether it is worth the effort, while the tock kernel needs its.

[torfmaster]

I assume this is fixed?

[torfmaster]

This is great! Do you have any idea what the split looks like size wise?

It is hard to answer: usinglibtock-rs is zero cost unless you use certain features. We have made quick investigations about that:

• using `block_on´ (i.e. using futures instead of sync runtime) costs 200 bytes
• using the parallel sleep driver costs 1kb

I think the last point has some potential for optimization, if one restricts to not delay in paralllel futures. The current workarounds for drawbacks of the timer interface are quite expensive.

However, I think we currently don't have objective criteria to judge about the size of libtock-rs applications. I started to create some basic tooling for that and have the vision of including that into the CI of libtock: https://github.com/torfmaster/libtock-size-utils (e.g. store some snapshot sizes, and fail if some threshold is hit).

[Woyten]

• using `block_on´ (i.e. using futures instead of sync runtime) costs 200 bytes
• using the parallel sleep driver costs 1kb

It should be mentioned that those are the approximate values for a trivial example. We observed that the impact of futures or the parallel sleep driver on the text size is significantly lower in more complex examples. This is kind of expected due to synergetic effects.

[alistair23]

What is this PR still waiting on?

[torfmaster]

Apart from some minor fixes we still need to create a solution for the panic handler, i.e. add a feature flag or an external panic crate.

[jrvanwhy]

I recommend adding a cargo feature flag to libtock-core that -- when enabled -- removes the panic handler.

[torfmaster]

I recommend adding a cargo feature flag to libtock-core that -- when enabled -- removes the panic handler.

I'll do that+add the original panic handler for libtock-rs behind a feature flag.

[torfmaster]

bors try

[Woyten]

I recommend adding a cargo feature flag to libtock-core that -- when enabled -- removes the panic handler.

I already prepared that. It's just that it's hard to test.

[torfmaster]

I already prepared that. It's just that it's hard to test.

Adding the original panic handler inside libtock-rs behind a feature flag may be a test.

[bors]

try

Build succeeded

• continuous-integration/travis-ci/push

[Woyten]

I pushed something, s.t. you can see where this is getting at but I am still trying to find a solution to include the feature flags into our build pipeline.

[torfmaster]

bors try

[bors]

try

Build succeeded

• continuous-integration/travis-ci/push

[torfmaster]

I pushed a commit addressing all comments but the panic_handler issue.

[torfmaster]

I added an example including a custom error handler and build this in CI. An alternative would be to put a regular panic example into the core crate and restore the original error handler of libtock-rs as a default feature.

[Woyten]

I found a slightly different solution which doesn't add a new example and tests both features.

[bradjc]

I would recommend a readme in the core folder that describes what is (and what isn't) in core. Mainly for future readers to understand what the conceptual split is.

[torfmaster]

I added a (minimal) readme and remove the now duplicated example with a custom panic handler.

bors try

[bors]

try

Build succeeded

• continuous-integration/travis-ci/push

[Woyten]

bors r+

[bors]

Build succeeded

• continuous-integration/travis-ci/push