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 generate ncval (and the corresponding library) pre/post
conditions for x86-64, scons build with the command-line argument
"--ncval_testing=1". This will build the code to test the validator on
single instructions, and to add any pre/post conditions needed by each
processed instruction. NOTE: This is a work in progress, and has not
been completed yet.

To run tests on pre/post conditions, use:

   .> ./scons --mode=opt-linux platform=x86-64 --ncval_testing=1 \
          ncval_testing

* 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/validator using:

       .> ./scons --mode=opt-linux platform=x86-64 --ncval_testing=1

   (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.

Debugging
---------

Many of the source files contain #define DEBUGGING flags. When
DEBUGGING is set to 1, additional debugging print messages are
compiled into the code. Unfortunately, by default, these message
frequently call routines that are not compiled into corresponding
executables (such as ncval and ncdis). To add the additional routines,
edit file

   native_client/site_scons/site_tools/library_deps.py

For x86-32, edit lines

            # When turning on the DEBUGGING flag in the x86-32 validator
            # or decoder, add the following:
            #'nc_opcode_modeling_verbose_x86_32',

to

            # When turning on the DEBUGGING flag in the x86-32 validator
            # or decoder, add the following:
            'nc_opcode_modeling_verbose_x86_32',

For x86-64, edit lines

            # When turning on the DEBUGGING flag in the x86-64 validator
            # or decoder, add the following:
            # 'nc_opcode_modeling_verbose_x86_64',

to

            # When turning on the DEBUGGING flag in the x86-64 validator
            # or decoder, add the following:
            'nc_opcode_modeling_verbose_x86_64',

These changes will make sure that the corresponding print routines are
added to the executables during link time.
