This directory tests the x86-64 instruction decoder and instruction
validator.  It does so using (human readable) text files.

For a test FOO, the following files are defined:

FOO.hex

   Textual file defining the sequence of hexidecimal bytes in the code
   segment for testing. Comments on what the code segment is intended
   to test are at the top of the file, and begin with a pound (#)
   symbol.

   By default, the starting program counter is at 0. If you want it at
   a different place, make the first non-comment line of the form '@XXX'
   where XXX should be used as the starting program counter.

FOO.dis

   Output generated by the full instruction decoder for the
   corresponding FOO.hex file.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --full_decoder --hex_text=- < FOO.hex

FOO.vdis

   Output generated by corresponding (x86-64) validator instruction
   decoder for the corresponding FOO.hex file.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --validator_decoder --hex_text=- < FOO.hex

FOO.val

   Output generated by the x86-64 write sandboxing, register based SFI
   validator for the corresponding FOO.hex file.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncval \
          --write_sfi --hex_text=- --max_errors=-1 \
          --annotate=false --cpuid-all < FOO.hex

FOO.rval

   Output generated by the x86-64 read/write sandboxing, register based SFI
   validator for the corresponding FOO.hex file.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncval \
          --readwrite_sfi -hex_text=- --max_errors=-1 \
          --annotate=false --cpuid-all --detailed=false < FOO.hex

FOO.rvala

   Output generated by the x86-64 read/write sandboxing, register
   based SFI validator for the corresponding FOO.hex file. Generates
   annotator messages in the form expected by ncval_annotate.py.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncval
          --readwrite_sfi -hex_text=- --max_errors=-1 \
          --annotate --cpuid-all < FOO.hex

FOO.nexe

   Run the installed instruction decoder and validator on the predefined
   compiled NACL executable FOO.nexe.

In addition, the following non-unit tests are run:

ncdis_FOO.input

   Self documenting file for the instruction decoder, assuming ncdis
   was run on each instruction specified in the input file. It is
   based on using the full decoder.

   Note: This input matches the generated output (i.e. self
   documenting) by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --self_document --full_decoder --commands=- \
          < ncdis_test.input

ncdis_FOO.input

   Self documenting file for the instruction decoder, assuming ncdis
   was run on each insruction specified in the input file. It is based
   on the validator decoder.

   Note: This input matches the generated output (i.e. self
   documenting) by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --self_document --validator_decoder --commands=-
	  < ncdis_FOO.vinput

ncdis_FOO.internal

   Output generated by the instruction decoder, generated from the
   input file ncdis_FOO.input. After each printed instruction, the
   internal form of the matched instruction, and the corresponding
   expression tree is also printed.

   Uses the full decoder of ncdis to decode the instruction.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --internal --full_decoder --commands=- \
          < ncdis_iter_test.input

ncdis_FOO.vinternal

   Output generated by the instruction decoder, generated from the
   input file ncdis_FOO.input. After each printed instruction, the
   internal form of the matched instruction, and the corresponding
   expression tree is also printed.

   Uses the validator decoder of ncdis to decode the instruction.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdis \
          --internal --validator_decoder --commands=- \
          < ncdis_FOO.input

modeled_insts.txt

   Automatically generated text describing the instruction set that
   the full decoder understands.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdecode_tablegen \
          -m64 -documentation

ncval_reg_sfi_modeled_insts.txt

   Automatically generated text describing the instruction set that
   the x86-64 validator decoder understands.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncdecode_tablegen \
          -m64 -documentation -validator_decoder

------------------------------------------------------------------

Note: Files with a cval extension are experimental, and are gold files
for pre/post conditions of individual instruction. Currently, these
files are under construction and are incomplete with respect to all
pre/post conditions.

Known issues with cval files are:

(1) Pre/Post conditions for jumps not (necessarily) being generated
yet.

(2) Printing Pre/Post conditions for instructions that are illegal.
For testing purposes, only want if instruction is legal if
preconditions are met.

(3) Code doesn't handle notion of multiple Pre/Post condition rules
for an instruction.

(4) Sometimes the same Pre/Post condition is repeated.


