This directory contains the code for the native client verifier (ncv)
which checks whether binaries adhere to certain control flow
and instruction set restrictions.

The following scons targets are used for testing this code:

* ncdecoder_test - unittest for decoder

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

* ncval_tests runs a set of unit/regression tests which

* ncval can be used to valid individual binaries or all binaries in a directory

* nacl_cpuid without arguments runs pass/fail unit tests on the
CPU whitelist code and also exercises the CPUID feature detection
code. Exits with status 0 on success and non-zero on error.

* 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:
   -not_nc
        Don't apply native client rules to the elf file. Allows the
        disassembly of non-native client compliant executables.
   -i=XX...
        Specify an instruction to decode (may be up to 15 bytes long).
   -pc=XXXX
        By default, the instruction specified by the -b option is
        assumed to be 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 -b and -pc options. See file testdata/32/ncdis_test.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_test.input for an example of such a file.
   -use_iter
        By default, ncdis uses the instruction decoder of the x86-32 bit
        decoder. When this command line option is specified, the new
        x86-32/x86-64 bit decoder is used.
   -internal
        Prints out the internal form of the disassembled instruction as
        well. Only applicable when -use_iter is specified.

* To run some sample tests, one can run:
   > ncdis -self_document -commands=testdata/32/ncdis_iter_test.input
or
   > ncdis -use_iter -self_document -commands=testdata/64/ncdis_iter_test.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.
