This repository hosts the Viper VM

At the moment, the build system works only on a linux64 machine with just "make" installed. The toolchain is included in the Viper package (under tools).

To build the VM type:

make BOARD=board

where board can be one of:

• arduino_due: for Arduino Due board
• st_nucleo: for ST Nucleo 401
• spark_v2: for the Spark Core

To upload the compiled VM to a board, type:

make BOARD=board upload

To clean everything, type:

make BOARD=board clean

To build with debug support, type:

make BOARD=board DEBUG=1

In a debug buil, VM_DEBUG is defined and the VM will start in debug mode, firing a lot of information to VM_STDERR.

To build a test suite, type:

make BOARD=board TESTFILE=testsuitename.c

The command will build a binary where the main.c is substituted with common/viper_test.c and the testsuite file will be under boards/BOARD/tests/testsuitename.c

To create a test:

1. create a new file testsuite.c under the tests directory of the selected board

2. include viper_test.h and any other relevant header you may need in the test

3. declare every test using the macro TEST(name_of_test)

4. at the end of testsuite.c write the array of tests to be run by using BEGIN_TEST(description_of_testsuite), followed by any number of ADD_TEST(test_function, description_of_test_function), and closing the array with END_TEST()

   A simple example follows:

    #include "viper_test.h"

    TEST(test1) {
        TEST_ASSERT("1+1=2?", (1 + 1) == 2);
        printf("Writing a message inside test1\n");
        return TEST_OK();
    }


    TEST(test2) {
        TEST_EQUAL("still 1+1=2?",1+1,2);
        return TEST_KO("this test shall never pass!");
    }

    /* TEST ARRAY */

    BEGIN_TEST("Testing the test framework"),
               ADD_TEST(test1, "Description of Test 1"),
               ADD_TEST(test2, "Description of Test 2"),
               END_TEST();

The compiled test binary can then be uploaded to the board (that must have a working serial connected to STDOUT) and it will execute the tests you defined in the order you specified in the test array.

The build system resolves all the info needed to build the VM for a specific board, and selects the correct files.

1. Everything starts in the Makefile contained in the directory where this BUILDME resides. Checks are done and a RTOS is selected (at the moment only ChibiOS is supported).
2. The second Makefile called is common/common.mk. It collects specific info about the board and the rtos to create the list of source files. The most important variables used in common/common.mk are:
   • BOARD: the short name of the board to build for. Board specific files reside in boards/$(BOARD)
   • RTOSDIR: is the directory where the rtos source resides. Every rtos supported will be placed under common/vos/
   • The list of source files that is created by adding together:
     • RTOS_SRC: the list of rtos sources, generated by a rtos.mk included from RTOSDIR
     • VOS_SRC: the Viper Operative Sytem Abstraction Layer (abstraction for threads, semaphore, etc...)
     • VHAL_SRC: the list of Viper Hardware Abstraction Layer files (abstraction for mcu peripherals). It is composed of vhal.c, all the source files inside the board specific vhal implementation (defined in VHAL_PLATFORM) and all the source files provided by the chip manufacturer that are needed in the VHAL layer
     • COMMON_SRC: all the drivers files that are automatically added from the definitions in boards/$(BOARD)/config/custom.mk
     • VM_SRC: VM specific source, everything resides in lang/
     • MAINFILE: usually common/main.c (but can be something else if TESTFILE is used)
3. Control is then passed to common/rules.mk that:
   • creates oal_conf.h inside boards/$(BOARD)/config containing the needed definitions for VM drivers
   • compiles every .c to .o inside build
   • links all object files into a viper.hex and viper.bin inside build

When building for a particular board, board specific info resides in:

1. boards/$(BOARD)/platform.mk: here gcc options are specified together with VHAL_PLATFORM, a variable holding the path where the abstraction layer for the board resides (under common/vhal/specific-mcu-path). Moreover, a check is made on the selected RTOS and the variables needed by the RTOS to correctly compile for the board are set. For example, in ChibiOS you need to specify where the ChibiOS HAL for the board is (if it is used by VHAL).
2. boards/$(BOARD)/config/custom.mk: contains the definition of C macros that will be passed on the command line. The most important are:
   • VM_UPLOAD_INTERFACE: the number of the serial port used to upload bytecode
   • VM_STDOUT/VM_STDIN: the number of the main serial port
   • VM_STDERR: the number of the debug serial port
   • VM_BOARD: the board name the VM will expose
   • VM_ARCH: the architecture name the VM will expose
   • VM_UPLOADED_BYTECODE: if set the VM will wait for bytecode to be uploaded, otherwise bytecode is expected to be included in the source files as a const uint8_t array.
   • BOARD_EXT_DRIVERS: contains the names of the drivers to compile in the VM and it is converted in a source code list by common.mk. A driver has the same case sensitive name of the directory it resides in under common/drivers

The Viper VM is released under GPL3, see the attached files for details