Using Python in Renode¶

Renode offers several different Python integrations which can be used to extend it, both from the inside and outside. It is important to differentiate between them to avoid confusion:

• built-in IronPython integration (this is Python 2 running inside Renode) which is the main focus of this chapter

• external pyrenode integration (this is a Python 3 wrapper using RPC calls to call Renode / execute Robot keywords)

• (NEW!) external pyrenode3 integration (this is the new, native CLR bindings, esentially a Python 3 wrapper around all of Renode, set to replace the ‘older’ pyrenode when stabilized)

This chapter currently focuses on the built-in IronPython integration and use of Python from within Renode, hence the Python 2 syntax with old-style print statements you will notice throughout. Eventually, the internal (Iron)Python integration will either be migrated to IronPython3 or moved over to the the same mechanism pyrenode3 is using.

In the meantime, documentation will be added for pyrenode3 to complement this chapter.

Thanks to the IronPython integration, you can use Python in runtime to do things like reacting to lines on UART, change of user state, peripheral access, or a value appearing in the memory.

Python offers a real programming language syntax with its flow control constructs, loops, etc.

Python also gives you access to emulation components available under context-specific variable names. These variables are described in respective sections. They serve as an API between the script and the rest of Renode.

Direct Python execution in the Monitor¶

Python code can be executed directly in the Renode Monitor using the python command in the Monitor:

(monitor) python [ py ]

You can also use the include command to load an existing .py file:

(monitor) include @path/to/file.py

Providing Python scripts from the Monitor¶

To provide a multiline Python script from the Monitor or a .resc file, use the following notation:

(monitor) set my_script """
> print "Hello"
> print "This is a multiline Python script"
> if 0 > 1:
>    print "This will not be printed"
> """
(monitor) python $my_script

Using the print Python command will output the text on the Monitor:

(monitor) python "print 'Hello'"
Hello

Creating Monitor commands in Python¶

Running the python command in the Monitor executes the provided code immediately. However, it is possible to use these Python scripts to define functions available for later use.

Such functions can be executed with subsequent python calls, but you can also expose them directly to the Monitor, if you follow a specific naming convention.

If the name of the function you define starts with the mc_ prefix, it will become available as a new Monitor command, stripped of this prefix.

For example, consider the following Python definition:

def mc_sleep(time):
    sleep(float(time))

When executed in Renode, this definition provides a sleep function in the Monitor:

(monitor) sleep 5

A small set of predefined Python commands is available in the monitor.py file.

Python peripherals in a platform description¶

You can use Python in the .repl file of your platform description. Several platforms included in Renode like Zynq 7000 use Python peripherals to implement simple logic. The most common use of Python peripherals is mocking certain blocks that are not fully implemented but are required by the software.

To create a Python peripheral, you need to specify several variables:

variableName: Python.PythonPeripheral @ sysbus 0x7000F410
    size: 0x4
    initable: false
    script: "request.value = 0x60000"

To define Python peripherals, you can specify the following variables:

When programming a Python peripheral, you have access to the request variable, which describes the current transaction.

The variable request in Renode gives you access to the following fields:

An example Python peripheral available in mainline Renode is repeater.py, returning the same value that was written to it by software:

if request.isInit:
    lastVal = 0
elif request.isRead:
    request.value = lastVal
elif request.isWrite:
    lastVal = request.value

self.NoisyLog("%s on REPEATER at 0x%x, value 0x%x" % (str(request.type), request.offset, request.value))

There are also other variables that can be used in Python peripherals:

Python hooks in Renode¶

There are multiple types of hooks in Renode, which allow you to execute code, e.g. a Python script, when certain specified conditions are met. Each separate hook provides you with different functionality, and multiple types of hooks can be used in a single project. Types of hooks in Renode:

• UART hooks,

• CPU hooks.

• system bus hooks,

• watchpoint hooks,

• packet interception hooks,

• user state hooks,

UART hooks¶

UART hooks enable you to code a reaction to the event when a specific character or substring appears on UART.

UART hooks in Renode have access to the following variables:

You have to specify the string you want to search for in the UART’s output and the Python script that will be executed if the substring appears on UART:

(machine) uart AddLineHook "searched value" "print 'Found the %s string' % line"

CPU hooks¶

CPU hooks enable you to code a reaction to reaching a specific stage in code execution. The hook can be triggered at the beginning, end of code of an executed block, or any specified point in the application. CPU hooks can also react to the interrupts in code and be triggered at the beginning or an end of an interruption or when the CPU enters or exits from WFI (“Wait-For-Interrupt”) state.

All CPU hooks in Renode have access to the following variables:

Specific hooks can have additional variables available:

To use a CPU hook, you need to name cpu you want to attach the hook to and specify the method. To create a hook that triggers at the beginning of interrupt:

(machine) cpu AddHookAtInterruptBegin "print 'Interrupt has started'"

To create a hook that triggers at the end of interrupt:

(machine) cpu AddHookAtInterruptEnd "print 'Interrupt has ended'"

To create a hook that triggers when the CPU enters or exits “Wait-For-Interrupt” state:

(machine) cpu AddHookAtWfiStateChange "print 'Entered/Exited WFI'"

To create a hook that triggers at the beginning of an executed block:

(machine) cpu SetHookAtBlockBegin "print 'Execution of a code block has started'"

To create a hook that triggers at the end of an executed block:

(machine) cpu SetHookAtBlockEnd "print 'Execution of a code block has ended'"

You can also create a hook for any specified point in the application:

cpu AddHook 0x60000000 "print 'You have reached a hook'"

and even combine the previous command with another one to add a hook at a symbol:

cpu AddHook `sysbus GetSymbolAddress "main"` "print 'You have reached the main function'"

System bus hooks¶

System bus hooks enable you to code a reaction to the event when peripherals are accessed to read or write. This hook has access to the peripherals, and it can be assigned to react only to a specific peripheral.

System bus hooks in Renode have access to the following variables:

To create a system bus hook that executes a Python script after a specific peripheral is accessed to read:

(machine) sysbus SetHookAfterPeripheralRead peripheral "print '%s peripheral has been accessed to read'"

To create a system bus hook that executes a Python script before a specific peripheral is accessed to write:

(machine) sysbus SetHookBeforePeripheralWrite peripheral "print '%s peripheral has been accessed to write'"

Watchpoint hooks¶

Watchpoint hooks enable you to code a reaction to the event when a specific value appears in a specific memory address.

Watchpoint hooks in Renode have access to the following variables:

To create a watchpoint hook that executes a Python script, when a Read access with width of 32 bits (DoubleWord) appears at address 0x70001000, run:

(machine) sysbus AddWatchpointHook 0x70001000 DoubleWord Read "print '32 bit value appeared at the address 0x70001000'"

Packet interception hooks¶

Packet interception hooks enable you to code a reaction to the event when a packet appears on a radio medium.

Packet interception hooks in Renode have access to the following variables:

To have a functioning Packet interception hook, your machine needs to have a wireless medium. To create a packet interception hook, run:

(machine) wireless SetPacketHookFromScript sysbus.radio "if packet[5] == 0x4: print('I\'m interested in packets with 0x4 as their sixth byte')"

You can also execute a script from a file:

(machine) wireless SetPacketHookFromFile sysbus.radio @path/to/file.py

User state hooks¶

User state hooks enable you to code a reaction to the event when “UserState” string of a machine changes.

User state hooks in Renode have access to the following variables:

To create a user state hook that executes Python script when a specific state is set:

(machine) machine AddUserStateHook "state" "print 'User state has changed to: %s state '"

Python enabled classes¶

The hooks described in previous sections use special methods that setup the execution environment for your Python script, but IronPython also allows you to attach Python functions to C# events.

As an example let’s create a trivial Ethernet sniffer:

(machine-0) emulation CreateSwitch "switch"
(machine-0) python "externals.switch.FrameProcessed += lambda switch, sender, data: sender.LogDebug(str(data))"

For an in-depth explanation of setting up the network see the Setting up a wired network chapter.

Dummy I2C Slave¶

The Mocks.DummyI2CSlave peripheral provides a set of methods and events that allow you to implement a simple I2C peripheral.

The DataReceived event doesn’t expect any data to be provided, but you can enqueue response bytes using the methods listed below. By default, when the internal buffer is empty, the peripheral returns zeros and will pad any enqueued data with zeros when not enough bytes is in the buffer.

With those available, we can change the dummy I2C peripheral into a simple I2C echo peripheral:

dummy = monitor.Machine["sysbus.i2c.dummy"]
dummy.DataReceived += lambda data: dummy.EnqueueResponseBytes(data)

Virtual Console¶

The VirtualConsole is meant to be a helper for Python scripts as it is supported with the same infrastructure, e.g. you can use it in Robot Framework tests with UART keywords and create an analyzer to interact with the console. It provides an internal buffer for the received data and methods and events listed below that allow for control from a Python script.

An instance of the console can be created with a Monitor command:

(machine-0) machine CreateVirtualConsole "vconsole"
(machine-0) showAnalyzer vconsole

or in a repl file:

vserial: UART.VirtualConsole @ sysbus

Using the methods listed above and some other hooks for accesses you can implement a polling-based peripheral, e.g. the Segger RTT for Renesas, which is used in demos (e.g. scripts/single-node/ek-ra2e1.resc) with interactive console and in Robot Framework tests using UART keywords (e.g. tests/platforms/EK-RA2E1.robot).

The VirtualConsole also has the Echo property to enable or disable displaying of received characters.

RISC-V extensions¶

Renode has extensive support for RISC-V architecture and lets you code extensions using Python. You can write the logic of Control/Status Register and custom instructions and then install them either from a file or a string. Those instructions can be either 16-bit, 32-bit, or 64-bit.

Python implementations of RISC-V custom instructions have access to the following variables:

Custom instructions from a string can be installed using:

(machine) sysbus.cpu InstallCustomInstructionHandlerFromString "10110011100011110000111110000010" "cpu.DebugLog('custom instruction executed!')"

If you want to install a custom instructions from a file, use:

(machine) sysbus.cpu InstallCustomInstructionHandlerFromFile "10110011100011110000111110000010" "path/to/file.py"

RISC-V custom instructions extensions in Renode have access to the following variables:

Custom instructions have access to the request object, which is similar to bus access. It has access to various properties:

To install custom Control/Status Register from a string, use:

(machine) sysbus.cpu RegisterCSRHandlerFromString 0xf0d "print 'CSR has been accessed'"

To provide a custom CSR from a file, instead use:

(machine) sysbus.cpu RegisterCSRHandlerFromString 0xf0d "path/to/file.py"

Examples of custom CSR and custom instructions can be found in Renode’s custom instructions tests.