earlgrey/ot: document configurations

No explicit default copy.

boards/opentitan/README.md

@@ -50,6 +50,23 @@ You can also just use the `spiflash` program manually to download the image to t
 
 NOTE: You will need to download the Tock binary after every power cycle.
 
+### Compiling the Kernel for FPGA or Verilator
+
+Opentitan is supported on both an FPGA and in Verilator. Slightly different
+versions of the EarlGrey chip implementation are required for the different
+platforms. By default the kernel is compiled for the FPGA. To compile for
+Verilator, run:
+
+```shell
+make BOARD_CONFIGURATION=sim_verilator
+```
+
+To explicitly specify the FPGA, run:
+
+```shell
+make BOARD_CONFIGURATION=fpga_nexysvideo
+```
+
 Programming Apps
 ----------------
 

chips/earlgrey/Cargo.toml

@@ -5,6 +5,8 @@ authors = ["Tock Project Developers <tock-dev@googlegroups.com>"]
 edition = "2018"
 
 [features]
+# Compiling this crate requires enabling one of these features, otherwise
+# the default will be chosen.
 config_fpga_nexysvideo = ["config_disable_default"]
 config_sim_verilator = ["config_disable_default"]
 config_disable_default = []

chips/earlgrey/README.md

@@ -4,3 +4,12 @@ EarlGrey is the first OpenTitan system. At the center of the Earl Grey is the
 Ibex RISC-V compliant processor.
 
 [General information](https://docs.opentitan.org/hw/top_earlgrey/doc/)
+
+
+EarlGrey Configurations
+-----------------------
+
+Since the EarlGrey chip has not yet been fabricated in silicon, using it
+requires running it on an FPGA or in a simulator. These environments have slight
+differences, and require slightly different configurations of the EarlGrey chip.
+These configurations can be found in `chip_config.rs`.

chips/earlgrey/src/chip.rs

@@ -173,6 +173,10 @@ impl<A: 'static + Alarm<'static>> kernel::Chip for EarlGrey<A> {
     }
 
     unsafe fn print_state(&self, writer: &mut dyn Write) {
+        let _ = writer.write_fmt(format_args!(
+            "\r\n---| EarlGrey configuration for {} |---",
+            CONFIG.name
+        ));
         rv32i::print_riscv_state(writer);
     }
 }

chips/earlgrey/src/chip_config.rs

@@ -1,29 +1,42 @@
 //! Chip specific configuration.
+//!
+//! This file includes configuration values for different implementations and
+//! uses of the same earlgrey chip. For example, running the chip on an FPGA
+//! requires different parameters from running it in a verilog simulator.
+//! Additionally, chips on different platforms can be used differently, so this
+//! also permits changing values like the UART baud rate to enable better
+//! debugging on platforms that can support it.
+//!
+//! The configuration used is selected via Cargo features specified when the
+//! board is compiled.
 
-// Chip configuration based on the target device.
+/// Earlgrey configuration based on the target device.
 pub struct Config<'a> {
+    /// Identifier for the platform. This is useful for debugging to confirm the
+    /// correct configuration of the chip is being used.
     pub name: &'a str,
+    /// The clock speed of the core in Hz.
     pub chip_freq: u32,
+    /// The baud rate for UART. This allows for a version of the chip that can
+    /// support a faster baud rate to use it to help with debugging.
     pub uart_baudrate: u32,
 }
 
-#[cfg(not(feature = "config_disable_default"))]
+/// Config for running EarlGrey on an FPGA. Also the default configuration.
+#[cfg(any(
+    feature = "config_fpga_nexysvideo",
+    not(feature = "config_disable_default")
+))]
 pub const CONFIG: Config = Config {
-    name: &"default",
-    chip_freq: 50_000_000,
-    uart_baudrate: 230400,
-};
-
-#[cfg(feature = "config_fpga_nexysvideo")]
-pub const CONFIG: Config = Config {
-    name: &"fpga_nexysvideo",
+    name: "fpga_nexysvideo",
     chip_freq: 50_000_000,
     uart_baudrate: 230400,
 };
 
+/// Config for running EarlGrey in a verilog simulator.
 #[cfg(feature = "config_sim_verilator")]
 pub const CONFIG: Config = Config {
-    name: &"sim_verilator",
+    name: "sim_verilator",
     chip_freq: 500_000,
     uart_baudrate: 9600,
 };