Part 4 - Modify & rebuild previous Firmware & Software projects then deploy on Zedboard

This tutorial details the steps required to create Firmware with Vivado & Software with Vitis to allow access to the LEDs & Push Buttons on the Zedboard via a GPIO module. The Firmware will be setup to generate interrupts from the Push Buttons and the software setup to handle these interrupts and control the LEDs. The tutorial covers generation of Programmable Logic (PL) & Processor System (PS) for the Zynq-7000 SoC using the previous project as a starting point. Deployment of the PL & PS images will be via JTAG and the resulting output provided via a UART upto the host PC.

Setup Xilinx design environment for the 2021.2 toolset.

steve@Desktop:~$ xilinx
Xilinx tools available tools at /opt/Xilinx :-
1) 2021.2 - Vivado - SDK - Vitis - PetaLinux
0) Exit
Please select tools required or exit : 1

Tools are as follows :-
vivado @ /opt/Xilinx/Vivado/2021.2/bin/vivado
vitis @ /opt/Xilinx/Vitis/2021.2/bin/vitis
petalinux-build @ /opt/Xilinx/PetaLinux/2021.2/tool/tools/common/petalinux/bin/petalinux-build

This project is going to be a branch of the previous project as that project is a very good starting point for this one. Clone the previous project (zedboard_leds_switches) into a new project directory (zedboard_leds_buttons) and switch to the v1.0 tag. Change the present working directory (pwd) to be at the project root and rename the main software file to suit the new project name.

steve@Desktop:~$ cd ~/projects
steve@Desktop:~/projects$ git clone git@192.168.2.20:zedboard_leds_switches.git zedboard_leds_buttons
steve@Desktop:~/projects$ cd zedboard_leds_buttons
steve@Desktop:~/projects/zedboard_leds_buttons$ git checkout -b zedboard_leds_buttons v1.0
steve@Desktop:~/projects/zedboard_leds_buttons$ git mv sw/src/c/zedboard_leds_switches.c sw/src/c/zedboard_leds_buttons.c

To recreate the Vivado project from its sources execute the Create Vivado Project shell script.

steve@Desktop:~/projects/zedboard_leds_buttons$ create_vivado_project.sh

The Vivado GUI should now appear and be executing the create_vivado_project.tcl script to recreate the zedboard_leds_switches project inside the zedboard_leds_buttons directory. The Vivado cockpit window should show the newly created zedboard_leds_buttons project. Missing Image!

Once Vivado completes execution of the Tcl script open the block design by clicking on Open Block Design under the IP INTEGRATOR heading inside the Flow Navigator section. Expand the Diagram by clicking on the Float Missing Image!

icon in the Diagram pane inside the BLOCK DESIGN section.

Double click on the ZYNQ7 Processing System module to begin re-customization.

An interrupt input is required for this design to allow triggered communication from the GPIO to the ZYNQ7 Processing System To enable the IRQ_F2P connection select Interrupts, expand Fabric Interrupts, expand PL-PS Interrupt Ports, tick Fabric Interrupts and then tick Fabric Interrupts. Missing Image!

Click OK to commit the changes.

Double click on the AXI GPIO module to begin re-customization.

Connections to both the LED's and Push Buttons on the ZedBoard are required for this design. Change the GPIO Width parameter in the GPIO2 section from 8 to 5. Connection to the interrupt output ip2intc_irpt on the AXI GPIO is also required. To enable this tick Enable Interrupt. Missing Image!

Click OK to commit the changes.

To connect up the interrupt, left click (keeping the mouse button held down afterwards) on the ip2intc_irpt output of the AXI GPIO and drag the new connection across to the IRQ_F2P input of the ZYNQ7 Processing System, release the mouse button once the connection is established. Missing Image!

Rename the external port that GPIO2 is connected to so it has a more meaningful name. Highlight switches and goto the Vivado cockpit window, in the External Interface Properties under BLOCK DESIGN change the Name field from switches to buttons. Missing Image!

The block design should now reflect the changes. Missing Image!

Verify the block design is error free by clicking on the Validate Design Missing Image!

icon. Once validated save the block design and return the floating Diagram pane back to Vivado by clicking on the Dock Missing Image!

icon.

Using the zedboard_master_XDC_RevC_D_v3.xdc from ~/projects/common/fw/src/constraint as a reference the constraints from the previous project can be adjusted to suit this project.

Double click on the existing constraints zedboard.xdc within Sources » Constraints » constrs_1 to edit. Missing Image!

Adjust zedboard.xdc and save the file.

zedboard.xdc

# User LEDs - Bank 33
set_property PACKAGE_PIN T22 [get_ports {leds_tri_o[0]}];  # "LD0"
set_property PACKAGE_PIN T21 [get_ports {leds_tri_o[1]}];  # "LD1"
set_property PACKAGE_PIN U22 [get_ports {leds_tri_o[2]}];  # "LD2"
set_property PACKAGE_PIN U21 [get_ports {leds_tri_o[3]}];  # "LD3"
set_property PACKAGE_PIN V22 [get_ports {leds_tri_o[4]}];  # "LD4"
set_property PACKAGE_PIN W22 [get_ports {leds_tri_o[5]}];  # "LD5"
set_property PACKAGE_PIN U19 [get_ports {leds_tri_o[6]}];  # "LD6"
set_property PACKAGE_PIN U14 [get_ports {leds_tri_o[7]}];  # "LD7"


# User DIP Switches - Bank 34 & 35
set_property PACKAGE_PIN F22 [get_ports {switches_tri_i[0]}];  # "SW0"
set_property PACKAGE_PIN G22 [get_ports {switches_tri_i[1]}];  # "SW1"
set_property PACKAGE_PIN H22 [get_ports {switches_tri_i[2]}];  # "SW2"
set_property PACKAGE_PIN F21 [get_ports {switches_tri_i[3]}];  # "SW3"
set_property PACKAGE_PIN H19 [get_ports {switches_tri_i[4]}];  # "SW4"
set_property PACKAGE_PIN H18 [get_ports {switches_tri_i[5]}];  # "SW5"
set_property PACKAGE_PIN H17 [get_ports {switches_tri_i[6]}];  # "SW6"
set_property PACKAGE_PIN M15 [get_ports {switches_tri_i[7]}];  # "SW7"


# Banks
set_property IOSTANDARD LVCMOS33 [get_ports -of_objects [get_iobanks 33]];
set_property IOSTANDARD LVCMOS18 [get_ports -of_objects [get_iobanks 34]];
set_property IOSTANDARD LVCMOS18 [get_ports -of_objects [get_iobanks 35]];

Direct download available here :-

steve@Desktop:~/projects/zedboard_leds_buttons$ wget https://spacewire.co.uk/tutorial/shared/repos/0004/zedboard_leds_buttons/fw/src/constraint/zedboard.xdc -O fw/src/constraint/zedboard.xdc

Create a very simple testbench to check basic connectivity.

Details to follow...

steve@Desktop:~/projects/zedboard_leds_buttons$ subl fw/src/testbench/testbench.sv

testbench.sv

//
// File .......... testbench.sv
// Author ........ Steve Haywood
// Version ....... 1.0
// Date .......... 22 December 2021
// Description ...
//   Very simple testbench to check correct connectivity of the block diagram.
// Uses the Zynq Verification IP suite to read/write the GPIO LED register and
// read the GPIO switch register.
// 


timeunit      1ns;
timeprecision 1ps;


module testbench;

  // Constants
  localparam [31:0] led_addr = 32'h41200000;
  localparam [31:0] sws_addr = 32'h41200008;
  localparam [31:0] led_init = 32'h00000018;
  localparam [31:0] led_next = 32'h00000081;
  localparam [ 7:0] sws_next =  8'b11000011;


  // Signals
  wire       ps_clk;
  wire       ps_porb;
  wire       ps_srstb;
  bit [ 7:0] leds_8bits;
  bit [ 7:0] sws_8bits;
  bit        clk;
  bit        resetn;
  bit        bresp;
  bit [31:0] rdata;
  bit        rresp;


  // 50MHz Clock
  always #10 clk = !clk;


  // Reset
  initial begin
    repeat(20)
      @(posedge clk);
    resetn = 1'b1;
  end


  // Drive PL Clock & Reset
  assign ps_clk   = clk;
  assign ps_porb  = resetn;
  assign ps_srstb = resetn;


  // Stimulus
  initial begin
    // Allow reset time to work

    @(posedge resetn);
    repeat(10)
      @(posedge clk);

    // Reset PL
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.fpga_soft_reset(32'h1);
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.fpga_soft_reset(32'h0);

    // Read GPIO LED Register
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.read_data(led_addr, 4, rdata, rresp);
    $display ("Read of GPIO LED Register = 32'h%x (%s)", rdata, (rdata == led_init) ? "expected" : "unexpected");

    // Write GPIO LED Register
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.write_data(led_addr, 4, led_next, bresp);

    // Read GPIO LED Register
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.read_data(led_addr, 4, rdata, rresp);
    $display ("Read of GPIO LED Register = 32'h%x (%s)", rdata, (rdata == led_next) ? "expected" : "unexpected");

    // Set some of the switches to 'on'
    sws_8bits = sws_next;

    // Read GPIO Switch Register
    testbench.system_wrapper_i.system_i.processing_system7_0.inst.read_data(sws_addr, 4, rdata, rresp);
    $display ("Read of GPIO Switch Register = 32'h%x (%s)", rdata, (rdata == sws_next) ? "expected" : "unexpected");

    // All done
    $display ("That's all folks!");
    $stop;

  end


  // Unit Under Test
  system_wrapper system_wrapper_i
   (
    // LEDs
    .leds_tri_o        ( leds_8bits ),  // O:LEDs
    // Switches
    .switches_tri_i    ( sws_8bits  ),  // I:Switches
    // System
    .DDR_addr          (            ),  // B:Address
    .DDR_ba            (            ),  // B:Bank Address
    .DDR_cas_n         (            ),  // B:Column Address Select
    .DDR_ck_n          (            ),  // B:Clock (Neg)
    .DDR_ck_p          (            ),  // B:Clock (Pos)
    .DDR_cke           (            ),  // B:Clock Enable
    .DDR_cs_n          (            ),  // B:Chip Select
    .DDR_dm            (            ),  // B:Data Mask
    .DDR_dq            (            ),  // B:Data Input/Output
    .DDR_dqs_n         (            ),  // B:Data Strobe (Neg)
    .DDR_dqs_p         (            ),  // B:Data Strobe (Pos)
    .DDR_odt           (            ),  // B:Output Dynamic Termination
    .DDR_ras_n         (            ),  // B:Row Address Select
    .DDR_reset_n       (            ),  // B:Reset
    .DDR_we_n          (            ),  // B:Write Enable
    .FIXED_IO_ddr_vrn  (            ),  // B:Termination Voltage
    .FIXED_IO_ddr_vrp  (            ),  // B:Termination Voltage
    .FIXED_IO_mio      (            ),  // B:Peripheral Input/Output
    .FIXED_IO_ps_clk   ( ps_clk     ),  // B:System Reference Clock
    .FIXED_IO_ps_porb  ( ps_porb    ),  // B:Power On Reset
    .FIXED_IO_ps_srstb ( ps_srstb   )   // B:External System Reset
   );


endmodule

Direct download available here :-

steve@Desktop:~/projects/zedboard_leds_buttons$ wget https://spacewire.co.uk/tutorial/shared/repos/0004/zedboard_leds_buttons/fw/src/testbench/testbench.sv -O fw/src/testbench/testbench.sv

Generate the programmable logic bitstream by clicking on Generate Bitstream under the PROGRAM AND DEBUG heading inside the Flow Navigator section.

Export the hardware platform by selecting File » Export » Export Hardware... from the main menu. Include the bitstream in the exported hardware file and save as ~/projects/zedboard_leds_buttons/fw/system_wrapper.xsa.

To recreate the Vitis project from its sources execute the Create Vitis Project shell script.

steve@Desktop:~/projects/zedboard_leds_buttons$ create_vitis_project.sh

The Vitis GUI should now appear and be executing the create_vitis_project.tcl script to recreate the zedboard_leds_switches project inside the zedboard_leds_buttons directory.

Close the Welcome tab by clicking on the X to the right of Welcome. Missing Image!

The Vitis cockpit window should now show the newly created zedboard_leds_buttons project. Missing Image!

Edit the main source file by double clicking on zedboard_leds_buttons.c inside the Explorer tab under zedboard_leds_buttons_system » zedboard_leds_buttons » src. Missing Image!

Remove all of the existing code from the previous project and replace it with something similar to the following.

zedboard_leds_buttons.c

//
// File .......... zedboard_leds_buttons.c
// Author ........ Steve Haywood
// Version ....... 1.0
// Date .......... 15 January 2022
// Description ...
//   Very simple LEDs & Push Buttons interrupt example design.
//


//
// Includes
//
#include "xparameters.h"
#include "xgpio.h"
#include "xscugic.h"
#include "xil_exception.h"
#include <stdio.h>


//
// Defines
//
#define CHANNEL_LEDS 1
#define CHANNEL_BTNS 2

#define BUTTON_CENTER 0x01
#define BUTTON_DOWN   0x02
#define BUTTON_LEFT   0x04
#define BUTTON_RIGHT  0x08
#define BUTTON_UP     0x10

//
// Global Variables
//
static XScuGic Intc;


//
// Instances
//
XGpio Gpio;


//
// Rotate right
//
u8 ror(u8 num) {
  return (num >> 1) | (num << 7);
}


//
// Rotate left
//
u8 rol(u8 num) {
  return (num << 1) | (num >> 7);
}


//
// Interrupt service routine
//
void GpioIsr(void *InstancePtr)
{
  u32 btns;
  u32 leds;
  u8 width = 0;

  XGpio *GpioPtr = (XGpio *)InstancePtr;

  // Disable button interrupts
  XGpio_InterruptDisable(GpioPtr, XGPIO_IR_CH2_MASK);

  // Only deal with button interrupts
  if ((XGpio_InterruptGetStatus(GpioPtr) & XGPIO_IR_CH2_MASK) != XGPIO_IR_CH2_MASK) {
    return;
  }

  // Obtain register values for LED's & buttons
  leds = XGpio_DiscreteRead(&Gpio, CHANNEL_LEDS);
  btns = XGpio_DiscreteRead(&Gpio, CHANNEL_BTNS);

  // Print button status
  xil_printf("ISR called, button register = 0x%x\n\r", btns);

  // Determine LED bar width
  for (u8 i=0; i<=7; i++) {
    if ((0b00000001 << i) & leds) {
      width++;
    }
  }

  // Handle button functionality
  switch (btns) {

    // Set LED bar width to 4
    case BUTTON_CENTER :
      leds = 0b00111100;
      break;

    // Rotate LED's left
    case BUTTON_LEFT :
      if (width == 0) {
        leds = 0b00000001;
      } else {
        leds = (u8)rol(leds);
      }
      break;

    // Rotate LED's right
    case BUTTON_RIGHT :
      if (width == 0) {
        leds = 0b10000000;
      } else {
        leds = (u8)ror(leds);
      }
      break;

    // Increase illuminated LED's
    case BUTTON_UP :
      if (width == 0) {
    	leds = 0b00001000;
      } else if (width & 1) {
        leds = leds | rol(leds);
      } else {
        leds = leds | ror(leds);
      }
      break;

    // Decrease illuminated LED's
    case BUTTON_DOWN :
      if (width == 8) {
    	leds = 0b01111111;
      } else if (width & 1) {
        leds = leds & rol(leds);
      } else {
        leds = leds & ror(leds);
      }
      break;

    // Do nothing
    default:
      break;
  }

  // Update LED's
  XGpio_DiscreteWrite(&Gpio, CHANNEL_LEDS, leds);

  // Clear pending interrupts
  XGpio_InterruptClear(GpioPtr, XGPIO_IR_CH2_MASK);

  // Enable button interrupts
  XGpio_InterruptEnable(GpioPtr, XGPIO_IR_CH2_MASK);
}


//
// Setup interrupt system
//
int SetupInterruptSystem()
{
  int Result;
  XScuGic *IntcInstancePtr = &Intc;

  XScuGic_Config *IntcConfig;

  // Initialise interrupt controller
  IntcConfig = XScuGic_LookupConfig(XPAR_PS7_SCUGIC_0_DEVICE_ID);
  if (NULL == IntcConfig) {
    return XST_FAILURE;
  }

  // Comment
  Result = XScuGic_CfgInitialize(IntcInstancePtr, IntcConfig, IntcConfig->CpuBaseAddress);
  if (Result != XST_SUCCESS) {
    return XST_FAILURE;
  }

  // Comment
  XScuGic_SetPriorityTriggerType(IntcInstancePtr, XPAR_FABRIC_AXI_GPIO_0_IP2INTC_IRPT_INTR, 0xA0, 0x3);

  // Connect interrupt handler
  Result = XScuGic_Connect(IntcInstancePtr, XPAR_FABRIC_AXI_GPIO_0_IP2INTC_IRPT_INTR, (Xil_ExceptionHandler)GpioIsr, &Gpio);
  if (Result != XST_SUCCESS) {
    return Result;
  }

  // Enable GPIO interrupt
  XScuGic_Enable(IntcInstancePtr, XPAR_FABRIC_AXI_GPIO_0_IP2INTC_IRPT_INTR);

  // Enable button interrupts
  XGpio_InterruptEnable(&Gpio, XGPIO_IR_CH2_MASK);

  // Enable GPIO interrupts
  XGpio_InterruptGlobalEnable(&Gpio);

  // Initialise the exception table
  Xil_ExceptionInit();

  // Register interrupt controller handle with exception table
  Xil_ExceptionRegisterHandler(XIL_EXCEPTION_ID_INT, (Xil_ExceptionHandler)XScuGic_InterruptHandler, IntcInstancePtr);

  // Enable non-critical exceptions
  Xil_ExceptionEnable();

  return XST_SUCCESS;
}


//
// Main function
//
int main(void)
{
  int Status;

  // Initialise GPIO driver
  Status = XGpio_Initialize(&Gpio, XPAR_AXI_GPIO_0_DEVICE_ID);
  if (Status != XST_SUCCESS) {
    return XST_FAILURE;
  }

  // Clear LED's
  XGpio_DiscreteWrite(&Gpio, CHANNEL_LEDS, 0);

  // Setup interrupt system
  Status = SetupInterruptSystem();
  if (Status != XST_SUCCESS) {
    return XST_FAILURE;
  }

  // Print header
  print("--== LED & Push Buttons interrupt example ==--\n\n\r");
  print("Use the buttons to control the LED's :-\n\n\r");
  print("Centre - Reset LED's to 00111100\n\r");
  print("Left   - Rotate LED's left\n\r");
  print("Right  - Rotate LED's right\n\r");
  print("Up     - Increase illuminated LED's\n\r");
  print("Down   - Decrease illuminated LED's\n\n\r");
  print("Press enter key to quit application\n\r");

  // Wait for user input
  getc(stdin);

  // Clear LED's
  XGpio_DiscreteWrite(&Gpio, CHANNEL_LEDS, 0);

  // Print footer
  print("All done!\n\n\r");

  return XST_SUCCESS;
}

Direct download available here :-

steve@Desktop:~/projects/zedboard_leds_buttons$ wget https://spacewire.co.uk/tutorial/shared/repos/0004/zedboard_leds_buttons/sw/src/c/zedboard_leds_buttons.c -O sw/src/c/zedboard_leds_buttons.c

Build the platform by right clicking on system_wrapper inside the Explorer tab and selecting Build Project. Missing Image!

Build the project by right clicking on zedboard_leds_buttons under zedboard_leds_buttons_system inside the Explorer tab and selecting Build Project. Missing Image!

Connect up the hardware as follows :-

Xubuntu PC USB ⇄ Zedboard USB JTAG/Debug
Xubuntu PC USB ⇄ Zedboard USB UART

Set the boot mode jumpers on the Zedboard for JTAG. Missing Image!

Power on the Zedboard.

If not already running, open up a new terminal and launch the MiniCom terminal emulator.

steve@Desktop:~$ minized

Welcome to minicom 2.7.1

OPTIONS: I18n
Compiled on Dec 23 2019, 02:06:26.
Port /dev/ttyACM0, 06:34:25

Press CTRL-A Z for help on special keys

To program the PL & PS part of the Zynq-7000 FPGA right click on zedboard_leds_buttons under zedboard_leds_buttons_system inside the Explorer tab and select Run As » Launch on Hardware (Single Application Debug) from the menu. The blue done LED will illuminate once the PL part of the FPGA has been programmed and after this the software will run on the PS part. Missing Image!

All being well the following sequence of events should be observed.

The blue done LED illuminates indicating the Programmable Logic (PL) has been programmed.
The software runs on the Processor System (PS).
The Minicom terminal emulator displays the following output from the application.

--== LED & Push Buttons interrupt example ==--

Use the buttons to control the LED's :-

Centre - Reset LED's to 00111100
Left   - Rotate LED's left
Right  - Rotate LED's right
Up     - Increase illuminated LED's
Down   - Decrease illuminated LED's

Press enter key to quit application

This design can be improved by added debounce logic to the push button inputs as sometimes multiple interrupts are detected for a single button press due to switch bounce. Another improvement would be to make the GPIO2 register latch and hold logic 1's for each of the push buttons when they are pressed, these held values would then be cleared by software after an interrupt is detected and the GPIO2 register read. If there is a large delay between an interrupt being detected and the GPIO2 register being read the users finger will be off the push button so it will not be detected as pressed.

Commit the updated files, create an annotated tag and push the commit & tag up to the remote repository.

steve@Desktop:~/projects/zedboard_leds_buttons$ git commit -am "Basic Zedboard design consisting of a ZYNQ7 Processing System controlling & monitoring LEDs & Push Buttons via a GPIO."
steve@Desktop:~/projects/zedboard_leds_buttons$ git push --set-upstream origin zedboard_leds_buttons
steve@Desktop:~/projects/zedboard_leds_buttons$ git tag -a v2.0_int -m "ZYNQ, GPIO & Interrupts"
steve@Desktop:~/projects/zedboard_leds_buttons$ git push origin v2.0_int

The source files relating to this tutorial for both Firmware & Software can be obtained from Bitbucket.

The instructions below assume that Part 1 - Installation of tools, setup of environment and creation of project area has been completed in full and that the environment has been setup as per 1. Setup environment. The root project area ~/projects should be present and contain the common project. The zedboard_leds_buttons project should NOT be present. Adjust the commands below to suit if the above differs.

Obtain firmware & software source, create & build Vivado project, export hardware, then create & build Vitis project.

steve@Desktop:~$ cd ~/projects
steve@Desktop:~/projects$ git clone -b v2.0_int https://bitbucket.org/spacewire_firmware/zedboard_leds_switches zedboard_leds_buttons
steve@Desktop:~/projects$ cd zedboard_leds_buttons
steve@Desktop:~/projects/zedboard_leds_buttons$ create_vivado_project.sh build
steve@Desktop:~/projects/zedboard_leds_buttons$ create_vitis_project.sh build

With the projects now created & built perform the following steps :-

Setup Zedboard hardware
Launch MiniCom terminal emulator
Deploy firware & software on Zedboard
Check everything is working as expected

Introduction

Aims

Part 1 - Project Setup

Part 2 - Firmware Development

Part 3 - Software Development

Part 4 - Hardware Deployment

Part 5 - Revision Control

Part 6 - Quickstart

1. Setup environment

2. Create project area

3. Recreate Vivado project & launch Vivado

4. Open block design

5. Re-customize ZYNQ IP

6. Re-customize AXI GPIO IP

7. Manually wire up connection

8. Rename external ports

9. Validate block design

10. Modify pin constraints

zedboard.xdc

11. Create testbench

testbench.sv

12. Generate bitstream

13. Export Hardware Platform

14. Recreate Vitis project & launch Vitis

15. Edit source file

zedboard_leds_buttons.c

16. Build platform

17. Build project

18. Setup Zedboard hardware

19. Launch MiniCom terminal emulator

20. Deploy firmware & software on Zedboard

21. Check everything is working as expected

22. Improvements

23. Commit to repository

24. Obtain tutorial files from Bitbucket, create & build projects, deploy on Zedboard