Tock 2.2

Tock 2.2 represents two years of Tock development since v2.1.1. This release contains almost 3900 commits made across 840 PRs by 90 contributors (of which 48 are new contributors!). It is the first Tock release that can compile on a stable Rust toolchain, and contains many other important fixes, new subsystems, new platforms, new drivers, and major refactors.

Backwards Compatibility

Tock 2.2 extends its system call interface through one new system call (Yield-WaitFor), but retains backwards compatibility with Tock 2.1.1 for its core system call interface and all stabilized drivers.

In this release, we revised Tock's alarm system call driver implementation to predictably wrap its ticks values at (2**32 - 1) ticks, across all platforms. Before this change, hardware alarm implementations that were less than 32 bit wide would wrap before reaching (2**32 - 1) ticks, which complicated correct alarm handling in userspace. In Tock 2.2, these alarm implementations are scaled to 32 bit, while also scaling their advertised frequency appropriately. While this change is non-breaking and compatible with the previous alarm implementation, it can expose such scaled alarms to userspace at significantly higher advertised frequency values. Userspace alarm implementations that did not correctly handle such high frequencies may need to be fixed to support this new driver implementation.

Security and arch-crate Fixes

Tock 2.2 includes important and security-relevant fixes for its Cortex-M and RISC-V architecture support.

• When switching between applications, the RISC-V PMP implementation did not correctly invalidate any additional memory protection regions that are not overwritten by the target app's PMP configuration. Under certain conditions this can allow an application to access private memory regions belonging to a different applications (such as when using IPC).

• The Cortex-M (Armv7-M) and Cortex-M0/M0+ (Armv6-M) hard fault, interrupt and svc handlers contained a bug that could allow an application to execute in privileged mode after returning from the handler. This allows an application to execute code at kernel privileges and read / write arbitrary memory.

Stable Rust Support

This release removes all nightly Rust features from all of Tock's core kernel crates (such as kernel, arch/*, and chips/*). This allows Tock to be built on the Rust stable toolchain for the first time!

We demonstrate this by switching the hail board to a stable toolchain in this release. We continue to compile other boards on the Rust nightly toolchain, as this enables some important code-size optimizations (such as by compiling our own, size-optimized core library).

AppID, Credentials and Storage Permissions

This Tock release revisits how applications are identified in the kernel, and introduces a set of mechanisms that allow developers to identify, verify, and restrict applications that are running on a Tock kernel. AppIDs are the core mechanism to enable this and identify an application contained in a userspace binary. AppIDs allow the kernel to apply security policies to applications as their code evolves and their binaries change. We specify AppIDs, Credentials and their interactions with process loading in a draft TRD.

Additionally, we introduce a mechanism to assign applications permissions to access some persistent storage (e.g., keys in a key value store). This mechanism interacts with AppIDs (ShortIDs) and is also specified in a a draft TRD.

Major Refactors and Interface Changes

We implement a number of kernel-internal refactors and interface changes:

• System call drivers are now mandated to either return Success or Failure(ErrorCode::NODEVICE) for a command system call with command number 0. Previously, some drivers used this command number to also convey additional information to userspace. This release does not change the interface of any stabilized drivers, which will be updated as part of Tock 3.0.

  Relevant PRs:

  • Syscall Spec: Allow Command 0 to return Success with value or lock it down by @ppannuto in #3626
  • Update command 0 comments on stabilized userspace drivers by @hudson-ayers in #3402
  • capsules: ensure driver existence check by @Samir-Rashid in #3613

• Tock 2.2 introduces [a new policy to support external dependencies][external-deps] in the upstream Tock codebase. As part of this effort, we split up the existing, single capsules crate into multipe crates (such as capsules-core, capsules-extra, and capsules-system) with different guarantees concerning stability and use of external dependencies. The core capsules crate contains capsules deemed essential to most Tock systems, as well as virtualizers which enable a given single peripheral to be used by multiple clients. Other capsules have been moved to the extra capsules crate. The system capsules crate contains components that extend the functionality of the Tock core kernel, while not requiring unsafe.

  Relevant PRs:

  • doc: Add ExternalDependencies.md by @alistair23 in #3312
  • capsules: split into core/ and extra/ (implementing #3346) by @lschuermann in #3396
  • Create system capsules crate, move kernel implementations, update boards by @bradjc in #3992

• Furthermore, the DeferredCall and DynamicDeferredCall subsystems have been replaced with a more lightweight and unified deferred call infrastructure. This new approach has a smaller code size overhead and requires less setup boilerplate code than DynamicDeferredCall.

  Relevant PR:

  • Replace DeferredCall and DynamicDeferredCall with a more general-purpose implementation by @hudson-ayers in #3382

• LeasableBuffer has been renamed to SubSlice and features a significantly improved API. Multiple subsystems have been ported to this new type.

  Relevant PRs:

  • kernel: LeasableBuffer: fix double slice end value by @bradjc in #3511
  • kernel: leasablebuffer: add APIs by @bradjc in #3505
  • Rename LeasableBuffer to SubSlice by @bradjc in #3519
  • Switch SPI master HIL to leasable buffers instead of raw slices by @alevy in #4173
  • ot: tests: switch to subslice by @bradjc in #3570
  • ot: tests: LB->SS by @bradjc in #3573
  • Screen: update HIL to simplify, format, and use SubSlice by @bradjc in #3792
  • kernel: SubSlice: fix slice calculation by @bradjc in #3791

• Tock 2.2 introduces "configuration boards": variants of in-tree board definition showcasing certain subsystems or peripherals. These boards (under boards/configurations) are implemented by converting some Tock boards into combined "lib + bin" crates and extending these boards.

  Relevant PRs:

  • boards: remove nrf52840dk demo by @bradjc in #3580
  • Add Configuration Boards by @bradjc in...

This is the first testing release for Tock 2.2!

With almost two years since Tock 2.1.1, it's about time for a new Tock release! Compared to 2.1.1, this release will contain 3882 commits made in 836 PRs by 90 contributers (of which 48 are new contributors!). This release is the first to support stable Rust for out-of-tree and (a subset of) the in-tree boards, adds new supported boards, and contains many other fixes and improvements. Some notable bug fixes are in the Cortex-M arch crate to prevent userspace applications from executing in privileged mode, and disabling unused PMP regions on RISC-V. A full change list will be included with the final release notes.

Release organization and testing will commence at #4272.

Tock 2.1.1 fixes an issue present in the Tock 2.0 and Tock 2.1 releases concerning system call error return values issued when userspace applications were issuing system calls towards non-existent capsules.

Breaking Changes

• The Tock system call interface specification (TRD 104) mandates that the kernel returns an error of NODEVICE when issuing a system call towards a non-registered driver number. However, Tock 2.0 would instead return an error of NOMEM on a subscribe system call. Furthermore, Tock 2.1 returns an error of NOMEM on all of read-only allow, read-write allow and subscribe system calls. This release changes this behavior and returns an error of NOMEM for all of these cases, in compliance with the specification (#3300).

All Merged PRs

Tock 2.1 has seen numerous changes from Tock 2.0. In particular, the new system call interface introduced with Tock 2.0 has been refined to provide more guarantees to processes with respect to sharing and unsharing buffers and upcalls. Other changes include the introduction of a userspace-readable allow system call, support for new HILs and boards, and various other bug-fixes and improvements to code size and documentation.

Breaking Changes

• The implemented encoding of the system call return variant "Success with u32 and u64" has been changed to match the specification of TRD 104. Accordingly, the name of the SyscallReturnVariant enum variant has been changed from SuccessU64U32 to SuccessU32U64 (#3175).
• VirtualMuxAlarms now require the setup() function to be called in board set up code after they are created (#2866).

Noteworthy Changes

• Subscribe and allow operations are no longer handled by capsules themselves, but through the kernel's Grant logic itself (#2906). This change has multiple implications for users of Tock:
  • The Grant type accepts the number of read-only and read-write allow buffers, as well as the number of subscribe upcalls. It will reserve a fixed amount of space per Grant to store the respective allow and subscribe state. Thus, to make efficient use of Grant space, allow buffer and subscribe upcall numbers should be assigned in a non-sparse fashion.
  • Legal allow and subscribe calls can no longer be refused by a capsule. This implies that it is always possible for an application to cause the kernel to relinquish a previously shared buffer through an allow operation. Similarly, subscribe can now be used to infallibly ensure that a given upcall will not be scheduled by the kernel any longer, although already enqueued calls to a given upcall function can still be delivered even after a subscribe operation. The precise semantics around these system calls are described in TRD 104.
• Introduction of a new userspace-readable allow system call, where apps are explicitly allowed to read buffers shared with the kernel (defined in a draft TRD).
• Introduction of a read-only state mechanism to convey information to processes without explicit system calls (#2381).
• Improvements to kernel code size (e.g., #2836, #2849, #2759, #2823).

New HILs

• hasher
• public_key_crypto

New Platforms

• OpenTitan EarlGrey CW310
• Redboard Red-V B
• STM32F429I Discovery development board
• QEMU RISC-V 32-bit "virt" Platform

Deprecated Platforms

• OpenTitan EarlGrey NexysVideo

Known Issues

This release was tagged despite several known bugs in non-tier-1 boards, so as to avoid delaying the release. These include:

• Raspberry Pi Pico: process faults when running IPC examples: #3183
• The cortex-m exception handler does not correctly handle all possible exception entry cases. This is not known to currently manifest on any examples, but could with unlucky timing: #3109
• STM32F303 Discovery: adc app runs, but eventually hangs in the app (seems to be caught in the exit loop, but not sure why it gets there)
• STM32F303 Discovery: kernel panics lead to only a partial printout of the panic message before the board enters a reboot loop
• weact_f401ccu6: gpio example fails to generate interrupts on the input pin. This board is likely to be deprecated soon anyway, as it is no longer available for sale.

All Merged PRs

This is the first testing release for Tock 2.1!

Tock 2.1 represents a year of general improvements since our last release. It includes code size improvements, progress towards stable Rust, and numerous core kernel improvements, new chip drivers, new platforms, and bug fixes. Importantly, this release will be the first post-2.0 release which libtock-rs can soundly target, thanks to the additional guarantees provided in Tock 2.1 regarding allow-buffer swapping and callback-swapping. A full change list will be included with the final release notes.

This is the second major release of Tock! Tock 2.0 comes with a revamped system call interface with clarified semantics for how resources are shared between processes and the kernel. This is a breaking change from Tock 1.x and Tock 2.0 requires apps compiled for the new syscall interface.

System Call Interface Changes

• Two new system calls: AllowReadOnly and Exit. Allow has been renamed to AllowReadWrite.
• System calls can now return up to 4 registers of values to userspace. This flexibility introduces some additional restraints on capsule code, see https://github.com/tock/tock/blob/master/doc/Porting_v1_Capsules_to_v2.md for more details.
• Additional restrictions on how capsules implement Subscribe and Allow, with some in-kernel checks of these restrictions.

New Requirements in Tock 2.0

• All apps must include a TBF header specifying the minimum supported kernel version they require. By default, the process loader will check this header and refuse to load apps which are not explicitly compatible with 2.0.
• All capsules must store any process state in a Grant, and each capsule may only have up to one grant.

Other Major Changes

• The Chip and Platform traits in the kernel have been refactored. Chip now only includes functions that are tightly coupled with microcontrollers. Platform has been divided into separate, clearly defined traits.
• How boards configure the kernel has been clarified. All resources the kernel needs to operate for a specific board are specified in the KernelResources trait. This replaces the previous ad-hoc approach where some configuration was passed in as function arguments and others where in a trait. Additionally, individual boards can now choose to exclude chip peripherals which they do not use.
• The kernel crate has been reorganized. Kernel exports are more clearly structured, and use full module paths by default. Inside the kernel crate, related files are namespaced as feature_X.rs, such as process_standard.rs and process_utilities.rs.
• The process console now is able to print memory maps.

New Platforms

• Nano RP2040 Connect
• Clue nRF52840
• BBC Micro:bit v2
• WeAct F401CCU6 Core Board
• i.MX RT 1052 Evaluation Kit
• Teensy 4.0
• Pico Explorer Base
• Rapsberry Pi Pico
• LiteX on Digilent Arty A-7
• Verilated LiteX simulation
• ESP32-C3-DevKitM-1

New HILs

• key/value store
• 8080 bus (for LCDs)
• text screen
• screen
• touch

All Merged PRs

This is the second testing candidate for Tock 2.0. This includes a few fixes from rc1:

• Fix for stack pointer check in cortex-m/syscalls
• Updates to process console
• Fix in priority scheduler
• Improvement to CDC stack for nano33ble
• HTS221 fix
• Other minor fixes

This is the first testing release for Tock 2.0!

Tock 2.0 represents over a year of work towards a revised system call interface for the Tock kernel. It also includes numerous core kernel improvements, new chip drivers, new platforms, and bug fixes. A full change list will be included with the final release notes.

If you are looking to update any out-of-tree code to 2.0 there is a porting guide.

The 1.6 release of Tock includes numerous improves as we work towards the 2.0 release of Tock. Tock 2.0 will include breaking syscall changes, and before those changes we wanted to ensure the changes over the last couple months made their way into a 1.x release. So here it is!

Tock Has a Scheduler!

The major change in this release is in PR #1767 which added a Scheduler trait allowing Tock to cleanly support different schedulers. That PR also included four different schedulers that boards can choose from when configuring the kernel.

New Platforms

As Tock continues to run on more and more hardware, 1.6 is no different. This release includes support for:

• msp432 (#1911)
• Apollo3 (#1857)
• Arduino Nano 33 BLE (#1909)
• HiFive1 rev B (#1847)

Internal Interface Refactors

Tock's HIL interfaces go through periodic re-designs as bugs come up and new hardware platforms expose issues or oversights. The time.rs HIL (alarms and timers) saw the major update in 1.6 (#2089).

Non-PIC Userspace Tooling Support

While Tock was originally designed for userspace processes to be compiled with PIC (meaning they can be executed at any address), both LLVM and RISC-V do not (yet?) support the PIC mode that Tock requires. While we wait, we use statically compiled TBF apps, and the tooling and kernel support for apps compiled for fixed addresses has improved significantly (#1845, #1928, #1930).

USB Stack Improvements

There has been some renewed interest in USB stack developments, and 1.6 includes support for UART over USB (using CDC-ACM) (#1902), as well as USB support on OpenTitan (#1846).

Changes Since RC1

Release testing exposed a few minor bugs and configuration mishaps. There were a couple MPU changes between RC1 and the release, however. First, when restarting apps the MPU is correctly reconfigured. Second, the RISC-V PMP restricts access to the grant region now.

Many Other Updates!

Of course those are just some highlights of development since 1.5. There have been a whole host of improvements:

The 1.6 release of Tock includes numerous improves as we work towards the 2.0 release of Tock. Tock 2.0 will include breaking syscall changes, and before those changes we wanted to ensure the changes over the last couple months made their way into a 1.x release. So here it is!

Tock Has a Scheduler!

The major change in this release is in PR #1767 which added a Scheduler trait allowing Tock to cleanly support different schedulers. That PR also included four different schedulers that boards can choose from when configuring the kernel.

New Platforms

As Tock continues to run on more and more hardware, 1.6 is no different. This release includes support for:

• msp432 (#1911)
• Apollo3 (#1857)
• Arduino Nano 33 BLE (#1909)
• HiFive1 rev B (#1847)

Internal Interface Refactors

Tock's HIL interfaces go through periodic re-designs as bugs come up and new hardware platforms expose issues or oversights. The time.rs HIL (alarms and timers) saw the major update in 1.6 (#2089).

Non-PIC Userspace Tooling Support

While Tock was originally designed for userspace processes to be compiled with PIC (meaning they can be executed at any address), both LLVM and RISC-V do not (yet?) support the PIC mode that Tock requires. While we wait, we use statically compiled TBF apps, and the tooling and kernel support for apps compiled for fixed addresses has improved significantly (#1845, #1928, #1930).

USB Stack Improvements

There has been some renewed interest in USB stack developments, and 1.6 includes support for UART over USB (using CDC-ACM) (#1902), as well as USB support on OpenTitan (#1846).

Many Other Updates!

Of course those are just some highlights of development since 1.5. There have been a whole host of improvements:

• #2116: chips: e310: improve interrupt handling
• #2134: riscv mtimer: don't directly modify interrupt enables
• #2136: doc: OurOfTree.md typo conneciton -> connection
• #1963: deprecate launchxl, cc26x2
• #2133: chips/earlgrey: Use the peripheral clock frequency
• #2091: Nano33 apds9960
• #2127: Create core-notes-2020-09-25.md
• #2128: opentitan: Disable USB support by default
• #2129: fix rustdoc CI, force bash for Makefile.common
• #2126: Earlgrey: dont call debug in interrupt top half
• #2117: Fix kernel work counting when processes are stopped or faulted
• #2089: Time redesign v3
• #2047: Virtual ADC support
• #2119: Add Tock core WG notes for 2020-09-18.
• #2120: arch/cortex-m3: Allow the kernel to access protected memory
• #2121: capsules: hmac: Replace the digest buffer after completion
• #1873: PMP and MPU Improvements
• #2107: Scheduler timer bugfix + documentation updates
• #1973: Remove reborrows?
• #2104: opentitan: Makefile: Use riscv64-elf-objcopy to prepare images
• #2053: Add utilities for allocating dynamic grants.
• #2083: Stm32f3: add flash support
• #2101: RFC: Remove AppPtr::Drop() and Owned::Drop()
• #2103: OpenTitan: A collection of USB fixes
• #2114: STM32 Readme Fix
• #2105: Core WG notes for September 11
• #2109: Core WG notes for 2020-09-04
• #2110: Makefile: Bump the OpenTitan ROM file
• #2092: arch/cortex-m: change a few llvm_asm!s to asm!s
• #2102: Add links to out-of-tree boards to boards/README.md.
• #2073: RISC-V: Update panic debug print
• #2080: OpenTitan: Add support for detecting the USB device
• #2100: Mask USB interrupt to avoid hardware bug in OpenTitan
• #2082: capsules: usb/cdc: Fixup the CDC control message logic
• #2090: Make .storage alignment configurable
• #2098: Kernel work increment/decrement prevents MCU going to sleep
• #2077: Add TakeCell::get_mut function
• #2085: Allow creating a Spi Peripheral
• #2095: Update tock-registers README.md
• #2086: MLFQ scheduler bug fix
• #2066: Msp432: DMA-support
• #2088: Core notes for August 28th
• #2087: opentitan: README: Update the OpenTitan minimum version SHA
• #2027: Remove duplicated code in cortex-m crates
• #2074: Add ability to get full address bytes & address type to nrf52 Ficr
• #2081: MSP432: Change SMCLK from 750kHz to 1.5MHz
• #2075: Create core-notes-2020-08-14.md
• #2076: rv32: pmp: Fix bounds
• #2060: Ft6x06 touch status fix and impoved report efficency
• #2071: Update tock-registers doc to fix mistake
• #2064: pmp: add PMP struct
• #2072: Makefile: Update the OpenTitan ROM download location
• #2070: core wg notes august 7
• #2068: schedulers: store references to slots in processes array instead of AppIds
• #1928: kernel: process: try to use memory fixed address
• #2067: Msp432: Platform fixes
• #2062: kernel: sched: add and update comments
• #2045: rt0: Convert uses of u32 to usize
• #2061: core notes july 31
• #2022: kernel: process: use slice for app memory
• #2065: hifive1: Document required revb parameter for qemu
• #2038: arch/rv32i: pmp: Make the PMP struct as long as required
• #1942: Console: Check for receive length just in case
• #2043: cortex-m: fix warning about volatile keyword in incorrect position
• #2059: kernel: return correct time used
• #2054: fix bug in round robin scheduling logic
• #2050: Boards: RISC-V: Update the QEMU README
• #2048: kernel: sched: priority: invert logic
• #1767: Scheduler trait + transition all boards to round robin scheduler
• #2010: Remove OptionalCell's dependency on feature(const_fn) using impl<T: Copy>
• #2032: riscv: check for stack overflow
• #1911: New Platform: Msp432
• #1986: Touch Panel HIL and ft6x06 driver
• #2001: boards: Make .app section default, do not include it in kernel binary
• #2015: tock-registers: use UnsafeCell in writeable registers
• #2021: arch/rv32i: Don't sort PMP regions when we configure the MPU
• #2024: Makefile: Don't run the setup commands inside bash
• #2035: OpenTitan: USB support cleanup
• #1994: kernel: expose APIs for external ProcessTypes
• #2026: boards: nrf52840dk: add flash-openocd
• #2029: tools: fix update rust script
• #1965: hil: gpio: remove 'static
• #2002: cortex-m: Detect stack overflow
• #2033: sifive: uart: make sure tx enabled
• #2014: docs: porting: add new platform checklist
• #2011: Makefile: Split QEMU build to a seperate directory
• #2031: Notes from Core WG call, July 17
• #2020: arch/rv32i: Reduce PMP stack usage
• #2019: riscv: pmp: disable all entries
• #1741: boards/opentitan: Build OpenTitan with target device specific parameters
• #2004: Adding ADC support for stm323f4xx
• #2000: Adding ADC support for stm323f303xc
• #1887: sched: Add a watchdog
• #1991: boards: make: quiet sha256sum from cargo
• #2025: kernel::hil: time: fixed wrong implementation of is_oneshot()
• #1985: Update Systick trait, implement it for e310x and ibex
• #2013: Add Core Meeting Notes of 2020-07-10
• #2017: Makefile: Bump the OpenTitan boot ROM
• #1930: kernel: process: omit debug addrs for fixed apps
• #2008: riscv: remove old feature
• #1971: Use mainline QEMU
• #2003: kernel: grant: do not pass T::default()
• #1988: chips: apollo3: Allow a few tries to set the stimer
• #1980: doc: ot: notes: June meetings
• #1989: chips: apollo3: Enable the I and D cache
• #1997: chip: rename Ibex to EarlGrey
• #1999: add core notes 2020-07-03
• #1996: Core working group notes, June 26
• #1987: Added support for external clock source and systick user-defined clock value for ARM
• #1978: Makefile: Fix the temp directory creation when cloning OT ROM
• #1961: Create core-notes-2020-06-19.md
• #1992: doc: remove allow(unused_doc_comments)
• #1981: LowRISC: Initial commit of Pad Controller
• #1962: Use linker file to create APP_MEMORY slice.
• #1916: Added STM32F412G Discovery kit
• #1983: USB: CDC: Allow boards to specify vendor id, product id, and strings.
• #1982: Correct memop documentation
• #1975: rv32i: Add support for 64 PMP regions
• #1967: Makefile.common: use system sha256sum if available
• #1917: hil: ble_advertising: Pass the transmit buffer on callback
• #1934: Initial support for Apollo3 BLE
• #1933: Bind AppSlice to app instance (AppId), fixes #1914
• #1979: add --strip-sections to objcopy flags
• #1943: kernel: TBF parsing: match the threat model
• #1951: ci: run miri where we can
• #1974: tools: pick toolchain that has all our components
• #1909: Add Nano 33 BLE Board
• #1970: rv32i: add Display trait for PMPRegion/Config
• #1969: Fix PMP use for RISC-V
• #1968: Stm32f4 I2C HAL
• #1964: hil: remove 'static from ble_advertising
• #1889: Apollo3: Add an alarm
• #1896: apollo3: uart: Fix the UART callback
• #1926: Prepare for 64 PMP config registers
• #1949: CDC: Wait for CDC messages, add delay to nRF USB RESET
• #1959: HIL: remove 'static from sensors
• #1957: Remove core_intrinsics offset feature
• #1955: kernel: remove panic_info_message feature
• #1956: CRC HIL: make lifetime 'a, not 'static
• #1958: Remove core::intrinsics::math
• #1960: Increase delay in Segger RTT debugging (fix #1697).
• #1907: nrf52: usb: handle control OUT transfer
• #1837: Frame buffer HIL and ST7735 screen support
• #1946: Add USB CDC Component, Move set_client() to USB HIL
• #1952: components: Add debug writer that doesn't use a UART mux
• #1950: remove all uses of lang_items unstable feature
• #1939: Make the Field::mask and FieldValue::mask fields private.
• #1947: nrf52: usb: better check state on IN resume
• #1945: nrf52: usb: do not print debug!() info on startup
• #1929: add core notes 2020-06-12
• #1902: USB: Add CDC support, update capsule stack
• #1771: boards/Makefile.common: tool-chain customization
• #1935: Makefile: Update the OpenTitan boot ROM
• #1927: Many updates to comments in capsules/
• #1936: ci: Add missing echo suppress
• #1925: Add support for the MLX90614 IR Temperature Sensor
• #1882: chips: ibex: Enable low power state
• #1910: Add meeting notes
• #1919: Core working group notes from June 05
• #1897: Apollo3: Add support for the I2C device
• #1892: Remove nrf52dk_base, initialize nordic b...