Add explanatory comments.

Former-commit-id: 738a14ec34d384dd239bf1a6947396e6f5958dd9

include/interfaces/irdb/STARSInstruction.h

@@ -22,10 +22,14 @@ class STARS_IRDB_Instruction_t : public STARS_Instruction_t
 
 		// Data initialization methods
 // jdh: get DISASM structure?  why not done in constructor?
+// ANSWER: We could call from constructor, but then we have to change some code that calls SMPInstr::FillCmd() and
+//  add some sort of query to get the bool return value of the current STARS_GetCmd(), i.e. to indicate that there
+//  were no errors in IDA Pro or beaEngine.
 		virtual bool STARS_GetCmd(void) { assert(0); }
 
 		// Get (accessor) methods
 // jdh: OK if insn sizes aren't well defined?
+// ANSWER: Shouldn't the size of machine code in bytes be available from beaEngine?
 		virtual inline uint16_t GetSize(void) const { assert(0); }
 		virtual inline uint16_t GetIDAOpcode(void) const { assert(0); }
 		virtual STARS_InstructionID_t GetNextInstructionID(void) { assert(0); }
@@ -33,20 +37,31 @@ class STARS_IRDB_Instruction_t : public STARS_Instruction_t
 
 // jdh: what are features?
 // what bits are used and what're their meanings?
+// ANSWER: Bit map identifying whether an operand is a DEF or USE, and of course some operands are both.
+// STARSIDAInstruction.cpp has:
+// static uint32_t UseMacros[STARS_UA_MAXOP] = {STARS_CF_USE1, STARS_CF_USE2, STARS_CF_USE3, STARS_CF_USE4, STARS_CF_USE5, STARS_CF_USE6};
+// static uint32_t DefMacros[STARS_UA_MAXOP] = { STARS_CF_CHG1, STARS_CF_CHG2, STARS_CF_CHG3, STARS_CF_CHG4, STARS_CF_CHG5, STARS_CF_CHG6 };
+// Each of these macro values is #defined and commented in STARSTypes.h.
+
 		virtual inline uint32_t GetInstFeatures(void) const { assert(0); }
 
 // jdh: consider returning by reference?
+// ANSWER: That would be a good optimization, but I will need some code reading time to ensure safety.
 		virtual STARSOpndTypePtr GetOpnd(std::size_t OpndNum) const { assert(0); }
 
 		// Set (mutator) methods
 
 		// why do instructions need to keep track of this?
+		// ANSWER: Imitating IDA Pro structure. Operands appear in many containers where it would not make
+		//  sense to carry around DEF or USE bits, but the features bitmap in the instruction holds them
+		//  within the context of the instruction they are part of. These mutators set bits in STARSfeatures.
 		virtual void SetOpUsed(std::size_t OpndNum) {assert(0); } // set the USE bit
 		virtual void SetOpNotUsed(std::size_t OpndNum) {assert(0); } // reset the USE bit
 		virtual void SetOpDefed(std::size_t OpndNum) {assert(0); } // set the DEF bit
 		virtual void SetOpNotDefed(std::size_t OpndNum) {assert(0); } // reset the DEF bit
 
 // jdh: not needed for IRDB?
+// ANSWER: Should never be called for IRDB variant.
 		virtual void RemoveIDAOp1ForIMUL(void) {assert(0); } // Fix up IDA Pro IMUL instruction by removing operand 1
 
 		// Query methods
@@ -56,20 +71,28 @@ class STARS_IRDB_Instruction_t : public STARS_Instruction_t
 		virtual bool OpcodeDefaultsTo64BitOperands(void) const {assert(0); }
 
 		// jdh: vex, etc. insns?  
+		// ANSWER: Yes. See implementations in STARSIDAInstruction.cpp.
 		virtual bool Has64BitOperands(void) const {assert(0); }
 		virtual inline bool Uses64BitAddressing(void) const {assert(0); }
 		virtual bool Uses32BitAddressing(void) const {assert(0); }
 
 // jdh: why are these not part of the Opnd class?
+// ANSWER: Just passing through to Opnd class. Implementation from idapro/STARSInstruction.h could be put in base class:
+//		inline bool IsRegOpnd(std::size_t OpndNum) const { return (STARScmd.Operands.at(OpndNum)->IsRegOp()); };
+//		inline bool IsImmedOpnd(std::size_t OpndNum) const { return (STARScmd.Operands.at(OpndNum)->IsImmedOp()); };
 		virtual inline bool IsRegOpnd(std::size_t OpndNum) const {assert(0); }
 		virtual inline bool IsImmedOpnd(std::size_t OpndNum) const {assert(0); }
 
 // jdh: what does this do?
-		virtual inline bool RegOpndMatches(std::size_t OpndNum, uint16_t RegNum) const {assert(0); }
+// ANSWER: Again, inline implementation could be in base class:
+//		inline bool RegOpndMatches(std::size_t OpndNum, uint16_t RegNum) const { return STARScmd.Operands.at(OpndNum)->MatchesReg(RegNum); };
+		virtual inline bool RegOpndMatches(std::size_t OpndNum, uint16_t RegNum) const { assert(0); }
+
 		virtual bool IsUseOpnd(std::size_t OpndNum) const {assert(0); }
 		virtual bool IsDefOpnd(std::size_t OpndNum) const {assert(0); }
 
 // jdh: what's this mean?
+// ANSWER: CurrInst is branch to a chunk that is disjoint from current chunk. Chunking is an IDA Pro concept.
 		virtual bool IsBranchToFarChunk(SMPInstr *CurrInst, STARS_ea_t &TargetAddr) {assert(0); }
 
 		// Operand creation methods
@@ -78,9 +101,14 @@ class STARS_IRDB_Instruction_t : public STARS_Instruction_t
 // jdh: do these "make operand" methods create an operand that's somehow linked/related to this instruction,
 // or are these generic operand for any instruction.  If generic, we should make them static factory-type methods
 // of the operand class.
+// ANSWER: Could be static factory methods of operand class. Current idapro/STARSIDAInstruction.cpp implementations
+//  make use of IDA Pro headers.
 
 
 // jdh: what is a void operand?
+// ANSWER: Placeholder, e.g. in an RTL tree, when there is no operand. Also, IDA Pro has an array of six operands
+//  for each instruction, and many of them have IDA Pro type o_void, which is now simulated in our brave new world
+//  of shared_ptrs to operands by having a VoidOpnd.
 		virtual STARSOpndTypePtr MakeVoidOpnd(void) const {assert(0); }
 		virtual STARSOpndTypePtr MakeImmediateOpnd(STARS_uval_t value) const {assert(0); }
 		virtual STARSOpndTypePtr MakeRegOpnd(uint16_t RegNum) const {assert(0); }