begriffs open source - cmsis-driver-validation/blob - docs/html/debugging.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   6 <title>Debugging</title>
   7 <title>CMSIS-Driver Validation: Debugging</title>
   8 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   9 <link href="drv.css" rel="stylesheet" type="text/css" />
  10 <script type="text/javascript" src="jquery.js"></script>
  11 <script type="text/javascript" src="dynsections.js"></script>
  12 <script type="text/javascript" src="printComponentTabs.js"></script>
  13 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="resize.js"></script>
  15 <script type="text/javascript" src="navtree.js"></script>
  16 <script type="text/javascript">
  17   $(document).ready(initResizable);
  18   $(window).load(resizeHeight);
  19 </script>
  20 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  21 <script type="text/javascript" src="search/search.js"></script>
  22 <script type="text/javascript">
  23   $(document).ready(function() { searchBox.OnSelectItem(0); });
  24 </script>
  25 <link href="stylsheetf" rel="stylesheet" type="text/css" />
  26 </head>
  27 <body>
  28 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  29 <div id="titlearea">
  30 <table cellspacing="0" cellpadding="0">
  31  <tbody>
  32  <tr style="height: 46px;">
  33   <td id="projectlogo"><img alt="Logo" src="keilarm.png"/></td>
  34   <td style="padding-left: 0.5em;">
  35    <div id="projectname">CMSIS-Driver Validation
  36    &#160;<span id="projectnumber">Version 2.0.0</span>
  37    </div>
  38    <div id="projectbrief">Driver Validation</div>
  39   </td>
  40  </tr>
  41  </tbody>
  42 </table>
  43 </div>
  44 <!-- end header part -->
  45 <div id="DRVnav" class="tabs1">
  46     <ul class="tablist">
  47       <script type="text/javascript">
  48                 <!--
  49                 writeComponentTabs.call(this);
  50                 //-->
  51       </script>
  52           </ul>
  53 </div>
  54 <!-- Generated by Doxygen 1.8.6 -->
  55 <script type="text/javascript">
  56 var searchBox = new SearchBox("searchBox", "search",false,'Search');
  57 </script>
  58   <div id="navrow1" class="tabs">
  59     <ul class="tablist">
  60       <li><a href="index.html"><span>Main&#160;Page</span></a></li>
  61       <li class="current"><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
  62       <li><a href="modules.html"><span>Reference</span></a></li>
  63       <li>
  64         <div id="MSearchBox" class="MSearchBoxInactive">
  65         <span class="left">
  66           <img id="MSearchSelect" src="search/mag_sel.png"
  67                onmouseover="return searchBox.OnSearchSelectShow()"
  68                onmouseout="return searchBox.OnSearchSelectHide()"
  69                alt=""/>
  70           <input type="text" id="MSearchField" value="Search" accesskey="S"
  71                onfocus="searchBox.OnSearchFieldFocus(true)"
  72                onblur="searchBox.OnSearchFieldFocus(false)"
  73                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  74           </span><span class="right">
  75             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
  76           </span>
  77         </div>
  78       </li>
  79     </ul>
  80   </div>
  81 </div><!-- top -->
  82 <div id="side-nav" class="ui-resizable side-nav-resizable">
  83   <div id="nav-tree">
  84     <div id="nav-tree-contents">
  85       <div id="nav-sync" class="sync"></div>
  86     </div>
  87   </div>
  88   <div id="splitbar" style="-moz-user-select:none;"
  89        class="ui-resizable-handle">
  90   </div>
  91 </div>
  92 <script type="text/javascript">
  93 $(document).ready(function(){initNavTree('debugging.html','');});
  94 </script>
  95 <div id="doc-content">
  96 <!-- window showing the filter options -->
  97 <div id="MSearchSelectWindow"
  98      onmouseover="return searchBox.OnSearchSelectShow()"
  99      onmouseout="return searchBox.OnSearchSelectHide()"
 100      onkeydown="return searchBox.OnSearchSelectKey(event)">
 101 <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>Files</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>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Pages</a></div>
 102
 103 <!-- iframe showing the search results (closed by default) -->
 104 <div id="MSearchResultsWindow">
 105 <iframe src="javascript:void(0)" frameborder="0"
 106         name="MSearchResults" id="MSearchResults">
 107 </iframe>
 108 </div>
 109
 110 <div class="header">
 111   <div class="headertitle">
 112 <div class="title">Debugging </div>  </div>
 113 </div><!--header-->
 114 <div class="contents">
 115 <div class="textblock"><p>After running the CMSIS-Driver Validation output report is used to see if the driver is compliant to the CMSIS-Driver specification.</p>
 116 <p>If the result of the driver testing under <code>Test Summary</code> contains any <code>Failed</code> tests then the driver needs to be corrected.</p>
 117 <p>Example of report in the Plain Text format of a non-compliant SPI driver: </p>
 118 <pre class="fragment">CMSIS-Driver SPI Test Report   May  6 2020   10:47:11
 119
 120 TEST 01: SPI_GetVersion
 121   DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
 122                                           PASSED
 123 TEST 02: SPI_GetCapabilities              PASSED
 124 TEST 03: SPI_Initialize_Uninitialize
 125   DV_SPI.c (1106): [FAILED]
 126   DV_SPI.c (1109): [FAILED]
 127   DV_SPI.c (1112): [FAILED]
 128                                           FAILED
 129 TEST 04: SPI_PowerControl
 130   DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
 131                                           PASSED
 132 ...
 133
 134 Test Summary: 56 Tests, 24 Passed, 1 Failed.
 135 Test Result: FAILED
 136 </pre><p>From previous report it is clear that one test function has failed.<br/>
 137  By Inspecting the details in previous report it is clear that <code>TEST 03: SPI_Initialize_Uninitialize</code> has failed on multiple assertions.<br/>
 138  Each failed assertion is recorded as a single line in the test report.<br/>
 139  The failed assert information in the output report contains additional information about the <b>source module</b> and <b>line</b> in that module where the assertion is located as well as any optional additional debugging info.</p>
 140 <p>The documentation can be consulted regarding the failed function, for example in previous case documentation on the <a class="el" href="group__spi__tests__drv__mgmt.html#ga1f84a363466cd780fcbc4cc0747cefec">SPI_Initialize_Uninitialize</a> can be consulted.</p>
 141 <p>Main way of fixing the driver consists of opening reported file mentioned as failed and inspecting the line in which failure was reported.</p>
 142 <p>In the previous report, opening <b><a class="el" href="_d_v___s_p_i_8c.html">DV_SPI.c</a></b> module (available in the project) and inspecting the <b>1106</b> line which states: </p>
 143 <pre class="fragment">  // Driver is uninitialized and peripheral is powered-off:
 144   // Call PowerControl(ARM_POWER_FULL) function and assert that it returned ARM_DRIVER_ERROR status
 145   TEST_ASSERT(drv-&gt;PowerControl (ARM_POWER_FULL) == ARM_DRIVER_ERROR);
 146 </pre><p>informs us that call to <code>PowerControl (ARM_POWER_FULL)</code>, when driver is not initialized, is expected to return <code>ARM_DRIVER_ERROR</code> status code but it has returned a different status code instead.</p>
 147 <p>We should put a breakpoint to this line and start the debug session.<br/>
 148  When the breakpoint is hit we can see that a call to <code>PowerControl (ARM_POWER_FULL)</code> has returned <code>ARM_DRIVER_OK</code> instead of expected <code>ARM_DRIVER_ERROR</code> status code.</p>
 149 <p>We can now go into source code of the driver and fix this.</p>
 150 <p>After we have fixed the driver, the report now looks like below:</p>
 151 <pre class="fragment">CMSIS-Driver SPI Test Report   May  6 2020   11:15:30
 152
 153 TEST 01: SPI_GetVersion
 154   DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
 155                                           PASSED
 156 TEST 02: SPI_GetCapabilities              PASSED
 157 TEST 03: SPI_Initialize_Uninitialize      PASSED
 158 TEST 04: SPI_PowerControl
 159   DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
 160                                           PASSED
 161 ...
 162
 163 Test Summary: 56 Tests, 25 Passed, 0 Failed.
 164 Test Result: PASSED
 165 </pre><p>The fix for the assertion failing in line 1106 has also fixed subsequent assertions in lines 1109 and 1112 thus the driver now reports no failed tests and reports that all of the 25 executed tests have passed.</p>
 166 <p>This report could be used as an insurance that the SPI Driver on this device is compliant to the CMSIS-Driver specification.</p>
 167 <p>The TestReport.xml report created instead of Plain Text opened in a Web browser looks like on the picture below:</p>
 168 <div class="image">
 169 <img src="xml_report.png" alt="xml_report.png"/>
 170 <div class="caption">
 171 XML test report</div></div>
 172 </div></div><!-- contents -->
 173 </div><!-- doc-content -->
 174 <!-- start footer part -->
 175 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 176   <ul>
 177     <li class="footer">Generated on Wed Jul 15 2020 10:47:10 for CMSIS-Driver Validation by ARM Ltd. All rights reserved.
 178         <!--
 179     <a href="http://www.doxygen.org/index.html">
 180     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
 181         -->
 182         </li>
 183   </ul>
 184 </div>
 185 </body>
 186 </html>