Zedboard Port Technical Note

Sergio Pastor Pérez

April 22, 2022

Contents
1 Changelog 2

2 Terms, definitions and abbreviated terms 2

3 Executive summary 2

4 Introduction 2

5 Port structure 2
5.1 docs/ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.2 xng/ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.3 micropython/ports/zedboard . . . . . . . . . . . . . . . . . . . . 3

6 Python code execution on the Micropython VM port 4

6.1 Python injection from C . . . . . . . . . . . . . . . . . . . . . . . 4
6.2 Load precompiled Python binaries . . . . . . . . . . . . . . . . . 5
6.3 Interactive prompt . . . . . . . . . . . . . . . . . . . . . . . . . . 5

7 Build system 5
7.1 Hello World example compilation . . . . . . . . . . . . . . . . . . 6
7.2 Test suite compilation . . . . . . . . . . . . . . . . . . . . . . . . 6
7.3 How to modify the build system . . . . . . . . . . . . . . . . . . 6
7.3.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.3.2 Test suite . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.3.3 Micropython . . . . . . . . . . . . . . . . . . . . . . . . . 7

8 Load binaries to Zedboard 7

1
1 Changelog
Version Date Author Comments
01 19/04/22 Sergio Pastor Pérez Initial document

2 Terms, definitions and abbreviated terms

Term Definition
elfbdr Xtratum tool for building the hypervisor images.
Zedboard Target port platform.
Viper Native code emmiter for the target architecture.
Hypervisor A hypervisor or virtual machine monitor (VMM)
is computer software, firmware or hardware that
creates and runs virtual machines.

RAM Random Access Memory

XNG Xtratum Next Generation
XRE Xtratum Runtime Enviroment
VFS Virtual File System
API Aplication Programming Interface
JIT Just In Time
REPL Read Evaluate Print Loop
UART Universal Asynchronous Receiver-Transmitter
QSTR uniQue STRing
XSDB Xilinx System Debuger
symlink Symbolic link

3 Executive summary
This document summarizes the results obtained from the Micropython porting
to XNG.

4 Introduction
Micropython is an implementation of Python 3 programming language for
microcontrollers. It is mostly compilant with the specification of CPython3.4.
The port support most of the funcionalty provided by Micropython with the
exception of optimisation oriented features, such as, the native assembly com-
piler and the viper compiler. Other features out of the scope are the VFS, the
GPIO and the implementation of drivers APIs for specific peripherals.

5 Port structure
The port is divided in two mayor components, the hypervisor folder named
xng and the Micropython folder which contains the Zedboard port. From the
Micropython folder, the port is located in ./ports/zedboard.

2
5.1 docs/
Holds all the documentation created for the port.
Subdirectories
• note_files: holds all the images and extra files needed to build the docu-
mentation.

5.2 xng/
Holds the example and test suite source files along with the necessary makefiles
to build them.
Subdirectories
• drivers: necessary source files to control de UART and enable the REPL
serial input.
• xml: configurations related to the hypervisor and the partitions.
• lds: linker scripts for the build system.
• mkfiles: the extra rules and paths used by the makefiles.

5.3 micropython/ports/zedboard
Holds the necessary libraries and configuration files needed by the python build
for the Zedboard.
Subdirectories
• tools: holds the tool needed to generate the test suite C file.
• mkfiles: the extra rules and paths used by the makefiles.

3
6 Python code execution on the Micropython VM
port
6.1 Python injection from C
Micropython allows to write python code from the C files used to program the
partition running over XRE. This can be done as follows:
int py_code_injection()
{
int stack_dummy;
stack_top = (char *)&stack_dummy;

#if MICROPY_ENABLE_GC
gc_init(heap, heap + sizeof(heap));
#endif

mp_init();

#if MICROPY_ENABLE_COMPILER
pyexec_friendly_repl();

do_str("print(’hello world!’, list(x+1 for x in range(10)),

end=’eol\\n’)", MP_PARSE_SINGLE_INPUT);
do_str("for i in range(10):\r\n print(i)", MP_PARSE_FILE_INPUT);
#else
XalPrintf("Compiler not enabled! Set MICROPY_ENABLE_COMPILER\n");
#endif

mp_deinit();

return 0;
}
First, the user has to initialize the Micropython enviroment, after that the
function do_str(. . . ) can be called and the python code passed as a string will
be execute thanks to the JIT compiler. When the Micropython enviroment is
no longer needed it should be discarded with mp_deinit().

4
6.2 Load precompiled Python binaries
Precompiled python binaries can be loaded from the C files used to program
the partition running over XRE. This can be done as follow:
int uPython_exec_frozen_test(const char *const test)
{
int stack_dummy;
stack_top = (char *)&stack_dummy;

mp_init();

pyexec_friendly_repl();
pyexec_frozen_module(test);

mp_deinit();
return 0;
}
First, the user has to initialize the Micropython environment, after that the
function pyexec_frozen_module(. . . ) can be called with a string holding the
.py file name that wants to be loaded.
To allow this loading, first the file has to be acknowledged and compiled by the
build system. This is done through the XNG makefile. For each partition, a
call to the makefile macro def_part(. . . ) will create the apropiate rules to build
the system. The ${1} argument should hold the partition name, ${2} should
hold all the partition source C files, ${3} holds all the extra object files that
are ready to be linked (if any), ${4} is reseved for a .py file that wants to be
frozen. ${4} can also accept __test__ as a parameter to start the build of the
test suite.

6.3 Interactive prompt

The Micropython REPL can be started as seen in uPython_exec_uart(. . . ).
In this example first the Micropython enviroment is started and the UART is
pooled in a blocking loop. The loop will store each received character until a \n
character is found, then the whole buffer will get processed and executed with
the do_str(. . . ) function call.

7 Build system
The build system will also generate the binaries of each partition separately, for
this example the generated partition file is hello_world.armv7a-vmsa-tz.elf,
which is stripped to a raw binary for the elfbdr tool. The raw binary is
hello_world.armv7a-vmsa-tz.bin.

5
7.1 Hello World example compilation
In order to build the hello_world example, execute make in the terminal. This
will generate the file sys_img.elf, this executable will run the example over
XRE in a partition of XNG.

7.2 Test suite compilation

In order to build the test suite, execute make -f Makefile.test in the termi-
nal. This will generate the file sys_img.elf, this executable will run the test
suite over XRE in a partition of XNG. It will report each test result through
the UART serial interface of the Zedboard.

7.3 How to modify the build system

7.3.1 General
The first modification the user might be interested in is, using diferent C files
for the partition. All them should be added to a variable as ${P0_SRC}, they
must be whitespace separated. This variable should be the second parameter of
the macro def_part. The build system will compile and link all of them without
any other user modifications.
If the partition source files need specific include paths, they should be added to
the ${TARGET_CFLAGS} variable as seen in the example. Every extra flag
should be included in this variable.
Other binaries the user would want to link against should be passed to the
macro def_part as the third argument, this can be seen in the example for the
uart drivers.
If the user wants to use the Micropython feature that allows to load .py files,
it would be necessary to specify the files to be frozen. This file path should be
passed to def_part as the fourth parameter.
Micropython uses string interning to save both RAM and ROM. This avoids
having to store duplicate copies of the same string. To apply string interning,
the user should list the source files for QSTR extraction by adding their file
paths to ${SRC_QSTR}.
For completion, the python binaries are compiled and linked by default since
they are allways added to the build from ${1}_ELF_EXTRA-y.

7.3.2 Test suite

The user might want to change the tests groups of the suite or add their own.
This should be done through the test generation tool, tinytest-codegen.py. In
this tool the user can add new tests directories to be scanned for .py test files
by changing the test_dirs tuple. Or remove specific tests from groups by adding
their name and prefix in exclude_tests tuple.

6
7.3.3 Micropython
The only modifications that the user should do to the Micropython side of the
build system are in the mpconfigport.h, here are the different macro definitions
that change how the Micropython firmware is built. For more information the
user should check the official documentation of the project from: Micropython
docs

8 Load binaries to Zedboard

The binaries are loaded onto the Zedboard with the Xilinx tool, XSDB. This
tool uses a .tcl file as a script to initialize the board and load the final image
onto the target. For more information read the official documentation.
In the provided example there is a symlink form xsdb.ini to init.tcl. This
has the effect of xsdb automatically loading the init.tcl script. This scripts
initializes the board and loads the sys_img.elf onto the Zedboard’s RAM.
With this setup the user only needs to run xsdb in the terminal to test the
firmware.