Functions
fsp_err_t	R_GMAC_B_Open (ether_ctrl_t const p_ctrl, ether_cfg_t const const p_cfg)

fsp_err_t	R_GMAC_B_Close (ether_ctrl_t *const p_ctrl)

fsp_err_t	R_GMAC_B_Read (ether_ctrl_t const p_ctrl, void const p_buffer, uint32_t *const length_bytes)

fsp_err_t	R_GMAC_B_BufferRelease (ether_ctrl_t *const p_ctrl)

fsp_err_t	R_GMAC_B_RxBufferUpdate (ether_ctrl_t const p_ctrl, void const p_buffer)

fsp_err_t	R_GMAC_B_Write (ether_ctrl_t const p_ctrl, void const p_buffer, uint32_t const frame_length)

fsp_err_t	R_GMAC_B_LinkProcess (ether_ctrl_t *const p_ctrl)

fsp_err_t	R_GMAC_B_GetLinkStatus (ether_ctrl_t const p_ctrl, uint8_t port, gmac_b_link_status_t p_status)

fsp_err_t	R_GMAC_B_WakeOnLANEnable (ether_ctrl_t *const p_ctrl)

fsp_err_t	R_GMAC_B_TxStatusGet (ether_ctrl_t const p_ctrl, void const p_buffer_address)

fsp_err_t	R_GMAC_B_CallbackSet (ether_ctrl_t const p_ctrl, void(p_callback)(ether_callback_args_t ), void const const p_context, ether_callback_args_t *const p_callback_memory)

Detailed Description

Driver for the Ethernet peripheral on RZ microprocessor. This module implements the Ethernet Interface.

Overview

This module performs Ethernet frame transmission and reception using an Ethernet controller (GMAC).

Features

The Ethernet module supports the following features:

Transmit/receive processing
Optional zero-copy buffering
Callback function with returned event code
Magic packet detection mode support
Auto negotiation support
Promiscuous mode support

Configuration

Build Time Configurations for r_gmac

The following build time configurations are defined in fsp_cfg/r_ether_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Networking > Ethernet (r_gmac)

This module can be added to the Stacks tab via New Stack > Networking > Ethernet (r_gmac).

Configuration	Options	Default	Description
General > Name	Name must be a valid C symbol	g_ether0	Module name.
General > Channel	0	0	Select the ether channel number. RZ/TMMMM
General > MAC address 0	Must be a valid MAC address	00:11:22:33:44:55	MAC address 0 of this channel.
General > MAC address 1	Must be a valid MAC address	NULL	MAC address 1 of this channel.
General > MAC address 2	Must be a valid MAC address	NULL	MAC address 2 of this channel.
General > Zero-copy Mode	Disable Enable	Disable	Enable or disable zero-copy mode.
General > Flow control functionality	Disable Enable	Disable	Enable or disable flow control.
Filters > Promiscuous Mode	Disable Enable	Enable	Enable this option to receive packets addressed to other NICs.
Buffers > Number of TX buffer	Must be an integer from 1 to 8	8	Number of transmit buffers
Buffers > Number of RX buffer	Must be an integer from 1 to 8	8	Number of receive buffers
Buffers > Buffer size	Must be at least 1522 bytes (the maximum Ethernet frame size 1514 bytes + ethsw management tag size 8 bytes).	1524	Size of Ethernet buffer
Interrupts > SBD Interrupt priority	MCU Specific Options		Select the Ether GMAC SBD interrupt priority.
Interrupts > PMT Interrupt priority	MCU Specific Options		Select the Ether GMAC PMT interrupt priority.
Interrupts > Callback	Name must be a valid C symbol	NULL	Callback provided when an ISR occurs
Link signal change	Disable Enable	Disable	Enable or disable callback by PHYLINK change.

Interrupt Configuration

The first R_GMAC_Open function call sets SDB and PMT interrupts. The user could provide callback function which would be invoked when SDB and PMT interrupt handler has been completed. The callback arguments will contain information about a channel number, the GMAC status, the event code, and a pointer to the user defined context.

Callback Configuration

The user could provide callback function which would be invoked when either a magic packet or a link signal change is detected. When the callback function is called, a variable in which the channel number for which the detection occurred and a constant for event code are stored is passed as an argument. If the value of this argument is to be used outside the callback function, its value should be copied into, for example, a global variable.

Clock Configuration

When using GMAC, Select "PLL1 diver clock" for "Ethernet Clock src".

Usage Notes

Ethernet Frame Format

The Ethernet module supports the Ethernet II/IEEE 802.3 frame format.

Frame Format for Data Transmission and Reception

Frame Format Image

The preamble and SFD signal the start of an Ethernet frame. The FCS contains the CRC of the Ethernet frame and is calculated on the transmitting side. When data is received the CRC value of the frame is calculated in hardware, and the Ethernet frame is discarded if the values do not match. When the hardware determines that the data is normal, the valid range of receive data is: (transmission destination address) + (transmission source address) + (length/type) + (data).

Managemt Port Specific Frame Format Image

The Ethernet frame have extended managemt port specific frame tag when management port specfic tag enable in Ether Switch configuration. By managemt port specific frame tag, It can select the external ports for transmission frame or obtain the external port for reception frame. Note that Ether Switch removes managemt port specific frame tag when sending to the external ports, and adds managemt port specific frame tag when receiving from the external port.

PAUSE Frame Format

Pause Frame Format Image

The transmission destination address is specified as 01:80:C2:00:00:01 (a multicast address reserved for PAUSE frames). At the start of the payload the length/type is specified as 0x8808 and the operation code as 0x0001. The pause duration in the payload is specified by the value of the automatic PAUSE (AP) bits in the automatic PAUSE frame setting register (APR), or the manual PAUSE time setting (MP) bits in the manual PAUSE frame setting register (MPR).

Magic Packet Frame Format

Magic Packet Frame Format Image

In a Magic Packet, the value FF:FF:FF:FF:FF:FF followed by the transmission destination address repeated 16 times is inserted somewhere in the Ethernet frame data.

Limitations

Memory alignment limitation for Ethernet buffer

The Ethernet Driver has several alignment constraints:

16-byte alignment for the descriptor
32-byte aligned write buffer for R_GMAC_Write when zero copy mode is enabled

Data Structures
struct	gmac_b_instance_descriptor_t

struct	gmac_b_instance_ctrl_t

struct	gmac_b_pause_resolution_t

Enumerations
enum	gmac_b_port_mask_t

enum	gmac_b_link_change_t

enum	gmac_b_magic_packet_t

enum	gmac_b_phylink_t

enum	gmac_b_pause_mask_t

enum	gmac_b_pause_val_t

enum	gmac_b_link_status_t

Data Structure Documentation

◆ gmac_b_instance_descriptor_t

struct gmac_b_instance_descriptor_t

GMAC descriptor as defined in the hardware manual.

Data Fields
volatile uint32_t	des0	TDES0/RDES0.
volatile uint32_t	des1	TDES1/RDES1.
volatile uint32_t	des2	TDES2/RDES2.
volatile uint32_t	des3	TDES3/RDES3.

◆ gmac_b_instance_ctrl_t

struct gmac_b_instance_ctrl_t

ETHER control block. DO NOT INITIALIZE. Initialization occurs when ether_api_t::open is called.

Data Fields
uint32_t	open
	Used to determine if the channel is configured.

ether_cfg_t const *	p_gmac_cfg
	Pointer to initial configurations.

uint32_t	rx_desc_pos
	index to the currently referenced transmit descriptor

uint32_t	tx_desc_pos
	index to the currently referenced receive descriptor

void *	p_reg_gmac
	Base register of ethernet controller for this channel.

gmac_b_port_mask_t	link_status
	link status by callback from ethsw (bit0:port0, bit1:port1,..)

gmac_b_port_mask_t	previous_link_status
	Previous link status (bit0:port0, bit1:port1,..)

uint32_t	link_speed_duplex
	Link speed & duplex.

gmac_b_magic_packet_t	magic_packet
	status of magic packet detection

gmac_b_port_mask_t	link_establish_status
	Current Link status (bit0:port0, bit1:port1,..)

uint32_t	local_pause_bits
	Local pause bits got from PHY.

uint32_t	partner_pause_bits
	Partner pause bits got from PHY.

◆ gmac_b_pause_resolution_t

struct gmac_b_pause_resolution_t

The "Pause Resolution" used to create the PAUSE resolution table 28B-3 of the IEEE 802.3-2008 standard.

Data Fields
gmac_b_pause_mask_t	mask	Pause mask.
gmac_b_pause_val_t	value	Pause value.
uint8_t	transmit	Transmit pause enable / disable.
uint8_t	receive	Receive pause enable / disable.

Enumeration Type Documentation

◆ gmac_b_port_mask_t

enum gmac_b_port_mask_t

Mask of the line port.

Enumerator
GMAC_B_PORT_MASK_0	Mask of Port 0.
GMAC_B_PORT_MASK_1	Mask of Port 1.
GMAC_B_PORT_MASK_2	Mask of Port 2.
GMAC_B_PORT_MASK_3	Mask of Port 3.
GMAC_B_PORT_MASK_ALL	Mask of Port 0 .. 3.

◆ gmac_b_link_change_t

enum gmac_b_link_change_t

Status of the link change.

Enumerator
GMAC_B_LINK_CHANGE_NO_CHANGE	Link status is no change.
GMAC_B_LINK_CHANGE_LINK_DOWN	Link status changes to down.
GMAC_B_LINK_CHANGE_LINK_UP	Link status changes to up.

◆ gmac_b_magic_packet_t

enum gmac_b_magic_packet_t

Status of the magic packet detection.

Enumerator
GMAC_B_MAGIC_PACKET_NOT_DETECTED	Magic packet is not detected.
GMAC_B_MAGIC_PACKET_DETECTING	Magic packet is detecting.
GMAC_B_MAGIC_PACKET_DETECTED	Magic packet is detected.

◆ gmac_b_phylink_t

enum gmac_b_phylink_t

Enable or disable link status change by PHYLINK

Enumerator
GMAC_B_PHYLINK_DISABLE	Disable.
GMAC_B_PHYLINK_ENABLE	Enable.

◆ gmac_b_pause_mask_t

enum gmac_b_pause_mask_t

The "Pause Mask" used to create the PAUSE resolution table 28B-3 of the IEEE 802.3-2008 standard.

Enumerator
GMAC_B_PAUSE_MASK0	Pause Mask 0.
GMAC_B_PAUSE_MASK1	Pause Mask 1.
GMAC_B_PAUSE_MASK2	Pause Mask 2.
GMAC_B_PAUSE_MASK3	Pause Mask 3.
GMAC_B_PAUSE_MASK4	Pause Mask 4.
GMAC_B_PAUSE_MASK5	Pause Mask 5.
GMAC_B_PAUSE_MASK6	Pause Mask 6.
GMAC_B_PAUSE_MASK7	Pause Mask 7.
GMAC_B_PAUSE_MASK8	Pause Mask 8.
GMAC_B_PAUSE_MASK9	Pause Mask 9.
GMAC_B_PAUSE_MASKA	Pause Mask A.
GMAC_B_PAUSE_MASKB	Pause Mask B.
GMAC_B_PAUSE_MASKC	Pause Mask C.
GMAC_B_PAUSE_MASKD	Pause Mask D.
GMAC_B_PAUSE_MASKE	Pause Mask E.
GMAC_B_PAUSE_MASKF	Pause Mask F.

◆ gmac_b_pause_val_t

enum gmac_b_pause_val_t

The "Pause Value" used to create the PAUSE resolution table 28B-3 of the IEEE 802.3-2008 standard.

Enumerator
GMAC_B_PAUSE_VAL0	Pause Value 0.
GMAC_B_PAUSE_VAL1	Pause Value 1.
GMAC_B_PAUSE_VAL2	Pause Value 2.
GMAC_B_PAUSE_VAL3	Pause Value 3.
GMAC_B_PAUSE_VAL4	Pause Value 4.
GMAC_B_PAUSE_VAL5	Pause Value 5.
GMAC_B_PAUSE_VAL6	Pause Value 6.
GMAC_B_PAUSE_VAL7	Pause Value 7.
GMAC_B_PAUSE_VAL8	Pause Value 8.
GMAC_B_PAUSE_VAL9	Pause Value 9.
GMAC_B_PAUSE_VALA	Pause Value A.
GMAC_B_PAUSE_VALB	Pause Value B.
GMAC_B_PAUSE_VALC	Pause Value C.
GMAC_B_PAUSE_VALD	Pause Value D.
GMAC_B_PAUSE_VALE	Pause Value E.
GMAC_B_PAUSE_VALF	Pause Value F.

◆ gmac_b_link_status_t

enum gmac_b_link_status_t

Link status of each port

Enumerator
GMAC_LINK_STATUS_DOWN	Link down.
GMAC_LINK_STATUS_UP	Link up.
GMAC_LINK_STATUS_READY	Link establishment.

Function Documentation

◆ R_GMAC_B_Open()

fsp_err_t R_GMAC_B_Open	(	ether_ctrl_t *const	p_ctrl,
		ether_cfg_t const *const	p_cfg
	)

After ETHERC, EDMAC and PHY-LSI are reset in software, an auto negotiation of PHY-LSI is begun. Afterwards, the link signal change interrupt is permitted. Implements ether_api_t::open.

Return values

FSP_SUCCESS	Channel opened successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block or configuration structure is NULL.
FSP_ERR_ALREADY_OPEN	Control block has already been opened or channel is being used by another instance. Call close() then open() to reconfigure.
FSP_ERR_ETHER_ERROR_PHY_COMMUNICATION	Initialization of PHY-LSI failed.
FSP_ERR_INVALID_CHANNEL	Invalid channel number is given.
FSP_ERR_INVALID_POINTER	Pointer to MAC address is NULL.
FSP_ERR_INVALID_ARGUMENT	Interrupt is not enabled.
FSP_ERR_ETHER_PHY_ERROR_LINK	Initialization of PHY-LSI failed.

◆ R_GMAC_B_Close()

fsp_err_t R_GMAC_B_Close ( ether_ctrl_t *const p_ctrl )

Disables interrupts. Removes power and releases hardware lock. Implements ether_api_t::close.

Return values

FSP_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

◆ R_GMAC_B_Read()

fsp_err_t R_GMAC_B_Read	(	ether_ctrl_t *const	p_ctrl,
		void *const	p_buffer,
		uint32_t *const	length_bytes
	)

Receive Ethernet frame. Receives data to the location specified by the pointer to the receive buffer. In zero copy mode, the address of the receive buffer is returned. In non zero copy mode, the received data in the internal buffer is copied to the pointer passed by the argument. Implements ether_api_t::read.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_ETHER_ERROR_NO_DATA	There is no data in receive buffer.
FSP_ERR_ETHER_ERROR_LINK	Auto-negotiation is not completed, and reception is not enabled.
FSP_ERR_ETHER_ERROR_MAGIC_PACKET_MODE	As a Magic Packet is being detected, transmission and reception is not enabled.
FSP_ERR_INVALID_POINTER	Value of the pointer is NULL.

◆ R_GMAC_B_BufferRelease()

fsp_err_t R_GMAC_B_BufferRelease ( ether_ctrl_t *const p_ctrl )

Move to the next buffer in the circular receive buffer list. Implements ether_api_t::bufferRelease.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_ETHER_ERROR_MAGIC_PACKET_MODE	As a Magic Packet is being detected, transmission and reception is not enabled.
FSP_ERR_ETHER_ERROR_LINK	Link is down.

◆ R_GMAC_B_RxBufferUpdate()

fsp_err_t R_GMAC_B_RxBufferUpdate	(	ether_ctrl_t *const	p_ctrl,
		void *const	p_buffer
	)

Change the buffer pointer of the current rx buffer descriptor. Implements ether_api_t::rxBufferUpdate.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	A pointer argument is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_INVALID_POINTER	The pointer of buffer is NULL or not aligned on a 32-bit boundary.
FSP_ERR_INVALID_MODE	Driver is configured to non zero copy mode.
FSP_ERR_ETHER_RECEIVE_BUFFER_ACTIVE	All descriptor is active.

◆ R_GMAC_B_Write()

fsp_err_t R_GMAC_B_Write	(	ether_ctrl_t *const	p_ctrl,
		void *const	p_buffer,
		uint32_t const	frame_length
	)

Transmit Ethernet frame. Transmits data from the location specified by the pointer to the transmit buffer, with the data size equal to the specified frame length. In the non zero copy mode, transmits data after being copied to the internal buffer. Implements ether_api_t::write.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_ETHER_ERROR_LINK	Auto-negotiation is not completed, and reception is not enabled.
FSP_ERR_ETHER_ERROR_MAGIC_PACKET_MODE	As a Magic Packet is being detected, transmission and reception is not enabled.
FSP_ERR_ETHER_ERROR_TRANSMIT_BUFFER_FULL	Transmit buffer is not empty.
FSP_ERR_INVALID_POINTER	Value of the pointer is NULL.
FSP_ERR_INVALID_ARGUMENT	Value of the send frame size is out of range.

◆ R_GMAC_B_LinkProcess()

fsp_err_t R_GMAC_B_LinkProcess ( ether_ctrl_t *const p_ctrl )

The Link up processing, the Link down processing, and the magic packet detection processing are executed. Implements ether_api_t::linkProcess.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_ETHER_ERROR_PHY_COMMUNICATION	When reopening the PHY interface initialization of the PHY-LSI failed.
FSP_ERR_ALREADY_OPEN	When reopening the PHY interface it was already opened.
FSP_ERR_INVALID_CHANNEL	When reopening the PHY interface an invalid channel was passed.
FSP_ERR_INVALID_POINTER	When reopening the PHY interface the MAC address pointer was NULL.
FSP_ERR_INVALID_ARGUMENT	When reopening the PHY interface the interrupt was not enabled.
FSP_ERR_ETHER_PHY_ERROR_LINK	Initialization of the PHY-LSI failed.

◆ R_GMAC_B_GetLinkStatus()

fsp_err_t R_GMAC_B_GetLinkStatus	(	ether_ctrl_t *const	p_ctrl,
		uint8_t	port,
		gmac_b_link_status_t *	p_status
	)

Get link status of specificed port.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_INVALID_POINTER	Value of the pointer is NULL.
FSP_ERR_INVALID_ARGUMENT	When reopening the PHY interface the interrupt was not enabled.

◆ R_GMAC_B_WakeOnLANEnable()

fsp_err_t R_GMAC_B_WakeOnLANEnable ( ether_ctrl_t *const p_ctrl )

The setting of ETHERC is changed from normal sending and receiving mode to magic packet detection mode. Implements ether_api_t::wakeOnLANEnable.

Return values

FSP_SUCCESS	Processing completed successfully.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

◆ R_GMAC_B_TxStatusGet()

fsp_err_t R_GMAC_B_TxStatusGet	(	ether_ctrl_t *const	p_ctrl,
		void *const	p_buffer_address
	)

Provides status of Ethernet driver in the user provided pointer. Implements ether_api_t::txStatusGet.

Return values

FSP_SUCCESS	Transmit buffer address is stored in provided p_buffer_address.
FSP_ERR_ASSERTION	Pointer to ETHER control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_INVALID_POINTER	p_status is NULL.
FSP_ERR_NOT_FOUND	Transmit buffer address has been overwritten in transmit descriptor.

◆ R_GMAC_B_CallbackSet()

fsp_err_t R_GMAC_B_CallbackSet	(	ether_ctrl_t *const	p_ctrl,
		void()(ether_callback_args_t )	p_callback,
		void const *const	p_context,
		ether_callback_args_t *const	p_callback_memory
	)

Updates the user callback with the option to provide memory for the callback argument structure. Implements ether_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for r_gmac

Configurations for Networking > Ethernet (r_gmac)

Interrupt Configuration

Callback Configuration

Clock Configuration

Usage Notes

Ethernet Frame Format

Frame Format for Data Transmission and Reception

PAUSE Frame Format

Magic Packet Frame Format

Limitations

Memory alignment limitation for Ethernet buffer

Data Structures

Enumerations

Data Structure Documentation

◆ gmac_b_instance_descriptor_t

◆ gmac_b_instance_ctrl_t

Data Fields

◆ gmac_b_pause_resolution_t

Enumeration Type Documentation

◆ gmac_b_port_mask_t

◆ gmac_b_link_change_t

◆ gmac_b_magic_packet_t

◆ gmac_b_phylink_t

◆ gmac_b_pause_mask_t

◆ gmac_b_pause_val_t

◆ gmac_b_link_status_t

Function Documentation

◆ R_GMAC_B_Open()

◆ R_GMAC_B_Close()

◆ R_GMAC_B_Read()

◆ R_GMAC_B_BufferRelease()

◆ R_GMAC_B_RxBufferUpdate()

◆ R_GMAC_B_Write()

◆ R_GMAC_B_LinkProcess()

◆ R_GMAC_B_GetLinkStatus()

◆ R_GMAC_B_WakeOnLANEnable()

◆ R_GMAC_B_TxStatusGet()

◆ R_GMAC_B_CallbackSet()