Embedding QuickJS in your Projects

QuickJS is small and embeddable Javascript engine made by the famous Fabrice Bellard, it supports ES2020 specifications and made available under MIT license.

You might have read about my porting of his TinyEMU to ESP32 which could boot linux.

During my hunt for scripting engine that can be integrated into a new embedded product I've encountered MicroPython and QuickJS, while the documentation is a bit lacking, the code was much easier to read and compile, there are no complicated build scripts and it was basically dropping the last version in the lib folder and selecting which files should be compiled with library.json

Once the library was compiled, integrating it into my demo was very easy and supporting multiple execution contexts is very easy since its not sharing context and variables.

1 2 3 4 5 6 7 8 9 10 11 12 13 14

JSRuntime *rt = JS_NewRuntime(); if (!rt) { fprintf(stderr, "qjs: cannot allocate JS runtime\n"); } JS_SetMemoryLimit(rt, 80 * 1024); JS_SetMaxStackSize(rt, 10 * 1024); JSContext *ctx = JS_NewContext(rt); if (!ctx) { fprintf(stderr, "qjs: cannot allocate JS context\n"); }

The JSRuntime object represents the JavaScript engine, its responsible for memory allocation and C function calls. 

The JSContext object respresents the execution context where JavaScript functions and variables live.

Our demo workload

1 2 3

function transform(a, b) { return (a ^ 2 / Math.sin(2 * Math.PI / b)) - a / 2; }

We'll eval(uate) the function to get it into the context

1 2 3 4 5 6

const char *expr = "function transform(a,b){return (a^2/Math.sin(2*Math.PI/b))-a/2;}"; JSValue r = JS_Eval(ctx, expr, strlen(expr), "", 0); if (JS_IsException(r)) { printf("Error evaluating script\r\n"); }

And once we have the function in the context, we can get it by name and execute it with the a and b arguments

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

JSValue args[2]; args[0] = JS_NewFloat64(ctx, (double)i); args[1] = JS_NewFloat64(ctx, (double)i); JSValue res = JS_Call(ctx, func, global, 2, args); if (JS_IsException(res)) { printf("Error Executing transform\r\n"); } if (!JS_IsNumber(res)) { printf("is not number!\r\n"); } double result; if (JS_ToFloat64(ctx, &result, res)) { printf("error parsing number\r\n"); }

Summary

QuickJS looks very interesting as a JavaScript runtime engine, its relatively fast and the code seems self explanatory. It has been embedded in rust, as an isolated VM in Node JS and more.

While QuickJS is different from MicroPython, its faster to execute the same workload, it was more readable for me and faster to setup and compile, one of the major drawbacks is that if you want to use it as an alternative to MicroPython, you'll need to implement your own hardware drivers for SPI, I2C etc'.

You may find Carlos Alberto's Writing native modules in C for QuickJS engine useful.

Lastly, I've attempted to modify QuickJS to use floats instead of double since ESP32 FPU is single precision only, it will probably make it non-standard and fail many JavaScript standard tests but I've included it here anyway.

In my particular use case:

• x64 native vs QuickJS slowdown is about x9 times
• ESP32 native vs QuickJS slowdown is about x63 times
• ESP32 native vs QuickJS using float slowdown is about x25 times

You may view the official benchmarks here.

As always you can find the fruits of my labor at my GitHub account.

Read More

Tags: esp32, javascript, platformio, quickjs, scripting

Dror Gluska November 23, 2022  1 comment

Embedding Micropython in your Projects

MicroPython is a python implementation for microcontrollers and other low resource requirement implementation which can make it perfect for embedding without significantly increasing your delivered executable or firmware.

The project was created by Damien George at 2013 and has since grown and improved and even earned its place at OBCPs and is planned to reach space on board Euclid at 2023 as well as integrating into RODOS.

If it can work for spacecrafts, why shouldn't it work for you?

My original goal was to use MicroPython as an expression evaluation and enrichment engine for embedded data acquisition, however, I've found that the complexity of actually integrating it into a PlatformIO project was too big to miss on an opportunity to make it an easier task.

MicroPython Project Structure

After downloading the release (in my case 1.19), the archive has the following interesting folders:

py - contains MicroPython VM

ports - contains platform specific implementation and support functionality

extmod - extra modules

I was a bit naïve, so I've decided to build all files in py and windows port but there were so many errors I've realized its probably the wrong approach.

I've started digging in the makefiles since I wasn't sure what to look for, the instructions were pretty standard. but once you start looking in the makefiles, there's plenty going on there.

But there's no easy way to use that in PlatformIO as far as I know, so I went ahead and checked what was executing when and why, there's some documentation about qstr but there are also modules and version info, some of it to optimize the build and prevent a rebuild of the whole qstr header.

I wanted to avoid precompiling the headers and keeping them in git, since it will complicate version updates, build flags changes and built-in module changes, there have been similar approached with NXP port but I wanted it to be more robust and developer friendly.

I've decided to keep it short and just write a script that executes all the scripts on the appropriate files and folders and after some fiddling with the list of sources that needed to be compiled, the project compiled on both Windows and ESP32.

Building MicroPython on PlatformIO

PlatformIO uses scons to build, scons keeps a series of flags and dictionaries of the files to build and uses the compiler so actually generate the executable and firmware. Though in ESP32 case it uses cmake as well to build esp-idf.

PlatformIO also added hooks before and after building the project, allowing extensibility through scripting, in this case I've chosen to execute a script in the library so its always executing before the build.

I went ahead and made the build system a bit more flexible by allowing different sources and includes to be used for different platforms. You may want to look in build_settings.py to see how.

In short, the script determines the framework and platform and reads the library.json->build->environments, it appends all the sources and flags from common and then looks for a specific platform and appends the sources and flags from there as well.

I then read list of file selectors (SRC_FILTER) and build a list of source files so it can be used to generate the headers with generate_strings.py

• makeversionhdr - generates the mpversion.h
• makeqstrdefs pp - generates qstr.i.last from a batch of source files and headers
• makeqstrdefs split qstr - extracts a list of qstr from the last qstr.i.last, this may run a few times with a few different qstr.i.last
• makeqstrdefs split module - extracts a list of modules from the last qstr.i.last, this may run a few times with a few different qstr.i.last
• makeqstrdefs cat module - generates a collected file from the splitted modle files
• makeqstrdefs cat qstr - generates a collected file from the splitted qstr files
• makemoduledefs - generates moduledefs.h from the collected module file
• qstrdefs_preprocessed - precompiles strings into preprocessed.h
• qstrdefs_generated - generates generated.h from preprocessed.h

Once this process is done, the qstr and modules dictionaries are ready to be compiled into the library.

Generic Port

MicroPython uses a set of configuration header files and functions so it will be portable and work across multiple environments but to run it without any special hardware modules requires very little configuration.

I've created a "generic" port:

• mimimal gc
• unhandled exceptions are sent to stderr
• all filesystem operations are throwing errors
• all python's print are sent to stdout, stdin does nothing

Initialization

To initialize micropython we need a stack and heap and then initialize the stack, the stack limit, the garbage collector which also handles allocations and finally MicroPython.

Please note there are two stack limits, one for python (pystack) and one for the OS limit, which is used to limit the recursion the MicroPython engine uses - it should be less than the OS stack size, looking at MicroPython's code, its about 2k less than the OS stack.

1 2 3 4 5 6 7 8 9 10 11 12

instance->stack = (uint8_t *)malloc(instance->stack_size); instance->heap = (uint8_t *)malloc(instance->heap_size); mp_stack_ctrl_init(); mp_stack_set_limit(instance->stack_size); // Initialize heap gc_init(instance->heap, instance->heap + instance->heap_size); mp_pystack_init(instance->stack, instance->stack + instance->stack_size); // Initialize interpreter mp_init();

NLR

NLR stands for non-local return, which is how MicroPython handles exceptions in C, using a stack of jumps.

1 2 3 4 5 6 7 8 9 10 11 12

nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { mp_obj_t retval = mp_call_function_n_kw(func, argc, 0, argv); nlr_pop(); return retval; } else { mp_obj_print_exception(&mp_stderr_print, MP_OBJ_FROM_PTR(nlr.ret_val)); return (mp_obj_t)nlr.ret_val; }

1-2 define a temporary nlr buffer and push the current context.

4 execute a MicroPython function

5 pop for successful execution

8 in case there's an error between lines 3-7 the IP will jump to line 9.

10 display the error

Executing Scripts and Calling Functions

While it seems very similar in python, there is a difference, executing a script might have an output, it is not captured, so there is no way to use that output unless you plan on capturing and parsing Python's print.

This is why I chose to split that functionality into two parts, the first part executes a script, creating functions / variables on the local/global scope and the second part executes a function and uses its return value.

For executing scripts, MicroPython needs to parse the string and compile it into MicroPython bytecode and execute it. So once the script is in the context, we can use the module for looking up the function name and execute it.

We'll pass the following script to the compilation code

1 2 3

import math; def transform(a,b): return (a**2/math.sin(2*math.pi/b))-a/2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { qstr src_name = 1 /*MP_QSTR_*/; mp_lexer_t *lex = mp_lexer_new_from_str_len(src_name, fragment, strlen(fragment), false); qstr source_name = lex->source_name; mp_parse_tree_t pt = mp_parse(lex, MP_PARSE_FILE_INPUT); mp_obj_t module_fun = mp_compile(&pt, source_name, false); mp_call_function_0(module_fun); nlr_pop(); return NULL; } else { mp_obj_print_exception(&mp_stderr_print, MP_OBJ_FROM_PTR(nlr.ret_val)); return (mp_obj_t)nlr.ret_val; }

And now we can lookup transform (line 1) function and call it (line 10)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

mp_obj_t transform_function = mp_obj_dict_get(mp_locals_get(), mp_obj_new_str("transform", strlen("transform"))); mp_obj_t args[2]; args[0] = mp_obj_new_float(1); args[1] = mp_obj_new_float(2); nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { mp_obj_t retval = mp_call_function_n_kw(transform_function, argc, 0, argv); nlr_pop(); return retval; } else { mp_obj_print_exception(&mp_stderr_print, MP_OBJ_FROM_PTR(nlr.ret_val)); return (mp_obj_t)nlr.ret_val; }

Summary

MicroPython has advanced light years since its first inception and it is very capable and enables rapid prototyping and even usable for space applications. That being said, its still a bit slow to function as a generic programming language and more appropriate for coordinating calls to C functions.

The other thing I've found lacking is documentation, to write this demo I needed to go over multiple sources and demos, look for forks, pull requests and read a lot of source code, its still not 100% clear to me what all the defines are doing exactly and what to expect in terms of performance impact for each of them.

In my particular use case:

• x64 native vs MicroPython slowdown is about x16 times.
• ESP32 native vs MicroPython slowdown is about x100 times.

For the curious minds of where did the CPU spent its time, I'm very happy to have found Very Sleepy

As always you can find the fruits of my labor at my GitHub account.

Further reading:

• https://www.snaums.de/static/resources/2017-12-mpy.pdf
• https://micropython.org/resources/publish/Spacebel_MicroPythonOBCP_Dasia2018_Paper.pdf
• https://mediatum.ub.tum.de/doc/1519584/document.pdf
• https://indico.esa.int/event/269/contributions/4156/attachments/3161/4272/Presentation_-_Qualification_of_a_Virtual_Machine_an_OBCP_Engine_Based_on_MicroPython.pdf

Read More

Tags: micropython, platformio, scripting, very sleepy

Dror Gluska November 17, 2022  No comment

LVGL ESP32 and Desktop Development Walkthrough

UI for Embedded is always a hassle, find the right MCU, find the right Display, connect the right wires and that's even before writing the first line of code that actually shows anything on the display, drivers, graphic libraries and input libraries can be a pain to use, not to mention a pain to write.

Fortunately, we no longer live in a cave, we have PlatformIO, LVGL and drivers for many of the LCDs available for commercial use and maker community.

I propose a way to start quickly so we can save some of the bring up time for a new setup, configuration is done in the kconfig way, so its really go through the menu, change a setting, compile and test.

There is a getting started for ESP32 on LVGL github, Gabor Kiss-Vamosi wrote a tutorial and we have some documentation, Espressif event got an example repository, but I've discovered my way is a bit more flexible and easier to use once its set-up, since you can develop on the desktop (LVGL refers to it as Simulator) and don't have to upload each revision, plus you don't have to do it, just fork my project and you're good to go. In any case, the full instructions are below, so you can mix and match versions and for me it provided a pretty much consistent experience.

Hardware

There are many kits you can buy, each one with its own quirks but my goal was to test what I had and unfortunately I had none of the kits.

So I got out a perfboard, a few pin headers and a resistor (more on that later) and built my own. 

Please note that I have yet to test any of them, so do your own research before purchasing, the following are affiliate links.

ESP32-LCDKit

The ESP32-LCDKit looks like its the most versatile for Graphic development, the schematic is available and you can use which ever ESP32 you want (as long as its a 38 pins)

ESP-WROVER-KIT

Next in line is the ESP-WROVER-KIT, like the previous one, its schematics are also available, but one major drawback is that the kit does not include a touch screen, only a display so its less suitable for interactive UI.

ESP32-S2-Kaluga-1 Kit

Next in line from Espressif is the ESP32-S2-Kaluga-1 Kit, this kit is more versatile and according to the documentation it does have a 3.2" touch screen but it can also have an audio extension, a touch panel (not display, just a board with touch) and a camera module.

WT32-SC01

Last but not least, The WT32-SC01 seems like it has great potential for having all the hardware on a single board, mounting holes and capacitive touch screen, schematics and code samples are available.

Source Control

We can't really start a project without source control, how can we track changes? how can we go back to a stable state?

Atlassian has a great cheat sheet and there is built in support in Visual Studio Code. 

Lets initialize a new git repo:

git init

I also recommend committing each stage of your setup, it will help you to track changes and find out which code caused the change.

PlatformIO

PlatformIO is a development platform that enables writing code in multiple platforms while maintaining a consistent experience.

In this case, we'd like to initialize a new project:

pio init

LVGL

Now that we have an empty project, we'll need to add lvgl to it, so go ahead and extract latest release from https://github.com/lvgl/lvgl/releases into lib/lvgl.

Than take library.json from our example project and copy it into lib/lvgl root, what this library.json file actually does is allow you to select which parts of lvgl gets compiled.

Native / Desktop Drivers

There are multiple ways of working with LVGL but one of the better ways is getting your UI completely disconnected from your business logic and running the UI on your PC, this way its easier to design, debug and verify, on top of it, you can use LVGL's snapshot API to automatically validate your views so they can stay consistent no matter which changes you do. 

The way LVGL works on the desktop is by using SDL2.

So first we'll extract the latest source from https://github.com/lvgl/lv_drivers into lib/lv_drivers

Then we'll copy lv_drv_conf_template.h to include/native/lv_drv_conf.h and enable the file (change #if 0 to 1)

Then we'll modify library.json to include SDL dependency, otherwise PlatformIO dependency detection won't work properly due to the way SDL is included through a #DEFINE macro.

    "dependencies":[

        {

            "name":"SDL2"

        }

    ],

And modify library.json to remove an incompatible source file:

    "build": {

        "srcFilter" : [

            "-<display/ILI9341.c>"

        ]

    }

Lastly, we'll update include/native/lv_drv_conf.h in appropriate place and copy our menu configuration keys to SDL configuration keys, otherwise our menu won't control SDL (Desktop) display properly.

    #include "lvgl_native_drivers.h"

    #define USE_SDL 1

    #define SDL_HOR_RES     CONFIG_SDL_HOR_RES

    #define SDL_VER_RES     CONFIG_SDL_VER_RES

Since our native environment will need to use SDL, we should also add SDL2 to lib, there are different libraries for different environments, such as Windows and Linux.

In Windows, we'll need to download SDL for mingw, extract it into our lib folder and copy library.json from this project to your SDL library

In Ubuntu its as simple as

apt-get install libsdl2-2.0 libsdl2-dev

Lastly we need to add our native drivers configuration script run_lvgl_native_drivers_kconfig.py and configure it with custom_lvgl_native_drivers_kconfig_save_settings and custom_lvgl_native_drivers_kconfig_output_header configuration keys

ESP32 Hardware Display Drivers

Now that we have our desktop setup, we also want our hardware setup so we can flash our device and see how our design looks on the real hardware.

Please note that the drivers are not always configured ideally, if the colors seems a bit off, you should read the datasheet and make sure everything is configured properly.

Lets start by extracting the latest source from https://github.com/lvgl/lvgl_esp32_drivers into lib/lvgl_esp32_drivers and copy the library.json from this project

Some drivers are not working properly with PlatformIO's scons configuration and needs to be enabled/disabled on a per-file basis, you should look in library.json as an example.

Another thing we want to tell our library.json is which framework it should work with, for example, in our setup we have native and esp32 environments and the esp32 drivers should not be compiled on the native environment since none of Espressif's libraries exist or even needed for desktops.

Then we'll modify lvgl_helper.c to include "lv_conf.h" right after "sdkconfig.h", the vanilla setup assumes your lvgl is part of esp32 components which can make desktop configuration a problem.

    #include "sdkconfig.h"

    #include "lv_conf.h"

Then we need to add lvgl kconfig script (run_lvgl_kconfig.py) and set  its configuration  custom_lvgl_kconfig_save_settings, custom_lvgl_kconfig_output_header,  custom_lvgl_kconfig_include_headers configuration sections to each relevant environment in platformio.ini

And add lvgl esp32 drivers kconfig script (run_lvgl_esp32_drivers_kconfig.py) and custom_lvgl_esp32_drivers_kconfig_save_settings, custom_lvgl_esp32_drivers_kconfig_output_header configuration section to each relevant environment in platformio.ini

These two scripts and their setting enables platformio.ini to use the target scripts for easy configuration. To see which scripts are installed for each environment:

> pio run --list-targets

Environment    Group     Name                        Title                        Description

-------------  --------  --------------------------  ---------------------------  -----------------------------------

native         Custom    lvgl-config                 lvgl-config                  Executes lvgl config

native         Custom    lvgl-esp32-drivers-config   lvgl-esp32-drivers-config    Executes lvgl esp32 drivers config

native         Custom    lvgl-native-drivers-config  lvgl-native-drivers-config   Executes lvgl native drivers config

esp32          Custom    lvgl-config                 lvgl-config                  Executes lvgl config

esp32          Custom    lvgl-esp32-drivers-config   lvgl-esp32-drivers-config    Executes lvgl esp32 drivers config

esp32          Custom    lvgl-native-drivers-config  lvgl-native-drivers-config   Executes lvgl native drivers config

esp32          Platform  buildfs                     Build Filesystem Image

esp32          Platform  erase                       Erase Flash

esp32          Platform  menuconfig                  Run Menuconfig

esp32          Platform  size                        Program Size                 Calculate program size

esp32          Platform  upload                      Upload

esp32          Platform  uploadfs                    Upload Filesystem Image

esp32          Platform  uploadfsota                 Upload Filesystem Image OTA

Now that we've assigned each configuration output to a different folder under include, we should tell platformio to include headers from these folders so each environment will get a different set of configuration files.

LVGL Configuration

LVGL uses configuration files separate from the driver configuration files to configure some aspects of it, such as fonts, widgets, colors and layouts, but we need to tell it where to take the configuration from.

We do it by adding these flags to build_flags for relevant environments in platformio.ini:

    -DLV_LVGL_H_INCLUDE_SIMPLE

    -DLV_CONF_INCLUDE_SIMPLE

    -DLV_CONF_PATH=lv_conf.h

Environment Hardware Abstraction

There is a small library in the demo project called lvgl_hal, it contains the setup for the drivers, obviously different from native to ESP32, you may need to modify it to your environment / programming.

So copy lvgl_hal to your lib folder.

Changing Configuration

Lets start with ESP32 configuration, LVGL can run lean or resource intensive, larger buffers may help with rendering speed, caching images and data can also help, my usual setup is 240Mhz CPU speed and 80Mhz PSRAM speed. 

To make these configuration, you'll need to modify ESP32 configuration by running:

pio run -e esp32 -t menuconfig

We can configure ESP32 drivers:

pio run -e esp32 -t lvgl-esp32-drivers-config

And native drivers, which at the time of this writing is only resolution:

pio run -e native -t lvgl-native-drivers-config

And lastly we'll want to configure our lvgl, using the same configuration for both desktop and embedded can help you to find bugs quicker.

pio run -e esp32 -t lvgl-config

pio run -e native -t lvgl-config

Runner

The runner library is intended as an abstraction of the main function, on a desktop its int main(argc,argv), on ESP32 its appmain() and on Arduino its setup() and loop(), instead of writing the same ifdefs everywhere, just copy the runner library, include it in your main file and use it:

MAIN(){

}

Unfortunately my ILI9488 is not configured properly (more on that later)

If you're looking for a solution to the ILI9488 configuration issue, you can read about it here.

Read More

Tags: esp32, ili9488, littlevgl, lvgl, platformio

Dror Gluska July 24, 2022  No comment

PlatformIO Menu Configuration Integration

One of the hurdles when building a custom library or software is how to allow the user to configure it. We can have a header file with comments and tell the user how to configure it but if multiple defines start to have dependencies or the value is more than true or false, there's a chance the user will get this wrong and the a whole class of issues is going to be opened and time is going to be wasted.

source

The linux kernel solved it with the Kconfig utility, which was reimplemented using the kconfiglib. fortunately its easier to install and use and the integration requires only menuconfig and genconfig utilities.

To implement it in our software we need to do the following:

KConfig file

write your configuration file, here's an example with one boolean and one string configuration values:

mainmenu "Sample configurable project using Kconfig"

config FOO
    bool "Foo module"
    help
        The infamous Foo module
config BAR
    string "Bar Value"
    help
        The Bar Value

platformio.ini

Once we have the configuration file we need to tell menuconfig and genconfig where the file is, where to save the configuration settings and where to generate the header file with the configuration values.

; menuconfig runner
extra_scripts = 
    scripts/run_menuconfig.py
; path to Kconfig file
custom_kconfig_config = scripts/configs/Kconfig
; configuration settings file
custom_kconfig_save_settings = include/custom_config.config
; configuration settings file and header file header comment
custom_kconfig_comment_header =
    File Header
    hello world
; output configuration header file
custom_kconfig_output_header = include/custom_config.h

All we need to do now is execute the runner

pio run -t kconfig

when we quit and save, menuconfig will generate the configuration setting file to custom_kconfig_save_settings:

#File Header
#hello world
CONFIG_FOO=y
CONFIG_BAR="hello world"

and then execute genconfig and generate the header file to custom_kconfig_output_header:

// File Header
// hello world
#define CONFIG_FOO 1
#define CONFIG_BAR "hello world"

and lastly, we can use the header file like any other header file and get our configuration from it:

#include <custom_config.h>
MAIN()
{
    printf("Program started!\r\n");
    printf("Bar Value %s\r\n", CONFIG_BAR);
}

Read More

Tags: genconfig, kconfig, menuconfig, platformio

Dror Gluska June 08, 2022  No comment

PlatformIO Dynamic Code Analysis and Coverage

Like static code analysis, dynamic code analysis provides another level of coding errors detection and can help diagnose memory access issues such as use-after-free or uninitialized read and even memory leaks and memory write overruns.

source

On top of that, we can write every line of code that has been used and later correlate that and say which lines were executed and which were not and that is the essence of code coverage. 

Code Coverage

A unit test is just code that executes your code, by executing your code and providing it with information it needs and checking its return values and side effects we can determine if your code does what it was designed to do.

Running unit tests is usually done by creating another executable or firmware that runs all your tests one by one and reports their status. 

Eventually, if this executable writes which lines were executed, a reporting tool can later read that data and cross reference it with the source code to produce statistics and reports.

To make it work, we need to disable optimizations and compile debug symbols, otherwise we'll get bad results if any. 

So first, we'll add the required flags to our environment in platformio.ini:

build_flags = -ggdb -lgcov -O0 --coverage

Now when we run tests, the coverage data will be written into the gcda and gcno files we can view it  with a VSCode Extension directly:

But it might not be enough, we can also view it in command line or even in CI so well need to build a report from it, we'll use gcovr do build a tracefile from it and since we have more than one test module, we'll want to merge all the tracefiles to a single report.

Lets start by adding our runner to platformio.ini:

extra_scripts = 
    scripts/run_gcovr.py

The runner hooks into the test executable generation and executes gcovr and generate a tracefile for each test executable.

When the tests are done, we can get the coverage info by running:

pio run -t gcovr

We can then browse the .reports/coverage.html

If you have other requirements from gcovr, there are many options for the output and you can use a configuration file to specify what you need.

Dr. Memory

By hooking into the PlatformIO testing mechanism and intercepting the compiled tests we can execute the tests under Dr. Memory's supervision and get a report of where exactly code was leaking or accessing memory it wasn't supposed to, it does require the developer to not leave dangling memory after tests so each malloc will need to be matched with free and every new will have to be delete(ed).

This step does not require any intervention from the user other than add run_drmemory.py to extra_scripts:

extra_scripts = 
    scripts/run_drmemory.py

Just note that Dr. Memory can do more than that, so its good to explore it further.

To sum things up, dynamic code analysis tools are essential to writing quality code with the added benefit of finding which parts of your code have leaks or not covered by enough tests.

Continue reading about static code analysis...

Read More

Tags: coverage, dr. memory, gcovr, platformio

Dror Gluska June 07, 2022  No comment

PlatformIO Static Code Analysis

Source

Writing code and testing it with unit and integration tests can provide high quality executable, however, it does not indicate if its a maintainable code, moreover code can have side effects when used outside its designed use, so in essence, tests pass, QA approved but then it gets in the field and crashes. 

One of the ways to make sure code is maintainable, understandable and quick to get into is code reviews, however, using style checks and static code analysis can help automate some of it before a human can review it.

Applications are like Swiss cheese, one tool can verify certain aspects of it but many tools can discover more possible issues.

Code Style 

Code style defines how a code looks like to the developer, it will most likely not affect how the code is run but it can affect how quickly a developer can understand what its doing.

clang-format

clang-format is a C++ code formatter and supports many formatting options that can help with readability and consistent source code format.

to install clang-format:

pip install clang-format

Once installed, we can generate a default clang-format configuration file and edit it if needed, clang-format defines a few standard styles: LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit

the following line will generate the configuration based on LLVM:

clang-format -style=LLVM -dump-config > .clang-format

For PlatformIO specific integration you can use my runner and execute it as follows:

pio run -t format

cpplint

cpplint is a tool that checks Google's C++ Style Guide, it can report the issues to command line or you can use the VSCode Extension and see the issues while writing code.

While the style guide is very strict, you can control how cpplint behaves by adjusting the linelength and which rule to apply or ignore in cpplint.cfg

For PlatformIO specific integration you can use my runner and execute it as follows:

pio run -t lint

By combining clang-format and cpplint you can avoid ever styling your code manually

Static Code Analysis

While coding style can really help for readability of code and preventing confusion, styling by itself does not contribute to the quality of code executed. Lets explore what is available 

Compiler Warnings

A great source of warnings and issues that originate from mistakes or lack of understanding of C/C++ languages is compiler warnings, the default warning level attempts to balance between certain mistakes and an attempt not to overwhelm the developer.

These flags can help you to switch between simple mistakes and pedantic development style, if you find yourself in a pickle or would like to avoid the pickle all together it might be beneficial to use the more restrictive warning levels but like everything in software, the tool does not make the software and you'll need to understand why you need to fix what the compiler tells you to fix.

Chris Coleman wrote about The Best and Worst GCC Compiler Flags For Embedded other than the GCC warnings documentation but in summary:

-Wall - enables warnings about questionable practices that are easy to avoid

-Wextra - more warnings 

-Wshadow - shadowing is a readability issue that can also lead to bugs since the developer might get confused about which variable is actually in use.

-Wdouble-promotion - some MCUs have FPU that supports floats only, whenever a floating point gets promoted to double for any reason this warning will tell you about it since you might lose performance over it.

-Wformat=2 - checks scanf and printf mistakes

-Wformat-truncation - checks snprintf has enough room, heuristics based.

-Wundef - warning if undefined identifier is evaluated in the preprocessor.

-Weffc++ - Warn about violations of style guidelines from Scott Meyers’ Effective C++ series of books

In any case, you can always view which warnings are enabled by:

gcc -Q --help=warnings

If you'd like to see which ones are enabled with using a certain warning level:

gcc -Wall -Wextra -Q --help=warnings

PlatformIO Check

PlatformIO check provides easy access to two static code analyzers, cppcheck and clang-tidy. to use them we need to add:

check_tool = cppcheck, clangtidy

and then run:

pio check

This should get you results similar to this when running the checks:

Checking native > cppcheck (platform: native)
----------------------------------------------------------------------------------------------
src\port_arduino.h:6: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
...
================================ [PASSED] Took 3.53 seconds ==================================

Checking native > clangtidy (platform: native)
----------------------------------------------------------------------------------------------
src\main.cpp:6: [medium:warning] system include stdio.h not allowed  [llvmlibc-restrict-system-libc-headers]
...
================================ [PASSED] Took 1.34 seconds ==================================

Component            HIGH    MEDIUM    LOW
------------------  ------  --------  -----
lib\circularbuffer    0        0       32
...

Total                 2        17      60

Environment    Tool       Status    Duration
-------------  ---------  --------  ------------
native         cppcheck   PASSED    00:00:03.533
native         clangtidy  PASSED    00:00:01.341
================================= 2 succeeded in 00:00:04.874 ================================

cppcheck

cppcheck is a free static code analyzer, it detects common mistakes and also supports a subset of MISRA standard, you can find examples and explanations in the Zephyr documentation.

To support MISRA checks, you'll need to add a few things to the default PlatformIO configuration.

1. in platformio.ini section:

check_flags =
    cppcheck: --enable=all --addon=./scripts/misra.json --addon=cert --addon=threadsafety --addon=y2038

2. download misra.py, misra_9.py and cppcheckdata.py from cppcheck repository and place it in scripts folder.

3. add misra.json to the scripts folder, this is the configuration for the MISRA addon, I've disabled rule 17.7 in this example.

{
    "script": "scripts/misra.py",
    "args": ["--rule-texts=scripts/misra.txt","--suppress-rules 17.7"]
}

4. download misra.txt and place it in the scripts folder for the addon to pick up and use as messages.

This should get you results similar to this when running the checks:

Checking native > cppcheck (platform: native)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
src\port_arduino.h:6: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
src\port_arduino.h:7: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
src\port_arduino.h:10: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
lib\examplelib\ProductionCode.h:3: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
src\main.cpp:6: [low:style] The Standard Library input/output functions shall not be used [misra-c2012-21.6]
src\main.cpp:22: [low:style] Do not use the rand() function for generating pseudorandom numbers [cert-MSC30-c]
lib\circularbuffer\CircularBuffer.cpp:32: [low:style] There should be no unused parameters in functions [misra-c2012-2.7]
lib\circularbuffer\CircularBuffer.cpp:88: [low:style] A string literal shall not be assigned to an object unless the object's type is pointer to const-qualified char [misra-c2012-7.4]
lib\circularbuffer\CircularBuffer.cpp:102: [low:style] A string literal shall not be assigned to an object unless the object's type is pointer to const-qualified char [misra-c2012-7.4]
lib\circularbuffer\CircularBuffer.cpp:105: [low:style] A string literal shall not be assigned to an object unless the object's type is pointer to const-qualified char [misra-c2012-7.4]
lib\circularbuffer\CircularBuffer.h:50: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
lib\circularbuffer\CircularBuffer.h:52: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
lib\circularbuffer\CircularBuffer.h:53: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]
lib\circularbuffer\CircularBuffer.h:54: [low:style] Function types shall be in prototype form with named parameters [misra-c2012-8.2]

clang-tidy

clang-tidy is llvm's static code analayzer, one of the more interesting features is that it can fix some errors it finds. 

to run it with fix you can run it as follows:

pio check --flags "clangtidy: --fix"

This should get you results similar to this when running the checks:

Checking native > clangtidy (platform: native)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
src\main.cpp:6: [medium:warning] system include stdio.h not allowed  [llvmlibc-restrict-system-libc-headers]
src\main.cpp:6: [medium:warning] inclusion of deprecated C++ header 'stdio.h'; consider using 'cstdio' instead  [hicpp-deprecated-headers,modernize-deprecated-headers]
src\main.cpp:9: [medium:warning] system include stdlib.h not allowed  [llvmlibc-restrict-system-libc-headers]
src\main.cpp:9: [medium:warning] inclusion of deprecated C++ header 'stdlib.h'; consider using 'cstdlib' instead  [hicpp-deprecated-headers,modernize-deprecated-headers]
src\main.cpp:16: [medium:warning] declaration must be declared within the '__llvm_libc' namespace  [llvmlibc-implementation-in-namespace]

Flawfinder

Flawfinder is a simple tool for scanning source code for possible security weaknesses (or "flaws"). 

For PlatformIO specific integration you can use my runner and execute it as follows:

pio run -t flawfinder

This should get you results similar to this when running flawfinder:

flawfinder -C -c -D -i -S -Q include src lib\arduino-printf lib\circularbuffer lib\defectedLib lib\examplelib lib\runner
src\main.cpp:21:2:  [0] (format) printf:If format strings can be influenced by an attacker, they can be exploited (CWE-134).  Use a constant for the format specification. Constant format string, so not considered risky.
        printf("test broken %d\r\n", FindFunction_WhichIsBroken(78));
src\main.cpp:24:2:  [0] (format) printf:If format strings can be influenced by an attacker, they can be exploited (CWE-134).  Use a constant for the format specification. Constant format string, so not considered risky.
        printf("displaying float %.6f", c);
lib\circularbuffer\CircularBuffer.cpp:90:5:  [2] (buffer) char:Statically-sized arrays can be improperly restricted, leading to potential overflows or other issues (CWE-119!/CWE-120).  Perform bounds checking, use functions
that limit length, or ensure that the size is larger than the maximum possible length.
    char sval[10];
lib\circularbuffer\CircularBuffer.cpp:98:9:  [0] (format) snprintf:If format strings can be influenced by an attacker, they can be exploited, and note that sprintf variations do not always \0-terminate (CWE-134).  Use a constant for the format specification. Constant format string, so not considered risky.
        snprintf(sval, sizeof(sval), "%d", buffer[printIndex]);

lib\circularbuffer\CircularBuffer.cpp:90:5:  [2] (buffer) char:Statically-sized arrays can be improperly restricted, leading to potential overflows or other issues (CWE-119!/CWE-120).  Perform bounds checking, use functions
that limit length, or ensure that the size is larger than the maximum possible length.
    char sval[10];

doxygen

while doxygen is not a static code analyzer per-se, it can help to generate documentation, call graphs and help other developers to understand the code in shorter time.

To ease with function documentation, you can use the Doxygen VSCode Extension.

Install doxygen and graphviz which is used to generate the graphs.

generate a basic configuration file:

doxygen -g .doxygen

As a quick start override the following settings:

OUTPUT_DIRECTORY       = docs
INPUT                  = lib src
BUILTIN_STL_SUPPORT    = YES
EXTRACT_ALL            = YES
EXTRACT_STATIC         = YES
WARN_NO_PARAMDOC       = YES
RECURSIVE              = YES
STRIP_CODE_COMMENTS    = NO
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
GENERATE_LATEX         = NO
MACRO_EXPANSION        = YES
HAVE_DOT               = YES
UML_LOOK               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
INTERACTIVE_SVG        = YES

Generate the documentation:

doxygen .doxygen

doxygen .doxygen

And finally, you should be able to see the documentation by opening the docs/html/index.html, search for functions and browse the documentation, you'll see that just after a few minutes you already know the basic structure, which function references which and you'll get a feeling of the general flow of the application.

Code Metrics

Code metrics are used to find hot spots that go against clean code's most prominent rule, “The first rule of functions is that they should be small.”
With code metrics we can find long functions, long files, complex functions and the most basic thing we can do to our team members to save them from this.

Lizard

Lizard is a code complexity analyzer, while it supports many languages, we only want it to work with C/C++ code.

First, we'll need to setup lizard's setting in platformio.ini, in this case we're limiting the complexity to 15, maximum length of functions to 100 lines and maximum arguments passed to a function is 1.

cyclomatic_complexity_analyzer = --CCN 15 --length 100 --arguments 1 --warning-msvs

For PlatformIO specific integration you can use my runner and execute it as follows:

pio run -t lizard

And see results similar to this:

lib\examplelib\ProductionCode2.c(4): warning: ThisFunctionHasNotBeenTested has 6 NLOC, 1 CCN, 28 token, 2 PARAM, 8 length
lizard -Eduplicate include src lib\arduino-printf lib\circularbuffer lib\defectedLib lib\examplelib lib\runner
*** Error 1
================================================
  NLOC    CCN   token  PARAM  length  location
------------------------------------------------
       8      2     48      0      10 setup@16-25@src\main.cpp
       3      1      5      0       4 loop@27-30@src\main.cpp
       7      2     19      0      10 main@10-19@src\port_arduino.h
       5      1     44      1       5 CircularBuffer::CircularBuffer@32-36@lib\circularbuffer\CircularBuffer.cpp
       4      1     12      0       4 CircularBuffer::~CircularBuffer@38-41@lib\circularbuffer\CircularBuffer.cpp
       4      1     10      0       4 CircularBuffer::IsEmpty@43-46@lib\circularbuffer\CircularBuffer.cpp
       4      1     10      0       4 CircularBuffer::IsFull@48-51@lib\circularbuffer\CircularBuffer.cpp
       8      3     49      1       8 CircularBuffer::Put@53-60@lib\circularbuffer\CircularBuffer.cpp
      11      3     51      0      12 CircularBuffer::Get@62-73@lib\circularbuffer\CircularBuffer.cpp
       4      1     10      0       4 CircularBuffer::Capacity@75-78@lib\circularbuffer\CircularBuffer.cpp
       5      2     23      1       5 CircularBuffer::Next@80-84@lib\circularbuffer\CircularBuffer.cpp
      18      5    116      0      22 CircularBuffer::Print@86-107@lib\circularbuffer\CircularBuffer.cpp
      11      2     69      0      11 dynamic_buffer_overrun_018@5-15@lib\defectedLib\bufferLibrary.c
       4      1     14      0       4 memory_leak_001@17-20@lib\defectedLib\bufferLibrary.c
       9      3     36      1       9 FindFunction_WhichIsBroken@11-19@lib\examplelib\ProductionCode.c
       4      1      9      1       4 FunctionWhichReturnsLocalVariable@21-24@lib\examplelib\ProductionCode.c
       6      1     28      2       8 ThisFunctionHasNotBeenTested@4-11@lib\examplelib\ProductionCode2.c
       3      1     11      0       3 setup@30-32@lib\runner\runner.h
13 file analyzed.
==============================================================
NLOC    Avg.NLOC  AvgCCN  Avg.token  function_cnt    file
--------------------------------------------------------------
     19       5.5     1.5       26.5         2     src\main.cpp
      9       7.0     2.0       19.0         1     src\port_arduino.h
      0       0.0     0.0        0.0         0     src\sdkconfig.h
      1       0.0     0.0        0.0         0     lib\arduino-printf\arduino-printf.h
     65       7.0     2.0       36.1         9     lib\circularbuffer\CircularBuffer.cpp
     29       0.0     0.0        0.0         0     lib\circularbuffer\CircularBuffer.h
     18       7.5     1.5       41.5         2     lib\defectedLib\bufferLibrary.c
      2       0.0     0.0        0.0         0     lib\defectedLib\bufferLibrary.h
     16       6.5     2.0       22.5         2     lib\examplelib\ProductionCode.c
      2       0.0     0.0        0.0         0     lib\examplelib\ProductionCode.h
      7       6.0     1.0       28.0         1     lib\examplelib\ProductionCode2.c
      1       0.0     0.0        0.0         0     lib\examplelib\ProductionCode2.h
     12       3.0     1.0       11.0         1     lib\runner\runner.h

===============================================================================================================
No thresholds exceeded (cyclomatic_complexity > 15 or length > 1000 or nloc > 1000000 or parameter_count > 100)
==========================================================================================
Total nloc   Avg.NLOC  AvgCCN  Avg.token   Fun Cnt  Warning cnt   Fun Rt   nloc Rt
------------------------------------------------------------------------------------------
       181       6.6     1.8       31.3       18            0      0.00    0.00
Duplicates
===================================
Total duplicate rate: 0.00%
Total unique rate: 100.00%

Now we can see a warning that a function has two parameters (over 1 of the limit we set)

We can also see statistics for the entire project analysis, this can help us locate functions that are approaching the limits we set and find duplicate code.

Coding Standards

In addition to MISRA, there are other interesting standards that you should be aware of.

SEI CERT C Coding Standard (PDF), what I really like about this standard is the explanation each rule have and why its in the standard.

Lastly but not less important is the AUTOSAR Guidelines for the use of the C++14 language in critical and safety-related systems (PDF), like the others, one of the more important sections is the rational for including the guidelines can provide an important insight into the "why" and is always a good reading material.

Test Sample

Lastly, if you're currently evaluating code standard tools and static code analysis tools, you may find the itc-benchmarks beneficial.

Continue reading about dynamic code analysis...

References:

Evaluation of Open Source Static Analysis Security Testing (SAST) Tools for C

FOSS Static Analysis Tools for Embedded Systems and How to Use Them

Joint Strike Fighter Air Vehicle C++ Coding Standards

Read More

Tags: autosar, clang-format, clang-tidy, clangtidy, code style, cppcheck, cpplint, doxygen, flawfinder, misra, platformio

Dror Gluska June 02, 2022  No comment