4.24. EMAC

4.24.1. Module Files

4.24.1.1. Driver

  • src/app/driver/emac/emac-low-level.c

  • src/app/driver/emac/emac-low-level.h

  • src/app/driver/emac/emac.c

  • src/app/driver/emac/emac.h

4.24.1.2. Configuration

  • src/app/driver/config/emac_cfg.h

4.24.1.3. Unit Test

  • tests/unit/app/driver/emac/test_emac.c

4.24.2. Description

The EMAC-Driver driver handles DMA-based packet transmit (Tx) and receive (Rx) as part of the TCP/IP stack. The TCP/IP communication is described in more detail in the section Operating System.

4.24.2.1. Initialization

The EMAC Module has its own RAM. This is used to store the Tx and Rx buffer descriptors. Each Buffer Descriptor (EMAC_TX_BUFFER_DESCRIPTOR_s) and (EMAC_RX_BUFFER_DESCRIPTOR_s) has fields:

  • pBuffer: pointer to data buffer

  • bufferOffsetAndLength: padding info and buffer length

  • flagsAndPacketLength: flags and packet length

  • next: link to the next descriptor

As the buffer descriptors are stored in a linked list, it contains first a pointer to the next buffer descriptor and then the pointer to the actual buffer. The buffer offset is the offset from the start of the packet buffer to the first byte of valid data. The buffer length then describes the number of valid data in the buffer. The flags contain information about the packet as:

  • SOP (Start of Packet)

  • EOP (End of Packet)

  • OWNER (Ownership)

  • EOQ (End of Queue)

The Packet Length field is only valid for data-carrying SOP (Start of Packet) descriptors. For these, it specifies the total length of the entire Ethernet frame, regardless of whether the frame is stored in a single buffer or span across multiple fragments.

Fig. 4.15 shows the buffer descriptors after their Initialization.

Initialization of |emac| DMA Module

Fig. 4.15 Initialization of EMAC DMA Module

During the initialization the buffer pointers are mapped to the buffer and aligned to a linked list. For each channel a struct is holding the relevant information for the network interface. For the receive part it is the free head, active head and active tail. The transmit channel contains the free head, next buffer descriptor to process and active tail.

4.24.2.1.1. Rx Channel

The struct Rx channel is prepared to manage the reception of several packets. It consists of the pointer (EMAC_RX_CHANNEL_s):

  • pFreeHead that points to next free head of the buffer list. It is set after the first reception.

  • pActiveHead, a pointer to the head of the list of buffer descriptors. The DMA engine will start to fill the buffer of this descriptor after reception.

  • pActiveTail that points to the last descriptor in the active list.

4.24.2.1.2. Tx Channel

The transmit channel is similar to the receive channel. It also consists of a linked list of buffer descriptors (EMAC_TX_CHANNEL_s). But this list is circularly linked. After initialization, pFreeHead and pNextBufferDescriptorToProcess point to the first buffer descriptor. The buffer pointers get assigned during the transmission processes.

4.24.2.2. Receive

When an Ethernet frame arrives on the MAC, the EMAC receive logic writes the frame into system memory using DMA. The DMA engine uses the previously mentioned linked list of buffer descriptors. For each descriptor, the DMA stores the address of the buffer, status information, and the number of valid bytes in that buffer. At the beginning, pActiveHead and pActiveTail are accessed. pFreeHead will point after the reception to the first descriptor. This is used as temporary storage for the pointer. The total packet length is recorded in the EOP descriptor, as illustrated in Fig. 4.16. Once the EMAC has completed writing a frame (i.e. the EOP descriptor has been filled and marked as owned by software), it signals the processor by generating an interrupt. At this point the software knows that at least one complete frame is available on the receive descriptor list. Starting with the first descriptor, they are processed in the Network Interface.

Reception of Ethernet Packets

Fig. 4.16 Structure of buffer descriptors before reception

In the receive handler, the software walks the list of active descriptors, starting at pActiveHead. For each packet, it:

  1. Locates the next SOP descriptor.

  2. Follows the descriptor chain up to and including the corresponding EOP descriptor. This covers all buffers that contain fragments of the same Ethernet frame.

  3. Copies the received data from these DMA buffers into a Ethernet packet buffer.

  4. Passes the packet to the network interface, which then hands it off to the Ethernet protocol stack for further processing (e.g. IP, TCP/UDP).

After the buffer descriptor is processed, the flags are reset and pActiveHead and pActiveTail point to the last processed buffer descriptor.

Note

Currently, the EMAC driver only supports the reception of one buffer descriptor.

When the chain is processed, the linked list is shifted to the end of the chain. Fig. 4.17 describes the linked RX buffer descriptor list after the reception.

Reception of Ethernet Packets

Fig. 4.17 Structure of buffer descriptors after reception

4.24.2.3. Transmit

Fig. 4.18 describes the buffer descriptors during data transmission.

Transmission of Ethernet Packets

Fig. 4.18 Structure of buffer descriptors after transmission

In the transmission process, the pNextBufferDescriptorToProcess of the Tx channel is filled first. The total packet length, the start of packet length (SOP) and the owner (OWNER) flag are set in the first buffer descriptor. Then the payload is added. As the driver currently does not accept fragmented packets every descriptor ends with the end of packet (EOP) flag. The last packet is the pActiveTail. pFreeHead points to the next descriptor available for sending data.

4.24.3. See Also