Preamble

This guide includes details for developers, such as setting up a development environment for camera FPGA development and building and testing firmware images.

1 Gateware

One of the major components of the Axiom-Beta Firmware is the FPGA gateware for the Zynq Programmable logic (PL). The Bitstreams are currently not build in the CI due to the requirement of proprietary software.

1.1 Setup Development Environment

The camera gateware is developed using Xilinx Vivado Design Suite. To setup a development environment where you can modify FPGA related code and build a bitstream, do the following:

1. Download and install Vivado. You can install a trial version that is good for 30 days but is otherwise unrestricted and will allow you to build the bitstream. After that you can purchase a license, or use the WebPACK version for free, which is completely sufficient for the fpga used in the AXIOM Beta. If you have purchased a Zedboard you may be eligible to receive a license included with your purchase.

2. Download the MicroZed Vivado board definition files. Extract the zip file and put the files in your Vivado installation directory ~data\boards\board_files.

3. Clone the beta git repo.

4. If necessary, you may need to update the BOARD_PART property in the build script of your cloned firmware repo vivado.tcl to match the version of your board definition files. To view of a list of valid board_parts you can enter the command get_board_parts in the Vivado Tcl Console. Make sure you have put the above board part files in the proper directory and the version board version is correct.

1.2 Building Gateware

The actual beta FPGA gateware for the zynq pl is located under peripherals/soc_main, and is built using the Vivado build script vivado.tcl in that directory.

To build the gateware (in directory where you checked out axiom-beta-firmware):

1. [axiom-beta-firmware] $ cd peripherals/soc_main

2. [soc_main] $ mkdir build && cd build

3. [build] $ vivado -source ../vivado.tcl (assuming vivado is in your PATH, on Linux it is normally installed under /tools/Xilinx/Vivado/<version>/bin/vivado)

Vivado should launch the GUI and begin building the source files. If successful, you should end up with a cmv_hdmi3.bit in your build directory. This is the actual fpga bitstream and can be copied to the camera directly for testing.

1.3 Testing Gateware

1.3.1 On Camera Hardware

Bitstream files are normally installed to /opt/BITS on the camera. A symlink in the camera root user's home directory controls which bit is loaded to the FPGA on startup. The easyest way to load the new bitstream is to reboot the whole device. To test a built bitstream on camera hardware, do the following:

1. Transfer the firmware bit file to the camera. (in your build directory):

$ scp ./cmv_hdmi3.bit root@beta:/opt/BITS/cmv_hdmi3-test.bit

2. Delete the existing symlink and link to your new bitstream. (on the camera):

~$ rm -f cmv_hdmi3.bit && ln -s /opt/BITS/cmv_hdmi3-test.bit ./cmv_hdmi3.bit

3. Reboot the camera:

~$ sync && reboot now

If all goes well the camera should reboot and load your new development FPGA gateware.

1.4 Custom HDMI Output Modes

The Axiom Beta currently supports a few different HDMI output video modes, namely 1080P60 and 1080P50. You may need to add a new mode to support your HDMI display or recording device. The general process is as follows:

1. Find out the mode timing parameters of your display device and the output mode you want to support. This can be done by looking up your device in the [EDID database http://edid.tv/edid/469/]. Try to get as much information as possible, you are looking for detailed timing information that includes the pixel clock frequency, blanking, horizontal/vertical offsets, etc. You can also dump EDID information by connecting the device to your laptop or PC and running a edid dump command. Another good way is to use a raspberry pi and dump the parameters using the commands tvservice and edidparser. This also allows you the benefit of testing modes via the raspberry pi to make sure they are correct before trying to get them working on axiom beta.

2. Create a new, empty Vivado project for the MicroZed Board (do not add any source files), and open the IP Integrator section.

3. Add a clocking wizard and auto-configure the pins.

4. Double-click on the clocking wizard to show the configuration and under the Output Clocks tab, enter the desired frequency of your video mode's pixel clock multiplied by 5. For example, if your clock is 146 MHz, specify 730 MHz.

5. Note the parameters under MMCM Settings.

6. In your checked out copy of axiom-beta-firmware, open the file peripherals/soc_main/hdmi_pll.vhd.

7. Add a new HDMI clock timings mode under hdmi_config_a. Three clocks need to be specified, one for the pixel data clock, a tmds clock, and the actual hdmi clock. The tmds_clk needs to be the pixel clock multiplied by 5 as found from the parameters above. The other two clocks can be divided by 5 or another number to get the desired pixel clock (based on the value of DIVCLK_DIVIDE). Look at the other HDMI clock configuration items for some examples.

As an example, here is a clock config for a 146 MHz pixel clock:

HDMI_146MHZ => (
    CLKIN1_PERIOD => 10.000,
    CLKFBOUT_MULT_F => 36.500,
    DIVCLK_DIVIDE => 5,
    --
    CLKOUT0_DIVIDE_F => 1.0,
    CLKOUT1_DIVIDE => 5,
    CLKOUT2_DIVIDE => 5,
    --
    CLKOUT0_PHASE => 0.0,
    CLKOUT1_PHASE => 0.0,
    CLKOUT2_PHASE => 0.0
)

This equates to a 146 MHz pixel clock and 730 MHz tmds clock.