From 5b1b6c4b777205645a947e1bbbbc8292fab9111d Mon Sep 17 00:00:00 2001
From: Robin Mueller <robin.mueller.m@gmail.com>
Date: Wed, 12 Jun 2024 11:45:30 +0200
Subject: [PATCH] README

---
 README.md              | 76 ++++++++++++++++++++++++++++++++++++++----
 vscode/extensions.json | 12 +++++++
 2 files changed, 82 insertions(+), 6 deletions(-)
 create mode 100644 vscode/extensions.json

diff --git a/README.md b/README.md
index 4573c82..87252cb 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,18 @@
-# Vorago VA416xx Rust Workspace
+Vorago VA416xx Rust Support
+=========
 
-After cloning, run
+This crate collection provided support to write Rust applications for the VA416XX family
+of devices.
 
-```sh
-git submodule init
-git submodule update
-```
+## List of crates
+
+This workspace contains the following crates:
+
+- The `va416xx` PAC crate containing basic low-level register definition
+- The `va416xx-hal` HAL crate containing higher-level abstractions on top of
+  the PAC register crate.
+- The `vorago-peb1` BSP crate containing support for the PEB1 development
+  board.
 
 ## Using the `.cargo/config.toml` file
 
@@ -17,3 +24,60 @@ cp .cargo/def-config.toml .cargo/config.toml
 
 You then can adapt the `config.toml` to your needs. For example, you can configure runners
 to conveniently flash with `cargo run`.
+
+## Using the sample VS Code files
+
+Use the following command to have a starting configuration for VS Code:
+
+```sh
+cp vscode .vscode -r
+```
+
+You can then adapt the files in `.vscode` to your needs.
+
+## Flashing, running and debugging with the command line
+
+### Prerequisites
+
+1. [SEGGER J-Link tools](https://www.segger.com/downloads/jlink/) installed
+2. [gdb-multiarch](https://packages.debian.org/sid/gdb-multiarch) or similar
+   cross-architecture debugger installed. All commands here assume `gdb-multiarch`.
+
+### Flashing and debugging the blinky application
+
+You can build the blinky example application with the following command
+
+```sh
+cargo build -p va416xx-hal --example blinky
+```
+
+Start the GDB server first. The server needs to be started with a certain configuration and with
+a JLink script to disable ROM protection.
+For example, on Debian based system the following command can be used to do this (this command
+is also run when running the `jlink-gdb.sh` script)
+
+```sh
+JLinkGDBServer -select USB -device Cortex-M4 -endian little -if SWD -speed 2000 \
+  -LocalhostOnly -vd -jlinkscriptfile ./jlink/JLinkSettings.JLinkScript
+```
+
+After this, you can flash and debug the application with the following command
+
+```sh
+gdb-mutliarch -q -x jlink/jlink.gdb target/thumbv7em-none-eabihf/debug/examples/blinky
+```
+
+Please note that you can automate all steps except starting the GDB server by using a cargo
+runner configuration, for example with the following lines in your `.cargo/config.toml` file:
+
+```toml
+[target.'cfg(all(target_arch = "arm", target_os = "none"))']
+runner = "gdb-multiarch -q -x jlink/jlink.gdb"
+```
+
+After that, you can simply use `cargo run -p va416xx-hal --example blinky` to flash the blinky
+example.
+
+## Flashing, running and debugging with VS Code
+
+TODO
diff --git a/vscode/extensions.json b/vscode/extensions.json
new file mode 100644
index 0000000..d2cfd28
--- /dev/null
+++ b/vscode/extensions.json
@@ -0,0 +1,12 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"rust-lang.rust",
+		"marus25.cortex-debug"
+		// "probe-rs.probe-rs-debugger"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": []
+}
\ No newline at end of file