Updating docs.

Author: thejpster

src/main.rs

@@ -1,14 +1,15 @@
 #![no_main]
 #![no_std]
 
-use neotron_bmc as _;
-
-use neotron_bmc::monotonic::{Instant, Tim3Monotonic, U16Ext};
-
-use cortex_m_rt::exception;
-
+///! Neotron BMC Firmware
+///!
+///! This is the firmware for the Neotron Board Management Controller (BMC). It controls the power, reset, UART and PS/2 ports on a Neotron mainboard.
+///! For more details, see the `README.md` file.
+///!
+///! # Licence
+///! This source code as a whole is licensed under the GPL v3. Third-party crates are covered by their respective licences.
+use cortex_m::interrupt::free as disable_interrupts;
 use rtic::app;
-
 use stm32f0xx_hal::{
 	gpio::gpioa::{PA10, PA11, PA12, PA9},
 	gpio::gpiob::{PB0, PB1},
@@ -19,11 +20,16 @@ use stm32f0xx_hal::{
 	serial,
 };
 
-use cortex_m::interrupt::free as disable_interrupts;
+use neotron_bmc as _;
+use neotron_bmc::monotonic::{Instant, Tim3Monotonic, U16Ext};
 
+/// Version string auto-generated by git.
 static VERSION: &'static str = include_str!(concat!(env!("OUT_DIR"), "/version.txt"));
 
+/// At what rate do we blink the status LED when we're running?
 const LED_PERIOD_MS: u16 = 1000;
+
+/// How often we poll the power and reset buttons in milliseconds.
 const DEBOUNCE_POLL_INTERVAL_MS: u16 = 75;
 
 /// The states we can be in controlling the DC power
@@ -63,6 +69,12 @@ const APP: () = {
 		dc_power_enabled: DcPowerState,
 	}
 
+	/// The entry point to our application.
+	///
+	/// Sets up the hardware and spawns the regular tasks.
+	///
+	/// * Task `led_status_blink` - blinks the LED
+	/// * Task `button_poll` - checks the power and reset buttons
 	#[init(spawn = [led_status_blink, button_poll])]
 	fn init(ctx: init::Context) -> init::LateResources {
 		defmt::info!("Neotron BMC version {:?} booting", VERSION);
@@ -136,6 +148,10 @@ const APP: () = {
 		}
 	}
 
+	/// Our idle task.
+	///
+	/// This task is called when there is nothing else to do. We
+	/// do a little logging, then put the CPU to sleep waiting for an interrupt.
 	#[idle(resources = [])]
 	fn idle(_ctx: idle::Context) -> ! {
 		defmt::info!("Idle is running...");
@@ -145,6 +161,10 @@ const APP: () = {
 		}
 	}
 
+	/// This is the USART1 task.
+	///
+	/// It fires whenever there is new data received on USART1. We should flag to the host
+	/// that data is available.
 	#[task(binds = USART1, resources=[serial])]
 	fn usart1_interrupt(ctx: usart1_interrupt::Context) {
 		// Reading the register clears the RX-Not-Empty-Interrupt flag.
@@ -158,6 +178,10 @@ const APP: () = {
 		}
 	}
 
+	/// This is the LED blink task.
+	///
+	/// This task is called periodically. We check whether the status LED is currently on or off,
+	/// and set it to the opposite. This makes the LED blink.
 	#[task(schedule = [led_status_blink], resources = [led_status])]
 	fn led_status_blink(ctx: led_status_blink::Context) {
 		// Use the safe local `static mut` of RTIC
@@ -177,6 +201,9 @@ const APP: () = {
 		ctx.schedule.led_status_blink(next).unwrap();
 	}
 
+	/// This task polls our power and reset buttons.
+	///
+	/// We poll them rather than setting up an interrupt as we need to debounce them, which involves waiting a short period and checking them again. Given that we have to do that, we might as well not bother with the interrupt.
 	#[task(schedule = [button_poll], resources = [led_power, button_power, button_power_short_press, button_power_long_press, dc_power_enabled])]
 	fn button_poll(ctx: button_poll::Context) {
 		// Poll button
@@ -244,11 +271,7 @@ const APP: () = {
 	}
 };
 
-#[exception]
-unsafe fn DefaultHandler(value: i16) {
-	defmt::panic!("DefaultHandler({})", value);
-}
-
+// TODO: Pins we haven't used yet
 // SPI pins
 // spi_clk: gpioa.pa5.into_alternate_af0(cs),
 // spi_cipo: gpioa.pa6.into_alternate_af0(cs),