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 3.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>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><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 with additional debugging info if available.</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>If there are many failures, it is recommended to deselect all tests except first failing one so it is easier to focus on just that failure. Also, selecting only first failing test removes potential clutter from following failing tests that are all failing due to same cause.</p>
 143 <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>
 144 <pre class="fragment">  // Driver is uninitialized and peripheral is powered-off:
 145   // Call PowerControl(ARM_POWER_FULL) function and assert that it returned ARM_DRIVER_ERROR status
 146   TEST_ASSERT(drv-&gt;PowerControl (ARM_POWER_FULL) == ARM_DRIVER_ERROR);
 147 </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>
 148 <p>We should put a breakpoint to this line and start the debug session.<br/>
 149  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>
 150 <p>We can now go into source code of the driver and fix this.</p>
 151 <p>After we have fixed the driver, the report now looks like below:</p>
 152 <pre class="fragment">CMSIS-Driver SPI Test Report   May  6 2020   11:15:30
 153
 154 TEST 01: SPI_GetVersion
 155   DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
 156                                           PASSED
 157 TEST 02: SPI_GetCapabilities              PASSED
 158 TEST 03: SPI_Initialize_Uninitialize      PASSED
 159 TEST 04: SPI_PowerControl
 160   DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
 161                                           PASSED
 162 ...
 163
 164 Test Summary: 56 Tests, 25 Passed, 0 Failed.
 165 Test Result: PASSED
 166 </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>
 167 <p>This report could be used as an insurance that the SPI Driver on this device is compliant to the CMSIS-Driver specification.</p>
 168 <p>The TestReport.xml report created instead of Plain Text opened in a Web browser looks similar to the the picture below:</p>
 169 <div class="image">
 170 <img src="xml_report.png" alt="xml_report.png"/>
 171 <div class="caption">
 172 XML test report</div></div>
 173 </div></div><!-- contents -->
 174 </div><!-- doc-content -->
 175 <!-- start footer part -->
 176 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 177   <ul>
 178     <li class="footer">Generated on Fri Jul 15 2022 08:42:08 for CMSIS-Driver Validation by ARM Ltd. All rights reserved.
 179         <!--
 180     <a href="http://www.doxygen.org/index.html">
 181     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
 182         -->
 183         </li>
 184   </ul>
 185 </div>
 186 </body>
 187 </html>