This guide covers best practices for maintaining subsytems not in the Tock master repository.
It is a work in progress. Comments and pull requests are appreciated!
Tock aims to maintain a stable syscall ABI, but does not guarantee stability of kernel interfaces. There are two primary channels to stay abreast of Tock development:
- tock-dev mailing list: Any major Tock changes will be announced via this list. The list also support general Tock development, however it is relatively low traffic (<1 email/day on average).
- Tock GitHub: All Tock changes go through Pull Requests. Non-trivial changes will generally wait at least one week to merge to allow for feedback.
Finally, please don't hesitate to ask for help.
Usually it is easiest to keep a submodule of Tock in your project.
We then suggest generally mirroring the Tock directory structure, something like:
$ tree .
.
├── boards
│ └── my_board
│ ├── Cargo.toml
│ ├── Makefile
│ ├── layout.ld
│ └── src
│ └── main.rs
├── my_drivers
│ ├── Cargo.toml
│ └── src
│ ├── my_radio.rs
│ └── my_sensor.rs
└── tock # Where this is a git submodule
│ ├── ...
Your board's Makefile will need to set a PLATFORM variable, specifying
the name of this platform, and include the primary Tock Makefile. We
also strongly suggest defining program and flash targets that
specify how the kernel is loaded onto your board.
PLATFORM = my_board
# Include Tock build rules
include ../../tock/boards/Makefile.common
# Rules for loading via bootloader or other simple, direct connection
program:
...
# Rules for loading via JTAG or other external programmer
flash:
...Your board's Cargo.toml will need to express how to find all the components that your board uses. Most of these will likely be references to elements of Tock.
[package]
name = "my_board"
version = "0.1.0"
authors = ["Example Developer <developer@example.com>"]
build = "../../tock/boards/build.rs"
[profile.dev]
panic = "abort"
lto = true
opt-level = 0
debug = true
[profile.release]
panic = "abort"
lto = true
[dependencies]
cortexm4 = { path = "../../tock/arch/cortex-m4" }
capsules = { path = "../../tock/capsules" }
sam4l = { path = "../../tock/chips/sam4l" }
kernel = { path = "../../tock/kernel" }
my_drivers = { path = "../../my_drivers" }If using a linker script named layout.ld, your board crate can make use of the
Tock submodule's build.rs script to ensure it rebuilds when any linker scripts
change.
Custom chips, drivers, or other components should only require a Cargo.toml.
[package]
name = "my_drivers"
version = "0.1.0"
authors = ["Example Developer <developer@example.com>"]
[dependencies]
kernel = { path = "../tock/kernel" }- Several of the Tock core developers also work on the Signpost project. The project includes seven boards (and growing!) that run Tock.
- New chips and boards often begin life out of tree. A current effort is the STM32 port.