<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Hardware - The Embedded Rust Book</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../highlight.css">
<link rel="stylesheet" href="../tomorrow-night.css">
<link rel="stylesheet" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "../";
var default_theme = "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li><a href="../intro/index.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li><a href="../intro/hardware.html"><strong aria-hidden="true">1.1.</strong> Hardware</a></li><li><a href="../intro/no-std.html"><strong aria-hidden="true">1.2.</strong> no_std</a></li><li><a href="../intro/tooling.html"><strong aria-hidden="true">1.3.</strong> Tooling</a></li><li><a href="../intro/install.html"><strong aria-hidden="true">1.4.</strong> Installation</a></li><li><ol class="section"><li><a href="../intro/install/linux.html"><strong aria-hidden="true">1.4.1.</strong> Linux</a></li><li><a href="../intro/install/macos.html"><strong aria-hidden="true">1.4.2.</strong> MacOS</a></li><li><a href="../intro/install/windows.html"><strong aria-hidden="true">1.4.3.</strong> Windows</a></li><li><a href="../intro/install/verify.html"><strong aria-hidden="true">1.4.4.</strong> Verify Installation</a></li></ol></li></ol></li><li><a href="../start/index.html"><strong aria-hidden="true">2.</strong> Getting started</a></li><li><ol class="section"><li><a href="../start/qemu.html"><strong aria-hidden="true">2.1.</strong> QEMU</a></li><li><a href="../start/hardware.html" class="active"><strong aria-hidden="true">2.2.</strong> Hardware</a></li><li><a href="../start/registers.html"><strong aria-hidden="true">2.3.</strong> Memory-mapped Registers</a></li><li><a href="../start/semihosting.html"><strong aria-hidden="true">2.4.</strong> Semihosting</a></li><li><a href="../start/panicking.html"><strong aria-hidden="true">2.5.</strong> Panicking</a></li><li><a href="../start/exceptions.html"><strong aria-hidden="true">2.6.</strong> Exceptions</a></li><li><a href="../start/interrupts.html"><strong aria-hidden="true">2.7.</strong> Interrupts</a></li><li><a href="../start/io.html"><strong aria-hidden="true">2.8.</strong> IO</a></li></ol></li><li><a href="../peripherals/index.html"><strong aria-hidden="true">3.</strong> Peripherals</a></li><li><ol class="section"><li><a href="../peripherals/a-first-attempt.html"><strong aria-hidden="true">3.1.</strong> A first attempt in Rust</a></li><li><a href="../peripherals/borrowck.html"><strong aria-hidden="true">3.2.</strong> The Borrow Checker</a></li><li><a href="../peripherals/singletons.html"><strong aria-hidden="true">3.3.</strong> Singletons</a></li></ol></li><li><a href="../static-guarantees/index.html"><strong aria-hidden="true">4.</strong> Static Guarantees</a></li><li><ol class="section"><li><a href="../static-guarantees/typestate-programming.html"><strong aria-hidden="true">4.1.</strong> Typestate Programming</a></li><li><a href="../static-guarantees/state-machines.html"><strong aria-hidden="true">4.2.</strong> Peripherals as State Machines</a></li><li><a href="../static-guarantees/design-contracts.html"><strong aria-hidden="true">4.3.</strong> Design Contracts</a></li><li><a href="../static-guarantees/zero-cost-abstractions.html"><strong aria-hidden="true">4.4.</strong> Zero Cost Abstractions</a></li></ol></li><li><a href="../portability/index.html"><strong aria-hidden="true">5.</strong> Portability</a></li><li><a href="../concurrency/index.html"><strong aria-hidden="true">6.</strong> Concurrency</a></li><li><a href="../collections/index.html"><strong aria-hidden="true">7.</strong> Collections</a></li><li><a href="../c-tips/index.html"><strong aria-hidden="true">8.</strong> Tips for embedded C developers</a></li><li><a href="../interoperability/index.html"><strong aria-hidden="true">9.</strong> Interoperability</a></li><li><ol class="section"><li><a href="../interoperability/c-with-rust.html"><strong aria-hidden="true">9.1.</strong> A little C with your Rust</a></li><li><a href="../interoperability/rust-with-c.html"><strong aria-hidden="true">9.2.</strong> A little Rust with your C</a></li></ol></li><li><a href="../unsorted/index.html"><strong aria-hidden="true">10.</strong> Unsorted topics</a></li><li><ol class="section"><li><a href="../unsorted/speed-vs-size.html"><strong aria-hidden="true">10.1.</strong> Optimizations: The speed size tradeoff</a></li></ol></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Embedded Rust Book</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="#hardware" id="hardware"><h1>Hardware</h1></a>
<p>By now you should be somewhat familiar with the tooling and the development
process. In this section we'll switch to real hardware; the process will remain
largely the same. Let's dive in.</p>
<a class="header" href="#know-your-hardware" id="know-your-hardware"><h2>Know your hardware</h2></a>
<p>Before we begin you need to identify some characteristics of the target device
as these will be used to configure the project:</p>
<ul>
<li>
<p>The ARM core. e.g. Cortex-M3.</p>
</li>
<li>
<p>Does the ARM core include an FPU? Cortex-M4<strong>F</strong> and Cortex-M7<strong>F</strong> cores do.</p>
</li>
<li>
<p>How much Flash memory and RAM does the target device have? e.g. 256 KiB of
Flash and 32 KiB of RAM.</p>
</li>
<li>
<p>Where are Flash memory and RAM mapped in the address space? e.g. RAM is
commonly located at address <code>0x2000_0000</code>.</p>
</li>
</ul>
<p>You can find this information in the data sheet or the reference manual of your
device.</p>
<p>In this section we'll be using our reference hardware, the STM32F3DISCOVERY.
This board contains an STM32F303VCT6 microcontroller. This microcontroller has:</p>
<ul>
<li>
<p>A Cortex-M4F core that includes a single precision FPU</p>
</li>
<li>
<p>256 KiB of Flash located at address 0x0800_0000.</p>
</li>
<li>
<p>40 KiB of RAM located at address 0x2000_0000. (There's another RAM region but
for simplicity we'll ignore it).</p>
</li>
</ul>
<a class="header" href="#configuring" id="configuring"><h2>Configuring</h2></a>
<p>We'll start from scratch with a fresh template instance. Refer to the
<a href="qemu.html">previous section on QEMU</a> for a refresher on how to do this without
<code>cargo-generate</code>.</p>
<pre><code class="language-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
</code></pre>
<p>Step number one is to set a default compilation target in <code>.cargo/config</code>.</p>
<pre><code class="language-console">$ tail -n5 .cargo/config
</code></pre>
<pre><code class="language-toml"># 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)
</code></pre>
<p>We'll use <code>thumbv7em-none-eabihf</code> as that covers the Cortex-M4F core.</p>
<p>The second step is to enter the memory region information into the <code>memory.x</code>
file.</p>
<pre><code class="language-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
}
</code></pre>
<p>Make sure the <code>debug::exit()</code> call is commented out or removed, it is used
only for running in QEMU.</p>
<pre><code class="language-rust ignore">#[entry]
fn main() -> ! {
hprintln!("Hello, world!").unwrap();
// exit QEMU
// NOTE do not run this on hardware; it can corrupt OpenOCD state
// debug::exit(debug::EXIT_SUCCESS);
loop {}
}
</code></pre>
<p>You can now cross compile programs using <code>cargo build</code>
and inspect the binaries using <code>cargo-binutils</code> as you did before. The
<code>cortex-m-rt</code> crate handles all the magic required to get your chip running,
as helpfully, pretty much all Cortex-M CPUs boot in the same fashion.</p>
<pre><code class="language-console">$ cargo build --example hello
</code></pre>
<a class="header" href="#debugging" id="debugging"><h2>Debugging</h2></a>
<p>Debugging will look a bit different. In fact, the first steps can look different
depending on the target device. In this section we'll show the steps required to
debug a program running on the STM32F3DISCOVERY. This is meant to serve as a
reference; for device specific information about debugging check out <a href="https://github.com/rust-embedded/debugonomicon">the
Debugonomicon</a>.</p>
<p>As before we'll do remote debugging and the client will be a GDB process. This
time, however, the server will be OpenOCD.</p>
<p>As done during the <a href="../intro/install/verify.html">verify</a> section connect the discovery board to your laptop /
PC and check that the ST-LINK header is populated.</p>
<p>On a terminal run <code>openocd</code> to connect to the ST-LINK on the discovery board.
Run this command from the root of the template; <code>openocd</code> will pick up the
<code>openocd.cfg</code> file which indicates which interface file and target file to use.</p>
<pre><code class="language-console">$ cat openocd.cfg
</code></pre>
<pre><code class="language-text"># 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]
</code></pre>
<blockquote>
<p><strong>NOTE</strong> If you found out that you have an older revision of the discovery
board during the <a href="../intro/install/verify.html">verify</a> section then you should modify the <code>openocd.cfg</code>
file at this point to use <code>interface/stlink-v2.cfg</code>.</p>
</blockquote>
<pre><code class="language-console">$ openocd
Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
none separate
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v2 JTAG v27 API v2 SWIM v15 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 2.913879
Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints
</code></pre>
<p>On another terminal run GDB, also from the root of the template.</p>
<pre><code class="language-console">$ <gdb> -q target/thumbv7em-none-eabihf/debug/examples/hello
</code></pre>
<p>Next connect GDB to OpenOCD, which is waiting for a TCP connection on port 3333.</p>
<pre><code class="language-console">(gdb) target remote :3333
Remote debugging using :3333
0x00000000 in ?? ()
</code></pre>
<p>Now proceed to <em>flash</em> (load) the program onto the microcontroller using the
<code>load</code> command.</p>
<pre><code class="language-console">(gdb) load
Loading section .vector_table, size 0x400 lma 0x8000000
Loading section .text, size 0x1e70 lma 0x8000400
Loading section .rodata, size 0x61c lma 0x8002270
Start address 0x800144e, load size 10380
Transfer rate: 17 KB/sec, 3460 bytes/write.
</code></pre>
<p>The program is now loaded. This program uses semihosting so before we do any
semihosting call we have to tell OpenOCD to enable semihosting. You can send
commands to OpenOCD using the <code>monitor</code> command.</p>
<pre><code class="language-console">(gdb) monitor arm semihosting enable
semihosting is enabled
</code></pre>
<blockquote>
<p>You can see all the OpenOCD commands by invoking the <code>monitor help</code> command.</p>
</blockquote>
<p>Like before we can skip all the way to <code>main</code> using a breakpoint and the
<code>continue</code> command.</p>
<pre><code class="language-console">(gdb) break main
Breakpoint 1 at 0x8000d18: file examples/hello.rs, line 15.
(gdb) continue
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.
Breakpoint 1, main () at examples/hello.rs:15
15 let mut stdout = hio::hstdout().unwrap();
</code></pre>
<p>Advancing the program with <code>next</code> should produce the same results as before.</p>
<pre><code class="language-console">(gdb) next
16 writeln!(stdout, "Hello, world!").unwrap();
(gdb) next
19 debug::exit(debug::EXIT_SUCCESS);
</code></pre>
<p>At this point you should see "Hello, world!" printed on the OpenOCD console,
among other stuff.</p>
<pre><code class="language-console">$ openocd
(..)
Info : halted: PC: 0x08000e6c
Hello, world!
Info : halted: PC: 0x08000d62
Info : halted: PC: 0x08000d64
Info : halted: PC: 0x08000d66
Info : halted: PC: 0x08000d6a
Info : halted: PC: 0x08000a0c
Info : halted: PC: 0x08000d70
Info : halted: PC: 0x08000d72
</code></pre>
<p>Issuing another <code>next</code> will make the processor execute <code>debug::exit</code>. This acts
as a breakpoint and halts the process:</p>
<pre><code class="language-console">(gdb) next
Program received signal SIGTRAP, Trace/breakpoint trap.
0x0800141a in __syscall ()
</code></pre>
<p>It also causes this to be printed to the OpenOCD console:</p>
<pre><code class="language-console">$ openocd
(..)
Info : halted: PC: 0x08001188
semihosting: *** application exited ***
Warn : target not halted
Warn : target not halted
target halted due to breakpoint, current mode: Thread
xPSR: 0x21000000 pc: 0x08000d76 msp: 0x20009fc0, semihosting
</code></pre>
<p>However, the process running on the microcontroller has not terminated and you
can resume it using <code>continue</code> or a similar command.</p>
<p>You can now exit GDB using the <code>quit</code> command.</p>
<pre><code class="language-console">(gdb) quit
</code></pre>
<p>Debugging now requires a few more steps so we have packed all those steps into a
single GDB script named <code>openocd.gdb</code>.</p>
<pre><code class="language-console">$ cat openocd.gdb
</code></pre>
<pre><code class="language-text">target remote :3333
# print demangled symbols
set print asm-demangle on
# detect unhandled exceptions, hard faults and panics
break DefaultHandler
break HardFault
break rust_begin_unwind
monitor arm semihosting enable
load
# start the process but immediately halt the processor
stepi
</code></pre>
<p>Now running <code><gdb> -x openocd.gdb $program</code> will immediately connect GDB to
OpenOCD, enable semihosting, load the program and start the process.</p>
<p>Alternatively, you can turn <code><gdb> -x openocd.gdb</code> into a custom runner to make
<code>cargo run</code> build a program <em>and</em> start a GDB session. This runner is included
in <code>.cargo/config</code> but it's commented out.</p>
<pre><code class="language-console">$ head -n10 .cargo/config
</code></pre>
<pre><code class="language-toml">[target.thumbv7m-none-eabi]
# 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 -x openocd.gdb"
# runner = "gdb-multiarch -x openocd.gdb"
# runner = "gdb -x openocd.gdb"
</code></pre>
<pre><code class="language-console">$ cargo run --example hello
(..)
Loading section .vector_table, size 0x400 lma 0x8000000
Loading section .text, size 0x1e70 lma 0x8000400
Loading section .rodata, size 0x61c lma 0x8002270
Start address 0x800144e, load size 10380
Transfer rate: 17 KB/sec, 3460 bytes/write.
(gdb)
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../start/qemu.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../start/registers.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="../start/qemu.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="../start/registers.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="../book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
12773
