170 lines
12 KiB
HTML
170 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<title>Use of Storage APIs</title>
|
||
|
|
<title>CMSIS-Driver: Use of Storage APIs</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<link href="cmsis.css" rel="stylesheet" type="text/css" />
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<script type="text/javascript" src="printComponentTabs.js"></script>
|
||
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="resize.js"></script>
|
||
|
|
<script type="text/javascript" src="navtree.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(document).ready(initResizable);
|
||
|
|
$(window).load(resizeHeight);
|
||
|
|
</script>
|
||
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="search/search.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(document).ready(function() { searchBox.OnSelectItem(0); });
|
||
|
|
</script>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 46px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
|
||
|
|
<td style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">CMSIS-Driver
|
||
|
|
 <span id="projectnumber">Version 2.05</span>
|
||
|
|
</div>
|
||
|
|
<div id="projectbrief">Peripheral Interface for Middleware and Application Code</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<div id="CMSISnav" class="tabs1">
|
||
|
|
<ul class="tablist">
|
||
|
|
<script type="text/javascript">
|
||
|
|
<!--
|
||
|
|
writeComponentTabs.call(this);
|
||
|
|
//-->
|
||
|
|
</script>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<!-- Generated by Doxygen 1.8.6 -->
|
||
|
|
<script type="text/javascript">
|
||
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
|
|
</script>
|
||
|
|
<div id="navrow1" class="tabs">
|
||
|
|
<ul class="tablist">
|
||
|
|
<li><a href="index.html"><span>Main Page</span></a></li>
|
||
|
|
<li><a href="pages.html"><span>Usage and Description</span></a></li>
|
||
|
|
<li><a href="modules.html"><span>Reference</span></a></li>
|
||
|
|
<li>
|
||
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
||
|
|
<span class="left">
|
||
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
alt=""/>
|
||
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
||
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
||
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
||
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
||
|
|
</span><span class="right">
|
||
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
||
|
|
</span>
|
||
|
|
</div>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
|
|
<div id="nav-tree">
|
||
|
|
<div id="nav-tree-contents">
|
||
|
|
<div id="nav-sync" class="sync"></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
||
|
|
class="ui-resizable-handle">
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(document).ready(function(){initNavTree('group__StorageDriverFunctions.html','');});
|
||
|
|
</script>
|
||
|
|
<div id="doc-content">
|
||
|
|
<!-- window showing the filter options -->
|
||
|
|
<div id="MSearchSelectWindow"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div>
|
||
|
|
|
||
|
|
<!-- iframe showing the search results (closed by default) -->
|
||
|
|
<div id="MSearchResultsWindow">
|
||
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
||
|
|
name="MSearchResults" id="MSearchResults">
|
||
|
|
</iframe>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">Use of Storage APIs<div class="ingroups"><a class="el" href="group__storage__interface__gr.html">Storage Interface</a></div></div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<p>Function pointers within <a class="el" href="group__storage__interface__gr.html#structARM__DRIVER__STORAGE">ARM_DRIVER_STORAGE</a> form the set of operations constituting the Storage driver. Their implementation is platform-specific, and needs to be supplied by the porting effort.</p>
|
||
|
|
<p>Some of these APIs will always operate synchronously:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gaf28193431b1a2ee64b22bfb36aed27e3">ARM_Storage_GetVersion</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga8378b3901dfe76d8f31728a50e10dae2">ARM_Storage_GetCapabilities</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga29e7bfe78f41abb16973bdb4e0188a20">ARM_Storage_GetStatus</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gad557e8e6e33cd4528d398ecf4dddc747">ARM_Storage_GetInfo</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga5a1934750a51c74b8b0fea52588a3b9a">ARM_Storage_ResolveAddress</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gad318f8cb38626cbeea1fcf36a0977c44">ARM_Storage_GetNextBlock</a> and</li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga5fe9d27ce8afe65124dec62566114073">ARM_Storage_GetBlock</a>.</li>
|
||
|
|
</ul>
|
||
|
|
<p>This means that control returns to the caller with a relevant status code only after the completion of the operation (or the discovery of a failure condition).</p>
|
||
|
|
<p>The remainder of the APIs:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gacc5dc090a35ac16caff8957030eaa174">ARM_Storage_Initialize</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga1d14b15ddcda2836c6e3c1d0b5e60dca">ARM_Storage_Uninitialize</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga979a2484bf05b2986de95a5d98307d54">ARM_Storage_PowerControl</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gabaa24553c165add98020434c980b3ab4">ARM_Storage_ReadData</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gabd20d561854c06918b0515b6c1bba230">ARM_Storage_ProgramData</a></li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#gaceef4851d9181cce65c8b2d05f4429bc">ARM_Storage_Erase</a> and</li>
|
||
|
|
<li><a class="el" href="group__storage__interface__gr.html#ga04e77387a3c628d6fc661e82f7daddaa">ARM_Storage_EraseAll</a></li>
|
||
|
|
</ul>
|
||
|
|
<p>can function asynchronously if the underlying controller supports it; that is if <a class="el" href="group__storage__interface__gr.html#a15ade4ca762bc6ce72d435a16febb4cc" title="Used to indicate if APIs like initialize, read, erase, program, etc. can operate in asynchronous mode...">ARM_STORAGE_CAPABILITIES::asynchronous_ops</a> is set. In the case of asynchronous operation, the invocation returns early (with ARM_DRIVER_OK) and results in a completion callback later. If <a class="el" href="group__storage__interface__gr.html#a15ade4ca762bc6ce72d435a16febb4cc" title="Used to indicate if APIs like initialize, read, erase, program, etc. can operate in asynchronous mode...">ARM_STORAGE_CAPABILITIES::asynchronous_ops</a> is not set, then all such APIs execute synchronously, and control returns to the caller with a status code only after the completion of the operation (or the discovery of a failure condition).</p>
|
||
|
|
<p>If <a class="el" href="group__storage__interface__gr.html#a15ade4ca762bc6ce72d435a16febb4cc" title="Used to indicate if APIs like initialize, read, erase, program, etc. can operate in asynchronous mode...">ARM_STORAGE_CAPABILITIES::asynchronous_ops</a> is set, a storage driver may still choose to execute asynchronous operations in a synchronous manner. If so, the driver returns a positive value to indicate successful synchronous completion (or an error code in case of failure) and no further invocation of completion callback should be expected. The expected return value for synchronous completion of such asynchronous operations varies depending on the operation. For operations involving data access, it often equals the amount of data transferred or affected. For non data-transfer operations, such as EraseAll or Initialize, it is usually 1.</p>
|
||
|
|
<p>Here's a code snippet to suggest how asynchronous APIs might be used by callers to handle both synchronous and asynchronous execution by the underlying storage driver: </p>
|
||
|
|
<div class="fragment"><div class="line">ASSERT(<a class="code" href="group__execution__status.html#ga85752c5de59e8adeb001e35ff5be6be7">ARM_DRIVER_OK</a> == 0); <span class="comment">// this is a precondition; it doesn't need to be put in code</span></div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line">int32_t returnValue = drv->asynchronousAPI(...);</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"><span class="keywordflow">if</span> (returnValue < <a class="code" href="group__execution__status.html#ga85752c5de59e8adeb001e35ff5be6be7">ARM_DRIVER_OK</a>) {</div>
|
||
|
|
<div class="line"> <span class="comment">// handle error.</span></div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line">} <span class="keywordflow">else</span> <span class="keywordflow">if</span> (returnValue == <a class="code" href="group__execution__status.html#ga85752c5de59e8adeb001e35ff5be6be7">ARM_DRIVER_OK</a>) {</div>
|
||
|
|
<div class="line"> ASSERT(drv->GetCapabilities().asynchronous_ops == 1);</div>
|
||
|
|
<div class="line"> <span class="comment">// handle early return from asynchronous execution; remainder of the work is done in the callback handler.</span></div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line">} <span class="keywordflow">else</span> {</div>
|
||
|
|
<div class="line"> ASSERT(returnValue == EXPECTED_RETURN_VALUE_FOR_SYNCHRONOUS_COMPLETION);</div>
|
||
|
|
<div class="line"> <span class="comment">// handle synchronous completion.</span></div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>THis example is mixing synchronous and asynchronous APIs: <a class="el" href="group__SampleUseOfStorageDriver.html">Sample Use of Storage Driver</a> </p>
|
||
|
|
</div><!-- contents -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<!-- start footer part -->
|
||
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
|
|
<ul>
|
||
|
|
<li class="footer">Generated on Wed Feb 8 2017 10:20:44 for CMSIS-Driver by ARM Ltd. All rights reserved.
|
||
|
|
<!--
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
|
||
|
|
-->
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|