<chapter id="chapter.gui.line">
  <title>Navigating the Line Coverage Window</title>
  <para>
    Line coverage is the quickest way to determine what logic in your design is being exercised and which logic has not
    be exercised during simulation.  If a line was found to not be simulated, this is an indication that there was some
    event that did not occur or did not occur at the proper time to cause a previous conditional expression to be
    evaluated to true or false.  For example, if a block of code looked something like:
  </para>
  <para>
    <example xml:id="example.gui.line">
      <title>Line Coverage Example</title>
      <programlisting><![CDATA[
  always @(posedge clock)  // Line 1
    if( a )                // Line 2
      b <= 1'b0;           // Line 3
    else                   // Line 4
      b <= 1'b1;           // Line 5
      ]]></programlisting>
    </example>
  </para>
  <para>
    If line 3 was shown to be not covered, this would indicate that at the positive edge of the term "clock", the value
    of "a" never evaluated to a value of 1 (true).  To make line 3 become covered, we would need to setup a situation in
    the diagnostic that caused "a" to become true at the positive edge of the term "clock".
  </para>
  <para>
    On the other hand, if all lines 2 - 5 were found to be uncovered, this would indicate the the term "clock" never made
    a transition from some value to a 1 (true) value during simulation.
  </para>

  <sect1 id="section.gui.line.uncov">
    <title>Viewing Uncovered Lines</title>
    <para>
      To view line coverage for all uncovered lines for a specific module/instance, do the following:
    </para>
    <para>
      <orderedlist>
        <listitem>
          <para>
            Make sure that the <emphasis role="bold">Show Uncovered</emphasis> menu item in the
            <link linkend="section.gui.main.reportmenu">report menu</link> is selected.
          </para>
        </listitem>
        <listitem>
          <para>
            Select the line coverage metric in the <link linkend="section.gui.main.covbar">coverage bar</link> by left-clicking
            on selection button to the left of "Line".
          </para>
        </listitem>
        <listitem>
          <para>
            Select one of the modules/instances that is highlighted in the uncovered color scheme (to change this color
            scheme, see <xref linkend="chapter.gui.preferences"/>) in the <link linkend="section.gui.main.listbox">listbox</link>.
            This will cause the selected module/instance source code to be displayed in the
            <link linkend="section.gui.main.viewer">file viewer</link>.
          </para>
        </listitem>
      </orderedlist>
    </para>
    <para>
      Once the selected module/instance has been displayed, scroll down in the Coverage File Viewer window (using the
      scroll bars to the right and below the Coverage File Viewer window) until you have reached a line that is
      highlighted in the uncovered color scheme. The line number of the highlighted line will be printed to the left of
      the source code line.  This line represents a line that was found to not be hit during the simulation of this
      module/instance.
    </para>
  </sect1>

  <sect1 id="section.gui.line.excl">
    <title>Excluding/Included Uncovered Lines from Line Coverage</title>
    <para>
      Any uncovered line in the design may be included/excluded from coverage consideration.  To the left of each
      uncovered line is an underlined "I" (line is currently included in coverage) or "E" (line is currently excluded
      in coverage).  Clicking on an "I" will cause a <link linkend="chapter.gui.exclude">exclusion reason popup
      window</link> to be displayed, allowing you to specify a reason for excluding this line.  Once a reason has been
      entered, the coverage exclusion property of the line will change to an "E" and be highlighted in the "covered"
      color scheme and the summary line coverage information will be recalculated and redisplayed in the
      <link linkend="section.gui.main.listbox">listbox</link> to reflect the current status of line coverage for the
      current module/instance.  Clicking on an "E" will cause the current line to be displayed in the "uncovered"
      color scheme, the "E" will change to an "I", and the summary line coverage will be recalculated and redisplayed
      in the summary listbox.  <xref linkend="figure.gui.line.include"/> shows an uncovered line that is included for
      coverage consideration.  <xref linkend="figure.gui.line.exclude"/> shows the same line which is now excluded
      from coverage consideration.
    </para>
    <para>
      <figure id="figure.gui.line.include">
        <title>Example of uncovered line included for line coverage consideration</title>
        <mediaobject><imageobject><imagedata fileref="img/line_incl.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    <para>
      <figure id="figure.gui.line.exclude">
        <title>Example of uncovered line excluded for line coverage consideration</title>
        <mediaobject><imageobject><imagedata fileref="img/line_excl.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    <para>
      In addition to changing the line coverage information, the combinational logic coverage information for an
      uncovered statement on that line will also be implicitly excluded from coverage (though the exclude properties for
      each subexpression of the statement will not change).
    </para>
    <para>
      If the user excludes any line in the design, the <emphasis role="bold">Save CDD...</emphasis> option in the
      <link linkend="section.gui.main.filemenu">file</link> menu will be enabled.  This allows the user to save the excluded property
      either back to the CDD file (or to a newly named CDD file). Doing so will allow the user to load the CDD file at a
      different time and retain the knowledge of which lines have been excluded/included for coverage.  Additionally, if
      a saved CDD file with coverage exclusion is merged with another CDD file, the excluded line information is
      preserved for the resulting merged CDD file.
    </para>
    <para>
      If a line has been excluded from coverage and an exclusion reason was specified, you can view the reason for exclusion
      by right-click-and-hold on the "E" on the desired line.  This will cause a tooltip-style window to be displayed specifying
      the reason for exclusion.  The background color of the tooltip will be the same color as the "covered" background color
      to help distinguish it from a normal tooltip.  To cause the exclusion reason tooltip to disappear, simply release the
      button.
    </para>
  </sect1>

  <sect1 id="section.gui.line.cov">
    <title>Viewing Covered Lines</title>
    <para>
      To view line coverage for all covered lines for a specific module/instance, do the following:
    </para>
    <para>
      <orderedlist>
        <listitem>
          <para>
            Make sure that the <emphasis role="bold">Show Covered</emphasis> menu item in the
            <link linkend="section.gui.main.reportmenu">report</link> menu is selected.
          </para>
        </listitem>
        <listitem>
          <para>
            Select the line coverage metric in the <link linkend="section.gui.main.covbar">coverage bar</link> by left-clicking on the
            selection button to the left of "Line".
          </para>
        </listitem>
        <listitem>
          <para>
            Select one of the modules/instances in the <link linkend="section.gui.main.listbox">listbox</link> that shows that at least
            one line was considered coverable by Covered.
          </para>
        </listitem>
      </orderedlist>
    </para>
    <para>
      Once the selected module/instance has been displayed, scroll down in the Coverage File Viewer window (using the
      scroll bars to the right and below the Coverage File Viewer window) until you have reached a line that is
      highlighted in the covered color scheme. The line number of the highlighted line will be printed to the left of the
      source code line.  This line represents a line that was found to be hit during the simulation of this
      module/instance.
    </para>
  </sect1>

  <note>
    <para>
      You may see both the covered and uncovered line coverage simultaneously by selecting both the
      <emphasis role="bold">Show Uncovered</emphasis> and <emphasis role="bold">Show Covered</emphasis> items in the
      <emphasis role="bold">Report</emphasis> menu.  This is sometimes useful to see what logic Covered was not able to
      provide coverage support for (all lines which contain code that are not highlighted in either the uncovered or
      covered color schemes).
    </para>
  </note>

</chapter>
