Tock Logo

Talking Tock

Talking Tock 67

Tock Registers' register_map API

tock-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:

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:

  1. Delete register_structs and the other deprecated APIs from the codebase.
  2. Use tock-registers from within the main tock repository, and iterate on the register_map API.
  3. Once the register_map API 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.