Merge pull request tock#3910 from tock/capsules-readme

Capsules: update readme with new capsules

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.

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.
 //!

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,18 +35,21 @@ 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.
 - **[TSL2561](src/tsl2561.rs)**: Light sensor.
 
 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

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.

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.")