mirror of
https://github.com/rtic-rs/rtic.git
synced 2024-11-27 14:04:56 +01:00
553 lines
27 KiB
HTML
553 lines
27 KiB
HTML
|
<!DOCTYPE HTML>
|
||
|
|
<html lang="en" class="light" dir="ltr">
|
||
|
|
<head>
|
||
|
|
<!-- Book generated using mdBook -->
|
||
|
|
<meta charset="UTF-8">
|
||
|
|
<title>v0.5.x to v1.0.x - Real-Time Interrupt-driven Concurrency</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" href="../highlight.css">
|
||
|
|
<link rel="stylesheet" href="../tomorrow-night.css">
|
||
|
|
<link rel="stylesheet" href="../ayu-highlight.css">
|
||
|
|
|
||
|
|
<!-- Custom theme stylesheets -->
|
||
|
|
|
||
|
|
</head>
|
||
|
|
<body class="sidebar-visible no-js">
|
||
|
|
<div id="body-container">
|
||
|
|
<!-- Provide site root to javascript -->
|
||
|
|
<script>
|
||
|
|
var path_to_root = "../";
|
||
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
|
|
<script>
|
||
|
|
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>
|
||
|
|
var theme;
|
||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
|
|
var html = document.querySelector('html');
|
||
|
|
html.classList.remove('light')
|
||
|
|
html.classList.add(theme);
|
||
|
|
var body = document.querySelector('body');
|
||
|
|
body.classList.remove('no-js')
|
||
|
|
body.classList.add('js');
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||
|
|
|
||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
||
|
|
<script>
|
||
|
|
var body = document.querySelector('body');
|
||
|
|
var sidebar = null;
|
||
|
|
var 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';
|
||
|
|
body.classList.remove('sidebar-visible');
|
||
|
|
body.classList.add("sidebar-" + sidebar);
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
|
|
<div class="sidebar-scrollbox">
|
||
|
|
<ol class="chapter"><li class="chapter-item expanded affix "><a href="../preface.html">Preface</a></li><li class="chapter-item expanded "><a href="../by-example.html"><strong aria-hidden="true">1.</strong> RTIC by example</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../by-example/app.html"><strong aria-hidden="true">1.1.</strong> The app</a></li><li class="chapter-item expanded "><a href="../by-example/resources.html"><strong aria-hidden="true">1.2.</strong> Resources</a></li><li class="chapter-item expanded "><a href="../by-example/app_init.html"><strong aria-hidden="true">1.3.</strong> The init task</a></li><li class="chapter-item expanded "><a href="../by-example/app_idle.html"><strong aria-hidden="true">1.4.</strong> The idle task</a></li><li class="chapter-item expanded "><a href="../by-example/app_task.html"><strong aria-hidden="true">1.5.</strong> Defining tasks</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../by-example/hardware_tasks.html"><strong aria-hidden="true">1.5.1.</strong> Hardware tasks</a></li><li class="chapter-item expanded "><a href="../by-example/software_tasks.html"><strong aria-hidden="true">1.5.2.</strong> Software tasks & spawn</a></li><li class="chapter-item expanded "><a href="../by-example/message_passing.html"><strong aria-hidden="true">1.5.3.</strong> Message passing & capacity</a></li><li class="chapter-item expanded "><a href="../by-example/app_priorities.html"><strong aria-hidden="true">1.5.4.</strong> Task priorities</a></li><li class="chapter-item expanded "><a href="../by-example/monotonic.html"><strong aria-hidden="true">1.5.5.</strong> Monotonic & spawn_{at/after}</a></li></ol></li><li class="chapter-item expanded "><a href="../by-example/starting_a_project.html"><strong aria-hidden="true">1.6.</strong> Starting a new project</a></li><li class="chapter-item expanded "><a href="../by-example/app_minimal.html"><strong aria-hidden="true">1.7.</strong> The minimal app</a></li><li class="chapter-item expanded "><a href="../by-example/tips.html"><strong aria-hidden="true">1.8.</strong> Tips & Tricks</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../by-example/tips_monotonic_impl.html"><strong aria-hidden="true">1.8.1.</strong> Implementing Monotonic</a></li><li class="chapter-item expanded "><a href="../by-example/tips_destructureing.html"><strong aria-hidden="true">1.8.2.</strong> Resource de-structure-ing</a></li><li class="chapter-item expanded "><a href="../by-example/tips_indirection.html"><strong aria-hidden="true">1.8.3.</strong> Avoid copies when message passing</a></li><li class="chapter-item expanded "><a href="../by-example/tips_static_lifetimes.html"><strong aria-hidden="true">1.8.4.</strong> 'static super-powers</a></li><li class="chapter-item expanded "><a href="../by-example/tips_view_code.html"><strong aria-hidden="true">1.8.5.</strong> Inspecting generated code</a></li><li class="chapter-item expanded "><a href="../by-example/tips_from_ram.html"><strong aria-hidden="true">1.8.6.</strong> Running tasks from RAM</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../awesome_rtic.html"><strong aria-hidden="true">2.</strong> Awesome RTIC examples</a></li><li class="chapter-item expanded "><a href="../migration.html"><strong aria-hidden="true">3.</strong> Migration Guides</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../migration/migration_v5.html" class="active"><strong aria-hidden="true">3.1.</strong> v0.5.x to v1.0.x</a></li><li class="chapter-item expanded "><a href="../migration/migration_v4.html"><strong aria-hidden="true">3.2.</strong> v0.4.x to v0.5.x</a></li><li class="chapter-item expanded "><a href="../migration/migration_rtic.html"><strong aria-hidden="true">3.3.</strong> RTFM to RTIC</a></li></ol></li><li class="chapter-item expanded "><a href="../internals.html"><strong aria-hidden="true">4.</strong> Under the hood</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../internals/targ
|
||
|
|
</div>
|
||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||
|
|
<div class="sidebar-resize-indicator"></div>
|
||
|
|
</div>
|
||
|
|
</nav>
|
||
|
|
|
||
|
|
<!-- Track and set sidebar scroll position -->
|
||
|
|
<script>
|
||
|
|
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
|
||
|
|
sidebarScrollbox.addEventListener('click', function(e) {
|
||
|
|
if (e.target.tagName === 'A') {
|
||
|
|
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
|
||
|
|
}
|
||
|
|
}, { passive: true });
|
||
|
|
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
|
||
|
|
sessionStorage.removeItem('sidebar-scroll');
|
||
|
|
if (sidebarScrollTop) {
|
||
|
|
// preserve sidebar scroll position when navigating via links within sidebar
|
||
|
|
sidebarScrollbox.scrollTop = sidebarScrollTop;
|
||
|
|
} else {
|
||
|
|
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
|
||
|
|
var activeSection = document.querySelector('#sidebar .active');
|
||
|
|
if (activeSection) {
|
||
|
|
activeSection.scrollIntoView({ block: 'center' });
|
||
|
|
}
|
||
|
|
}
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<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="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. (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">Real-Time Interrupt-driven Concurrency</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/rtic-rs/cortex-m-rtic" 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="migrating-from-v05x-to-v100"><a class="header" href="#migrating-from-v05x-to-v100">Migrating from v0.5.x to v1.0.0</a></h1>
|
||
|
|
<p>This section describes how to upgrade from v0.5.x to v1.0.0 of the RTIC framework.</p>
|
||
|
|
<h2 id="cargotoml---version-bump"><a class="header" href="#cargotoml---version-bump"><code>Cargo.toml</code> - version bump</a></h2>
|
||
|
|
<p>Change the version of <code>cortex-m-rtic</code> to <code>"1.0.0"</code>.</p>
|
||
|
|
<h2 id="mod-instead-of-const"><a class="header" href="#mod-instead-of-const"><code>mod</code> instead of <code>const</code></a></h2>
|
||
|
|
<p>With the support of attributes on modules the <code>const APP</code> workaround is not needed.</p>
|
||
|
|
<p>Change</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(/* .. */)]
|
||
|
|
const APP: () = {
|
||
|
|
[code here]
|
||
|
|
};
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>into</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(/* .. */)]
|
||
|
|
mod app {
|
||
|
|
[code here]
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>Now that a regular Rust module is used it means it is possible to have custom
|
||
|
|
user code within that module.
|
||
|
|
Additionally, it means that <code>use</code>-statements for resources used in user
|
||
|
|
code must be moved inside <code>mod app</code>, or be referred to with <code>super</code>. For
|
||
|
|
example, change:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>use some_crate::some_func;
|
||
|
|
|
||
|
|
#[rtic::app(/* .. */)]
|
||
|
|
const APP: () = {
|
||
|
|
fn func() {
|
||
|
|
some_crate::some_func();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>into</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(/* .. */)]
|
||
|
|
mod app {
|
||
|
|
use some_crate::some_func;
|
||
|
|
|
||
|
|
fn func() {
|
||
|
|
some_crate::some_func();
|
||
|
|
}
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>or</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>use some_crate::some_func;
|
||
|
|
|
||
|
|
#[rtic::app(/* .. */)]
|
||
|
|
mod app {
|
||
|
|
fn func() {
|
||
|
|
super::some_crate::some_func();
|
||
|
|
}
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<h2 id="move-dispatchers-from-extern-c-to-app-arguments"><a class="header" href="#move-dispatchers-from-extern-c-to-app-arguments">Move Dispatchers from <code>extern "C"</code> to app arguments</a></h2>
|
||
|
|
<p>Change</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(/* .. */)]
|
||
|
|
const APP: () = {
|
||
|
|
[code here]
|
||
|
|
|
||
|
|
// RTIC requires that unused interrupts are declared in an extern block when
|
||
|
|
// using software tasks; these free interrupts will be used to dispatch the
|
||
|
|
// software tasks.
|
||
|
|
extern "C" {
|
||
|
|
fn SSI0();
|
||
|
|
fn QEI0();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>into</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(/* .. */, dispatchers = [SSI0, QEI0])]
|
||
|
|
mod app {
|
||
|
|
[code here]
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>This works also for ram functions, see examples/ramfunc.rs</p>
|
||
|
|
<h2 id="resources-structs---shared-local"><a class="header" href="#resources-structs---shared-local">Resources structs - <code>#[shared]</code>, <code>#[local]</code></a></h2>
|
||
|
|
<p>Previously the RTIC resources had to be in in a struct named exactly "Resources":</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>struct Resources {
|
||
|
|
// Resources defined in here
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>With RTIC v1.0.0 the resources structs are annotated similarly like
|
||
|
|
<code>#[task]</code>, <code>#[init]</code>, <code>#[idle]</code>: with the attributes <code>#[shared]</code> and <code>#[local]</code></p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[shared]
|
||
|
|
struct MySharedResources {
|
||
|
|
// Resources shared between tasks are defined here
|
||
|
|
}
|
||
|
|
|
||
|
|
#[local]
|
||
|
|
struct MyLocalResources {
|
||
|
|
// Resources defined here cannot be shared between tasks; each one is local to a single task
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>These structs can be freely named by the developer.</p>
|
||
|
|
<h2 id="shared-and-local-arguments-in-tasks"><a class="header" href="#shared-and-local-arguments-in-tasks"><code>shared</code> and <code>local</code> arguments in <code>#[task]</code>s</a></h2>
|
||
|
|
<p>In v1.0.0 resources are split between <code>shared</code> resources and <code>local</code> resources.
|
||
|
|
<code>#[task]</code>, <code>#[init]</code> and <code>#[idle]</code> no longer have a <code>resources</code> argument; they must now use the <code>shared</code> and <code>local</code> arguments.</p>
|
||
|
|
<p>In v0.5.x:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>struct Resources {
|
||
|
|
local_to_b: i64,
|
||
|
|
shared_by_a_and_b: i64,
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(resources = [shared_by_a_and_b])]
|
||
|
|
fn a(_: a::Context) {}
|
||
|
|
|
||
|
|
#[task(resources = [shared_by_a_and_b, local_to_b])]
|
||
|
|
fn b(_: b::Context) {}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>In v1.0.0:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[shared]
|
||
|
|
struct Shared {
|
||
|
|
shared_by_a_and_b: i64,
|
||
|
|
}
|
||
|
|
|
||
|
|
#[local]
|
||
|
|
struct Local {
|
||
|
|
local_to_b: i64,
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(shared = [shared_by_a_and_b])]
|
||
|
|
fn a(_: a::Context) {}
|
||
|
|
|
||
|
|
#[task(shared = [shared_by_a_and_b], local = [local_to_b])]
|
||
|
|
fn b(_: b::Context) {}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<h2 id="symmetric-locks"><a class="header" href="#symmetric-locks">Symmetric locks</a></h2>
|
||
|
|
<p>Now RTIC utilizes symmetric locks, this means that the <code>lock</code> method need
|
||
|
|
to be used for all <code>shared</code> resource access.
|
||
|
|
In old code one could do the following as the high priority
|
||
|
|
task has exclusive access to the resource:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[task(priority = 2, resources = [r])]
|
||
|
|
fn foo(cx: foo::Context) {
|
||
|
|
cx.resources.r = /* ... */;
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(resources = [r])]
|
||
|
|
fn bar(cx: bar::Context) {
|
||
|
|
cx.resources.r.lock(|r| r = /* ... */);
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>And with symmetric locks one needs to use locks in both tasks:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[task(priority = 2, shared = [r])]
|
||
|
|
fn foo(cx: foo::Context) {
|
||
|
|
cx.shared.r.lock(|r| r = /* ... */);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(shared = [r])]
|
||
|
|
fn bar(cx: bar::Context) {
|
||
|
|
cx.shared.r.lock(|r| r = /* ... */);
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>Note that the performance does not change thanks to LLVM's optimizations which optimizes away unnecessary locks.</p>
|
||
|
|
<h2 id="lock-free-resource-access"><a class="header" href="#lock-free-resource-access">Lock-free resource access</a></h2>
|
||
|
|
<p>In RTIC 0.5 resources shared by tasks running at the same priority could be accessed <em>without</em> the <code>lock</code> API.
|
||
|
|
This is still possible in 1.0: the <code>#[shared]</code> resource must be annotated with the field-level <code>#[lock_free]</code> attribute.</p>
|
||
|
|
<p>v0.5 code:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>struct Resources {
|
||
|
|
counter: u64,
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(resources = [counter])]
|
||
|
|
fn a(cx: a::Context) {
|
||
|
|
*cx.resources.counter += 1;
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(resources = [counter])]
|
||
|
|
fn b(cx: b::Context) {
|
||
|
|
*cx.resources.counter += 1;
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>v1.0 code:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[shared]
|
||
|
|
struct Shared {
|
||
|
|
#[lock_free]
|
||
|
|
counter: u64,
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(shared = [counter])]
|
||
|
|
fn a(cx: a::Context) {
|
||
|
|
*cx.shared.counter += 1;
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(shared = [counter])]
|
||
|
|
fn b(cx: b::Context) {
|
||
|
|
*cx.shared.counter += 1;
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<h2 id="no-static-mut-transform"><a class="header" href="#no-static-mut-transform">no <code>static mut</code> transform</a></h2>
|
||
|
|
<p><code>static mut</code> variables are no longer transformed to safe <code>&'static mut</code> references.
|
||
|
|
Instead of that syntax, use the <code>local</code> argument in <code>#[init]</code>.</p>
|
||
|
|
<p>v0.5.x code:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[init]
|
||
|
|
fn init(_: init::Context) {
|
||
|
|
static mut BUFFER: [u8; 1024] = [0; 1024];
|
||
|
|
let buffer: &'static mut [u8; 1024] = BUFFER;
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>v1.0.0 code:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[init(local = [
|
||
|
|
buffer: [u8; 1024] = [0; 1024]
|
||
|
|
// type ^^^^^^^^^^^^ ^^^^^^^^^ initial value
|
||
|
|
])]
|
||
|
|
fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
|
||
|
|
let buffer: &'static mut [u8; 1024] = cx.local.buffer;
|
||
|
|
|
||
|
|
(Shared {}, Local {}, init::Monotonics())
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<h2 id="init-always-returns-late-resources"><a class="header" href="#init-always-returns-late-resources">Init always returns late resources</a></h2>
|
||
|
|
<p>In order to make the API more symmetric the #[init]-task always returns a late resource.</p>
|
||
|
|
<p>From this:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(device = lm3s6965)]
|
||
|
|
const APP: () = {
|
||
|
|
#[init]
|
||
|
|
fn init(_: init::Context) {
|
||
|
|
rtic::pend(Interrupt::UART0);
|
||
|
|
}
|
||
|
|
|
||
|
|
// [more code]
|
||
|
|
};
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>to this:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[rtic::app(device = lm3s6965)]
|
||
|
|
mod app {
|
||
|
|
#[shared]
|
||
|
|
struct MySharedResources {}
|
||
|
|
|
||
|
|
#[local]
|
||
|
|
struct MyLocalResources {}
|
||
|
|
|
||
|
|
#[init]
|
||
|
|
fn init(_: init::Context) -> (MySharedResources, MyLocalResources, init::Monotonics) {
|
||
|
|
rtic::pend(Interrupt::UART0);
|
||
|
|
|
||
|
|
(MySharedResources, MyLocalResources, init::Monotonics())
|
||
|
|
}
|
||
|
|
|
||
|
|
// [more code]
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<h2 id="spawn-from-anywhere"><a class="header" href="#spawn-from-anywhere">Spawn from anywhere</a></h2>
|
||
|
|
<p>With the new spawn/spawn_after/spawn_at interface,
|
||
|
|
old code requiring the context <code>cx</code> for spawning such as:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[task(spawn = [bar])]
|
||
|
|
fn foo(cx: foo::Context) {
|
||
|
|
cx.spawn.bar().unwrap();
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task(schedule = [bar])]
|
||
|
|
fn bar(cx: bar::Context) {
|
||
|
|
cx.schedule.foo(/* ... */).unwrap();
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>Will now be written as:</p>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>#[task]
|
||
|
|
fn foo(_c: foo::Context) {
|
||
|
|
bar::spawn().unwrap();
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task]
|
||
|
|
fn bar(_c: bar::Context) {
|
||
|
|
// Takes a Duration, relative to “now”
|
||
|
|
let spawn_handle = foo::spawn_after(/* ... */);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[task]
|
||
|
|
fn bar(_c: bar::Context) {
|
||
|
|
// Takes an Instant
|
||
|
|
let spawn_handle = foo::spawn_at(/* ... */);
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>Thus the requirement of having access to the context is dropped.</p>
|
||
|
|
<p>Note that the attributes <code>spawn</code>/<code>schedule</code> in the task definition are no longer needed.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="additions"><a class="header" href="#additions">Additions</a></h2>
|
||
|
|
<h3 id="extern-tasks"><a class="header" href="#extern-tasks">Extern tasks</a></h3>
|
||
|
|
<p>Both software and hardware tasks can now be defined external to the <code>mod app</code>.
|
||
|
|
Previously this was possible only by implementing a trampoline calling out the task implementation.</p>
|
||
|
|
<p>See examples <code>examples/extern_binds.rs</code> and <code>examples/extern_spawn.rs</code>.</p>
|
||
|
|
<p>This enables breaking apps into multiple files.</p>
|
||
|
|
|
||
|
|
</main>
|
||
|
|
|
||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
|
|
<!-- Mobile navigation buttons -->
|
||
|
|
<a rel="prev" href="../migration.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="../migration/migration_v4.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="../migration.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="../migration/migration_v4.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>
|