| OLD | NEW |
|---|
| (Empty) |
| 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. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 625923004:
Delete old x86 validator. (Closed)
Base URL: svn://svn.chromium.org/native_client/trunk/src/native_client