Ivn Ren Morales, Guatemala

Written for MLAB, ICTP

April, 2015

Giving your first steps on Xillinux with Zedboard

What is this tutorial for?
Its intended to bring you step-by-step into the basic functionality tests provided by Xillybus
within its Xillinux distribution. This tutorial is compatible with Zybo and Zedboard development
boards; MicroZed should be compatible too, but it hasnt been tested yet. Notice its very
important to be familiar with the basic Linux shell commands.

Before you start

Be sure youve successfully completed the Getting Started with Xillinux for Zynq-7000 tutorial.
Youll also need a VGA or HDMI (only compatible with Zybo) display, a keyboard and a mouse.

First steps - Starting the graphical interface

Every time the device boots youll notice theres only a shell interface logged in as root user. To
start the graphical user interface, type in the shell:

$ root@localhost:~# startx

Just a tip
Please, notice that from now on, the following convention is being used:
root@localhost:~# This is the current command line prompt (italics)
startx This is what you need to type at the command prompt (bold italics)

Now, after some seconds, you should be able to see a familiar Ubuntu 12.04-like interface

Figure 1: Xillinux Graphical User Interface

1
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Xillinux is not a stock Ubuntu distro

Xillinux is an Ubuntu-based linux distribution, but its kernel has been compiled to run
within the Zynqs ARM A9 architecture and to provide direct access to Xillybus. Well
now navigate through the available devices to discover the Xillybus interfaces that can
be accessed directly from the OS. First, open a shell prompt window pressing
Ctrl+Alt+T

Figure 2: Shell prompt in Xillinux

Now, well display the files where the Xillybus pipes are connected to. To do so, type:
root@localhost:~# ls /dev/xillybus_*

A list of the available Xillybus interfaces may appear as shown in Figure 3.

2
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 3: Xillybus interfaces shown in /dev

If everything is built using default configuration, you should see the list as is shown
above. However, if a custom architecture was made using Xillybuss IP-Core Factory,
other interfaces may (dis)appear.

As this is an introductory tutorial, well focus only on 8- and 32- bit read/write interfaces.
This interfaces (or pipes) can be directly accessed through any programming language,
or even from Linux shell prompt as files.

Well be using the following (all of them located at /dev)

xillybus_read_8: synchronous 8-bit FIFO read interface. FPGA -> ARM PS
xillybus_write_8: synchronous 8-bit FIFO write interface. ARM PS -> FPGA
xillybus_read_32: asynchronous 32-bit FIFO read interface. FPGA -> ARM PS
xillybus_write_32: asynchronous 32-bit FIFO write interface. ARM PS -> FPGA

3
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Just a tip
FPGA -> ARM PS means data is being transferred from FPGA to ARM PS
ARM PS stands for ARM Processing System
Asynchronous interfaces use (most of the times) DMA transfers and are mostly
intended to be used in high throughput applications
Synchronous interfaces are intended to be used in low-latency and time-critical
applications
To deepen more on how asynchronous and synchronous memory interfaces
differ, please refer to Xillybus host application programming guide for Linux,
section 2.1

4
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Getting hands-on with Xillybus

Now we will actually start working with Xillybus. The following tests are intended
to be done exclusively if you used the default xillybus_demo.v(hd) demonstration
hardware description files on the PL (programmable logic) side while synthesizing. This
demo infers a loopback FIFO with the mere purpose to reply back everything that is
sent from the ARM PS. In other words, its a ping-pong test.

Well be writing data directly to the xillybus_write_(8/32) buses and wait for a
reply at the xillybus_read_(8/32): this is done by manipulating the pipes, either from
Linux bash, or form a user custom-made app.

Nice thing is that Xillybus provides a set of APIs written in C, which not only
facilitate access to their bus interfaces, but also provide an efficient way to read from
and write to them.

To get started, open two terminal windows (pressing Ctrl+Alt+T twice) and
arrange them as you like. Consider theyll be used simultaneously later on.

Figure 3: Two simultaneous terminal windows

5
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

For this test Linuxs cat utility will be used to read from and write to Xillybus
interfaces. First step is to start listening at the read bus. At the first terminal window
type in:

root@localhost:~# cat /dev/xillybus_read_8

Figure 4: Opening the 8-bit synchronous read interface using linux command shell

As you may have now noticed, well be using the 8-bit bus interface for this
example. When you press <Enter> after writing the command above nothing should
happen, as nothing has been written to that interface yet.

Now lets proceed to write something to the same bus. Obviously, if youre trying
to read something from the 8-bit bus interface, youll also write to it, not to the 32-bit
one. To do so, type in the second linux terminal window (while the first is still open and
running the previous cat command) the following:

root@localhost:~# cat > /dev/xillybus_write_8

This will send everything that is typed with to the bus interface file.

6
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 5: Opening the 8-bit synchronous write interface using linux command shell

Now you can actually start sending data to the bus. Try writing something on the
second window, but youll notice nothing happens until you press <Enter>. This is
because of the way cat handles the input from keyboard, flushing data until you send de
command with the previously mentioned key.

7
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 6: Sharing data through the 8-bit write/read interface with cat command

Now, when youre done having fun transferring characters through the Xillybus,
you may close the channel by pressing Ctrl+C. Its important to notice that even if a
single character was typed and then the <Enter> key was pressed, it was immediately
shown up on the first terminal prompt. Figure 7 shows how everything should look like
after this process.

8
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 7: Closing read and write pipes

Now, open a new pair of terminals or simple use the command clear to clean the
command prompts. Well now proceed to make the same operation, but with the 32-bit
bus interface. Type in the first command prompt the following:

root@localhost:~# cat /dev/xillybus_read_32

Now, on the second command prompt, type the following command:

root@localhost:~# cat > /dev/xillybus_write_32

You may notice this is exactly the same test that was done before, but using the
32-bit bus interface. Its also important to notice that behavior is not exactly the same!

9
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 8: Opening the 32-bit asynchronous interface using linux command shell

Try typing some text down, and maybe it shall be happening the messages are
incomplete at the read side. A nice way to test this out is trying to send a single
character at a time: surprisingly it wont be immediately transferred. Well, there is an
explanation to this phenomenon: data is being transferred in 4-byte chunks (8*4 = 32),
and as every character is an 8-bit ASCII representation (dont forget <Enter> is also an
ASCII code), the data is flushed from the write FIFO every four characters. Some of this
single tests are shown on Figures 9 and 10.

10
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 9: Single characters are not immediately transferred through the 32-bit bus interface

Compare the first and the second command prompts, and notice the read
interface hasnt received everything that has previously been sent through the write bus
interface.

11
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 10: Just another test through the 32-bit bus interface: incomplete characters

Its important to stress this is not a bus malfunction, its simply the way data is
being shared between bus. This is why asynchronous 32-bit width bus interfaces are
intended to be used in streaming high-throughput operations, where pipelining latency is
not a concern to care about (at least, not that much).

Now that basic familiarization with the bus has been achieved, its time to get
hands into the included API functionalities provided by Xillybus. But before starting,
dont forget to close both pipes with Ctrl+C and open a set of new terminal prompts (or
just clean them with the clear command).

12
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Before using the provided API examples, apps must be compiled with gcc.
Xillybus has been kindly enough to also provide a makefile to make things even easier.

In the first command prompt, go to the ~/xillybus/demoapps directory. Just type in

root@localhost:~# cd xillybus/demoapps/

Then, in order to list the available files, type:

root@localhost:~# ls

Figure 11: Demo Apps including Xillybuss API examples

13
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

To compile the Demo Apps (assuming current directory is still

~/xillybus/demoapps/) just type in:

root@localhost:~# make

Figure 12: Compiling Demo Apps with included makefile

Now, clean the first terminal window and be prepared to start using the apps.
Well use the stream application included within the examples. Type into the first
terminal the following command:
root@localhost:~/xillybus/demoapps# ./streamread /dev/xillybus_read_8

On the second terminal prompt, home directory has to be changed to demoapps,

and then, execute the stream writing app
root@localhost:~# cd xillybus/demoapps
root@localhost:~/xillybus/demoapps# ./streamwrite /dev/xillybus_write_8

14
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Syntax for streamread:

./streamread <xillybus_interface_to_read_from>

Syntax for streamwrite:

./streamwrite <xillybus_interface_to_write_to>

Using this applications imply the usage of systems standard I/O (keyboard and
display through command prompt), but API functions can be tweaked to use alternative
sources and sinks instead, which is mostly the case.

You can start playing again with Xillybus, now using API functions, which lead to
a more efficient way to transfer data (for further details, please refer to Getting started
with Xillybus on a Linux host). Notice that each keystroke automatically generates a
data transfer operation to the bus.

Figure 13: Running the stream read/write applications on the 8-bit synchronous bus interface

15
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 14: Transferring data through the 8-bit bus interface using Xillybus C API

Next step is to test the same application, but using the 32-bit asynchronous bus
interface. As its expected, data transfers are done in 4 byte chunks to, so characters
will be flushed from output FIFO once the counter reaches 4 characters. To do so, close
the currently open pipes in both terminal prompts by pressing Ctrl + C. Now, type into
the first terminal the following command:
root@localhost:~/xillybus/demoapps# ./streamread /dev/xillybus_read_32

Further, open the write interface for the same bus with the application on the second
terminal prompt by typing:
root@localhost:~/xillybus/demoapps# ./streamwrite /dev/xillybus_write_32

16
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 15: Transferring data through the 32-bit bus interface using Xillybus C API

At this moment is easy to figure out why, even when data is automatically
transferred without pressing <Enter>, its not immediately sent until 4 bytes accumulate
in the output FIFO.

17
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Figure 16: Using C API again with 32-bit bus interface. Data is grouped in 4-byte chunks

18
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Using the ethernet port directly from Linux

Well, theres not that much to say about. As simply as that: ethernet port is fully
functional as a Ubuntu-based computers ethernet port is. Unfortunately there are some
limitations that lead to a poor performance of this peripheral; however, low bandwidth
applications work nice. This test was done assuming theres a DHCP server enabled to
assign IP addresses in the network the board is going to be connected to, otherwise,
manual IP configuration must be done.

The Hello World! test is a ping test to Google. First, plug an ethernet cable from
the development boards RJ45 connector and wait until a connection is established, as
shown in Figure 17.

Figure 17: Connection established to a LAN

19
 Ivn Ren Morales, Guatemala
Written for MLAB, ICTP
April, 2015

Finally, open a new terminal prompt by pressing Ctrl+Alt+T and type in

root@localhost:~# ping www.google.com

Replies from the server (similar to whats shown in Figure 18) should come out, if
so, youre done! You can even surf the Internet with a web browser, although this is not
the main task this hardware was intended for :)

Figure 18: Replies from an external host connected via ethernet interface

Special thanks to MLABs Staff for providing me with

the tools and support to develop this tutorial:
Dr. Maria Liz Crespo
Dr. Andrs Cicuttin
Grazie mille a tutti!
For any further comment or suggestion, please send an email
ivan@fisica.usac.edu.gt
ivan.rene.morales@gmail.com

20