Docs (#6)

* [RUST EMBEDDED] more documentation

* [GITHUB] pull request template

Author: hexdae

.github/pull_request_template/pull_request_template.md

@@ -0,0 +1,6 @@
+# Background
+
+# Related issues
+
+# Breaking Changes
+N/A

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Davide Asnaghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -26,7 +26,7 @@
 
 </p>
 
-# Bazel Rust Embedded Tools
+# Rust Embedded Tools
 
 This repository contains useful, cross-platform embedded tools that work out of the box in any Bazel project.
 
@@ -57,6 +57,21 @@ rust_embedded_deps()
 
 Head to the [Releases](https://github.com/d-asnaghi/bazel-rust-embedded/releases) page for more specific `WORKSPACE` settings
 
+## Dependencies
+
+At the moment, this is still a pre-release project. The build is not completely hermetic (it will be in the future) and requires to install the following dependencies based on your operating system
+
+### Linux
+
+`sudo apt install -y pkg-config libusb-1.0-0-dev libftdi1-dev`
+### Windows
+
+`vcpkg install libftdi1:x64-windows-static-md libusb:x64-windows-static-md`
+
+## Examples
+
+Head to the [examples](examples) directory where you can see how to use the rules in this repo to flash and debug ARM firmware targets using a custom toolchain.
+
 ## [Cargo Flash](https://crates.io/crates/cargo-flash)
 
 You can use cargo flash to load binaries or elf files to any target that uses a supported probe (JLink, STLink, Etc).
@@ -95,5 +110,64 @@ cargo_flash(
 ```
 
 Then `bazel run //package:flash_elf` and `bazel run //package:flash_bin` will load the file to the target
+## [Cargo Embed](https://crates.io/crates/cargo-embed)
+
+Cargo embed is a more powerful version of cargo-flash. It can be used to start a gdb server after flashing the probe. You have an option to specify a custom config to feed into cargo flash for maximum configurability.
+
+That config can also be an actual `.toml` file if you would rather have even more options.
 
+```python
+# package/BUILD
 
+load("@rust_embedded//:rules.bzl", "cargo_embed_config", "cargo_embed")
+
+cc_binary(
+    name = "firmware_elf",
+    ...
+)
+
+cargo_emebd_config(
+    name = "config",
+    flash = "true",
+    halt = "true",
+    gdb_enabled = "true",
+)
+
+cargo_embed(
+    name = "flash_debug",
+    file = ":firmware_elf",
+    chip = "STM32F103C8",
+    custom_config = ":config",
+)
+```
+
+# GDB targets
+
+Cargo embed exposes a GDB server, which can be connected to. For convenience, there are rules that specifically instantiate a GDB server and even launch the console for you.
+
+```python
+# package/BUILD
+
+load("@rust_embedded//:rules.bzl", "gdb_server", "gdb_console")
+
+cc_binary(
+    name = "firmware_elf",
+    ...
+)
+
+gdb_server(
+    name = "gdb-server",
+    file = ":firmware",
+    chip = "STM32F103C8",
+)
+
+gdb_console(
+    name = "gdb-console",
+    file = ":firmware_elf",
+    chip = "STM32F103C8",
+    gdb = "<label to gdb binary>",
+    gdb_commands = [
+        "b main",
+    ]
+)
+```