zWrap

A simple MATLAB wrapper based on TCP-over-Ethernet to deploy MATLAB function on ZedBoard and communicate back to MATLAB/Simulink with drop-in functions and blocks.

Dependencies

These are the prerequisites to use zWrap:

• MATLAB and MATLAB Coder
• GNU make to compile the generated files
• ARM Compiler available from ARM official website.
• bootgen, available from the original open-source repository1, to generate the BOOT.bin image to put on the SD card

Quickstart

zWrap comes as a MATLAB function. It is possible to call zWrap with the following notation:

zedWrap -path [Path to the codegen/lib/ folder generated by MATLAB coder, in which the CodeInfo.mat and buildInfo.mat objects are located] -ip [IP to assign to the board] -udpport [udp port to signal program runs] -tcpport [tcpport to signal program runs] -stack [stack size, dec or hex] -heap [stack size, dec or hex]

NOTE: Currently the IP and ports should be hardcoded as:

• IP: 192.168.1.10
• UDP Port: 7
• TCP Port: 8 The ZedBoard image supports DHCP and prints the network settings out on startup on the serial port. Future developments will allow to select the IP and ports manually and to display them on the ZedBoard included LCD screen.

Deployment instructions:

1. You need to have a coder-ready MATLAB function. The target should correspond to the target board. For the ZedBoard, make sure to select "Generic ARM device" as target hardware, specifying the "ARM Cortex-A9" architecture. Moreover, make sure to:
   • Not have dynamic variables
   • Use bounded inputs for variable-sized inputs
   • De-select the "Use OpenMP library if available", because OMP is not supported on most embedded boards
   • Generate either C or C++ source files.

MATLAB will create a folder in the root path of your MATLAB function, under codegen/lib. That folder is the one you will need to provide to zWrap.

2. Run zWrap with the desired settings. An example of call is:

zedWrap -path [Path] -ip 192.168.1.10 -udpport 7 -tcpport 8 -stack 819200 -heap 81920

If succesfully, you will find all the generated outputs in the out subfolder of zWrap, in a folder with the same name of your MATLAB function, preceded by a z. In particular:

• The 'simulink' folder will contain the block library and the MATLAB functions to interface the host with the board
• The 'project' folder will contain all the source files and board settings to be compiled through GNU make.
• The 'generated' folder contains support functions that have been copied in the 'project' sub-directories.

3. In order to generate, the BOOT.bin image, you should go to the 'project' folder, in the '{fcnname}_multicore_system' subfolder. There, go either in Debug or Release. Debug compiles with debug flags, Release with -O2. Run 'make' and the two cores' images will be generated, and bootgen will run to generate the BOOT.bin image. Copy-paste the image on the SD card an you're good to go.

Debug

If compiled with the Debug flags, the current version allows Vitis to debug the board by "attaching to running application" on target device. This allows to look at the disassembly and source codes if symbols (.elf) and source dirs are provided in Vitis.

Future works foresee the creation of an entire Vitis project, in order to use zWrap just to kickstart the project and then moving all the low-level stuff to Vitis, including debugging.

Known bugs

• With super-fast executions, sometimes the UDP packet to run the code is lost and the PIL simulation gets stuck.
• Single-output variables are buggy. Quickfix: make your function also return a simple return flag
• MATLAB's packNGo function is buggy and cannot distinguish between the path separators used on Windows or Linux/MacOs. Currently, the function is modified to run on MacOS. If you have problems with the packNGo, you can manually comment the part in which the code is packed, and manually pack the function with your systems' packNGo or with the "PACKAGE" functionality at the end of the MATLAB Coder workflow. Make sure to extract the packed files in a "pack" dir inside your codegen/lib/{fcnname} in order to fool zWrap.
• Sometimes the addresses of the vector table are compiled with strange paddings. The current padding is set at 2048 - as per ARM specification - and should be fine.
• Compiling libraries (i.e., lm) are normally not included. If you get compilations errors, make sure to edit the makefiles in order to include the libraries. This is a WiP because the libraries to compile are actually stated in the buildInfo.mat file generated by MATLAB and can be added automatically.

Disclaimer

zWrap is currently looking for test cases to be validated. Feel free to reach out to gianfranco.didomenico@polimi.it if you are interested in using zWrap to deploy your code.

Footnotes

1. Boogen is listed as available only for Windows and Linux; however, it is possible to compile it also for MacOS systems. ↩