diff --git a/capsules/core/README.md b/capsules/core/README.md index 313d4aa618..a632da6954 100644 --- a/capsules/core/README.md +++ b/capsules/core/README.md @@ -25,8 +25,10 @@ These capsules provide a `Driver` interface for common MCU peripherals. - **[Alarm](src/alarm.rs)**: Oneshot and periodic timers. - **[GPIO](src/gpio.rs)**: GPIO configuring and control. - **[I2C_MASTER](src/i2c_master.rs)**: I2C master access only. -- **[I2C_MASTER_SLAVE](src/i2c_master_slave_driver.rs)**: I2C master and slave +- **[I2C_MASTER_SLAVE](src/i2c_master_slave_combo.rs)**: I2C master and slave access. +- **[I2C_MASTER_SLAVE Driver](src/i2c_master_slave_driver.rs)**: I2C master and + slave userspace access. - **[RNG](src/rng.rs)**: Random number generation. - **[SPI Controller](src/spi_controller.rs)**: SPI controller device (SPI master) @@ -39,6 +41,8 @@ These provide common and better abstractions for userspace. - **[Button](src/button.rs)**: Detect button presses. - **[Console](src/console.rs)**: UART console support. +- **[Console Ordered](src/console_ordered.rs)**: UART console ordered with + kernel `debug!()` prints. - **[LED](src/led.rs)**: Turn on and off LEDs. Debugging Capsules @@ -47,7 +51,7 @@ Debugging Capsules These are selectively included on a board to help with testing and debugging various elements of Tock. -- **[Low-Level Debug](src/low_level_debug/mod.rs)**: Provides system calls for +- **[Low-Level Debug](src/low_level_debug)**: Provides system calls for low-level debugging tasks, such as debugging toolchain and relocation issues. - **[Process Console](src/process_console.rs)**: Provide a UART console to inspect the status of process and stop/start them. @@ -60,13 +64,10 @@ These allow for multiple users of shared hardware resources in the kernel. - **[Virtual ADC](src/virtualizers/virtual_adc.rs)**: Shared single ADC channel. - **[Virtual AES-CCM](src/virtualizers/virtual_aes_ccm.rs)**: Shared AES-CCM engine. - **[Virtual Alarm](src/virtualizers/virtual_alarm.rs)**: Shared alarm resource. -- **[Virtual Digest](src/virtualizers/virtual_digest.rs)**: Shared digest resource. - **[Virtual Flash](src/virtualizers/virtual_flash.rs)**: Shared flash resource. -- **[Virtual HMAC](src/virtualizers/virtual_hmac.rs)**: Shared HMAC resource. - **[Virtual I2C](src/virtualizers/virtual_i2c.rs)**: Shared I2C and fixed addresses. - **[Virtual PWM](src/virtualizers/virtual_pwm.rs)**: Shared PWM hardware. - **[Virtual RNG](src/virtualizers/virtual_rng.rs)**: Shared random number generator. -- **[Virtual SHA](src/virtualizers/virtual_sha.rs)**: Shared SHA hashes. - **[Virtual SPI](src/virtualizers/virtual_spi.rs)**: Shared SPI and fixed chip select pins. - **[Virtual Timer](src/virtualizers/virtual_timer.rs)**: Shared timer. - **[Virtual UART](src/virtualizers/virtual_uart.rs)**: Shared UART bus. diff --git a/capsules/core/src/i2c_master_slave_combo.rs b/capsules/core/src/i2c_master_slave_combo.rs index b5180b1f9a..0f787b5ab6 100644 --- a/capsules/core/src/i2c_master_slave_combo.rs +++ b/capsules/core/src/i2c_master_slave_combo.rs @@ -4,7 +4,7 @@ //! Combines two hardware devices into a single I2C master/slave device. //! -//! If a chip provides a seperate hardware implementation for a I2C master and +//! If a chip provides a separate hardware implementation for a I2C master and //! slave device, like the Apollo3 for example, this capsule can be used to //! combine them into a single `I2CMasterSlave` compatible implementation. //! diff --git a/capsules/extra/README.md b/capsules/extra/README.md index 328e7590a4..42582b8eb0 100644 --- a/capsules/extra/README.md +++ b/capsules/extra/README.md @@ -19,9 +19,11 @@ These implement a driver to setup and read various physical sensors. - **[Analog Sensors](src/analog_sensor.rs)**: Single ADC pin sensors. - **[APDS9960](src/apds9960.rs)**: Proximity sensor. - **[BME280](src/bme280.rs)**: Humidity and air pressure sensor. +- **[BMM150](src/bmm150.rs)**: Geomagnetic sensor. - **[BMP280](src/bmp280.rs)**: Temperature (and air pressure) sensor. - **[CCS811](src/ccs811.rs)**: VOC gas sensor. - **[FXOS8700CQ](src/fxos8700cq.rs)**: Accelerometer and magnetometer. +- **[HS3003](src/hs3003.rs)**: Temperature and humidity sensor. - **[HTS221](src/hts221.rs)**: Temperature and humidity sensor. - **[ISL29035](src/isl29035.rs)**: Light sensor. - **[L3GD20](src/l3gd20.rs)**: MEMS 3 axys digital gyroscope and temperature @@ -33,11 +35,13 @@ These implement a driver to setup and read various physical sensors. sensor. - **[LSM6DSOXTR](src/lsm6dsoxtr.rs)**: 3D accelerometer and 3D magnetometer sensor. +- **[LPS22HB](src/lps22hb.rs)**: Pressure sensor. - **[LPS25HB](src/lps25hb.rs)**: Pressure sensor. - **[MLX90614](src/mlx90614.rs)**: Infrared temperature sensor. - **[RP2040 Temperature](src/temperature_rp2040.rs)**: Analog RP2040 temperature sensor. -- **[SHT3x](src/sht3x.rs)**: SHT3x temperature and humidity sensor. +- **[SHT3x](src/sht3x.rs)**: Temperature and humidity sensor. +- **[SHT4x](src/sht4x.rs)**: Temperature and humidity sensor. - **[SI7021](src/si7021.rs)**: Temperature and humidity sensor. - **[STM32 Temperature](src/temperature_stm.rs)**: Analog STM32 temperature sensor. @@ -45,6 +49,7 @@ These implement a driver to setup and read various physical sensors. These drivers provide support for various ICs. +- **[AT24C32/64](src/at24c_eeprom.rs)**: EEPROM chip. - **[FM25CL](src/fm25cl.rs)**: FRAM chip. - **[FT6x06](src/ft6x06.rs)**: FT6x06 touch panel. - **[HD44780 LCD](src/hd44780.rs)**: HD44780 LCD screen. @@ -56,6 +61,7 @@ These drivers provide support for various ICs. - **[PCA9544A](src/pca9544a.rs)**: Multiple port I2C selector. - **[SD Card](src/sdcard.rs)**: Support for SD cards. - **[Seven Segment Display](src/seven_segment.rs)**: Seven segment displays. +- **[SSD1306](src/ssd1306.rs)**: SSD1306 OLED screen driver. - **[ST77xx](src/st77xx.rs)**: ST77xx IPS screen. @@ -72,6 +78,7 @@ Support for wireless radios. - **[LoRa Phy]**: Support for exposing Semtech devices to userspace See the lora_things_plus board for an example + Libraries --------- @@ -109,13 +116,17 @@ These provide common and better abstractions for userspace. - **[App Flash](src/app_flash_driver.rs)**: Allow applications to write their own flash. - **[Buzzer](src/buzzer_driver.rs)**: Simple buzzer. -- **[CTAP](src/ctap.rs)**: Client to Authenticator Protocol (CTAP) support. +- **[Date-Time](src/date_time.rs)**: Real time clock date/time support. +- **[HMAC](src/hmac.rs)**: Hash-based Message Authentication Code support. - **[Humidity](src/humidity.rs)**: Query humidity sensors. - **[Key-Value Store](src/kv_driver.rs)**: Store key-value data. - **[LED Matrix](src/led_matrix.rs)**: Control a 2D array of LEDs. +- **[Pressure](src/pressure.rs)**: Pressure sensors. - **[Proximity](src/proximity.rs)**: Proximity sensors. +- **[PWM](src/pwm.rs)**: Pulse-width modulation support. - **[Read Only State](src/read_only_state.rs)**: Read-only state sharing. - **[Screen](src/screen.rs)**: Displays and screens. +- **[Screen Shared](src/screen_shared.rs)**: App-specific screen windows. - **[SHA](src/sha.rs)**: SHA hashes. - **[Sound Pressure](src/sound_pressure.rs)**: Query sound pressure levels. - **[Temperature](src/temperature.rs)**: Query temperature sensors. @@ -142,17 +153,19 @@ Utility Capsules Other capsules that implement reusable logic. +- **[Bus Adapters](src/bus.rs)**: Generic abstraction for SPI/I2C/8080. +- **[Buzzer PWM](src/buzzer_pwm.rs)**: Buzzer with a PWM pin. +- **[HMAC-SHA256](src/hmac_sha256.rs)**: HMAC using SHA-256. +- **[Key-Value Store with Permissions](src/kv_store_permissions.rs)**: Key-value + interface that requires read/write permissions. +- **[Log Storage](src/log.rs)**: Log storage abstraction on flash devices. - **[Nonvolatile to Pages](src/nonvolatile_to_pages.rs)**: Map arbitrary reads and writes to flash pages. -- **[HMAC](src/hmac.rs)**: Hash-based Message Authentication Code (HMAC) digest - engine. -- **[Log Storage](src/log.rs)**: Log storage abstraction on top of flash - devices. -- **[Bus Adapters](src/bus.rs)**: Generic abstraction for SPI/I2C/8080. -- **[TicKV](src/tickv.rs)**: Key-value storage. -- **[Key-Value Store](src/kv_store.rs)**: Key-value virtualized interface. - **[SHA256](src/sha256.rs)**: SHA256 software hash. - **[SipHash](src/sip_hash.rs)**: SipHash software hash. +- **[TicKV](src/tickv.rs)**: Key-value storage. +- **[TicKV KV Store](src/tickv_kv_store.rs)**: Provide `hil::kv::KV` with TickV. +- **[Virtual KV](src/virtual_kv.rs)**: Virtualize access to KV with permissions. Debugging Capsules diff --git a/capsules/extra/src/at24c_eeprom.rs b/capsules/extra/src/at24c_eeprom.rs index c194273df7..8403d72bf0 100644 --- a/capsules/extra/src/at24c_eeprom.rs +++ b/capsules/extra/src/at24c_eeprom.rs @@ -11,7 +11,7 @@ //! > The AT24C32/64 provides 32,768/65,536 bits of serial electrically erasable and programmable //! > read only memory (EEPROM) organized as 4096/8192 words of 8 bits each. The device’s cascadable //! > feature allows up to 8 devices to share a common 2- wire bus. The device is optimized for use -//! > in many industrial and commercial applica- tions where low power and low voltage operation are +//! > in many industrial and commercial applications where low power and low voltage operation are //! > essential. The AT24C32/64 is available in space saving 8-pin JEDEC PDIP, 8-pin JEDEC SOIC, //! > 8-pin EIAJ SOIC, and 8-pin TSSOP (AT24C64) packages and is accessed via a 2-wire serial //! > interface. diff --git a/tools/check_capsule_readme.py b/tools/check_capsule_readme.py index 085e0ea95a..a5a5a5fdc2 100755 --- a/tools/check_capsule_readme.py +++ b/tools/check_capsule_readme.py @@ -4,48 +4,83 @@ # SPDX-License-Identifier: Apache-2.0 OR MIT # Copyright Tock Contributors 2023. -''' +""" Check if all of the available capsules are documented in the README. -''' +""" import os import re +import sys -SKIP = ['/mod.rs', - 'src/lib.rs', - '/test', - 'src/driver.rs', - 'src/rf233_const.rs'] +SKIP = [ + "README.md", + "src/lib.rs", + "/test", + "src/rf233_const.rs", + "extra/src/tutorials", +] documented_capsules = [] implemented_capsules = [] -# Find all documented capsules -with open('capsules/README.md') as f: - for l in f: - items = re.findall(r".*\((src/.*?)\).*", l) - if len(items) > 0: - for item in items: - documented_capsules.append('capsules/{}'.format(item)) - - -# Find all capsule source files. -for subdir, dirs, files in os.walk(os.fsencode('capsules/src/')): - for file in files: - filepath = os.fsdecode(os.path.join(subdir, file)) - - # Get just the part after /src, effectively. - folders = filepath.split('/') - filepath = '/'.join(folders[0:3]) - - # Skip some noise. - for skip in SKIP: - if skip in filepath: - break - else: - implemented_capsules.append(filepath) +def parse_capsule_readme(readme_filename, documented_list): + root = "/".join(readme_filename.split("/")[:-1]) + + # Find all documented capsules + with open(readme_filename) as f: + for l in f: + items = re.findall(r".*\((src/.*?)\).*", l) + if len(items) > 0: + for item in items: + documented_capsules.append("{}/{}".format(root, item)) + + +def find_implemented_capsules(root_path, implemented_list): + # Find all capsule source files. + for subdir, dirs, files in os.walk(os.fsencode(root_path)): + for file in files: + filepath = os.fsdecode(os.path.join(subdir, file)) + + # Include the directory on behalf of `mod.rs` files. + if os.fsdecode(file) == "mod.rs": + # If we document any file in this folder, we must document them + # all. + document_within_this_folder = False + for doc_capsule in documented_capsules: + fp = os.fsdecode(subdir) + if doc_capsule.startswith(fp) and doc_capsule != fp: + document_within_this_folder = True + break + if document_within_this_folder: + # Skip the mod.rs + continue + else: + # Use the mod.rs as the entire folder + filepath = os.fsdecode(subdir) + + # Skip some noise. + for skip in SKIP: + if skip in filepath: + break + else: + # Skip files where the directory (e.g. extra/src/net) is + # documented. + for doc_capsule in documented_capsules: + if filepath.startswith(doc_capsule) and filepath != doc_capsule: + break + else: + implemented_list.append(filepath) + + +# Find links in readmes. +parse_capsule_readme("capsules/core/README.md", documented_capsules) +parse_capsule_readme("capsules/extra/README.md", documented_capsules) + +# Find actual files of capsules. +find_implemented_capsules("capsules/core/src", implemented_capsules) +find_implemented_capsules("capsules/extra/src", implemented_capsules) # Calculate what doesn't seem to be documented. missing = list(set(implemented_capsules) - set(documented_capsules)) @@ -54,12 +89,23 @@ removed = list(set(documented_capsules) - set(implemented_capsules)) -print('The following capsules do not seem to be documented:') -for m in sorted(missing): - print(' - {}'.format(m)) +if len(missing) > 0: + print("The following capsules do not seem to be documented:") + for m in sorted(missing): + print(" - {}".format(m)) + +if len(removed) > 0: + print("The following capsules seem to have been removed:") + for m in sorted(removed): + print(" - {}".format(m)) + +if len(missing) > 0: + print("ERROR: Capsules missing documentation") + sys.exit(-1) -print('The following capsules seem to have been removed:') -for m in sorted(removed): - print(' - {}'.format(m)) +if len(removed) > 0: + print("ERROR: Capsules documented that are missing") + sys.exit(-1) +print("Capsule documentation up to date.")