Getting Started with Zynq Servers

This guide will demonstrate creating an Ethernet server application that runs on a Zynq 7000-based FPGA board, such as the Zybo Z7 or Arty Z7. Vivado/Vitis 2023.1 creates the Zynq processor and the server application. The application is called an echo server, and as the name implies, any character sent to it through an Ethernet connection is repeated back to the host.

• Zybo Z7, Arty Z7, Cora Z7 or Eclypse Z7 Development Board
• Ethernet Cat 5 cable
• Micro USB cable for UART communication and JTAG programming

• Xilinx Vivado 2023.1 software suite
• If the Vivado Suite has not been installed, please review the following installation guide Installing Vivado, Vitis, and Digilent Board Files

Important: For FPGA boards that use an RTL8211F Ethernet PHY, a modified version of Xilinx's LWIP library is required to correctly operate the echo server example. To fix the copy of the library found in your Vitis installation, one file needs to be updated. To do so, follow the instructions below:

• Download the ZIP archive of the realtek-21.1 branch of Digilent's fork of Xilinx's embeddedsw repository: realtek-21.1.zip.
• Extract the downloaded ZIP archive and, using File Explorer, browse to /ThirdParty/sw_services/lwip211/src/contrib/ports/xilinx/netif/xemacpsif_physpeed.c. This is an updated version of the one source file that needs changed.
• Browse to C:\Xilinx\Vitis\2023.1\data\embeddedsw\ThirdParty\sw_services\lwip213_v1_0\src\contrib\ports\xilinx\netif. This is the directory that LWIP sources used in your Vitis projects' BSPs are pulled from.
• To back up the original file and avoid overwriting it, rename the existing xemacpsif_physpeed.c in the Vitis install directory to xemacpsif_physpeed.c.orig.
• Replace the original file by copying the updated version of the xemacpsif_physpeed.c file into this folder.
• Ensure the Vitis project's Board Support Package (BSP) has lwip213 enabled.

I. Vivado

• Open Vivado
• Create a new Vivado Project
• Select your board
• Create an empty block design workspace inside the new project
• Add Zynq processor IP blocks
• Validate and save block design
• Create HDL system wrapper
• Run design Synthesis and Implementation
• Generate FPGA Bitstream
• Export Hardware Design that includes the Bitstream.
• Launch Vitis

II. Vitis

• Create a new application project using the Vivado *.xsa hardware design wrapper.
• Choose the Echo Server example project.
• Build the example, program the FPGA, and run the application

When you're done experimenting with the echo server, remember to go back into Open Network and Sharing Center

Select Internet Protocol Version 4 (TCP/IPv4) and click Properties.

Select obtain an IP address automatically

As a simple case study in how to modify the echo server to do something else, and to better understand how the LWIP TCP API works, lets make it so that any alpha characters sent to the server to be echo'd have their case switched. So letters a-z sent to it will be echo'd as A-Z, and any letters A-Z will be returned as a-z.

First, lets trace through how a connection is handled. Rather than starting with the main file, lets look at the echo.c file. This is where the functions that the API calls are defined. To implement the desired change, we just need to look at a couple of functions:

1. The start_application function triggers when the board is booted, and initializes the server. This is our entrypoint. It registers the accept callback.
2. The accept_callback function triggers when a client connects to the server and makes sure data associated with the client is passed to other callbacks. It registers these other callbacks, importantly, the recv callback.
3. The recv_callback function triggers when data is received from a client. It then starts a write, writing back the received data. We've found the function we need to change.

Let's add a function that can perform the necessary conversion. Place it somewhere above the recv_callback function. To follow best practices, you could also add a function prototype. Here's some code that implements the case swap, without copying data:

void swap_case (char *buffer, u16 length) {
	// Swap the case of each char in the buffer in place
	for (int i = 0; i < length; i++) {
		if (buffer[i] >= 'a' && buffer[i] <= 'z') {
			buffer[i] = buffer[i] + 'A' - 'a';
		}
		else if (buffer[i] >= 'A' && buffer[i] <= 'Z') {
			buffer[i] = buffer[i] + 'a' - 'A';
		}
	}
}

Next, we need to modify the recv_callback function. To do so, we need to know a bit more about what it does and what data it has access to. Let's go over the arguments:

1. The arg argument passes a pointer to data defined by a tcp_arg call. In the example, it's just a connection ID, indicating which client a packet came from.
2. The tpcb argument is a pointer to a protocol control block containing a bunch of information about the connection.
3. The p argument is a pointer to a packet buffer - this contains our data.
4. We can disregard the err argument in this case, it indicates when something has gone wrong with the connection.

Now that we know what we have access to, let's modify the data. In the recv_callback function, somewhere between the check to see if the packet buffer is null, and the call to tcp_write that initiates the echo back, add the following code:

	/* swap the cases of alpha characters in the payload */
	swap_case(p->payload, p->len);

This function call simply invokes the function we wrote previously on the packet buffer data.

All that's left to do is to build the project and run it on your board!

With that, you've got an ethernet connection capable of sending data back and forth between a host computer and your FPGA development board!

For more guides on how to use your board, check out its resource center, which can be found through the Programmable Logic page of this site.