<!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>stacktest library: stacktest.h File Reference</title>
<link href="html/tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="html/doxygen.css" rel="stylesheet" type="text/css" />
</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: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">stacktest library
 <span id="projectnumber">v0.5</span>
</div>
<div id="projectbrief">For testing how much stack space one or more functions running CMM/LMM code in another cog use.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="html/index.html"><span>Main Page</span></a></li>
<li class="current"><a href="html/files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="html/files.html"><span>File List</span></a></li>
<li><a href="html/globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">stacktest.h File Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>Provides a tool for testing how much of a cog's stack has been used.
<a href="#details">More...</a></p>
<div class="textblock"><code>#include "simpletools.h"</code><br/>
</div>
<p><a href="html/stacktest_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a4cb9ecdd69ae89091f2b62614a62fd97"><td class="memItemLeft" align="right" valign="top">int * </td><td class="memItemRight" valign="bottom"><a class="el" href="html/stacktest_8h.html#a4cb9ecdd69ae89091f2b62614a62fd97">cog_runStackTest</a> (void(*function)(void *par), int stacksize)</td></tr>
<tr class="memdesc:a4cb9ecdd69ae89091f2b62614a62fd97"><td class="mdescLeft"> </td><td class="mdescRight">Runs a function's code in the next available cog (processor) and tracks how much of the call stack the cog actually utilizes. After exercising the code running in another cog to its fullest extent with a liberal stack size, call cog_endStackTest to find out how much stack was actually used. Then reduce the stack accordingly to reduce the application's or library's overall memory footprint. <a href="#a4cb9ecdd69ae89091f2b62614a62fd97"></a><br/></td></tr>
<tr class="memitem:aac4c00806d2d5639379e4c6a7a1d8d17"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="html/stacktest_8h.html#aac4c00806d2d5639379e4c6a7a1d8d17">cog_endStackTest</a> (int *coginfo)</td></tr>
<tr class="memdesc:aac4c00806d2d5639379e4c6a7a1d8d17"><td class="mdescLeft"> </td><td class="mdescRight">Ends function code running in another cog that was launched by cog_runStackTest and returns the number of int variables that were actually used in the stack. Provided the test code exercised ALL of the function's features in that other cog, you can reduce the stack space to some value slightly above the one cog_endStackTest reports. <a href="#aac4c00806d2d5639379e4c6a7a1d8d17"></a><br/></td></tr>
<tr class="memitem:a55ac6c6c1308c59109c5df5a19a3d018"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="html/stacktest_8h.html#a55ac6c6c1308c59109c5df5a19a3d018">cogstart_stackTest</a> (void(*func)(void *), void *par, void *stack, size_t stacksize)</td></tr>
<tr class="memdesc:a55ac6c6c1308c59109c5df5a19a3d018"><td class="mdescLeft"> </td><td class="mdescRight">Starts a function's code in the next available cog (processor) and tracks how much of the call stack the cog actually utilizes. After exercising the code running in another cog to its fullest extent with a liberal stack size, call cogstop_stackTest to find out how much stack was actually used. Then reduce the stack accordingly to reduce the application's or library's overall memory footprint. <a href="#a55ac6c6c1308c59109c5df5a19a3d018"></a><br/></td></tr>
<tr class="memitem:ab7c6af49e4f8a4563d278dd7c9e4f1bc"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="html/stacktest_8h.html#ab7c6af49e4f8a4563d278dd7c9e4f1bc">cogstop_stackTest</a> (int cog, void *stack)</td></tr>
<tr class="memdesc:ab7c6af49e4f8a4563d278dd7c9e4f1bc"><td class="mdescLeft"> </td><td class="mdescRight">Stops function code running in another cog that was launched by cogstart_stackTest and returns the number of int variables that were actually used in the stack. Provided enough stack space was set aside and the test code exercised ALL of the function's features in that other cog, you can reduce the stack space to some value slightly above the one cogstop_stackTest reports. <a href="#ab7c6af49e4f8a4563d278dd7c9e4f1bc"></a><br/></td></tr>
</table>
<a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>Provides a tool for testing how much of a cog's stack has been used. </p>
<dl class="section author"><dt>Author</dt><dd>Andy Lindsay</dd></dl>
<dl class="section version"><dt>Version</dt><dd>0.50</dd></dl>
<dl class="section copyright"><dt>Copyright</dt><dd>Copyright (C) Parallax, Inc. 2014. All Rights MIT Licensed. </dd></dl>
</div><h2>Function Documentation</h2>
<a class="anchor" id="aac4c00806d2d5639379e4c6a7a1d8d17"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int cog_endStackTest </td>
<td>(</td>
<td class="paramtype">int * </td>
<td class="paramname"><em>coginfo</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Ends function code running in another cog that was launched by cog_runStackTest and returns the number of int variables that were actually used in the stack. Provided the test code exercised ALL of the function's features in that other cog, you can reduce the stack space to some value slightly above the one cog_endStackTest reports. </p>
<p>This function uses the value returned by cog_runStackTest to stop a function running in another and capture and report the number of int variables that were actually used by the stack. It also frees free the stack space cog_runStackTest allocated with its stacksize parameter.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">*coginfo</td><td>the address returned by cog_runStackTest.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>stackUsed The minimum number of int variables that should be reserved with the cog_run function's stacksize parameter for the function that was run with cog_runStackTest. </dd></dl>
</div>
</div>
<a class="anchor" id="a4cb9ecdd69ae89091f2b62614a62fd97"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int* cog_runStackTest </td>
<td>(</td>
<td class="paramtype">void(*)(void *par) </td>
<td class="paramname"><em>function</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>stacksize</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Runs a function's code in the next available cog (processor) and tracks how much of the call stack the cog actually utilizes. After exercising the code running in another cog to its fullest extent with a liberal stack size, call cog_endStackTest to find out how much stack was actually used. Then reduce the stack accordingly to reduce the application's or library's overall memory footprint. </p>
<p>Propeller applications launch in cog 0, and that cog reads from and writes to unused Main RAM for call stack operations. These operations include setting aside memory for local variables, passing parameters, and function call/return addresses.</p>
<p>When the application launches another cog, that cog has to have some stack space set aside for those same operations to rule out possible memory contentions. It's crucial to always set aside enough stack space for functions running in another cog; otherwise, the cog might inadvertently overwrite other portions of the Main RAM that contain the program, global variables, or other critical components. Too much stack space is also problematic because it takes more memory than it needs to, which can prevent a library from being successfully incorporated into an application.</p>
<p>The best way to avoid using too much or too little stack is to test stack usage with an excessively large stack, and measure how much of it was actually used with test code that exercises all its features to be sure the cog has used as much stack space as it possibly can.</p>
<p>The cog_runStackTest function behaves almost identically to cog_run, but under the hood, it writes a series of pseudo-random values to the stack before starting the next available cog. After test code has exercised the code to its fullest extent, the cog_endStackTest function checks to find out how many memory elements were used by finding the address furthest from the stack base that does not match the sequence.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">*function</td><td>pointer to a function with no parameters or return value. Example, if your function is void myFunction(), then pass myFunction.</td></tr>
<tr><td class="paramname">stacksize</td><td>Number of extra int variables for local variable declarations and call/return stack. This also needs to cover any local variable declarations in functions that your function calls, including library functions. Be VERY liberal with extra stack space for this test to help ensure that some library isn't using a large buffer that you haven't accounted for. If your application has an extra 4 kB, consider using 1024 even for small and simple functions that run in other cogs.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>*coginfo Address of memory set aside for the cog. Make sure to save this value in a variable because it is a required parameter for cog_endStackTest to find out how much stack space was used. </dd></dl>
</div>
</div>
<a class="anchor" id="a55ac6c6c1308c59109c5df5a19a3d018"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int cogstart_stackTest </td>
<td>(</td>
<td class="paramtype">void(*)(void *) </td>
<td class="paramname"><em>func</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>par</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>stack</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>stacksize</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Starts a function's code in the next available cog (processor) and tracks how much of the call stack the cog actually utilizes. After exercising the code running in another cog to its fullest extent with a liberal stack size, call cogstop_stackTest to find out how much stack was actually used. Then reduce the stack accordingly to reduce the application's or library's overall memory footprint. </p>
<p>Propeller applications launch in cog 0, and that cog reads from and writes to unused Main RAM for call stack operations. These operations include setting aside memory for local variables, passing parameters, and function call/return addresses.</p>
<p>When the application launches another cog, that cog has to have some stack space set aside for those same operations to rule out possible memory contentions. It's crucial to always set aside enough stack space for functions running in another cog; otherwise, the cog might inadvertently overwrite other portions of the Main RAM that contain the program, global variables, or other critical components. Too much stack space is also problematic because it takes more memory than it needs to, which can prevent a library from being successfully incorporated into an application.</p>
<p>The best way to avoid using too much or too little stack is to test stack usage with an excessively large stack, and measure how much of it was actually used with test code that exercises all its features to be sure the cog has used as much stack space as it possibly can.</p>
<p>The cogstart_stackTest function behaves almost identically to cogstart, but under the hood, it writes a series of pseudo-random values to the stack before starting the next available cog. After test code has exercised the code to its fullest extent, the cogstop_stackTest function checks to find out how many memory elements were used by finding the address furthest from the stack base that does not match the sequence.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">*func</td><td>pointer to a function with void *parameter, and void return value. Example, if your function is void myFunction(void *par), then pass myFunction.</td></tr>
<tr><td class="paramname">*par</td><td>Optional parameter that points to a memory location with data to define the function's behavior. This data typically takes the form of a structure.</td></tr>
<tr><td class="paramname">*stack</td><td>The stack array to set aside for the function(s) executed by the other cog. The stack array has to take the form of int stack[46 + stackTestSize], where 46 is a base value required by the application, and stackTestSize is the number of int values that will be tested for stack usage. Be VERY liberal with the value of stackTestSize to help ensure that some library isn't using a large buffer that you haven't accounted for. If your application has an extra 4 kB, consider using 1024 even for small and simple functions that run in other cogs.</td></tr>
<tr><td class="paramname">stacksize</td><td>Total number of bytes in the stack array. Assuming the stack array was declared with int stack[46 + stackTestSize], use sizeof(stack).</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>cog The number of the cog the process was launched into, or -1 if no cogs were available. </dd></dl>
</div>
</div>
<a class="anchor" id="ab7c6af49e4f8a4563d278dd7c9e4f1bc"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int cogstop_stackTest </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>cog</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>stack</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Stops function code running in another cog that was launched by cogstart_stackTest and returns the number of int variables that were actually used in the stack. Provided enough stack space was set aside and the test code exercised ALL of the function's features in that other cog, you can reduce the stack space to some value slightly above the one cogstop_stackTest reports. </p>
<p>This function uses the address of the array passed to cogstop_stackTest along with the cog number it retuned to stop the function it started and capture and report the number of int variables that were actually used by the stack.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">cog</td><td>The cog number returned by cogstart_stackTest.</td></tr>
<tr><td class="paramname">*stack</td><td>Address of stack array passed to cogstart_stackTest.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>stackUsed The minimum number of int variables that should be declared in the array passed to cogstart. This value does not include the 44 elements that are required, so make sure to add 44 to the number of elements. Example: if cogstop_stackTest returns 64, the int stack array that gets passed to cogstart should be declared with at least 44 + 64 elements. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Aug 25 2014 16:14:38 for stacktest library by  <a href="html/http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.1.2
</small></address>
</body>
</html>