force a single codegen unit on the dev profile

to work around problems with several codegen units, which is now the default for unoptimized builds
2017-11-19 03:58:24 +01:00
38 changed files with 1329 additions and 861 deletions
--- a/.cargo/config
+++ b/.cargo/config
@@ -1,40 +1,31 @@
-[target.thumbv7m-none-eabi]
+[target.thumbv6m-none-eabi]
-# uncomment this to make `cargo run` execute programs on QEMU
+runner = 'arm-none-eabi-gdb'
 # runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"
 [target.'cfg(all(target_arch = "arm", target_os = "none"))']
 # uncomment ONE of these three option to make `cargo run` start a GDB session
 # which option to pick depends on your system
 # runner = "arm-none-eabi-gdb -q -x openocd.gdb"
 # runner = "gdb-multiarch -q -x openocd.gdb"
 # runner = "gdb -q -x openocd.gdb"
 rustflags = [
  # This is needed if your flash or ram addresses are not aligned to 0x10000 in memory.x
  # See https://github.com/rust-embedded/cortex-m-quickstart/pull/95
  "-C", "link-arg=--nmagic",
  # LLD (shipped with the Rust toolchain) is used as the default linker
  "-C", "link-arg=-Tlink.x",
-
+  "-C", "linker=arm-none-eabi-ld",
-  # if you run into problems with LLD switch to the GNU linker by commenting out
+  "-Z", "linker-flavor=ld",
  # 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",
 ]
-[build]
+[target.thumbv7m-none-eabi]
-# Pick ONE of these compilation targets
+runner = 'arm-none-eabi-gdb'
-# target = "thumbv6m-none-eabi"        # Cortex-M0 and Cortex-M0+
+rustflags = [
-target = "thumbv7m-none-eabi"        # Cortex-M3
+  "-C", "link-arg=-Tlink.x",
-# target = "thumbv7em-none-eabi"       # Cortex-M4 and Cortex-M7 (no FPU)
+  "-C", "linker=arm-none-eabi-ld",
-# target = "thumbv7em-none-eabihf"     # Cortex-M4F and Cortex-M7F (with FPU)
+  "-Z", "linker-flavor=ld",
-# target = "thumbv8m.base-none-eabi"   # Cortex-M23
+]
-# target = "thumbv8m.main-none-eabi"   # Cortex-M33 (no FPU)
+
-# target = "thumbv8m.main-none-eabihf" # Cortex-M33 (with FPU)
+[target.thumbv7em-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
  "-C", "link-arg=-Tlink.x",
  "-C", "linker=arm-none-eabi-ld",
  "-Z", "linker-flavor=ld",
 ]
 [target.thumbv7em-none-eabihf]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
  "-C", "link-arg=-Tlink.x",
  "-C", "linker=arm-none-eabi-ld",
  "-Z", "linker-flavor=ld",
 ]
--- a/.gdbinit
+++ b/.gdbinit
@@ -0,0 +1,18 @@
 target remote :3333
 monitor arm semihosting enable
 # # send captured ITM to the file itm.fifo
 # # (the microcontroller SWO pin must be connected to the programmer SWO pin)
 # # 8000000 must match the core clock frequency
 # monitor tpiu config internal itm.fifo uart off 8000000
 # # OR: make the microcontroller SWO pin output compatible with UART (8N1)
 # # 2000000 is the frequency of the SWO pin
 # monitor tpiu config external uart off 8000000 2000000
 # # enable ITM port 0
 # monitor itm port 0 on
 load
 step
--- a/.gitignore
+++ b/.gitignore
@@ -1,13 +1,4 @@
 **/*.rs.bk
 .#*
 .gdb_history
 Cargo.lock
 target/
 # editor files
 .vscode/*
 !.vscode/*.md
 !.vscode/*.svd
 !.vscode/launch.json
 !.vscode/tasks.json
 !.vscode/extensions.json
--- a/.vscode/README.md
+++ b/.vscode/README.md
@@ -1,109 +0,0 @@
 # VS Code Configuration
 Example configurations for debugging programs in-editor with VS Code.  
 This directory contains configurations for two platforms:
 - `LM3S6965EVB` on QEMU
 - `STM32F303x` via OpenOCD
 ## Required Extensions
 If you have the `code` command in your path, you can run the following commands to install the necessary extensions.
 ```sh
 code --install-extension rust-lang.rust
 code --install-extension marus25.cortex-debug
 ```
 Otherwise, you can use the Extensions view to search for and install them, or go directly to their marketplace pages and click the "Install" button.
 - [Rust Language Server (RLS)](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust)
 - [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)
 ## Use
 The quickstart comes with two debug configurations.
 Both are configured to build the project, using the default settings from `.cargo/config`, prior to starting a debug session.
 1. QEMU: Starts a debug session using an emulation of the `LM3S6965EVB` mcu.
   - This works on a fresh `cargo generate` without modification of any of the settings described above.
   - Semihosting output will be written to the Output view `Adapter Output`.
   - `ITM` logging does not work with QEMU emulation.
 2. OpenOCD: Starts a debug session for a `STM32F3DISCOVERY` board (or any `STM32F303x` running at 8MHz).
   - Follow the instructions above for configuring the build with `.cargo/config` and the `memory.x` linker script.
   - `ITM` output will be written to the Output view `SWO: ITM [port: 0, type: console]` output.
 ### Git
 Files in the `.vscode/` directory are `.gitignore`d by default because many files that may end up in the `.vscode/` directory should not be committed and shared.  
 If you would like to save this debug configuration to your repository and share it with your team, you'll need to explicitly `git add` the files to your repository.
 ```sh
 git add -f .vscode/launch.json
 git add -f .vscode/tasks.json
 git add -f .vscode/*.svd
 ```
 ## Customizing for other targets
 For full documentation, see the [Cortex-Debug][cortex-debug] repository.
 ### Device
 Some configurations use this to automatically find the SVD file.  
 Replace this with the part number for your device.
 ```json
 "device": "STM32F303VCT6",
 ```
 ### OpenOCD Config Files
 The `configFiles` property specifies a list of files to pass to OpenOCD.
 ```json
 "configFiles": [
    "interface/stlink-v2-1.cfg",
    "target/stm32f3x.cfg"
 ],
 ```
 See the [OpenOCD config docs][openocd-config] for more information and the [OpenOCD repository for available configuration files][openocd-repo].
 ### SVD
 The SVD file is a standard way of describing all registers and peripherals of an ARM Cortex-M mCU.  
 Cortex-Debug needs this file to display the current register values for the peripherals on the device.  
 You can probably find the SVD for your device on the vendor's website.  
 For example, the STM32F3DISCOVERY board uses an mcu from the `STM32F303x` line of processors.  
 All the SVD files for the STM32F3 series are available on [ST's Website][stm32f3].  
 Download the [stm32f3 SVD pack][stm32f3-svd], and copy the `STM32F303.svd` file into `.vscode/`.  
 This line of the config tells the Cortex-Debug plug in where to find the file.
 ```json
 "svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
 ```
 For other processors, simply copy the correct `*.svd` file into the project and update the config accordingly.
 ### CPU Frequency
 If your device is running at a frequency other than 8MHz, you'll need to modify this line of `launch.json` for the `ITM` output to work correctly.
 ```json
 "cpuFrequency": 8000000,
 ```
 ### Other GDB Servers
 For information on setting up GDB servers other than OpenOCD, see the [Cortex-Debug repository][cortex-debug].
 [cortex-debug]: https://github.com/Marus/cortex-debug
 [stm32f3]: https://www.st.com/content/st_com/en/products/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus/stm32-mainstream-mcus/stm32f3-series.html#resource
 [stm32f3-svd]: https://www.st.com/resource/en/svd/stm32f3_svd.zip
 [openocd-config]: http://openocd.org/doc/html/Config-File-Guidelines.html
 [openocd-repo]: https://sourceforge.net/p/openocd/code/ci/master/tree/tcl/
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,14 +0,0 @@
 {
 	// 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",
 	],
 	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
 	"unwantedRecommendations": [
 	]
 }
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -1,52 +0,0 @@
 {
    /* 
     * Requires the Rust Language Server (RLS) and Cortex-Debug extensions
     * https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
     * https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug
     */
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug (QEMU)",
            "servertype": "qemu",
            "cwd": "${workspaceRoot}",
            "preLaunchTask": "Cargo Build (debug)",
            "runToMain": true,
            "executable": "./target/thumbv7m-none-eabi/debug/{{project-name}}",
            /* Run `cargo build --example hello` and uncomment this line to run semi-hosting example */
            //"executable": "./target/thumbv7m-none-eabi/debug/examples/hello",
            "cpu": "cortex-m3",
            "machine": "lm3s6965evb",
        },
        {
            /* Configuration for the STM32F303 Discovery board */
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug (OpenOCD)",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}",
            "preLaunchTask": "Cargo Build (debug)",
            "runToMain": true,
            "executable": "./target/thumbv7em-none-eabihf/debug/{{project-name}}",
            /* Run `cargo build --example itm` and uncomment this line to run itm example */
            // "executable": "./target/thumbv7em-none-eabihf/debug/examples/itm",
            "device": "STM32F303VCT6",
            "configFiles": [
                "interface/stlink-v2-1.cfg",
                "target/stm32f3x.cfg"
            ],
            "svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
            "swoConfig": {
                "enabled": true,
                "cpuFrequency": 8000000,
                "swoFrequency": 2000000,
                "source": "probe",
                "decoders": [
                    { "type": "console", "label": "ITM", "port": 0 }
                ]
            }
        }
    ]
 }
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -1,63 +0,0 @@
 {
    // See https://go.microsoft.com/fwlink/?LinkId=733558 
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            /*
             * This is the default cargo build task,
             * but we need to provide a label for it,
             * so we can invoke it from the debug launcher.
             */
            "label": "Cargo Build (debug)",
            "type": "process",
            "command": "cargo",
            "args": ["build"],
            "problemMatcher": [
                "$rustc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Cargo Build (release)",
            "type": "process",
            "command": "cargo",
            "args": ["build", "--release"],
            "problemMatcher": [
                "$rustc"
            ],
            "group": "build"
        },
        {
            "label": "Cargo Build Examples (debug)",
            "type": "process",
            "command": "cargo",
            "args": ["build","--examples"],
            "problemMatcher": [
                "$rustc"
            ],
            "group": "build"
        },
        {
            "label": "Cargo Build Examples (release)",
            "type": "process",
            "command": "cargo",
            "args": ["build","--examples", "--release"],
            "problemMatcher": [
                "$rustc"
            ],
            "group": "build"
        },
        {
            "label": "Cargo Clean",
            "type": "process",
            "command": "cargo",
            "args": ["clean"],
            "problemMatcher": [],
            "group": "build"
        },
    ]
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,87 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 ## [v0.1.8] - 2017-05-30
 ### Changed
 - Bumped the cortex-m-rt dependency to v0.2.3, and documented the `_stext`
  symbol (see memory.x).
 ## [v0.1.7] - 2017-05-27
 ### Added
 - Documentation and an example about how to use the heap and a dynamic memory
  allocator.
 ### Changed
 - Bumped the `cortex-m-rt` dependency to v0.2.2
 - Bumped the `cortex-m` dependency to v0.2.7
 ## [v0.1.6] - 2017-05-26
 ### Added
 - Set the default runner in .cargo/config to `arm-none-eabi-gdb`. Now `xargo
  run` will build the program and start a debug session.
 ## [v0.1.5] - 2017-05-16
 ### Added
 - A warning about using CARGO_INCREMENTAL to the how to use and the
  troubleshooting sections.
 ## [v0.1.4] - 2017-05-13
 ### Added
 - A dependencies section to the documentation
 ### Changed
 - Extend troubleshooting section
 ## [v0.1.3] - 2017-05-13
 ### Added
 - A troubleshooting section to the documentation
 ### Changed
 - Bumped the cortex-m crate version to v0.2.6
 ## [v0.1.2] - 2017-05-07
 ### Fixed
 - .gdbinit: jump to reset handler after loading the program.
 ## [v0.1.1] - 2017-04-27
 ### Changed
 - Bumped the version of the `cortex-m-rt` dependency to v0.2.0. NOTE that the
  instantiation steps have slightly changed, the `memory.x` file changed,
  because of this.
 ## v0.1.0 - 2017-04-25
 - Initial release
 [Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.8...HEAD
 [v0.1.8]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.7...v0.1.8
 [v0.1.7]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.6...v0.1.7
 [v0.1.6]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.5...v0.1.6
 [v0.1.5]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.4...v0.1.5
 [v0.1.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.3...v0.1.4
 [v0.1.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.2...v0.1.3
 [v0.1.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.1...v0.1.2
 [v0.1.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.0...v0.1.1
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,36 +1,20 @@
 [package]
-authors = ["{{authors}}"]
+authors = ["Jorge Aparicio <jorge@japaric.io>"]
-edition = "2018"
+categories = ["embedded", "no-std"]
-readme = "README.md"
+description = "A template for building applications for ARM Cortex-M microcontrollers"
-name = "{{project-name}}"
+keywords = ["arm", "cortex-m", "template"]
-version = "0.1.0"
+license = "MIT OR Apache-2.0"
 name = "cortex-m-quickstart"
 repository = "https://github.com/japaric/cortex-m-quickstart"
 version = "0.1.9"
 [dependencies]
-cortex-m = "0.6.0"
+cortex-m = "0.2.7"
-cortex-m-rt = "0.6.10"
+cortex-m-rt = "0.2.3"
 cortex-m-semihosting = "0.3.3"
 panic-halt = "0.2.0"
-# Uncomment for the panic example.
+[profile.dev]
-# panic-itm = "0.4.1"
+codegen-units = 1
 # Uncomment for the allocator example.
 # alloc-cortex-m = "0.4.0"
 # Uncomment for the device example.
 # Update `memory.x`, set target to `thumbv7em-none-eabihf` in `.cargo/config`,
 # and then use `cargo build --examples device` to build it.
 # [dependencies.stm32f3]
 # features = ["stm32f303", "rt"]
 # version = "0.7.1"
 # this lets you use `cargo fix`!
 [[bin]]
 name = "{{project-name}}"
 test = false
 bench = false
 [profile.release]
-codegen-units = 1 # better optimizations
+lto = true
-debug = true # symbols are nice and they don't increase the size on Flash
+debug = true
 lto = true # better optimizations
--- a/201
+++ b/201
@@ -0,0 +1,201 @@
                              Apache License
                        Version 2.0, January 2004
                     http://www.apache.org/licenses/
 TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 1. Definitions.
   "License" shall mean the terms and conditions for use, reproduction,
   and distribution as defined by Sections 1 through 9 of this document.
   "Licensor" shall mean the copyright owner or entity authorized by
   the copyright owner that is granting the License.
   "Legal Entity" shall mean the union of the acting entity and all
   other entities that control, are controlled by, or are under common
   control with that entity. For the purposes of this definition,
   "control" means (i) the power, direct or indirect, to cause the
   direction or management of such entity, whether by contract or
   otherwise, or (ii) ownership of fifty percent (50%) or more of the
   outstanding shares, or (iii) beneficial ownership of such entity.
   "You" (or "Your") shall mean an individual or Legal Entity
   exercising permissions granted by this License.
   "Source" form shall mean the preferred form for making modifications,
   including but not limited to software source code, documentation
   source, and configuration files.
   "Object" form shall mean any form resulting from mechanical
   transformation or translation of a Source form, including but
   not limited to compiled object code, generated documentation,
   and conversions to other media types.
   "Work" shall mean the work of authorship, whether in Source or
   Object form, made available under the License, as indicated by a
   copyright notice that is included in or attached to the work
   (an example is provided in the Appendix below).
   "Derivative Works" shall mean any work, whether in Source or Object
   form, that is based on (or derived from) the Work and for which the
   editorial revisions, annotations, elaborations, or other modifications
   represent, as a whole, an original work of authorship. For the purposes
   of this License, Derivative Works shall not include works that remain
   separable from, or merely link (or bind by name) to the interfaces of,
   the Work and Derivative Works thereof.
   "Contribution" shall mean any work of authorship, including
   the original version of the Work and any modifications or additions
   to that Work or Derivative Works thereof, that is intentionally
   submitted to Licensor for inclusion in the Work by the copyright owner
   or by an individual or Legal Entity authorized to submit on behalf of
   the copyright owner. For the purposes of this definition, "submitted"
   means any form of electronic, verbal, or written communication sent
   to the Licensor or its representatives, including but not limited to
   communication on electronic mailing lists, source code control systems,
   and issue tracking systems that are managed by, or on behalf of, the
   Licensor for the purpose of discussing and improving the Work, but
   excluding communication that is conspicuously marked or otherwise
   designated in writing by the copyright owner as "Not a Contribution."
   "Contributor" shall mean Licensor and any individual or Legal Entity
   on behalf of whom a Contribution has been received by Licensor and
   subsequently incorporated within the Work.
 2. Grant of Copyright License. Subject to the terms and conditions of
   this License, each Contributor hereby grants to You a perpetual,
   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
   copyright license to reproduce, prepare Derivative Works of,
   publicly display, publicly perform, sublicense, and distribute the
   Work and such Derivative Works in Source or Object form.
 3. Grant of Patent License. Subject to the terms and conditions of
   this License, each Contributor hereby grants to You a perpetual,
   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
   (except as stated in this section) patent license to make, have made,
   use, offer to sell, sell, import, and otherwise transfer the Work,
   where such license applies only to those patent claims licensable
   by such Contributor that are necessarily infringed by their
   Contribution(s) alone or by combination of their Contribution(s)
   with the Work to which such Contribution(s) was submitted. If You
   institute patent litigation against any entity (including a
   cross-claim or counterclaim in a lawsuit) alleging that the Work
   or a Contribution incorporated within the Work constitutes direct
   or contributory patent infringement, then any patent licenses
   granted to You under this License for that Work shall terminate
   as of the date such litigation is filed.
 4. Redistribution. You may reproduce and distribute copies of the
   Work or Derivative Works thereof in any medium, with or without
   modifications, and in Source or Object form, provided that You
   meet the following conditions:
   (a) You must give any other recipients of the Work or
       Derivative Works a copy of this License; and
   (b) You must cause any modified files to carry prominent notices
       stating that You changed the files; and
   (c) You must retain, in the Source form of any Derivative Works
       that You distribute, all copyright, patent, trademark, and
       attribution notices from the Source form of the Work,
       excluding those notices that do not pertain to any part of
       the Derivative Works; and
   (d) If the Work includes a "NOTICE" text file as part of its
       distribution, then any Derivative Works that You distribute must
       include a readable copy of the attribution notices contained
       within such NOTICE file, excluding those notices that do not
       pertain to any part of the Derivative Works, in at least one
       of the following places: within a NOTICE text file distributed
       as part of the Derivative Works; within the Source form or
       documentation, if provided along with the Derivative Works; or,
       within a display generated by the Derivative Works, if and
       wherever such third-party notices normally appear. The contents
       of the NOTICE file are for informational purposes only and
       do not modify the License. You may add Your own attribution
       notices within Derivative Works that You distribute, alongside
       or as an addendum to the NOTICE text from the Work, provided
       that such additional attribution notices cannot be construed
       as modifying the License.
   You may add Your own copyright statement to Your modifications and
   may provide additional or different license terms and conditions
   for use, reproduction, or distribution of Your modifications, or
   for any such Derivative Works as a whole, provided Your use,
   reproduction, and distribution of the Work otherwise complies with
   the conditions stated in this License.
 5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.
 6. Trademarks. This License does not grant permission to use the trade
   names, trademarks, service marks, or product names of the Licensor,
   except as required for reasonable and customary use in describing the
   origin of the Work and reproducing the content of the NOTICE file.
 7. Disclaimer of Warranty. Unless required by applicable law or
   agreed to in writing, Licensor provides the Work (and each
   Contributor provides its Contributions) on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
   implied, including, without limitation, any warranties or conditions
   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
   PARTICULAR PURPOSE. You are solely responsible for determining the
   appropriateness of using or redistributing the Work and assume any
   risks associated with Your exercise of permissions under this License.
 8. Limitation of Liability. In no event and under no legal theory,
   whether in tort (including negligence), contract, or otherwise,
   unless required by applicable law (such as deliberate and grossly
   negligent acts) or agreed to in writing, shall any Contributor be
   liable to You for damages, including any direct, indirect, special,
   incidental, or consequential damages of any character arising as a
   result of this License or out of the use or inability to use the
   Work (including but not limited to damages for loss of goodwill,
   work stoppage, computer failure or malfunction, or any and all
   other commercial damages or losses), even if such Contributor
   has been advised of the possibility of such damages.
 9. Accepting Warranty or Additional Liability. While redistributing
   the Work or Derivative Works thereof, You may choose to offer,
   and charge a fee for, acceptance of support, warranty, indemnity,
   or other liability obligations and/or rights consistent with this
   License. However, in accepting such obligations, You may act only
   on Your own behalf and on Your sole responsibility, not on behalf
   of any other Contributor, and only if You agree to indemnify,
   defend, and hold each Contributor harmless for any liability
   incurred by, or claims asserted against, such Contributor by reason
   of your accepting any such warranty or additional liability.
 END OF TERMS AND CONDITIONS
 APPENDIX: How to apply the Apache License to your work.
   To apply the Apache License to your work, attach the following
   boilerplate notice, with the fields enclosed by brackets "[]"
   replaced with your own identifying information. (Don't include
   the brackets!)  The text should be enclosed in the appropriate
   comment syntax for the file format. We also recommend that a
   file or class name and description of purpose be included on the
   same "printed page" as the copyright notice for easier
   identification within third-party archives.
 Copyright [yyyy] [name of copyright owner]
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 	http://www.apache.org/licenses/LICENSE-2.0
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
--- a/25
+++ b/25
@@ -0,0 +1,25 @@
 Copyright (c) 2017 {{toml-escape author}}
 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.
--- a/README.md
+++ b/README.md
@@ -2,115 +2,11 @@
 > A template for building applications for ARM Cortex-M microcontrollers
-This project is developed and maintained by the [Cortex-M team][team].
+# [Documentation](https://docs.rs/cortex-m-quickstart)
 ## Dependencies
 To build embedded programs using this template you'll need:
 - Rust 1.31, 1.30-beta, nightly-2018-09-13 or a newer toolchain. e.g. `rustup
  default beta`
 - The `cargo generate` subcommand. [Installation
  instructions](https://github.com/ashleygwilliams/cargo-generate#installation).
 - `rust-std` components (pre-compiled `core` crate) for the ARM Cortex-M
  targets. Run:
 ``` console
 $ rustup target add thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi thumbv7em-none-eabihf
 ```
 ## Using this template
 **NOTE**: This is the very short version that only covers building programs. For
 the long version, which additionally covers flashing, running and debugging
 programs, check [the embedded Rust book][book].
 [book]: https://rust-embedded.github.io/book
 0. Before we begin you need to identify some characteristics of the target
  device as these will be used to configure the project:
 - The ARM core. e.g. Cortex-M3.
 - Does the ARM core include an FPU? Cortex-M4**F** and Cortex-M7**F** cores do.
 - How much Flash memory and RAM does the target device has? e.g. 256 KiB of
  Flash and 32 KiB of RAM.
 - Where are Flash memory and RAM mapped in the address space? e.g. RAM is
  commonly located at address `0x2000_0000`.
 You can find this information in the data sheet or the reference manual of your
 device.
 In this example we'll be using the STM32F3DISCOVERY. This board contains an
 STM32F303VCT6 microcontroller. This microcontroller has:
 - A Cortex-M4F core that includes a single precision FPU
 - 256 KiB of Flash located at address 0x0800_0000.
 - 40 KiB of RAM located at address 0x2000_0000. (There's another RAM region but
  for simplicity we'll ignore it).
 1. Instantiate the template.
 ``` console
 $ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart
 Project Name: app
 Creating project called `app`...
 Done! New project created /tmp/app
 $ cd app
 ```
 2. Set a default compilation target. There are four options as mentioned at the
   bottom of `.cargo/config`. For the STM32F303VCT6, which has a Cortex-M4F
   core, we'll pick the `thumbv7em-none-eabihf` target.
 ``` console
 $ tail -n6 .cargo/config
 ```
 ``` toml
 [build]
 # Pick ONE of these compilation targets
 # target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
 # target = "thumbv7m-none-eabi"    # Cortex-M3
 # target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
 target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
 ```
 3. Enter the memory region information into the `memory.x` file.
 ``` console
 $ cat memory.x
 /* Linker script for the STM32F303VCT6 */
 MEMORY
 {
  /* NOTE 1 K = 1 KiBi = 1024 bytes */
  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
  RAM : ORIGIN = 0x20000000, LENGTH = 40K
 }
 ```
 4. Build the template application or one of the examples.
 ``` console
 $ cargo build
 ```
 ## VS Code
 This template includes launch configurations for debugging CortexM programs with Visual Studio Code located in the `.vscode/` directory.  
 See [.vscode/README.md](./.vscode/README.md) for more information.  
 If you're not using VS Code, you can safely delete the directory from the generated project.
 # License
-This template is licensed under either of
+Licensed under either of
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  http://www.apache.org/licenses/LICENSE-2.0)
@@ -124,12 +20,3 @@ at your option.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
 ## Code of Conduct
 Contribution to this crate is organized under the terms of the [Rust Code of
 Conduct][CoC], the maintainer of this crate, the [Cortex-M team][team], promises
 to intervene to uphold that code of conduct.
 [CoC]: https://www.rust-lang.org/policies/code-of-conduct
 [team]: https://github.com/rust-embedded/wg#the-cortex-m-team
--- a/Xargo.toml
+++ b/Xargo.toml
@@ -0,0 +1,6 @@
 [dependencies.core]
 [dependencies.compiler_builtins]
 features = ["mem"]
 git = "https://github.com/rust-lang-nursery/compiler-builtins"
 stage = 1
--- a/build.rs
+++ b/build.rs
@@ -1,21 +1,10 @@
 //! This build script copies the `memory.x` file from the crate root into
 //! a directory where the linker can always find it at build time.
 //! For many projects this is optional, as the linker always searches the
 //! project root directory -- wherever `Cargo.toml` is. However, if you
 //! are using a workspace or have a more complicated build setup, this
 //! build script becomes required. Additionally, by requesting that
 //! Cargo re-run the build script whenever `memory.x` is changed,
 //! updating `memory.x` ensures a rebuild of the application with the
 //! new memory settings.
 use std::env;
 use std::fs::File;
 use std::io::Write;
 use std::path::PathBuf;
 fn main() {
-    // Put `memory.x` in our output directory and ensure it's
+    // Put the linker script somewhere the linker can find it
    // on the linker search path.
    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
    File::create(out.join("memory.x"))
        .unwrap()
@@ -23,9 +12,6 @@ fn main() {
        .unwrap();
    println!("cargo:rustc-link-search={}", out.display());
-    // By default, Cargo will re-run a build script whenever
+    println!("cargo:rerun-if-changed=build.rs");
    // any file in the project changes. By specifying `memory.x`
    // here, we ensure the build script is only re-run when
    // `memory.x` is changed.
    println!("cargo:rerun-if-changed=memory.x");
 }
--- a/examples/allocator.rs
+++ b/examples/allocator.rs
@@ -1,56 +1,71 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml:
+//! To compile this example you'll need to build the collections crate as part
 //! of the Xargo sysroot. To do that change the Xargo.toml file to look like
 //! this:
 //!
 //! ``` text
 //! [dependencies.core]
 //! [dependencies.collections] # new
 //!
 //! [dependencies.compiler_builtins]
 //! features = ["mem"]
 //! git = "https://github.com/rust-lang-nursery/compiler-builtins"
 //! stage = 1
 //! ```
 //!
 //! This example depends on the alloc-cortex-m crate so you'll have to add it
 //! to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
 //! $ cargo add alloc-cortex-m
 //! ```
 //!
 //! ---
-#![feature(alloc_error_handler)]
+#![feature(collections)]
-#![no_main]
+#![feature(used)]
 #![no_std]
-extern crate alloc;
+// This is the allocator crate; you can use a different one
-use panic_halt as _;
+extern crate alloc_cortex_m;
 #[macro_use]
 extern crate collections;
 #[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
 use self::alloc::vec;
 use core::alloc::Layout;
 use alloc_cortex_m::CortexMHeap;
 use cortex_m::asm;
 use cortex_m_rt::entry;
 use cortex_m_semihosting::{hprintln, debug};
-// this is the allocator the application will use
+fn main() {
-#[global_allocator]
+    // Initialize the allocator
-static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
+    unsafe {
        extern "C" {
            // Start of the heap
            static mut _sheap: usize;
        }
-const HEAP_SIZE: usize = 1024; // in bytes
+        // Size of the heap in words (1 word = 4 bytes)
        // WARNING: The bigger the heap the greater the chance to run into a
        // stack overflow (collision between the stack and the heap)
        const SIZE: isize = 256;
-#[entry]
+        // End of the heap
-fn main() -> ! {
+        let _eheap = (&mut _sheap as *mut _).offset(SIZE);
-    // Initialize the allocator BEFORE you use it
+
-    unsafe { ALLOCATOR.init(cortex_m_rt::heap_start() as usize, HEAP_SIZE) }
+        alloc_cortex_m::init(&mut _sheap as *mut _, _eheap);
    }
    // Growable array allocated on the heap
    let xs = vec![0, 1, 2];
-
+    hprintln!("{:?}", xs);
    hprintln!("{:?}", xs).unwrap();
    // exit QEMU
    // NOTE do not run this on hardware; it can corrupt OpenOCD state
    debug::exit(debug::EXIT_SUCCESS);
    loop {}
 }
-// define what happens in an Out Of Memory (OOM) condition
+// As we are not using interrupts, we just register a dummy catch all handler
-#[alloc_error_handler]
+#[allow(dead_code)]
-fn alloc_error(_layout: Layout) -> ! {
+#[used]
 #[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 extern "C" fn default_handler() {
    asm::bkpt();
    loop {}
 }
--- a/examples/crash.rs
+++ b/examples/crash.rs
@@ -1,96 +1,58 @@
 //! Debugging a crash (exception)
 //!
-//! Most crash conditions trigger a hard fault exception, whose handler is defined via
+//! The `cortex-m-rt` crate provides functionality for this through a default
-//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
+//! exception handler. When an exception is hit, the default handler will
-//! snapshot of the CPU registers at the moment of the exception.
+//! trigger a breakpoint and in this debugging context the stacked registers
 //! are accessible.
 //!
-//! This program crashes and the `HardFault` handler prints to the console the contents of the
+//! In you run the example below, you'll be able to inspect the state of your
-//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! program under the debugger using these commands:
 //! that led to the exception.
 //!
-//! ``` text
+//! ```
-//! (gdb) continue
+//! (gdb) # Stacked registers = program state during the crash
-//! Program received signal SIGTRAP, Trace/breakpoint trap.
+//! (gdb) print/x *_sr
-//! __bkpt () at asm/bkpt.s:3
+//! $1 = cortex_m::exception::StackedRegisters {
-//! 3         bkpt
+//!   r0 = 0x2fffffff,
 //!   r1 = 0x2fffffff,
 //!   r2 = 0x0,
 //!   r3 = 0x0,
 //!   r12 = 0x0,
 //!   lr = 0x8000443,
 //!   pc = 0x8000190,
 //!   xpsr = 0x61000200,
 //! }
 //!
 //! (gdb) # What exception was triggered?
 //! (gdb) print _e
 //! $2 = cortex_m::exception::Exception::HardFault
 //!
 //! (gdb) # Where did we come from?
 //! (gdb) backtrace
 //! #0  __bkpt () at asm/bkpt.s:3
 //! #1  0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19
 //! #2  rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87
 //! #3  0x08001d06 in core::panicking::panic_fmt () at libcore/panicking.rs:71
 //! #4  0x080004a6 in crash::hard_fault (ef=0x20004fa0) at examples/crash.rs:99
 //! #5  0x08000548 in UserHardFault (ef=0x20004fa0) at <exception macros>:10
 //! #6  0x0800093a in HardFault () at asm.s:5
 //! Backtrace stopped: previous frame identical to this frame (corrupt stack?)
 //! ```
 //!
 //! In the console output one will find the state of the Program Counter (PC) register at the time
 //! of the exception.
 //!
 //! ``` text
 //! panicked at 'HardFault at ExceptionFrame {
 //!     r0: 0x2fffffff,
 //!     r1: 0x2fffffff,
 //!     r2: 0x080051d4,
 //!     r3: 0x080051d4,
 //!     r12: 0x20000000,
 //!     lr: 0x08000435,
 //!     pc: 0x08000ab6,
 //!     xpsr: 0x61000000
 //! }', examples/crash.rs:106:5
 //! ```
 //!
 //! This register contains the address of the instruction that caused the exception. In GDB one can
 //! disassemble the program around this address to observe the instruction that caused the
 //! exception.
 //!
 //! ``` text
 //! (gdb) disassemble/m 0x08000ab6
 //! Dump of assembler code for function core::ptr::read_volatile:
 //! 451     pub unsafe fn read_volatile<T>(src: *const T) -> T {
 //!    0x08000aae <+0>:     sub     sp, #16
 //!    0x08000ab0 <+2>:     mov     r1, r0
 //!    0x08000ab2 <+4>:     str     r0, [sp, #8]
 //!
 //! 452         intrinsics::volatile_load(src)
 //!    0x08000ab4 <+6>:     ldr     r0, [sp, #8]
 //! -> 0x08000ab6 <+8>:     ldr     r0, [r0, #0]
 //!    0x08000ab8 <+10>:    str     r0, [sp, #12]
 //!    0x08000aba <+12>:    ldr     r0, [sp, #12]
 //!    0x08000abc <+14>:    str     r1, [sp, #4]
 //!    0x08000abe <+16>:    str     r0, [sp, #0]
 //!    0x08000ac0 <+18>:    b.n     0x8000ac2 <core::ptr::read_volatile+20>
 //!
 //! 453     }
 //!    0x08000ac2 <+20>:    ldr     r0, [sp, #0]
 //!    0x08000ac4 <+22>:    add     sp, #16
 //!    0x08000ac6 <+24>:    bx      lr
 //!
 //! End of assembler dump.
 //! ```
 //!
 //! `ldr r0, [r0, #0]` caused the exception. This instruction tried to load (read) a 32-bit word
 //! from the address stored in the register `r0`. Looking again at the contents of `ExceptionFrame`
 //! we see that the `r0` contained the address `0x2FFF_FFFF` when this instruction was executed.
 //!
 //! ---
-#![no_main]
+#![feature(used)]
 #![no_std]
-use panic_halt as _;
+extern crate cortex_m;
 extern crate cortex_m_rt;
 use core::ptr;
-use cortex_m_rt::entry;
+use cortex_m::asm;
-#[entry]
+fn main() {
-fn main() -> ! {
+    // Read an invalid memory address
    unsafe {
        // read an address outside of the RAM region; this causes a HardFault exception
        ptr::read_volatile(0x2FFF_FFFF as *const u32);
    }
-
+}
-    loop {}
+
 // As we are not using interrupts, we just register a dummy catch all handler
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 extern "C" fn default_handler() {
    asm::bkpt();
 }
--- a/examples/device.rs
+++ b/examples/device.rs
@@ -1,62 +0,0 @@
 //! Using a device crate
 //!
 //! Crates generated using [`svd2rust`] are referred to as device crates. These crates provide an
 //! API to access the peripherals of a device.
 //!
 //! [`svd2rust`]: https://crates.io/crates/svd2rust
 //!
 //! This example depends on the [`stm32f3`] crate so you'll have to
 //! uncomment it in your Cargo.toml.
 //!
 //! [`stm32f3`]: https://crates.io/crates/stm32f3
 //!
 //! ```
 //! $ edit Cargo.toml && tail $_
 //! [dependencies.stm32f3]
 //! features = ["stm32f303", "rt"]
 //! version = "0.7.1"
 //! ```
 //!
 //! You also need to set the build target to thumbv7em-none-eabihf,
 //! typically by editing `.cargo/config` and uncommenting the relevant target line.
 //!
 //! ---
 #![no_main]
 #![no_std]
 #[allow(unused_extern_crates)]
 use panic_halt as _;
 use cortex_m::peripheral::syst::SystClkSource;
 use cortex_m_rt::entry;
 use cortex_m_semihosting::hprint;
 use stm32f3::stm32f303::{interrupt, Interrupt, NVIC};
 #[entry]
 fn main() -> ! {
    let p = cortex_m::Peripherals::take().unwrap();
    let mut syst = p.SYST;
    let mut nvic = p.NVIC;
    nvic.enable(Interrupt::EXTI0);
    // configure the system timer to wrap around every second
    syst.set_clock_source(SystClkSource::Core);
    syst.set_reload(8_000_000); // 1s
    syst.enable_counter();
    loop {
        // busy wait until the timer wraps around
        while !syst.has_wrapped() {}
        // trigger the `EXTI0` interrupt
        NVIC::pend(Interrupt::EXTI0);
    }
 }
 #[interrupt]
 fn EXTI0() {
    hprint!(".").unwrap();
 }
--- a/examples/exception.rs
+++ b/examples/exception.rs
@@ -1,37 +0,0 @@
 //! Overriding an exception handler
 //!
 //! You can override an exception handler using the [`#[exception]`][1] attribute.
 //!
 //! [1]: https://rust-embedded.github.io/cortex-m-rt/0.6.1/cortex_m_rt_macros/fn.exception.html
 //!
 //! ---
 #![deny(unsafe_code)]
 #![no_main]
 #![no_std]
 use panic_halt as _;
 use cortex_m::peripheral::syst::SystClkSource;
 use cortex_m::Peripherals;
 use cortex_m_rt::{entry, exception};
 use cortex_m_semihosting::hprint;
 #[entry]
 fn main() -> ! {
    let p = Peripherals::take().unwrap();
    let mut syst = p.SYST;
    // configures the system timer to trigger a SysTick exception every second
    syst.set_clock_source(SystClkSource::Core);
    syst.set_reload(8_000_000); // period = 1s
    syst.enable_counter();
    syst.enable_interrupt();
    loop {}
 }
 #[exception]
 fn SysTick() {
    hprint!(".").unwrap();
 }
--- a/examples/hello.rs
+++ b/examples/hello.rs
@@ -1,20 +1,24 @@
-//! Prints "Hello, world!" on the host console using semihosting
+//! Prints "Hello, world!" on the OpenOCD console using semihosting
-#![no_main]
+#![feature(used)]
 #![no_std]
-use panic_halt as _;
+#[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
-use cortex_m_rt::entry;
+use cortex_m::asm;
 use cortex_m_semihosting::{debug, hprintln};
-#[entry]
+fn main() {
-fn main() -> ! {
+    hprintln!("Hello, world!");
-    hprintln!("Hello, world!").unwrap();
+}
-
+
-    // exit QEMU
+// As we are not using interrupts, we just register a dummy catch all handler
-    // NOTE do not run this on hardware; it can corrupt OpenOCD state
+#[allow(dead_code)]
-    debug::exit(debug::EXIT_SUCCESS);
+#[used]
-
+#[link_section = ".rodata.interrupts"]
-    loop {}
+static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 extern "C" fn default_handler() {
    asm::bkpt();
 }
--- a/examples/itm.rs
+++ b/examples/itm.rs
@@ -1,33 +1,41 @@
 //! Sends "Hello, world!" through the ITM port 0
 //!
 //! **IMPORTANT** Not all Cortex-M chips support ITM. You'll have to connect the
 //! microcontroller's SWO pin to the SWD interface. Note that some development
 //! boards don't provide this option.
 //!
 //! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
 //!
-//! **NOTE** Cortex-M0 chips don't support ITM.
+//! You'll need [`itmdump`] to receive the message on the host plus you'll need
 //! to uncomment OpenOCD's ITM support in `.gdbinit`.
 //!
-//! You'll have to connect the microcontroller's SWO pin to the SWD interface. Note that some
+//! [`itmdump`]: https://docs.rs/itm/0.1.1/itm/
 //! development boards don't provide this option.
 //!
 //! You'll need [`itmdump`] to receive the message on the host plus you'll need to uncomment two
 //! `monitor` commands in the `.gdbinit` file.
 //!
 //! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/
 //!
 //! ---
-#![no_main]
+#![feature(used)]
 #![no_std]
-use panic_halt as _;
+#[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
-use cortex_m::{iprintln, Peripherals};
+use cortex_m::{asm, interrupt, peripheral};
 use cortex_m_rt::entry;
-#[entry]
+fn main() {
-fn main() -> ! {
+    interrupt::free(
-    let mut p = Peripherals::take().unwrap();
+        |cs| {
-    let stim = &mut p.ITM.stim[0];
+            let itm = peripheral::ITM.borrow(&cs);
-    iprintln!(stim, "Hello, world!");
+            iprintln!(&itm.stim[0], "Hello, world!");
-
+        },
-    loop {}
+    );
 }
 // As we are not using interrupts, we just register a dummy catch all handler
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 extern "C" fn default_handler() {
    asm::bkpt();
 }
--- a/examples/override-exception-handler.rs
+++ b/examples/override-exception-handler.rs
@@ -0,0 +1,46 @@
 //! Overriding an exception
 //!
 //! **NOTE** You have to disable the `cortex-m-rt` crate's "exceptions" feature
 //! to make this work.
 #![feature(used)]
 #![no_std]
 extern crate cortex_m;
 extern crate cortex_m_rt;
 use core::ptr;
 use cortex_m::{asm, exception};
 fn main() {
    unsafe {
        // Invalid memory access
        ptr::read_volatile(0x2FFF_FFFF as *const u32);
    }
 }
 extern "C" fn hard_fault(_: exception::HardFault) {
    // You'll hit this breakpoint rather than the one in cortex-m-rt
    asm::bkpt()
 }
 // When the "exceptions" feature is disabled, you'll have to provide this symbol
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.exceptions"]
 static EXCEPTIONS: exception::Handlers = exception::Handlers {
    // This is the exception handler override
    hard_fault: hard_fault,
    ..exception::DEFAULT_HANDLERS
 };
 // As we are not using interrupts, we just register a dummy catch all handler
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 extern "C" fn default_handler() {
    asm::bkpt();
 }
--- a/examples/panic.rs
+++ b/examples/panic.rs
@@ -1,28 +1,35 @@
-//! Changing the panicking behavior
+//! Redirecting `panic!` messages
 //!
-//! The easiest way to change the panicking behavior is to use a different [panic handler crate][0].
+//! The `cortex-m-rt` crate provides two options to redirect `panic!` messages
 //! through these two Cargo features:
 //!
-//! [0]: https://crates.io/keywords/panic-impl
+//! - `panic-over-semihosting`. `panic!` messages will be printed to the OpenOCD
 //!    console using semihosting. This is slow.
 //!
 //! - `panic-over-itm`. `panic!` messages will be send through the ITM port 0.
 //!   This is much faster but requires ITM support on the device.
 //!
 //! If neither of these options is specified then the `panic!` message will be
 //! lost. Note that all `panic!`s will trigger a debugger breakpoint.
-#![no_main]
+#![feature(used)]
 #![no_std]
-// Pick one of these panic handlers:
+extern crate cortex_m;
 extern crate cortex_m_rt;
-// `panic!` halts execution; the panic message is ignored
+use cortex_m::asm;
 use panic_halt as _;
-// Reports panic messages to the host stderr using semihosting
+fn main() {
-// NOTE to use this you need to uncomment the `panic-semihosting` dependency in Cargo.toml
+    panic!("Oops");
-// use panic_semihosting as _;
+}
-
+
-// Logs panic messages using the ITM (Instrumentation Trace Macrocell)
+// As we are not using interrupts, we just register a dummy catch all handler
-// NOTE to use this you need to uncomment the `panic-itm` dependency in Cargo.toml
+#[allow(dead_code)]
-// use panic_itm as _;
+#[used]
-
+#[link_section = ".rodata.interrupts"]
-use cortex_m_rt::entry;
+static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
+
-#[entry]
+extern "C" fn default_handler() {
-fn main() -> ! {
+    asm::bkpt();
    panic!("Oops")
 }
--- a/examples/register-interrupt-handler.rs
+++ b/examples/register-interrupt-handler.rs
@@ -0,0 +1,36 @@
 //! Register an interrupt handler
 //!
 //! NOTE Requires a device crate generated using `svd2rust`
 #![feature(used)]
 #![no_std]
 extern crate cortex_m;
 extern crate cortex_m_rt;
 // NOTE this is the device crate
 extern crate stm32f30x;
 use cortex_m::asm;
 use stm32f30x::interrupt;
 fn main() {}
 // NOTE each interrupt handler has a different signature
 extern "C" fn my_interrupt_handler(_ctxt: interrupt::Tim7) {
    asm::bkpt();
 }
 extern "C" fn another_interrupt_handler(_ctxt: interrupt::Exti0) {
    asm::bkpt();
 }
 // Here we override only two interrupt handlers, the rest of interrupt are
 // handled by the same interrupt handler
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.interrupts"]
 static INTERRUPTS: interrupt::Handlers = interrupt::Handlers {
    Tim7: my_interrupt_handler,
    Exti0: another_interrupt_handler,
    ..interrupt::DEFAULT_HANDLERS
 };
--- a/examples/test_on_host.rs
+++ b/examples/test_on_host.rs
@@ -1,57 +0,0 @@
 //! Conditionally compiling tests with std and our executable with no_std.
 //!
 //! Rust's built in unit testing framework requires the standard library,
 //! but we need to build our final executable with no_std.
 //! The testing framework also generates a `main` method, so we need to only use the `#[entry]`
 //! annotation when building our final image.
 //! For more information on why this example works, see this excellent blog post.
 //! https://os.phil-opp.com/unit-testing/
 //!
 //! Running this example:
 //!
 //! Ensure there are no targets specified under `[build]` in `.cargo/config`
 //! In order to make this work, we lose the convenience of having a default target that isn't the
 //! host.
 //!
 //! cargo build --example test_on_host --target thumbv7m-none-eabi
 //! cargo test --example test_on_host
 #![cfg_attr(test, allow(unused_imports))]
 #![cfg_attr(not(test), no_std)]
 #![cfg_attr(not(test), no_main)]
 // pick a panicking behavior
 #[cfg(not(test))]
 use panic_halt as _; // you can put a breakpoint on `rust_begin_unwind` to catch panics
 // use panic_abort as _; // requires nightly
 // use panic_itm as _; // logs messages over ITM; requires ITM support
 // use panic_semihosting as _; // logs messages to the host stderr; requires a debugger
 use cortex_m::asm;
 use cortex_m_rt::entry;
 #[cfg(not(test))]
 #[entry]
 fn main() -> ! {
    asm::nop(); // To not have main optimize to abort in release mode, remove when you add code
    loop {
        // your code goes here
    }
 }
 fn add(a: i32, b: i32) -> i32 {
    a + b
 }
 #[cfg(test)]
 mod test {
  use super::*;
  #[test]
  fn foo() {
    println!("tests work!");
    assert!(2 == add(1,1));
  }
 }
--- a/gen-examples.sh
+++ b/gen-examples.sh
@@ -0,0 +1,55 @@
 # Converts the examples in the `examples` directory into documentation in the
 # `examples` module (`src/examples/*.rs`)
 set -ex
 main() {
    local examples=(
        hello
        itm
        panic
        crash
        register-interrupt-handler
        override-exception-handler
        allocator
    )
    rm -rf src/examples
    mkdir src/examples
    cat >src/examples/mod.rs <<'EOF'
 //! Examples
 // Auto-generated. Do not modify.
 EOF
    local i=0 out=
    for ex in ${examples[@]}; do
        name=_${i}_${ex//-/_}
        out=src/examples/${name}.rs
        echo "pub mod $name;" >> src/examples/mod.rs
        grep '//!' examples/$ex.rs > $out
        echo '//!' >> $out
        echo '//! ```' >> $out
        grep -v '//!' examples/$ex.rs | (
            IFS=''
            while read line; do
                echo "//! $line" >> $out;
            done
        )
        echo '//! ```' >> $out
        echo '// Auto-generated. Do not modify.' >> $out
        chmod -x $out
        i=$(( i + 1 ))
    done
    chmod -x src/examples/mod.rs
 }
 main
--- a/memory.x
+++ b/memory.x
@@ -1,34 +1,19 @@
 MEMORY
 {
-  /* NOTE 1 K = 1 KiBi = 1024 bytes */
+  /* NOTE K = KiBi = 1024 bytes */
  /* TODO Adjust these memory regions to match your device memory layout */
-  /* These values correspond to the LM3S6965, one of the few devices QEMU can emulate */
+  FLASH : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
-  FLASH : ORIGIN = 0x00000000, LENGTH = 256K
+  RAM : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
  RAM : ORIGIN = 0x20000000, LENGTH = 64K
 }
 /* This is where the call stack will be allocated. */
 /* The stack is of the full descending type. */
-/* You may want to use this variable to locate the call stack and static
+/* NOTE Do NOT modify `_stack_start` unless you know what you are doing */
-   variables in different memory regions. Below is shown the default value */
+_stack_start = ORIGIN(RAM) + LENGTH(RAM);
 /* _stack_start = ORIGIN(RAM) + LENGTH(RAM); */
 /* You can use this symbol to customize the location of the .text section */
 /* If omitted the .text section will be placed right after the .vector_table
   section */
-/* This is required only on microcontrollers that store some configuration right
+/* This is required only on some microcontrollers that store some configuration
-   after the vector table */
+   right after the vector table */
 /* _stext = ORIGIN(FLASH) + 0x400; */
 /* Example of putting non-initialized variables into custom RAM locations. */
 /* This assumes you have defined a region RAM2 above, and in the Rust
   sources added the attribute `#[link_section = ".ram2bss"]` to the data
   you want to place there. */
 /* Note that the section will not be zero-initialized by the runtime! */
 /* SECTIONS {
     .ram2bss (NOLOAD) : ALIGN(4) {
       *(.ram2bss);
       . = ALIGN(4);
     } > RAM2
   } INSERT AFTER .bss;
 */
--- a/openocd.cfg
+++ b/openocd.cfg
@@ -1,12 +0,0 @@
 # Sample OpenOCD configuration for the STM32F3DISCOVERY development board
 # Depending on the hardware revision you got you'll have to pick ONE of these
 # interfaces. At any time only one interface should be commented out.
 # Revision C (newer revision)
 source [find interface/stlink-v2-1.cfg]
 # Revision A and B (older revisions)
 # source [find interface/stlink-v2.cfg]
 source [find target/stm32f3x.cfg]
--- a/openocd.gdb
+++ b/openocd.gdb
@@ -1,40 +0,0 @@
 target extended-remote :3333
 # print demangled symbols
 set print asm-demangle on
 # set backtrace limit to not have infinite backtrace loops
 set backtrace limit 32
 # detect unhandled exceptions, hard faults and panics
 break DefaultHandler
 break HardFault
 break rust_begin_unwind
 # # run the next few lines so the panic message is printed immediately
 # # the number needs to be adjusted for your panic handler
 # commands $bpnum
 # next 4
 # end
 # *try* to stop at the user entry point (it might be gone due to inlining)
 break main
 monitor arm semihosting enable
 # # send captured ITM to the file itm.fifo
 # # (the microcontroller SWO pin must be connected to the programmer SWO pin)
 # # 8000000 must match the core clock frequency
 # monitor tpiu config internal itm.txt uart off 8000000
 # # OR: make the microcontroller SWO pin output compatible with UART (8N1)
 # # 8000000 must match the core clock frequency
 # # 2000000 is the frequency of the SWO pin
 # monitor tpiu config external uart off 8000000 2000000
 # # enable ITM port 0
 # monitor itm port 0 on
 load
 # start the process but immediately halt the processor
 stepi
--- a/src/examples/_0_hello.rs
+++ b/src/examples/_0_hello.rs
@@ -0,0 +1,28 @@
 //! Prints "Hello, world!" on the OpenOCD console using semihosting
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use cortex_m::asm;
 //! 
 //! fn main() {
 //!     hprintln!("Hello, world!");
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_1_itm.rs
+++ b/src/examples/_1_itm.rs
@@ -0,0 +1,45 @@
 //! Sends "Hello, world!" through the ITM port 0
 //!
 //! **IMPORTANT** Not all Cortex-M chips support ITM. You'll have to connect the
 //! microcontroller's SWO pin to the SWD interface. Note that some development
 //! boards don't provide this option.
 //!
 //! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
 //!
 //! You'll need [`itmdump`] to receive the message on the host plus you'll need
 //! to uncomment OpenOCD's ITM support in `.gdbinit`.
 //!
 //! [`itmdump`]: https://docs.rs/itm/0.1.1/itm/
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use cortex_m::{asm, interrupt, peripheral};
 //! 
 //! fn main() {
 //!     interrupt::free(
 //!         |cs| {
 //!             let itm = peripheral::ITM.borrow(&cs);
 //! 
 //!             iprintln!(&itm.stim[0], "Hello, world!");
 //!         },
 //!     );
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_2_panic.rs
+++ b/src/examples/_2_panic.rs
@@ -0,0 +1,39 @@
 //! Redirecting `panic!` messages
 //!
 //! The `cortex-m-rt` crate provides two options to redirect `panic!` messages
 //! through these two Cargo features:
 //!
 //! - `panic-over-semihosting`. `panic!` messages will be printed to the OpenOCD
 //!    console using semihosting. This is slow.
 //!
 //! - `panic-over-itm`. `panic!` messages will be send through the ITM port 0.
 //!   This is much faster but requires ITM support on the device.
 //!
 //! If neither of these options is specified then the `panic!` message will be
 //! lost. Note that all `panic!`s will trigger a debugger breakpoint.
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use cortex_m::asm;
 //! 
 //! fn main() {
 //!     panic!("Oops");
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_3_crash.rs
+++ b/src/examples/_3_crash.rs
@@ -0,0 +1,62 @@
 //! Debugging a crash (exception)
 //!
 //! The `cortex-m-rt` crate provides functionality for this through a default
 //! exception handler. When an exception is hit, the default handler will
 //! trigger a breakpoint and in this debugging context the stacked registers
 //! are accessible.
 //!
 //! In you run the example below, you'll be able to inspect the state of your
 //! program under the debugger using these commands:
 //!
 //! ```
 //! (gdb) # Stacked registers = program state during the crash
 //! (gdb) print/x *_sr
 //! $1 = cortex_m::exception::StackedRegisters {
 //!   r0 = 0x2fffffff,
 //!   r1 = 0x2fffffff,
 //!   r2 = 0x0,
 //!   r3 = 0x0,
 //!   r12 = 0x0,
 //!   lr = 0x8000443,
 //!   pc = 0x8000190,
 //!   xpsr = 0x61000200,
 //! }
 //!
 //! (gdb) # What exception was triggered?
 //! (gdb) print _e
 //! $2 = cortex_m::exception::Exception::HardFault
 //!
 //! (gdb) # Where did we come from?
 //! (gdb) backtrace
 //! ```
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use core::ptr;
 //! 
 //! use cortex_m::asm;
 //! 
 //! fn main() {
 //!     // Read an invalid memory address
 //!     unsafe {
 //!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
 //!     }
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_4_register_interrupt_handler.rs
+++ b/src/examples/_4_register_interrupt_handler.rs
@@ -0,0 +1,40 @@
 //! Register an interrupt handler
 //!
 //! NOTE Requires a device crate generated using `svd2rust`
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! // NOTE this is the device crate
 //! extern crate stm32f30x;
 //! 
 //! use cortex_m::asm;
 //! use stm32f30x::interrupt;
 //! 
 //! fn main() {}
 //! 
 //! // NOTE each interrupt handler has a different signature
 //! extern "C" fn my_interrupt_handler(_ctxt: interrupt::Tim7) {
 //!     asm::bkpt();
 //! }
 //! 
 //! extern "C" fn another_interrupt_handler(_ctxt: interrupt::Exti0) {
 //!     asm::bkpt();
 //! }
 //! 
 //! // Here we override only two interrupt handlers, the rest of interrupt are
 //! // handled by the same interrupt handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: interrupt::Handlers = interrupt::Handlers {
 //!     Tim7: my_interrupt_handler,
 //!     Exti0: another_interrupt_handler,
 //!     ..interrupt::DEFAULT_HANDLERS
 //! };
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_5_override_exception_handler.rs
+++ b/src/examples/_5_override_exception_handler.rs
@@ -0,0 +1,50 @@
 //! Overriding an exception
 //!
 //! **NOTE** You have to disable the `cortex-m-rt` crate's "exceptions" feature
 //! to make this work.
 //!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use core::ptr;
 //! 
 //! use cortex_m::{asm, exception};
 //! 
 //! fn main() {
 //!     unsafe {
 //!         // Invalid memory access
 //!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
 //!     }
 //! }
 //! 
 //! extern "C" fn hard_fault(_: exception::HardFault) {
 //!     // You'll hit this breakpoint rather than the one in cortex-m-rt
 //!     asm::bkpt()
 //! }
 //! 
 //! // When the "exceptions" feature is disabled, you'll have to provide this symbol
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.exceptions"]
 //! static EXCEPTIONS: exception::Handlers = exception::Handlers {
 //!     // This is the exception handler override
 //!     hard_fault: hard_fault,
 //!     ..exception::DEFAULT_HANDLERS
 //! };
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/_6_allocator.rs
+++ b/src/examples/_6_allocator.rs
@@ -0,0 +1,75 @@
 //! How to use the heap and a dynamic memory allocator
 //!
 //! To compile this example you'll need to build the collections crate as part
 //! of the Xargo sysroot. To do that change the Xargo.toml file to look like
 //! this:
 //!
 //! ``` text
 //! [dependencies.core]
 //! [dependencies.collections] # new
 //!
 //! [dependencies.compiler_builtins]
 //! features = ["mem"]
 //! git = "https://github.com/rust-lang-nursery/compiler-builtins"
 //! stage = 1
 //! ```
 //!
 //! This example depends on the alloc-cortex-m crate so you'll have to add it
 //! to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
 //! $ cargo add alloc-cortex-m
 //! ```
 //!
 //! ```
 //! 
 //! #![feature(collections)]
 //! #![feature(used)]
 //! #![no_std]
 //! 
 //! // This is the allocator crate; you can use a different one
 //! extern crate alloc_cortex_m;
 //! #[macro_use]
 //! extern crate collections;
 //! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
 //! use cortex_m::asm;
 //! 
 //! fn main() {
 //!     // Initialize the allocator
 //!     unsafe {
 //!         extern "C" {
 //!             // Start of the heap
 //!             static mut _sheap: usize;
 //!         }
 //! 
 //!         // Size of the heap in words (1 word = 4 bytes)
 //!         // WARNING: The bigger the heap the greater the chance to run into a
 //!         // stack overflow (collision between the stack and the heap)
 //!         const SIZE: isize = 256;
 //! 
 //!         // End of the heap
 //!         let _eheap = (&mut _sheap as *mut _).offset(SIZE);
 //! 
 //!         alloc_cortex_m::init(&mut _sheap as *mut _, _eheap);
 //!     }
 //! 
 //!     // Growable array allocated on the heap
 //!     let xs = vec![0, 1, 2];
 //!     hprintln!("{:?}", xs);
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
 //! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {
 //!     asm::bkpt();
 //! }
 //! ```
 // Auto-generated. Do not modify.
--- a/src/examples/mod.rs
+++ b/src/examples/mod.rs
@@ -0,0 +1,9 @@
 //! Examples
 // Auto-generated. Do not modify.
 pub mod _0_hello;
 pub mod _1_itm;
 pub mod _2_panic;
 pub mod _3_crash;
 pub mod _4_register_interrupt_handler;
 pub mod _5_override_exception_handler;
 pub mod _6_allocator;
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -0,0 +1,292 @@
 //! A template for building applications for ARM Cortex-M microcontrollers
 //!
 //! # Dependencies
 //!
 //! - Nightly Rust toolchain: `rustup default nightly`
 //! - ARM linker: `sudo apt-get install binutils-arm-none-eabi`
 //! - Cargo `clone` subcommand: `cargo install cargo-clone`
 //! - GDB: `sudo apt-get install gdb-arm-none-eabi`
 //! - OpenOCD: `sudo apt-get install OpenOCD`
 //! - Xargo: `cargo install xargo`
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
 //!
 //! # Usage
 //!
 //! - Clone this crate
 //!
 //! ``` text
 //! $ cargo clone cortex-m-quickstart && cd $_
 //! ```
 //!
 //! - Change the crate name, author and version
 //!
 //! ``` text
 //! $ edit Cargo.toml && head $_
 //! [package]
 //! authors = ["Jorge Aparicio <jorge@japaric.io>"]
 //! name = "demo"
 //! version = "0.1.0"
 //! ```
 //!
 //! - Specify the memory layout of the target device
 //!
 //! (Note that some board support crates may provide this file for you (check
 //! the crate documentation). If you are using one that does that then remove
 //! *both* the `memory.x` and `build.rs` files.)
 //!
 //! ``` text
 //! $ edit memory.x && cat $_
 //! MEMORY
 //! {
 //!   /* NOTE K = KiBi = 1024 bytes */
 //!   FLASH : ORIGIN = 0x08000000, LENGTH = 256K
 //!   RAM : ORIGIN = 0x20000000, LENGTH = 40K
 //! }
 //!
 //! /* This is where the call stack will be allocated. */
 //! /* The stack is of the full descending type. */
 //! /* NOTE Do NOT modify `_stack_start` unless you know what you are doing */
 //! _stack_start = ORIGIN(RAM) + LENGTH(RAM);
 //! ```
 //!
 //! - Optionally, set a default build target
 //!
 //! ``` text
 //! $ cat >>.cargo/config <<'EOF'
 //! [build]
 //! target = "thumbv7em-none-eabihf"
 //! EOF
 //! ```
 //!
 //! - Very likely, depend on a device or a BSP (Board Support Package) crate.
 //!
 //! ``` text
 //! # add a device crate, or
 //! $ cargo add stm32f30x
 //!
 //! # add a board support crate
 //! $ cargo add f3
 //! ```
 //!
 //! - Write the application or start from one of the examples
 //!
 //! ``` text
 //! $ rm -r src/* && cp examples/hello.rs src/main.rs
 //! ```
 //!
 //! - Disable incremental compilation. It doesn't work for embedded development.
 //!   You'll hit nonsensical linker errors if you use it.
 //!
 //! ``` text
 //! $ unset CARGO_INCREMENTAL
 //! ```
 //!
 //! - Build the application
 //!
 //! ``` text
 //! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
 //! $ xargo build --release
 //!
 //! $ arm-none-eabi-readelf -A target/thumbv7em-none-eabihf/release/demo
 //! Attribute Section: aeabi
 //! File Attributes
 //!   Tag_conformance: "2.09"
 //!   Tag_CPU_arch: v7E-M
 //!   Tag_CPU_arch_profile: Microcontroller
 //!   Tag_THUMB_ISA_use: Thumb-2
 //!   Tag_FP_arch: VFPv4-D16
 //!   Tag_ABI_PCS_GOT_use: direct
 //!   Tag_ABI_FP_denormal: Needed
 //!   Tag_ABI_FP_exceptions: Needed
 //!   Tag_ABI_FP_number_model: IEEE 754
 //!   Tag_ABI_align_needed: 8-byte
 //!   Tag_ABI_align_preserved: 8-byte, except leaf SP
 //!   Tag_ABI_HardFP_use: SP only
 //!   Tag_ABI_VFP_args: VFP registers
 //!   Tag_ABI_optimization_goals: Aggressive Speed
 //!   Tag_CPU_unaligned_access: v6
 //!   Tag_FP_HP_extension: Allowed
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
 //! - Flash the program
 //!
 //! ``` text
 //! # Launch OpenOCD on a terminal
 //! $ openocd -f (..)
 //! ```
 //!
 //! ``` text
 //! # Start debug session
 //! $ arm-none-eabi-gdb target/..
 //! ```
 //!
 //! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you
 //! can simply run `cargo run` or `cargo run --example $example` to build the
 //! program, and immediately start a debug session. IOW, it lets you omit the
 //! `arm-none-eabi-gdb` command.
 //!
 //! ``` text
 //! $ cargo run --example hello
 //! > # drops you into a GDB session
 //! ```
 //!
 //! # Examples
 //!
 //! Check the [examples module](./examples/index.html)
 //!
 //! # Troubleshooting
 //!
 //! This section contains fixes for common errors encountered when the
 //! `cortex-m-quickstart` template is misused.
 //!
 //! ## Forgot to launch an OpenOCD instance
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ arm-none-eabi-gdb target/..
 //! Reading symbols from hello...done.
 //! .gdbinit:1: Error in sourced command file:
 //! :3333: Connection timed out.
 //! ```
 //!
 //! Solution: Launch OpenOCD on other terminal. See [Usage] section.
 //!
 //! [Usage]: ./index.html#usage
 //!
 //! ## Didn't modify the `memory.x` linker script
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ xargo build
 //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
 //! error: linking with `arm-none-eabi-ld` failed: exit code: 1
 //! |
 //! = note: "arm-none-eabi-ld" "-L" (..)
 //! = note: arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
 //! arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
 //! arm-none-eabi-ld:
 //! Invalid '.rodata.exceptions' section.
 //! Make sure to place a static with type `cortex_m::exception::Handlers`
 //! in that section (cf. #[link_section]) ONLY ONCE.
 //! ```
 //!
 //! Solution: Specify your device memory layout in the `memory.x` linker script.
 //! See [Usage] section.
 //!
 //! ## Forgot to set a default build target
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ xargo build
 //! (..)
 //! Compiling cortex-m-semihosting v0.1.3
 //! error[E0463]: can't find crate for `std`
 //!
 //! error: aborting due to previous error
 //! ```
 //!
 //! Solution: Set a default build target in the `.cargo/config` file
 //! (see [Usage] section), or call Xargo with `--target` flag:
 //! `xargo build --target thumbv7em-none-eabi`.
 //!
 //! ## Called OpenOCD with wrong arguments
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ openocd -f ..
 //! (..)
 //! Error: open failed
 //! in procedure 'init'
 //! in procedure 'ocd_bouncer'
 //! ```
 //!
 //! Solution: Correct the OpenOCD arguments. Check the
 //! `/usr/share/openocd/scripts` directory (exact location varies per
 //! distribution / OS) for a list of scripts that can be used.
 //!
 //! ## Used Cargo instead of Xargo
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ cargo build
 //! Compiling cortex-m-rt v0.2.0
 //! error[E0463]: can't find crate for `core`
 //! |
 //! = note: the `thumbv7em-none-eabihf` target may not be installed
 //!
 //! error: aborting due to previous error
 //! ```
 //!
 //! Solution: Use `xargo build`.
 //!
 //! ## Used the stable toolchain
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ xargo build
 //! error: failed to run `rustc` to learn about target-specific information
 //!
 //! To learn more, run the command again with --verbose.
 //! ```
 //!
 //! Solution: Switch to the nightly toolchain with `rustup default nightly`.
 //!
 //! ## Used `CARGO_INCREMENTAL=1`
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ xargo build
 //! error: linking with `arm-none-eabi-ld` failed: exit code: 1
 //!     |
 //! = note: "arm-none-eabi-ld" (..)
 //!     = note: arm-none-eabi-ld:
 //! You must specify the exception handlers.
 //!     Create a non `pub` static variable with type
 //!     `cortex_m::exception::Handlers` and place it in the
 //!     '.rodata.exceptions' section. (cf. #[link_section]). Apply the
 //!     `#[used]` attribute to the variable to make it reach the linker.
 //!     arm-none-eabi-ld:
 //! Invalid '.rodata.exceptions' section.
 //!     Make sure to place a static with type `cortex_m::exception::Handlers`
 //!     in that section (cf. #[link_section]) ONLY ONCE.
 //! ```
 //!
 //! Solution: `$ unset CARGO_INCREMENAL`. And to be on the safe side, call
 //! `cargo clean` and thrash the Xargo sysroot: `$ rm -rf ~/.xargo`
 //!
 //! ## Used `gdb` instead of `arm-none-eabi-gdb`
 //!
 //! Error message:
 //!
 //! ``` text
 //! $ gdb target/..
 //! Reading symbols from hello...done.
 //! warning: Architecture rejected target-supplied description
 //! warning: Cannot convert floating-point register value to ..
 //! value has been optimized out
 //! Cannot write the dashboard
 //! Traceback (most recent call last):
 //! File "<string>", line 353, in render
 //! File "<string>", line 846, in lines
 //! gdb.error: Frame is invalid.
 //! 0x00000000 in ?? ()
 //! semihosting is enabled
 //! Loading section .text, size 0xd88 lma 0x8000000
 //! Start address 0x8000000, load size 3464
 //! .gdbinit:6: Error in sourced command file:
 //! Remote connection closed
 //! ```
 //!
 //! Solution: Use `arm-none-eabi-gdb target/..`
 #![no_std]
 pub mod examples;
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,20 +0,0 @@
 #![no_std]
 #![no_main]
 // pick a panicking behavior
 use panic_halt as _; // you can put a breakpoint on `rust_begin_unwind` to catch panics
 // use panic_abort as _; // requires nightly
 // use panic_itm as _; // logs messages over ITM; requires ITM support
 // use panic_semihosting as _; // logs messages to the host stderr; requires a debugger
 use cortex_m::asm;
 use cortex_m_rt::entry;
 #[entry]
 fn main() -> ! {
    asm::nop(); // To not have main optimize to abort in release mode, remove when you add code
    loop {
        // your code goes here
    }
 }