ext/opcache/jit: add some API documentation

Author: MaxKellermann

ext/opcache/jit/zend_jit.c

@@ -115,12 +115,48 @@ static int zend_jit_vm_kind = 0;
 static bool zend_write_protect = true;
 #endif
 
+/**
+ * Start of the shared memory area to contain JIT machine code.  Call
+ * zend_jit_unprotect() before writing to it, and call
+ * zend_jit_protect() when done.
+ *
+ * #dasmn_end is the end of the area and #dasm_ptr points to the end
+ * of the portion that is really used currently.
+ *
+ * This area is allocated during startup and is never changed.
+ * Allocations are linear by incrementing #dasm_ptr.
+ */
 static void *dasm_buf = NULL;
+
+/**
+ * End of the shared memory area to contain JIT machine code.
+ */
 static void *dasm_end = NULL;
+
+/**
+ * Pointer to pointer to end of the used portion of the shared memory
+ * area to contain JIT machine code.
+ *
+ * This "pointer to pointer" points to inside the shared memory area,
+ * because it needs to be shared across all processes/threads.  All
+ * accesses to the pointed-to pointer need to be protected using
+ * zend_shared_alloc_lock().
+ *
+ * Additionally, dasm_ptr[1] contains a pointer to the end of the
+ * stubs and veneers.  This is used by zend_jit_restart() to free all
+ * JIT-generated functions, but keep those stubs and veneers.
+ */
 static void **dasm_ptr = NULL;
 
+/**
+ * The total size of the #dasm_buf, including the trailer which
+ * #dasm_ptr points to (after #dasm_end).
+ */
 static size_t dasm_size = 0;
 
+/**
+ * Counter for checking the opcache.jit_bisect_limit setting.
+ */
 static zend_long jit_bisect_pos = 0;
 
 static const void *zend_jit_runtime_jit_handler = NULL;
@@ -805,6 +841,10 @@ ZEND_EXT_API void zend_jit_status(zval *ret)
 	add_assoc_zval(ret, "jit", &stats);
 }
 
+/**
+ * Generate a name for a JIT-generated native function (for the
+ * disassembler and for external debuggers/profilers/tracers).
+ */
 static zend_string *zend_jit_func_name(const zend_op_array *op_array)
 {
 	smart_str buf = {0};
@@ -2677,6 +2717,10 @@ static bool zend_jit_supported_binary_op(zend_uchar op, uint32_t op1_info, uint3
 	}
 }
 
+/**
+ * Caller must have called zend_shared_alloc_lock() and
+ * zend_jit_unprotect().
+ */
 static int zend_jit(const zend_op_array *op_array, zend_ssa *ssa, const zend_op *rt_opline)
 {
 	int b, i, end;
@@ -4717,6 +4761,9 @@ static void zend_jit_init_handlers(void)
 	}
 }
 
+/**
+ * Generate all JIT stub functions.
+ */
 static bool zend_jit_make_stubs(void)
 {
 	dasm_State* dasm_state = NULL;

ext/opcache/jit/zend_jit.h

@@ -119,6 +119,10 @@ typedef struct _zend_jit_globals {
 
 	zend_sym_node *symbols;            /* symbols for disassembler */
 
+	/**
+	 * True while zend_jit_trace_execute() runs, to avoid
+	 * recursively calling it twice.
+	 */
 	bool tracing;
 
 	zend_jit_trace_rec *current_trace;
@@ -140,10 +144,36 @@ extern int jit_globals_id;
 extern zend_jit_globals jit_globals;
 #endif
 
+/**
+ * Activate the JIT on the given #zend_op_array.
+ *
+ * @return SUCCESS or FAILURE
+ */
 ZEND_EXT_API int  zend_jit_op_array(zend_op_array *op_array, zend_script *script);
+
+/**
+ * Activate the JIT on the given #zend_script.
+ *
+ * @return SUCCESS or FAILURE
+ */
 ZEND_EXT_API int  zend_jit_script(zend_script *script);
+
+/**
+ * Make the JIT machine code area (i.e. #dasm_buf) writable (but not
+ * executable).  Call this before generating new machine code.  Call
+ * zend_jit_protect() when done.
+ *
+ * (These write/execute permissions affect only the current process.)
+ */
 ZEND_EXT_API void zend_jit_unprotect(void);
+
+/**
+ * Make the JIT machine code area (i.e. #dasm_buf) executable (but not
+ * writable).  Call this after generating new machine code to undo the
+ * effect of zend_jit_unprotect().
+ */
 ZEND_EXT_API void zend_jit_protect(void);
+
 ZEND_EXT_API void zend_jit_init(void);
 ZEND_EXT_API int  zend_jit_config(zend_string *jit_options, int stage);
 ZEND_EXT_API int  zend_jit_debug_config(zend_long old_val, zend_long new_val, int stage);

ext/opcache/jit/zend_jit_internal.h

@@ -219,8 +219,18 @@ static zend_always_inline bool zend_jit_same_addr(zend_jit_addr addr1, zend_jit_
 	return 0;
 }
 
+/**
+ * #ZEND_FUNC_INFO for functions handled by the JIT with trigger
+ * #ZEND_JIT_ON_FIRST_EXEC or #ZEND_JIT_ON_PROF_REQUEST.  The handler
+ * #override is zend_jit_runtime_jit_handler().
+ */
 typedef struct _zend_jit_op_array_extension {
 	zend_func_info func_info;
+
+	/**
+	 * The original opcode handler, just in case we need to
+	 * restore it.
+	 */
 	const void *orig_handler;
 } zend_jit_op_array_extension;
 
@@ -252,9 +262,24 @@ static zend_always_inline zend_long zend_jit_hash(const void *ptr)
 
 void ZEND_FASTCALL zend_jit_hot_func(zend_execute_data *execute_data, const zend_op *opline);
 
+/**
+ * #ZEND_FUNC_INFO for functions being handled by the JIT with trigger
+ * #ZEND_JIT_ON_HOT_COUNTERS.  The handler override is
+ * #zend_jit_func_hot_counter_handler().
+ */
 typedef struct _zend_jit_op_array_hot_extension {
 	zend_func_info func_info;
+
+	/**
+	 * Pointer to the counter.  Points to inside global variable
+	 * #zend_jit_hot_counters.
+	 */
 	int16_t    *counter;
+
+	/**
+	 * The original handler for each opline, just in case we need
+	 * to restore it.
+	 */
 	const void *orig_handlers[1];
 } zend_jit_op_array_hot_extension;
 
@@ -392,10 +417,29 @@ typedef enum _zend_jit_trace_stop {
 #define ZEND_JIT_TRACE_START_RETURN (1<<2)
 #define ZEND_JIT_TRACE_START_SIDE   (1<<3) /* used for side traces */
 
+/**
+ * Was this opline already processed by the JIT?  This is used to skip
+ * further JIT calls.
+ */
 #define ZEND_JIT_TRACE_JITED        (1<<4)
+
+/**
+ * Was this opline blacklisted by the JIT?  Blacklisted oplines will
+ * never be inspected again by the JIT.
+ */
 #define ZEND_JIT_TRACE_BLACKLISTED  (1<<5)
+
+/**
+ * Is this opline supported by the JIT?  This is determined by
+ * zend_jit_trace_supported().
+ */
 #define ZEND_JIT_TRACE_UNSUPPORTED  (1<<6)
 
+/**
+ * Not an actual trace_flag; just a descriptive macro indicating the
+ * absence of #ZEND_JIT_TRACE_UNSUPPORTED for the
+ * zend_jit_trace_supported() return value.
+ */
 #define ZEND_JIT_TRACE_SUPPORTED    0
 
 #define ZEND_JIT_EXIT_JITED         (1<<0)
@@ -410,20 +454,47 @@ typedef enum _zend_jit_trace_stop {
 #define ZEND_JIT_EXIT_METHOD_CALL   (1<<9) /* exit because of polymorphic INIT_METHOD_CALL call */
 #define ZEND_JIT_EXIT_INVALIDATE    (1<<10) /* invalidate current trace */
 
+/**
+ * Per-opline information for #zend_jit_op_array_trace_extension.
+ */
 typedef union _zend_op_trace_info {
 	zend_op dummy; /* the size of this structure must be the same as zend_op */
 	struct {
+		/**
+		 * The original opcode handler, just in case we need
+		 * to restore it.
+		 */
 		const void *orig_handler;
 		const void *call_handler;
+
+		/**
+		 * Pointer to the counter.  Points to inside global variable
+		 * #zend_jit_hot_counters.
+		 */
 		int16_t    *counter;
+
+		/**
+		 * Bit mask of the ZEND_JIT_TRACE_* flags.
+		 */
 		uint8_t     trace_flags;
 	};
 } zend_op_trace_info;
 
+/**
+ * #ZEND_FUNC_INFO for functions handled by the JIT with trigger
+ * #ZEND_JIT_ON_HOT_TRACE.  The handler override is
+ * #zend_jit_loop_trace_counter_handler() or
+ * #zend_jit_func_trace_counter_handler(), configured by
+ * #zend_jit_setup_hot_trace_counters().
+ */
 typedef struct _zend_jit_op_array_trace_extension {
 	zend_func_info func_info;
 	const zend_op_array *op_array;
 	size_t offset; /* offset from "zend_op" to corresponding "op_info" */
+
+	/**
+	 * Information for each opline.
+	 */
 	zend_op_trace_info trace_info[1];
 } zend_jit_op_array_trace_extension;
 

ext/opcache/jit/zend_jit_trace.c

@@ -3970,6 +3970,10 @@ static bool zend_jit_trace_next_is_send_result(const zend_op              *oplin
 	return false;
 }
 
+/**
+ * Caller must have called zend_shared_alloc_lock() and
+ * zend_jit_unprotect().
+ */
 static const void *zend_jit_trace(zend_jit_trace_rec *trace_buffer, uint32_t parent_trace, uint32_t exit_num)
 {
 	const void *handler = NULL;