Many updates to comments in capsules/

Makefile

@@ -414,6 +414,8 @@ ci-job-archs:
 ci-job-kernel:
 	$(call banner,CI-Job: Kernel)
 	@cd kernel && CI=true RUSTFLAGS="-D warnings" TOCK_KERNEL_VERSION=ci_test cargo test
+	# Capsule initialization depends on board/chip specific imports, so ignore doc tests
+	@cd capsules && CI=true RUSTFLAGS="-D warnings" TOCK_KERNEL_VERSION=ci_test cargo test --lib
 
 .PHONY: ci-job-chips
 ci-job-chips:

capsules/examples/traitobj_list.rs

@@ -16,22 +16,26 @@
 //! manager.report();
 //! ```
 
+// Dummy main function for this example to compile with `cargo test`.
+fn main() {}
+
 use kernel::common::list::{List, ListLink, ListNode};
+use kernel::debug;
 
-pub trait Funky<'a> {
+pub trait Funky<'a>: 'a {
     fn name(&self) -> &'static str;
-    fn next_funky_thing(&'a self) -> &'a ListLink<'a, Funky<'a>>;
+    fn next_funky_thing(&'a self) -> &'a ListLink<'a, dyn Funky<'a>>;
 }
 
-impl<'a> ListNode<'a, Funky<'a>> for Funky<'a> {
-    fn next(&'a self) -> &'a ListLink<'a, Funky<'a>> {
+impl<'a> ListNode<'a, dyn Funky<'a>> for dyn Funky<'a> {
+    fn next(&'a self) -> &'a ListLink<'a, dyn Funky<'a>> {
         &self.next_funky_thing()
     }
 }
 
 // A manager holds a list of funky things
 pub struct Manager<'a> {
-    funky_things: List<'a, Funky<'a>>,
+    funky_things: List<'a, dyn Funky<'a>>,
 }
 
 impl<'a> Manager<'a> {
@@ -41,7 +45,7 @@ impl<'a> Manager<'a> {
         }
     }
 
-    pub fn manage(&mut self, thing: &'a (Funky<'a>)) {
+    pub fn manage(&mut self, thing: &'a (dyn Funky<'a>)) {
         self.funky_things.push_head(thing);
     }
 
@@ -54,7 +58,7 @@ impl<'a> Manager<'a> {
 
 // Jazz is a funky thing
 pub struct Jazz<'a> {
-    next: ListLink<'a, Funky<'a>>,
+    next: ListLink<'a, dyn Funky<'a>>,
 }
 
 impl<'a> Jazz<'a> {
@@ -70,14 +74,14 @@ impl<'a> Funky<'a> for Jazz<'a> {
         "Jazz"
     }
 
-    fn next_funky_thing(&'a self) -> &'a ListLink<'a, Funky<'a>> {
+    fn next_funky_thing(&'a self) -> &'a ListLink<'a, dyn Funky<'a>> {
         &self.next
     }
 }
 
 // Cheese is a funky thing
 pub struct Cheese<'a> {
-    next: ListLink<'a, Funky<'a>>,
+    next: ListLink<'a, dyn Funky<'a>>,
 }
 
 impl<'a> Cheese<'a> {
@@ -92,7 +96,7 @@ impl<'a> Funky<'a> for Cheese<'a> {
     fn name(&self) -> &'static str {
         "Cheese"
     }
-    fn next_funky_thing(&'a self) -> &'a ListLink<'a, Funky<'a>> {
+    fn next_funky_thing(&'a self) -> &'a ListLink<'a, dyn Funky<'a>> {
         &self.next
     }
 }

capsules/src/adc.rs

@@ -4,7 +4,9 @@
 //! Usage
 //! -----
 //!
-//! ```
+//! ```rust
+//! # use kernel::static_init;
+//!
 //! let adc_channels = static_init!(
 //!     [&'static sam4l::adc::AdcChannel; 6],
 //!     [

capsules/src/aes_ccm.rs

@@ -39,7 +39,10 @@
 //! Usage
 //! -----
 //!
-//! ```
+//! ```rust
+//! # use kernel::static_init;
+//! # use kernel::hil::symmetric_encryption;
+//!
 //! const CRYPT_SIZE: usize = 3 * symmetric_encryption::AES128_BLOCK_SIZE + radio::MAX_BUF_SIZE;
 //! static mut CRYPT_BUF: [u8; CRYPT_SIZE] = [0x00; CRYPT_SIZE];
 //!

capsules/src/ambient_light.rs

@@ -3,10 +3,12 @@
 //! You need a device that provides the `hil::sensors::AmbientLight` trait.
 //!
 //! ```rust
+//! # use kernel::{hil, static_init};
+//!
 //! let light = static_init!(
-//!     capsules::sensors::AmbientLight<'static>,
-//!     capsules::sensors::AmbientLight::new(isl29035,
-//!         kernel::Grant::create()));
+//!     capsules::ambient_light::AmbientLight<'static>,
+//!     capsules::ambient_light::AmbientLight::new(isl29035,
+//!         board_kernel.create_grant(&grant_cap)));
 //! hil::sensors::AmbientLight::set_client(isl29035, ambient_light);
 //! ```
 

capsules/src/analog_comparator.rs

@@ -3,7 +3,9 @@
 //! Usage
 //! -----
 //!
-//! ```
+//! ```rust
+//! # use kernel::static_init;
+//!
 //! let ac_channels = static_init!(
 //!     [&'static sam4l::acifc::AcChannel; 2],
 //!     [

capsules/src/app_flash_driver.rs

@@ -13,11 +13,13 @@
 //! -----
 //!
 //! ```
+//! # use kernel::static_init;
+//!
 //! pub static mut APP_FLASH_BUFFER: [u8; 512] = [0; 512];
 //! let app_flash = static_init!(
 //!     capsules::app_flash_driver::AppFlash<'static>,
 //!     capsules::app_flash_driver::AppFlash::new(nv_to_page,
-//!         kernel::Grant::create(), &mut APP_FLASH_BUFFER));
+//!         board_kernel.create_grant(&grant_cap), &mut APP_FLASH_BUFFER));
 //! ```
 
 use core::cmp;

capsules/src/ble_advertising_driver.rs

@@ -63,19 +63,24 @@
 //! timer to perform events and not block the entire kernel
 //!
 //! ```rust
-//!     let ble_radio = static_init!(
-//!     nrf5x::ble_advertising_driver::BLE
-//!     <'static, nrf52::radio::Radio, VirtualMuxAlarm<'static, Rtc>>,
-//!     nrf5x::ble_advertising_driver::BLE::new(
-//!         &mut nrf52::radio::RADIO,
-//!     kernel::Grant::create(),
-//!         &mut nrf5x::ble_advertising_driver::BUF,
-//!         ble_radio_virtual_alarm));
-//!    nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_rx_client(&nrf52::radio::RADIO,
-//!                                                                      ble_radio);
-//!    nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_tx_client(&nrf52::radio::RADIO,
-//!                                                                      ble_radio);
-//!    ble_radio_virtual_alarm.set_client(ble_radio);
+//! # use kernel::static_init;
+//! # use capsules::virtual_alarm::VirtualMuxAlarm;
+//!
+//! let ble_radio = static_init!(
+//! nrf5x::ble_advertising_driver::BLE<
+//!     'static,
+//!     nrf52::radio::Radio, VirtualMuxAlarm<'static, Rtc>
+//! >,
+//! nrf5x::ble_advertising_driver::BLE::new(
+//!     &mut nrf52::radio::RADIO,
+//!     board_kernel.create_grant(&grant_cap),
+//!     &mut nrf5x::ble_advertising_driver::BUF,
+//!     ble_radio_virtual_alarm));
+//! nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_rx_client(&nrf52::radio::RADIO,
+//!                                                                   ble_radio);
+//! nrf5x::ble_advertising_hil::BleAdvertisementDriver::set_tx_client(&nrf52::radio::RADIO,
+//!                                                                   ble_radio);
+//! ble_radio_virtual_alarm.set_client(ble_radio);
 //! ```
 //!
 //! ### Authors

capsules/src/button.rs

@@ -8,12 +8,14 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let button_pins = static_init!(
 //!     [&'static sam4l::gpio::GPIOPin; 1],
 //!     [&sam4l::gpio::PA[16]]);
 //! let button = static_init!(
-//!     capsules::button::Button<'static, sam4l::gpio::GPIOPin>,
-//!     capsules::button::Button::new(button_pins, kernel::Grant::create()));
+//!     capsules::button::Button<'static>,
+//!     capsules::button::Button::new(button_pins, board_kernel.create_grant(&grant_cap)));
 //! for btn in button_pins.iter() {
 //!     btn.set_client(button);
 //! }

capsules/src/buzzer_driver.rs

@@ -11,7 +11,9 @@
 //! Usage
 //! -----
 //!
-//! ```
+//! ```rust
+//! # use kernel::static_init;
+//!
 //! let virtual_pwm_buzzer = static_init!(
 //!     capsules::virtual_pwm::PwmPinUser<'static, nrf52::pwm::Pwm>,
 //!     capsules::virtual_pwm::PwmPinUser::new(mux_pwm, nrf5x::pinmux::Pinmux::new(31))
@@ -31,7 +33,7 @@
 //!         virtual_pwm_buzzer,
 //!         virtual_alarm_buzzer,
 //!         capsules::buzzer_driver::DEFAULT_MAX_BUZZ_TIME_MS,
-//!         kernel::Grant::create())
+//!         board_kernel.create_grant(&grant_cap))
 //! );
 //! virtual_alarm_buzzer.set_client(buzzer);
 //! ```

capsules/src/console.rs

@@ -6,13 +6,16 @@
 //! You need a device that provides the `hil::uart::UART` trait.
 //!
 //! ```rust
+//! # use kernel::static_init;
+//! # use capsules::console::Console;
+//!
 //! let console = static_init!(
 //!     Console<usart::USART>,
 //!     Console::new(&usart::USART0,
 //!                  115200,
 //!                  &mut console::WRITE_BUF,
 //!                  &mut console::READ_BUF,
-//!                  kernel::Grant::create()));
+//!                  board_kernel.create_grant(&grant_cap)));
 //! hil::uart::UART::set_client(&usart::USART0, console);
 //! ```
 //!

capsules/src/crc.rs

@@ -8,9 +8,11 @@
 //! driver:
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let crc = static_init!(
 //!     capsules::crc::Crc<'static, sam4l::crccu::Crccu<'static>>,
-//!     capsules::crc::Crc::new(&mut sam4l::crccu::CRCCU, kernel::Grant::create()));
+//!     capsules::crc::Crc::new(&mut sam4l::crccu::CRCCU, board_kernel.create_grant(&grant_cap)));
 //! sam4l::crccu::CRCCU.set_client(crc);
 //!
 //! ```
@@ -103,9 +105,8 @@ impl<'a, C: hil::crc::CRC> Crc<'a, C> {
     ///
     /// ## Example
     ///
-    /// ```
-    /// capsules::crc::Crc::new(&sam4l::crccu::CRCCU, kernel::Grant::create()),
-    ///
+    /// ```rust
+    /// capsules::crc::Crc::new(&sam4l::crccu::CRCCU, board_kernel.create_grant(&grant_cap));
     /// ```
     ///
     pub fn new(crc_unit: &'a C, apps: Grant<App>) -> Crc<'a, C> {
@@ -194,7 +195,9 @@ impl<C: hil::crc::CRC> Driver for Crc<'_, C> {
     /// result of a CRC computation.  The signature of the callback is
     ///
     /// ```
-    /// fn callback(status, result);
+    /// # use kernel::ReturnCode;
+    ///
+    /// fn callback(status: ReturnCode, result: usize) {}
     /// ```
     ///
     /// where

capsules/src/dac.rs

@@ -4,6 +4,8 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let dac = static_init!(
 //!     capsules::dac::Dac<'static>,
 //!     capsules::dac::Dac::new(&mut sam4l::dac::DAC));

capsules/src/debug_process_restart.rs

@@ -7,6 +7,8 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::{capabilities, static_init};
+//!
 //! struct ProcessMgmtCap;
 //! unsafe impl capabilities::ProcessManagementCapability for ProcessMgmtCap {}
 //! let debug_process_restart = static_init!(

capsules/src/fm25cl.rs

@@ -15,6 +15,8 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! // Create a SPI device for this chip.
 //! let fm25cl_spi = static_init!(
 //!     capsules::virtual_spi::VirtualSpiMasterDevice<'static, usart::USART>,

capsules/src/fxos8700cq.rs

@@ -9,6 +9,8 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let fxos8700_i2c = static_init!(I2CDevice, I2CDevice::new(i2c_bus, 0x1e));
 //! let fxos8700 = static_init!(
 //!     capsules::fxos8700cq::Fxos8700cq<'static>,

capsules/src/gpio.rs

@@ -12,6 +12,8 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let gpio_pins = static_init!(
 //!     [Option<&'static sam4l::gpio::GPIOPin>; 4],
 //!     [Option<&sam4l::gpio::PB[14]>,

capsules/src/gpio_async.rs

@@ -8,13 +8,15 @@
 //! -----
 //!
 //! ```rust
-//! Generate a list of ports to group into one userspace driver.
+//! # use kernel::static_init;
+//!
+//! // Generate a list of ports to group into one userspace driver.
 //! let async_gpio_ports = static_init!(
-//!     [&'static capsules::mcp23008::MCP23008; 1],
+//!     [&'static capsules::mcp230xx::MCP230xx; 1],
 //!     [mcp23008]);
 //!
 //! let gpio_async = static_init!(
-//!     capsules::gpio_async::GPIOAsync<'static, capsules::mcp23008::MCP23008<'static>>,
+//!     capsules::gpio_async::GPIOAsync<'static, capsules::mcp230xx::MCP230xx<'static>>,
 //!     capsules::gpio_async::GPIOAsync::new(async_gpio_ports));
 //!
 //! // Setup the clients correctly.

capsules/src/humidity.rs

@@ -39,10 +39,12 @@
 //! You need a device that provides the `hil::sensors::HumidityDriver` trait.
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let humidity = static_init!(
 //!        capsules::humidity::HumiditySensor<'static>,
 //!        capsules::humidity::HumiditySensor::new(si7021,
-//!                                                kernel::Grant::create()));
+//!                                                board_kernel.create_grant(&grant_cap)));
 //! kernel::hil::sensors::HumidityDriver::set_client(si7021, humidity);
 //! ```
 

capsules/src/ieee802154/framer.rs

@@ -54,9 +54,11 @@
 //! 802.15.4 frames:
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! let radio_capsule = static_init!(
 //!     capsules::ieee802154::RadioDriver<'static>,
-//!     capsules::ieee802154::RadioDriver::new(mac_device, kernel::Grant::create(), &mut RADIO_BUF));
+//!     capsules::ieee802154::RadioDriver::new(mac_device, board_kernel.create_grant(&grant_cap), &mut RADIO_BUF));
 //! mac_device.set_key_procedure(radio_capsule);
 //! mac_device.set_device_procedure(radio_capsule);
 //! mac_device.set_transmit_client(radio_capsule);

capsules/src/ieee802154/virtual_mac.rs

@@ -12,6 +12,8 @@
 //! -----
 //!
 //! ```
+//! # use kernel::static_init;
+//!
 //! // Create the mux.
 //! let mux_mac = static_init!(
 //!     capsules::ieee802154::virtual_mac::MuxMac<'static>,

capsules/src/ieee802154/xmac.rs

@@ -33,6 +33,8 @@
 //! necessary modifications to the board configuration are shown below for `imix`s:
 //!
 //! ```rust
+//! # use kernel::static_init;
+//!
 //! // main.rs
 //!
 //! use capsules::ieee802154::mac::Mac;

capsules/src/isl29035.rs

@@ -13,6 +13,9 @@
 //! -----
 //!
 //! ```rust
+//! # use kernel::static_init;
+//! # use capsules::virtual_alarm::VirtualMuxAlarm;
+//!
 //! let isl29035_i2c = static_init!(I2CDevice, I2CDevice::new(i2c_bus, 0x44));
 //! let isl29035_virtual_alarm = static_init!(
 //!     VirtualMuxAlarm<'static, sam4l::ast::Ast>,