1<!-- mdformat off(b/169948621#comment2) --> 2 3<!-- 4Semi-automated TOC generation with instructions from 5https://github.com/ekalinin/github-markdown-toc#auto-insert-and-update-toc 6--> 7 8<!--ts--> 9 * [Software Emulation with Renode](#software-emulation-with-renode) 10 * [Installation](#installation) 11 * [Running Unit Tests](#running-unit-tests) 12 * [Under the hood of the Testing Infrastructure](#under-the-hood-of-the-testing-infrastructure) 13 * [Running a non-test Binary with Renode](#running-a-non-test-binary-with-renode) 14 * [Useful External Links for Renode and Robot Documentation](#useful-external-links-for-renode-and-robot-documentation) 15 16<!-- Added by: advaitjain, at: Tue 10 Nov 2020 09:43:05 AM PST --> 17 18<!--te--> 19 20# Software Emulation with Renode 21 22TensorFlow Lite Micro makes use of [Renode](https://github.com/renode/renode) to 23for software emulation. 24 25Here, we document how Renode is used as part of the TFLM project. For more 26general use of Renode, please refer to the [Renode 27documentation](https://renode.readthedocs.io/en/latest/). 28 29You can also read more about Renode from a [publicly available slide deck](https://docs.google.com/presentation/d/1j0gjI4pVkgF9CWvxaxr5XuCKakEB25YX2n-iFxlYKnE/edit). 30 31# Installation 32 33Renode can be installed and used in a variety of ways, as documented in the 34[Renode README](https://github.com/renode/renode/blob/master/README.rst#installation/). For the purpose of Tensorflow 35Lite Micro, we make use of the portable version for Linux. 36 37Portable renode will be automatically installed when using the TfLite Micro 38Makefile to `tensorflow/lite/micro/tools/make/downloads/renode`. 39 40The Makefile internally calls the `renode_download.sh` script: 41 42``` 43tensorflow/lite/micro/tools/make/renode_download.sh tensorflow/lite/micro/tools/make/downloads 44``` 45 46# Running Unit Tests 47 48All the tests for a specific platform (e.g. bluepill) can be run with: 49 50``` 51make -f tensorflow/lite/micro/tools/make/Makefile TARGET=bluepill test 52``` 53 54 * This makes use of the robot framework from Renode. 55 * Note that the tests can currently not be run in parallel. 56 * It takes about 25 second to complete all tests, including around 3 seconds for suite startup/teardown and average 0.38 second per test. 57 58## Under the hood of the Testing Infrastructure 59 60Describe how we wait for a particular string on the UART. Some pointers into the 61robot files as well as any relevant documentation from Renode. 62 63A test failure is the absence of a specific string on the UART so the test will 64wait for a specific timeout period (configured in the .robot) file before 65failing. 66 67 * What this means in practice is that a failing test will take longer to finish 68 than a test that passes. 69 70 * If needed, an optimization on this would be to have a specific failure 71 message as well so that both success and failure can be detected quickly. 72 73# Running a non-test Binary with Renode 74 75Renode can also be used to run and debug binaries interactively. For example, 76to debug `kernel_addr_test` on Bluepill platform, run Renode: 77 78``` 79tensorflow/lite/micro/tools/make/downloads/renode/renode 80``` 81and issue following commands: 82``` 83# Create platform 84include @tensorflow/lite/micro/testing/bluepill_nontest.resc 85# Load ELF file 86sysbus LoadELF @tensorflow/lite/micro/tools/make/gen/bluepill_cortex-m3_default/bin/keyword_benchmark 87# Start simulation 88start 89 90# To run again: 91Clear 92include @tensorflow/lite/micro/testing/bluepill_nontest.resc 93sysbus LoadELF @tensorflow/lite/micro/tools/make/gen/bluepill_cortex-m3_default/bin/keyword_benchmark 94start 95 96``` 97 98To make repeat runs a bit easier, you can put all the commands into a 99single line (up arrow will show the last command in the Renode terminal): 100``` 101Clear; include @tensorflow/lite/micro/testing/bluepill_nontest.resc; sysbus LoadELF @tensorflow/lite/micro/tools/make/gen/bluepill_cortex-m3_default/bin/keyword_benchmark; start 102``` 103 104You can also connect GDB to the simulation. 105To do that, start the GDB server in Renode before issuing the `start` command: 106``` 107machine StartGdbServer 3333 108``` 109Than you can connect from GDB with: 110``` 111target remote localhost:3333 112``` 113 114For further reference please see the [Renode documentation](https://renode.readthedocs.io/en/latest/). 115 116# Useful External Links for Renode and Robot Documentation 117 118 * [Testing with Renode](https://renode.readthedocs.io/en/latest/introduction/testing.html?highlight=robot#running-the-robot-test-script) 119 120 * [Robot Testing Framework on Github](https://github.com/robotframework/robotframework). For someone new to 121 the Robot Framework, the documentation can be a bit hard to navigate, so 122 here are some links that are relevant to the use of the Robot Framework with 123 Renode for TFLM: 124 125 * [Creating Test Data](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-data) 126 section of the user guide. 127 128 * Renode-specific additions to the Robot test description format are in the 129 [RobotFrameworkEngine directory](https://github.com/renode/renode/tree/master/src/Renode/RobotFrameworkEngine). For example, 130 131 * [Start Emulation](https://github.com/renode/renode/blob/master/src/Renode/RobotFrameworkEngine/RenodeKeywords.cs#L41-L42) 132 * [Wait For Line On Uart](https://github.com/renode/renode/blob/master/src/Renode/RobotFrameworkEngine/UartKeywords.cs#L62-L63) 133 is where `Wait For Line On Uart` is defined. 134 135 * Some documentation for all the [Standard Libraries](http://robotframework.org/robotframework/#standard-libraries) 136 that define commands such as: 137 138 * [Remove File](http://robotframework.org/robotframework/latest/libraries/OperatingSystem.html#Remove%20File) 139 * [List Files In Directory](https://robotframework.org/robotframework/latest/libraries/OperatingSystem.html#List%20Files%20In%20Directory) 140
