[Scummvm-cvs-logs] SF.net SVN: scummvm:[51993] tools/branches/gsoc2010-decompiler/decompiler/ doc

[pidgeot at users.sourceforge.net]

Revision: 51993
          http://scummvm.svn.sourceforge.net/scummvm/?rev=51993&view=rev
Author:   pidgeot
Date:     2010-08-11 17:33:36 +0000 (Wed, 11 Aug 2010)

Log Message:
-----------
DECOMPILER: Documentation updates

Modified Paths:
--------------
    tools/branches/gsoc2010-decompiler/decompiler/doc/cfg.tex
    tools/branches/gsoc2010-decompiler/decompiler/doc/codegen.tex
    tools/branches/gsoc2010-decompiler/decompiler/doc/disassembler.tex

Modified: tools/branches/gsoc2010-decompiler/decompiler/doc/cfg.tex
===================================================================
--- tools/branches/gsoc2010-decompiler/decompiler/doc/cfg.tex	2010-08-11 17:33:12 UTC (rev 51992)
+++ tools/branches/gsoc2010-decompiler/decompiler/doc/cfg.tex	2010-08-11 17:33:36 UTC (rev 51993)
@@ -34,7 +34,7 @@
 \item If the next instruction is a jump or a return, end the group here.
 \item If the next instruction has multiple predecessors, end the group here.
 \item If the current instruction brings the stack to a lower level than the start of the current group, make the new level the expected stack level (to support clean-up after control structures).
-\item If the current instruction brings the stack level to the same as the start of the current group, and at least one instruction with a stack effect >= 0 exists in the group, end the group here.
+\item If the current instruction brings the stack level to the same as the start of the current group, and at least one instruction with a non-negative stack effect exists in the group, end the group here.
 \end{itemize}
 
 Unreachable code will not be processed in the group generation, but will remain as individual instructions.

Modified: tools/branches/gsoc2010-decompiler/decompiler/doc/codegen.tex
===================================================================
--- tools/branches/gsoc2010-decompiler/decompiler/doc/codegen.tex	2010-08-11 17:33:12 UTC (rev 51992)
+++ tools/branches/gsoc2010-decompiler/decompiler/doc/codegen.tex	2010-08-11 17:33:36 UTC (rev 51993)
@@ -79,7 +79,7 @@
 \subsection{Default instruction handling and instruction metadata}
 When disassembling, you can store metadata for a given instruction to be used during code generation.
 
-Default handling exists for a number of instruction types, described below. If the default handling does not work for a particular instruction, you can force the instruction to process by your engine specific code by placing the hexadecimal byte 0xC0 at the start of the metadata string. This character was chosen for two reasons: it is unlikely to be used as a byte in a script, and the byte is invalid in UTF-8, avoiding potential encoding conflicts. Note that if you do this, it is your own responsibility to strip off that character during processing.
+Default handling exists for a number of instruction types, described below. If the default handling does not work for a particular instruction, you can force the instruction to be processed by your engine-specific \code{processInst} by placing the hexadecimal byte 0xC0 at the start of the metadata string. This character was chosen for two reasons: it is unlikely to be used as a byte in a script, and the byte is invalid in UTF-8, avoiding potential encoding conflicts. Note that if you do this, it is your own responsibility to strip off that character during processing.
 
 \paragraph{kDup}
 The topmost stack entry is popped, and two duplicated copies are pushed to the stack. If the entry being duplicated was not already a duplicate, an assignment will be output to assign the original stack entry to a special dup variable, to show that the original entry is not being recalculated.
@@ -91,7 +91,7 @@
 The two topmost stack entries are popped, and a BinaryOpEntry is created and pushed to the stack, using the codegen metadata as the operator and the previously popped entries as the operands. The order of the operands is determined by the value of the field \code{\_binOrder}, as described in Section~\vref{sec:argOrder}.
 
 \paragraph{kCondJump and kCondJumpRel}
-The instruction is sent for processing in the engine-specific \code{processInst} method, so you can add any information provided by the specific opcode. The information on the stack is then read by the default code, and an if, while or do-while condition is output using the topmost stack entry.
+The instruction is first sent for processing in the engine-specific \code{processInst} method, so you can add any information provided by the specific opcode. The information on the stack is then read by the default code, and an if, while or do-while condition is output using the topmost stack entry.
 
 \paragraph{kJump and kJumpRel}
 If the current group has been detected as a break or a continue, a break or continue statement is output. Otherwise, the jump is analyzed and output unless it is a jump back to the condition of a while-loop that ends there, or it is determined that the jump is unnecessary due to an else block following immediately after.

Modified: tools/branches/gsoc2010-decompiler/decompiler/doc/disassembler.tex
===================================================================
--- tools/branches/gsoc2010-decompiler/decompiler/doc/disassembler.tex	2010-08-11 17:33:12 UTC (rev 51992)
+++ tools/branches/gsoc2010-decompiler/decompiler/doc/disassembler.tex	2010-08-11 17:33:36 UTC (rev 51993)
@@ -60,19 +60,18 @@
 class Disassembler {
 protected:
 	Common::File _f;
-	std::vector<Instruction> _insts;
+	std::vector<Instruction> &_insts;
 	uint32 _addressBase;
-	bool _disassemblyDone;
 
-	virtual void doDisassemble() = 0;
+	virtual void doDisassemble() throw(UnknownOpcodeException) = 0;
 	virtual void doDumpDisassembly(std::ostream &output);
 
 public:
-	Disassembler();
+	Disassembler(std::vector<Instruction> &insts);
 	virtual ~Disassembler() {}
 
 	void open(const char *filename);
-	const std::vector<Instruction> &disassemble();
+	void disassemble();
 	void dumpDisassembly(std::ostream &output);
 };
 \end{lstlisting}
@@ -80,15 +79,13 @@
 
 \code{\_f} represents the file you will be reading from. The file is opened using the \code{open} function.
 
-\code{\_insts} is an \code{std::vector} storing the instructions. Whenever you have read an instruction fully, add it here.
+\code{\_insts} is a reference to an \code{std::vector} storing the instructions, passed in via the constructor. Whenever you have read an instruction fully, add it here.
 
 \code{\_addressBase} is provided as a convenience if your engine does not consider the first instruction to be located at address 0. Assign the expected base address to this field, and make sure that the addresses you assign to the instructions are relative to this base address. This is mainly useful if your engine supports jumps or other references to absolute addresses in the script; if only relative addresses are used, the base address will not be relevant.
 
-\code{\_disassemblyDone} is used to represent whether or not disassembly has already been performed. This is set automatically by \code{disassemble} and  \code{dumpDisassembly}.
-
 \code{doDisassemble} is the method used to perform the actual disassembly, so this method must be implemented by all disassemblers.
 
-\code{disassemble} simply calls the \code{doDisassemble} method to perform the disassembly (if necessary), and returns \code{\_insts} to the calling method.
+\code{disassemble} simply calls the \code{doDisassemble} method to perform the disassembly. The result is cached, so if this method is called twice, \code{doDisassemble} will only be called the first time.
 
 Finally, \code{dumpDisassembly} is used to output the instructions in a human-readable format to a file or stdout, performing a disassembly first if required, and then calls \code{doDumpDisassembly} to perform the actual output. A default implementation is provided for \code{doDumpDisassembly}, but you can override it if the standard output format is not suitable for your particular engine.
 
@@ -246,7 +243,7 @@
 \begin{C++}
 \begin{lstlisting}
 START_OPCODES;
-	OPCODE_MD(0x14, "add", kBinaryOp, -1, "", "}");
+	OPCODE_MD(0x14, "add", kBinaryOp, -1, "", "+");
 END_OPCODES;
 \end{lstlisting}
 \end{C++}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.