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 10976)
+++ src/trusted/validator_ragel/decoder.h	(working copy)
@@ -17,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.
@@ -32,7 +36,7 @@
   OPERAND_TYPE_MMX,              /* MMX registers: %mmX.                      */
   OPERAND_TYPE_XMM,              /* XMM register: %xmmX.                      */
   OPERAND_TYPE_YMM,              /* YMM registers: %ymmX.                     */
-  OPERAND_TYPE_SEGMENT_REGISTER, /* Operand is segment register: %es … %gs.   */
+  OPERAND_TYPE_SEGMENT_REGISTER, /* Operand is segment register: %es ... %gs. */
   OPERAND_TYPE_CONTROL_REGISTER, /* Operand is control register: %crX.        */
   OPERAND_TYPE_DEBUG_REGISTER,   /* Operand is debug register: %drX.          */
   OPERAND_TYPE_TEST_REGISTER,    /* Operand is test register: %trX.           */
@@ -74,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,
@@ -93,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.                    */
@@ -122,6 +134,9 @@
   DISP64
 };
 
+/*
+ * Information about decoded instruction: name, operands, prefixes, etc.
+ */
 struct Instruction {
   const char *name;
   unsigned char operands_count;
@@ -154,22 +169,26 @@
 };
 
 /*
+ * Instruction processing callback: called once for each instruction in a stream
+ *
  * "begin" points to first byte of the instruction
- * "end" points to the last byte of the instruction
- *   for single-byte instruction “begin” == “end”
- * "instruction" is detailed information about instruction
+ * "end" points to the first byte of the next instruction
+ *   for single-byte instruction "begin + 1" == "end"
+ * "instruction" contains detailed information about instruction
  */
 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.
+ *
  * "ptr" points to the first byte rejected by DFA and can be used in more
  * advanced decoders to try to do some kind of recovery.
  */
 typedef void (*ProcessDecodingErrorFunc) (const uint8_t *ptr,
-                                          void *userdata);
+                                          void *callback_data);
 
 /*
  * kFullCPUIDFeatures is pre-defined constant of NaClCPUFeaturesX86 type with
@@ -179,11 +198,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