Merge #41

41: use LLD as the default linker r=therealprof a=japaric

closes #39

I added instructions on how to switch to a different linker to .cargo/config but
I don't think that's too visible. Beginners are unlikely to look into that file
if they run into problems with the default linker. Any suggestions to improve
the visibility of that information?

Also, don't merge this until the default linker changes for the Cortex-M targets
on nightly as this relies on that change.

r? @rust-embedded/cortex-m

Co-authored-by: Jorge Aparicio <jorge@japaric.io>

.cargo/config

@@ -1,27 +1,56 @@
 [target.thumbv6m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
+  # LLD (shipped with the Rust toolchain) is used as the default linker
-  "-C", "link-arg=-nostartfiles",
+  "-C", "link-arg=-Tlink.x",
+
+  # if you run into problems with LLD switch to the GNU linker by commenting out
+  # this line
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # if you need to link to pre-compiled C libraries provided by a C toolchain
+  # use GCC as the linker by commenting out both lines above and then
+  # uncommenting the three lines below
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
-  "-C", "link-arg=-nostartfiles",
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
-  "-C", "link-arg=-nostartfiles",
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabihf]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
-  "-C", "link-arg=-nostartfiles",
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]

.travis.yml

@@ -2,36 +2,24 @@ language: rust
 
 matrix:
   include:
+    - env: TARGET=x86_64-unknown-linux-gnu
+      rust: nightly
+      if: branch = master AND type != pull_request
+
     - env: TARGET=thumbv6m-none-eabi
       rust: nightly
-      addons:
-        apt:
-          packages:
-            - gcc-arm-none-eabi
       if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master)
 
     - env: TARGET=thumbv7m-none-eabi
       rust: nightly
-      addons:
-        apt:
-          packages:
-            - gcc-arm-none-eabi
       if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master)
 
     - env: TARGET=thumbv7em-none-eabi
       rust: nightly
-      addons:
-        apt:
-          packages:
-            - gcc-arm-none-eabi
       if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master)
 
     - env: TARGET=thumbv7em-none-eabihf
       rust: nightly
-      addons:
-        apt:
-          packages:
-            - gcc-arm-none-eabi
       if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master)
 
 before_install: set -e
@@ -42,6 +30,9 @@ install:
 script:
   - bash ci/script.sh
 
+after_success:
+  - bash ci/after-success.sh
+
 after_script: set +e
 
 cache: cargo

Cargo.toml

@@ -2,16 +2,17 @@
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
 categories = ["embedded", "no-std"]
 description = "A template for building applications for ARM Cortex-M microcontrollers"
+documentation = "https://rust-embedded.github.io/cortex-m-quickstart/cortex_m_quickstart"
 keywords = ["arm", "cortex-m", "template"]
 license = "MIT OR Apache-2.0"
 name = "cortex-m-quickstart"
 repository = "https://github.com/japaric/cortex-m-quickstart"
-version = "0.3.3"
+version = "0.3.4"
 
 [dependencies]
-cortex-m = "0.5.0"
+cortex-m = "0.5.6"
-cortex-m-rt = "0.5.0"
+cortex-m-rt = "0.5.3"
-cortex-m-semihosting = "0.3.0"
+cortex-m-semihosting = "0.3.1"
 panic-semihosting = "0.3.0"
 
 # Uncomment for the panic example.

ci/after-success.sh

@@ -0,0 +1,20 @@
+set -euxo pipefail
+
+main() {
+    cargo doc
+
+    mkdir ghp-import
+
+    curl -Ls https://github.com/davisp/ghp-import/archive/master.tar.gz |
+        tar --strip-components 1 -C ghp-import -xz
+
+    ./ghp-import/ghp_import.py target/doc
+
+    set +x
+    git push -fq https://$GH_TOKEN@github.com/$TRAVIS_REPO_SLUG.git gh-pages && echo OK
+}
+
+# only publish on successful merges to master
+if [ $TRAVIS_BRANCH = master ] && [ $TRAVIS_PULL_REQUEST = false ] && [ $TARGET = x86_64-unknown-linux-gnu ]; then
+    main
+fi

ci/install.sh

@@ -1,7 +1,9 @@
 set -euxo pipefail
 
 main() {
+    if [ $TARGET != x86_64-unknown-linux-gnu ]; then
         rustup target add $TARGET
+    fi
 }
 
 main

ci/script.sh

@@ -61,10 +61,12 @@ EOF
         examples+=( $ex )
     fi
 
-    IFS=,;eval arm-none-eabi-size target/$TARGET/release/examples/"{${examples[*]}}"
+    IFS=,;eval size target/$TARGET/release/examples/"{${examples[*]}}"
 
     popd
     rm -rf $td
 }
 
+if [ $TARGET != x86_64-unknown-linux-gnu ]; then
     main
+fi

examples/allocator.rs

@@ -11,7 +11,6 @@
 
 #![feature(alloc)]
 #![feature(alloc_error_handler)]
-#![feature(global_allocator)]
 #![feature(lang_items)]
 #![no_main]
 #![no_std]
@@ -58,7 +57,7 @@ fn main() -> ! {
 // define what happens in an Out Of Memory (OOM) condition
 #[alloc_error_handler]
 #[no_mangle]
-pub fn alloc_error(layout: Layout) -> ! {
+pub fn alloc_error(_layout: Layout) -> ! {
     asm::bkpt();
 
     loop {}

examples/minimal.rs

@@ -15,28 +15,19 @@
 //! define a panicking behavior is to link to a [panic handler crate][0]
 //!
 //! [0]: https://crates.io/keywords/panic-impl
-//!
-//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
-//! called when a hard fault exception is raised by the hardware.
-//!
-//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
-//!
-//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
-//! all interrupts and exceptions which have not been assigned a specific handler.
 
 #![no_main] // <- IMPORTANT!
 #![no_std]
 
 extern crate cortex_m;
 
-#[macro_use(entry, exception)]
+#[macro_use(entry)]
 extern crate cortex_m_rt as rt;
 
 // makes `panic!` print messages to the host stderr using semihosting
 extern crate panic_semihosting;
 
 use cortex_m::asm;
-use rt::ExceptionFrame;
 
 // the program entry point is ...
 entry!(main);
@@ -47,17 +38,3 @@ fn main() -> ! {
         asm::bkpt();
     }
 }
-
-// define the hard fault handler
-exception!(HardFault, hard_fault);
-
-fn hard_fault(ef: &ExceptionFrame) -> ! {
-    panic!("HardFault at {:#?}", ef);
-}
-
-// define the default exception handler
-exception!(*, default_handler);
-
-fn default_handler(irqn: i16) {
-    panic!("Unhandled exception (IRQn = {})", irqn);
-}

src/lib.rs

@@ -4,7 +4,6 @@
 //!
 //! - Nightly Rust toolchain newer than `nightly-2018-04-08`: `rustup default nightly`
 //! - Cargo `clone` subcommand: `cargo install cargo-clone`
-//! - ARM toolchain: `sudo apt-get install gcc-arm-none-eabi` (on Ubuntu)
 //! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
 //! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
@@ -179,11 +178,13 @@
 //! ``` text
 //! $ cargo build
 //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
-//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
+//! error: linking with `rust-lld` failed: exit code: 1
 //! |
-//! = note: "arm-none-eabi-gcc" "-L" (..)
+//! = note: "rust-lld" "-flavor" "gnu" "-L" (..)
+//! (..)
+//!  = note: rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by X bytes
+//!          rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by Y bytes
 //! (..)
-//!           (..)/ld: region `FLASH' overflowed by XXX bytes
 //! ```
 //!
 //! Solution: Specify your device memory layout in the `memory.x` linker script. See [Usage]
@@ -206,24 +207,15 @@
 //!
 //! ## Overwrote the original `.cargo/config` file
 //!
-//! Error message:
+//! You won't get an error message but the output binary will be empty
 //!
 //! ``` text
-//! error: linking with `arm-none-eabi-gcc` failed: exit code: 1
+//! $ cargo build && echo OK
-//!   |
+//! OK
-//!   = note: (..)
+//!
-//! (..)
+//! $ size target/thumbv7m-none-eabi/debug/app
-//! (..)/crt0.o: In function `_start':
+//!    text    data     bss     dec     hex filename
-//! (.text+0x90): undefined reference to `memset'
+//!       0       0       0       0       0 target/thumbv7m-none-eabi/debug/app
-//! (..)/crt0.o: In function `_start':
-//! (.text+0xd0): undefined reference to `atexit'
-//! (..)/crt0.o: In function `_start':
-//! (.text+0xd4): undefined reference to `__libc_init_array'
-//! (..)/crt0.o: In function `_start':
-//! (.text+0xe4): undefined reference to `exit'
-//! (..)/crt0.o: In function `_start':
-//! (.text+0x100): undefined reference to `__libc_fini_array'
-//! collect2: error: ld returned 1 exit status
 //! ```
 //!
 //! Solution: You probably overwrote the original `.cargo/config` instead of appending the default