rtic/2/api/imxrt_ral/macro.write_reg.html

72 lines
9.2 KiB
HTML
Raw Permalink Normal View History

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Write to a RWRegister or UnsafeRWRegister."><title>write_reg in imxrt_ral - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-b0742ba02757f159.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="imxrt_ral" data-themes="" data-resource-suffix="" data-rustdoc-version="1.83.0 (90b35a623 2024-11-26)" data-channel="1.83.0" data-search-js="search-f0d225181b97f9a4.js" data-settings-js="settings-805db61a62df4bd2.js" ><script src="../static.files/storage-1d39b6787ed640ff.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-f070b9041d14864c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-0111fcff984fae8f.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc macro"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../imxrt_ral/index.html">imxrt_<wbr>ral</a><span class="version">0.5.3</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">write_<wbr>reg</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></li><li><a href="#usage" title="Usage">Usage</a></li><li><a href="#safety" title="Safety">Safety</a></li></ul></section><div id="rustdoc-modnav"><h2 class="in-crate"><a href="index.html">In crate imxrt_<wbr>ral</a></h2></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><span class="rustdoc-breadcrumbs"><a href="index.html">imxrt_ral</a></span><h1>Macro <span class="macro">write_reg</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../src/ral_registers/lib.rs.html#282">source</a> </span></div><pre class="rust item-decl"><span class="macro">macro_rules!</span> write_reg {
( <span class="macro-nonterminal">$periph</span>:path, <span class="macro-nonterminal">$instance</span>:expr, <span class="macro-nonterminal">$reg</span>:ident $([<span class="macro-nonterminal">$offset</span>:expr])<span class="kw-2">*</span>, $( <span class="macro-nonterminal">$field</span>:ident : <span class="macro-nonterminal">$value</span>:expr ),+ $(,)<span class="question-mark">? </span>) =&gt; { ... };
( <span class="macro-nonterminal">$periph</span>:path, <span class="macro-nonterminal">$instance</span>:expr, <span class="macro-nonterminal">$reg</span>:ident $([<span class="macro-nonterminal">$offset</span>:expr])<span class="kw-2">*</span>, <span class="macro-nonterminal">$value</span>:expr ) =&gt; { ... };
}</pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Write to a RWRegister or UnsafeRWRegister.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// Safely acquire the peripheral instance (will panic if already acquired)
</span><span class="kw">let </span>gpioa = stm32ral::gpio::GPIOA::take().unwrap();
<span class="comment">// Write some value to the register.
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, ODR, <span class="number">1</span>&lt;&lt;<span class="number">3</span>);
<span class="comment">// Write values to specific fields. Unspecified fields are written to 0.
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, MODER, MODER3: Output, MODER4: Analog);
<span class="comment">// Unsafe access without requiring you to first `take()` the instance
</span><span class="kw">unsafe </span>{ <span class="macro">write_reg!</span>(stm32ral::gpio, GPIOA, MODER, MODER3: Output, MODER4: Analog) };</code></pre></div>
<p>To support register arrays, each macro form also supports one or more array indices after the
register. For example, <code>write_reg!(stm32ral::gpio, gpioa, ODR[2], 42);</code> writes the value 42 to
the third register in an <code>ODR</code> register array.</p>
<h2 id="usage"><a class="doc-anchor" href="#usage">§</a>Usage</h2>
<p>Like <code>modify_reg!</code>, this macro can be used in two ways, either with a single value to write to
the whole register, or with multiple fields each with their own value.</p>
<p>In both cases, the first arguments are:</p>
<ul>
<li>the path to the peripheral module: <code>stm32ral::gpio</code>,</li>
<li>a reference to the instance of that peripheral: gpioa (anything which dereferences to
<code>RegisterBlock</code>, such as <code>Instance</code>, <code>&amp;Instance</code>, <code>&amp;RegisterBlock</code>, or
<code>*const RegisterBlock</code>),</li>
<li>the register (and offset, for arrays) you wish you access: <code>MODER</code> (a field on the
<code>RegisterBlock</code>).</li>
</ul>
<p>In the single-value usage, the final argument is just the value to write:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// Turn on PA3 (and turn everything else off).
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, ODR, <span class="number">1</span>&lt;&lt;<span class="number">3</span>);</code></pre></div>
<p>Otherwise, the remaining arguments are each <code>Field: Value</code> pairs:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// Set PA3 to Output, PA4 to Analog, and everything else to 0 (which is Input).
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, MODER, MODER3: <span class="number">0b01</span>, MODER4: <span class="number">0b11</span>);</code></pre></div>
<p>For fields with annotated values, you can also specify a named value:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// As above, but with named values.
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, MODER, MODER3: Output, MODER4: Analog);</code></pre></div>
<p>This macro expands to calling <code>(*$instance).$register.write(value)</code>,
where in the second usage, the value is computed as the bitwise OR of
each field value, which are masked and shifted appropriately for the given field.
The named values are brought into scope by <code>use $peripheral::$register::$field::*</code> for
each field. The same constants could just be specified manually:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// As above, but being explicit about named values.
</span><span class="macro">write_reg!</span>(stm32ral::gpio, gpioa, MODER, MODER3: stm32ral::gpio::MODER::MODER3::RW::Output,
MODER4: stm32ral::gpio::MODER::MODER4::RW::Analog);</code></pre></div>
<p>The fully expanded form is equivalent to:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// As above, but expanded.
</span>(<span class="kw-2">*</span>gpioa).MODER.write(
((stm32ral::gpio::MODER::MODER3::RW::Output &lt;&lt; stm32ral::gpio::MODER::MODER3::offset)
&amp; stm32ral::gpio::MODER::MODER3::mask)
|
((stm32ral::gpio::MODER::MODER4::RW::Analog &lt;&lt; stm32ral::gpio::MODER::MODER4::offset)
&amp; stm32ral::gpio::MODER::MODER4::mask)
);</code></pre></div>
<h2 id="safety"><a class="doc-anchor" href="#safety">§</a>Safety</h2>
<p>This macro will require an unsafe function or block when used with an UnsafeRWRegister,
but not if used with RWRegister.</p>
<p>When run in an unsafe context, peripheral instances are directly accessible without requiring
having called <code>take()</code> beforehand:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">unsafe </span>{ <span class="macro">write_reg!</span>(stm32ral::gpio, GPIOA, MODER, MODER3: Output, MODER4: Analog) };</code></pre></div>
<p>This works because <code>GPIOA</code> is a <code>*const RegisterBlock</code> in the <code>stm32ral::gpio</code> module;
and the macro brings such constants into scope and then dereferences the provided reference.</p>
</div></details></section></div></main></body></html>