Create crate for Tock Registers #984

brghena · 2018-06-12T19:27:14Z

Pull Request Overview

This PR creates a separate crate for the Tock register interface (named tock-regs) and moves the code to tools/tock-register-interface/. While this change affects many files throughout Tock, almost all of them are just changes to the import statement. Additionally, Cargo.toml files have changed to reference the new crate, and documentation has been updated.

The driver for this change is to allow other projects to use or extend Tock registers. In order to support this, the mask and shift fields of Field as well as the mask and value fields of FieldValue are made public.

An example of using this crate in an external project can be found here based off of examples from @niklasad1 and @andre-richter. This example both uses Tock registers and extends them with additional functionality. Unfortunately, the first build of this example repo takes a considerable amount of time (several minutes) because using the Tock registers crate requires a clone of the entire Tock repo. Subsequent builds are quick, however.

Closes #930.

Testing Strategy

Compiling all boards.

TODO or Help Wanted

None

Documentation Updated

Kernel: Updated the relevant files in /docs, or no updates are required.
N/A ~~Userland: Added/updated the application README, if needed.~~

Formatting

Ran make formatall.

andre-richter · 2018-06-12T20:01:37Z

Awesome, thanks a lot for the effort. Unfortunately, currently not much free time for hobby projects on my side, but I will definitely check this out once time permits.

niklasad1 · 2018-06-12T20:54:03Z

tools/tock-register-interface/src/lib.rs

+pub mod regs;
+
+#[macro_use]
+pub mod macros;


So the only thing I would want is to export the structs directly here by:

pub use regs::{ReadOny, WriteOnly, LocalRegisterCopy, Field, FieldValue}

Then if I use this crate it's enough to

extern crate tock_regs; use tock_regs::ReadWrite;

Instead of

extern crate tock_regs; use tock_regs::regs::ReadWrite;

That seems like a good suggestion. I will do that.

niklasad1 · 2018-06-12T20:56:02Z

tools/tock-register-interface/src/regs.rs

@@ -293,8 +290,8 @@ impl<R: RegisterLongName> From<LocalRegisterCopy<u32, R>> for u32 {
 /// Specific section of a register.
 #[derive(Copy, Clone)]
 pub struct Field<T: IntLike, R: RegisterLongName> {
-    mask: T,
-    shift: u32,
+    pub mask: T,


Why are these fields made pub?

So that other users can extend the register system. For example: https://github.com/brghena/tock-register-example/blob/master/src/cpu_regs.rs#L16

It is annoying that they have to public though. Do you have any suggestions on a better way to do this?

Ok, I see. I don't think it possible to leak private items without getters.

niklasad1

Looks good 👍

bradjc · 2018-06-12T21:15:42Z

arch/cortex-m3/src/systick.rs

 use kernel::common::StaticRef;
+use tock_regs::regs::{ReadOnly, ReadWrite};


I think it would be better to have the kernel crate depend on the new tock_regs crate, and re-export the regs they way they are now so we don't need all of these changes.

What's the rationale for re-exporting them through the kernel? I'm happy to make the change, but I'm not sure why it would be preferable compared to directly referencing the tock_regs crate. Do we expect all libraries to be re-exported through the kernel in Tock?

It would mean not having to change all these files every time we do this (since there is a motion to move the cells too), and it seems like all of these helper functions should come from the same place (and I think it makes sense to stick with them coming from the kernel trait).

@bradjc

Do you mean that only the kernel imports the crate(tock_regs) and then exports as pub?

For example in lib.rs:

extern crate tock_regs; pub use tock_regs;

Then others just use use kernel::tock_regs::ReadOnly?!

No, the kernel lib.rs does whatever it has to so that chips use kernel::common::regs::ReadOnly as they do now.

I agree with Brad that centralizing the dependencies within Tock (by re-exporting through the kernel crate) is a good idea.

Ah, makes sense!

bradjc

Idea: export tock_regs through the kernel.

phil-levis

I agree with @bradjc suggestion to re-export.

alevy · 2018-06-19T14:18:44Z

Better @phil-levis and @bradjc? Now none of the crates have changed at all, except kernel which re-exports tock-regs and the Cargo.lock files which now include tock-regs as a sub-dependency through kernel.

bradjc

Looks good

brghena · 2018-06-19T15:52:51Z

This looks good to me. Thanks so much for making those changes Amit!!

The only real changes here are making the tock-register-interface crate, and the `Cargo.toml` and `lib.rs` file connections to it in `arch/` and `chips/`. Tested on Hail, where the Hail app still Hails.

brghena · 2018-06-19T17:11:41Z

(rebased on master again since we had all the pulls today)

niklasad1 · 2018-06-19T21:29:36Z

kernel/src/lib.rs

 #![no_std]

+extern crate tock_regs;
+
+pub use tock_regs::{register_bitfields, register_bitmasks};


Is it really worth introducing another unstable feature just for using extern macros over #[macro_use(register_bitfields, register_bitmasks)]?

OT: I don´t like this syntax for using macros confuses me with ordinary imports but but .........

niklasad1

Ok, grumble on using #![feature(use_extern_macros)] because we are not consistent through the codebase. In all other places, we are using #[macro_use]

alevy · 2018-06-19T21:58:15Z

@niklasad1

on using #![feature(use_extern_macros)] because we are not consistent through the codebase. In all other places, we are using #[macro_use]

Don't they serve different purposes? I thought #![feature(use_extern_macros)] was the only way to export macros imported from a different crate, while #[macro_use] only works when importing macros from a sub-module.

niklasad1 · 2018-06-20T03:48:10Z

@alevy

Yes, you right never mind (clearly haven´t done my homework)
But, a super module can’t import a submodule’s macros

Addressed concern

phil-levis

My one comment is that if it isn't already there, putting Shane's name somewhere in the documentation would be useful. This was less important when it was internal but if the goal is for other people to use it too giving credit in the files is good.

andre-richter · 2018-06-24T12:18:00Z

Thanks for carving this out!

Any plans to upload it to crates.io with a license? Would make it a bit easier to include it and reuse some snippets where needed in one's own crates :)

bradjc · 2018-06-25T21:18:37Z

Would pulling it from the gihub repo in cargo.toml not work for now? I'm not sure how everyone feels but I don't think we are ready to support that as a component on crates.io.

andre-richter · 2018-06-25T21:49:07Z

Not at all, that is perfectly fine. The question was more towards the licensing. But I overlooked the license files in the tock root, and thought the project is unlicensed. My bad, nevermind 😅.

brghena added the P-Significant This is a substancial change that requires review from all core developers. label Jun 12, 2018

niklasad1 reviewed Jun 12, 2018

View reviewed changes

niklasad1 previously approved these changes Jun 12, 2018

View reviewed changes

bradjc reviewed Jun 12, 2018

View reviewed changes

bradjc requested changes Jun 12, 2018

View reviewed changes

phil-levis previously requested changes Jun 13, 2018

View reviewed changes

alevy dismissed niklasad1’s stale review via b4b210c June 19, 2018 14:17

alevy force-pushed the seperate-registers branch from d3509fa to b4b210c Compare June 19, 2018 14:17

alevy previously approved these changes Jun 19, 2018

View reviewed changes

bradjc previously approved these changes Jun 19, 2018

View reviewed changes

alevy dismissed stale reviews from bradjc and themself via 2bfcb3e June 19, 2018 14:41

alevy previously approved these changes Jun 19, 2018

View reviewed changes

brghena added 3 commits June 19, 2018 13:09

Make Tock Register Interface its own crate

ef87cb3

The only real changes here are making the tock-register-interface crate, and the `Cargo.toml` and `lib.rs` file connections to it in `arch/` and `chips/`. Tested on Hail, where the Hail app still Hails.

Update documentation

511f810

Make some fields public so they can be built on

9294bad

brghena dismissed alevy’s stale review via 9294bad June 19, 2018 17:10

brghena force-pushed the seperate-registers branch from 2bfcb3e to 9294bad Compare June 19, 2018 17:10

brghena mentioned this pull request Jun 19, 2018

A directory for crates #1006

Merged

2 tasks

alevy previously approved these changes Jun 19, 2018

View reviewed changes

bradjc previously approved these changes Jun 19, 2018

View reviewed changes

niklasad1 reviewed Jun 19, 2018

View reviewed changes

niklasad1 previously approved these changes Jun 19, 2018

View reviewed changes

bradjc added the last-call Final review period for a pull request. label Jun 21, 2018

phil-levis approved these changes Jun 21, 2018

View reviewed changes

phil-levis previously approved these changes Jun 21, 2018

View reviewed changes

tock regs: add author

da8cfca

bradjc dismissed stale reviews from phil-levis, niklasad1, alevy, and themself via da8cfca June 21, 2018 15:33

bradjc approved these changes Jun 21, 2018

View reviewed changes

bradjc merged commit 435f4d3 into master Jun 21, 2018

bradjc deleted the seperate-registers branch June 21, 2018 15:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create crate for Tock Registers #984

Create crate for Tock Registers #984

brghena commented Jun 12, 2018

andre-richter commented Jun 12, 2018

niklasad1 Jun 12, 2018 •

edited

brghena Jun 12, 2018

niklasad1 Jun 12, 2018

brghena Jun 12, 2018

niklasad1 Jun 14, 2018

niklasad1 left a comment

bradjc Jun 12, 2018

brghena Jun 13, 2018

bradjc Jun 13, 2018

niklasad1 Jun 13, 2018

bradjc Jun 13, 2018

phil-levis Jun 13, 2018

niklasad1 Jun 14, 2018

bradjc left a comment

phil-levis left a comment

alevy commented Jun 19, 2018

bradjc left a comment

brghena commented Jun 19, 2018

brghena commented Jun 19, 2018

niklasad1 Jun 19, 2018

niklasad1 left a comment

alevy commented Jun 19, 2018

niklasad1 commented Jun 20, 2018 •

edited

phil-levis left a comment

andre-richter commented Jun 24, 2018

bradjc commented Jun 25, 2018

andre-richter commented Jun 25, 2018

		use kernel::common::StaticRef;
		use tock_regs::regs::{ReadOnly, ReadWrite};

Create crate for Tock Registers #984

Create crate for Tock Registers #984

Conversation

brghena commented Jun 12, 2018

Pull Request Overview

Testing Strategy

TODO or Help Wanted

Documentation Updated

Formatting

andre-richter commented Jun 12, 2018

niklasad1 Jun 12, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

niklasad1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bradjc left a comment

Choose a reason for hiding this comment

phil-levis left a comment

Choose a reason for hiding this comment

alevy commented Jun 19, 2018

bradjc left a comment

Choose a reason for hiding this comment

brghena commented Jun 19, 2018

brghena commented Jun 19, 2018

Choose a reason for hiding this comment

niklasad1 left a comment

Choose a reason for hiding this comment

alevy commented Jun 19, 2018

niklasad1 commented Jun 20, 2018 • edited

phil-levis left a comment

Choose a reason for hiding this comment

andre-richter commented Jun 24, 2018

bradjc commented Jun 25, 2018

andre-richter commented Jun 25, 2018

niklasad1 Jun 12, 2018 •

edited

niklasad1 commented Jun 20, 2018 •

edited