Add comments

Author: test@test.test

Zend/zend_builtin_functions.c

@@ -1860,7 +1860,8 @@ ZEND_API void zend_fetch_debug_backtrace(zval *return_value, int skip_last, int
 			}
 			zend_function *func = ZEND_FLF_FUNC(opline);
 			/* Assume frameless functions are not recursive with themselves.
-			 * This condition may be true when observers are enabled. */
+			 * This condition may be true when observers are enabled:
+			 * Observers will put a call frame on top of the frameless opcode. */
 			if (last_call && last_call->func == func) {
 				goto not_frameless_call;
 			}

Zend/zend_observer.c

@@ -199,6 +199,7 @@ ZEND_API void zend_observer_add_begin_handler(zend_function *function, zend_obse
 ZEND_API bool zend_observer_remove_begin_handler(zend_function *function, zend_observer_fcall_begin_handler begin, zend_observer_fcall_begin_handler *next) {
 	void **begin_handlers = (void **)ZEND_OBSERVER_DATA(function);
 	if (zend_observer_remove_handler(begin_handlers, begin, (void**)next)) {
+		// Ensure invariant: ZEND_OBSERVER_NONE_OBSERVED in begin_handlers if both are not observed
 		if (*begin_handlers == ZEND_OBSERVER_NOT_OBSERVED) {
 			size_t registered_observers = zend_observers_fcall_list.count;
 			if (begin_handlers[registered_observers] /* first end handler */ == ZEND_OBSERVER_NOT_OBSERVED) {
@@ -230,6 +231,7 @@ ZEND_API bool zend_observer_remove_end_handler(zend_function *function, zend_obs
 	void **begin_handlers = (void **)ZEND_OBSERVER_DATA(function);
 	void **end_handlers = begin_handlers + registered_observers;
 	if (zend_observer_remove_handler(end_handlers, end, (void**)next)) {
+		// Ensure invariant: ZEND_OBSERVER_NONE_OBSERVED in begin_handlers if both are not observed
 		if (*begin_handlers == ZEND_OBSERVER_NOT_OBSERVED && *end_handlers == ZEND_OBSERVER_NOT_OBSERVED) {
 			*begin_handlers = ZEND_OBSERVER_NONE_OBSERVED;
 		}

Zend/zend_observer.h

@@ -48,7 +48,9 @@ typedef struct _zend_observer_fcall_handlers {
 #define ZEND_OBSERVER_DATA(function) \
 	((zend_observer_fcall_begin_handler *)&ZEND_OP_ARRAY_EXTENSION((&(function)->common), ZEND_OBSERVER_HANDLE(function)))
 
-#define ZEND_OBSERVER_NONE_OBSERVED ((void *) 3) // Neither begin nor end handler present
+/* Neither begin nor end handler present. Needs to be set in the slot of the begin handler.
+ * Optimization reducing runtime checks. */
+#define ZEND_OBSERVER_NONE_OBSERVED ((void *) 3)
 
 /* Omit zend_observer_fcall_internal_function_extension check, they are set at the same time. */
 #define ZEND_OBSERVER_ENABLED (zend_observer_fcall_op_array_extension != -1)
@@ -84,12 +86,14 @@ ZEND_API void zend_observer_activate(void);
 ZEND_API void zend_observer_shutdown(void);
 
 ZEND_API void ZEND_FASTCALL zend_observer_fcall_begin(zend_execute_data *execute_data);
+/* prechecked: the call is actually observed. */
 ZEND_API void ZEND_FASTCALL zend_observer_fcall_begin_prechecked(zend_execute_data *execute_data, zend_observer_fcall_begin_handler *observer_data);
 
 static zend_always_inline bool zend_observer_handler_is_unobserved(zend_observer_fcall_begin_handler *handler) {
 	return *handler == ZEND_OBSERVER_NONE_OBSERVED;
 }
 
+/* Initial check for observers has not happened yet or no observers are installed. */
 static zend_always_inline bool zend_observer_fcall_has_no_observers(zend_execute_data *execute_data, bool allow_generator, zend_observer_fcall_begin_handler **handler) {
 	zend_function *function = EX(func);
 	void *ZEND_MAP_PTR(runtime_cache) = ZEND_MAP_PTR(function->common.run_time_cache);
@@ -106,6 +110,7 @@ static zend_always_inline bool zend_observer_fcall_has_no_observers(zend_execute
 	return zend_observer_handler_is_unobserved(*handler);
 }
 
+/* zend_observer_fcall_begin(), but with generator check inlined and optimized away. */
 static zend_always_inline void zend_observer_fcall_begin_specialized(zend_execute_data *execute_data, bool allow_generator) {
 	zend_observer_fcall_begin_handler *handler;
 	if (!zend_observer_fcall_has_no_observers(execute_data, allow_generator, &handler)) {
@@ -115,6 +120,7 @@ static zend_always_inline void zend_observer_fcall_begin_specialized(zend_execut
 
 ZEND_API void ZEND_FASTCALL zend_observer_generator_resume(zend_execute_data *execute_data);
 
+/* prechecked: the call is actually observed. */
 ZEND_API void ZEND_FASTCALL zend_observer_fcall_end_prechecked(zend_execute_data *execute_data, zval *return_value);
 static zend_always_inline void zend_observer_fcall_end(zend_execute_data *execute_data, zval *return_value) {
 	if (execute_data == EG(current_observed_frame)) {

ext/opcache/jit/zend_jit_helpers.c

@@ -3278,4 +3278,3 @@ static zend_string* ZEND_FASTCALL zend_jit_rope_end(zend_string **rope, uint32_t
 	*target = '\0';
 	return ret;
 }
-

ext/opcache/jit/zend_jit_ir.c

@@ -4485,6 +4485,7 @@ static struct jit_observer_fcall_is_unobserved_data jit_observer_fcall_is_unobse
 	if (func) {
 		ZEND_ASSERT((func->common.fn_flags & (ZEND_ACC_CALL_VIA_TRAMPOLINE | ZEND_ACC_GENERATOR)) == 0);
 	} else {
+		// JIT: if (function->common.fn_flags & (ZEND_ACC_CALL_VIA_TRAMPOLINE | ZEND_ACC_GENERATOR)) {
 		ZEND_ASSERT(rx != IR_UNUSED);
 		ir_ref if_trampoline_or_generator = ir_IF(ir_AND_U32(
 			ir_LOAD_U32(ir_ADD_OFFSET(func_ref, offsetof(zend_function, common.fn_flags))),
@@ -4494,13 +4495,15 @@ static struct jit_observer_fcall_is_unobserved_data jit_observer_fcall_is_unobse
 		ir_IF_FALSE(if_trampoline_or_generator);
 	}
 	if (func && (func->common.fn_flags & ZEND_ACC_CLOSURE) == 0 && ZEND_MAP_PTR_IS_OFFSET(func->common.run_time_cache)) {
+		// JIT: ZEND_MAP_PTR_GET_IMM(func->common.runtime_cache)
 		run_time_cache = ir_LOAD_A(ir_ADD_OFFSET(ir_LOAD_A(jit_CG(map_ptr_base)), (uintptr_t)ZEND_MAP_PTR(func->common.run_time_cache)));
 	} else {
 		ZEND_ASSERT(rx != IR_UNUSED);
 		// Closures may be duplicated and have a different runtime cache. Use the regular run_time_cache access pattern for these
 		if (func && ZEND_USER_CODE(func->type)) { // not a closure and definitely not an internal function
 			run_time_cache = ir_LOAD_A(jit_CALL(rx, run_time_cache));
 		} else {
+			// JIT: ZEND_MAP_PTR_GET(func->common.runtime_cache)
 			run_time_cache = ir_LOAD_A(ir_ADD_OFFSET(ir_LOAD_A(jit_CALL(rx, func)), offsetof(zend_op_array, run_time_cache__ptr)));
 			ir_ref if_odd = ir_IF(ir_AND_A(run_time_cache, ir_CONST_ADDR(1)));
 			ir_IF_TRUE(if_odd);
@@ -4510,6 +4513,7 @@ static struct jit_observer_fcall_is_unobserved_data jit_observer_fcall_is_unobse
 			ir_ref if_odd_end = ir_END();
 			ir_IF_FALSE(if_odd);
 
+			// JIT: if (func->common.runtime_cache != NULL) {
 			ir_ref if_rt_cache = ir_IF(ir_EQ(run_time_cache, IR_NULL));
 			ir_IF_TRUE(if_rt_cache);
 			ir_END_list(data.ir_end_inputs);
@@ -4519,12 +4523,13 @@ static struct jit_observer_fcall_is_unobserved_data jit_observer_fcall_is_unobse
 			run_time_cache = ir_PHI_2(IR_ADDR, run_time_cache, run_time_cache2);
 		}
 	}
+	// JIT: observer_handler = runtime_cache + ZEND_OBSERVER_HANDLE(function)
 	if (func) {
 		*observer_handler = ir_ADD_OFFSET(run_time_cache, ZEND_OBSERVER_HANDLE(func) * sizeof(void *));
 	} else {
-		// JIT: if (ZEND_USER_CODE(func->type)) {
+		// JIT: (func->type == ZEND_INTERNAL_FUNCTION ? zend_observer_fcall_internal_function_extension : zend_observer_fcall_op_array_extension) * sizeof(void *)
 		ir_ref tmp = ir_LOAD_U8(ir_ADD_OFFSET(func_ref, offsetof(zend_function, type)));
-		ir_ref if_internal_func = ir_IF(ir_AND_U8(tmp, ir_CONST_U8(1)));
+		ir_ref if_internal_func = ir_IF(ir_AND_U8(tmp, ir_CONST_U8(ZEND_INTERNAL_FUNCTION)));
 		ir_IF_TRUE(if_internal_func);
 
 		ir_ref observer_handler_internal = ir_ADD_OFFSET(run_time_cache, zend_observer_fcall_internal_function_extension * sizeof(void *));
@@ -4538,11 +4543,13 @@ static struct jit_observer_fcall_is_unobserved_data jit_observer_fcall_is_unobse
 		*observer_handler = ir_PHI_2(IR_ADDR, observer_handler_internal, observer_handler_user);
 	}
 
+	// JIT: if (*observer_handler == ZEND_OBSERVER_NONE_OBSERVED) {
 	data.if_unobserved = ir_IF(ir_EQ(ir_LOAD_A(*observer_handler), ir_CONST_ADDR(ZEND_OBSERVER_NONE_OBSERVED)));
 	ir_IF_FALSE(data.if_unobserved);
 	return data;
 }
 
+/* For frameless the true branch of if_unobserved is used and this function not called. */
 static void jit_observer_fcall_is_unobserved_end(zend_jit_ctx *jit, struct jit_observer_fcall_is_unobserved_data *data) {
 	ir_END_list(data->ir_end_inputs);
 	ir_IF_TRUE(data->if_unobserved);
@@ -4555,6 +4562,7 @@ static void jit_observer_fcall_begin(zend_jit_ctx *jit, ir_ref rx, ir_ref observ
 }
 
 static void jit_observer_fcall_end(zend_jit_ctx *jit, ir_ref rx, ir_ref res_ref) {
+	// JIT: if (execute_data == EG(current_observed_frame)) {
 	ir_ref has_end_observer = ir_IF(ir_EQ(rx, ir_LOAD_A(jit_EG(current_observed_frame))));
 	ir_IF_TRUE(has_end_observer);
 	ir_CALL_2(IR_VOID, ir_CONST_FC_FUNC(zend_observer_fcall_end_prechecked),
@@ -17058,7 +17066,7 @@ static ir_ref jit_frameless_observer(zend_jit_ctx *jit, const zend_op *opline) {
 	// Not need for runtime cache or generator checks here, we just need if_unobserved
 	ir_ref if_unobserved = jit_observer_fcall_is_unobserved_start(jit, fbc, &observer_handler, IR_UNUSED, IR_UNUSED).if_unobserved;
 
-	// push call frame
+	// Call zend_frameless_observed_call for the main logic. 
 	if (GCC_GLOBAL_REGS) {
 		// FP register will point to the right place, but zend_frameless_observed_call needs IP to be also pointing to the precise opline.
 		ir_ref old_ip = ir_HARD_COPY_A(ir_RLOAD_A(ZREG_IP));
@@ -17150,7 +17158,6 @@ static void jit_frameless_icall2(zend_jit_ctx *jit, const zend_op *opline, uint3
 	zend_jit_addr res_addr = RES_ADDR();
 	zend_jit_addr op1_addr = OP1_ADDR();
 	zend_jit_addr op2_addr = OP2_ADDR();
-
 	ir_ref res_ref = jit_ZVAL_ADDR(jit, res_addr);
 	ir_ref op1_ref = jit_ZVAL_ADDR(jit, op1_addr);
 	ir_ref op2_ref = jit_ZVAL_ADDR(jit, op2_addr);
@@ -17210,7 +17217,6 @@ static void jit_frameless_icall3(zend_jit_ctx *jit, const zend_op *opline, uint3
 	zend_jit_addr op1_addr = OP1_ADDR();
 	zend_jit_addr op2_addr = OP2_ADDR();
 	zend_jit_addr op3_addr = OP1_DATA_ADDR();
-
 	ir_ref res_ref = jit_ZVAL_ADDR(jit, res_addr);
 	ir_ref op1_ref = jit_ZVAL_ADDR(jit, op1_addr);
 	ir_ref op2_ref = jit_ZVAL_ADDR(jit, op2_addr);