Merge pull request #17 from casper-astro/workshop2018

Workshop2018 in master

docs/tutorials/skarab/tut_intro.md

@@ -62,7 +62,7 @@ Set it for 1 bit wide with offset from top bit at zero. As you might guess, this
 ![](../../_static/img/tut_intro/Slice_params.png)
 
 #### Add a GPIO block
-From: CASPER XPS library -> gpio.
+From: CASPER XPS library -> IO -> gpio.
 
 ![casper_xps_select_io.png](../../_static/img/tut_intro/casper_xps_select_io.png)
 

docs/tutorials/snap/tut_intro.md

@@ -3,30 +3,32 @@ In this tutorial, you will create a simple Simulink design using both standard X
 
 ## Creating Your Design
 ### Create a New Model
-Start Matlab via executing the <code>startsg</code> command, as described [here](https://casper.berkeley.edu/wiki/Casper_Caltech_Workshop_2017_Tutorials_Help_Page). This ensures that necessary Xilinx and CASPER libraries are loaded into your by Simulink. When MATLAB starts up, open Simulink by typing <i>simulink</i> on the MATLAB command line. Start a new model, and save it with an appropriate name. **With Simulink, it is very wise to save early, and often**.
+Start Matlab via executing the <code>startsg</code> command, as described [here](https://github.com/casper-astro/tutorials_devel/blob/master/workshop_setup.md). This ensures that necessary Xilinx and CASPER libraries are loaded into your by Simulink. When MATLAB starts up, open Simulink by typing <i>simulink</i> on the MATLAB command line. Start a new model, and save it with an appropriate name. **With Simulink, it is very wise to save early, and often**.
 
 There are some Matlab limitations you should be aware-of right from the start:
 
-**Do not use spaces in your filenames** or anywhere in the file path as it will break the toolflow.
-**Do not use capital letters in your filenames** or anywhere in the file path as it will break the toolflow.
-**Beware block paths that exceed 64 characters**. This refers to not only the file path, but also the path to any block within your design. For example, if you save a model file with a name ~/some_really_long_filename.slx, and have a block called <block> in a submodule <submodule> the longest block path would be: some_really_long_filename_submodule_block. If you use lots of subsystems, this can cause problems. 
+- **Do not use spaces in your filenames** or anywhere in the file path as it will break the toolflow.
+- **Do not use capital letters in your filenames** or anywhere in the file path as it will break the toolflow.
+- **Beware block paths that exceed 64 characters**. This refers to not only the file path, but also the path to any block within your design.
+  - For example, if you save a model file with a name ~/some_really_long_filename.slx, and have a block called <block> in a submodule <submodule> the longest block path would be: some_really_long_filename_submodule_block.
+  - If you use lots of subsystems, this can cause problems. 
 
 ### Library organization
 There are three libraries which you will use when you design firmware in Simulink.
-1. The *CASPER XPS Library* contains "Yellow Blocks" -- these are blocks which encapsulate interfaces to hardware (ADCs, Memory chips, CPUs, Ethernet ports, etc.) 
-2. The *CASPER DSP Library* contains (mostly green) blocks which inplement DSP functions, like filters, FFTs, etc.
-3. The *Xilinx Library* contains blue blocks which provide low-level functionality such as multiplexing, delaying, adding, etc. The Xilinx library also contains the super-special System Generator block, which contains information about the type of FPGA you are targeting.
+1. The **CASPER XPS Library** contains "Yellow Blocks" -- these are blocks which encapsulate interfaces to hardware (ADCs, Memory chips, CPUs, Ethernet ports, etc.) 
+2. The **CASPER DSP Library** contains (mostly green) blocks which implement DSP functions such as filters, FFTs, etc.
+3. The **Xilinx Library** contains blue blocks which provide low-level functionality such as multiplexing, delaying, adding, etc. The Xilinx library also contains the super-special System Generator block, which contains information about the type of FPGA you are targeting.
 
 ### Add Xilinx System Generator and XSG core config blocks
 Add a System generator block from the Xilinx library by locating the <i>Xilinx Blockset</i> library's <i>Basic Elements</i> subsection and dragging a <i>System Generator</i> token onto your new file. 
 
-![](../../_static/img/tut_intro/sysgen_select.png)
+![xilinx_select_sysgen.png](../../_static/img/tut_intro/xilinx_select_sysgen.png)
 
 Do not configure it directly, but rather add a platform block representing the system you care compiling for. These can be found in the <i>CASPER XPS System Blockset</i> library. For SNAP (and later) platforms, you need a block which matches the platform name, which can be found in the library under "platforms", as shown below.
 
-![](../../_static/img/tut_intro/Casper_xps_blockset_default_final.png)
+![casper_xps_select_platform.png](../../_static/img/tut_intro/casper_xps_select_platform.png)
 
-![](../../_static/img/tut_intro/Casper_xps_blockset_hw_plat.png)
+![casper_xps_select_platform_skarab.png](../../_static/img/tut_intro/snap_tut_intro_hw_platform.png)
 
 
 Double click on the platform block that you just added. The <i>Hardware Platform</i> parameter should match the platform you are compiling for. Once you have selected a board, you need to choose where it will get its clock. In designs including ADCs you probably want the FPGA clock to be derived from the sampling clock, but for this simple design (which doesn't include an ADC) you should use the platform's on-board clock. To do this, set the <i>User IP Clock Source</i> to <b>sys_clk</b>. The sys_clk rate is 100 MHz, so you should set this for *User IP Clock Rate* in the block.
@@ -42,16 +44,16 @@ To demonstrate the basic use of hardware interfaces, we will make an LED flash.
 #### Add a counter
 Add a counter to your design by navigating to Xilinx Blockset -> Basic Elements -> Counter and dragging it onto your model.
 
-![](../../_static/img/tut_intro/counter_select.png)
+![xilinx_select_counter.png](../../_static/img/tut_intro/xilinx_select_counter.png)
 
 Double-click it and set it for free running, 27 bits, unsigned. This means it will count from 0 to 2^27 - 1, and will then wrap back to zero and continue.
 
-![](../../_static/img/tut_intro/Counter_params.png)
+![xilinx_params_counter_led](../../_static/img/tut_intro/xilinx_params_counter_led.png)
 
 #### Add a slice block to select out the msb
 We now need to select the [most significant bit](http://en.wikipedia.org/wiki/Most_significant_bit) (msb) of the counter. We do this using a slice block, which Xilinx provides. Xilinx Blockset -> Basic Elements -> Slice.
 
-![](../../_static/img/tut_intro/Slice_select.png)
+![Slice_select.png](../../_static/img/tut_intro/Slice_select.png)
 
 Double-click on the newly added slice block. There are multiple ways to select which bit(s) you want.  In this case, it is simplest to index from the upper end and select the first bit. If you wanted the [least significant bit](http://en.wikipedia.org/wiki/Least_significant_bit) (lsb), you can also index from that position. You can either select the width and offset, or two bit locations.
 
@@ -60,13 +62,15 @@ Set it for 1 bit wide with offset from top bit at zero. As you might guess, this
 ![](../../_static/img/tut_intro/Slice_params.png)
 
 #### Add a GPIO block
-From: CASPER XPS library -> gpio.
+From: CASPER XPS library -> IO -> gpio.
 
-![](../../_static/img/tut_intro/Gpio_select.png)
+![casper_xps_select_io.png](../../_static/img/tut_intro/casper_xps_select_io.png)
+
+![casper_xps_select_io_gpio.png](../../_static/img/tut_intro/casper_xps_select_io_gpio.png)
 
 In order to send the 1 bit signal you have sliced off to an LED, you need to connect it to the right FPGA output pin. To do this you can use a GPIO (general-purpose input/output) block from the XPS library, this allows you to route a signal from Simulink to a selection of FPGA pins, which are addressed with user-friendly names. Set it to use SNAP's LED bank as output. Once you've chosen the LED bank, you need to pick *which* LED you want to output to. Set the GPIO bit index to 0 (the first LED) and the data type to Boolean with bitwidth 1. This means your simulink input is a 1 bit Boolean, and the output is LED0.
 
-![](../../_static/img/tut_intro/Gpio_params_r2.png)
+![casper_xps_params_io_gpio.png](../../_static/img/tut_intro/casper_xps_params_io_gpio.png)
 
 #### Add a terminator
 To prevent warnings (from MATLAB & Simulink) about unconnected outputs, terminate all unused outputs using a *Terminator*:
@@ -96,7 +100,7 @@ By the end of this section, you will create a system that looks like this:
 #### Add the software registers ###
 We need two software registers. One to control the counter, and a second one to read its current value. From the CASPER XPS System Blockset library, drag two Software Registers onto your design.
 
-![SW_reg_select2.png](../../_static/img/tut_intro/SW_reg_select2.png)
+![casper_xps_select_memory_swreg.png](../../_static/img/tut_intro/casper_xps_select_memory_swreg.png)
 
 Set the I/O direction to *From Processor* on the first one (counter control) to enable a value to be set from software and sent *to* your FPGA design. Set it to *To Processor* on the second one (counter value) to enable a value to be sent *from* the FPGA to software. Set both registers to a bitwidth of 32 bits.
 
@@ -140,11 +144,11 @@ The enable and reset ports of the counter require boolean values (which Simulink
 
 Slice for enable:
 
-![](../../_static/img/tut_intro/Slice_en.png)
+![casper_xps_params_slice_enable.png](../../_static/img/tut_intro/casper_xps_params_slice_enable.png)
 
 Slice for reset:
 
-![](../../_static/img/tut_intro/Slice_rst.png)
+![casper_xps_params_slice_reset.png](../../_static/img/tut_intro/casper_xps_params_slice_reset.png)
 
 #### Connect it all up
 Now we need to connect all these blocks together. To neaten things up, consider resizing the slice blocks and hiding their names. Their function is clear enough from their icon without needing to see their names.
@@ -156,7 +160,7 @@ Do so by right-clicking and unchecking Format → Show Block Name. You could do
 ### Adder
 To demonstrate some simple mathematical operations, we will create an adder. It will add two numbers on demand and output the result to another software register. Almost all astronomy DSP is done using fixed-point (integer) notation, and this adder will be no different.
 
-We will calculate a+b#sum_a_b.
+We will calculate a+b = sum_a_b.
 
 ![](../../_static/img/tut_intro/Add_sub_circuit.png)
 
@@ -168,7 +172,7 @@ Either copy your existing software register blocks (copy-paste or holding ctrl w
 #### Add the adder block
 Locate the adder/subtractor block, Xilinx Blockset -> Math -> AddSub and drag one onto your design. This block can optionally perform addition or subtraction. Let's leave it set at it's default, for addition.
 
-![](../../_static/img/tut_intro/Add_sub_basic.png)
+![](../../_static/img/tut_intro/xilinx_params_addsub_basic.png)
 
 The output register is 32 bits. If we add two 32 bit numbers, we will have 33 bits.
 
@@ -183,7 +187,7 @@ be a 32 bit saturating adder. On the second tab, set it for user-defined precisi
 
 Also, under overflow, set it to saturate. Now if we add two very large numbers, it will simply return 2^32 -1.
 
-![](../../_static/img/tut_intro/Add_sub_output.png)
+![](../../_static/img/tut_intro/xilinx_params_addsub_output.png)
 
 #### Add the scope and simulation inputs
 Either copy your existing scope and simulation constants (copy-paste or ctrl-drag) or place a new one from the library as before. Set the values of the simulation inputs to anything you like.
@@ -202,11 +206,11 @@ You can watch the simulation progress in the status bar in the bottom right. It
 
 You can double-click on the scopes to see what the signals look like on those lines. For example, the one connected to the counter should look like this:
 
-![](../../_static/img/tut_intro/Counter_sim.png)
+![](../../_static/img/tut_intro/scope_counter.png)
 
 The one connected to your adder should return a constant, equal to the sum of the two numbers you entered. You might have to press the Autoscale button to scale the scope appropriately.
 
-![](../../_static/img/tut_intro/Adder_sim.png)
+![](../../_static/img/tut_intro/scope_sum_with_model.png)
 
 Once you have verified that that design functions as you'd like, you're ready to compile for the FPGA...
 
@@ -219,7 +223,7 @@ In order to compile this to an FPGA bitstream, execute the following command in
 ```
 When a GUI pops up, click "Compile!". This will run the complete build process, which consists of two stages. The first involving Xilinx's System Generator, which compiles any Xilinx blocks in your Simulink design to a circuit which can be implemented on your FPGA. While System Generator is running, you should see the following window pop up:
 
-![](../../_static/img/tut_intro/Jasper_sysgen_SKARAB.png)
+![](../../_static/img/tut_intro/Jasper_sysgen_SNAP.png)
 
 After this, the second stage involves synthesis of your design through Vivado, which goes about turning your design into a physical implementation and figuring out where to put the resulting components and signals on your FPGA. Finally the toolflow will create the final output fpg file that you will use to program your FPGA. This file contains the bitstream (the FPGA configuration information) as well as meta-data describing what registers and other yellow blocks are in your design. This file will be created in the 'outputs' folder in the working directory of your Simulink model. **Note: Compile time is approximately 15-20 minutes**.
 
@@ -232,7 +236,7 @@ Once you are familiar with the CASPER toolflow, you might find you want to run t
 ```
 After this is completed, the last message printed will tell you how to finish the compile. It will look something like:
 ```bash
- 'python /path_to/mlib_devel/jasper_library/exec_flow.py -m /home/user/path_to/snap/tut_intro/snap_tut_intro.slx --middleware --backend --software'
+$ python /path_to/mlib_devel/jasper_library/exec_flow.py -m /home/user/path_to/snap/tut_intro/snap_tut_intro.slx --middleware --backend --software
  ```
 You can run this command in a separate terminal, after sourcing appropriate environment variables. Not recommended for beginners.
 
@@ -253,21 +257,25 @@ SSH into the server that the SNAP board is connected to and navigate to the fold
 
 Start interactive python by running:
 ```bash
-ipython
+$ ipython
 ```
+
 Now import the fpga control library. This will automatically pull-in the KATCP library and any other required communications libraries.
 ```python
 import casperfpga
 ```
+
 To connect to the board we create a CasperFpga instance; let's call it fpga. The CasperFpga constructor requires just one argument: the IP hostname or address of your FPGA board.
 ```python
-fpga = casperfpga.CasperFpga('<snap hostname or ip_address>')
+fpga = casperfpga.CasperFpga('SNAP hostname or ip_address')
 ```
+
 The first thing we do is program the FPGA with the .fpg file which your compile generated.
 
 ```python
-fpga.upload_to_ram_and_program('<your_fpgfile.fpg>')
+fpga.upload_to_ram_and_program('your_fpgfile.fpg')
 ```
+
 Should the execution of this command return true, you can safely assume the FPGA is now configured with your design. You should see the LED on your board flashing. Go check! All the available/configured registers can be displayed using:
 ```python
 fpga.listdev()
@@ -278,13 +286,16 @@ fpga.write_int('a',10)
 fpga.write_int('b',20)
 fpga.read_int('sum_a_b')
 ```
+
 With any luck, the sum returned by the FPGA should be correct.
 
 You can also try writing to the counter control registers in your design. You should find that with appropriate manipulation of the control register, you can make the counter start, stop, and return to zero.
+
 ```python
 fpga.write_int('counter_ctrl',10')
 fpga.read_uint('counter_value')
 ```
+
 ## Conclusion
 This concludes the first CASPER Tutorial. You have learned how to construct a simple Simulink design, program an FPGA board and interact with it with Python using [casperfpga](https://github.com/casper-astro/casperfpga). Congratulations!