README updates.

Trying to clarify what is HAL specific and what is RP specific.

.cargo/config

@@ -10,3 +10,4 @@ rustflags = [
     "-C", "no-vectorize-loops",
 ]
 runner = "elf2uf2-rs -d"
+# runner = "probe-run-rp --chip RP2040"

README.md

@@ -8,26 +8,26 @@
    <h3 align="center">rp-hal</h3>
 
   <p align="center">
-    A Rust HAL and board support packages for the RP family of microcontrollers from the Raspberry Pi Foundation
+    Rust support for Raspberry Pi Silicon
     <br />
-    <a href="https://github.com/rp-rs/rp-hal"><strong>Explore the docs »</strong></a>
+    <a href="https://docs.rs/rp2040-hal"><strong>Explore the API docs »</strong></a>
     <br />
     <br />
-    <a href="https://github.com/rp-rs/rp-hal">View Demo</a>
+    <a href="https://github.com/rp-rs/rp-hal/tree/main/boards/pico/examples">View Demos</a>
     ·
-    <a href="https://github.com/rp-rs/rp-hal/issues">Report Bug</a>
+    <a href="https://github.com/rp-rs/rp-hal/issues">Report a Bug</a>
     ·
-    <a href="https://github.com/rp-rs/rp-hal/issues">Request Feature</a>
+    <a href="https://matrix.to/#/#rp-rs:matrix.org">Chat on Matrix</a>
   </p>
 </p>
 
 
-
 <!-- TABLE OF CONTENTS -->
 <details open="open">
   <summary><h2 style="display: inline-block">Table of Contents</h2></summary>
   <ol>
-    <li><a href="#packages">Packages</a></li>
+    <li><a href="#gettting_started">Getting Started</a></li>
+    <li><a href="#programming">Programming</a></li>
     <li><a href="#roadmap">Roadmap</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -37,6 +37,40 @@
 </details>
 
 <!-- GETTING STARTED -->
+
+## Getting Started
+
+So, you want to program your Raspberry Pi Silicon, using the Rust programming
+language. You've come to the right place!
+
+This repository is `rp-hal` - a collection of high-level drivers for the RP2040
+and various associated boards, like the Raspberry Pi Pico and the Adafruit
+Feather RP2040.
+
+If you want to try out some examples on one of our supported boards, check out
+the list of *Board Support Packages* below, and click through to see the various
+examples for each board.
+
+If you want to write an application for Raspberry Pi Silicon, check out our
+[RP2040 Project Template](https://github.com/rp-rs/rp2040-project-template).
+
+Before trying any of the examples, please ensure you have the latest stable version of Rust installed, along with the right target support:
+
+```console
+$ rustup self update
+$ rustup update stable
+$ rustup target add thumbv6m-none-eabi
+```
+
+You may also want to install these helpful tools:
+
+```sh
+# Useful to creating UF2 images for the RP2040 USB Bootloader
+cargo install elf2uf2-rs
+# Useful for flashing over the SWD pins using a supported JTAG probe
+cargo install --git https://github.com/rp-rs/probe-run.git --branch rp2040-support 
+```
+
 ## Packages
 
 This git repository is organised as a [Cargo Workspace].
@@ -147,6 +181,106 @@ RP2040 chip according to how it is connected up on the Pro Micro RP2040.
 [Sparkfun Pro Micro RP2040]: https://www.sparkfun.com/products/18288
 [pro_micro_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/pro_micro_rp2040
 
+<!-- PROGRAMMING -->
+## Programming
+
+Rust generates standard Arm ELF files, which you can load onto your Raspberry Pi
+Silicon device with your favourite Arm flashing/debugging tool. In addition, the
+RP2040 contains a ROM bootloader which appears as a Mass Storage Device over USB
+that accepts UF2 format images. You can use the `elf2uf2-rs` package to convert
+the Arm ELF file to a UF2 format image.
+
+For boards with USB Device support like the Raspberry Pi Pico, we recommend you
+use the UF2 process.
+
+The RP2040 contains a Cortex-M0+ processor, which implements the Thumb-2 format
+of the ARMv6-M instruction set. For compatibilty with other Arm code (e.g. as
+produced by GCC), Rust uses the *Arm Embedded-Application Binary Interface*
+standard or EABI. Therefore, any Rust code for the RP2040 should be compiled
+with the target `thumbv6m-none-eabi`.
+
+More details can be found in the [Project Template](https://github.com/rp-rs/rp2040-project-template).
+
+### Loading a UF2 over USB
+
+*Step 1* - Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs):
+
+```console
+$ cargo install elf2uf2-rs
+```
+
+*Step 2* - Make sure your .cargo/config contains the following (it should by
+default if you are working in this repository):
+
+```toml
+[target.thumbv6m-none-eabi]
+runner = "elf2uf2-rs -d"
+```
+
+The `thumbv6m-none-eabi` target may be replaced by the all-Arm wildcard
+`'cfg(all(target_arch = "arm", target_os = "none"))'`.
+
+*Step 3* - Boot your RP2040 into "USB Bootloder mode", typically by rebooting
+whilst holding some kind of "Boot Select" button. On Linux, you will also need
+to 'mount' the device, like you would a USB Thumb Drive.
+
+*Step 4* - Use `cargo run`, which will compile the code and started the
+specified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2
+file and copy it to your RP2040.
+
+```console
+$ cargo run --release --example pico_pwm_blink
+```
+
+### Loading with probe-run
+
+The Knurling project has a tool called
+[probe-run](https://github.com/knurling-rs/probe-run). This is a command-line
+tool which can flash a wide variety of microcontrollers using a wide variety of
+debug/JTAG probes. It is based on a library called
+[probe-rs](https://github.com/probe-rs/probe-rs).
+
+Currently, probe-rs supports the slightly unusual debug hardware in the RP2040,
+but the last released probe-run tool (v0.2.6, as of September 2021), does not.
+However, there is a special version of probe-run for the RP2040 called
+[probe-run-rs].
+
+*Step 1* - Install `probe-run-rp`:
+
+```console
+$ cargo install --git https://github.com/rp-rs/probe-run.git --branch rp2040-support 
+```
+
+*Step 2* - Make sure your .cargo/config contains the following:
+
+```toml
+[target.thumbv6m-none-eabi]
+runner = "probe-run-rp --chip RP2040"
+```
+
+*Step 3* - Connect your USB JTAG/debug probe (such as a Raspberry Pi Pico
+running [this firmware](https://github.com/majbthrd/DapperMime)) to the SWD
+programming pins on your RP2040 board. Check the probe has been found by
+running:
+
+```console
+$ probe-run-rp --chip RP2040 --list-probes
+The following devices were found:
+[0]: J-Link (J-Link) (VID: 1366, PID: 0101, Serial: 000099999999, JLink)
+```
+
+There is a SEGGER J-Link connected in the example above - the mesage you see
+will reflect the probe you have connected.
+
+*Step 4* - Use `cargo run`, which will compile the code and start the specified
+'runner'. As the 'runner' is the `probe-run-rp` tool, it will connect to the
+RP2040 via the first probe it finds, and install your firmware into the Flash
+connected to the RP2040.
+
+```console
+$ cargo run --release --example pico_pwm_blink
+```
+
 <!-- ROADMAP -->
 ## Roadmap
 

rp2040-hal/README.md

@@ -8,16 +8,16 @@
    <h3 align="center">rp-hal</h3>
 
   <p align="center">
-    A Rust HAL impl for the RP family of microcontrollers from the Raspberry Pi Foundation
+    High-level Rust drivers for the Raspberry Pi Silicon RP2040 Microcontroller
     <br />
-    <a href="https://github.com/rp-rs/rp-hal"><strong>Explore the docs »</strong></a>
+    <a href="https://docs.rs/rp2040-hal"><strong>Explore the API docs »</strong></a>
     <br />
     <br />
-    <a href="https://github.com/rp-rs/rp-hal">View Demo</a>
+    <a href="https://github.com/rp-rs/rp-hal/tree/main/boards/pico/examples">View Demos</a>
     ·
-    <a href="https://github.com/rp-rs/rp-hal/issues">Report Bug</a>
+    <a href="https://github.com/rp-rs/rp-hal/issues">Report a Bug</a>
     ·
-    <a href="https://github.com/rp-rs/rp-hal/issues">Request Feature</a>
+    <a href="https://matrix.to/#/#rp-rs:matrix.org">Chat on Matrix</a>
   </p>
 </p>
 
@@ -27,6 +27,7 @@
 <details open="open">
   <summary><h2 style="display: inline-block">Table of Contents</h2></summary>
   <ol>
+    <li><a href="#introduction">Introduction</a></li>
    <li>
       <a href="#getting-started">Getting Started</a>
       <ul>
@@ -34,7 +35,6 @@
         <li><a href="#installation">Installation</a></li>
       </ul>
     </li>
-    <li><a href="#usage">Usage</a></li>
     <li><a href="#roadmap">Roadmap</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -43,70 +43,60 @@
   </ol>
 </details>
 
+<!-- INTRODUCTION -->
+## Introduction
+
+This is the `rp2040-hal` package - a library crate of high-level Rust drivers
+for the Raspberry Pi Silicon RP2040 microcontroller, along with a collection of
+non-board specific example programs for you to study. You should use this crate
+in your application if you want to write code for the RP2040 microcontroller.
+The *HAL* in the name standards for *Hardware Abstraction Layer*, and comes from
+the fact that many of the drivers included implement the generic
+hardware-abstraction interfaces defined in the Rust Embedded Working Group's
+[embedded-hal](https://github.com/rust-embedded/embedded-hal) crate.
+
+We also provide a series of *Board Support Package* (BSP) crates, which take
+this HAL crate and pre-configure the pins according to a specific PCB design. If
+you are using on of the supported boards, you should use one of those crates in
+preference, and return here to see documentation about specific peripherals on
+the RP2040 and how to use them. See the `boards` folder in
+https://github.com/rp-rs/rp-hal/ for more details.
+
 <!-- GETTING STARTED -->
 ## Getting Started
 
-To get a local copy up and running follow these simple steps.
+To include this crate in your project, amend your `Cargo.toml` file to include
-
-### Prerequisites
-
-* A [Rust](https://www.rust-lang.org/tools/install) toolchain
-
-### Installation
-
-1. Clone the repo or use the crate
-
-   ```sh
-   git clone https://github.com/rp-rs/rp-hal
-   ```
-
-   or
-
-   ```sh
-   cargo install rp2040-hal
-   ```
-
-<!-- USAGE EXAMPLES -->
-## Usage
-
-Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.
-
-For more examples, please refer to the [Documentation](https://github.com/rp-rs/rp-hal)
-
-### Run examples
-
-#### UF2
-
-For boards with uf2 flashloaders like the raspberry pi pico. Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs):
-
-```sh
-cargo install elf2uf2-rs
-```
-
-Make sure .cargo/config contains the following (it should by default):
 
 ```toml
-runner = "elf2uf2-rs -d"
+rp2040-hal = "0.3"
 ```
 
-**IMPORTANT: Make sure you've put your device into bootloader mode and the drive is showing as mounted before executing the next command.**
+To obtain a copy of the source code (e.g. if you want to propose a bug-fix or
+new feature, or simply to study the code), run:
 
-```sh
+```console
-cargo run --example pico_pwm_blink # Run `cargo run --example` for more examples
+$ git clone https://github.com/rp-rs/rp-hal.git
 ```
 
+For details on how to program an RP2040 microcontroller, see the [top-level
+rp-hal README](https://github.com/rp-rs/rp-hal/).
+
 <!-- ROADMAP -->
 ## Roadmap
 
-NOTE This HAL is under active development. As such, it is likely to remain volatile until a 1.0.0 release.
+NOTE This HAL is under active development. As such, it is likely to remain
+volatile until a 1.0.0 release.
 
-See the [open issues](https://github.com/rp-rs/rp-hal/issues) for a list of proposed features (and known issues).
+See the [open issues](https://github.com/rp-rs/rp-hal/issues) for a list of
+proposed features (and known issues).
 
 
 <!-- CONTRIBUTING -->
 ## Contributing
 
-Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+Contributions are what make the open source community such an amazing place to
+be learn, inspire, and create. Any contributions you make are **greatly
+appreciated**.
 
 1. Fork the Project
 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)