Document bindings implementaion
Change-Id: Ic2690fa09f35284fcb96050e8d6ce16b724e45dc
Reviewed-on: https://pdfium-review.googlesource.com/6212
Commit-Queue: Tom Sepez <tsepez@chromium.org>
Reviewed-by: Lei Zhang <thestig@chromium.org>
diff --git a/fxjs/README b/fxjs/README
new file mode 100644
index 0000000..99d2f90
--- /dev/null
+++ b/fxjs/README
@@ -0,0 +1,33 @@
+There are two separate wrappers for V8 here. One is called FXJS, and
+it is used by the non-XFA code. The other is called FXJSE, and it is
+used only by the XFA code. Additionally FXJSE may request services
+from FXJS to bridge the two.
+
+Both the FXJS and FXJSE binding code needs to be replaced by something
+saner, perhaps Gin or perhaps some IDL. See
+ https://bugs.chromium.org/p/pdfium/issues/detail?id=716
+for progress on the issue.
+
+FXJS binds objects by sticking a pointer to a CFXJS_PerObjectData in
+the V8 object's internal slot. FXJSE binds objects by sticking a
+pointer to either an actual v8 function object or a CFXJSE_HostObject
+in the the V8 object's internal slot, depending upon whether the object
+represents (in some notion) a "class" or an "instance". Also, V8 objects
+bound in one library may unexpectedly arrive at the other given a script
+that's trying to mess with us.
+
+To distinguish these cases, we use two internal slots for all bound
+objects, regardless of the FXJS/FXJSE distinction. Slot 0 is the
+tag and contains either:
+ kPerObjectDataTag for FXJS objects, or
+ g_FXJSETagString for FXJSE Host objects, or
+ One of 4 specific FXJSE_CLASS_DESCRIPTOR globals for FXJSE classes:
+ GlobalClassDescriptor
+ NormalClassDescriptor
+ VariablesClassDescriptor
+ formcalc_fm2js_descriptor
+
+Slot 1's contents are determined by these tags:
+ kPerObjectDataTag means to expect a CFXJS_PerObjectData.
+ g_FXJSETagString means to expect a CFXJSE_HostObject.
+ A FXJSE_CLASS_DESCRIPTOR pointer means to expect a v8 function.
