blob: 1e62f450d6e7913eb874dab2f8faf01cac8056c9 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>SPI &mdash; Apache Mynewt latest documentation</title>
<link rel="shortcut icon" href="../../../../_static/mynewt-logo-only-newt32x32.png"/>
<link rel="stylesheet" href="../../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/sphinx_theme.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/bootstrap-3.0.3.min.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/v2.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/restructuredtext.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/css/overrides.css" type="text/css" />
<link rel="index" title="Index"
href="../../../../genindex.html"/>
<link rel="search" title="Search" href="../../../../search.html"/>
<link rel="top" title="Apache Mynewt latest documentation" href="../../../../index.html"/>
<link rel="up" title="Hardware Abstraction Layer" href="../hal.html"/>
<link rel="next" title="I2C" href="../hal_i2c/hal_i2c.html"/>
<link rel="prev" title="UART" href="../hal_uart/hal_uart.html"/>
<script src="../../../../_static/js/modernizr.min.js"></script>
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="not-front page-documentation" role="document" >
<div id="wrapper">
<div class="container">
<div id="banner" class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="../../../../_static/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released September 7, 2023)
</div>
</div>
</div>
</div>
<header>
<nav id="navbar" class="navbar navbar-inverse" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li class="important">
<a href="/quick-start/">Quick Start</a>
</li>
<li>
<a href="/about/">About</a>
</li>
<li>
<a href="/talks/">Talks</a>
</li>
<li class="active">
<a href="/documentation/">Documentation</a>
</li>
<li>
<a href="/download/">Download</a>
</li>
<li>
<a href="/community/">Community</a>
</li>
<li>
<a href="/events/">Events</a>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
</ul>
</div>
</div>
</nav>
</header>
<!-- STARTS MAIN CONTENT -->
<div id="main-content">
<div id="breadcrumb">
<div class="container">
<a href="/documentation/">Docs</a> /
<a href="../../../os_user_guide.html">OS User Guide</a> /
<a href="../hal.html">Hardware Abstraction Layer</a> /
SPI
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-core/edit/master/docs/os/modules/hal/hal_spi/hal_spi.rst" class="icon icon-github"
rel="nofollow"> Edit on GitHub</a>
</div>
</div>
</div>
<!-- STARTS CONTAINER -->
<div class="container">
<!-- STARTS .content -->
<div id="content" class="row">
<!-- STARTS .container-sidebar -->
<div class="container-sidebar col-xs-12 col-sm-3">
<div id="docSidebar" class="sticky-container">
<div role="search" class="sphinx-search">
<form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
<input type="text" name="q" placeholder="Search documentation" class="search-documentation" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<!-- Note: only works when deployed -->
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest" selected>
Version: latest
</option>
<option value="/v1_11_0" >
Version: 1.11.0
</option>
<option value="/v1_10_0" >
Version: 1.10.0
</option>
<option value="/v1_9_0" >
Version: 1.9.0
</option>
<option value="/v1_8_0" selected="selected" >
Version: 1.8.0
</option>
<option value="/v1_7_0" >
Version: 1.7.0
</option>
<option value="/v1_6_0" >
Version: 1.6.0
</option>
<option value="/v1_5_0" >
Version: 1.5.0
</option>
<option value="/v1_4_0" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select>
<div class="region region-sidebar">
<div class="docs-menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../get_started/index.html">Setup &amp; Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../concepts.html">Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../tutorials/tutorials.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../external_links.html">Third-party Resources</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../os_user_guide.html">OS User Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../core_os/mynewt_os.html">Kernel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../system_modules.html">System</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../hal.html">Hardware Abstraction</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../hal_timer/hal_timer.html">Timer</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_gpio/hal_gpio.html">GPIO</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_uart/hal_uart.html">UART</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">SPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_i2c/hal_i2c.html">I2C</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_flash/hal_flash.html">Flash</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_watchdog/hal_watchdog.html">Watchdog</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hal_bsp/hal_bsp.html">BSP</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../bootloader/bootloader.html">Secure Bootloader</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../split/split.html">Split Images</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../core_os/porting/port_os.html">Porting Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../baselibc.html">Baselibc</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../drivers/driver.html">Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../devmgmt/newtmgr.html">Device Management with Newt Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../mcumgr/mcumgr.html">Device Management with MCUmgr</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../imgmgr/imgmgr.html">Image Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sysinitconfig/sysinitconfig.html">Compile-Time Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../fs/fs.html">File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../fcb/fcb.html">Flash Circular Buffer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sensor_framework/sensor_framework.html">Sensor Framework</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../testutil/testutil.html">Test Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../json/json.html">JSON</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../mfg/mfg.html">Manufacturing support</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../../network/index.html">BLE User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../newt/index.html">Newt Tool Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../newtmgr/index.html">Newt Manager Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../mynewt_faq/index.html">Mynewt FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../../misc/index.html">Appendix</a></li>
</ul>
</div>
</div>
</div>
<!-- ENDS STICKY CONTAINER -->
</div>
<!-- ENDS .container-sidebar -->
<div class="col-xs-12 col-sm-9">
<div class="alert alert-warning">
<p>
Version 1.8.0 is not the most recent version of the
Apache Mynewt documentation. Click <a href="/latest">here</a> to
read the latest version.
</p>
</div>
<div class="">
<div class="rst-content">
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="spi">
<h1>SPI<a class="headerlink" href="#spi" title="Permalink to this headline"></a></h1>
<p>SPI (Serial Peripheral Interface) is a synchronous 4-wire serial
interface commonly used to connect components in embedded systems.</p>
<p>For a detailed description of SPI, see
<a class="reference external" href="https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus">Wikipedia</a>.</p>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
<p>The Mynewt HAL interface supports the SPI master functionality with both
blocking and non-blocking interface. SPI slave functionality is
supported in non-blocking mode.</p>
</div>
<div class="section" id="theory-of-operation">
<h2>Theory Of Operation<a class="headerlink" href="#theory-of-operation" title="Permalink to this headline"></a></h2>
<p>SPI is called a 4-wire interface because of the 4 signals, MISO, MOSI,
CLK, and SS. The SS signal (slave select) is an active low signal that
activates a SPI slave device. This is how a master “addresses” a
particular slave device. Often this signal is also referred to as “chip
select” as it selects particular slave device for communications.</p>
<p>The Mynewt SPI HAL has blocking and non-blocking transfers. Blocking
means that the API call to transfer a byte will wait until the byte
completes transmissions before the function returns. Blocking interface
can be used for only the master slave SPI type. Non-blocking means he
function returns control to the execution environment immediately after
the API call and a callback function is executed at the completion of
the transmission. Non-blocking interface can be used for both master and
slave SPI types.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">hal_spi_config</span></code> method in the API above allows the SPI to be
configured with appropriate settings for master or slave. It Must be
called after the spi is initialized (i.e. after hal_spi_init is
called) and when the spi is disabled (i.e. user must call
hal_spi_disable if the spi has been enabled through hal_spi_enable
prior to calling this function). It can also be used to reconfigure an
initialized SPI (assuming it is disabled as described previously).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">hal_spi_config</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">spi_num</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">hal_spi_settings</span><span class="w"> </span><span class="o">*</span><span class="n">psettings</span><span class="p">);</span>
</pre></div>
</div>
<p>The SPI settings consist of the following:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">hal_spi_settings</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">data_mode</span><span class="p">;</span>
<span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">data_order</span><span class="p">;</span>
<span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">word_size</span><span class="p">;</span>
<span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">baudrate</span><span class="p">;</span><span class="w"> </span><span class="cm">/* baudrate in kHz */</span>
<span class="p">};</span>
</pre></div>
</div>
<p>The Mynewt SPI HAL does not include built-in SS (Slave Select)
signaling. It’s up to the hal_spi user to control their own SS pins.
Typically applications will do this with GPIO.</p>
</div>
<div class="section" id="api">
<h2>API<a class="headerlink" href="#api" title="Permalink to this headline"></a></h2>
<dl class="c type">
<dt id="c.hal_spi_txrx_cb">
<span class="target" id="group___h_a_l_spi_1ga2eaa9ef4b5bdf3048b6a942462ad1ec1"></span><em class="property"><span class="pre">typedef</span> </em><span class="pre">void</span> <span class="pre">(</span><span class="pre">*</span><code class="sig-name descname"><span class="pre">hal_spi_txrx_cb</span></code><span class="pre">)</span><span class="sig-paren">(</span><span class="pre">void</span> <span class="pre">*</span><span class="pre">arg</span>, <span class="pre">int</span> <span class="pre">len</span><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_txrx_cb" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
<dl class="c function">
<dt id="c.hal_spi_init">
<span class="target" id="group___h_a_l_spi_1ga2b7019ae59d7b80d9a712221e564f2c5"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_init</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">cfg</span></em>, <span class="pre">uint8_t</span> <em><span class="pre">spi_type</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_init" title="Permalink to this definition"></a><br /></dt>
<dd><p>Initialize the SPI, given by spi_num. </p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: The number of the SPI to initialize </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cfg</span></code>: HW/MCU specific configuration, passed to the underlying implementation, providing extra configuration. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">spi_type</span></code>: SPI type (master or slave)</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_init_hw">
<span class="target" id="group___h_a_l_spi_1gaf6c66abb08c072baf534f8f91191b16a"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_init_hw</span></code><span class="sig-paren">(</span><span class="pre">uint8_t</span> <em><span class="pre">spi_num</span></em>, <span class="pre">uint8_t</span> <em><span class="pre">spi_type</span></em>, <em class="property"><span class="pre">const</span></em> <em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="#c.hal_spi_hw_settings" title="hal_spi_hw_settings"><span class="pre">hal_spi_hw_settings</span></a> <span class="pre">*</span><em><span class="pre">cfg</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_init_hw" title="Permalink to this definition"></a><br /></dt>
<dd><p>Initialize SPI controller. </p>
<p>This initializes SPI controller hardware before 1st use. Shall be called only once.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>0 on success, non-zero error code on failure </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: Number of SPI controller </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cfg</span></code>: Configuration</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_config">
<span class="target" id="group___h_a_l_spi_1ga8546bc1ec3e14eabc80bb56319d6628e"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_config</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="#c.hal_spi_settings" title="hal_spi_settings"><span class="pre">hal_spi_settings</span></a> <span class="pre">*</span><em><span class="pre">psettings</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_config" title="Permalink to this definition"></a><br /></dt>
<dd><p>Configure the spi. </p>
<p>Must be called after the spi is initialized (after hal_spi_init is called) and when the spi is disabled (user must call hal_spi_disable if the spi has been enabled through hal_spi_enable prior to calling this function). Can also be used to reconfigure an initialized SPI (assuming it is disabled as described previously).</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: The number of the SPI to configure. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">psettings</span></code>: The settings to configure this SPI with</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_set_txrx_cb">
<span class="target" id="group___h_a_l_spi_1gaa87db99ce986ed1b1385590cea1f32a8"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_set_txrx_cb</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <a class="reference internal" href="#c.hal_spi_txrx_cb" title="hal_spi_txrx_cb"><span class="pre">hal_spi_txrx_cb</span></a> <em><span class="pre">txrx_cb</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">arg</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_set_txrx_cb" title="Permalink to this definition"></a><br /></dt>
<dd><p>Sets the txrx callback (executed at interrupt context) when the buffer is transferred by the master or the slave using the non-blocking API. </p>
<p>Cannot be called when the spi is enabled. This callback will also be called when chip select is de-asserted on the slave.</p>
<p>NOTE: This callback is only used for the non-blocking interface and must be called prior to using the non-blocking API.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: SPI interface on which to set callback </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">txrx</span></code>: Callback function </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arg</span></code>: Argument to be passed to callback function</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_enable">
<span class="target" id="group___h_a_l_spi_1gac20b051b9e98152804dd0801a57f1360"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_enable</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_enable" title="Permalink to this definition"></a><br /></dt>
<dd><p>Enables the SPI. </p>
<p>This does not start a transmit or receive operation; it is used for power mgmt. Cannot be called when a SPI transfer is in progress.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: </p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_disable">
<span class="target" id="group___h_a_l_spi_1gae2fca841a1ac4dd055e6247449bf45ab"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_disable</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_disable" title="Permalink to this definition"></a><br /></dt>
<dd><p>Disables the SPI. </p>
<p>Used for power mgmt. It will halt any current SPI transfers in progress.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: </p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_tx_val">
<span class="target" id="group___h_a_l_spi_1gafae520402e8829bbbca450f504851cd5"></span><span class="pre">uint16_t</span> <code class="sig-name descname"><span class="pre">hal_spi_tx_val</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <span class="pre">uint16_t</span> <em><span class="pre">val</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_tx_val" title="Permalink to this definition"></a><br /></dt>
<dd><p>Blocking call to send a value on the SPI. </p>
<p>Returns the value received from the SPI slave.</p>
<p>MASTER: Sends the value and returns the received value from the slave. SLAVE: Invalid API. Returns 0xFFFF</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>uint16_t Value received on SPI interface from slave. Returns 0xFFFF if called when the SPI is configured to be a slave </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: Spi interface to use </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">val</span></code>: Value to send</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_txrx">
<span class="target" id="group___h_a_l_spi_1ga553da06a116ddadf0df93343f51f1432"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_txrx</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">txbuf</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">rxbuf</span></em>, <span class="pre">int</span> <em><span class="pre">cnt</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_txrx" title="Permalink to this definition"></a><br /></dt>
<dd><p>Blocking interface to send a buffer and store the received values from the slave. </p>
<p>The transmit and receive buffers are either arrays of 8-bit (uint8_t) values or 16-bit values depending on whether the spi is configured for 8 bit data or more than 8 bits per value. The ‘cnt’ parameter is the number of 8-bit or 16-bit values. Thus, if ‘cnt’ is 10, txbuf/rxbuf would point to an array of size 10 (in bytes) if the SPI is using 8-bit data; otherwise txbuf/rxbuf would point to an array of size 20 bytes (ten, uint16_t values).</p>
<p>NOTE: these buffers are in the native endian-ness of the platform. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>MASTER: master sends all the values in the buffer and stores the
stores the values in the receive buffer if rxbuf is not NULL.
The txbuf parameter cannot be NULL.
SLAVE: cannot be called for a slave; returns -1
</pre></div>
</div>
</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: SPI interface to use </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">txbuf</span></code>: Pointer to buffer where values to transmit are stored. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">rxbuf</span></code>: Pointer to buffer to store values received from peer. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cnt</span></code>: Number of 8-bit or 16-bit values to be transferred.</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_txrx_noblock">
<span class="target" id="group___h_a_l_spi_1gaf63f67ca8a93d7c93061565e9be1385b"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_txrx_noblock</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">txbuf</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">rxbuf</span></em>, <span class="pre">int</span> <em><span class="pre">cnt</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_txrx_noblock" title="Permalink to this definition"></a><br /></dt>
<dd><p>Non-blocking interface to send a buffer and store received values. </p>
<p>Can be used for both master and slave SPI types. The user must configure the callback (using hal_spi_set_txrx_cb); the txrx callback is executed at interrupt context when the buffer is sent.</p>
<p>The transmit and receive buffers are either arrays of 8-bit (uint8_t) values or 16-bit values depending on whether the spi is configured for 8 bit data or more than 8 bits per value. The ‘cnt’ parameter is the number of 8-bit or 16-bit values. Thus, if ‘cnt’ is 10, txbuf/rxbuf would point to an array of size 10 (in bytes) if the SPI is using 8-bit data; otherwise txbuf/rxbuf would point to an array of size 20 bytes (ten, uint16_t values).</p>
<p>NOTE: these buffers are in the native endian-ness of the platform. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>MASTER: master sends all the values in the buffer and stores the
stores the values in the receive buffer if rxbuf is not NULL.
The txbuf parameter cannot be NULL
SLAVE: Slave &quot;preloads&quot; the data to be sent to the master (values
stored in txbuf) and places received data from master in rxbuf
(if not NULL). The txrx callback occurs when len values are
transferred or master de-asserts chip select. If txbuf is NULL,
the slave transfers its default byte. Both rxbuf and txbuf cannot
be NULL.
</pre></div>
</div>
</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: SPI interface to use </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">txbuf</span></code>: Pointer to buffer where values to transmit are stored. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">rxbuf</span></code>: Pointer to buffer to store values received from peer. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cnt</span></code>: Number of 8-bit or 16-bit values to be transferred.</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_slave_set_def_tx_val">
<span class="target" id="group___h_a_l_spi_1gadc32383878ad19d66fac43f6b011991e"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_slave_set_def_tx_val</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em>, <span class="pre">uint16_t</span> <em><span class="pre">val</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_slave_set_def_tx_val" title="Permalink to this definition"></a><br /></dt>
<dd><p>Sets the default value transferred by the slave. </p>
<p>Not valid for master</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: SPI interface to use</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_abort">
<span class="target" id="group___h_a_l_spi_1gaf9e6514439403074fb2cb9ebd5929639"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_abort</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">spi_num</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_abort" title="Permalink to this definition"></a><br /></dt>
<dd><p>This aborts the current transfer but keeps the spi enabled. </p>
<p><p>NOTE: does not return an error if no transfer was in progress. </p>
<dl class="simple">
<dt><strong>Return</strong></dt><dd><p>int 0 on success, non-zero error code on failure.</p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">spi_num</span></code>: SPI interface on which transfer should be aborted.</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.hal_spi_data_mode_breakout">
<span class="target" id="group___h_a_l_spi_1ga4a51284d7a86783244406751de4c6b14"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">hal_spi_data_mode_breakout</span></code><span class="sig-paren">(</span><span class="pre">uint8_t</span> <em><span class="pre">data_mode</span></em>, <span class="pre">int</span> <span class="pre">*</span><em><span class="pre">out_cpol</span></em>, <span class="pre">int</span> <span class="pre">*</span><em><span class="pre">out_cpha</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.hal_spi_data_mode_breakout" title="Permalink to this definition"></a><br /></dt>
<dd><p>Extracts CPOL and CPHA values from a data-mode constant. </p>
<p>Utility function, defined once for every MCU.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>0 on success; nonzero on invalid input. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">data_mode</span></code>: The HAL_SPI_MODE value to convert. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">out_cpol</span></code>: The CPOL gets written here on success. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">out_cpha</span></code>: The CPHA gets written here on success.</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_TYPE_MASTER">
<span class="target" id="group___h_a_l_spi_1gaa9052e61a231f7317781cd6a4ffe8b5e"></span><code class="sig-name descname"><span class="pre">HAL_SPI_TYPE_MASTER</span></code><a class="headerlink" href="#c.HAL_SPI_TYPE_MASTER" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_TYPE_SLAVE">
<span class="target" id="group___h_a_l_spi_1gaaee6eee2ec864affda97df74eb55933f"></span><code class="sig-name descname"><span class="pre">HAL_SPI_TYPE_SLAVE</span></code><a class="headerlink" href="#c.HAL_SPI_TYPE_SLAVE" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_MODE0">
<span class="target" id="group___h_a_l_spi_1gaf269bbeaf787deae7de03b7e1c8ede4f"></span><code class="sig-name descname"><span class="pre">HAL_SPI_MODE0</span></code><a class="headerlink" href="#c.HAL_SPI_MODE0" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI mode 0. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_MODE1">
<span class="target" id="group___h_a_l_spi_1gaa4fae1c5b56c54e8bb905d4774b6c21e"></span><code class="sig-name descname"><span class="pre">HAL_SPI_MODE1</span></code><a class="headerlink" href="#c.HAL_SPI_MODE1" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI mode 1. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_MODE2">
<span class="target" id="group___h_a_l_spi_1ga9a4f7a6b535bf91c6d9eadc94876b3ab"></span><code class="sig-name descname"><span class="pre">HAL_SPI_MODE2</span></code><a class="headerlink" href="#c.HAL_SPI_MODE2" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI mode 2. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_MODE3">
<span class="target" id="group___h_a_l_spi_1gab3d553cb6ad796c81cf8da03fd162410"></span><code class="sig-name descname"><span class="pre">HAL_SPI_MODE3</span></code><a class="headerlink" href="#c.HAL_SPI_MODE3" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI mode 3. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_MSB_FIRST">
<span class="target" id="group___h_a_l_spi_1ga141f16a65d039c8587710056aa4bcf61"></span><code class="sig-name descname"><span class="pre">HAL_SPI_MSB_FIRST</span></code><a class="headerlink" href="#c.HAL_SPI_MSB_FIRST" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI data order, most significant bit first. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_LSB_FIRST">
<span class="target" id="group___h_a_l_spi_1gad78a641f633979ca311bf4adb0c3c282"></span><code class="sig-name descname"><span class="pre">HAL_SPI_LSB_FIRST</span></code><a class="headerlink" href="#c.HAL_SPI_LSB_FIRST" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI data order, least significant bit first. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_WORD_SIZE_8BIT">
<span class="target" id="group___h_a_l_spi_1gac0c2a0f9c70877319df3eda695953b7c"></span><code class="sig-name descname"><span class="pre">HAL_SPI_WORD_SIZE_8BIT</span></code><a class="headerlink" href="#c.HAL_SPI_WORD_SIZE_8BIT" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI word size 8 bit. </p>
</dd></dl>
<dl class="c macro">
<dt id="c.HAL_SPI_WORD_SIZE_9BIT">
<span class="target" id="group___h_a_l_spi_1gad6372e8ec76058a16520e19fe33c1841"></span><code class="sig-name descname"><span class="pre">HAL_SPI_WORD_SIZE_9BIT</span></code><a class="headerlink" href="#c.HAL_SPI_WORD_SIZE_9BIT" title="Permalink to this definition"></a><br /></dt>
<dd><p>SPI word size 9 bit. </p>
</dd></dl>
<dl class="c struct">
<dt id="c.hal_spi_hw_settings">
<span class="target" id="structhal__spi__hw__settings"></span><em class="property"><span class="pre">struct</span> </em><code class="sig-name descname"><span class="pre">hal_spi_hw_settings</span></code><a class="headerlink" href="#c.hal_spi_hw_settings" title="Permalink to this definition"></a><br /></dt>
<dd><em>#include &lt;hal_spi.h&gt;</em><p>SPI controller hardware settings. </p>
</dd></dl>
<dl class="c struct">
<dt id="c.hal_spi_settings">
<span class="target" id="structhal__spi__settings"></span><em class="property"><span class="pre">struct</span> </em><code class="sig-name descname"><span class="pre">hal_spi_settings</span></code><a class="headerlink" href="#c.hal_spi_settings" title="Permalink to this definition"></a><br /></dt>
<dd><em>#include &lt;hal_spi.h&gt;</em><p>since one spi device can control multiple devices, some configuration can be changed on the fly from the hal </p>
<div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-members">Public Members</p>
<dl class="c var">
<dt id="c.hal_spi_settings.data_mode">
<span class="target" id="structhal__spi__settings_1a7c948a0d643cf02d65afb68479c27525"></span><span class="pre">uint8_t</span> <code class="sig-name descname"><span class="pre">data_mode</span></code><a class="headerlink" href="#c.hal_spi_settings.data_mode" title="Permalink to this definition"></a><br /></dt>
<dd><p>Data mode of SPI driver, defined by HAL_SPI_MODEn. </p>
</dd></dl>
<dl class="c var">
<dt id="c.hal_spi_settings.data_order">
<span class="target" id="structhal__spi__settings_1a8604e51cedd73c00d9ec91f3a77429e6"></span><span class="pre">uint8_t</span> <code class="sig-name descname"><span class="pre">data_order</span></code><a class="headerlink" href="#c.hal_spi_settings.data_order" title="Permalink to this definition"></a><br /></dt>
<dd><p>Data order, either HAL_SPI_MSB_FIRST or HAL_SPI_LSB_FIRST. </p>
</dd></dl>
<dl class="c var">
<dt id="c.hal_spi_settings.word_size">
<span class="target" id="structhal__spi__settings_1ab609e05b0ae7b008b28a06dd9baba450"></span><span class="pre">uint8_t</span> <code class="sig-name descname"><span class="pre">word_size</span></code><a class="headerlink" href="#c.hal_spi_settings.word_size" title="Permalink to this definition"></a><br /></dt>
<dd><p>The word size of the SPI transaction, either 8-bit or 9-bit. </p>
</dd></dl>
<dl class="c var">
<dt id="c.hal_spi_settings.baudrate">
<span class="target" id="structhal__spi__settings_1a3e1c672197908a71a947c5c9cc94236c"></span><span class="pre">uint32_t</span> <code class="sig-name descname"><span class="pre">baudrate</span></code><a class="headerlink" href="#c.hal_spi_settings.baudrate" title="Permalink to this definition"></a><br /></dt>
<dd><p>Baudrate in kHz. </p>
</dd></dl>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="../hal_i2c/hal_i2c.html" class="btn btn-neutral float-right" title="I2C" accesskey="n">Next: I2C <span class="fa fa-arrow-circle-right"></span></a>
<a href="../hal_uart/hal_uart.html" class="btn btn-neutral" title="UART" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: UART</a>
</div>
</div>
</div>
</div>
<!-- ENDS CONTENT SECTION -->
</div>
<!-- ENDS .content -->
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<img src="../../../../_static/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt project logo are either
registered trademarks or trademarks of the Apache Software Foundation in the United States and other countries.
</small>
<a href="">
<img src="../../../../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
</div>
</div>
</footer>
</div>
<!-- ENDS #wrapper -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../../../',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
LINK_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../../_static/js/bootstrap-3.0.3.min.js"></script>
<script type="text/javascript" src="../../../../_static/js/affix.js"></script>
<script type="text/javascript" src="../../../../_static/js/main.js"></script>
</body>
</html>