Merge branch 'main' into cram-dev

Cargo.toml

@@ -114,6 +114,8 @@ members = [
   "services/usb-cramium",
   "services/bao-console",
   "libs/ux-api",
+  "services/cramium-emu",
+  "libs/cramium-api",
 ]
 resolver = "2"
 

README-baochip.md

@@ -0,0 +1,96 @@
+# "Baochip" / "Cramium" Series API Organization & Glossary
+
+## API Organization
+
+The Baochip platform has the following API structure. Note that
+`cramium` is the original code name for the target chip, which after
+two years of extensive code development migrated to the `baochip`
+brand name. At the moment the misnaming stands, due to the amount
+of code that carries the legacy name.
+
+`libs/cramium-api`: contains hardware-abstracted API code to the hardware
+layers (traits, some constants, enums, etc.). For example, "here is
+an IO trait that lets you configure and set GPIO pins", which could
+then be implemented in hardware or emulation. The APIs aren't entirely
+generic across all SoCs because they are tweaked to accommodate
+quirks of the cramium SoC.
+
+`libs/cramium-hal`: contains board-specific driver codes that do not
+require persistent services to be started. Possibly misnamed because
+it also includes not just cramium-chip items, but also e.g. peripherals
+to the cramium SoC, such as the PMIC and camera.
+
+`services/cramium-hal-service`: contains the `main` process that manages
+shared resources, such as UDMA, IO pins, IFRAM. These drivers cannot
+be delegated to a `lib` crate because there can be only one instance
+of these resources, and instead we have to dynamically allocate
+access to these through IPC messaging.
+
+`services/cramium-emu`: hosted mode emulation of things in
+cramium-hal-service.
+
+`services/bao-video`: contains a `main` process that integrates
+the camera and OLED driver. This means that all graphic drawing
+primitives also interface with this crate. These are condensed
+into a single process space to speed up execution, and kept
+separate from cramium-hal-services because we want the video
+services to not be blocked by, for example, a thread that is
+handling I2C things.
+
+## Glossary
+
+The history of names in this SoC are complicated because the drivers
+were developed in parallel with the legal entity that makes the chip
+being formed and funded. Thus the name of the company and chip don't
+even match compared to the final product. Here is a glossary of terms
+you may encounter in this project.
+
+`daric`: Code name for the MPW (multi-project-wafer) test SoC. It was
+also supposed to be a product name but apparently this was already
+taken and thus while lots of code uses the name, it can't be used
+as a product name.
+
+`cramium`: Putative name for a company that was supposed to be started
+to sell what was the `daric` SoC, and was assumed to be the brand
+name for the chip. As of writing the entity may still not exist.
+
+`crossbar`: The parent company that was supposed to spin out `cramium`.
+Most of the OSS SoC code has its copyright assigned to this organization;
+so, this is probably the most relevant legal entity even though its
+name doesn't appear in marketing materials.
+
+`baochip`: The name of a new company formed to market an OSS- and Xous-focused
+variant of the `daric` chip. This is the relevant legal organization in terms
+of purchasing chips and systems related to this code base; thus from a user
+perspective this is the brand used in Xous.
+
+`baochip zero`: Actual brand name of the chip. Internally code named `nto` (which
+stands for "Next Tape Out" - look, I don't come up with half of these names,
+I just use them).
+
+`cramium-soc`: The name of the Xous target that is actually the `baochip zero`.
+It is also used as a target for "pure SoC" simulations; i.e., verilog RTL
+simulations where the peripherals are entirely virtual test benches.
+
+`cramium-fpga`: A placeholder target that is meant to be a down-sized
+FPGA implementation of the SoC. This will likely be an Artix-7 100T
+implementation, targeting the Digilent Arty A7.
+
+`baosec`: Internal code name of a board that contains the `baochip zero` with
+a USB security token form factor. This is likewise the name of the xtask target
+to build images for this board. Contains a camera, display, storage, USB
+and buttons. `board-baosec` is the flag for the board target, and `loader-baosec`
+is an analogous flag but for no-std environments. `hosted-baosec` likewise
+is for `baosec` but running on an x86 host (for UX development).
+
+`baosec-emu`: xtask target for hosted mode emulation for `baosec`. `cramium-emu`
+contains hosted mode shims for the `baosec` target. `cramium-emu` mis-named and
+should probably be renamed to `baosec-emu`.
+
+`baosor`: Internal code name of a board that contains the `baochip zero` with
+the Precursor form factor. `board-basor` is the flag for the board target,
+and `loader-baosor` is an analogous flag but for no-std environments.
+
+`dabao`: Internal codename of a breakout board for the `baochip zero` that
+contains nothing more than the chip, a power regulator and a USB connector.
+

README.md

@@ -4,6 +4,8 @@ Core files for the Xous microkernel operating system.
 
 You might find this [wiki](https://github.com/betrusted-io/betrusted-wiki/wiki) handy, as well as the [Xous Book](https://betrusted.io/xous-book/).
 
+Users targeting Baochip platforms should also familiarize with the [Boachip API structure and glossary](./README-baochip.md) as the platform has several targets and gone through numerous name changes.
+
 This repository contains everything necessary to build the Xous kernel
 from source.  It consists of the following projects:
 
@@ -23,6 +25,15 @@ from source.  It consists of the following projects:
 - Some system packages are needed, which can be installed with `sudo apt install libssl-dev libxkbcommon-dev` or similar
 - If you receive an error about `feature resolver is required`, try installing a newer version of `rustc` and `cargo` via [rustup](https://rustup.rs)
 
+## Building Documentation
+A flag of `--feature doc-deps` must be passed when running `cargo doc`, like this:
+
+`cargo doc --no-deps --feature doc-deps`
+
+This flag is required because Xous requires a target board to be specified in
+all build configurations. `doc-deps` specifies a set of dummy dependencies
+that satisfy board requirements for the purpose of building documentation.
+
 ## Local-vs-crates.io Verification
 By default the `xtask` resolver runs a check to confirm that your local files
 match the ones referenced in `crates.io`. For a handful of core crates, the
@@ -59,13 +70,13 @@ will begin scrolling in your terminal.
 
 ### Hosted Mode UI navigation
 
-| Precursor | Host |
-| --------- | ---- |
-| D-pad middle button | Home |
-| D-pad up | up arrow |
-| D-pad down | down arrow |
-| D-pad left | left arrow |
-| D-pad right | right arrow |
+| Precursor           | Host        |
+| ------------------- | ----------- |
+| D-pad middle button | Home        |
+| D-pad up            | up arrow    |
+| D-pad down          | down arrow  |
+| D-pad left          | left arrow  |
+| D-pad right         | right arrow |
 
 
 ## Quickstart using an emulator

RELEASE-v0.9.md

@@ -506,7 +506,13 @@ perform the Xous firmware upgrade. This requires running manual update commands,
   - Number of pages to allocate could be automated inside the `xous-ipc` crate, but this will be delegated to a future time with a new API.
   - Most applications were forward-ported, except for `app-loader` which has already bit-rotted for other reasons and may be deprecated because we can use "swap" space to effectively do app loading (to be made available in future hardware revs)
   - Serialization is a bit easier now with the new `rkyv`, we don't have to track a `pos` explicitly; all of the archival metadata is now stuck at the end of the archive, so all you need to know is the final length of the serialized record and you're done.
-
+- Refactor `blitstr2` to be in its own `libs` crate, allowing it to be re-used across multiple configurations
+- Clean up the board vs soc abstraction. There are still places that don't adhere to this distinction, but:
+  - A `soc` flag specifies dependencies that are generic to a system-on-chip (SoC). For example, the locations of registers, or the extents of memory regions contained in the `soc`.
+  - A `board` flag specifies dependencies that are specific to a board. For example, the resolution of displays, pin mappings to peripherals, and sizes of external memory. Typically, a board assumes a `soc`, so both a `board-*` and `*-soc` set of flags are required to fully specify a build.
+  - Precursor (the first target for Xous) did not hold to this abstraction and conflated the two, so it is a special case in the build system.
+  - "Hosted" mode emulations are considered to be a `board` target; the `soc` is assumed to be the host (linux, windows, etc.)
+- Since all builds require a `board` specifier, documentation now requires a `doc-deps` flag to be passed. This effectively specifies a set of dummy board dependencies so that the documentation can build. Here is the recommended command line for building docs: `cargo doc --no-deps --feature doc-deps`
 
 ## Roadmap
 - Lots of testing and bug fixes

kernel/Cargo.toml

@@ -44,12 +44,17 @@ critical-section = "1.1.1"
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(ci)', 'cfg(baremetal)'] }
 
 [features]
-cramium-soc = ["utralib/cramium-soc", "cramium-hal", "rand_chacha", "raw-trng"]
+cramium-soc = [
+    "utralib/cramium-soc",
+    "cramium-hal/cramium-soc",
+    "rand_chacha",
+    "raw-trng",
+]
 verilator-only = []
 cramium-fpga = ["utralib/cramium-fpga", "rand_chacha"]
-board-baosec = ["cramium-hal/board-baosec"]
-board-baosor = ["cramium-hal/board-baosor"]
-board-dabao = ["cramium-hal/board-dabao"]
+board-baosec = []
+board-baosor = []
+board-dabao = []
 
 atsama5d27 = ["utralib/atsama5d27"]
 precursor = ["utralib/precursor"]

libs/blitstr2/src/platform/doc.rs

@@ -0,0 +1,6 @@
+// Dummy values to allow cargo doc to build
+pub const LINES: isize = 536;
+pub const WIDTH: isize = 336;
+pub const WORDS_PER_LINE: usize = 11;
+pub type FrBuf = [u32; WORDS_PER_LINE * LINES as usize];
+pub const FB_SIZE: usize = WORDS_PER_LINE * LINES as usize; // 44 bytes by 536 lines

libs/blitstr2/src/platform/mod.rs

@@ -9,3 +9,22 @@ pub use baosec::*;
 mod precursor;
 #[cfg(any(feature = "hosted", feature = "renode", feature = "precursor"))]
 pub use precursor::*;
+
+// Dummy configuration to allow cargo doc to run - this has no board specified
+#[cfg(any(
+    all(
+        not(any(feature = "board-baosec", feature = "hosted-baosec")),
+        not(any(feature = "hosted", feature = "renode", feature = "precursor"))
+    ),
+    doc
+))]
+mod doc;
+
+#[cfg(any(
+    all(
+        not(any(feature = "board-baosec", feature = "hosted-baosec")),
+        not(any(feature = "hosted", feature = "renode", feature = "precursor"))
+    ),
+    doc
+))]
+pub use doc::*;

libs/cramium-api/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "cramium-api"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+xous = "0.9.64"
+xous-ipc = { version = "0.10.4", optional = true }
+xous-names = { package = "xous-api-names", version = "0.9.65", optional = true }
+num-derive = { version = "0.4.2", default-features = false }
+num-traits = { version = "0.2.14", default-features = false }
+rkyv = { version = "0.8.8", default-features = false, features = [
+    "std",
+    "alloc",
+], optional = true }
+
+[features]
+std = ["derive-rkyv", "xous-names", "xous-ipc"]
+derive-rkyv = ["rkyv"]
+default = []

libs/cramium-api/src/i2c.rs

@@ -0,0 +1,50 @@
+pub trait I2cApi {
+    fn i2c_write(&mut self, dev: u8, adr: u8, data: &[u8]) -> Result<usize, xous::Error>;
+
+    /// initiate an i2c read. The read buffer is passed during the await.
+    fn i2c_read(
+        &mut self,
+        dev: u8,
+        adr: u8,
+        buf: &mut [u8],
+        repeated_start: bool,
+    ) -> Result<usize, xous::Error>;
+}
+
+#[cfg_attr(feature = "derive-rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[derive(Debug, PartialEq, Eq)]
+pub enum I2cTransactionType {
+    Write,
+    Read,
+    ReadRepeatedStart,
+}
+
+#[cfg_attr(feature = "derive-rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[derive(Debug)]
+pub enum I2cResult {
+    /// For the outbound message holder
+    Pending,
+    /// Returns # of bytes read or written if successful
+    Ack(usize),
+    /// An error occurred.
+    Nack,
+}
+#[cfg_attr(feature = "derive-rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[cfg(feature = "std")]
+pub struct I2cTransaction {
+    pub i2c_type: I2cTransactionType,
+    pub device: u8,
+    pub address: u8,
+    pub data: Vec<u8>,
+    pub result: I2cResult,
+}
+
+#[cfg_attr(feature = "derive-rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[cfg(feature = "std")]
+pub struct I2cTransactions {
+    pub transactions: Vec<I2cTransaction>,
+}
+#[cfg(feature = "std")]
+impl From<Vec<I2cTransaction>> for I2cTransactions {
+    fn from(value: Vec<I2cTransaction>) -> Self { Self { transactions: value } }
+}