From 8174d59c8f1eee79d6f053bb33a84bc15dc2c2d3 Mon Sep 17 00:00:00 2001 From: Guillaume Endignoux Date: Fri, 10 Jul 2020 09:38:45 +0200 Subject: [PATCH] Add documentation about development and testing. --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/README.md b/README.md index 6e68ba1..9385fbc 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,70 @@ All the required files can be downloaded from file, allowing you to easily make the modifications you need to further customize it. +## Development and testing + +### Printing panic messages to the console + +By default, libtock-rs blinks some LEDs when the userspace application panicks. +This is not always convenient as the panic message is lost. In order to enable +a custom panic handler that first writes the panic message via Tock's console +driver, before faulting the app, you can use the `--panic-console` flag of the +`deploy.py` script. + +```shell +# Example on Nordic nRF52840-DK board +./deploy.py --board=nrf52840dk --opensk --panic-console +``` + +### Debugging memory allocations + +You may want to track memory allocations to understand the heap usage of +OpenSK. This can be useful if you plan to port it to a board with fewer +available RAM for example. To do so, you can enable the `--debug-allocations` +flag of the `deploy.py` script. This enables a custom (userspace) allocator +that prints a message to the console for each allocation and deallocation +operation. + +The additional output looks like the following. + +``` +# Allocation of 256 byte(s), aligned on 1 byte(s). The allocated address is +# 0x2002401c. After this operation, 2 pointers have been allocated, totalling +# 384 bytes (the total heap usage may be larger, due to alignment and +# fragmentation of allocations within the heap). +alloc[256, 1] = 0x2002401c (2 ptrs, 384 bytes) +# Deallocation of 64 byte(s), aligned on 1 byte(s), from address 0x2002410c. +# After this operation, 1 pointers are allocated, totalling 512 bytes. +dealloc[64, 1] = 0x2002410c (1 ptrs, 512 bytes) +``` + +A tool is provided to analyze such reports, in `tools/heapviz`. This tool +parses the console output, identifies the lines corresponding to (de)allocation +operations, and first computes some statistics: + +- Address range used by the heap over this run of the program, +- Peak heap usage (how many useful bytes are allocated), +- Peak heap consumption (how many bytes are used by the heap, including + unavailable bytes between allocated blocks, due to alignment constraints and + memory fragmentation), +- Fragmentation overhead (difference between heap consumption and usage). + +Then, the `heapviz` tool displays an animated "movie" of the allocated bytes in +heap memory. Each frame in this "movie" shows bytes that are currently +allocated, that were allocated but are now freed, and that have never been +allocated. A new frame is generated for each (de)allocation operation. This tool +uses the `ncurses` library, that you may have to install beforehand. + +You can control the tool with the following parameters: +- `--logfile` (required) to provide the file which contains the console output + to parse, +- `--fps` (optional) to customize the number of frames per second in the movie + animation. + +```shell +cargo run --manifest-path tools/heapviz/Cargo.toml -- --logfile console.log --fps 50 +``` + ## Contributing See [Contributing.md](docs/contributing.md).