- Improve comments, docs, code...

1 files changed, 32 insertions, 17 deletions

diff --git a/Zend/README.ZEND_VM b/Zend/README.ZEND_VM
index bc82e9817c..3020f0ed4d 100644
--- a/Zend/README.ZEND_VM
+++ b/Zend/README.ZEND_VM
@@ -9,22 +9,21 @@ method). As most in most PHP applications raw execution speed isn't the
 limiting factor but system calls and database callls are, your mileage with
 this patch will vary.
 
-Most parts of the old zend_execute.c go into zend_vm_handlers.h. Here you can
+Most parts of the old zend_execute.c go into zend_vm_def.h. Here you can
 find opcode handlers and helpers. The typical opcode handler template looks
 like this:
 
-#define <OPCODE>_SPEC() OPDEF(<OPCODE>, <OP1_TYPES>, <OP2_TYPES>)
-#if HAVE_OP(<OPCODE>)
-ZEND_VM_HANDLER(<OPCODE>)
+ZEND_VM_HANDLER(<OPCODE-NUMBER>, <OPCODE>, <OP1_TYPES>, <OP2_TYPES>)
 {
 	<HANDLER'S CODE>
 }
-#endif
 
+<OPCODE-NUMBER> is a opcode number (0, 1, ...)
 <OPCODE> is an opcode name (ZEN_NOP, ZEND_ADD, :)
 <OP1_TYPES> & <OP2_TYPES> are masks for allowed operand op_types. Specializer
-will generate code only for defined combination of types. You can also use
-M_ANY mask to disable specialization according operand's op_type.
+will generate code only for defined combination of types. You can use any 
+combination of the following op_types UNUSED, CONST, VAR, TMP and  CV also
+you can use ANY mask to disable specialization according operand's op_type.
 <HANDLER'S CODE> is a handler's code itself. For most handlers it stills the
 same as in old zend_execute.c, but now it uses macros to access opcode operands
 and some internal executor data.
@@ -72,19 +71,35 @@ FREE_OP<X>_IF_VAR()
 FREE_OP<X>_VAR_PTR()
 	FREE_VAR_PTR(free_op<X>)
 
-If handler can receive control form some other handler it should be defined
-with macro ZEND_VM_HANDLER_EX() instead of ZEND_VM_HANDLER().
 
-The additional parameters of helpers (see ZEND_VM_DISPATCH_TO_HELPER_EX) mast
-be defined in the start of execute() function inside ZEND_VM_HELPER_VAR() macro.
+Executor's helpers can be defined without parameters or with one parameter. 
+This is done with the following constructs:
 
-zend_vm.h and zend_vm_spec.h are used for abstraction of execution method and
-operands specialization. They mainly contain macros that are used for
-compile-time specialization.
+ZEND_VM_HELPER(<HELPER-NAME>, <OP1_TYPES>, <OP2_TYPES>)
+{
+	<HELPER'S CODE>
+}
+
+ZEND_VM_HELPER_EX(<HELPER-NAME>, <OP1_TYPES>, <OP2_TYPES>, <PARAM_SPEC>)
+{
+	<HELPER'S CODE>
+}
+
+Executor's code is generated by PHP script zend_vm_gen.php it uses zend_vm_def.h
+and zend_vm_execute.skl as input and produces zend_vm_opcodes.h and 
+zend_vm_execute.h. The first file is a list of opcode definitions. It is 
+included from zend_compile.h. The second one is an executor code itself. It is
+included from zend_execute.c.
+
+zend_vm_gen.php can produce different kind of executors. You can select 
+different opcode threading model using --with-vm-kind=CALL|SWITCH|GOTO. You can 
+disable opcode specialization using --without-specializer. You can include or
+exclude old executor together with specialized one using --without-old-executor.
+At last you can debug executor using original zend_vm_def.h or generated file
+zend_vm_execute.h. Debugging with generated file requires --without-lines
+option. By default ZE2 uses the following command to generate executor:
 
-You can switch specialization on/off with define/undefined of the ZEND_VM_SPEC
-in the start of zend.vm.h and select execution method by defining ZEND_VM_KIND
-in the same place.
+$ php zend_vm_gen.php --with-vm-kind=CALL --without-lines
 
 Zend Engine II currently includes two executors during the build process, one
 is the specialized version and the other is the old one non-specialized with