README.md

Undergraduate Teaching Platform: A Prototype 👷

🚧 🚧 This is very much not stable yet! 🚧 🚧

This repo houses the 'core' of the UTP platform which consists of these pieces:

• Types and friends for the LC-3 ISA as we know and love it.
  • Lives in the lc3-isa crate.
• Traits defining the LC-3's peripherals, memory, and control interface.
  • Lives in the lc3-traits crate.
  • This is really the heart and soul of the platform.
• An instruction level simulator for the LC-3.
  • Lives in the lc3-baseline-sim crate.
• Example implementations of the LC-3 peripherals and memory suitable for simulating the peripherals on a computer.
  • Lives in the lc3-shims crate.
  • Unlike the other library crates, this one isn't #![no_std]!
• Some helper proc-macros (in the lc3-macros crate).
  • This also isn't #![no_std] but it doesn't really count.
• A barebones OS that is virtually identical to the one used in lc3tools.
  • Lives in the lc3-os crate.
• Bits and bobs useful to applications (things that interact with simulator implementations).
  • Lives in the lc3-application-support crate.
  • Currently has a wrapper type for shims and an Input/Output peripheral abstraction for impls that are backed by a host.

<TODO: diagram>

At the moment, the primary 'users' of the platform are the following:

• An implementation of the platform for the TI Launchpad.
  • Lives in the lc3-tm4c crate.
• A TUI that can interact with any UTP LC-3 simulator.
  • Lives in the lc3-tui crate.
  • Works with instances of the simulator as well as actual devices like the TM4C.
• A device support crate.
  • This contains macros and pieces that aid in implementing the peripheral traits and running the simulator on devices with embedded-hal support. This includes:
    • the uart transport layer
    • the #![no_std] compatible encoding layer (based on postcard)
    • (eventually (TODO)) the macros that, provided with embedded-hal compliant pins, provides you with peripheral trait impls
    • miscellaneous things necessary for the above like a simple FIFO
  • Lives in the lc3-device-support crate.
  • TODO: move out of this repo!

For Developers

TODO: fill in

To check that the project will build:

• cargo c or cargo check-all

To actually build the project:

• cargo b or cargo build-all to build everything
• cargo build -p <crate name> to build a particular crate
  • i.e. cargo build -p lc3-isa

To run the project's tests:

• cargo t or cargo test-all to run all the tests
• cargo test -p <crate name> to run a particular crate's tests

To run the project's benchmarks:

• cargo bench to run them all
• cargo bench --bench <benchmark name> to run a particular benchmark

To build the docs for the project:

• cargo +nightly docs (cargo-nightly docs if using nix)
  • NOTE: this requires a nightly Rust toolchain!
  • If you're on stable you can instead run: cargo d (or cargo docs-stable) to get mostly identical output

To run the project's lints (that CI runs):

• cargo lint

TODO:

• crate and doc badges on each crate
• doc badge to gh pages on the top level README (this file)
• CI:
  • release (on tag)
  • docs (upload to gh-pages)
  • coverage (still want codecov over coveralls but may acquiesce)