Roach_Tutorial - david-macmahon/wiki_convert_test GitHub Wiki

In this tutorial, you will create a simple Simulink design using both standard Xilinx system generator blockset, as well as library blocks specific to ROACH. At the end of this tutorial, you will have a BORPH executable file, a BOF file, and you will know how to interact with your running hardware design using BORPH.

Before you start, you have to make sure you have set up the path variables BEE2_XPS_LIB_PATH and MLIB_ROOT in Matlab correctly, pointing to xps_lib in mlib_devel_10_1. For instance, there should be two lines in the batch script that starts Matlab that look like this:

• set MLIB_ROOT=<WORKING_DIRECTORY>\mlib_devel_10_1 set BEE2_XPS_LIB_PATH=%MLIB_ROOT%\xps_lib

Also, when Matlab starts up it runs startup.m if it exists. To let Matlab/Simulink know where the correct libraries are, you should add the lines:

• addpath('<WORKING_DIRECTORY>\mlib_devel_10_1\bee_library'); addpath('<WORKING_DIRECTORY>\mlib_devel_10_1\xps_library'); addpath('<WORKING_DIRECTORY>\mlib_devel_10_1\casper_library'); addpath('<WORKING_DIRECTORY>\mlib_devel_10_1\gavrt_library');

Where <WORKING_DIRECTORY> should be replaced with the directory where you checked out the libraries. Once Matlab is started, you can start Simulink by typing 'simulink' in the Matlab prompt. If your path is setup correctly, you should see among other libraries, the BEE_XPS System Blockset, CASPER DSP Blockset, GAVRT_BLOCKSET, and Xilinx Blockset.

1. Create a new model:

2. Select Xilinx Blockset:

3. Add 1 instance of Counter and 1 instance of System Generator <br\> 4. Double-click on Counter

• i. Set Number of Bits to 32 ii. Check the box next to Provide Enable Port iii. Select OK

You should have a design that looks like this:

5. It is a good time to save this new design. In this tutorial, we will call it "testborph". 6. Now, select BEE_XPS System Blockset:

7. Add 1 instance of XSG core config and 2 instances of software register:

Name the instance of sofware register on the left of Counter as cnt_en, while naming the other instance as cnt_val. <br\>

8. Double-click on the software register named cnt_en and select I/O direction as From Processor. Note the field Data bitwidth is greyed out with a value 32. It is because all software registers have a fixed data bitwidth of 32 bits.<br\>

9. Since we want to control the en port of Counter, which takes a Boolean input, we need a way to extract 1 bit out of this 32-bits software register. That's why we need to add one more block, a Slice from the Xilinx Blockset. Add an instance of Slice from the Xilinx Blockset to our design, connecting it between the cnt_en software register and the counter.

10. Double-click on the newly added Slice block to set it's parameter:

11. In order to generate a BOF file from this Simulink design using our Matlab Simulink System Generator EDK (MSSGE) flow, we will need to add one final block: a XSG Core Confing block from the BEE_XPS System Blockset. Furthermore, for the sake of simulating your design within Simulink, as well as to make our MSSGE flow run correctly, you will need to connect up the sim_in/sim_out port of any software registers. In Simulink, the Scope and Pulse Generator are under Sinks and Sources respectively. If you don't intend to simulate your design in Simulink, simply connect a constant block to the input of any software register. You now have a design that looks like this:

12. Save your work. You now have a fully functional design that is ready to be run on ROACH

To generate a BOF file from your design, you must first specify the target platform and the synthesis tool to be used.

1. Double-click the XSG core config block. For a design to be run on ROACH, select ROACH:sx95t or ROACH:lx110t depending on the FPGA you're using. Selecting XST for synthesis tool is sufficient for most designs.

2. Once that's done, click OK and save your work.<br\> 3. Now, go to the Matlab prompt, and type bee_xps:

matlab>> bee_xps

4. You should see a new window pops up like this:

5. Make sure the name showing on the top of this new window corresponds to the design you want to generate your BOF file. (If it is not, click anywhere on your design such that it is the highlighted window, then click gcs.)<br\> 6. Finally, click Run XPS. Once the MSSGE script has finished, it should have created a subdirectory with your design name in the directory where you saved your design. For example, if your design is saved in a directory FOO, then if you list the content of the directory, you will see:

user@local$ ls -lF FOO drwxrwxrwx  7 user grp  4096 May 15 12:12 testborph/ -rwxrwxrwx  1 user grp 36370 May 15 13:21 testborph.mdl

Inside the directory testborph is a directory called bit_files, which contains 1 .bit file and 1 BOF file. For this tutorial, focus only on the one with name <design_name>_<date_time>.bof. This BOF file is what we will use now. Feel free to rename it to a shorter name if you want.

Running your design is as simple as running a compiled software program from a compiler: All you need is to execute the floating BOF file within BORPH as if it is any other executable file in the system.

The exact way of transferring a BOF file to the ROACH depends on your system setup. For BWRC setup, the easiest way is to copy BOF files to the ROACH system by using scp from wright.eecs.berkeley.edu:

user@wright$ scp testborph.bof user@zuul:/srv/roachfs/etch/boffiles

Where zuul is the server at the BWRC that exports the ROACH filesystem (/srv/roachfs) and BORPH kernel using the NFS protocol. In any case, once you have copied your BOF files, log on to your ROACH and execute your BOF file like this (using 'roach' as an example):

user@zuul$ ssh user@roach roach:~# ls roach:~# cd /boffiles roach:/boffiles# ls  testborph.bof roach:/boffiles#./testborph.bof &

That's it, you have just launched a hardware process in BORPH. You can see if your Simulink hardware is running by the command ps:

roach:/boffiles# ps  PID TTY          TIME CMD  318 pts/0    00:00:00 bash  346 pts/0    00:00:00 testborph_2009_  372 pts/0    00:00:00 ps

Once your hardware process is running, you can interact with it through the ioreg interface of BORPH. Without going into the detail, assume your hardware process is running with process ID (PID) of 346 as shown above, issue the following commands:

roach:~/# cd /proc/346/hw/ioreg

roach:/proc/346/hw/ioreg# ls
cnt_en   sys_board_id    sys_clkfreq  sys_rev_rcs
cnt_val  sys_clkcounter  sys_rev      sys_scratchpad

The two "software registers" you put in your design now show up automatically on Linux side. These are binary files, but you can check the current values of by using hexdump (hd):

roach:/proc/346/hw/ioreg# cat cnt_en | hd 00000000  00 00 00 00                                       |....| 00000004

roach:/proc/346/hw/ioreg# cat cnt_val | hd 00000000  00 00 00 00                                       |....| 00000004

The column on the left tells us the memory addresses, while the four space separated values on the right give us the 4 byte (32 bit) value of the software register in hexidecimal. Right now, both registers report all zeros. According to our Simulink design, we can disable or enable the counter by setting cnt_en to 0 or 1 respectively:

roach:/proc/346/hw/ioreg# echo -n -e "\000\000\000\001" > cnt_en roach:/proc/346/hw/ioreg# cat cnt_en | hd 00000000  00 00 00 01                                       |....| 00000004

Now let's see if our counter is actually counting:

roach:/proc/346/hw/ioreg# cat cnt_val | hd 00000000  9d af 3d d0                                       |..=.| 00000004 roach:/proc/346/hw/ioreg# cat cnt_val | hd 00000000  a2 bd 93 ad                                       |....| 00000004

If you run the above command repeatedly, you should see the register values increasing until they reach 2^32-1 and then repeat. This method of accessing the shared memory and registers is good for quick verification that your design is running and loaded correctly, but for more advanced command, control and data acquisition, we recommend using the tcpborphserver and KATCP that starts up automatically when booting ROACH. For mor information on this, see: KATCP.

In this tutorial, you have leaned how to create an executable BOF file from Simulink. You have also learned the basics of running a hardware design in BORPH and interating with it using BORPH's ioreg interface.