<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Introduction - 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"><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="#introduction" id="introduction"><h1>Introduction</h1></a>
<p>Welcome to The Embedded Rust Book: An introductory book about using the Rust
Programming Language on "Bare Metal" embedded systems, such as Microcontrollers.</p>
<a class="header" href="#who-embedded-rust-is-for" id="who-embedded-rust-is-for"><h2>Who Embedded Rust is For</h2></a>
<p>Embedded Rust is for everyone who wants to do embedded programming while taking advantage of the higher-level concepts and safety guarantees the Rust language provides.
(See also <a href="https://doc.rust-lang.org/book/ch00-00-introduction.html">Who Rust Is For</a>)</p>
<a class="header" href="#scope" id="scope"><h2>Scope</h2></a>
<p>The goals of this book are:</p>
<ul>
<li>
<p>Get developers up to speed with embedded Rust development. i.e. How to set
up a development environment.</p>
</li>
<li>
<p>Share <em>current</em> best practices about using Rust for embedded development. i.e.
How to best use Rust language features to write more correct embedded
software.</p>
</li>
<li>
<p>Serve as a cookbook in some cases. e.g. How do I do mix C and Rust in a single
project?</p>
</li>
</ul>
<p>This book tries to be as general as possible but to make things easier for both
the readers and the writers it uses the ARM Cortex-M architecture in all its
examples. However, the book doesn't assume that the reader is familiar with this
particular architecture and explains details particular to this architecture
where required.</p>
<a class="header" href="#who-this-book-is-for" id="who-this-book-is-for"><h2>Who This Book is For</h2></a>
<p>This book caters towards people with either some embedded background or some Rust background, however we believe
everybody curious about embedded Rust programming can get something out of this book. For those without any prior knowledge
we suggest you read the "Assumptions and Prerequisites" section and catch up on missing knowledge to get more out of the book
and improve your reading experience. You can check out the "Other Resources" section to find resources on topics
you might want to catch up on.</p>
<a class="header" href="#assumptions-and-prerequisites" id="assumptions-and-prerequisites"><h3>Assumptions and Prerequisites</h3></a>
<ul>
<li>You are comfortable using the Rust Programming Language, and have written,
run, and debugged Rust applications on a desktop environment. You should also
be familiar with the idioms of the <a href="https://doc.rust-lang.org/edition-guide/">2018 edition</a> as this book targets
Rust 2018.</li>
</ul>
<ul>
<li>You are comfortable developing and debugging embedded systems in another
language such as C, C++, or Ada, and are familiar with concepts such as:
<ul>
<li>Cross Compilation</li>
<li>Memory Mapped Peripherals</li>
<li>Interrupts</li>
<li>Common interfaces such as I2C, SPI, Serial, etc.</li>
</ul>
</li>
</ul>
<a class="header" href="#other-resources" id="other-resources"><h3>Other Resources</h3></a>
<p>If you are unfamiliar with anything mentioned above or if you want more information about a specific topic mentioned in this book you might find some of these resources helpful.</p>
<table><thead><tr><th> Topic </th><th> Resource </th><th> Description </th></tr></thead><tbody>
<tr><td> Rust </td><td> <a href="https://doc.rust-lang.org/book/">Rust Book</a> </td><td> If you are not yet comfortable with Rust, we highly suggest reading the this book. </td></tr>
<tr><td> Rust, Embedded </td><td> <a href="https://docs.rust-embedded.org">Embedded Rust Bookshelf</a> </td><td> Here you can find several other resources provided by Rust's Embedded Working Group. </td></tr>
<tr><td> Rust, Embedded </td><td> <a href="https://docs.rust-embedded.org/embedonomicon/">Embedonomicon</a> </td><td> The nitty gritty details when doing embedded programming in Rust. </td></tr>
<tr><td> Rust, Embedded </td><td> <a href="https://docs.rust-embedded.org/faq.html">embedded FAQ</a> </td><td> Frequently asked questions about Rust in an embedded context. </td></tr>
<tr><td> Interrupts </td><td> <a href="https://en.wikipedia.org/wiki/Interrupt">Interrupt</a> </td><td> - </td></tr>
<tr><td> Memory-mapped IO/Peripherals </td><td> <a href="https://en.wikipedia.org/wiki/Memory-mapped_I/O">Memory-mapped I/O</a> </td><td> - </td></tr>
<tr><td> SPI, UART, RS232, USB, I2C, TTL </td><td> <a href="https://electronics.stackexchange.com/questions/37814/usart-uart-rs232-usb-spi-i2c-ttl-etc-what-are-all-of-these-and-how-do-th">Stack Exchange about SPI, UART, and other interfaces</a> </td><td> - </td></tr>
</tbody></table>
<a class="header" href="#how-to-use-this-book" id="how-to-use-this-book"><h2>How to Use This Book</h2></a>
<p>This book generally assumes that you’re reading it front-to-back. Later
chapters build on concepts in earlier chapters, and earlier chapters may
not dig into details on a topic, revisiting the topic in a later chapter.</p>
<p>This book will be using the <a href="http://www.st.com/en/evaluation-tools/stm32f3discovery.html">STM32F3DISCOVERY</a> development board from
STMicroelectronics for the majority of the examples contained within. This board
is based on the ARM Cortex-M architecture, and while basic functionality is
the same across most CPUs based on this architecture, peripherals and other
implementation details of Microcontrollers are different between different
vendors, and often even different between Microcontroller families from the same
vendor.</p>
<p>For this reason, we suggest purchasing the <a href="http://www.st.com/en/evaluation-tools/stm32f3discovery.html">STM32F3DISCOVERY</a> development board
for the purpose of following the examples in this book.</p>
<a class="header" href="#contributing-to-this-book" id="contributing-to-this-book"><h2>Contributing to This Book</h2></a>
<p>The work on this book is coordinated in <a href="https://github.com/rust-embedded/book">this repository</a> and is mainly
developed by the <a href="https://github.com/rust-embedded/wg#the-resources-team">resources team</a>.</p>
<p>If you have trouble following the instructions in this book or find that some
section of the book is not clear enough or hard to follow then that's a bug and
it should be reported in <a href="https://github.com/rust-embedded/book/issues/">the issue tracker</a> of this book.</p>
<p>Pull requests fixing typos and adding new content are very welcome!</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</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
>
12743
