Talking Tock 67
Tock Registers' register_map API
by jrvanwhytock-registers versions 0.11 and 0.12 have been published on crates.io! These
releases introduce register_map, the successor to register_structs. It is a
complete redesign, with a new syntax for specifying register layouts and a
completely new format for the generated code. It has the following improvements
over register_structs:
- It resolves the reference-to-MMIO soundness issue.
- It supports unit-testing driver implementations.
- It better supports registers with non-pointer-sized addresses, such as x86 IO ports.
- It allows external crates to define new operations beyond “read” and “write”.
The new design is documented in the README, rustdoc, and in the docs/,
examples/, and tests/ directories of the tock-registers
repository. You can also reference
pull request 11, which
introduced the design.
To make it easier to incrementally migrate code to register_map, these
releases do not remove the earlier APIs. However, because register_structs is
unsound, it is immediately deprecated: please migrate code to register_map
instead. The difference between 0.11 and 0.12 is the deprecation mechanism:
0.11 merely documents the old APIs as deprecated, 0.12 additionally uses the
#[deprecated] attribute to emit compiler warnings on code that uses the
unsound APIs. If your project denies warnings in CI, you can use 0.11 as a
stop-gap while you migrate to register_map, otherwise we recommend updating
directly to 0.12.
What’s Next?
The current roadmap for tock-registers is:
- Delete
register_structsand the other deprecated APIs from the codebase. - Use tock-registers from within the main tock repository, and iterate on the
register_mapAPI. - Once the
register_mapAPI seems stable, we will publish tock-registers 2.0.
The jump from release 0.12 to 2.0 is intentional: register_map is effectively
the second major iteration of tock-registers, and we did not feel that a 1.0
release would be suitable for it.