Move validator_x86_XX.rl out of unreviewed.

src/trusted/validator_ragel/decoder.h

Index: src/trusted/validator_ragel/decoder.h
===================================================================
--- src/trusted/validator_ragel/decoder.h	(revision 9944)
+++ src/trusted/validator_ragel/decoder.h	(working copy)
@@ -4,6 +4,11 @@
  * 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_
 
@@ -12,6 +17,10 @@
 
 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.
@@ -69,6 +78,14 @@
   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,
@@ -88,12 +105,12 @@
   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.                    */
@@ -117,6 +134,9 @@
   DISP64
 };
 
+/*
+ * Insformation about decoded instruction: name, operands, prefixes, etc.
+ */
 struct Instruction {
   const char *name;
   unsigned char operands_count;
@@ -149,13 +169,30 @@
   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
@@ -165,11 +202,13 @@
 
 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