Part 10 - Create Peek & Poke CGI binaries to access Programmable Logic address space (28 November 2021)

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.

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

Change the present working directory to be the project directory.

steve@Desktop:~$ cd ~/projects/zedboard_linux/os/petalinux

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

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

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$ cd ../..

Peek

steve@Desktop:~/projects/zedboard_linux$ subl os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/peek.c

peek.c

//
// File .......... peek.c
// Author ........ Steve Haywood
// Version ....... 1.0
// Date .......... 26 Novemebr 2021
// Description ...
//   Very simple CGI peek application for single 32-bit reads. Provides
// status & error reporting back to the client side application.
//

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/mman.h>
#include <fcntl.h>

int main()
{
  char *querystring;
  char *paddr;
  char *pval;
  int fd;
  void *ptr;
  unsigned addr, page_addr, page_offset;
  unsigned page_size = sysconf(_SC_PAGESIZE);
  printf("Content-Type: text/plain;charset=us-ascii\n\n");
  querystring = getenv("QUERY_STRING");
  if (querystring) {
    pval = querystring;
    if (paddr = strtok_r(pval, "&", &pval)) {
//      if (pval) {
        fd = open("/dev/mem", O_RDWR);
        if (fd > 0) {
          addr = strtoul(paddr, NULL, 0);
          page_addr = (addr & ~(page_size - 1));
          page_offset = addr - page_addr;
          ptr = mmap(NULL, page_size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, page_addr);
          if (ptr != MAP_FAILED) {
            printf("0x%08X",*((unsigned *)(ptr + page_offset)));
          } else printf("Error: Failed to mmap");
        } else printf("Error: Failed to open /dev/mem");
//      } else printf("Error: Data not found");
    } else printf("Error: Address not found");
  } else printf("Error: No QUERY_STRING");
}

Direct download available here :-

steve@Desktop:~/projects/zedboard_linux$ wget https://spacewire.co.uk/tutorial/shared/repos/0011/zedboard_linux/os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/peek.c -O os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/peek.c

Poke

steve@Desktop:~/projects/zedboard_linux$ subl os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/poke.c

poke.c

//
// File .......... poke.c
// Author ........ Steve Haywood
// Version ....... 1.0
// Date .......... 26 Novemebr 2021
// Description ...
//   Very simple CGI poke application for single 32-bit writes. Provides
// status & error reporting back to the client side application.
//

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/mman.h>
#include <fcntl.h>

int main()
{
  char *querystring;
  char *paddr;
  char *pval;
  int fd;
  void *ptr;
  unsigned val;
  unsigned addr, page_addr, page_offset;
  unsigned page_size = sysconf(_SC_PAGESIZE);
  printf("Content-Type: text/plain;charset=us-ascii\n\n");
  querystring = getenv("QUERY_STRING");
  if (querystring) {
    pval = querystring;
    if (paddr = strtok_r(pval, "&", &pval)) {
      if (pval) {
        fd = open("/dev/mem", O_RDWR);
        if (fd > 0) {
          addr = strtoul(paddr, NULL, 0);
          val = strtoul(pval, NULL, 0);
          page_addr = (addr & ~(page_size - 1));
          page_offset = addr - page_addr;
          ptr = mmap(NULL, page_size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, page_addr);
          if (ptr != MAP_FAILED) {
            *((unsigned *)(ptr + page_offset)) = val;
            printf("Success");
          } else printf("Error: Failed to mmap");
        } else printf("Error: Failed to open /dev/mem");
      } else printf("Error: Data not found");
    } else printf("Error: Address not found");
  } else printf("Error: No QUERY_STRING");
}

Direct download available here :-

steve@Desktop:~/projects/zedboard_linux$ wget https://spacewire.co.uk/tutorial/shared/repos/0011/zedboard_linux/os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/poke.c -O os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/files/poke.c

Modify the BitBake recipe to change the installation location of the peek & poke applications.

steve@Desktop:~/projects/zedboard_linux$ subl os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb

peekpokecgi.bb

#
# This is the peekpokecgi aplication recipe
#
#

SUMMARY = "peekpokecgi application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
SRC_URI = "file://peek.c \
           file://poke.c \
           file://Makefile \
          "
FILES_${PN} += "/srv/www/cgi-bin"
S = "${WORKDIR}"
CFLAGS_prepend = "-I ${S}/include"
do_compile() {
        oe_runmake
}
do_install() {
        install -d ${D}/srv/www/cgi-bin
        install -m 0755 ${S}/peek ${D}/srv/www/cgi-bin
        install -m 0755 ${S}/poke ${D}/srv/www/cgi-bin
}

Direct download available here :-

steve@Desktop:~/projects/zedboard_linux$ wget https://spacewire.co.uk/tutorial/shared/repos/0011/zedboard_linux/os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb -O os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb

Check out the changes.

steve@Desktop:~/projects/zedboard_linux$ git difftool os/petalinux/project-spec/meta-user/recipes-apps/peekpokecgi/peekpokecgi.bb

Rebuild the project to include the updated files.

steve@Desktop:~/projects/zedboard_linux$ cd os/petalinux
steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-build

Package up the project ready for deployment.

steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-package --prebuilt --force

If not already, connect up the hardware as follows :-

Xubuntu PC USB ⇄ Zedboard USB JTAG/Debug
Xubuntu PC USB ⇄ Zedboard USB UART
Zedboard Ethernet ⇄ Router
Xubuntu PC Ethenet ⇄ Router
Router ⇄ Internet

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

Power cycle the Zedboard and deploy the project via JTAG.

steve@Desktop:~/projects/zedboard_linux/os/petalinux$ petalinux-boot --jtag --prebuilt 3

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

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 -a -m "Added peek/poke CGI application."
steve@Desktop:~/projects/zedboard_linux/os/petalinux$ git push
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 origin v5.0

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 :-

Build PetaLinux
Package PetaLinux
Setup Zedboard hardware
Launch MiniCom terminal emulator
Run PetaLinux on Zedboard via JTAG
Check everything is working as expected

Introduction

Aims

Part 1 - Project Setup

Part 2 - Create C application

Part 3 - Build & package PetaLinux

Part 4 - Hardware Deployment

Part 5 - Revision Control

Part 6 - Quickstart

1. Setup environment

2. Change present working directory

3. Create C application

4. Copy previous peek & poke application

5. Edit C application

peek.c

poke.c

6. Modify BitBake recipe

peekpokecgi.bb

7. Build PetaLinux

8. Package PetaLinux

9. Setup Zedboard hardware

10. Launch MiniCom terminal emulator

11. Run PetaLinux on Zedboard via JTAG

12. Check everything is working as expected

13. Commit to repository

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