QualiTI
=======

This page describes how to run QualiTI on the included sample algorithms,
and then on any algorithm.


What's in the QualiTI package
-----------------------------
Under the top directory is the following:

    - packages/ti/xdais/qualiti   -- this dir contains the QualiTI application
    - ti.xdais.qualiti.bat        -- batch file that runs the app (Windows)
    - ti.xdais.qualiti.sh         -- shell script that runs the app (Linux)


Requirements
------------
QualiTI runs on Windows and Linux. On either OS you need:

1. XDC tools 3.00.05 or higher (some older versions will work as well, but
have not been validated)

2. "cg_xml" tools 2.12 or later.

   cg_xml is a collection of utility scripts / executables which
   parse XML files generated by TI Codegen Tools to get information such as
   footprint and stack size from the object files. QualiTI uses several of these
   executables. Note that you do NOT need to download / install Perl, since the
   cg_xml perl scripts have already been converted to executables.

   Download the latest cg_xml release from: -
   https://www-a.ti.com/downloads/sds_support/applications_packages/cg_xml/index.htm

Note:
   A subset of the required TI codegen tools are currently bundled with QualiTI
   in the <QualiTI Dir>/cgtools.  As a result, the dependency on a TI codegen
   release has been [temporarily] removed.  At some time in the future, QualiTI
   will likely reintroduce this dependency.


Preparation (Windows)
---------------------
Edit file ti.xdais.qualiti.bat and modify the path to match your XDC installation dir.


Running QualiTI in graphical mode
----------------------------------

- Open a DOS shell, cd to where ti.xdais.qualiti.bat file is, and run this file.
  Alternatively, double-click on ti.xdais.qualiti.bat from the File Explorer.

- You will see that the settings from the last session are remembered (they
  are stored under the user's home directory). If this
  is the first time you are running QualiTI, examine the Settings section and
  specify the right values for your installation for a sample algorithm:

  - Under "Algorithm":
    - Load an existing .qti config file.  Each XDAIS example includes one or
      more of these .qti config files
      E.g. <XDAIS_INSTALL_DIR>\examples\ti\xdais\dm\examples\auddec1_copy\auddec1copy.qti

      The "Base Dir" is loosely the top directory underneath which the library
      directory and the headers directory is -- it's a common parent for
      library and headers.  It can also be the package base directory, if the
      algorithm is in a RTSC package.

  - Under Tools:
    - specify your cg_xml tools directory, e.g.
      C:\myInstallations\cg_xml

- Click the "Run" button to run all the tests.

- Examine different windows.

- Click on the "Status [...]" column header to cycle through failures.

- Go to Settings->Reports tab to view generated HTML reports. By default, the
  two reports will be generated in the base directory.


Running QualiTI in command mode
--------------------------------

To run the auddec1copy.qti project from the command line, type (from a DOS shell)

> startqti <path to example>/auddec1copy.qti

The script will run the tests and generate HTML report, presenting a brief
summary on standard output.

You can control how quiet or verbose the script is, and also control HTML
reports by using options you can learn about from invoking "startqti -h".

Note that the tools paths are read from a file Tools.ini located in the
user's home directory.  This file is created when the application
exits in GUI mode, and it stores Settings->Tools in there.  If you want to
use a different Tools.ini file, you can specify one with the -t option.


Changing QualiTI rule settings
-------------------------------

Some rules in the suite define some of their parameters as configurable
options.  You can redefine these parameters by writing a user script that
changes them and which runs prior to other QualiTI scripts.  To specify
such a script, use the -u <filename> command line options.

For example, Rule13 defines the list of standard sections as
    config string standardSections[] = [ ".cinit", ".text", etc. ... ];

If you want to redefine this list (bad idea!) create script, say,
c:\myscripts\user.ini with the following contents:
    var Rule13 = xdc.module( "ti.sdo.qualiti6.Rule13" );
    Rule13.standardSections = [ ".foo", ".bar" ];
and run QualiTI by passing -u c:\myscripts\user.ini from the command line.

This option works in either mode (graphical or command).


Running QualiTI on Linux
-------------------------

Make sure you have the "xdc" command in your path. Run <XDAIS_INSTALL_DIR>/
ti.xdais.qualiti.sh shell script. Everything else should be the same.
