src/native_client/src/trusted/validator/x86/testing/enuminsts/README.txt

   1 Copyright (c) 2012 The Native Client Authors. All rights reserved.
   2 Use of this source code is governed by a BSD-style license that be
   3 found in the LICENSE file.
   4
   5 ************************************************************************
   6  NOTE: The Scons version of enuminst is documented in README_scons.txt.
   7  It has less functionality than the Makefile version.
   8 ************************************************************************
   9
  10 Exhaustive instruction enumeration test for x86 Native Client decoder.
  11 Limited testing of validator.
  12
  13 This test performs an exhaustive enumeration of x86 instructions,
  14 comparing two or more decoders. Specific decoders it can compare are:
  15    * the old Native Client production decoders (both 32- and 64-bit)
  16    * the new ragel-based Native Client decoders
  17    * the XED decoder from Intel
  18
  19 For each instruction enuminst can compare:
  20    * instruction validity (still being worked on in x86-32)
  21    * instruction length
  22    * opcodes (64-bit only)
  23
  24
  25 Building enuminsts-32 and enuminsts-64
  26
  27 Enuminsts can be built in 32- and 64-bit variants using:
  28    % make BITS=32 clean enuminsts-64
  29    % make BITS=64 clean enuminsts-32
  30 To build for Ragel use:
  31    % make BITS=64 RAGEL=1 clean enuminsts-64
  32 The Makefile does not do proper dependency checking, so please use
  33 a clean build. The build will fail if the required NaCl libraries
  34 are not already built.
  35
  36 By default, the build assumes that you have downloaded a (Pin) version of
  37 xed. See variable PINV in Makefile to see the version assumed.  You can
  38 specify the xed on the command line, allowing use other versions of xed.
  39
  40 Running enuminsts
  41 --------------------
  42 The instructions that follow are for enuminsts-64; the same identical
  43 instructions should work for enuminsts-32 as well.
  44
  45 Enuminsts requires that you specify one or more filters to indicate how
  46 to process instructions produced by the enumeration. For example:
  47    % enuminsts-64 --legal=nacl --illegal=xed --print=xed
  48 will filter instructions that decode for NaCl but don't decode for Xed,
  49 and then uses Xed to print the instructions. You can induce additional
  50 NaCl validation checking with the --nacllegal flag:
  51    % enuminsts-64 --nacllegal --illegal=nacl --legal=ragel --print=ragel
  52 This causes enuminsts to apply limited validator checks (instruction
  53 type) in addition to decoder problems.
  54
  55 Enuminsts-64 supports a --help option to see all command-line options:
  56    % ./enuminsts-32 --help
  57
  58
  59 Testing against the NaCl baseline
  60 ---------------------------------
  61 TODO(kschimpf): rewrite this section. It seems incorrect.
  62
  63 Included in this directory is (one or more) frozen versions of the
  64 enumerator, named "enuminsts-XX-NNNNN" where XX in {32, 64}, and NNNNN
  65 is the nacl revision number used to generate the executable.
  66
  67 The (shell) file "enuminsts-64-baseline" is a canned script that pipes
  68 a run of "enuminsts-XX-NNNNN" into "enuminsts-64", using the input
  69 decoder on the output generated by "enuminsts-XX-NNNNN". The command
  70 line arguments to "enuminsts-64-baseline" are passed to the latter
  71 executable "enuminsts-64".
  72
  73 To see possible (valid) arguments, run:
  74
  75    .> ./enuminsts-64-baseline --help
  76
  77 The purpose of this run is that the baseline has been defined so that
  78 it generates a large, valid set of x86-64 instructions, and then
  79 (though enuminsts-64) allows you to run these instructions on any of
  80 the valid decoders.
  81
  82 To run a decoder DDD on the set of (legal) baseline instructions, run:
  83
  84   .> ./enuminsts-64-baseline --DDD
  85
  86 Note: you can add additional command line arguments. To see them, add
  87 the "--Help" option to the command line.
  88
  89 Building enuminsts with a XED decoder
  90 -------------------------------------
  91
  92 Before building enuminsts with a xed decoder, you must download
  93 Intel's xed decoder, distributed as part of PIN. It is available for
  94 free from
  95
  96    http://www.pintool.org.
  97
  98 The default for the Makefile is PIN version 2.10-45467. However, any
  99 version can be used if you specify "PINV=VVVVVVVVVVV" (where
 100 VVVVVVVVVV is the PIN version you downloaded). To build enuminsts
 101 with xed, run
 102
 103    .> make BITS=XX PINV=VVVVVVVVVVV XED=1
 104
 105 where BITS in {32, 64} and VVVVVVVVVV is the PIN version you
 106 downloaded. This will build the executable enuminsts-XX-xed.
 107
 108 Building a new baseline
 109 -----------------------
 110
 111 To build a new baseline, you need to build a frozen executable
 112 of the form enuminsts-XX-NNNNN by running the command:
 113
 114    .> make BITS=64 NACLV=NNNNN
 115
 116 where NNNNN is the revision number of the corresponding generated NaCl
 117 (scons) libraries. This will build executable
 118 "enuminsts-64-NNNNN". You also need to build a copy of enuminsts with
 119 a xed decoder (see "Building enuminsts with a xed decoder").
 120
 121 Once both executables have been built, edit shell file
 122 enuminsts-64-legal to define the command line arguments you believe
 123 will generate legal instructions, and pipe the corresponding opcode
 124 sequences to the output (i.e. use options --opcode_bytes or
 125 --opcode_bytes_plus_dec).
 126
 127 To test that you have generated the correct command line arguments,
 128 run:
 129 TODO(kschimpf): check this; looks wrong.
 130    .> ./enuminsts-64-baseline-test
 131
 132 This shell file will perform two runs of enuminsts-64-legal. The first
 133 will compare the set of generated instructions against the xed decoder
 134 to find instructions that are legal in both. The second will then
 135 compare the set of generated instructions against the xed decoder to
 136 find instructions that are not understood by xed.  If you have your
 137 arguments right, no error messages will be reported in either step.
 138
 139 If enuminsts-64-baseline-test doesn't generate any errors, you have
 140 found an acceptable new baseline, and you can install it. If you get
 141 errors, but are only generated in the first pass, you can still use
 142 enuminsts-64-baseline for the baseline. However, any instruction for
 143 which an error is reported in the first pass, will not be generated by
 144 the baseline.
 145
 146 If you get errors in the second pass (which tests if the generated
 147 instructions are invalid according to xed), you need to change your
 148 parameters in enuminsts-64-legal.  These errors represent bad
 149 instruction opcodes that will be generated by the baseline.
 150
 151 Brad's Notes on testing Ragel:
 152 ------------------------------
 153 enuminsts-64 --legal=nacl --legal=ragel
 154     Compare lengths of instructions that decode for both nacl and ragel.
 155     As of April 2012 there were a lot of these.
 156
 157 enuminsts-64 --illegal=nacl --legal=ragel --print=ragel
 158     Identifies instructions decoded by ragel but not by nacl
 159
 160 enuminsts-64 --legal=nacl --illegal=ragel --print=nacl
 161     Identifies instructions decoded by nacl but not by ragel
 162
 163 When Ragel supports a partial-validation mode, checking if a single
 164 instruction might be legal (ignoring inter-instruction rules) these
 165 tests should be useful:
 166
 167 enuminsts-64 --nacllegal --legal=nacl --illegal=ragel --print=ragel
 168       Print's instructions accepted by NaCl but not Ragel
 169
 170 enuminsts-64 --nacllegal --legal=ragel --illegal=nacl print=nacl
 171       Print's instructions legal for Ragel but not NaCl.
 172       Currently, no problems!
 173
 174 enuminsts-64 --nacl --ragel
 175       Compares instruction length only.