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

Note: The .dis files correspond to using the (new) 32-bit full
decoder. By looking at the corresponding outputs, it is clear that the
full decoder needs work. See
http://code.google.com/p/nativeclient/issues/detail?id=2171 for
corresponding issue that has already been filed.

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 the corresponding (x86-32) 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.nval

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Jump errors are summarized as in
   sel_ldr.

   Note: This file is generated by running:

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

FOO.nval16

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Assumes that the block size is 16 bytes
   instead of 32. Jump errors are summarized as in sel_ldr.

   Note: This file is generated by running:

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

FOO.nvals

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Adds summary information.  Jump errors
   are summarized as in sel_ldr.

   Note: This file is generated by running:

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

FOO.nvals16

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Adds summary information, as well as
   assume that the block size is 16 bytes instead of 32.  Jump errors
   are summarized as in sel_ldr.

   Note: This file is generated by running:

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

FOO.nvald

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Jump errors are detailed, describing
   each (individual) jump instruction that violates the jump criteria
   of native client.

   Note: This file is generated by running:

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

FOO.nvald16

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Assumes that the block size is 16 bytes
   instead of 32. Jump errors are detailed, describing each
   (individual) jump instruction that violates the jump criteria of
   native client.

   Note: This file is generated by running:

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

FOO.nvals

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Adds summary information.  Jump errors
   are detailed.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncval \
          --hex_text=- --max_errors=-1 --stats --alignment=32 \
          --detailed --cpuid--all < FOO.hex

FOO.nvals16

   Output generated by the x86-32 (segment based) validator for the
   corresponding FOO.hex file. Adds summary information, as well as
   assume that the block size is 16 bytes instead of 32.  Jump errors
   are detailed, describing each (individual) jump instruction that
   violates the jump criteria of native client.

   Note: This file is generated by running:

     > scons-out/.../obj/src/trusted/validator_x86/ncval \
          --hex_text=- --max_errors=-1 --stats --alignment=16 \
          --detailed --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_FOO.input

ncdis_FOO.vinput

   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.

   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 \
          -m32 -documentation