src/native_client/src/trusted/validator/x86/testing/enuminsts/enuminsts.h

   1 /*
   2  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 /*
   8  * enuminsts.h
   9  *
  10  * Defines the general API for defining decoder / validation tools to be
  11  * tested by the enumeration structure.
  12  */
  13
  14 #ifndef NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_TESTING_ENUMINSTS_ENUMINST_H_
  15 #define NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_TESTING_ENUMINSTS_ENUMINST_H_
  16
  17 #include "native_client/src/include/nacl_macros.h"
  18 #include "native_client/src/shared/utils/types.h"
  19
  20 /* Defines routine to print out non-fatal error due to unexpected
  21  * internal error.
  22  */
  23 extern void InternalError(const char *why);
  24
  25 /* Records that a fatal (i.e. non-recoverable) error occurred. */
  26 extern void ReportFatalError(const char* why);
  27
  28 /* Structure holding decoder/validation tool to test. */
  29 struct NaClEnumeratorDecoder;
  30
  31 /* Defines the maximum length of an instruction. */
  32 #define NACL_ENUM_MAX_INSTRUCTION_BYTES 15
  33
  34 /* Defines an array containing the bytes defining an instruction. */
  35 typedef uint8_t InstByteArray[NACL_ENUM_MAX_INSTRUCTION_BYTES];
  36
  37
  38 /* Defines the maximum number of enumeration decoders one can run. */
  39 #define NACL_MAX_ENUM_DECODERS 5
  40
  41 /*
  42  * Defines the data structure used by the driver to enumerate possible
  43  * instruction encodings.
  44  */
  45 typedef struct NaClEnumerator {
  46   /* Defines the buffer of bytes generated for an enumeration.
  47    */
  48   InstByteArray _itext;
  49
  50   /* Defines the actual number of bytes to be tried within _itext. */
  51   size_t _num_bytes;
  52
  53   /* Defines the two enumerator decoders to apply. */
  54   struct NaClEnumeratorDecoder* _decoder[NACL_MAX_ENUM_DECODERS];
  55
  56   /* Defines the number of decoders being applied. */
  57   size_t _num_decoders;
  58 } NaClEnumerator;
  59
  60 /* Define the (virtual) function to parse the first instruction in the itext
  61  * array of the enumerator. Assumes that the length of the first instruction
  62  * must be no larger than the _num_bytes field of the enumerator.
  63  */
  64 typedef void (*NaClDecoderParseInstFn)(const NaClEnumerator* enmerator,
  65                                        const int pc_address);
  66
  67 /* Defines the (virtual) function that returns the number of bytes in the
  68  * disassembled instruction.
  69  */
  70 typedef size_t (*NaClDecoderInstLengthFn)(const NaClEnumerator* enumerator);
  71
  72 /* Defines the (virtual) function that prints out the textual description
  73  * of the parsed instruction.
  74  */
  75 typedef void (*NaClDecoderPrintInstFn)(const NaClEnumerator* enumerator);
  76
  77 /* Defines the (virtual) function that returns the instruction mnemonic
  78  * for the disassembled instruction.
  79  */
  80 typedef const char*
  81 (*NaClDecoderGetInstMnemonicFn)(const NaClEnumerator* enumerator);
  82
  83 /* Defines the (virtual) function that returns the number of operands in
  84  * the disassembled instruction.
  85  */
  86 typedef size_t (*NaClDecoderGetInstNumOperandsFn)(
  87     const NaClEnumerator* enumerator);
  88
  89 /* Defines the (virtual) function that returns a text string describing the
  90  * operands of the instruciton (i.e. less the instruction mnemonic).
  91  */
  92 typedef const char*
  93 (*NaClDecoderGetInstOperandsTextFn)(const NaClEnumerator* enumerator);
  94
  95 /* Defines the (virtual) function that returns true if operand n of the
  96  * disassembled instruction is a write to one of the registers RSP, RBP,
  97  * or R15, and the disassembler can prove it (If it can't prove it, it
  98  * should simply return FALSE).
  99  */
 100 typedef Bool
 101 (*NaClDecoderOperandWritesToReservedRegFn)(const NaClEnumerator* enumerator,
 102                                            const size_t n);
 103
 104 /* Defines the (virtual) function that tests that the instruction is legal.
 105  */
 106 typedef Bool
 107 (*NaClDecoderIsInstLegalFn)(const NaClEnumerator *enumerator);
 108
 109 /* Defines the (virtual) function that tests that the instruction
 110  * validates to the level the tester can test validation.
 111  */
 112 typedef Bool
 113 (*NaClDecoderMaybeInstValidatesFn)(const NaClEnumerator* enumerator);
 114
 115 /* Defines the (virtual) function that tests (to the limit it can) that
 116  * the given code segment validates. If the tester can't run the validator
 117  * on the segment, it should return true.
 118  */
 119 typedef Bool
 120 (*NaClDecoderMaybeSegmentValidatesFn)(const NaClEnumerator* enumerator,
 121                                       const uint8_t* segment,
 122                                       const size_t size,
 123                                       const int pc_address);
 124
 125 /* Defines the (virtual) function that processes the given global flag,
 126  * in terms of the corresponding tester.
 127  */
 128 typedef void (*NaClDecoderInstallFlagFn)(const NaClEnumerator* enumerator,
 129                                          const char* flag_name,
 130                                          const void* flag_address);
 131
 132 /*
 133  * Defines the structure to hold a decoder/validation tool. Note that
 134  * the validation part is optional, and does not need to be supplied.
 135  *
 136  * Note: This struct acts like a C++ class with single inhertence. Derived
 137  * classes should define this as the first field in the struct, so that
 138  * they can be casted up to a NaClEnumeratorDecoder pointer.
 139  *
 140  * Note: Because not all decoders implement NaCl validation, some virtuals
 141  * are optional, and can be defined using NULL. In addition, some decoders
 142  * may not implement a full decoder, making it hard to define operands
 143  * of an instruction. Hence, the following virtual functions (i.e. fields)
 144  * are optional:
 145  *    _get_inst_mnemonic_fn
 146  *    _get_inst_num_operands_fn
 147  *    _get_inst_operands_text_fn;
 148  *    _writes_to_reserved_reg_fn;
 149  *    _maybe_inst_validates_fn;
 150  *    _segment_validates_fn;
 151  */
 152 typedef struct NaClEnumeratorDecoder {
 153   /* The identifying name for the tester. */
 154   const char* _id_name;
 155   /* True if the legal filter should be applied to this tester. That is,
 156    * only report on instructions this tester finds to be a legal instruction.
 157    * When false, filter out instructions that are illegal.
 158    * Note: This field is initialized by NaClPreregisterEnumeratorDecoder
 159    * in enuminsts.c
 160    */
 161   Bool _legal_only;
 162   /* True if we should should not run comparison tests, but only print.
 163    * Note: This field is initialized by NaClPreregisterEnumeratorDecoder
 164    * in enuminsts.c
 165    */
 166   Bool _print;
 167   /* True if we should print out the matched opcode sequence for the decoder.
 168    * Note: This field is initialized by NaClPreregisterEnumeratorDecoder
 169    * in enuminsts.c
 170    */
 171   Bool _print_opcode_sequence;
 172   /* True if we should print out the matched opcode sequence, as well as the
 173    * mnemonic and operands (as returned by _get_inst_mnemonic_fn and
 174    * _get_inst_operands_text_fn) as a comment after the matched opcode sequence.
 175    * Note: This field is initialized by NaClPreregisterEnumeratorDecoder
 176    * in enuminsts.c
 177    */
 178   Bool _print_opcode_sequence_plus_desc;
 179   /*
 180    * Parses the first instruction in the itext array of the enumerator. Assumes
 181    * that the length of the first instruction must be <= the _num_bytes field
 182    * of the enumerator.
 183    */
 184   NaClDecoderParseInstFn _parse_inst_fn;
 185   /*
 186    * Returns the number of bytes in the disassembled instruction.
 187    */
 188   NaClDecoderInstLengthFn _inst_length_fn;
 189   /*
 190    * Prints out the disassembled instruction.
 191    */
 192   NaClDecoderPrintInstFn _print_inst_fn;
 193   /*
 194    * Returns the mnemonic name of the disassembled instruction.
 195    * If not implemented, use NULL;
 196    */
 197   NaClDecoderGetInstMnemonicFn _get_inst_mnemonic_fn;
 198   /*
 199    * Returns the number of operands in the disassembled instruction.
 200    * If not implemented, use NULL;
 201    */
 202   NaClDecoderGetInstNumOperandsFn _get_inst_num_operands_fn;
 203   /*
 204    * Returns a text string containing the operands of the disassembled
 205    * instruction. If not implemented, use NULL;
 206    */
 207   NaClDecoderGetInstOperandsTextFn _get_inst_operands_text_fn;
 208   /*
 209    * Returns true if operand n of the disassembled instruction can be
 210    * proven to be a write to registers RSP, RBP, or R15. If not implemented,
 211    * use NULL.
 212    */
 213   NaClDecoderOperandWritesToReservedRegFn _writes_to_reserved_reg_fn;
 214   /*
 215    * Returns true if the instruction is legal, according to the tester.
 216    */
 217   NaClDecoderIsInstLegalFn _is_inst_legal_fn;
 218   /*
 219    * Returns true if the instruction will validate. If not implemented,
 220    * use NULL. This function should only be implemented for decoders that
 221    * define a nacl validator.
 222    */
 223   NaClDecoderMaybeInstValidatesFn _maybe_inst_validates_fn;
 224   /*
 225    * Returns true if the segment should validate, to the best we can
 226    * check with this tester. If not implemented, use NULL;
 227    */
 228   NaClDecoderMaybeSegmentValidatesFn _segment_validates_fn;
 229   /* Processes the given command line flag. */
 230   NaClDecoderInstallFlagFn _install_flag_fn;
 231   /* Holds the usage message to printed for the decoder in the (command-line)
 232    * usage function.
 233    */
 234   const char* _usage_message;
 235 } NaClEnumeratorDecoder;
 236
 237 #endif  /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_TESTING_ENUMINSTS_ENUMINST_H_ */