Add docs (#32)

* cargo fmt mailbox and fb

* remove console

* remove old boot folder

* alloc compiles

* add deps

* add alloc to std build

* finish removing console

* add dead code header

* add macos, linux, windows to gitignore

* remove aarch64

* add alloc test

* move dev_barrier fn to cpu module

* add note

* add dev_barrier(), refactor

* ill be back

* allocator failing with uart garbage

* use most recent spin crate

* add crate dependency

* small changes

* update makefile

* blink faster

* launch codes

* ignore debug files

* rip, optimization breaks the uart

* add objdump, nm, and readelf targets for test

* read ascii chars

* most of uart is broken

* hello from rust

* 🦀

* add test case

* add aeabi_unwind_cpp_pr0 -> panic

* sheesh its running slow

* hello from rust

* guess we like space

* remove commented code

* remove vs code settings

* remove comment

* standardize naming

* opt level 1 seems the best so far

* beam hits ship

* screen is blank

* game on make run target

* i am speed

* space invader

* unsafeteeee

* emit beam

* stop panicking!

* keyboard timeout

* change movement speed

* pause

* merge and black rectangle on bottom

* fewer beam artifacts

* fewer beam artifacts

* better

* add setup instructions

* add contributions and remove docs from main

* refactor

* add some more edits

* Ashish/docs (#30)

* better

* docs

Co-authored-by: Ashish Rao <aprao@stanford.edu>

* Xiluo/docs (#31)

* Remove Artifacts (#29)

* fewer beam artifacts

* better

* Update gpio.rs

* Update keyboard.rs

* Update timer.rs

Co-authored-by: Ashish Rao <aprao@stanford.edu>
Co-authored-by: xiluohe <42448015+xiluohe@users.noreply.github.com>

* Update space_invaders.rs

* add email

* add more refs

Co-authored-by: Ashish Rao <aprao@stanford.edu>
Co-authored-by: Xiluo He <hexiluo@gmail.com>
Co-authored-by: xiluohe <42448015+xiluohe@users.noreply.github.com>

Author: 3 people

README.md

@@ -1,58 +1,102 @@
 [![Build Status](https://staging.travis-ci.com/piruts/rustberry.svg?branch=main)](https://staging.travis-ci.com/piruts/rustberry)
+
 # Rustberry Pi
 
 ## Setup
 
 ### Install Rustup
 
 #### Macos
-```
+
+```sh
 brew install rustup
 ```
 
 #### Windows, Linux
 
 visit: https://rustup.rs/#
 
-
 ### Configure the project to use `Nightly` Rust Channel
 
-```
+```sh
 rustup override set nightly
 ```
 
 ### Install Dependencies
-```bash
+
+```sh
 cargo install cargo-binutils rustfilt
 rustup component add llvm-tools clippy rust-src
 ```
 
 ## Setup Hardware
+
 Things you need:
+
 - Raspberry Pi A
-- CP2102 Breakout
+- CP2102 USB to UART Bridge
 - PS/2 Keyboard
 - HDMI Cable
 - HDMI Display
-- Jumper cables
+- Jumper Wires
+- Header Pin
+
+### Wiring
 
-Before plugging anything in, connect 
-### Keyboard
+| CP2102 | Raspberry Pi       |
+|--------|--------------------|
+| DTR    | Run*               |
+| RXI    | GPIO 14 (UART TXD) |
+| TXO    | GPIO 15 (UART RXD) |
+| VCC    | 5V                 |
+| GND    | GND                |
 
-## Build
+**you need to solder a pin on the Raspberry Pi*
 
-**Compile and run on hardware**
+Take a look at [Mini-DIN connectors](https://en.wikipedia.org/wiki/Mini-DIN_connector)
 
-```bash
+| PS/2 Keyboard | Raspberry Pi |
+|---------------|--------------|
+| DATA (1)      | GPIO 4       |
+| VCC (4)       | 5V           |
+| CLK (5)       | GPIO 3       |
+| GND (3)       | GND          |
+
+## Build and run
+
+```sh
 make run
 ```
-**Generate docs**
 
-```
-make doc
-```
+---
 
-**Run linter**
-```
-make clippy
-```
+## Individual Contributions
+
+Flynn:
+
+- Implemented UART module
+- Implemented test framework
+- Implemented Alloc Module
+- Defined custom target for rust/llvm compilation
+
+Ashish:
+
+- Implemented mailbox and framebuffer modules
+- Implemented support for embedded-graphics crate (see src/gl.rs)
+- Worked on final game
+- Animation with double buffering
+  - Logic for firing beams and checking for collision with enemy ships
+  - Movement of enemies and player
+
+Xiluo:
+
+- Implemented GPIO module and part of GPIO extra
+- Implemented timer module
+- Implemented ps2 module and keyboard support
+
+## Resources Used
+
+- In order to figure out how to run Rust on the Raspberry Pi, we referred to a Raspberry Pi ¾ project. https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials. Our Makefile was based on the one given under lesson 03_hacky_hello_world in this repository, and we included the linker file and based some of our modules off of modules in their codebase. All files used have their license and original author listed at the top.
+- We used the embedded-graphics library for drawing rectangles and triangles: https://crates.io/crates/embedded-graphics. We implemented the low-level functions necessary to use this library on Raspberry Pi ourselves (mailbox and framebuffer).
+- To learn more about and understand Rust, we referred to the Rust book and the embedded Rust book: https://doc.rust-lang.org/book/, https://docs.rust-embedded.org/book/
+- We had help from Akshay Srivatsan and used Dawson Engler’s dev_barrier() code from CS140E

custom-target-definition.md

@@ -0,0 +1,17 @@
+# How to Define a Custom Target
+
+The rust only includes support for certain chips/instruction sets. Run `rustup target list`—if you don't see your target, do not fear! You can define a custom one as explained briefly here.
+
+First, find a similar target and copy its configuration. The following will print this to your shell.
+
+```sh
+rustc +nightly -Z unstable-options --print target-spec-json --target $SOME_SIMILAR_TARGET
+```
+
+Edit all the fields that are different, and add more as necessary.
+
+The LLVM docs have useful information on memoery layout
+https://llvm.org/docs/LangRef.html#data-layout
+
+**Note**
+_For this project, we could not get the GNU linker to work, but LLD (the LLVM linker which is a drop-in replacement for the GNU one) works fine._

docs/custom-target-definition.md

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 //
 // Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+// 
+// Edited by Xiluo He <xiluohe@stanford.edu> and Flynn Dreilinger <flynnd@stanford.edu>
 
 .section ".text._start"