By Adam Taylor
In the previous blog we introduced the Zynq SoC’s Gigabit Ethernet Controller, which provides Media Access Controller (MAC) capability. This is the first step in being able to establish an IP stack. Now we will look at how we can configure the MAC to send and receive packets using the example provided by Xilinx with the SDK, which demonstrates how the MAC works.
First, open SDK and create a new blank application referencing a BSP with an enabled Gigabit Ethernet Controller. (This needs to done in Vivado).
The Xilinx SDK comes complete with an example that demonstrates use of the Ethernet MAC to send a frame. I am going to build this instalment around this great example. First things first, however. We need to include those example files within our design. We can do this very simply by clicking on our application, selecting import -> file system, navigating to
<Install> /SDK/2014.1/data/embeddedsw/XilinxProcessorIPLib/d rivers/emacps_v2_0/examples
and importing the following files:
- c – The example file itself
- c – This contains a number of function which are of use in the example
- h – Contains the function definitions of the utilities
With these files within your project, you can build the example demonstration and if your board is connected to a terminal program you will see the success (or otherwise) of the demonstration. However, these steps do not help our understanding or allow us to learn about how to configure and use the Zynq SoC’s Ethernet MAC.
So let’s take a look at these example files and work out exactly what they do to better understand the MAC. We start with the xemacps_example_intr_dma.c file. The first things this file does is:
- Within the declarations, the file defines a number of Rx and Tx buffer descriptors, device ID’s, interrupt ID’s, and register offsets and values.
- Declares Global variables for transmitting and receiving Ethernet frames, sets the frame length and the number of frames transmitted and received.
The main functionality is contained within EmacPSIntrExample function. This function unlocks the SLCR (System Level Control Registers) and sets up the clocking for the MAC followed by configuring and initializing the MAC using the same approah used with many other peripherals—looking up the configuration and then initializing using pointers to instances.
Once initialized, the MAC address is set. This address is contained within the file xemacps_example_util.c and is six bytes long. It’s defined as a char array; in this case it’s 00:0A:35:01:02:03. The MAC address is a unique identifier used to identify each node connected to the network. After the MAC address is set, three handlers are set up to be called when transmission, reception, or errors occur.
With the MAC configuration complete, the next step is to establish the DMA buffer descriptors (BDs) for both transmit and receive buffers.
Buffer Descriptor (BD) structure
To create a BD Ring we need five things:
- The RX or TX pointer instance, which in this case is provided by the XEmacPs_GetRxRing function. There is a similar function for the TX.
- The physical start address of the buffer memory – defined earlier in the declarations.
- The virtual start address of the buffer memory – this is the same as the physical address because the cache is disabled.
- The alignment of the bytes, in this case 4.
- The number of buffer descriptors to create.
With the ring created we can clone the buffer descriptor templates for the newly created ring. We do something similar for the transmit ring.
TX buffer Descriptor after creation and cloning
The frame is generated and received within the EmacPsDmaSingleFrameIntrExample function. This function uses both the transmit and receive buffer descriptors to send and receive 1000-byte payload frames. With the MAC in loop-back mode, the function simply checks the transmitted frame against the received frame to verify that the example works.
How the frame is built is very interesting. An Ethernet frame consists of:
- 8 Octet Preamble
- 6 Octet Destination address
- 6 Octet Source address
- 2 Octet Ethertype – this defines the type of protocol contained within the payload
- 46 to 1500 Octet Payload
- 4 Octet CRC
The transmit frame TxFrame is defined as type EthernetFrame. This is a char array of size 1532 chars. The approach taken to create the frame is therefore to use a pointer to address each element of the array and set it to the required value. For this example, the source and destination addresses are set to the same the MAC address. The payload just contains an incrementing counter and the EtherType is set to 1000.
The TxFrame needs to be inserted into the buffer descriptor so we can commit it to the hardware. Within the example, the tx_frame is split across two buffer descriptors to demonstrate how to use multiple BDs while the RX frame is contained within a single BD.
Setting up the BD and committing to Hardware.
The same process is followed for the Rx buffer descriptor, pointing it towards the RxFrame char array. With the BD for both the Tx and RX established and committed to hardware, the demonstration then enables the transmission:
Once the transmission is complete, the transmit handler is called, the FramesTx counter is incremented, and buffer descriptors are cleaned up. The Tx and Rx frames are then compared with each other to make sure they agree; success or failure is reported.
It has taken a long time to explain all of this, however understanding how the MAC works and how we configure it is important if we want to create an IP stack. Stepping through this demo proves that there is nothing too complicated about how we can configure the Zynq SoC’s Ethernet MAC to transfer data.
Now, you can have convenient, low-cost Kindle access to the first year of Adam Taylor’s MicroZed Chronicles for a mere $7.50. Click here.
Please see the previous entries in this MicroZed Chronicles series by Adam Taylor: