Here we describe the basic components of the current database tables. Note
that a number of columns in the tables are not currently used. They exist
for experimental purposes, and in some cases they exist as we anticipate
future needs. All the columns for each table are described in the model 
directory within the file __init__.py. 

Note that SQLAlchemy will automatically create these tables when runtest is
invoked if they do not already exist.

environment - this table is used to set up environment variables that may
              be needed by a tool. The important fields are:
              - envid: the primary key for this table
              - name: a tool name for which this environment applies. This
                field is a foreign key to the tools table
              - variable: the environment variable being referenced
              - value: the environment variable value to set
              - clear: if set, clear this environment variable before
                setting it to value
              - priority: not currently used

error_codes - used to define errors. The fields:
              - id: primary key
              - status_id: foreign key to the status table
              - error_desc: a pattern-matching value which further defines
                a matching entry in the status table with id status_id
              - merge type: not currently used
              - save_to_db: not currently used

flagdefs - list of flags as described in the flag_info file of the docs
           directory. The fields:
              - flagid: the flag name, such as C00, or D3H. primary key
              - flag1: what this flag translated into, if anything (may
                just be the base default value for a given flagtype)
              - flag2: not currently used, but may be useful for multi-
                pass compilation settings
              - type: one of the eight flag types, as described in flag_info
              - trackperf: not currently used

hosts - list of hosts. Mostly used for display purposes currently. In a 
        large, heterogeneous environment, many of the flags can be used to
        distinguish features possessed by a particular host, which may
        be needed for complex scheduling tasks. The only fields used
        currently:
               - name: host name, and the primary key
               - os: the OS name installed on this host
               - osname: a longer, more descriptive name, if needed

knownfailures - this table not currently used, but may be used to put 
        tests that are not to be run. The difference between tests in
        this table versus a test in the suitetests table with the enable
        field set to zero is that a test in the knownfailures table can
        be run by using the -force flag to the runtest command (although
        the result status cannot be saved to the database).

QA_data - the three QA_ tables are the heart of all saved test result
        information with the test harness database. QA_data has exactly
        one entry for every test run (which may be many tests for a
        particular runtest invocation). The logs of each test are stored
        within QA_logs, and there exists a 1-1 correspondece between these
        two table. Important fields:
                - id: primary key
                - index_id: foreign key to the QA_index table
                - hostname: the host on which the test was run. Foreign
                  key to the hosts table
                - date: date and time the test was run
                - runby: the user who ran the test. Foreign key to users
                - runid: this field is essentially the year and day of the 
                  year concatenated. Thus, 11138 is the 138th day of 2011,
                  which corresponds to May 18, 2011.
                - statusid: the status of the test result. Foreign key to
                  the status table
                - errorcodeid: the particular error code entry. Foreign key
                  to error_codes
                - runtime: execution time of the test
                - usertime: as reported from python time modules
                - systime: as reported from python time modules 
                - walltime: as reported from python time modules

QA_index - This table has one entry for each runtest invocation that is
           distinct from all other entries within QA_index. Thus there is
           a 1-to-many relationshia between QA_index and either QA_data or
           QA_logs. The table entries include id (primary key), userid,
           suitename, testname run, flags, compilerid, mode, version, 
           siliconid, osversion, and runid. There are a few other column 
           fields that are not currently used. This table is referenced to
           produce a web page for examining results. See the view table for
           more information.

QA_logs - This table holds the output from each test run. There is a 1-1
          correspondence between QA_logs and QA_data. The fields:
                 - id: the primary key
                 - data_id: foreign key to a QA_data entry
                 - log: a large text field that holds the output of 
                   each runtest test invocation

silicon - a table which can be used to further describe characteristics
          of a particular architecture. Currently the required column 
          silicon is set to "all" for the prepopulated database.

status - this table provides fields which are used to compare with each 
         line of output from a test to determine test outcomes. More details
         can be found in the <ROOT>/docs/test_info file.

suite - this table describes a suite of tests, such as the c_correct suite
        that can be found in the <ROOT>/tests directory. Many of the columns
        are not currently used. The important columns at this point are:
          - name: the suite name and primary key
          - displayname: the name used in the web views for the suite
          - suitetype: foreign key to a suitetype
          - the eight *flag fields. These are default values required for
            each suite. 
          - compilerid: a compilerid matching a compiler in the tools table
          - srcdir: provides the location of the suite when concatenated 
            to the homeqa variable

suitetests - this table contains all individual tests for a given suite. Each
             test usually needs at least the following column entries:
          - suitename: the name of the suite and also a primary key
          - testname: the name of the test and also a primary key
          - at least one of the four phase columns need to exist for proper
            operation of the makefiles within the suite source directory.
            Those phase columns are buildname, linkname, runname, and
            verifyname. See the test_info document for more information.
          - enable: set this column value to 1 so that the test is 
            considered "live" within the test suite
          - defaultstatus: this column can be filled in with an expected
            status. This column entry can be useful if an expected status
            may not be the usual result (such as a test which deliberately
            generates failures). See the test_info document for more
            information.

suitetype - this table describes the largest grouping of test suites within
            a suitetype. In our prepopulated database we have two suitetypes,
            correct and benchmark. There can be many suites of tests within
            each suitetype. Here is a description of the column fields:
          - name: the suitetype name, and primary key
          - description: currently just filled in for a user benefit
          - position: not currently used
          - displayname: the name used in a web view
          - baselineformula: not currently used

tools - this table has entries for all types of tools (compilers, linkers,
        assemblers, remote runner scripts, etc.) that may be referenced or
        needed by the processing of a runtest command. The important column
        entries include:
          - toolid: the tool id string, which is the primary key. It is
            referenced as a foreign key in many places.
          - os: a string which represents the os for which this tool applies
          - vendor: a place to record the vendor of the tool
          - version: a place to record the version of the tool
          - name: this is the name which corresponds to entries as a foreign
            key in the validFlagdefCompilers table. There may be different
            toolid values which have the same tool name
          - longname: a place to record a more detailed name of the tool
          - description: a place for a longer description of the tool
          - type: the tool type should match one of the entries within the
            <defaults><tools> section of the config.xml file (assembler,
            linker, compiler, simulator).
          - run: if the tool needs a more complicated command to actually
            invoke or execute the tool, this is the column to fill in
          - path: if a path needs to be provided for the tool, runtest will
            append this value to the PATH variable
          - mode: this field might be used to distinguish 32- vs. 64-bit
            processors, as an example

users - this table lists all the allowed users. The default user (qa in our
        prepopulated database) can be set in the config.xml file. The
        columns are:
          - id: a string for the user, which is the primary key
          - name: a larger field for a more descriptive name of the user
          - password: if desired, a password can be given and entered for
            each user

validFlagdefCompilers - this table matches up flags in the flagdefs table
        to compilers for which these flags are allowed from the tools table.
        There are only two columns:
          - flagid: a foreign key to the flagdefs flagid entry. Also a
            primary key
          - compiler: a foreign key to the tools name entry. Also a primary 
            key

views - this table defines a view for examining web pages that display the
        results of all runtest commands stored within the database. A view
        will display all database entries that match the corresponding columns 
        with values in the QA_index table. Thus, execpt for the first two
        column entries, these column fields are filters for what the web
        page will display. Columns that are empty for a particular view will
        match any of the respective columns within QA_index rows. 
        The columns are:
          - id: the view index id, and primary key
          - name: a name for the view that is displayed in the web page
          - siliconid: this can be all, as it is for the prepopulated
            database. But it can also be used to distinguish specific cores
            such as arm, a gpu, or specific x86 variants. 
          - osversion: This can be also be used to restrict entries for a
            particular view. An OS such as linux, android, or windows might
            be used here. 
          - version: the compiler version being used
          - compilerid: the compiler being used
          - userid: the user invoking runtest
