peripherals/singletons.html - rust-embedded/book - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Singletons - The Embedded Rust Book</title>


         <!-- Custom HTML head -->

         <meta name="description" content="">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">

         <link rel="icon" href="../favicon.svg">
         <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 rel="stylesheet" href="../fonts/fonts.css">

         <!-- Highlight.js Stylesheets -->
         <link rel="stylesheet" id="highlight-css" href="../highlight.css">
         <link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
         <link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

         <!-- Custom theme stylesheets -->


         <!-- Provide site root and default themes to javascript -->
         <script>
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "navy";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc.js"></script>
     </head>
     <body>
     <div id="mdbook-help-container">
         <div id="mdbook-help-popup">
             <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
             <div>
                 <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
                 <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
                 <p>Press <kbd>?</kbd> to show this help</p>
                 <p>Press <kbd>Esc</kbd> to hide this help</p>
             </div>
         </div>
     </div>
     <div id="body-container">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
                 let theme = localStorage.getItem('mdbook-theme');
                 let 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>
             const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
             let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
             html.classList.remove('light')
             html.classList.add(theme);
             html.classList.add("js");
         </script>

         <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
             let sidebar = null;
             const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             } else {
                 sidebar = 'hidden';
             }
             sidebar_toggle.checked = sidebar === 'visible';
             html.classList.remove('sidebar-visible');
             html.classList.add("sidebar-" + sidebar);
         </script>

         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
             <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
             </noscript>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                 <div class="sidebar-resize-indicator"></div>
             </div>
         </nav>

         <div id="page-wrapper" class="page-wrapper">

             <div class="page">
                 <div id="menu-bar-hover-placeholder"></div>
                 <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
                         </label>
                         <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="default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="light">Light</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 (`/`)" 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>
                         <a href="https://github.com/rust-embedded/book" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>

                     </div>
                 </div>

                 <div id="search-wrapper" class="hidden">
                     <form id="searchbar-outer" class="searchbar-outer">
                         <input type="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>
                     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>
                         <h1 id="singletons"><a class="header" href="#singletons">Singletons</a></h1>
 <blockquote>
 <p>In software engineering, the singleton pattern is a software design pattern that restricts the instantiation of a class to one object.</p>
 <p><em>Wikipedia: <a href="https://en.wikipedia.org/wiki/Singleton_pattern">Singleton Pattern</a></em></p>
 </blockquote>
 <h2 id="but-why-cant-we-just-use-global-variables"><a class="header" href="#but-why-cant-we-just-use-global-variables">But why can't we just use global variable(s)?</a></h2>
 <p>We could make everything a public static, like this</p>
 <pre><code class="language-rust ignore">static mut THE_SERIAL_PORT: SerialPort = SerialPort;

 fn main() {
     let _ = unsafe {
         THE_SERIAL_PORT.read_speed();
     };
 }</code></pre>
 <p>But this has a few problems. It is a mutable global variable, and in Rust, these are always unsafe to interact with. These variables are also visible across your whole program, which means the borrow checker is unable to help you track references and ownership of these variables.</p>
 <h2 id="how-do-we-do-this-in-rust"><a class="header" href="#how-do-we-do-this-in-rust">How do we do this in Rust?</a></h2>
 <p>Instead of just making our peripheral a global variable, we might instead decide to make a structure, in this case called <code>PERIPHERALS</code>, which contains an <code>Option&lt;T&gt;</code> for each of our peripherals.</p>
 <pre><code class="language-rust ignore">struct Peripherals {
     serial: Option&lt;SerialPort&gt;,
 }
 impl Peripherals {
     fn take_serial(&amp;mut self) -&gt; SerialPort {
         let p = replace(&amp;mut self.serial, None);
         p.unwrap()
     }
 }
 static mut PERIPHERALS: Peripherals = Peripherals {
     serial: Some(SerialPort),
 };</code></pre>
 <p>This structure allows us to obtain a single instance of our peripheral. If we try to call <code>take_serial()</code> more than once, our code will panic!</p>
 <pre><code class="language-rust ignore">fn main() {
     let serial_1 = unsafe { PERIPHERALS.take_serial() };
     // This panics!
     // let serial_2 = unsafe { PERIPHERALS.take_serial() };
 }</code></pre>
 <p>Although interacting with this structure is <code>unsafe</code>, once we have the <code>SerialPort</code> it contained, we no longer need to use <code>unsafe</code>, or the <code>PERIPHERALS</code> structure at all.</p>
 <p>This has a small runtime overhead because we must wrap the <code>SerialPort</code> structure in an option, and we'll need to call <code>take_serial()</code> once, however this small up-front cost allows us to leverage the borrow checker throughout the rest of our program.</p>
 <h2 id="existing-library-support"><a class="header" href="#existing-library-support">Existing library support</a></h2>
 <p>Although we created our own <code>Peripherals</code> structure above, it is not necessary to do this for your code. the <code>cortex_m</code> crate contains a macro called <code>singleton!()</code> that will perform this action for you.</p>
 <pre><code class="language-rust ignore">use cortex_m::singleton;

 fn main() {
     // OK if `main` is executed only once
     let x: &amp;'static mut bool =
         singleton!(: bool = false).unwrap();
 }</code></pre>
 <p><a href="https://docs.rs/cortex-m/latest/cortex_m/macro.singleton.html">cortex_m docs</a></p>
 <p>Additionally, if you use <a href="https://github.com/rtic-rs/cortex-m-rtic"><code>cortex-m-rtic</code></a>, the entire process of defining and obtaining these peripherals are abstracted for you, and you are instead handed a <code>Peripherals</code> structure that contains a non-<code>Option&lt;T&gt;</code> version of all of the items you define.</p>
 <pre><code class="language-rust ignore">// cortex-m-rtic v0.5.x
 #[rtic::app(device = lm3s6965, peripherals = true)]
 const APP: () = {
     #[init]
     fn init(cx: init::Context) {
         static mut X: u32 = 0;

         // Cortex-M peripherals
         let core: cortex_m::Peripherals = cx.core;

         // Device specific peripherals
         let device: lm3s6965::Peripherals = cx.device;
     }
 }</code></pre>
 <h2 id="but-why"><a class="header" href="#but-why">But why?</a></h2>
 <p>But how do these Singletons make a noticeable difference in how our Rust code works?</p>
 <pre><code class="language-rust ignore">impl SerialPort {
     const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;

     fn read_speed(
         &amp;self // &lt;------ This is really, really important
     ) -&gt; u32 {
         unsafe {
             ptr::read_volatile(Self::SER_PORT_SPEED_REG)
         }
     }
 }</code></pre>
 <p>There are two important factors in play here:</p>
 <ul>
 <li>Because we are using a singleton, there is only one way or place to obtain a <code>SerialPort</code> structure</li>
 <li>To call the <code>read_speed()</code> method, we must have ownership or a reference to a <code>SerialPort</code> structure</li>
 </ul>
 <p>These two factors put together means that it is only possible to access the hardware if we have appropriately satisfied the borrow checker, meaning that at no point do we have multiple mutable references to the same hardware!</p>
 <pre><code class="language-rust ignore">fn main() {
     // missing reference to `self`! Won't work.
     // SerialPort::read_speed();

     let serial_1 = unsafe { PERIPHERALS.take_serial() };

     // you can only read what you have access to
     let _ = serial_1.read_speed();
 }</code></pre>
 <h2 id="treat-your-hardware-like-data"><a class="header" href="#treat-your-hardware-like-data">Treat your hardware like data</a></h2>
 <p>Additionally, because some references are mutable, and some are immutable, it becomes possible to see whether a function or method could potentially modify the state of the hardware. For example,</p>
 <p>This is allowed to change hardware settings:</p>
 <pre><code class="language-rust ignore">fn setup_spi_port(
     spi: &amp;mut SpiPort,
     cs_pin: &amp;mut GpioPin
 ) -&gt; Result&lt;()&gt; {
     // ...
 }</code></pre>
 <p>This isn't:</p>
 <pre><code class="language-rust ignore">fn read_button(gpio: &amp;GpioPin) -&gt; bool {
     // ...
 }</code></pre>
 <p>This allows us to enforce whether code should or should not make changes to hardware at <strong>compile time</strong>, rather than at runtime. As a note, this generally only works across one application, but for bare metal systems, our software will be compiled into a single application, so this is not usually a restriction.</p>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="../peripherals/borrowck.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 prefetch" href="../static-guarantees/index.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 rel="prev" href="../peripherals/borrowck.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>

                     <a rel="next prefetch" href="../static-guarantees/index.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>
             window.playground_copyable = true;
         </script>


         <script src="../elasticlunr.min.js"></script>
         <script src="../mark.min.js"></script>
         <script src="../searcher.js"></script>

         <script src="../clipboard.min.js"></script>
         <script src="../highlight.js"></script>
         <script src="../book.js"></script>

         <!-- Custom JS scripts -->


     </div>
     </body>
 </html>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Singletons - The Embedded Rust Book</title>


	<!-- Custom HTML head -->

	<meta name="description" content="">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<meta name="theme-color" content="#ffffff">

	<link rel="icon" href="../favicon.svg">
	<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 rel="stylesheet" href="../fonts/fonts.css">

	<!-- Highlight.js Stylesheets -->
	<link rel="stylesheet" id="highlight-css" href="../highlight.css">
	<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
	<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

	<!-- Custom theme stylesheets -->


	<!-- Provide site root and default themes to javascript -->
	<script>
	const path_to_root = "../";
	const default_light_theme = "light";
	const default_dark_theme = "navy";
	</script>
	<!-- Start loading toc.js asap -->
	<script src="../toc.js"></script>
	</head>
	<body>
	<div id="mdbook-help-container">
	<div id="mdbook-help-popup">
	<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
	<div>
	<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
	<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
	<p>Press <kbd>?</kbd> to show this help</p>
	<p>Press <kbd>Esc</kbd> to hide this help</p>
	</div>
	</div>
	</div>
	<div id="body-container">
	<!-- Work around some values being stored in localStorage wrapped in quotes -->
	<script>
	try {
	let theme = localStorage.getItem('mdbook-theme');
	let 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>
	const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
	let theme;
	try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
	if (theme === null \|\| theme === undefined) { theme = default_theme; }
	const html = document.documentElement;
	html.classList.remove('light')
	html.classList.add(theme);
	html.classList.add("js");
	</script>

	<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

	<!-- Hide / unhide sidebar before it is displayed -->
	<script>
	let sidebar = null;
	const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
	if (document.body.clientWidth >= 1080) {
	try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
	sidebar = sidebar \|\| 'visible';
	} else {
	sidebar = 'hidden';
	}
	sidebar_toggle.checked = sidebar === 'visible';
	html.classList.remove('sidebar-visible');
	html.classList.add("sidebar-" + sidebar);
	</script>

	<nav id="sidebar" class="sidebar" aria-label="Table of contents">
	<!-- populated by js -->
	<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
	<noscript>
	<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
	</noscript>
	<div id="sidebar-resize-handle" class="sidebar-resize-handle">
	<div class="sidebar-resize-indicator"></div>
	</div>
	</nav>

	<div id="page-wrapper" class="page-wrapper">

	<div class="page">
	<div id="menu-bar-hover-placeholder"></div>
	<div id="menu-bar" class="menu-bar sticky">
	<div class="left-buttons">
	<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
	<i class="fa fa-bars"></i>
	</label>
	<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="default_theme">Auto</button></li>
	<li role="none"><button role="menuitem" class="theme" id="light">Light</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 (`/`)" 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>
	<a href="https://github.com/rust-embedded/book" title="Git repository" aria-label="Git repository">
	<i id="git-repository-button" class="fa fa-github"></i>
	</a>

	</div>
	</div>

	<div id="search-wrapper" class="hidden">
	<form id="searchbar-outer" class="searchbar-outer">
	<input type="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>
	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>
	<h1 id="singletons"><a class="header" href="#singletons">Singletons</a></h1>
	<blockquote>
	<p>In software engineering, the singleton pattern is a software design pattern that restricts the instantiation of a class to one object.</p>
	<p><em>Wikipedia: <a href="https://en.wikipedia.org/wiki/Singleton_pattern">Singleton Pattern</a></em></p>
	</blockquote>
	<h2 id="but-why-cant-we-just-use-global-variables"><a class="header" href="#but-why-cant-we-just-use-global-variables">But why can't we just use global variable(s)?</a></h2>
	<p>We could make everything a public static, like this</p>
	<pre><code class="language-rust ignore">static mut THE_SERIAL_PORT: SerialPort = SerialPort;

	fn main() {
	let _ = unsafe {
	THE_SERIAL_PORT.read_speed();
	};
	}</code></pre>
	<p>But this has a few problems. It is a mutable global variable, and in Rust, these are always unsafe to interact with. These variables are also visible across your whole program, which means the borrow checker is unable to help you track references and ownership of these variables.</p>
	<h2 id="how-do-we-do-this-in-rust"><a class="header" href="#how-do-we-do-this-in-rust">How do we do this in Rust?</a></h2>
	<p>Instead of just making our peripheral a global variable, we might instead decide to make a structure, in this case called <code>PERIPHERALS</code>, which contains an <code>Option<T></code> for each of our peripherals.</p>
	<pre><code class="language-rust ignore">struct Peripherals {
	serial: Option<SerialPort>,
	}
	impl Peripherals {
	fn take_serial(&mut self) -> SerialPort {
	let p = replace(&mut self.serial, None);
	p.unwrap()
	}
	}
	static mut PERIPHERALS: Peripherals = Peripherals {
	serial: Some(SerialPort),
	};</code></pre>
	<p>This structure allows us to obtain a single instance of our peripheral. If we try to call <code>take_serial()</code> more than once, our code will panic!</p>
	<pre><code class="language-rust ignore">fn main() {
	let serial_1 = unsafe { PERIPHERALS.take_serial() };
	// This panics!
	// let serial_2 = unsafe { PERIPHERALS.take_serial() };
	}</code></pre>
	<p>Although interacting with this structure is <code>unsafe</code>, once we have the <code>SerialPort</code> it contained, we no longer need to use <code>unsafe</code>, or the <code>PERIPHERALS</code> structure at all.</p>
	<p>This has a small runtime overhead because we must wrap the <code>SerialPort</code> structure in an option, and we'll need to call <code>take_serial()</code> once, however this small up-front cost allows us to leverage the borrow checker throughout the rest of our program.</p>
	<h2 id="existing-library-support"><a class="header" href="#existing-library-support">Existing library support</a></h2>
	<p>Although we created our own <code>Peripherals</code> structure above, it is not necessary to do this for your code. the <code>cortex_m</code> crate contains a macro called <code>singleton!()</code> that will perform this action for you.</p>
	<pre><code class="language-rust ignore">use cortex_m::singleton;

	fn main() {
	// OK if `main` is executed only once
	let x: &'static mut bool =
	singleton!(: bool = false).unwrap();
	}</code></pre>
	<p><a href="https://docs.rs/cortex-m/latest/cortex_m/macro.singleton.html">cortex_m docs</a></p>
	<p>Additionally, if you use <a href="https://github.com/rtic-rs/cortex-m-rtic"><code>cortex-m-rtic</code></a>, the entire process of defining and obtaining these peripherals are abstracted for you, and you are instead handed a <code>Peripherals</code> structure that contains a non-<code>Option<T></code> version of all of the items you define.</p>
	<pre><code class="language-rust ignore">// cortex-m-rtic v0.5.x
	#[rtic::app(device = lm3s6965, peripherals = true)]
	const APP: () = {
	#[init]
	fn init(cx: init::Context) {
	static mut X: u32 = 0;

	// Cortex-M peripherals
	let core: cortex_m::Peripherals = cx.core;

	// Device specific peripherals
	let device: lm3s6965::Peripherals = cx.device;
	}
	}</code></pre>
	<h2 id="but-why"><a class="header" href="#but-why">But why?</a></h2>
	<p>But how do these Singletons make a noticeable difference in how our Rust code works?</p>
	<pre><code class="language-rust ignore">impl SerialPort {
	const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;

	fn read_speed(
	&self // <------ This is really, really important
	) -> u32 {
	unsafe {
	ptr::read_volatile(Self::SER_PORT_SPEED_REG)
	}
	}
	}</code></pre>
	<p>There are two important factors in play here:</p>
	<ul>
	<li>Because we are using a singleton, there is only one way or place to obtain a <code>SerialPort</code> structure</li>
	<li>To call the <code>read_speed()</code> method, we must have ownership or a reference to a <code>SerialPort</code> structure</li>
	</ul>
	<p>These two factors put together means that it is only possible to access the hardware if we have appropriately satisfied the borrow checker, meaning that at no point do we have multiple mutable references to the same hardware!</p>
	<pre><code class="language-rust ignore">fn main() {
	// missing reference to `self`! Won't work.
	// SerialPort::read_speed();

	let serial_1 = unsafe { PERIPHERALS.take_serial() };

	// you can only read what you have access to
	let _ = serial_1.read_speed();
	}</code></pre>
	<h2 id="treat-your-hardware-like-data"><a class="header" href="#treat-your-hardware-like-data">Treat your hardware like data</a></h2>
	<p>Additionally, because some references are mutable, and some are immutable, it becomes possible to see whether a function or method could potentially modify the state of the hardware. For example,</p>
	<p>This is allowed to change hardware settings:</p>
	<pre><code class="language-rust ignore">fn setup_spi_port(
	spi: &mut SpiPort,
	cs_pin: &mut GpioPin
	) -> Result<()> {
	// ...
	}</code></pre>
	<p>This isn't:</p>
	<pre><code class="language-rust ignore">fn read_button(gpio: &GpioPin) -> bool {
	// ...
	}</code></pre>
	<p>This allows us to enforce whether code should or should not make changes to hardware at <strong>compile time</strong>, rather than at runtime. As a note, this generally only works across one application, but for bare metal systems, our software will be compiled into a single application, so this is not usually a restriction.</p>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="../peripherals/borrowck.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 prefetch" href="../static-guarantees/index.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 rel="prev" href="../peripherals/borrowck.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="../static-guarantees/index.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>
	window.playground_copyable = true;
	</script>


	<script src="../elasticlunr.min.js"></script>
	<script src="../mark.min.js"></script>
	<script src="../searcher.js"></script>

	<script src="../clipboard.min.js"></script>
	<script src="../highlight.js"></script>
	<script src="../book.js"></script>

	<!-- Custom JS scripts -->


	</div>
	</body>
	</html>