Ethernet (r_ether)

Functions
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_Close (ether_ctrl_t *const p_ctrl)
	Disables interrupts. Removes power and releases hardware lock. Implements ether_api_t::close. More...
fsp_err_t	R_ETHER_BufferRelease (ether_ctrl_t *const p_ctrl)
	Move to the next buffer in the circular receive buffer list. Implements ether_api_t::bufferRelease. More...
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_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. More...
fsp_err_t	R_ETHER_TxStatusGet (ether_ctrl_t *const p_ctrl, void *const p_buffer_address)
fsp_err_t	R_ETHER_CallbackSet (ether_ctrl_t *const p_api_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 RA MCUs. This module implements the Ethernet Interface.

Overview

This module performs Ethernet frame transmission and reception using an Ethernet controller and an Ethernet DMA controller.

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
• Flow control support
• Multicast filtering support
• Broadcast filtering support
• Promiscuous mode support

Configuration

Build Time Configurations for r_ether

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.
ET0_LINKSTA Pin Status Flag	Fall -> Rise Rise -> Fall	Fall -> Rise	Specify the polarity of the link signal output by the PHY-LSI. When 0 is specified, link-up and link-down correspond respectively to the fall and rise of the LINKSTA signal. When 1 is specified, link-up and link-down correspond respectively to the rise and fall of the LINKSTA signal.
Link Signal Change Flag	Unused Used	Unused	Use LINKSTA signal for detect link status changes 0 = unused (use PHY-LSI status register) 1 = use (use LINKSTA signal)
Interrupt event backward compatibility	Do not keep compatibility Keep compatibility	Keep compatibility	Keep backword compatibility of interrupt events. 0 = Do not keep compatibility, use separate events for each cause of interrupt. 1 = Keep compatibility, use common events for all interrupts.

Configurations for Networking > Ethernet (r_ether)

This module can be added to the Stacks tab via New Stack > Networking > Ethernet (r_ether). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_ether0	Module name.
Channel	0	0	Select the ether channel number.
MAC address	Must be a valid MAC address	00:11:22:33:44:55	MAC address of this channel.
Zero-copy Mode	Disable Enable	Disable	Enable or disable zero-copy mode.
Flow control functionality	Disable Enable	Disable	Enable or disable flow control.
Filters
Multicast Mode	Disable Enable	Enable	Enable or disable multicast frame reception.
Promiscuous Mode	Disable Enable	Disable	Enable this option to receive packets addressed to other NICs.
Broadcast filter	Must be a valid non-negative integer with maximum configurable value of 65535.	0	Limit of the number of broadcast frames received continuously
Buffers
Number of TX buffer	Must be an integer from 1 to 8	1	Number of transmit buffers
Number of RX buffer	Must be an integer from 1 to 8	1	Number of receive buffers
Allocate RX buffer	Disable Enable	Enable	Allocates the RX buffer when generating the configuration structure
Buffer size	Must be at least 1514 which is the maximum Ethernet frame size.	1514	Size of Ethernet buffer
Padding size	Disable 1 Byte 2 Bytes 3 Bytes	Disable	The padding size that is automatically inserted into the received packets
Padding offset	Must be less than 64 bytes.	0	The offset into a receive buffer to insert padding bytes.
Interrupts
EESR event	Refer to the RA Configuration tool for available options.	RFOF RDE FR TFUF TDE TC	Select event list for each bit of EESR.
ECSR event	ICD MPD LCHNG PSRTO BFR		Select event list for each bit of ECSR.
Interrupt priority	MCU Specific Options		Select the EDMAC interrupt priority.
Callback	Name must be a valid C symbol	NULL	Callback provided when an ISR occurs

Interrupt Configuration

The first R_ETHER_Open function call sets EINT interrupts. The user could provide callback function which would be invoked when EINT interrupt handler has been completed. The callback arguments will contain information about a channel number, the ETHERC and EDMAC 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 shown in Table 2.4 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

The clock for this module is derived from the following peripheral clock for each MCU group:

MCU Group	Peripheral Clock
RA4E2	PCLKA
RA4T1	PCLKA
RA6E1	PCLKA
RA6E2	PCLKA
RA6M2	PCLKA
RA6M3	PCLKA
RA6M4	PCLKA
RA6M5	PCLKA
RA6T3	PCLKA

Note

1. When using ETHERC, the PCLKA frequency is in the range 12.5 MHz <= PCLKA <= 120 MHz.

2. When using ETHERC, PCLKA = ICLK.

Pin Configuration

To use the Ethernet module, input/output signals of the peripheral function have to be allocated to pins with the multi-function pin controller (MPC). Please perform the pin setting before calling the R_ETHER_Open function.

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).

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 read buffer for R_ETHER_RxBufferUpdate when zero copy mode is enabled

Functional limitations in TrustZone Security Extensions

The Ethernet Driver has several security constraints:

MCU	Has Security Extension	Support Flat project	Support TrustZone project
			Secure	Non-Secure
RA6M2	-	x	-	-
RA6M3	-	x	-	-
RA6M4	- *1	x	-	x
RA6M5	- *1	x	-	x
RA8M1	x	x	x	x

Note

1. ETHERC/EDMAC is always Non-secure peripheral in this MCU.

Examples

ETHER Basic Example

This is a basic example of minimal use of the ETHER in an application.

Note

In this example zero-copy mode is disabled and there are no restrictions on buffer alignment.

#define ETHER_EXAMPLE_MAXIMUM_ETHERNET_FRAME_SIZE     (1514)

#define ETHER_EXAMPLE_TRANSMIT_ETHERNET_FRAME_SIZE    (60)

#define ETHER_EXAMPLE_SOURCE_MAC_ADDRESS              0x74, 0x90, 0x50, 0x00, 0x79, 0x01
#define ETHER_EXAMPLE_DESTINATION_MAC_ADDRESS         0x74, 0x90, 0x50, 0x00, 0x79, 0x02
#define ETHER_EXAMPLE_FRAME_TYPE                      0x00, 0x2E
#define ETHER_EXAMPLE_PAYLOAD                         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,                                                   \
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,                                                   \
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,                                                   \


/* Receive data buffer */
static uint8_t gp_read_buffer[ETHER_EXAMPLE_MAXIMUM_ETHERNET_FRAME_SIZE] = {0};

/* Transmit data buffer */
static uint8_t gp_send_data[ETHER_EXAMPLE_TRANSMIT_ETHERNET_FRAME_SIZE] =
{
    ETHER_EXAMPLE_DESTINATION_MAC_ADDRESS, /* Destination MAC address */
    ETHER_EXAMPLE_SOURCE_MAC_ADDRESS,      /* Source MAC address */
    ETHER_EXAMPLE_FRAME_TYPE,              /* Type field */
    ETHER_EXAMPLE_PAYLOAD                  /* Payload value (46byte) */
};

void ether_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Source MAC Address */
    static uint8_t mac_address_source[6] = {ETHER_EXAMPLE_SOURCE_MAC_ADDRESS};

    uint32_t read_data_size = 0;

    g_ether0_cfg.p_mac_address = mac_address_source;


    /* Open the ether instance with initial configuration. */
    err = R_ETHER_Open(&g_ether0_ctrl, &g_ether0_cfg);


    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);


    do
    {
        /* When the Ethernet link status read from the PHY-LSI Basic Status register is link-up,
         * Initializes the module and make auto negotiation. */
        err = R_ETHER_LinkProcess(&g_ether0_ctrl);
    } while (FSP_SUCCESS != err);



    /* Transmission is non-blocking. */
    /* User data copy to internal buffer and is transferred by DMA in the background. */
    err = R_ETHER_Write(&g_ether0_ctrl, (void *) gp_send_data, sizeof(gp_send_data));
    assert(FSP_SUCCESS == err);



    /* received data copy to user buffer from internal buffer. */
    err = R_ETHER_Read(&g_ether0_ctrl, (void *) gp_read_buffer, &read_data_size);
    assert(FSP_SUCCESS == err);



    /* Disable transmission and receive function and close the ether instance. */
    R_ETHER_Close(&g_ether0_ctrl);

}

ETHER Advanced Example

The example demonstrates using send and receive function in zero copy mode. Transmit buffers must be 32-byte aligned and the receive buffer must be released once its contents have been used.

#define ETHER_EXAMPLE_FLAG_ON                  (1U)
#define ETHER_EXAMPLE_FLAG_OFF                 (0U)

#define ETHER_EXAMPLE_ETHER_ISR_EE_FR_MASK     (1UL << 18)
#define ETHER_EXAMPLE_ETHER_ISR_EE_TC_MASK     (1UL << 21)
#define ETHER_EXAMPLE_ETHER_ISR_EC_MPD_MASK    (1UL << 1)

#define ETHER_EXAMPLE_ALIGNMENT_32_BYTE        (32)

static volatile uint32_t g_example_receive_complete  = 0;
static volatile uint32_t g_example_transfer_complete = 0;
static volatile uint32_t g_example_magic_packet_done = 0;

static uint8_t gp_send_data_internal[ETHER_EXAMPLE_TRANSMIT_ETHERNET_FRAME_SIZE] =
{
    ETHER_EXAMPLE_DESTINATION_MAC_ADDRESS, /* Destination MAC address */
    ETHER_EXAMPLE_SOURCE_MAC_ADDRESS,      /* Source MAC address */
    ETHER_EXAMPLE_FRAME_TYPE,              /* Type field */
    ETHER_EXAMPLE_PAYLOAD                  /* Payload value (46byte) */
};

void ether_example_callback (ether_callback_args_t * p_args) {
    switch (p_args->event)
    {
        case ETHER_EVENT_INTERRUPT:
        {
            if (ETHER_EXAMPLE_ETHER_ISR_EC_MPD_MASK == (p_args->status_ecsr & ETHER_EXAMPLE_ETHER_ISR_EC_MPD_MASK))
            {
                g_example_magic_packet_done = ETHER_EXAMPLE_FLAG_ON;
            }

            if (ETHER_EXAMPLE_ETHER_ISR_EE_TC_MASK == (p_args->status_eesr & ETHER_EXAMPLE_ETHER_ISR_EE_TC_MASK))
            {
                g_example_transfer_complete = ETHER_EXAMPLE_FLAG_ON;
            }

            if (ETHER_EXAMPLE_ETHER_ISR_EE_FR_MASK == (p_args->status_eesr & ETHER_EXAMPLE_ETHER_ISR_EE_FR_MASK))
            {
                g_example_receive_complete = ETHER_EXAMPLE_FLAG_ON;
            }

            break;
        }

        default:
        {
        }
    }
}

void ether_advanced_use_internal_buffer_example (void) {
    fsp_err_t err = FSP_SUCCESS;

    /* Source MAC Address */
    static uint8_t mac_address_source[6] = {ETHER_EXAMPLE_SOURCE_MAC_ADDRESS};

    static uint8_t * p_read_buffer_nocopy;
    uint32_t         read_data_size = 0;

    g_ether0_cfg.p_mac_address = mac_address_source;

    g_ether0_cfg.zerocopy   = ETHER_ZEROCOPY_ENABLE;
    g_ether0_cfg.p_callback = (void (*)(ether_callback_args_t *))ether_example_callback;

    /* Open the ether instance with initial configuration. */
    err = R_ETHER_Open(&g_ether0_ctrl, &g_ether0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    do
    {
        /* When the Ethernet link status read from the PHY-LSI Basic Status register is link-up,
         * Initializes the module and make auto negotiation. */
        err = R_ETHER_LinkProcess(&g_ether0_ctrl);
    } while (FSP_SUCCESS != err);


    /* Set user buffer to TX descriptor and enable transmission. */
    err = R_ETHER_Write(&g_ether0_ctrl, (void *) gp_send_data_internal, sizeof(gp_send_data_internal));
    if (FSP_SUCCESS == err)
    {
        /* Wait for the transmission to complete. */
        /* Data array should not change in zero copy mode until transfer complete. */
        while (ETHER_EXAMPLE_FLAG_ON != g_example_transfer_complete)
        {
            ;
        }
    }



    /* Get receive buffer from RX descriptor. */
    err = R_ETHER_Read(&g_ether0_ctrl, (void *) &p_read_buffer_nocopy, &read_data_size);
    assert(FSP_SUCCESS == err);

    /* Process received data here */

    /* Release receive buffer to RX descriptor. */
    err = R_ETHER_BufferRelease(&g_ether0_ctrl);
    assert(FSP_SUCCESS == err);



    /* Disable transmission and receive function and close the ether instance. */
    R_ETHER_Close(&g_ether0_ctrl);

}

#define ETHER_EXAMPLE_ALIGNMENT_32_BYTE                (32)
#define ETHER_EXAMPLE_ETHERNET_FRAME_PAYLOAD_OFFSET    (14)

/* The data buffer must be 32-byte aligned when using zero copy mode. */
static uint8_t gp_send_data_external[ETHER_EXAMPLE_TRANSMIT_ETHERNET_FRAME_SIZE] =
{
    ETHER_EXAMPLE_DESTINATION_MAC_ADDRESS, /* Destination MAC address */
    ETHER_EXAMPLE_SOURCE_MAC_ADDRESS,      /* Source MAC address */
    ETHER_EXAMPLE_FRAME_TYPE,              /* Type field */
    ETHER_EXAMPLE_PAYLOAD                  /* Payload value (46byte) */
};

typedef struct st_buffer_node
{
    uint8_t               * p_buffer;
    struct st_buffer_node * p_next;
} buffer_node_t;

void ether_advanced_use_external_buffer_example (void) {
    fsp_err_t err = FSP_SUCCESS;

    /* Source MAC Address */
    uint8_t mac_address_source[6] = {ETHER_EXAMPLE_SOURCE_MAC_ADDRESS};

    uint8_t       * p_tx_buffer           = NULL;
    uint8_t       * p_rx_buffer           = NULL;
    uint8_t       * p_rx_allocate_buffer  = NULL;
    uint8_t       * p_tx_last_sent_buffer = NULL;
    buffer_node_t * p_tx_buffer_head;
    buffer_node_t * p_tx_buffer_tail;

    uint32_t read_data_size = 0;
    uint8_t  i;

    g_ether0_cfg.p_mac_address = mac_address_source;

    g_ether0_cfg.zerocopy         = ETHER_ZEROCOPY_ENABLE;
    g_ether0_cfg.pp_ether_buffers = NULL;

    /* Create ring buffer structure to manage transmit buffer.*/
    p_tx_buffer_head = (buffer_node_t *) malloc(sizeof(buffer_node_t));
    p_tx_buffer_tail = p_tx_buffer_head;

    for (i = 0; i < g_ether0_cfg.num_tx_descriptors - 1; i++)
    {
        p_tx_buffer_tail->p_buffer = NULL;
        p_tx_buffer_tail->p_next   = (buffer_node_t *) malloc(sizeof(buffer_node_t));
        p_tx_buffer_tail           = p_tx_buffer_tail->p_next;
    }

    p_tx_buffer_tail->p_buffer = NULL;
    p_tx_buffer_tail->p_next   = p_tx_buffer_head;

    /* Open the ether instance with initial configuration. */
    err = R_ETHER_Open(&g_ether0_ctrl, &g_ether0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    i = 0;

    /* Initialize receive buffer in Ethernet driver. */
    while (i < g_ether0_cfg.num_rx_descriptors)
    {
        if (posix_memalign((void **) &p_rx_allocate_buffer, ETHER_EXAMPLE_ALIGNMENT_32_BYTE,
                           g_ether0_cfg.ether_buffer_size * sizeof(char)))
        {

            /* Set receive buffer to Ethernet driver. */
            err = R_ETHER_RxBufferUpdate(&g_ether0_ctrl, (void *) p_rx_allocate_buffer);


            if (FSP_SUCCESS == err)
            {
                i++;
            }
        }
        else
        {
            assert(0);
        }
    }

    do
    {
        /* When the Ethernet link status read from the PHY-LSI Basic Status register is link-up,
         * Initializes the module and make auto negotiation. */
        err = R_ETHER_LinkProcess(&g_ether0_ctrl);
    } while (FSP_SUCCESS != err);

    while (1)
    {
        if (NULL == p_tx_buffer_tail->p_buffer)
        {
            /* Allocate memory to transmit buffer */
            p_tx_buffer = (uint8_t *) malloc(sizeof(gp_send_data_external));

            /* Process transmit data here. */
            memcpy(p_tx_buffer, gp_send_data_external, sizeof(gp_send_data_external));
            gp_send_data_external[ETHER_EXAMPLE_ETHERNET_FRAME_PAYLOAD_OFFSET]++;

            /* Set user buffer to TX descriptor and enable transmission. */
            err = R_ETHER_Write(&g_ether0_ctrl, (void *) gp_send_data_external, sizeof(gp_send_data_external));

            /* Register transmit buffer to ring buffer. */
            if (FSP_SUCCESS == err)
            {
                p_tx_buffer_tail->p_buffer = p_tx_buffer;
                p_tx_buffer_tail           = p_tx_buffer_tail->p_next;
            }
            else
            {
                /* Release transmit buffer. */
                free(p_tx_buffer);
            }
        }

        /* Get receive buffer from RX descriptor. */
        err = R_ETHER_Read(&g_ether0_ctrl, (void *) &p_rx_buffer, &read_data_size);

        if (FSP_SUCCESS == err)
        {
            /* Allocate new receive buffer and update receive buffer to RX descriptor. */
            if (0 ==
                posix_memalign((void **) &p_rx_allocate_buffer, ETHER_EXAMPLE_ALIGNMENT_32_BYTE,
                               g_ether0_cfg.ether_buffer_size * sizeof(char)))
            {
                R_ETHER_RxBufferUpdate(&g_ether0_ctrl, p_rx_allocate_buffer);
            }
            else
            {
                assert(0);
            }

            /* Process received data here. */

            /* Release receive buffer. */
            free(p_rx_buffer);
        }

        /* Release all transmitted buffer from the ring buffer. */
        if (FSP_SUCCESS == R_ETHER_TxStatusGet(&g_ether0_ctrl, (void *) &p_tx_last_sent_buffer))
        {
            buffer_node_t * p_tx_buffer_current = p_tx_buffer_head;
            for (i = 0; i < g_ether0_cfg.num_tx_descriptors; i++)
            {
                if (p_tx_last_sent_buffer == p_tx_buffer_current->p_buffer)
                {
                    do
                    {
                        free(p_tx_buffer_head->p_buffer);
                        p_tx_buffer_head->p_buffer = NULL;
                        p_tx_buffer_head           = p_tx_buffer_head->p_next;
                    } while (p_tx_buffer_head != p_tx_buffer_current);

                    free(p_tx_buffer_head->p_buffer);
                    p_tx_buffer_head->p_buffer = NULL;

                    break;
                }

                p_tx_buffer_current = p_tx_buffer_current->p_next;
            }
        }
    }
}

Data Structures
struct	ether_instance_descriptor_t
struct	ether_extended_cfg_t
struct	ether_instance_ctrl_t

Enumerations
enum	ether_previous_link_status_t
enum	ether_link_change_t
enum	ether_magic_packet_t
enum	ether_link_establish_status_t
enum	ether_eesr_event_mask_t
enum	ether_ecsr_event_mask_t

---

Data Structure Documentation

ether_instance_descriptor_t

struct ether_instance_descriptor_t

EDMAC descriptor as defined in the hardware manual. Structure must be packed at 1 byte.

ether_extended_cfg_t

struct ether_extended_cfg_t

ETHER extension configures the buffer descriptor for ETHER.

Data Fields
ether_instance_descriptor_t *	p_rx_descriptors	Receive descriptor buffer pool.
ether_instance_descriptor_t *	p_tx_descriptors	Transmit descriptor buffer pool.
uint32_t	eesr_event_filter	Filter for EESR related event.
uint8_t	ecsr_event_filter	Filter for ECSR related event.

ether_instance_ctrl_t

struct ether_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_ether_cfg
	Pointer to initial configurations.
ether_instance_descriptor_t *	p_rx_descriptor
	Pointer to the currently referenced transmit descriptor.
ether_instance_descriptor_t *	p_tx_descriptor
	Pointer to the currently referenced receive descriptor.
void *	p_reg_etherc
	Base register of ethernet controller for this channel.
void *	p_reg_edmac
	Base register of EDMA controller for this channel.
ether_previous_link_status_t	previous_link_status
	Previous link status.
ether_link_change_t	link_change
	status of link change
ether_magic_packet_t	magic_packet
	status of magic packet detection
ether_link_establish_status_t	link_establish_status
	Current Link status.

Enumeration Type Documentation

ether_previous_link_status_t

enum ether_previous_link_status_t

Enumerator
ETHER_PREVIOUS_LINK_STATUS_DOWN	Previous link status is down.
ETHER_PREVIOUS_LINK_STATUS_UP	Previous link status is up.

ether_link_change_t

enum ether_link_change_t

Enumerator
ETHER_LINK_CHANGE_NO_CHANGE	Link status is no change.
ETHER_LINK_CHANGE_LINK_DOWN	Link status changes to down.
ETHER_LINK_CHANGE_LINK_UP	Link status changes to up.

ether_magic_packet_t

enum ether_magic_packet_t

Enumerator
ETHER_MAGIC_PACKET_NOT_DETECTED	Magic packet is not detected.
ETHER_MAGIC_PACKET_DETECTED	Magic packet is detected.

ether_link_establish_status_t

enum ether_link_establish_status_t

Enumerator
ETHER_LINK_ESTABLISH_STATUS_DOWN	Link establish status is down.
ETHER_LINK_ESTABLISH_STATUS_UP	Link establish status is up.

ether_eesr_event_mask_t

enum ether_eesr_event_mask_t

Event mask for EESR register

Enumerator
ETHER_EESR_EVENT_MASK_CERF	CERF event.
ETHER_EESR_EVENT_MASK_PRE	PRE event.
ETHER_EESR_EVENT_MASK_RTSF	RTSF event.
ETHER_EESR_EVENT_MASK_RTLF	RTLF event.
ETHER_EESR_EVENT_MASK_RRF	PRF event.
ETHER_EESR_EVENT_MASK_RMAF	RMAF event.
ETHER_EESR_EVENT_MASK_TRO	TRO event.
ETHER_EESR_EVENT_MASK_CD	CD event.
ETHER_EESR_EVENT_MASK_DLC	DLC event.
ETHER_EESR_EVENT_MASK_CND	CND event.
ETHER_EESR_EVENT_MASK_RFOF	RFOF event.
ETHER_EESR_EVENT_MASK_RDE	RDE event.
ETHER_EESR_EVENT_MASK_FR	FR event.
ETHER_EESR_EVENT_MASK_TFUF	TFUF event.
ETHER_EESR_EVENT_MASK_TDE	TDE event.
ETHER_EESR_EVENT_MASK_TC	TC event.
ETHER_EESR_EVENT_MASK_ECI	ECI event.
ETHER_EESR_EVENT_MASK_ADE	ADE event.
ETHER_EESR_EVENT_MASK_RFCOF	RFCOF event.
ETHER_EESR_EVENT_MASK_RABT	RABT event.
ETHER_EESR_EVENT_MASK_TABT	TABT event.
ETHER_EESR_EVENT_MASK_TWB	TWB event.

ether_ecsr_event_mask_t

enum ether_ecsr_event_mask_t

Event mask for ECSR register

Enumerator
ETHER_ECSR_EVENT_MASK_ICD	ICD event.
ETHER_ECSR_EVENT_MASK_MPD	MPD event.
ETHER_ECSR_EVENT_MASK_LCHNG	LCHNG event.
ETHER_ECSR_EVENT_MASK_PSRTO	PSRTO event.
ETHER_ECSR_EVENT_MASK_BFR	BFR event.

Function Documentation

R_ETHER_Open()

fsp_err_t R_ETHER_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 extend config structure or MAC address is NULL.
FSP_ERR_INVALID_ARGUMENT	Interrupt is not enabled.
FSP_ERR_ETHER_PHY_ERROR_LINK	Initialization of PHY-LSI failed.

R_ETHER_Close()

fsp_err_t R_ETHER_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_ETHER_BufferRelease()

fsp_err_t R_ETHER_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_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.

R_ETHER_RxBufferUpdate()

fsp_err_t R_ETHER_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_ETHER_LinkProcess()

fsp_err_t R_ETHER_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	Link is up.
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	Link is down.
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_ETHER_WakeOnLANEnable()

fsp_err_t R_ETHER_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.
FSP_ERR_ETHER_ERROR_LINK	Auto-negotiation is not completed, and reception is not enabled.
FSP_ERR_ETHER_PHY_ERROR_LINK	Initialization of PHY-LSI failed.

R_ETHER_Read()

fsp_err_t R_ETHER_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_ETHER_ERROR_FILTERING	Multicast Frame filter is enable, and Multicast Address Frame is received.
FSP_ERR_INVALID_POINTER	Value of the pointer is NULL.

R_ETHER_Write()

fsp_err_t R_ETHER_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_ETHER_TxStatusGet()

fsp_err_t R_ETHER_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_ETHER_CallbackSet()

fsp_err_t R_ETHER_CallbackSet	(	ether_ctrl_t *const	p_api_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.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.