Files
KSDK_2.0_MKL03Z8xxx4/docs/Kinetis SDK API Reference Manual MKL03Z4_v2.0.0/group__debugconsole.html
2016-08-09 18:02:18 +02:00

329 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Kinetis SDK v.2.0 API Reference Manual: Debug Console</title>
<link href="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="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>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="customdoxygen.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 id="projectlogo"><img alt="Logo" src="fs_logo.gif"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">Kinetis SDK v.2.0 API Reference Manual
&#160;<span id="projectnumber">Rev. 0</span>
</div>
<div id="projectbrief">NXP Semiconductors</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<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><a href="pages.html"><span>Related&#160;Pages</span></a></li>
<li><a href="modules.html"><span>API&#160;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__debugconsole.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>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><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="summary">
<a href="#groups">Modules</a> </div>
<div class="headertitle">
<div class="title">Debug Console</div> </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Overview</h2>
<p>This section describes the programming interface of the debug console driver.</p>
<p>The debug console enables debug log messages to be output via the specified peripheral with frequency of the peripheral source clock and base address at the specified baud rate. Additionally, it provides input and output functions to scan and print formatted data.</p>
<h1><a class="anchor" id="DbgConsoleFunGrps"></a>
Function groups</h1>
<h2><a class="anchor" id="DbgConsoleInit"></a>
Initialization</h2>
<p>To initialize the debug console, call the <span style="color:red">DbgConsole_Init()</span> function with these parameters. This function automatically enables the module and the clock.</p>
<div class="fragment"><div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> * @brief Initializes the the peripheral used to debug messages.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * @param baseAddr Indicates which address of the peripheral is used to send debug messages.</span></div>
<div class="line"><span class="comment"> * @param baudRate The desired baud rate in bits per second.</span></div>
<div class="line"><span class="comment"> * @param device Low level device type for the debug console, can be one of:</span></div>
<div class="line"><span class="comment"> * @arg DEBUG_CONSOLE_DEVICE_TYPE_UART,</span></div>
<div class="line"><span class="comment"> * @arg DEBUG_CONSOLE_DEVICE_TYPE_LPUART,</span></div>
<div class="line"><span class="comment"> * @arg DEBUG_CONSOLE_DEVICE_TYPE_LPSCI,</span></div>
<div class="line"><span class="comment"> * @arg DEBUG_CONSOLE_DEVICE_TYPE_USBCDC.</span></div>
<div class="line"><span class="comment"> * @param clkSrcFreq Frequency of peripheral source clock.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * @return Whether initialization was successful or not.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line">status_t DbgConsole_Init(uint32_t baseAddr, uint32_t baudRate, uint8_t device, uint32_t clkSrcFreq)</div>
</div><!-- fragment --><p>Selects the supported debug console hardware device type, such as</p>
<div class="fragment"><div class="line">DEBUG_CONSOLE_DEVICE_TYPE_NONE </div>
<div class="line">DEBUG_CONSOLE_DEVICE_TYPE_LPSCI </div>
<div class="line">DEBUG_CONSOLE_DEVICE_TYPE_UART </div>
<div class="line">DEBUG_CONSOLE_DEVICE_TYPE_LPUART </div>
<div class="line">DEBUG_CONSOLE_DEVICE_TYPE_USBCDC </div>
</div><!-- fragment --><p>After the initialization is successful, stdout and stdin are connected to the selected peripheral. The debug console state is stored in the debug_console_state_t structure, such as shown here:</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>DebugConsoleState</div>
<div class="line">{</div>
<div class="line"> uint8_t type; </div>
<div class="line"> <span class="keywordtype">void</span>* base; </div>
<div class="line"> debug_console_ops_t ops; </div>
<div class="line">} debug_console_state_t;</div>
</div><!-- fragment --><p>This example shows how to call the DbgConsole_Init() given the user configuration structure:</p>
<div class="fragment"><div class="line">uint32_t uartClkSrcFreq = <a class="code" href="group__clock.html#ga53acae220d651789bb505c53c73ecf2b">CLOCK_GetFreq</a>(BOARD_DEBUG_UART_CLKSRC);</div>
<div class="line"></div>
<div class="line">DbgConsole_Init(BOARD_DEBUG_UART_BASEADDR, BOARD_DEBUG_UART_BAUDRATE, DEBUG_CONSOLE_DEVICE_TYPE_UART, uartClkSrcFreq);</div>
</div><!-- fragment --><h2><a class="anchor" id="DbgConsoleAdvFeature"></a>
Advanced Feature</h2>
<p>The debug console provides input and output functions to scan and print formatted data.</p>
<ul>
<li>Support a format specifier for PRINTF following this prototype " %[flags][width][.precision][length]specifier", which is explained below</li>
</ul>
<div style="width:800px;"> <table class="doxtable">
<tr>
<th>flags </th><th>Description </th></tr>
<tr>
<td>- </td><td>Left-justified within the given field width. Right-justified is the default. </td></tr>
<tr>
<td>+ </td><td>Forces to precede the result with a plus or minus sign (+ or -) even for positive numbers. By default, only negative numbers are preceded with a - sign. </td></tr>
<tr>
<td>(space) </td><td>If no sign is going to be written, a blank space is inserted before the value. </td></tr>
<tr>
<td># </td><td>Used with o, x, or X specifiers the value is preceded with 0, 0x, or 0X respectively for values other than zero. Used with e, E and f, it forces the written output to contain a decimal point even if no digits would follow. By default, if no digits follow, no decimal point is written. Used with g or G the result is the same as with e or E but trailing zeros are not removed. </td></tr>
<tr>
<td>0 </td><td>Left-pads the number with zeroes (0) instead of spaces, where padding is specified (see width sub-specifier). </td></tr>
</table>
</div><div style="width:800px;"> <table class="doxtable">
<tr>
<th>Width </th><th>Description </th></tr>
<tr>
<td>(number) </td><td>A minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger. </td></tr>
<tr>
<td>* </td><td>The width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. </td></tr>
</table>
</div><div style="width:800px;"> <table class="doxtable">
<tr>
<th>.precision </th><th>Description </th></tr>
<tr>
<td>.number </td><td>For integer specifiers (d, i, o, u, x, X) precision specifies the minimum number of digits to be written. If the value to be written is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is written for the value 0. For e, E, and f specifiers this is the number of digits to be printed after the decimal point. For g and G specifiers This is the maximum number of significant digits to be printed. For s this is the maximum number of characters to be printed. By default, all characters are printed until the ending null character is encountered. For c type it has no effect. When no precision is specified, the default is 1. If the period is specified without an explicit value for precision, 0 is assumed. </td></tr>
<tr>
<td>.* </td><td>The precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. </td></tr>
</table>
</div><table class="doxtable">
<tr>
<th>length </th><th>Description </th></tr>
<tr>
<td colspan="2">Do not support </td></tr>
</table>
<table class="doxtable">
<tr>
<th>specifier </th><th>Description </th></tr>
<tr>
<td>d or i </td><td>Signed decimal integer </td></tr>
<tr>
<td>f </td><td>Decimal floating point </td></tr>
<tr>
<td>F </td><td>Decimal floating point capital letters </td></tr>
<tr>
<td>x </td><td>Unsigned hexadecimal integer </td></tr>
<tr>
<td>X </td><td>Unsigned hexadecimal integer capital letters </td></tr>
<tr>
<td>o </td><td>Signed octal </td></tr>
<tr>
<td>b </td><td>Binary value </td></tr>
<tr>
<td>p </td><td>Pointer address </td></tr>
<tr>
<td>u </td><td>Unsigned decimal integer </td></tr>
<tr>
<td>c </td><td>Character </td></tr>
<tr>
<td>s </td><td>String of characters </td></tr>
<tr>
<td>n </td><td>Nothing printed </td></tr>
</table>
<ul>
<li>Support a format specifier for SCANF following this prototype <span style="color:red">" %[*][width][length]specifier"</span>, which is explained below</li>
</ul>
<div style="width:800px;"> <table class="doxtable">
<tr>
<th>* </th><th>Description </th></tr>
<tr>
<td colspan="2">An optional starting asterisk indicates that the data is to be read from the stream but ignored, i.e., it is not stored in the corresponding argument. </td></tr>
</table>
</div><div style="width:800px;"> <table class="doxtable">
<tr>
<th>width </th><th>Description </th></tr>
<tr>
<td colspan="2">This specifies the maximum number of characters to be read in the current reading operation. </td></tr>
</table>
</div><div style="width:800px;"> <table class="doxtable">
<tr>
<th>length </th><th>Description </th></tr>
<tr>
<td>hh </td><td>The argument is interpreted as a signed character or unsigned character (only applies to integer specifiers: i, d, o, u, x, and X). </td></tr>
<tr>
<td>h </td><td>The argument is interpreted as a short integer or unsigned short integer (only applies to integer specifiers: i, d, o, u, x, and X). </td></tr>
<tr>
<td>l </td><td>The argument is interpreted as a long integer or unsigned long integer for integer specifiers (i, d, o, u, x, and X), and as a wide character or wide character string for specifiers c and s. </td></tr>
<tr>
<td>ll </td><td>The argument is interpreted as a long long integer or unsigned long long integer for integer specifiers (i, d, o, u, x, and X), and as a wide character or wide character string for specifiers c and s. </td></tr>
<tr>
<td>L </td><td>The argument is interpreted as a long double (only applies to floating point specifiers: e, E, f, g, and G). </td></tr>
<tr>
<td>j or z or t </td><td>Not supported </td></tr>
</table>
</div><div style="width:800px;"> <table class="doxtable">
<tr>
<th>specifier </th><th>Qualifying Input </th><th>Type of argument </th></tr>
<tr>
<td>c </td><td>Single character: Reads the next character. If a width different from 1 is specified, the function reads width characters and stores them in the successive locations of the array passed as argument. No null character is appended at the end. </td><td>char * </td></tr>
<tr>
<td>i </td><td>Integer: : Number optionally preceded with a + or - sign </td><td>int * </td></tr>
<tr>
<td>d </td><td>Decimal integer: Number optionally preceded with a + or - sign </td><td>int * </td></tr>
<tr>
<td>a, A, e, E, f, F, g, G </td><td>Floating point: Decimal number containing a decimal point, optionally preceded by a + or - sign and optionally followed by the e or E character and a decimal number. Two examples of valid entries are -732.103 and 7.12e4 </td><td>float * </td></tr>
<tr>
<td>o </td><td>Octal Integer: </td><td>int * </td></tr>
<tr>
<td>s </td><td>String of characters. This reads subsequent characters until a white space is found (white space characters are considered to be blank, newline, and tab). </td><td>char * </td></tr>
<tr>
<td>u </td><td>Unsigned decimal integer. </td><td>unsigned int * </td></tr>
</table>
</div><p>The debug console has its own printf/scanf/putchar/getchar functions which are defined in the header file:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> DbgConsole_Printf(<span class="keyword">const</span> <span class="keywordtype">char</span> *fmt_s, ...); </div>
<div class="line"><span class="keywordtype">int</span> DbgConsole_Putchar(<span class="keywordtype">int</span> ch); </div>
<div class="line"><span class="keywordtype">int</span> DbgConsole_Scanf(<span class="keyword">const</span> <span class="keywordtype">char</span> *fmt_ptr, ...); </div>
<div class="line"><span class="keywordtype">int</span> DbgConsole_Getchar(<span class="keywordtype">void</span>); </div>
</div><!-- fragment --><p>This utility supports selecting toolchain's printf/scanf or the KSDK printf/scanf:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#if SDK_DEBUGCONSOLE </span><span class="comment">/* Select printf, scanf, putchar, getchar of SDK version. */</span><span class="preprocessor"></span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define PRINTF DbgConsole_Printf</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define SCANF DbgConsole_Scanf</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define PUTCHAR DbgConsole_Putchar</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define GETCHAR DbgConsole_Getchar</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#else </span><span class="comment">/* Select printf, scanf, putchar, getchar of toolchain. */</span><span class="preprocessor"></span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define PRINTF printf</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define SCANF scanf</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define PUTCHAR putchar</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define GETCHAR getchar</span></div>
<div class="line"><span class="preprocessor">#endif </span><span class="comment">/* SDK_DEBUGCONSOLE */</span><span class="preprocessor"></span></div>
</div><!-- fragment --><h1><a class="anchor" id="DbgConsoleTpyUC"></a>
Typical use case</h1>
<h2>Some examples use the PUTCHAR &amp; GETCHAR function</h2>
<div class="fragment"><div class="line">ch = GETCHAR();</div>
<div class="line">PUTCHAR(ch);</div>
</div><!-- fragment --><h2>Some examples use the PRINTF function</h2>
<p>Statement prints the string format.</p>
<div class="fragment"><div class="line">PRINTF(<span class="stringliteral">&quot;%s %s\r\n&quot;</span>, <span class="stringliteral">&quot;Hello&quot;</span>, <span class="stringliteral">&quot;world!&quot;</span>);</div>
</div><!-- fragment --><p>Statement prints the hexadecimal format/</p>
<div class="fragment"><div class="line">PRINTF(<span class="stringliteral">&quot;0x%02X hexadecimal number equivalents 255&quot;</span>, 255);</div>
</div><!-- fragment --><p>Statement prints the decimal floating point and unsigned decimal.</p>
<div class="fragment"><div class="line">PRINTF(<span class="stringliteral">&quot;Execution timer: %s\n\rTime: %u ticks %2.5f milliseconds\n\rDONE\n\r&quot;</span>, <span class="stringliteral">&quot;1 day&quot;</span>, 86400, 86.4);</div>
</div><!-- fragment --><h2>Some examples use the SCANF function</h2>
<div class="fragment"><div class="line">PRINTF(<span class="stringliteral">&quot;Enter a decimal number: &quot;</span>);</div>
<div class="line">SCANF(<span class="stringliteral">&quot;%d&quot;</span>, &amp;i);</div>
<div class="line">PRINTF(<span class="stringliteral">&quot;\r\nYou have entered %d.\r\n&quot;</span>, i, i);</div>
<div class="line">PRINTF(<span class="stringliteral">&quot;Enter a hexadecimal number: &quot;</span>);</div>
<div class="line">SCANF(<span class="stringliteral">&quot;%x&quot;</span>, &amp;i);</div>
<div class="line">PRINTF(<span class="stringliteral">&quot;\r\nYou have entered 0x%X (%d).\r\n&quot;</span>, i, i);</div>
</div><!-- fragment --><h2>Print out failure messages using KSDK __assert_func:</h2>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> __assert_func(<span class="keyword">const</span> <span class="keywordtype">char</span> *file, <span class="keywordtype">int</span> line, <span class="keyword">const</span> <span class="keywordtype">char</span> *func, <span class="keyword">const</span> <span class="keywordtype">char</span> *failedExpr)</div>
<div class="line">{</div>
<div class="line"> PRINTF(<span class="stringliteral">&quot;ASSERT ERROR \&quot; %s \&quot;: file \&quot;%s\&quot; Line \&quot;%d\&quot; function name \&quot;%s\&quot; \n&quot;</span>, failedExpr, file , line, func);</div>
<div class="line"> <span class="keywordflow">for</span> (;;)</div>
<div class="line"> {}</div>
<div class="line">}</div>
</div><!-- fragment --> <h2>Note:</h2>
<p>If you want to use 'printf' and 'scanf' for GNUC Base, you should add file <b>'fsl_sbrk.c'</b> in path: <b>..\{package}\devices\{subset}\utilities\fsl_sbrk.c </b> to your project.</p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
Modules</h2></td></tr>
<tr class="memitem:group__Semihosting"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__Semihosting.html">Semihosting</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.5-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul class="foot">
<li class="footer">&copy; 2016 Freescale Semiconductor, Inc. All rights reserved.
</li>
</ul>
</div>
</body>
</html>