GitHub action for v4l2 application testing in Renode

Antmicro’s work with camera systems often results in new reusable tools and libraries helpful for debugging video devices and applications. Some examples of such tools for working with v4l2 pipelines such as grabthecam, farshow, pyrav4l2 and Raviewer can be found on Antmicro’s Open Source Portal.

The apps and utilities themselves, however, require testing which is tricky to automate, as it requires a camera device.

One way to perform these tests without a physical camera is to use the Vivid driver which creates a fake v4l2 node capable of streaming test patterns, while providing example v4l2 controls for virtually any control type available for v4l2. It is a great choice for testing v4l2 applications, utils and debugging tools, but in many Linux compilations it is either completely disabled or provided as a dynamic kernel module. This includes e.g. the stock machines provided by GitHub Actions, and while in many projects we use our custom-developed GitHub runners to mitigate those kinds of problems, enabling easy peripheral testing with customized kernels via simulation in any context seemed like a very useful capability.

This consideration led us to create a GitHub action capable of running a full-fledged Linux distribution with a kernel of our choice, using the Renode simulation framework.

How the Renode Linux runner action works

The newly introduced GitHub action is designed to be completely transparent to users. They are able to run their CIs as usual, but instead of executing the code directly in docker containers provided by GitHub, the execution is wrapped in a Renode environment.

Inside the action, you can use the renode-run command which behaves similarly to the well-known run command in GitHub Actions, letting you run single commands as well as multi-line scripts.

You can also specify a shared directory shared between the Docker container and the Renode environment (shared-dir) for this action, where you can place the scripts you want to run.

This is how you would run a single command using the renode-run parameter:

- uses: antmicro/renode-linux-runner-action@main
  with:
    shared-dir: ./shared-dir
    renode-run: command_to_run

Running multiple commands works the same way as in the standard run command:

- uses: antmicro/renode-linux-runner-action@main
  with:
    shared-dir: ./shared-dir
    renode-run: |
      command_to_run_1
      command_to_run_2

The action runs the code on an emulated HiFive Unleashed platform with a RISC-V CPU, however it is the architecture-independent Linux API that is tested here.

Example use case

Since this is just a regular GitHub action, it is highly reusable. Below, as an example, we will run scripts extracted from the README for Antmicro’s pyrav4l2 tool for easily controlling v4l2 devices inside Python scripts using tuttest. Tuttest is another of Antmicro’s utilities which lets you test code embedded in tutorials and examples you provide to users to make sure they continue to run.

name: Running Python CI jobs

on:
  push:
    paths:
      - 'pyrav4l2/**'
      - 'README.md'

  pull_request:
    paths:
      - 'pyrav4l2/**'
      - 'README.md'

...

  run-example-scripts-from-readme:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Install tuttest
        run: pip install git+https://github.com/antmicro/tuttest.git

      - name: Extract example scripts from README
        run: python ./.github/save_examples.py README.md

      - name: Copy examples and pyrav4l2 to shared-dir
        run: |
          mkdir -p tests/pyrav4l2
          cp -r ./pyrav4l2 setup.py ./tests/pyrav4l2
          cp -r ./examples ./tests
      - name: Run scripts in Renode
        uses: antmicro/renode-linux-runner-action@main
        with:
          shared-dir: ./tests
          renode-run: |
            pip install ./pyrav4l2
            for script in ./examples/*.py; do python $script; done

Then, after the script is run in Renode, the following information regarding v4l2 is returned:

Color format: YUYV 4:2:2

Frame size: 320 x 180

Device name: vivid

Driver name: vivid

Device supports video capturing

Frame 0: 115200 bytes

Frame 1: 115200 bytes

More flexibility through testing in Renode

This action alleviates a common grievance and allows us to continuously test our open-source v4l2 apps, but its potential capabilities reach much further. Thanks to the flexibility of the Renode framework, we can not only use emulated devices (like Vivid), but also a wide variety of emulated hardware, which would allow users to test embedded Linux userspace applications with GitHub Actions, just like they would on physical hardware.

Potential further use cases for this action include testing applications that communicate with various sensors (e.g. via I2C or SPI) that use devices like watchdogs or flash, or even connect to other, completely independent devices over Bluetooth, Ethernet or other interfaces.

Whether you are interested in developing and testing applications for video devices together with Antmicro or you would like to discuss using Renode for comprehensive simulation of complex systems, feel free to contact us at contact@antmicro.com.