This directory is in the process of being deprecated, and being moved
to subdirectories of

    native_client/src/trusted/valdiator/x86

The code remaining in this directory are tests, and code to generate
tables used by the x86-32 and x86-64 validators. In addition, it
contains code to implement ncdis (a command line decoder) and ncval (a
command line validator).


The following scons targets are used for testing this code:

* ncdecode_test - unittest for decoder

* ncdis - can be used to disassemble executable binaries using the
  decoder library

* ncval_tests runs a set of unit/regression tests which tests the
  x86-32 validator.

* ncval can be used to validate executable binaries using the x86
  validator libraries.

* discmp.py <binary>: this compares decoder results for the ncdecode.c
  to the results of GNU "objdump -d", and complains if they do not
  agree in terms of instructions lengths. There used to be an easy way
  to use this script to test the validator on a bunch of binaries; I
  need to resurect that as it used to be driven by a Makefile which
  has been expunged from the tree. Exits with status 0 on success and
  non-zero on error.

* ncdis can be used to test the decoding of a single instruction, or
  by specifying an input file with instructions to decode. Options
  are:

   -i=XX...
        Specify an instruction to decode (may be up to 15 bytes long).
   --pc=XXXX

        By default, the EIP (or RIP in x86-64 code) register is assmed
        to linked at address zero. This option lets you specify some
        other (hexidecimal) address to use.

   --commands=filename

        Continue to process command line arguments from the specified
        file. Each non-comment line is treated as a separate command
        line. This allows one to test decoding multiple instructions
        using the -i and -pc options. See file
        testdata/32/ncdis_examples1.input for an example of such a
        file. If "-" is used, standard input is used instead of a
        file.

   --self_document

        Processes command lines (specified by the -commands argument)
        to a) only copy up to the "#" comment character, and then
        print the corresponding output for the disassembled
        instruction.  This allows simple testing of disassembled
        instructions, in that the input file (specified -commands)
        should be identical to the corresponding output generated by
        ncdis. See file testdata/32/ncdis_examples.input for an
        example of such a file.

   --full_decoder

        Specifies that the full decoder should be used to decode
        instructions.

   --validator_decoder

        Specifies that the decoder used by the validator should be
        used to decode instructions.

   --internal

        Prints out the internal form of the disassembled instruction
        as well, if it is available.

* To run some sample tests, one can run:

   > ncdis -self_document -commands=testdata/32/ncdis_examples1.input


* To see the set of modeled instructions used by the iterator model of
the decoder and validator, see testdata/XX/README (where XX is 32 or
64).

* To test the differences between the modeled x86-64 instructions, and
the effects of prefixes, when compared to xed, do the following (in
the native_client directory):

   (1) Generate the 64-bit decoder using:

       .> ./scons --mode=opt-linux platform=x86-64 sdl=none

   (2) Change directory to the following private tests:

       .> cd private_tests/enuminsts

   (3) Add the PIN library (see README in private_tests/enuminsts)
       tarfile.

   (4) Make sure you have the latest patches for enuminsts:

       .> svn update

   (5) Remove old implementations.

       .> make clean

   (6) Build new implementation

       .> make

   (7) Run the comparison of the NaCl decoder against xed using:

       .> ./enuminsts --checkoperands --nacllegal --xedimplemented --nops

The output generated describes differences from NACL (legal)
instructions, using the NACL decoder, and what xed finds.
