Directory Restructure

[Amit Levy]

In this episode of making the code more mature...

Phil noted he thought the directory structure was getting unwieldy, made worse by the recent move to Cargo which added yet-another `src` subdirectory in the already fairly nested directory structure. I agree.

I propose getting rid of the top-level `src` directory and instead having the following (I expanded selectively to make it clear where crates actually live):

tock

|-- userland/

    |-- newlib/

    +-- libtock/

    +-- examples/

        |-- blink/

        |-- sensors/

        ...

    +-- README.md

+-- arch/

    |-- cortex-m0/

    +-- cortex-m4/

    +-- README.md

+-- boards/

    |-- firestorm/

    +-- nrf51dk/

    + README.md

+-- chips/

    |-- nrf51/

    +-- sam4l/

    +-- README.md

+-- docs/

+-- drivers/

    |-- src/

    +-- Cargo.toml

+-- kernel/

    |-- src/

    +-- Cargo.toml

+-- tools/

The high level rational is that each crate is as close to the top-level directory as possible, only putting them in subdirectories is useful for grouping. For example, the architecture crates, chip crates and board crates are grouped in their respective directories so it's obvious where to look for things.

You might notice that a bunch of crates are now merged into the `kernel` crate--`main`, `common`, `hil`, `support` and `process`. These were really separated for historical reasons, because other crates weren't able to depend on `main`. But that's gone, so I think it makes sense to just merge them. `kernel` then, serves the dual purpose of containing the scheduler and exposing a package with various utilities and traits that other parts of a Tock system might depend on.

One exception to this is the `drivers` crate because it, unlike the kernel, is untrusted, and should not be allowed to compile with `unsafe`, so it _needs_ to be a separate crate.

Thoughts?

-Amit

[Branden Ghena]

Should drivers/ instead be called capsules/?

Pros:

• Directory may hold code that is not technically a driver, runs in the kernel, and can be compiled "safely"
  
• We use the word 'capsule' in papers to refer to this kind of code

Cons:

• 'Capsule' doesn't have a meaning in the software community at large. Will confuse new users

I also think userland/ might make more sense to new users as applications/

[Amit Levy]

I agree with `drivers` vs. `capsules`. In particular, virtualization layers also live here. In general, anything that's not "special" would live in this directory, and it should really be a collection of capsules that we maintain. They could eventually be subdivided further (in principal) to, e.g. "sensors", "virtualization", "net", etc.

Another downside to the name `capsules` is that it implies other components are not capsules (which is not true). But I think it's a better name than drivers regardless.

For `applications` vs. `userland`, my only reservation is that actually the main code that belongs here is userland library code (e.g. crt0, system call wrappers, `wait_for`, etc). In particular, an app developer should be able to build a static library for either a generic Tock app or a platform specific one (which includes interfaces for platform-specific drivers) and copy that to their app development directory (to support simple app development out of tree).

We should have applications here as well, but I think we might want to even restrict it to example-apps that work across platforms. One of the bummers I felt with TinyOS was that `apps` had an collection of apps that each only worked for 1 platform, and it's not at all clear which one builds on which.

Granted, the name of the directory doesn't necessarily affect this organization, and if "applications" is clearer regardless, I'm for it.

[Pat Pannuto]

+1 capsules

I lean `userland` over `applications` for the same reasons as Amit. One might imagine a `userland/support` or `userland/libraries` and `userland/applications`, but that could be prematurely deep. I think a flat `userland` is fine for now.

I do have some sensitivity to the generic `apps` folder and the question of what platforms it will run on. Prabal has brought this up to varying degrees before as well. It's obvious that a Blink app will only run on a platform with an LED. It's the dream and an "Environmental Monitoring" app will gracefully degrade to using the sensors available. It's useless to have an "Intrusion Detection" app on a device with no hardware to support it. I don't have a good solution to the `apps` folder vs platforms that support them problem, but I think it's a good question to talk about.

Maybe apps have a manifest file of some kind describing required and optional sensors, maybe that's just a readme. Should an app build successfully on a platform with no hardware to support it? Can it even know if kernel calls are needed to discover hardware resources?

Relatedly, (and I think this has been Prabal's big question for a while), as the number, diversity, and specificity of capsules grows, what does a "cross-platform", "stable" ABI look like for apps - both at a mechanistic level (global registry of syscall #'s?) and a runtime level (what ABIs does _this_ kernel/platform support?)

--
You received this message because you are subscribed to the Google Groups "Tock Embedded OS Development Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tock-dev+u...@googlegroups.com.
To post to this group, send email to tock...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tock-dev/15eac822-888e-4733-99a0-864cc3f1d8b7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Amit Levy]

OK, I'm calling it on the initial RFC period and I'm going to incorporate Pat and Branden's feedback into a pull request. Of course feel free to continue to send feedback on this thread if you haven't had your say yet.

To unsubscribe from this group and stop receiving emails from it, send an email to tock-dev+unsubscribe@googlegroups.com.

[Amit Levy]

FYI, we did this last week in PR 113 (https://github.com/helena-project/tock/pull/113).

There are some remaining questions about the internal structure of the `kernel` crate as well as the location of `support` (which is sort of architecture-specific) in `kernel` instead of the chip-specific crates, but we'll fix those incrementally.

To unsubscribe from this group and stop receiving emails from it, send an email to tock-dev+u...@googlegroups.com.

To post to this group, send email to tock...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tock-dev/8799178a-3e68-4a78-b407-361c01508a49%40googlegroups.com.