blob: 54689f6aa8846a74bc17dce2f673eca5c52b9b8c [file] [log] [blame]
<!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>SVC Functions</title>
<title>CMSIS-RTOS: SVC Functions</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-RTOS
&#160;<span id="projectnumber">Version 1.03</span>
</div>
<div id="projectbrief">Real-Time Operating System: API and RTX Reference Implementation.</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&#160;Page</span></a></li>
<li class="current"><a href="pages.html"><span>Usage&#160;and&#160;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('svcFunctions.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">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</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">SVC Functions </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Supervisor Calls (SVC) are exceptions targeted at software and operating systems for generating system function calls. They are sometimes called software interrupts. For example, instead of allowing user programs to directly access hardware, an operating system may provide access to hardware through an SVC. So when a user program wants to use certain hardware, it generates the SVC exception using SVC instructions, and then the software exception handler in the operating system is executed and provides the requested service to the user application. In this way, access to hardware is under the control of the OS, which can provide a more robust system by preventing the user applications from directly accessing the hardware.</p>
<p>SVC can also make software more portable because the user application does not need to know the programming details of the underlying hardware. The user program will only need to know the application programming interface (API) function ID and parameters; the actual hardware-level programming is handled by device drivers.</p>
<p>SVCs run in <b>Privileged</b> <b>Handler</b> mode of the <b>Cortex-M</b> core. SVC functions accept arguments and can return values. The functions are used in the same way as other functions; however, differences are hidden to the user. The ARMCC handles the differences and generates code instructions to call SVC functions. SVC functions are called by executing the SVC instruction. When executing SVC instructions, the controller changes to the Privileged Handler Mode.</p>
<p>Interrupts are <b>not disabled</b> in this mode. To protect SVC function from interrupts, you need to include the disable/enable intrinsic functions <b>__disable_irq()</b> and <b>__enable_irq()</b> in your code.</p>
<p>You can use SVC functions to access <b>protected</b> <b>peripherals</b>, for example, to configure NVIC and interrupts. This is required if you run tasks in unprivileged (protected) mode and you need to change interrupts from the task.</p>
<p>To implement SVC functions in your CMSIS-RTOS RTX kernel project, you need to:</p>
<ol type="1">
<li>Copy the file <b>SVC_Table.s</b> to your project folder and include it into your project. This file is available as a source code template.</li>
<li>Declare a function with a <b>__svc(x)</b> attribute. Use the first SVC number, starting from 1, that is free. <div class="fragment"><div class="line"><span class="keywordtype">void</span> __svc(1) inc_5bit (U32 *cp);</div>
</div><!-- fragment --></li>
<li>Write a function implementation and convert the function name into a <b>__SVC_x</b> function name. Later, this name is referenced by the linker from the <b>SVC_Table.s</b> module. You also need to disable/enable interrupts. <div class="fragment"><div class="line"><span class="keywordtype">void</span> __SVC_1 (U32 *cp) {</div>
<div class="line"> <span class="comment">// A protected function to increment a 5-bit counter. </span></div>
<div class="line"> __disable_irq();</div>
<div class="line"> cp = (*cp + 1) &amp; 0x1F;</div>
<div class="line"> __enable_irq();</div>
<div class="line">}</div>
</div><!-- fragment --></li>
<li>Add the function <b>__SVC_x</b> to the SVC function table in the <b>SVC_Table.s</b> module. First import it from other modules: <div class="fragment"><div class="line">; Import user SVC functions here.</div>
<div class="line"> IMPORT __SVC_1</div>
</div><!-- fragment --> Then, add a reference to it into the table: <div class="fragment"><div class="line">; Insert user SVC functions here. SVC 0 used by RTL Kernel.</div>
<div class="line"> DCD __SVC_1 ; user SVC <span class="keyword">function</span></div>
</div><!-- fragment --></li>
<li>Your <b>SVC</b> function should now look like this: <div class="fragment"><div class="line"><span class="keywordtype">void</span> __svc(1) inc_5bit (U32 *cp);</div>
<div class="line"><span class="keywordtype">void</span> __SVC_1 (U32 *cp) {</div>
<div class="line"> <span class="comment">// A protected function to increment a 5-bit counter. </span></div>
<div class="line"> __disable_irq();</div>
<div class="line"> cp = (*cp + 1) &amp; 0x1F;</div>
<div class="line"> __enable_irq();</div>
<div class="line">}</div>
</div><!-- fragment --></li>
</ol>
<dl class="section note"><dt>Note</dt><dd><ul>
<li>SVC function <b>0</b> is <b>reserved</b> for the CMSIS-RTOS RTX kernel.</li>
<li>Do not leave gaps when numbering SVC functions. They must occupy a <b>continuous</b> range of numbers starting from 1.</li>
<li>SVC functions can still be interrupted.</li>
<li>CMSIS-RTOS RTX must not be called before the main() function. </li>
</ul>
</dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="rtxImplementation.html">RTX Implementation</a></li><li class="navelem"><a class="el" href="configure.html">Configure RTX</a></li>
<li class="footer">Generated on Wed Jul 10 2019 15:21:02 for CMSIS-RTOS Version 1.03 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>