[pypy-commit] cffi cffi-1.0: Move the remaining interesting parts of the PLAN file to doc/

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: cffi-1.0
Changeset: r1984:971a4b0c5aa4
Date: 2015-05-12 10:44 +0200
http://bitbucket.org/cffi/cffi/changeset/971a4b0c5aa4/

Log:	Move the remaining interesting parts of the PLAN file to doc/

diff --git a/_cffi1/PLAN b/_cffi1/PLAN
deleted file mode 100644
--- a/_cffi1/PLAN
+++ /dev/null
@@ -1,123 +0,0 @@
-
-==================================================
-CPython C extension module produced by recompile()
-==================================================
-
-Global variable:
-CTypeDescrObject *_cffi_types[];
-
-Every _cffi_types entry is initially an odd integer and is fixed
-to be a real `CTypeDescrObject *` later.
-
-The generated C functions are listed in _cffi_globals, a sorted array
-of entries which get turned lazily into real <builtin function
-objects>.  Each entry in this array has an index in the _cffi_types
-array, which describe the function type (CTOP_FUNCTION opcode, see
-below).  We turn the odd integers into real CTypeDescrObjects at the
-point where the entry is turned into a real builtin function object.
-
-The odd integers are "opcodes" that contain a type info in the lowest
-byte.  The remaining N-1 bytes of the integer is an "arg" that depends
-on the type info:
-
-CTOP_PRIMITIVE
-    the arg tells which primitive type it is
-
-CTOP_POINTER
-    the arg is the index of the item type in the _cffi_types array.
-
-CTOP_ARRAY
-    the arg is the index of the item type in the _cffi_types array.
-    followed by another opcode that contains (uintptr_t)length_of_array.
-
-CTOP_OPEN_ARRAY
-    for syntax like "int[]".  same as CTOP_ARRAY but without the length
-
-CTOP_STRUCT_UNION
-    the arg is the index of the struct/union in _cffi_structs_unions
-
-CTOP_ENUM
-    the arg is the index of the enum in _cffi_enums
-
-CTOP_TYPENAME
-    the arg is the index of the typename in _cffi_typenames
-
-CTOP_FUNCTION
-    the arg is the index of the result type in _cffi_types.
-    followed by other opcodes for the arguments.
-    terminated by CTOP_FUNCTION_END.
-
-CTOP_FUNCTION_END
-    the arg's lowest bit is set if there is a "..." argument.
-
-
-_cffi_globals
--------------
-
-Lists global functions (with a type CTOP_FUNCTION), and also global
-variables (with a different type than CTOP_FUNCTION).
-
-struct {
-    const char *name;
-    void *address;
-    int type_index;
-}
-
-
-_cffi_structs_unions
---------------------
-
-struct {
-    const char *name;
-    size_t size;
-    int alignment;
-    int flags;               // CT_UNION?  CT_IS_OPAQUE?
-    int num_fields;
-    int first_field_index;   // -> _cffi_fields array
-}
-
-struct _cffi_field_s {
-    const char *name;
-    size_t field_offset;
-    size_t field_size;
-    int field_bit_size;
-    int field_type;          // -> _cffi_types
-}
-
-
-_cffi_enums
------------
-
-struct {
-    const char *name;
-    int integer_type;        // -> _cffi_types
-}
-
-
-_cffi_typenames
----------------
-
-struct {
-    const char *name;
-    int type_index;          // -> _cffi_types
-}
-
-
-_cffi_constants
----------------
-
-struct {
-    const char *name;
-    unsigned long long value;
-    int cinfo_or_type_index;    // CINFO_POSITIVE_INT, CINFO_NONPOSITIVE_INT
-}
-
-
-
-Runtime type parsing
-==================================================
-
-For ffi.new() etc.  This is done by turning the C declaration into an
-array of opcodes like above, and then turning these opcodes into real
-types.  The array of opcodes is then freed.  We use a cache from C
-declaration to final types.
diff --git a/_cffi1/parse_c_type.h b/_cffi1/parse_c_type.h
--- a/_cffi1/parse_c_type.h
+++ b/_cffi1/parse_c_type.h
@@ -1,3 +1,5 @@
+
+/* See doc/parse_c_type.rst in the source of CFFI for more information */
 
 typedef void *_cffi_opcode_t;
 
diff --git a/doc/parse_c_type.rst b/doc/parse_c_type.rst
new file mode 100644
--- /dev/null
+++ b/doc/parse_c_type.rst
@@ -0,0 +1,72 @@
+==================================================
+CPython C extension module produced by recompile()
+==================================================
+
+Global variable::
+
+  _cffi_opcode_t _cffi_types[];
+
+Every _cffi_types entry is initially an odd integer.  At runtime, it
+is fixed to be a `CTypeDescrObject *` when the odd integer is
+interpreted and turned into a real <ctype> object.
+
+The generated C functions are listed in _cffi_globals, a sorted array
+of entries which get turned lazily into real <builtin function
+objects>.  Each entry in this array has an index in the _cffi_types
+array, which describe the function type (OP_FUNCTION opcode, see
+below).  We turn the odd integers describing argument and return types
+into real CTypeDescrObjects at the point where the entry is turned
+into a real builtin function object.
+
+The odd integers are "opcodes" that contain a type info in the lowest
+byte.  The remaining high bytes of the integer is an "arg" that depends
+on the type info:
+
+OP_PRIMITIVE
+    the arg tells which primitive type it is (an index in some list)
+
+OP_POINTER
+    the arg is the index of the item type in the _cffi_types array.
+
+OP_ARRAY
+    the arg is the index of the item type in the _cffi_types array.
+    followed by another opcode that contains (uintptr_t)length_of_array.
+
+OP_OPEN_ARRAY
+    for syntax like "int[]".  same as OP_ARRAY but without the length
+
+OP_STRUCT_UNION
+    the arg is the index of the struct/union in _cffi_structs_unions
+
+OP_ENUM
+    the arg is the index of the enum in _cffi_enums
+
+OP_TYPENAME
+    the arg is the index of the typename in _cffi_typenames
+
+OP_FUNCTION
+    the arg is the index of the result type in _cffi_types.
+    followed by other opcodes for the arguments.
+    terminated by OP_FUNCTION_END.
+
+OP_FUNCTION_END
+    the arg's lowest bit is set if there is a "..." argument.
+
+OP_NOOP
+    simple indirection: the arg is the index to look further in
+
+There are other opcodes, used not inside _cffi_types but in other
+individual ``type_op`` fields.  Most importantly, these are used
+on _cffi_globals entries:
+
+OP_CPYTHON_BLTN_*
+    declare a function
+
+OP_CONSTANT
+    declare a non-integral constant
+
+OP_CONSTANT_INT
+    declare an int constant
+
+OP_GLOBAL_VAR
+    declare a global var