Merge pull request #351 from posborne/doc-fixes

Documentation updates and fixes

Author: farcaller

.cargo/config

@@ -0,0 +1,11 @@
+[target.thumbv6-none-eabi]
+linker = "arm-none-eabi-gcc"
+ar = "arm-none-eabi-ar"
+
+[target.thumbv7m-none-eabi]
+linker = "arm-none-eabi-gcc"
+ar = "arm-none-eabi-ar"
+
+[target.thumbv7em-none-eabi]
+linker = "arm-none-eabi-gcc"
+ar = "arm-none-eabi-ar"

.gitignore

@@ -3,7 +3,6 @@
 .DS_Store
 Cargo.lock
 target
-.cargo
 *.o
 *.bin
 *.lst

Makefile.in

@@ -1,28 +1,60 @@
-[![Build Status](https://travis-ci.org/hackndev/zinc.svg)](https://travis-ci.org/hackndev/zinc) [![Stories in Ready](https://badge.waffle.io/hackndev/zinc.png?label=ready&title=Ready)](https://waffle.io/hackndev/zinc)
+[![Build Status](https://travis-ci.org/hackndev/zinc.svg)](https://travis-ci.org/hackndev/zinc)
+[![Stories in Ready](https://badge.waffle.io/hackndev/zinc.png?label=ready&title=Ready)](https://waffle.io/hackndev/zinc)
 Zinc, the bare metal stack for rust
 ===================================
 
 ## About zinc.rs
 
-Zinc is an experimental attempt to write an ARM stack that would be similar to CMSIS or mbed in capabilities but would show rust's best safety features applied to embedded development.
+Zinc is an experimental attempt to write an ARM stack that would be
+similar to CMSIS or mbed in capabilities but would show rust's best
+safety features applied to embedded development.
 
-Zinc is mostly assembly-free and completely C-free at the moment. One of the goals of zinc is to figure out, how much of the usual RTOS stack is it possible to write in rust in a safe manner, while keeping the resource usage profile low enough (comparable to C/C++ code).
+Zinc is mostly assembly-free and completely C-free at the moment. One
+of the goals of zinc is to figure out, how much of the usual RTOS
+stack is it possible to write in rust in a safe manner, while keeping
+the resource usage profile low enough (comparable to C/C++ code).
 
 Useful links:
 
  * [blog](http://zinc.rs/blog)
- * [build stats](http://zinc.rs/stats) (output binary size change over time)
+ * [build stats](http://zinc.rs/stats) (output binary size change over
+   time)
  * [api docs](http://zinc.rs/apidocs/zinc)
 
 ## Main features
 
-Zinc provides you with *safe* code in terms of rust code safety; accessing hardware directly is *unsafe*, but you can do that as well if you want.
+Zinc provides you with *safe* code in terms of rust code safety;
+accessing hardware directly is *unsafe*, but you can do that as well
+if you want.
 
-In addition to *software safety*, zinc provides *hardware safety* with Platform Tree specification; you define the hardware configuration right in the code in simple key-value DSL and compiler verifies that all hardware is configured properly; that also allows to optimize the code to much bigger extent than with conventional RTOSes.
+In addition to *software safety*, zinc provides *hardware safety* with
+Platform Tree specification; you define the hardware configuration
+right in the code in simple key-value DSL and compiler verifies that
+all hardware is configured properly; that also allows to optimize the
+code to much bigger extent than with conventional RTOSes.
+
+There is also an effort to generate platform tree specifications for
+new platforms from
+[ARM CMSIS SVDs](http://www.keil.com/pack/doc/CMSIS/SVD/html/index.html)
+such as those aggregated by the
+[cmsis-svd](http://www.keil.com/pack/doc/CMSIS/SVD/html/index.html)
+project.
 
 ## Supported hardware
 
-Zinc supports only ARM at the moment. The primary development is focused on two test boards with NXP LPC1768 and ST STM32F407. Other MCUs will follow when core API is stabilized.
+Some level of support is currently provided for the following
+processor families.  Not all peripherals are supported for all
+processors at this time.
+
+* NXP lpc11xx
+* NXP lpc17xx
+* Freescale k20
+* ST STM32f4
+* ST STM32l1
+
+In the future, a better story will be available that will allow for
+additional processor families, procesors, and boards using those
+processors to be defined more easily.
 
 ## License
 
@@ -32,21 +64,63 @@ Zinc is distributed under Apache-2.0, see LICENSE for more details.
 
 ### Environment Setup
 
-Get a gcc cross-toolchain for arm and make sure it is accessible.
+For the time being, Zinc makes use unstable features of the Rust
+language.  As such, we recommend using the latest nightly version of
+Rust for development.  As features of the language stabilize over
+time, it is the goal of Zinc to eventually be able to target stable
+versions of the compiler.
+[Multirust](https://github.com/brson/multirust) may be used to manage
+installations of multiple versions of rust on single machine.
+
+In addition to rust itself, a GCC cross-toolchain for ARM must be
+installed.  Although LLVM is used for a majority of compilation, the
+GCC Linker is still used at this time.  The
+[GCCM ARM Embedded toolchain](https://launchpad.net/gcc-arm-embedded/+download)
+works well for most people.
+
+### Building Examples Within Zinc
+
+There are several examples available within the Zinc source itself.
+Zinc makes use of Cargo for its build system, but it is still necesary
+to provide the build system with a few pieces of information for it to
+properly compile for your target.
 
-### Examples
+Namely, cargo must know about and have access to:
 
-First, generate a `Makefile` and `.cargo/config` with `configure` so cargo
-can find your toolchain. Your toolchain triple is probably `arm-none-eabi`
-````
-./configure PLATFORM=<platform> --host=<toolchain-triple>
-````
+1. The target specification for the machine being specified (consumed
+   by the compiler)
+2. A feature telling the code what platform is being targetted.  These
+   features are defined in the form `mcu_<platform>`.
 
-To build an application from examples/ use the following command after having
-run `configure`:
+Suppose we are targetting the `k20` platform.  In that case, I could
+build the `blink_k20` example program by doing the following.  Refer
+to (build-jenkins.sh)[support/build-jenkins.sh] for a mapping of
+platforms to targets.
 
 ```
-EXAMPLE_NAME=<example> make build
+$ cd examples/blink_k20
+$ ln -s ../../thumbv7em-none-eabi.json
+$ cargo build --target=thumbv7em-none-eabi --features mcu_k20 --release
+
+$ file target/thumbv7em-none-eabi/release/blink
+target/thumbv7em-none-eabi/release/blink: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, not stripped
+```
+
+If you receive link errors, you probably need to tell Cargo to use
+your cross-compilers linker.  You can do this by adding a
+`.cargo/config` to either your home directory or the root of the Zinc
+project:
+
+```toml
+[target.thumbv7em-none-eabi]
+linker = "arm-none-eabi-gcc"
+ar = "arm-none-eabi-ar"
 ```
 
-Ouput will go to `target/<target-triple>/release/examples`.
+### Using Zinc for your Project
+
+Sinc Zinc uses cargo for its build system, using Zinc from your own
+project just requires setting up your Cargo.toml correctly.
+
+You can find an example of how to do that here:
+https://github.com/posborne/zinc-example-lpc1768