From d1194ccc05e19c600d3b8acc03f14b803e87816a Mon Sep 17 00:00:00 2001 From: Jerome Laban Date: Thu, 9 Jan 2025 15:47:38 -0500 Subject: [PATCH] chore: Adjust docs --- doc/features-profiled-aot-validation.md | 71 +++++++++++++++++++ doc/runtime-execution-modes.md | 19 ++--- .../build/Uno.Wasm.Bootstrap.targets | 1 - 3 files changed, 75 insertions(+), 16 deletions(-) create mode 100644 doc/features-profiled-aot-validation.md diff --git a/doc/features-profiled-aot-validation.md b/doc/features-profiled-aot-validation.md new file mode 100644 index 000000000..36b4d30ba --- /dev/null +++ b/doc/features-profiled-aot-validation.md @@ -0,0 +1,71 @@ +--- +uid: Uno.Wasm.Bootstrap.ProfiledAOTValidation +--- + +# Troubleshooting Profiled AOT + +The .NET WebAssembly AOT compiler uses the AOT profile to determine which methods to compile to WebAssembly. In some cases, which may change depending on the .NET SDK version, selected methods may not be AOT compiled silently and may fall back to the interpreter. + +In such cases, the runtime performance of the app may become slower than expected. + +The bootstrapper provides a way to log the methods that were not AOT compiled, by setting the following property: + +```xml + + true + +``` + +## Assemblies filtering + +Assemblies may be skipped entirely from the validation using the following property: + +```xml + + $(WasmShellAOTProfileValidationExcludedAssemblies);System.* + +``` + +Entries in the `WasmShellAOTProfileValidationExcludedAssemblies` property are semi-colon separated regular expressions. + +## Methods filtering + +Specific methods may be skipped entirely from the validation using the following property: + +```xml + + $(WasmShellAOTProfileValidationExcludedMethods);MyNamespace.MyType.MyMethod.* + +``` + +Entries in the `WasmShellAOTProfileValidationExcludedMethods` property are semi-colon separated regular expressions. + +## Conditions when methods are not AOT compiled + +### Methods with try/finally blocks + +Methods with `try/finally` or `using()` blocks are not AOT compiled, because WebAssembly does not support the `finally` block in the same way as the .NET runtime. In this case, the .NET runtime switches to the interpreter. + +To reduce the impact of the interpreter, while still keep the try/finally block, moving the code from the inside of the `try` block to another method will improve performance. + +## Build Errors + +### UNOW0001 + +The following error may be raised: + +``` +UNOW0001: Method XXX from YYY has not been AOTed, even if present in the AOT profile. +``` + +This error is raised when the AOT profile requested a method to be AOT compiled, but was not. + +### UNOW0002 + +The following error may be raised: + +``` +UNOW0002: The method XXX from YYY is not present in the assembly. +``` + +This error generally means that there's a problem in the bootstrapper when matching methods from the compiled assemblies. If you find this specific error, please report it by opening an issue. diff --git a/doc/runtime-execution-modes.md b/doc/runtime-execution-modes.md index e220b410f..54e79e3ee 100644 --- a/doc/runtime-execution-modes.md +++ b/doc/runtime-execution-modes.md @@ -106,7 +106,10 @@ To create a profiled build: - Build you application again -Note that the AOT profile is a snapshot of the current set of assemblies and methods in your application. If that set changes significantly, you'll need to re-create the AOT profile to get optimal results. +> [!NOTE] +> AOT profile is a snapshot of the current set of assemblies and methods in your application. If that set changes significantly, you'll need to re-create the AOT profile to get optimal results. + +More information about [troubleshooting the Profiled AOT mode](xref:Uno.Wasm.Bootstrap.ProfiledAOTValidation) is available. ### AOT Profile method exclusion @@ -151,20 +154,6 @@ At this time, it is only possible to exclude assemblies from being compiled to W Adding assemblies to this list will exclude them from being compiled to WebAssembly. -### Troubleshooting Mixed AOT/Interpreter Mode - -When using the Mixed AOT/Interpreter mode, it is possible that some methods may not be compiled to WebAssembly for a variety of reasons. This can cause performance issues, as the interpreter is slower than the AOT-generated code. - -In order to determine which methods are still using the interpreter, you can use the following property: - -```xml - - true - -``` - -The logs from the AOT compiler can be found in [binlogs generated](https://aka.platform.uno/msbuild-troubleshoot) from the build. - ### Increasing the Initial Memory Size When building with Mixed AOT/Interpreter modes, the initial memory may need to be adjusted in the project configuration if the following error message appears: diff --git a/src/Uno.Wasm.Bootstrap/build/Uno.Wasm.Bootstrap.targets b/src/Uno.Wasm.Bootstrap/build/Uno.Wasm.Bootstrap.targets index 979dcd856..3d6a0b56d 100644 --- a/src/Uno.Wasm.Bootstrap/build/Uno.Wasm.Bootstrap.targets +++ b/src/Uno.Wasm.Bootstrap/build/Uno.Wasm.Bootstrap.targets @@ -23,7 +23,6 @@ $(WasmShellAOTProfileValidationExcludedAssemblies);System.* - $(WasmShellAOTProfileValidationExcludedAssemblies);System2.*