Bar
SpaceWire UK
Specialist providers of VHDL Intellectual Property & Design Services
BarBarBarBar
Tutorial
Missing Image!
Part 10 - Create Peek & Poke CGI binaries to access Programmable Logic address space (28 November 2021)

Introduction

This tutorial details the steps required to create and install peek & poke CGI binary applications to be used with the website. The C source from the previously installed binary peek & poke applications will be used as a starting point along with extra code to make CGI possible. The end result will be a peek & poke CGI binary.

Aims

The aims of this tutorial are as follows :-

    Part 1 - Project Setup

    1. Setup environment
    2. Change present working directory

    Part 2 - Create C application

    1. Create C application
    2. Copy previous peek & poke application
    3. Edit C application
    4. Modify BitBake recipe

    Part 3 - Build & package PetaLinux

    1. Build PetaLinux
    2. Package PetaLinux

    Part 4 - Hardware Deployment

    1. Setup Zedboard hardware
    2. Launch MiniCom terminal emulator
    3. Run PetaLinux on Zedboard via JTAG
    4. Check everything is working as expected

    Part 5 - Revision Control

    1. Commit to repository

    Part 6 - Quickstart

    1. Obtain tutorial files from Bitbucket, create & build project, deploy on Zedboard
    #### Part 1 - Project Setup ####

    1. Setup environment

    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

    2. Change present working directory

    Change the present working directory to be the project directory.
    steve@Desktop:~$ cd ~/projects/zedboard_linux/os/petalinux
    #### Part 2 - Create C application ####

    3. Create C application

    Create a new auto-enabled C application.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-create --type apps --template c --name peekpokecgi --enable
    Examine the file structure of the newly created C application.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ tree project-spec/meta-user/recipes-apps/peekpokecgi
    project-spec/meta-user/recipes-apps/peekpokecgi
    ├── files
    │   ├── Makefile
    │   └── peekpokecgi.c
    ├── peekpokecgi.bb
    └── README

    1 directory, 4 files

    4. Copy previous peek & poke application

    Copy the sources from the previously installed peek & poke application and remove the unrequired files.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ cp project-spec/meta-user/recipes-apps/peekpoke/files/{Makefile,peek.c,poke.c} project-spec/meta-user/recipes-apps/peekpokecgi/files
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ cp project-spec/meta-user/recipes-apps/peekpoke/peekpoke.bb project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ rm project-spec/meta-user/recipes-apps/peekpokecgi/files/peekpokecgi.c

    5. Edit C application

    Examine the source for peek & poke to gain an understanding of what they are doing. Edit the sources to remove unnecessary code, include CGI specific code and provide status & verbose error reporting back to the client application.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ subl project-spec/meta-user/recipes-apps/peekpokecgi/files/{peek.c,poke.c}

    peek.c

    1. //
    2. // File .......... peek.c
    3. // Author ........ Steve Haywood
    4. // Version ....... 1.0
    5. // Date .......... 26 Novemebr 2021
    6. // Description ...
    7. //   Very simple CGI peek application for single 32-bit reads. Provides
    8. // status & error reporting back to the client side application.
    9. //

    11. #include <stdio.h>
    12. #include <stdlib.h>
    13. #include <unistd.h>
    14. #include <sys/mman.h>
    15. #include <fcntl.h>

    17. int main()
    18. {
    19.   char *querystring;
    20.   char *paddr;
    21.   char *pval;
    22.   int fd;
    23.   void *ptr;
    24.   unsigned addr, page_addr, page_offset;
    25.   unsigned page_size = sysconf(_SC_PAGESIZE);
    26.   printf("Content-Type: text/plain;charset=us-ascii\n\n");
    27.   querystring = getenv("QUERY_STRING");
    28.   if (querystring) {
    29.     pval = querystring;
    30.     if (paddr = strtok_r(pval, "&", &pval)) {
    31. //      if (pval) {
    32.         fd = open("/dev/mem", O_RDWR);
    33.         if (fd > 0) {
    34.           addr = strtoul(paddr, NULL, 0);
    35.           page_addr = (addr & ~(page_size - 1));
    36.           page_offset = addr - page_addr;
    37.           ptr = mmap(NULL, page_size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, page_addr);
    38.           if (ptr != MAP_FAILED) {
    39.             printf("0x%08X",*((unsigned *)(ptr + page_offset)));
    40.           } else printf("Error: Failed to mmap");
    41.         } else printf("Error: Failed to open /dev/mem");
    42. //      } else printf("Error: Data not found");
    43.     } else printf("Error: Address not found");
    44.   } else printf("Error: No QUERY_STRING");
    45. }

    poke.c

    1. //
    2. // File .......... poke.c
    3. // Author ........ Steve Haywood
    4. // Version ....... 1.0
    5. // Date .......... 26 Novemebr 2021
    6. // Description ...
    7. //   Very simple CGI poke application for single 32-bit writes. Provides
    8. // status & error reporting back to the client side application.
    9. //

    11. #include <stdio.h>
    12. #include <stdlib.h>
    13. #include <unistd.h>
    14. #include <sys/mman.h>
    15. #include <fcntl.h>

    17. int main()
    18. {
    19.   char *querystring;
    20.   char *paddr;
    21.   char *pval;
    22.   int fd;
    23.   void *ptr;
    24.   unsigned val;
    25.   unsigned addr, page_addr, page_offset;
    26.   unsigned page_size = sysconf(_SC_PAGESIZE);
    27.   printf("Content-Type: text/plain;charset=us-ascii\n\n");
    28.   querystring = getenv("QUERY_STRING");
    29.   if (querystring) {
    30.     pval = querystring;
    31.     if (paddr = strtok_r(pval, "&", &pval)) {
    32.       if (pval) {
    33.         fd = open("/dev/mem", O_RDWR);
    34.         if (fd > 0) {
    35.           addr = strtoul(paddr, NULL, 0);
    36.           val = strtoul(pval, NULL, 0);
    37.           page_addr = (addr & ~(page_size - 1));
    38.           page_offset = addr - page_addr;
    39.           ptr = mmap(NULL, page_size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, page_addr);
    40.           if (ptr != MAP_FAILED) {
    41.             *((unsigned *)(ptr + page_offset)) = val;
    42.             printf("Success");
    43.           } else printf("Error: Failed to mmap");
    44.         } else printf("Error: Failed to open /dev/mem");
    45.       } else printf("Error: Data not found");
    46.     } else printf("Error: Address not found");
    47.   } else printf("Error: No QUERY_STRING");
    48. }

    6. Modify BitBake recipe

    Modify the BitBake recipe to change the installation location of the peek & poke applications.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ subl project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb

    peekpokecgi.bb

    1. #
    2. # This is the peekpokecgi aplication recipe
    3. #
    4. #

    6. SUMMARY = "peekpokecgi application"
    7. SECTION = "PETALINUX/apps"
    8. LICENSE = "MIT"
    9. LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
    10. SRC_URI = "file://peek.c \
    11.            file://poke.c \
    12.            file://Makefile \
    13.           "
    14. FILES_${PN} += "/srv/www/cgi-bin"
    15. S = "${WORKDIR}"
    16. CFLAGS_prepend = "-I ${S}/include"
    17. do_compile() {
    18.         oe_runmake
    19. }
    20. do_install() {
    21.         install -d ${D}/srv/www/cgi-bin
    22.         install -m 0755 ${S}/peek ${D}/srv/www/cgi-bin
    23.         install -m 0755 ${S}/poke ${D}/srv/www/cgi-bin
    24. }


    #### Part 3 - Build & package PetaLinux ####

    7. Build PetaLinux

    Rebuild the project to include the updated files.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-build

    8. Package PetaLinux

    Package up the project ready for deployment.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-package --prebuilt --force
    #### Part 4 - Hardware Deployment ####

    9. Setup Zedboard hardware

    Connect up the hardware as follows :-
    1. Xubuntu PC USB ⇄ Zedboard USB JTAG/Debug
    2. Xubuntu PC USB ⇄ Zedboard USB UART
    3. Zedboard Ethernet ⇄ Router
    4. Xubuntu PC Ethenet ⇄ Router
    5. Router ⇄ Internet
    Missing Image! Set the boot mode jumpers on the Zedboard for JTAG. Missing Image! Power on the Zedboard.

    10. Launch MiniCom terminal emulator

    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

    11. Run PetaLinux on Zedboard via JTAG

    Power cycle the Zedboard and deploy the project via JTAG.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-boot --jtag --prebuilt 3

    12. Check everything is working as expected

    Access the CGI application directly to test functionality by performing a write to the LED register and a read from the slide switch register.

    Using the Client URL (curl) command enter the following URL to command the CGI script to write 0x0F to the LED register at 0x41200000.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ curl -w "\nReceived %{size_download} bytes\n" "http://192.168.2.87/cgi-bin/poke?0x41200000&0x0F"
    All being well LED's 0, 1, 2 & 3 should illuminate and the script should return the success message.
    Success
    Received 7 bytes
    Again using curl enter the following URL to command the CGI script to read from the slide switch register at 0x41200008.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ curl -w "\nReceived %{size_download} bytes\n" "http://192.168.2.87/cgi-bin/peek?0x41200008"
    All being well the script should successfully return something akin to the following indicating which of the slide switches are in their on position, in this case switches 0 & 1.
    0x00000003
    Received 10 bytes
    #### Part 5 - Revision Control ####

    13. Commit to repository

    Add and commit the new & updated files, create an annotated tag and push the commit & tag up to the remote repository.
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ git add project-spec/meta-user/recipes-apps/peekpokecgi
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ git commit -am "Added peek/poke CGI application."
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ git tag -a v5.0 -m "PetaLinux, Peek/Poke, LED Runner, Webserver & Peek/Poke CGI with XSA from zedboard_leds_switches v1.0"
    steve@Desktop:~/projects/zedboard_linux/os/petalinux$ git push
    #### Part 6 - Quickstart ####

    14. Obtain tutorial files from Bitbucket, create & build project, deploy on Zedboard

    The source files relating to this tutorial for the OS can be obtained from Bitbucket. The OS repository contains both PetaLinux and a local copy of the exported hardware (firmware).

    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_linux projects should NOT be present. Adjust the commands below to suit if the above differs.

    Obtain OS source, build & deploy on Zedboard.
    steve@Desktop:~$ cd ~/projects
    steve@Desktop:~/projects$ git clone -b v4.0 https://bitbucket.org/spacewire_firmware/zedboard_linux
    steve@Desktop:~/projects$ cd zedboard_linux/os/petalinux
    Do something with the OS (if required) then perform the following steps :-
    1. Build PetaLinux
    2. Package PetaLinux
    3. Setup Zedboard hardware
    4. Launch MiniCom terminal emulator
    5. Run PetaLinux on Zedboard via JTAG
    6. Check everything is working as expected
    Copyright © 2004-2024 SpaceWire UK. All rights reserved.