Move validator_x86_XX.rl out of unreviewed.

src/trusted/validator_ragel/decoder.h

 /*
  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
+/*
+ * Data structures for decoding instructions.  Includes definitions which are
+ * by both decoders (full-blown standalone one and reduced one in validator).
+ */
+
 #ifndef NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_RAGEL_DECODER_H_
 #define NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_RAGEL_DECODER_H_
 
 #include "native_client/src/shared/utils/types.h"
 #include "native_client/src/trusted/validator/x86/nacl_cpuid.h"
 
 EXTERN_C_BEGIN
 
+/*
+ * Instruction operand TYPE: GP register size (8-bit, 32-bit, MMX, XXM, etc), or
+ * in-memory structure (far pointer, 256-bit SIMD operands, etc).
+ */
 enum OperandType {
   /*
    * These are for general-purpose registers, memory access and immediates.
    * They are not used for XMM, MMX etc.
    */
   OPERAND_TYPE_8_BIT,
   OPERAND_TYPE_16_BIT,
   OPERAND_TYPE_32_BIT,
   OPERAND_TYPE_64_BIT,
 
@@ skipping 37 matching lines @@
 
   /* Miscellaneous structures in memory.  */
   OPERAND_TYPE_X87_BCD,           /* 10-byte packed BCD value.                */
   OPERAND_TYPE_X87_ENV,           /* A 14-byte or 28-byte x87 environment.    */
   OPERAND_TYPE_X87_STATE,         /* A 94-byte or 108-byte x87 state.         */
   OPERAND_TYPE_X87_MMX_XMM_STATE, /* A 512-byte extended x87/MMX/XMM state.   */
   OPERAND_TYPE_SELECTOR,          /* Operand is 6/10 bytes selector.          */
   OPERAND_TYPE_FAR_PTR            /* Operand is 6/10 bytes far pointer.       */
 };
 
+/*
+ * Instruction operand NAME: register number (REG_RAX means any of the following
+ * registers: %al/%ax/%eax/%rax/%st(0)/%mm0/%xmm0/%ymm0/%es/%cr0/%db0/%tr0), or
+ * non-register operand (REG_RM means address in memory specified via “ModR/M
+ * byte” (plus may be “SIB byte” or displacement), REG_DS_RBX is special operand
+ * of “xlat” instruction, REG_ST is to of x87 stack and so on - see below for
+ * for the full list).
+ */
 enum OperandName {
   /* First 16 registers are compatible with encoding of registers in x86 ABI. */
   REG_RAX,
   REG_RCX,
   REG_RDX,
   REG_RBX,
   REG_RSP,
   REG_RBP,
   REG_RSI,
   REG_RDI,
   REG_R8,
   REG_R9,
   REG_R10,
   REG_R11,
   REG_R12,
   REG_R13,
   REG_R14,
   REG_R15,
   /* These are different kinds of operands used in special cases.             */
-  REG_RM,           /* Address in memory via rm field.                        */
+  REG_RM,           /* Address in memory via ModR/M (+SIB).                   */
   REG_RIP,          /* RIP - used as base in x86-64 mode.                     */
   REG_RIZ,          /* EIZ/RIZ - used as "always zero index" register.        */
   REG_IMM,          /* Fixed value in imm field.                              */
   REG_IMM2,         /* Fixed value in second imm field.                       */
-  REG_DS_RBX,       /* Fox xlat: %ds(%rbx).                                   */
+  REG_DS_RBX,       /* Fox xlat: %ds:(%rbx).                                  */
   REG_ES_RDI,       /* For string instructions: %es:(%rsi).                   */
   REG_DS_RSI,       /* For string instructions: %ds:(%rdi).                   */
   REG_PORT_DX,      /* 16-bit DX: for in/out instructions.                    */
   NO_REG,           /* For modrm: both index and base can be absent.          */
   REG_ST,           /* For x87 instructions: implicit %st.                    */
   JMP_TO,           /* Operand is jump target address: usually %rip+offset.   */
 };
 
 /*
  * Displacement can be of four different sizes in x86 instruction set: nothing,
  * 8-bit, 16-bit, 32-bit, and 64-bit.  These are traditionally treated slightly
  * differently by decoders: 8-bit are usually printed as signed offset, while
  * 32-bit (in ia32 mode) and 64-bit (in amd64 mode) are printed as unsigned
  * offset.
  */
 enum DisplacementMode {
   DISPNONE,
   DISP8,
   DISP16,
   DISP32,
   DISP64
 };
 
+/*
+ * Insformation about decoded instruction: name, operands, prefixes, etc.
+ */
 struct Instruction {
   const char *name;
   unsigned char operands_count;
   struct {
     unsigned char rex;        /* Mostly to distingush cases like %ah vs %spl. */
     Bool rex_b_spurious;
     Bool rex_x_spurious;
     Bool rex_r_spurious;
     Bool rex_w_spurious;
     Bool data16;              /* "Normal", non-rex prefixes. */
@@ skipping 12 matching lines @@
     enum OperandName base;
     enum OperandName index;
     int scale;
     int64_t offset;
     enum DisplacementMode disp_type;
   } rm;
   uint64_t imm[2];
   const char* att_instruction_suffix;
 };
 
+/*
+ * Instruction processing callback: called once for each instruction in a stream
+ *
+ * Note: there are peculiar case related to “fwait” threatment.  For historical
+ * reasons it's both a standalone instruction (which can be used in separation)
+ * and “prefix” for instructions “fclex”, “finit”, “fsave”, “fsaves”, “fstcw”,
+ * “fstenv”, “fstenvs”, and “fstsw”.  Decoder processes sequence of, e.g.
+ * “fwait” and “fninit” in the followin way:
+ *  • First “fwait” is processed by ProcessInstructionFunc.
+ *  • Then “fninit” is processed by ProcessInstructionFunc.
+ *    Decoder detects the case of »“fwait” followed by “fninit”« situation and
+ *    reports correct name of the operation but it DOES NOT include “fwait” in
+ *    the piece marked by “begin” and “end” pointers.
+ */
 typedef void (*ProcessInstructionFunc) (const uint8_t *begin,
                                         const uint8_t *end,
                                         struct Instruction *instruction,
-                                        void *userdata);
+                                        void *callback_data);
 
+/*
+ * Decoding error: called when decoder's DFA does not recognize the instruction.
+ */
 typedef void (*ProcessDecodingErrorFunc) (const uint8_t *ptr,
-                                          void *userdata);
+                                          void *callback_data);
 
 /*
  * kFullCPUIDFeatures is pre-defined constant of NaClCPUFeaturesX86 type with
  * all possible CPUID features enabled.
  */
 extern const NaClCPUFeaturesX86 kFullCPUIDFeatures;
 
 int DecodeChunkAMD64(const uint8_t *data, size_t size,
                      ProcessInstructionFunc process_instruction,
-                     ProcessDecodingErrorFunc process_error, void *userdata);
+                     ProcessDecodingErrorFunc process_error,
+                     void *callback_data);
 
 int DecodeChunkIA32(const uint8_t *data, size_t size,
                     ProcessInstructionFunc process_instruction,
-                    ProcessDecodingErrorFunc process_error, void *userdata);
+                    ProcessDecodingErrorFunc process_error,
+                    void *callback_data);
 
 EXTERN_C_END
 
 #endif  /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_RAGEL_DECODER_H_ */