From 3d08cd842113f24b32ff8054876e5f765c073bd8 Mon Sep 17 00:00:00 2001 From: walon Date: Thu, 22 Aug 2024 22:57:39 +0800 Subject: [PATCH] =?UTF-8?q?HybridCLRSettings=E6=96=B0=E5=A2=9EenableProfil?= =?UTF-8?q?erInReleaseBuild=E5=92=8CenableStraceTraceInWebGLReleaseBuild?= =?UTF-8?q?=E9=80=89=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/basic/com.code-philosophy.hybridclr.md | 71 +++++++++++++++++++ docs/basic/workwithscriptlanguage.md | 1 + .../basic/com.code-philosophy.hybridclr.md | 62 ++++++++++++++++ .../current/basic/workwithscriptlanguage.md | 1 + 4 files changed, 135 insertions(+) diff --git a/docs/basic/com.code-philosophy.hybridclr.md b/docs/basic/com.code-philosophy.hybridclr.md index 0decc30da..8cbf8ffe8 100644 --- a/docs/basic/com.code-philosophy.hybridclr.md +++ b/docs/basic/com.code-philosophy.hybridclr.md @@ -281,6 +281,76 @@ preserveHotUpdateAssemblies字段用来满足这种需求。打包时不检查 运行菜单`HybridCLR/Generate/MethodBridge`时，生成工具递归分析AOT泛型实例化的迭代次数。含义与`maxGenericReferenceIteration`相似。 +### enableProfilerInReleaseBuild + +在v6.6.0及更早版本，以Release编译模式构建的游戏，运行游戏过程中进出解释器函数时会调用il2cpp_codegen_profiler_method_enter和il2cpp_codegen_profiler_method_exit，这增加了10-15%函数调用的开销。 + +自v6.7.0版本起，默认只有Debug编译模式构建时才会开启Profiler支持，Release模式下不再开启。如果想在Release模式下也开启Profiler支持，需要开启`enableProfilerInReleaseBuild`选项。 + +```cpp + +// Il2CppCompatibleDef.h + +#ifndef HYBRIDCLR_ENABLE_PROFILER +#define HYBRIDCLR_ENABLE_PROFILER (IL2CPP_ENABLE_PROFILER && (IL2CPP_DEBUG || HYBRIDCLR_ENABLE_PROFILER_IN_RELEASE_BUILD)) +#endif + +// Engine.cpp + InterpFrame* InterpFrameGroup::EnterFrameFromNative(const MethodInfo* method, StackObject* argBase) + { +#if HYBRIDCLR_ENABLE_PROFILER + il2cpp_codegen_profiler_method_enter(method); +#endif + // ... + } +``` + +:::warning +在HybridCLRSettings中修改此选项后，请运行`HybridCLR/Generate/Il2CppDef`或`HybridCLR/Generate/All`，并且清空构建缓存后重新构建，此选项才会生效。 +::: + +### enableStraceTraceInWebGLReleaseBuild + +在v6.6.0及更早版本中，以Release编译模式构建WebGL平台目标游戏，运行游戏过程中在进出解释器函数时会调用PUSH_STACK_FRAME和POP_STACK_FRAME。这个操作使得Debug.Log及抛出异常 +时可以正确打印解释器栈，但增加了10%左右函数调用的开销。 + +自v6.7.0版本起，默认只有WebGL平台的Debug模式才会开启这个StraceTrace，Release模式下不再开启。如果想在Release模式下也开启StraceTrace支持，需要开启`enableStraceTraceInWebGLReleaseBuild`选项。 + +```cpp + +// Engine.cpp +#if HYBRIDCLR_ENABLE_STRACKTRACE + +#define PUSH_STACK_FRAME(method, rawIp) do { \ + Il2CppStackFrameInfo stackFrameInfo = { method, rawIp }; \ + il2cpp::vm::StackTrace::PushFrame(stackFrameInfo); \ +} while(0) + +#define POP_STACK_FRAME() do { il2cpp::vm::StackTrace::PopFrame(); } while(0) + +#else +#define PUSH_STACK_FRAME(method, rawIp) +#define POP_STACK_FRAME() +#endif + + InterpFrame* InterpFrameGroup::EnterFrameFromInterpreter(const MethodInfo* method, StackObject* argBase) + { + // ... + PUSH_STACK_FRAME(method, (uintptr_t)newFrame); + return newFrame; + } + + InterpFrame* InterpFrameGroup::LeaveFrame() + { + POP_STACK_FRAME(); + // ... + } +``` + +:::warning +在HybridCLRSettings中修改此选项后，请运行`HybridCLR/Generate/Il2CppDef`或`HybridCLR/Generate/All`，并且清空构建缓存后重新构建，此选项才会生效。 +::: + ## Build Pipeline相关脚本 主要包含以下功能： @@ -374,6 +444,7 @@ Consistent要求与裁剪后的dll精确一致，而`generate/all`中生成的 用于为当前添加了 `[MonoPInvokeCallback]` 特性的函数预留指定数量的wrapper函数。在如下示例中，为LuaFunction签名的函数预留了10个wrapper函数。 ```csharp + [UnmanagedFunctionPointer(CallingConvention.Cdecl)] delegate int LuaFunction(IntPtr luaState); public class MonoPInvokeWrapperPreserves diff --git a/docs/basic/workwithscriptlanguage.md b/docs/basic/workwithscriptlanguage.md index 29b1d53f3..99760938d 100644 --- a/docs/basic/workwithscriptlanguage.md +++ b/docs/basic/workwithscriptlanguage.md @@ -38,6 +38,7 @@ HybridCLR对 `[MonoPInvokeCallbackAttribute]` 的支持跟原生完全相同。 ```csharp +[UnmanagedFunctionPointer(CallingConvention.Cdecl)] delegate int LuaFunction(IntPtr luaState); public class MonoPInvokeWrapperPreserves diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic/com.code-philosophy.hybridclr.md b/i18n/en/docusaurus-plugin-content-docs/current/basic/com.code-philosophy.hybridclr.md index 200f5bfd1..a6f65eba8 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic/com.code-philosophy.hybridclr.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic/com.code-philosophy.hybridclr.md @@ -279,6 +279,67 @@ Due to recursive generic instantiation, it can never be calculated. When running the menu `HybridCLR/Generate/MethodBridge`, the generation tool recursively analyzes the number of iterations of AOT generic instantiation. The meaning is similar to `maxGenericReferenceIteration`. +### enableProfilerInReleaseBuild + +In v6.6.0 and earlier versions, games built in Release compilation mode will call il2cpp_codegen_profiler_method_enter and il2cpp_codegen_profiler_method_exit when entering and exiting interpreter functions during game running, which increases the function call overhead by 10-15%. + +Since v6.7.0, Profiler support is enabled by default only when building in Debug compilation mode, and is no longer enabled in Release mode. If you want to enable Profiler support in Release mode, you need to enable the `enableProfilerInReleaseBuild` option. + +```cpp + // Il2CppCompatibleDef.h +#ifndef HYBRIDCLR_ENABLE_PROFILER +#define HYBRIDCLR_ENABLE_PROFILER (IL2CPP_ENABLE_PROFILER && (IL2CPP_DEBUG || HYBRIDCLR_ENABLE_PROFILER_IN_RELEASE_BUILD)) +#endif + +// Engine.cpp +InterpFrame* InterpFrameGroup::Enter FrameFromNative(const MethodInfo* method, StackObject* argBase) +{ +#if HYBRIDCLR_ENABLE_PROFILER + il2cpp_codegen_profiler_method_enter(method); +#endif +// ... +} +``` + +:::warning +After modifying this option in HybridCLRSettings, run `HybridCLR/Generate/Il2CppDef` or `HybridCLR/Generate/All`, and clear the build cache and rebuild it for this option to take effect. +::: + +### enableStraceTraceInWebGLReleaseBuild + +In v6.6.0 and earlier versions, when building a WebGL platform target game in Release compilation mode, PUSH_STACK_FRAME and POP_STACK_FRAME will be called when entering and exiting the interpreter function during the game. This operation allows the interpreter stack to be printed correctly when Debug.Log and throwing an exception, but it increases the function call overhead by about 10%. + +Starting from v6.7.0, this StraceTrace is enabled by default only in the Debug mode of the WebGL platform, and it is no longer enabled in Release mode. If you want to enable StraceTrace support in Release mode, you need to enable the `enableStraceTraceInWebGLReleaseBuild` option. + +```cpp + +// Engine.cpp + #if HYBRIDCLR_ENABLE_STRACKTRACE + #define PUSH_STACK_FRAME(method, rawIp) do { \ Il2CppStackFrameInfo stackFrameInfo = { method, rawIp }; \ il2cpp::vm::StackTrace::PushFrame(stackFrameInfo); \ } while(0) + #define POP_STACK_FRAME() do { il2cpp: :vm::StackTrace::PopFrame(); } while(0) +#else + +#define PUSH_STACK_FRAME(method, rawIp) #define POP_STACK_FRAME() +#endif + +InterpFrame* InterpFrameGroup::EnterFrameFromInterpreter(const MethodInfo* method, StackObject* argBase) +{ + // ... PUSH_STACK_FRAME(method, (uintptr_t)newFrame); + return newFrame; +} + +InterpFrame* InterpFrameGroup::LeaveFrame() +{ + POP_STACK_FRAME(); + // ... +} +``` + +:::warning +After modifying this option in HybridCLRSettings, please run `HybridCLR/Generate/Il2CppDef` or `HybridCLR/Generate/All`, clear the build cache and rebuild, so that this option will take effect. +::: + + ## Build Pipeline related scripts It mainly includes the following functions: @@ -376,6 +437,7 @@ Therefore, if a function with the `[MonoPInvokeCallback]` feature is added in su It is used to reserve the specified number of wrapper functions for the functions currently added with the `[MonoPInvokeCallback]` feature. In the following example, 10 wrapper functions are reserved for functions signed by LuaFunction. ```csharp + [UnmanagedFunctionPointer(CallingConvention.Cdecl)] delegate int LuaFunction(IntPtr luaState); public class MonoPInvokeWrapperPreserves diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic/workwithscriptlanguage.md b/i18n/en/docusaurus-plugin-content-docs/current/basic/workwithscriptlanguage.md index a8f271293..d304183af 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic/workwithscriptlanguage.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic/workwithscriptlanguage.md @@ -37,6 +37,7 @@ As shown below, there are 10 wrappers of type `LuaFunction`, 101 wrappers of typ ```csharp +[UnmanagedFunctionPointer(CallingConvention.Cdecl)] delegate int LuaFunction(IntPtr luaState); public class MonoPInvokeWrapperPreserves