Default to extended-remote instead of remote mode

Extended remote allows a lot more features like attaching and detaching and much more fine-grained execution options. If a gdbserver implementation supports it (and OpenOCD sure does) it should be preferred over `remote`.

.cargo/config

@@ -1,35 +1,33 @@
-[target.thumbv6m-none-eabi]
-runner = 'arm-none-eabi-gdb'
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
-  "-Z", "thinlto=no",
-]
-
 [target.thumbv7m-none-eabi]
-runner = 'arm-none-eabi-gdb'
+# uncomment this to make `cargo run` execute programs on QEMU
+# 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 = [
+  # LLD (shipped with the Rust toolchain) is used as the default linker
   "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
-  "-Z", "thinlto=no",
+
+  # 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.thumbv7em-none-eabi]
-runner = 'arm-none-eabi-gdb'
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
-  "-Z", "thinlto=no",
-]
-
-[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",
-  "-Z", "thinlto=no",
-]
+[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)

.gitignore

@@ -1,4 +1,5 @@
 **/*.rs.bk
+.#*
 .gdb_history
 Cargo.lock
 target/

CHANGELOG.md

@@ -1,153 +0,0 @@
-# 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.2.5] - 2018-02-26
-
-### Added
-
-- Comments to Cargo.toml and Xargo.toml to make it easier to try the examples.
-
-### Fixed
-
-- The `allocator` example to use the `#[global_allocator]` feature.
-
-## [v0.2.4] - 2018-01-26
-
-### Changed
-
-- Disable ThinLTO which causes extreme binary size bloat. See rust-lang/rust#47770 for details.
-
-## [v0.2.3] - 2018-01-20
-
-### Changed
-
-- Tweaked docs. Instruction steps are now numbered.
-
-### Removed
-
-- The `CARGO_INCREMENTAL=1` workaround has been removed since it's now controlled via Cargo.toml and
-  we have the setting disabled in the template.
-
-## [v0.2.2] - 2018-01-17
-
-### Added
-
-- Troubleshooting documentation: how to workaround the "Ignoring packet error, continuing..." GDB
-  error.
-
-### Changed
-
-- Disabled incremental compilation and parallel codegen on the dev profile to reduce the changes of
-  running into rust-lang/rust#47074.
-
-- Bumped the version of the `cortex-m-rt` dependency to v0.3.12.
-
-## [v0.2.1] - 2017-07-14
-
-### Added
-
-- Troubleshooting documentation: how to fix the error of overwriting the
-  `.cargo/config` file when you meant to append text to it.
-
-### Changed
-
-- Xargo.toml: Changed the source of the `compiler-builtins` crate from git to
-  the `rust-src` component.
-
-- Expanded the `device` example to do some I/O.
-
-## [v0.2.0] - 2017-07-07
-
-### Changed
-
-- [breaking-change] Bumped the cortex-m and cortex-m-rt versions to v0.3.0.
-
-## [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.2.4...HEAD
-[v0.2.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.3...v0.2.4
-[v0.2.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.2...v0.2.3
-[v0.2.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.1...v0.2.2
-[v0.2.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...v0.2.1
-[v0.2.0]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.8...v0.2.0
-[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

Cargo.toml

@@ -1,36 +1,33 @@
 [package]
-authors = ["Jorge Aparicio <jorge@japaric.io>"]
-categories = ["embedded", "no-std"]
-description = "A template for building applications for ARM Cortex-M microcontrollers"
-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.2.5"
+authors = ["{{authors}}"]
+edition = "2018"
+name = "{{project-name}}"
+version = "0.1.0"
 
 [dependencies]
-cortex-m = "0.4.0"
-cortex-m-semihosting = "0.2.0"
-# alloc-cortex-m release doesn't use linked_list_allocator v0.5.0 yet.
-# Uncomment for the allocator example.
-#alloc-cortex-m = "0.3.2"
+cortex-m = "0.5.7"
+cortex-m-rt = "0.6.3"
+cortex-m-semihosting = "0.3.1"
+panic-halt = "0.2.0"
 
-[dependencies.cortex-m-rt]
-version = "0.3.12"
-# Comment for the panic example.
-features = ["abort-on-panic"]
+# Uncomment for the panic example.
+# panic-itm = "0.4.0"
+
+# Uncomment for the allocator example.
+# alloc-cortex-m = "0.3.5"
 
 # Uncomment for the device example.
-# [dependencies.stm32f103xx]
+# [dependencies.stm32f30x]
 # features = ["rt"]
-# version = "0.8.0"
+# version = "0.7.1"
 
-# disable both incremental compilation and parallel codegen to reduce the chances of running into
-# rust-lang/rust#47074
-[profile.dev]
-codegen-units = 1
-incremental = false
+# this lets you use `cargo fix`!
+[[bin]]
+name = "{{project-name}}"
+test = false
+bench = false
 
 [profile.release]
-debug = true
-lto = true
+codegen-units = 1 # better optimizations
+debug = true # symbols are nice and they don't increase the size on Flash
+lto = true # better optimizations

LICENSE-APACHE

@@ -1,201 +0,0 @@
-                              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.

LICENSE-MIT

@@ -1,25 +0,0 @@
-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.

README.md

@@ -2,11 +2,112 @@
 
 > A template for building applications for ARM Cortex-M microcontrollers
 
-# [Documentation](https://docs.rs/cortex-m-quickstart)
+This project is developed and maintained by the [Cortex-M team][team].
+
+## Dependencies
+
+To build embedded programs using this template you'll need:
+
+- Rust 1.30, 1.30-beta, nightly-2018-09-13 or a newer toolchain. e.g. `rustup
+  default beta`
+
+> **NOTE**: 1.30-beta is not out yet so you'll have to use the nightly channel
+> in the meantime.
+
+- 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
+```
 
 # License
 
-Licensed under either of
+This template is licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
@@ -20,3 +121,12 @@ 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]: CODE_OF_CONDUCT.md
+[team]: https://github.com/rust-embedded/wg#the-cortex-m-team

Xargo.toml

@@ -1,9 +0,0 @@
-[dependencies.core]
-stage = 0
-
-# [dependencies.alloc] # Uncomment for the alloc example.
-# stage = 0
-
-[dependencies.compiler_builtins]
-features = ["mem"]
-stage = 1

build.rs

@@ -12,6 +12,7 @@ fn main() {
         .unwrap();
     println!("cargo:rustc-link-search={}", out.display());
 
-    println!("cargo:rerun-if-changed=build.rs");
+    // Only re-run the build script when memory.x is changed,
+    // instead of when any part of the source code changes.
     println!("cargo:rerun-if-changed=memory.x");
 }

examples/allocator.rs

@@ -1,22 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the alloc crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.alloc] # NEW
-//! stage = 0
-//!
-//! [dependencies.compiler_builtins]
-//! stage = 1
-//! ```
-//!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it
-//! to your Cargo.toml:
+//! 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
@@ -26,50 +10,45 @@
 //! ---
 
 #![feature(alloc)]
-#![feature(used)]
-#![feature(global_allocator)]
+#![feature(alloc_error_handler)]
+#![no_main]
 #![no_std]
 
-// This is the allocator crate; you can use a different one
-extern crate alloc_cortex_m;
-#[macro_use]
-extern crate alloc;
-extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+extern crate panic_halt;
 
+use core::alloc::Layout;
 use core::fmt::Write;
 
-use cortex_m::asm;
-use cortex_m_semihosting::hio;
+use alloc::vec;
 use alloc_cortex_m::CortexMHeap;
+use cortex_m::asm;
+use cortex_m_rt::entry;
+use cortex_m_semihosting::hio;
 
+// this is the allocator the application will use
 #[global_allocator]
 static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
 
-extern "C" {
-    static mut _sheap: u32;
-    static mut _eheap: u32;
-}
+const HEAP_SIZE: usize = 1024; // in bytes
 
-fn main() {
-    // Initialize the allocator
-    let start = unsafe { &mut _sheap as *mut u32 as usize };
-    let end = unsafe { &mut _eheap as *mut u32 as usize };
-    unsafe { ALLOCATOR.init(start, end - start) }
+#[entry]
+fn main() -> ! {
+    // Initialize the allocator BEFORE you use it
+    unsafe { ALLOCATOR.init(cortex_m_rt::heap_start() as usize, HEAP_SIZE) }
 
     // Growable array allocated on the heap
     let xs = vec![0, 1, 2];
 
     let mut stdout = hio::hstdout().unwrap();
     writeln!(stdout, "{:?}", xs).unwrap();
+
+    loop {}
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
+// define what happens in an Out Of Memory (OOM) condition
+#[alloc_error_handler]
+fn alloc_error(_layout: Layout) -> ! {
     asm::bkpt();
+
+    loop {}
 }

examples/crash.rs

@@ -1,85 +1,96 @@
 //! 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.
+//! Most crash conditions trigger a hard fault exception, whose handler is defined via
+//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
+//! snapshot of the CPU registers at the moment of the exception.
 //!
-//! In you run the example below, you'll be able to inspect the state of your
-//! program under the debugger using these commands:
+//! This program crashes and the `HardFault` handler prints to the console the contents of the
+//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! that led to the exception.
 //!
 //! ``` text
-//! (gdb) # Exception frame = program state during the crash
-//! (gdb) print/x *ef
-//! $1 = cortex_m::exception::ExceptionFrame {
-//!   r0 = 0x2fffffff,
-//!   r1 = 0x2fffffff,
-//!   r2 = 0x0,
-//!   r3 = 0x0,
-//!   r12 = 0x0,
-//!   lr = 0x8000481,
-//!   pc = 0x8000460,
-//!   xpsr = 0x61000000,
-//! }
+//! (gdb) continue
+//! Program received signal SIGTRAP, Trace/breakpoint trap.
+//! __bkpt () at asm/bkpt.s:3
+//! 3         bkpt
 //!
-//! (gdb) # Where did we come from?
 //! (gdb) backtrace
-//! #0  cortex_m_rt::default_handler (ef=0x20004f54) at (..)
-//! #1  <signal handler called>
-//! #2  0x08000460 in core::ptr::read_volatile<u32> (src=0x2fffffff) at (..)
-//! #3  0x08000480 in crash::main () at examples/crash.rs:68
+//! #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?)
+//! ```
 //!
-//! (gdb) # Nail down the location of the crash
-//! (gdb) disassemble/m ef.pc
-//! Dump of assembler code for function core::ptr::read_volatile<u32>:
-//! 408     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000454 <+0>:     sub     sp, #20
-//!    0x08000456 <+2>:     mov     r1, r0
-//!    0x08000458 <+4>:     str     r0, [sp, #8]
-//!    0x0800045a <+6>:     ldr     r0, [sp, #8]
-//!    0x0800045c <+8>:     str     r0, [sp, #12]
+//! In the console output one will find the state of the Program Counter (PC) register at the time
+//! of the exception.
 //!
-//! 409         intrinsics::volatile_load(src)
-//!    0x0800045e <+10>:    ldr     r0, [sp, #12]
-//!    0x08000460 <+12>:    ldr     r0, [r0, #0]
-//!    0x08000462 <+14>:    str     r0, [sp, #16]
-//!    0x08000464 <+16>:    ldr     r0, [sp, #16]
-//!    0x08000466 <+18>:    str     r1, [sp, #4]
-//!    0x08000468 <+20>:    str     r0, [sp, #0]
-//!    0x0800046a <+22>:    b.n     0x800046c <core::ptr::read_volatile<u32>+24>
+//! ``` 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
+//! ```
 //!
-//! 410     }
-//!    0x0800046c <+24>:    ldr     r0, [sp, #0]
-//!    0x0800046e <+26>:    add     sp, #20
-//!    0x08000470 <+28>:    bx      lr
+//! 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.
+//!
 //! ---
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_rt;
+extern crate panic_halt;
 
 use core::ptr;
 
-use cortex_m::asm;
+use cortex_m_rt::entry;
 
-fn main() {
-    // Read an invalid memory address
+#[entry]
+fn main() -> ! {
     unsafe {
+        // read an address outside of the RAM region; this causes a HardFault exception
         ptr::read_volatile(0x2FFF_FFFF as *const u32);
     }
-}
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
-    asm::bkpt();
+    loop {}
 }

examples/device.rs

@@ -1,98 +1,71 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt 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
 //!
-//! Device crates also provide an `interrupt!` macro to register interrupt
+//! Device crates also provide an `interrupt!` macro (behind the "rt" feature) to register interrupt
 //! handlers.
 //!
-//! This example depends on the [`stm32f103xx`] crate so you'll have to add it
-//! to your Cargo.toml.
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
 //!
 //! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
 //!
 //! ```
-//! $ edit Cargo.toml && cat $_
+//! $ edit Cargo.toml && tail $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.8.0"
+//! version = "0.10.0"
 //! ```
 //!
 //! ---
 
-#![deny(warnings)]
-#![feature(const_fn)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_semihosting;
-#[macro_use(exception, interrupt)]
-extern crate stm32f103xx;
+#[allow(unused_extern_crates)]
+extern crate panic_halt;
 
-use core::cell::RefCell;
 use core::fmt::Write;
 
-use cortex_m::interrupt::{self, Mutex};
 use cortex_m::peripheral::syst::SystClkSource;
+use cortex_m_rt::entry;
 use cortex_m_semihosting::hio::{self, HStdout};
-use stm32f103xx::Interrupt;
+use stm32f30x::{interrupt, Interrupt};
 
-static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
-    Mutex::new(RefCell::new(None));
+#[entry]
+fn main() -> ! {
+    let p = cortex_m::Peripherals::take().unwrap();
 
-static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> =
-    Mutex::new(RefCell::new(None));
+    let mut syst = p.SYST;
+    let mut nvic = p.NVIC;
 
-fn main() {
-    let global_p = cortex_m::Peripherals::take().unwrap();
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Ok(fd) = hio::hstdout() {
-            *hstdout.borrow_mut() = Some(fd);
-        }
+    nvic.enable(Interrupt::EXTI0);
 
-        let mut nvic = global_p.NVIC;
-        nvic.enable(Interrupt::TIM2);
-        *NVIC.borrow(cs).borrow_mut() = Some(nvic);
+    // 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();
 
-        let mut syst = global_p.SYST;
-        syst.set_clock_source(SystClkSource::Core);
-        syst.set_reload(8_000_000); // 1s
-        syst.enable_counter();
-        syst.enable_interrupt();
-    });
+    loop {
+        // busy wait until the timer wraps around
+        while !syst.has_wrapped() {}
+
+        // trigger the `EXTI0` interrupt
+        nvic.set_pending(Interrupt::EXTI0);
+    }
 }
 
-exception!(SYS_TICK, tick);
+// try commenting out this line: you'll end in `default_handler` instead of in `exti0`
+interrupt!(EXTI0, exti0, state: Option<HStdout> = None);
 
-fn tick() {
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-            writeln!(*hstdout, "Tick").ok();
-        }
+fn exti0(state: &mut Option<HStdout>) {
+    if state.is_none() {
+        *state = Some(hio::hstdout().unwrap());
+    }
 
-        if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
-            nvic.set_pending(Interrupt::TIM2);
-        }
-    });
-}
-
-interrupt!(TIM2, tock, locals: {
-    tocks: u32 = 0;
-});
-
-fn tock(l: &mut TIM2::Locals) {
-    l.tocks += 1;
-
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-            writeln!(*hstdout, "Tock ({})", l.tocks).ok();
-        }
-    });
+    if let Some(hstdout) = state.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
 }

examples/exception.rs

@@ -0,0 +1,47 @@
+//! 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]
+
+extern crate panic_halt;
+
+use core::fmt::Write;
+
+use cortex_m::peripheral::syst::SystClkSource;
+use cortex_m::Peripherals;
+use cortex_m_rt::{entry, exception};
+use cortex_m_semihosting::hio::{self, HStdout};
+
+#[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() {
+    static mut STDOUT: Option<HStdout> = None;
+
+    if STDOUT.is_none() {
+        *STDOUT = Some(hio::hstdout().unwrap());
+    }
+
+    if let Some(hstdout) = STDOUT.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
+}

examples/hello.rs

@@ -1,29 +1,22 @@
-//! Prints "Hello, world!" on the OpenOCD console using semihosting
-//!
-//! ---
+//! Prints "Hello, world!" on the host console using semihosting
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+extern crate panic_halt;
 
 use core::fmt::Write;
 
-use cortex_m::asm;
-use cortex_m_semihosting::hio;
+use cortex_m_rt::entry;
+use cortex_m_semihosting::{debug, hio};
 
-fn main() {
+#[entry]
+fn main() -> ! {
     let mut stdout = hio::hstdout().unwrap();
     writeln!(stdout, "Hello, world!").unwrap();
-}
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+    // exit QEMU or the debugger section
+    debug::exit(debug::EXIT_SUCCESS);
 
-extern "C" fn default_handler() {
-    asm::bkpt();
+    loop {}
 }

examples/itm.rs

@@ -1,39 +1,33 @@
 //! 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 the `monitor` commands in the `.gdbinit` file.
+//! **NOTE** Cortex-M0 chips don't support ITM.
 //!
-//! [`itmdump`]: https://docs.rs/itm/0.1.1/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.
+//!
+//! 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/
 //!
 //! ---
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-#[macro_use]
-extern crate cortex_m;
-extern crate cortex_m_rt;
+extern crate panic_halt;
 
-use cortex_m::{asm, Peripherals};
+use cortex_m::{iprintln, Peripherals};
+use cortex_m_rt::entry;
 
-fn main() {
-    let p = Peripherals::take().unwrap();
-    let mut itm = p.ITM;
+#[entry]
+fn main() -> ! {
+    let mut p = Peripherals::take().unwrap();
+    let stim = &mut p.ITM.stim[0];
 
-    iprintln!(&mut itm.stim[0], "Hello, world!");
-}
-
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
-    asm::bkpt();
+    iprintln!(stim, "Hello, world!");
+
+    loop {}
 }

examples/override-exception-handler.rs

@@ -1,47 +0,0 @@
-//! Overriding an exception handler
-//!
-//! You can override an exception handler using the [`exception!`][1] macro.
-//!
-//! [1]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.exception.html
-//!
-//! The default exception handler can be overridden using the
-//! [`default_handler!`][2] macro
-//!
-//! [2]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.default_handler.html
-//!
-//! ---
-
-#![feature(used)]
-#![no_std]
-
-extern crate cortex_m;
-#[macro_use(exception)]
-extern crate cortex_m_rt;
-
-use core::ptr;
-
-use cortex_m::asm;
-
-fn main() {
-    unsafe {
-        // Invalid memory access
-        ptr::read_volatile(0x2FFF_FFFF as *const u32);
-    }
-}
-
-exception!(HARD_FAULT, handler);
-
-fn handler() {
-    // You'll hit this breakpoint rather than the one in cortex-m-rt
-    asm::bkpt()
-}
-
-// As we are not using interrupts, we just register a dummy catch all handler
-#[allow(dead_code)]
-#[used]
-#[link_section = ".vector_table.interrupts"]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
-    asm::bkpt();
-}

examples/panic.rs

@@ -1,58 +1,28 @@
-//! Defining the panic handler
+//! Changing the panicking behavior
 //!
-//! The panic handler can be defined through the `panic_fmt` [language item][1].
-//! Make sure that the "abort-on-panic" feature of the cortex-m-rt crate is
-//! disabled to avoid redefining the language item.
+//! The easiest way to change the panicking behavior is to use a different [panic handler crate][0].
 //!
-//! [1]: https://doc.rust-lang.org/unstable-book/language-features/lang-items.html
-//!
-//! ---
+//! [0]: https://crates.io/keywords/panic-impl
 
-#![feature(core_intrinsics)]
-#![feature(lang_items)]
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+// Pick one of these panic handlers:
 
-use core::fmt::Write;
-use core::intrinsics;
+// `panic!` halts execution; the panic message is ignored
+extern crate panic_halt;
 
-use cortex_m::asm;
-use cortex_m_semihosting::hio;
+// Reports panic messages to the host stderr using semihosting
+// NOTE to use this you need to uncomment the `panic-semihosting` dependency in Cargo.toml
+// extern crate panic_semihosting;
 
-fn main() {
-    panic!("Oops");
-}
-
-#[lang = "panic_fmt"]
-#[no_mangle]
-pub unsafe extern "C" fn rust_begin_unwind(
-    args: core::fmt::Arguments,
-    file: &'static str,
-    line: u32,
-    col: u32,
-) -> ! {
-    if let Ok(mut stdout) = hio::hstdout() {
-        write!(stdout, "panicked at '")
-            .and_then(|_| {
-                stdout
-                    .write_fmt(args)
-                    .and_then(|_| writeln!(stdout, "', {}:{}:{}", file, line, col))
-            })
-            .ok();
-    }
-
-    intrinsics::abort()
-}
-
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
-    asm::bkpt();
+// Logs panic messages using the ITM (Instrumentation Trace Macrocell)
+// NOTE to use this you need to uncomment the `panic-itm` dependency in Cargo.toml
+// extern crate panic_itm;
+
+use cortex_m_rt::entry;
+
+#[entry]
+fn main() -> ! {
+    panic!("Oops")
 }

gen-examples.sh

@@ -1,55 +0,0 @@
-# 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
-        override-exception-handler
-        device
-        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

memory.x

@@ -1,9 +1,10 @@
 MEMORY
 {
-  /* NOTE K = KiBi = 1024 bytes */
+  /* NOTE 1 K = 1 KiBi = 1024 bytes */
   /* TODO Adjust these memory regions to match your device memory layout */
-  FLASH : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
-  RAM : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
+  /* These values correspond to the LM3S6965, one of the few devices QEMU can emulate */
+  FLASH : ORIGIN = 0x00000000, LENGTH = 256K
+  RAM : ORIGIN = 0x20000000, LENGTH = 64K
 }
 
 /* This is where the call stack will be allocated. */
@@ -18,6 +19,3 @@ MEMORY
 /* This is required only on microcontrollers that store some configuration right
    after the vector table */
 /* _stext = ORIGIN(FLASH) + 0x400; */
-
-/* Size of the heap (in bytes) */
-/* _heap_size = 1024; */

openocd.cfg

@@ -0,0 +1,12 @@
+# 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]

openocd.gdb

@@ -1,16 +1,25 @@
-target remote :3333
+target extended-remote :3333
 
-# print demangled symbols by default
+# print demangled symbols
 set print asm-demangle on
 
+# detect unhandled exceptions, hard faults and panics
+break DefaultHandler
+break UserHardFault
+break rust_begin_unwind
+
+# *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.fifo uart off 8000000
+# 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
 
@@ -18,4 +27,6 @@ monitor arm semihosting enable
 # monitor itm port 0 on
 
 load
-step
+
+# start the process but immediately halt the processor
+stepi

src/examples/_0_hello.rs

@@ -1,33 +0,0 @@
-//! Prints "Hello, world!" on the OpenOCD console using semihosting
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
-//! use core::fmt::Write;
-//! 
-//! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! 
-//! fn main() {
-//!     let mut stdout = hio::hstdout().unwrap();
-//!     writeln!(stdout, "Hello, world!").unwrap();
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_1_itm.rs

@@ -1,43 +0,0 @@
-//! 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 the `monitor` commands in the `.gdbinit` file.
-//!
-//! [`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, Peripherals};
-//! 
-//! fn main() {
-//!     let p = Peripherals::take().unwrap();
-//!     let mut itm = p.ITM;
-//! 
-//!     iprintln!(&mut itm.stim[0], "Hello, world!");
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_2_panic.rs

@@ -1,62 +0,0 @@
-//! Defining the panic handler
-//!
-//! The panic handler can be defined through the `panic_fmt` [language item][1].
-//! Make sure that the "abort-on-panic" feature of the cortex-m-rt crate is
-//! disabled to avoid redefining the language item.
-//!
-//! [1]: https://doc.rust-lang.org/unstable-book/language-features/lang-items.html
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(core_intrinsics)]
-//! #![feature(lang_items)]
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
-//! use core::fmt::Write;
-//! use core::intrinsics;
-//! 
-//! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! 
-//! fn main() {
-//!     panic!("Oops");
-//! }
-//! 
-//! #[lang = "panic_fmt"]
-//! #[no_mangle]
-//! pub unsafe extern "C" fn rust_begin_unwind(
-//!     args: core::fmt::Arguments,
-//!     file: &'static str,
-//!     line: u32,
-//!     col: u32,
-//! ) -> ! {
-//!     if let Ok(mut stdout) = hio::hstdout() {
-//!         write!(stdout, "panicked at '")
-//!             .and_then(|_| {
-//!                 stdout
-//!                     .write_fmt(args)
-//!                     .and_then(|_| writeln!(stdout, "', {}:{}:{}", file, line, col))
-//!             })
-//!             .ok();
-//!     }
-//! 
-//!     intrinsics::abort()
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_3_crash.rs

@@ -1,89 +0,0 @@
-//! 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:
-//!
-//! ``` text
-//! (gdb) # Exception frame = program state during the crash
-//! (gdb) print/x *ef
-//! $1 = cortex_m::exception::ExceptionFrame {
-//!   r0 = 0x2fffffff,
-//!   r1 = 0x2fffffff,
-//!   r2 = 0x0,
-//!   r3 = 0x0,
-//!   r12 = 0x0,
-//!   lr = 0x8000481,
-//!   pc = 0x8000460,
-//!   xpsr = 0x61000000,
-//! }
-//!
-//! (gdb) # Where did we come from?
-//! (gdb) backtrace
-//! #0  cortex_m_rt::default_handler (ef=0x20004f54) at (..)
-//! #1  <signal handler called>
-//! #2  0x08000460 in core::ptr::read_volatile<u32> (src=0x2fffffff) at (..)
-//! #3  0x08000480 in crash::main () at examples/crash.rs:68
-//!
-//! (gdb) # Nail down the location of the crash
-//! (gdb) disassemble/m ef.pc
-//! Dump of assembler code for function core::ptr::read_volatile<u32>:
-//! 408     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000454 <+0>:     sub     sp, #20
-//!    0x08000456 <+2>:     mov     r1, r0
-//!    0x08000458 <+4>:     str     r0, [sp, #8]
-//!    0x0800045a <+6>:     ldr     r0, [sp, #8]
-//!    0x0800045c <+8>:     str     r0, [sp, #12]
-//!
-//! 409         intrinsics::volatile_load(src)
-//!    0x0800045e <+10>:    ldr     r0, [sp, #12]
-//!    0x08000460 <+12>:    ldr     r0, [r0, #0]
-//!    0x08000462 <+14>:    str     r0, [sp, #16]
-//!    0x08000464 <+16>:    ldr     r0, [sp, #16]
-//!    0x08000466 <+18>:    str     r1, [sp, #4]
-//!    0x08000468 <+20>:    str     r0, [sp, #0]
-//!    0x0800046a <+22>:    b.n     0x800046c <core::ptr::read_volatile<u32>+24>
-//!
-//! 410     }
-//!    0x0800046c <+24>:    ldr     r0, [sp, #0]
-//!    0x0800046e <+26>:    add     sp, #20
-//!    0x08000470 <+28>:    bx      lr
-//!
-//! End of assembler dump.
-//! ```
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![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
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_4_override_exception_handler.rs

@@ -1,51 +0,0 @@
-//! Overriding an exception handler
-//!
-//! You can override an exception handler using the [`exception!`][1] macro.
-//!
-//! [1]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.exception.html
-//!
-//! The default exception handler can be overridden using the
-//! [`default_handler!`][2] macro
-//!
-//! [2]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.default_handler.html
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! #[macro_use(exception)]
-//! extern crate cortex_m_rt;
-//! 
-//! use core::ptr;
-//! 
-//! use cortex_m::asm;
-//! 
-//! fn main() {
-//!     unsafe {
-//!         // Invalid memory access
-//!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
-//!     }
-//! }
-//! 
-//! exception!(HARD_FAULT, handler);
-//! 
-//! fn handler() {
-//!     // You'll hit this breakpoint rather than the one in cortex-m-rt
-//!     asm::bkpt()
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[allow(dead_code)]
-//! #[used]
-//! #[link_section = ".vector_table.interrupts"]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_5_device.rs

@@ -1,102 +0,0 @@
-//! Using a device crate
-//!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt crate.
-//!
-//! [`svd2rust`]: https://crates.io/crates/svd2rust
-//!
-//! Device crates also provide an `interrupt!` macro to register interrupt
-//! handlers.
-//!
-//! This example depends on the [`stm32f103xx`] crate so you'll have to add it
-//! to your Cargo.toml.
-//!
-//! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
-//!
-//! ```
-//! $ edit Cargo.toml && cat $_
-//! [dependencies.stm32f103xx]
-//! features = ["rt"]
-//! version = "0.8.0"
-//! ```
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![deny(warnings)]
-//! #![feature(const_fn)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_semihosting;
-//! #[macro_use(exception, interrupt)]
-//! extern crate stm32f103xx;
-//! 
-//! use core::cell::RefCell;
-//! use core::fmt::Write;
-//! 
-//! use cortex_m::interrupt::{self, Mutex};
-//! use cortex_m::peripheral::syst::SystClkSource;
-//! use cortex_m_semihosting::hio::{self, HStdout};
-//! use stm32f103xx::Interrupt;
-//! 
-//! static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
-//!     Mutex::new(RefCell::new(None));
-//! 
-//! static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> =
-//!     Mutex::new(RefCell::new(None));
-//! 
-//! fn main() {
-//!     let global_p = cortex_m::Peripherals::take().unwrap();
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Ok(fd) = hio::hstdout() {
-//!             *hstdout.borrow_mut() = Some(fd);
-//!         }
-//! 
-//!         let mut nvic = global_p.NVIC;
-//!         nvic.enable(Interrupt::TIM2);
-//!         *NVIC.borrow(cs).borrow_mut() = Some(nvic);
-//! 
-//!         let mut syst = global_p.SYST;
-//!         syst.set_clock_source(SystClkSource::Core);
-//!         syst.set_reload(8_000_000); // 1s
-//!         syst.enable_counter();
-//!         syst.enable_interrupt();
-//!     });
-//! }
-//! 
-//! exception!(SYS_TICK, tick);
-//! 
-//! fn tick() {
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-//!             writeln!(*hstdout, "Tick").ok();
-//!         }
-//! 
-//!         if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
-//!             nvic.set_pending(Interrupt::TIM2);
-//!         }
-//!     });
-//! }
-//! 
-//! interrupt!(TIM2, tock, locals: {
-//!     tocks: u32 = 0;
-//! });
-//! 
-//! fn tock(l: &mut TIM2::Locals) {
-//!     l.tocks += 1;
-//! 
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-//!             writeln!(*hstdout, "Tock ({})", l.tocks).ok();
-//!         }
-//!     });
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_6_allocator.rs

@@ -1,79 +0,0 @@
-//! How to use the heap and a dynamic memory allocator
-//!
-//! To compile this example you'll need to build the alloc crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.alloc] # NEW
-//! stage = 0
-//!
-//! [dependencies.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)]
-//! #![feature(used)]
-//! #![feature(global_allocator)]
-//! #![no_std]
-//! 
-//! // This is the allocator crate; you can use a different one
-//! extern crate alloc_cortex_m;
-//! #[macro_use]
-//! extern crate alloc;
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
-//! use core::fmt::Write;
-//! 
-//! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! use alloc_cortex_m::CortexMHeap;
-//! 
-//! #[global_allocator]
-//! static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
-//! 
-//! extern "C" {
-//!     static mut _sheap: u32;
-//!     static mut _eheap: u32;
-//! }
-//! 
-//! fn main() {
-//!     // Initialize the allocator
-//!     let start = unsafe { &mut _sheap as *mut u32 as usize };
-//!     let end = unsafe { &mut _eheap as *mut u32 as usize };
-//!     unsafe { ALLOCATOR.init(start, end - start) }
-//! 
-//!     // Growable array allocated on the heap
-//!     let xs = vec![0, 1, 2];
-//! 
-//!     let mut stdout = hio::hstdout().unwrap();
-//!     writeln!(stdout, "{:?}", xs).unwrap();
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/mod.rs

@@ -1,9 +0,0 @@
-//! 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_override_exception_handler;
-pub mod _5_device;
-pub mod _6_allocator;

src/lib.rs

@@ -1,319 +0,0 @@
-//! 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` (on Ubuntu)
-//! - Cargo `clone` subcommand: `cargo install cargo-clone`
-//! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
-//! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
-//! - Xargo: `cargo install xargo`
-//! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
-//!
-//! # Usage
-//!
-//! 1) Clone this crate
-//!
-//! ``` text
-//! $ cargo clone cortex-m-quickstart && cd $_
-//! ```
-//!
-//! 2) 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"
-//! ```
-//!
-//! 3) Specify the memory layout of the target device
-//!
-//! **NOTE** board support crates sometimes provide this file for you (check the crate
-//! documentation). If you are using one that does 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
-//! }
-//! ```
-//!
-//! 4) Optionally, set a default build target
-//!
-//! ``` text
-//! $ cat >>.cargo/config <<'EOF'
-//! [build]
-//! target = "thumbv7em-none-eabihf"
-//! EOF
-//! ```
-//!
-//! 5) Depend on a device, HAL implementation or a board support crate.
-//!
-//! ``` text
-//! $ # add a device crate, OR
-//! $ cargo add stm32f30x
-//!
-//! $ # add a HAL implementation crate, OR
-//! $ cargo add stm32f103xx-hal
-//!
-//! $ # add a board support crate
-//! $ cargo add f3
-//! ```
-//!
-//! 6) Write the application or start from one of the examples
-//!
-//! ``` text
-//! $ rm -r src/* && cp examples/hello.rs src/main.rs
-//! ```
-//!
-//! 7) Build the application
-//!
-//! ``` text
-//! $ # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
-//! $ xargo build --release
-//!
-//! $ # sanity check
-//! $ 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
-//! ```
-//!
-//! 8) Flash the program
-//!
-//! ``` text
-//! $ # Launch OpenOCD on a terminal
-//! $ openocd -f (..)
-//! ```
-//!
-//! ``` text
-//! $ # Start a debug session in another terminal
-//! $ arm-none-eabi-gdb target/thumbv7em-none-eabihf/release/demo
-//! ```
-//!
-//! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you can simply run `xargo
-//! run` or `xargo 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`.
-//!
-//! ## Overwrote the original `.cargo/config` file
-//!
-//! Error message:
-//!
-//! ``` text
-//! error: linking with `arm-none-eabi-gcc` failed: exit code: 1
-//!   |
-//!   = note: (..)
-//! (..)
-//! (..)/crt0.o: In function `_start':
-//! (.text+0x90): undefined reference to `memset'
-//! (..)/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 build target (e.g. `cat >` instead of `cat >>`). The
-//! less error prone way to fix this is to remove the `.cargo` directory, clone
-//! a new copy of the template and then copy the `.cargo` directory from that
-//! fresh template into your current project. Don't forget to *append* the
-//! default build target to `.cargo/config`.
-//!
-//! ## 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 `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/..`
-//!
-//! # Used a named piped for `itm.fifo`
-//!
-//! Error message:
-//!
-//! ``` text
-//! $ xargo run [--example ..]
-//!
-//! Reading symbols from target/thumbv7em-none-eabihf/debug/cortex-m-quickstart...done.
-//! cortex_m_rt::reset_handler ()
-//!     at $REGISTRY/cortex-m-rt-0.3.12/src/lib.rs:330
-//! 330     unsafe extern "C" fn reset_handler() -> ! {
-//! semihosting is enabled
-//! Ignoring packet error, continuing...
-//! Ignoring packet error, continuing...
-//! ```
-//!
-//! Note that when you reach this point OpenOCD will become unresponsive and you'll have to kill it
-//! and start a new OpenOCD process before you can invoke `xargo run` / start GDB.
-//!
-//! Cause: You uncommented the `monitor tpiu ..` line in `.gdbinit` and are using a named pipe to
-//! receive the ITM data (i.e. you ran `mkfifo itm.fifo`). This error occurs when `itmdump -f
-//! itm.fifo` (or equivalent, e.g. `cat itm.fifo`) is not running.
-//!
-//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `xargo
-//! run` / starting GDB. Note that sometimes `itmdump` will exit when the GDB session ends. In that
-//! case you'll have to run `itmdump` before you start the next GDB session.
-//!
-//! Alternative solution: Use a plain text file instead of a named pipe. In this scenario you omit
-//! the `mkfifo itm.dump` command. You can use `itmdump`'s *follow* mode (-F) to get named pipe like
-//! output.
-
-#![no_std]
-
-pub mod examples;

src/main.rs

@@ -0,0 +1,17 @@
+#![no_std]
+#![no_main]
+
+// pick a panicking behavior
+extern crate panic_halt; // you can put a breakpoint on `rust_begin_unwind` to catch panics
+// extern crate panic_abort; // requires nightly
+// extern crate panic_itm; // logs messages over ITM; requires ITM support
+// extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger
+
+use cortex_m_rt::entry;
+
+#[entry]
+fn main() -> ! {
+    loop {
+        // your code goes here
+    }
+}