From 9f1ee73a42472cb7cc3e6bb788acb42702bf5bc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Fri, 11 Aug 2017 18:22:15 +0100 Subject: [PATCH] Improve documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add documentation with tips for debigging the startup and assembly loading - add links to the main readme of existing docs Signed-off-by: José Simões --- docs/README.md | 15 +++++++++++++++ docs/debugging-class-libraries.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/debugging-class-libraries.md diff --git a/docs/README.md b/docs/README.md index af9db6dd60..a2160c8a8b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,21 @@ - [Building **nanoFramework**](build-instructions.md) - [Debug with VS Code](vscode-debug-instructions.md) +- [Debug class libraries and startup](debugging-class-libraries.md) ## CLR core and support components - [Wire Protocol](wire-protocol.md) + +## Architecture + +- [Class Libraries](architecture/class-libraries.md) +- [Date and Time](architecture/date-and-time.md) +- [Application deployment](architecture/deployment.md) +- [Thread execution](architecture/thread-execution.md) + + +## ChibiOS HAL + +- [CLR Managed heap definition](ChibiOS HAL/clr-managed-heap.md) +- [USB configuration of Virtual COM port (CDC)](ChibiOS HAL/config-usb-virtual-com-port.md) +- [GCC linker script for ChibiOS boards](ChibiOS HAL/gcc-linker-script.md) diff --git a/docs/debugging-class-libraries.md b/docs/debugging-class-libraries.md new file mode 100644 index 0000000000..1f198347f7 --- /dev/null +++ b/docs/debugging-class-libraries.md @@ -0,0 +1,29 @@ +# Guidelines for debugging **nanoFramework** class libraries native code + +**About this document** + +This document provides guidelines useful when debugging class libraries native code. +It doesn't care if the developer is using VS Code or other IDE. + + +## How does an assembly load successfully? + +The assemblies with the class libraries and the managed application are loaded at startup from the deployment area in the FLASH memory. +When the `LoadDeploymentAssemblies()` is called the deployment area is sweep and all 'candidate' assemblies are validated. The validation steps are basically checking the start token, a valid header and the CRC32 of the full assembly. Only the ones that pass the complete set of validation make it to the assembly collection. + +After this step a call to `g_CLR_RT_TypeSystem.ResolveAll()` happens in which the type system tries to resolve all the assemblies. This means that all the required types and methods (from all the assemblies) are available and in the correct versions. + +Next comes the `g_CLR_RT_TypeSystem.PrepareForExecution()` which is only called if all the assemblies could be resolved along with the required types. + + +## Starting the execution engine + +The managed application actually starts to be executed with a call to `g_CLR_RT_ExecutionEngine.Execute()`. +As long the managed code is being executed this will never exit. +When the execution ends, because of a serious exception or because there is no managed application to execute the code flow hits the `CLR_EE_DBG_IS( RebootPending )` line (bellow the the call to the execution engine call). + + +## Summarizing + +So, by setting break points at, or after, the above calls one can understand and perform a check if the assemblies are being loaded and/or the managed application being executed. +If something goes wrong (for instance) with an assembly failing to load the developer has to go deeper in order to find out the root cause. But that's a matter for another piece of documentation.