From 95f93a761e73b74dff66bbd2c37182d6091b6287 Mon Sep 17 00:00:00 2001
From: Richard Patel <me@terorie.dev>
Date: Thu, 7 Apr 2022 01:48:21 +0200
Subject: [PATCH] update README.md

---
 README.md | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 92a2819..f406afa 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,15 @@
 
 Rust tools for working with the PowerPC 750CL family of processors.
 
-### Python module
+### Rust crates
 
-Build instructions:
+```shell
+rustup components add rustfmt
+cargo run --package ppc750cl-genisa
+cargo build --release
+```
+
+### Python module
 
 ```shell
 python -m venv env
@@ -12,3 +18,21 @@ source ./env/bin/activate
 pip install maturin
 maturin build -m ./disasm-py/Cargo.toml
 ```
+
+### Instruction Set
+
+For those unfamiliar with PowerPC, here are some basics.
+- PowerPC 7xx is a family of RISC CPUs produced from 1997 to 2012.
+  - They operate with 32-bit words and every instruction is 32-bits wide.
+- This project focuses (only) on compatibility with the PowerPC 750CL.
+  - This chip is famously packaged as codename "Broadway" for the Nintendo Wii.
+  - Its predecessor PowerPC 750CXe is used in the Nintendo GameCube.
+  - It adds a "paired-singles" SIMD unit and a bunch of other instructions.
+
+### isa.yaml
+
+The file [isa.yaml](./isa.yaml) contains a full definition of the PowerPC 750CL instruction set.
+
+It powers the disassembler, assembler, and Rust/Python bindings code analysis tools.
+
+Similarly to LLVM TableGen, the program `ppc750cl-genisa` generates a Rust file implementing an instruction decoder.