Driver API for Ethernet MAC Peripheral (Driver_ETH_MAC.h) More...

Content
	Ethernet MAC Events
	The Ethernet MAC driver generates call back events that are notified via the function ARM_ETH_MAC_SignalEvent.

	Ethernet MAC Control Codes
	Configure and control the Ethernet MAC using the ARM_ETH_MAC_Control.

	Ethernet MAC Timer Control Codes
	Control codes for ARM_ETH_MAC_ControlTimer function.

	Ethernet MAC Frame Transmit Flags
	Specify frame transmit flags.

Data Structures
struct	ARM_ETH_MAC_CAPABILITIES
	Ethernet MAC Capabilities. More...

struct	ARM_DRIVER_ETH_MAC
	Access structure of the Ethernet MAC Driver. More...

struct	ARM_ETH_MAC_TIME
	Ethernet MAC Time. More...

Typedefs
typedef void(*	ARM_ETH_MAC_SignalEvent_t) (uint32_t event)
	Pointer to ARM_ETH_MAC_SignalEvent : Signal Ethernet Event.

Functions
ARM_DRIVER_VERSION	ARM_ETH_MAC_GetVersion (void)
	Get driver version.

ARM_ETH_MAC_CAPABILITIES	ARM_ETH_MAC_GetCapabilities (void)
	Get driver capabilities.

int32_t	ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event)
	Initialize Ethernet MAC Device.

int32_t	ARM_ETH_MAC_Uninitialize (void)
	De-initialize Ethernet MAC Device.

int32_t	ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)
	Control Ethernet MAC Device Power.

int32_t	ARM_ETH_MAC_GetMacAddress (ARM_ETH_MAC_ADDR *ptr_addr)
	Get Ethernet MAC Address.

int32_t	ARM_ETH_MAC_SetMacAddress (const ARM_ETH_MAC_ADDR *ptr_addr)
	Set Ethernet MAC Address.

int32_t	ARM_ETH_MAC_SetAddressFilter (const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr)
	Configure Address Filter.

int32_t	ARM_ETH_MAC_SendFrame (const uint8_t *frame, uint32_t len, uint32_t flags)
	Send Ethernet frame.

int32_t	ARM_ETH_MAC_ReadFrame (uint8_t *frame, uint32_t len)
	Read data of received Ethernet frame.

uint32_t	ARM_ETH_MAC_GetRxFrameSize (void)
	Get size of received Ethernet frame.

int32_t	ARM_ETH_MAC_GetRxFrameTime (ARM_ETH_MAC_TIME *time)
	Get time of received Ethernet frame.

int32_t	ARM_ETH_MAC_GetTxFrameTime (ARM_ETH_MAC_TIME *time)
	Get time of transmitted Ethernet frame.

int32_t	ARM_ETH_MAC_Control (uint32_t control, uint32_t arg)
	Control Ethernet Interface.

int32_t	ARM_ETH_MAC_ControlTimer (uint32_t control, ARM_ETH_MAC_TIME *time)
	Control Precision Timer.

int32_t	ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
	Read Ethernet PHY Register through Management Interface.

int32_t	ARM_ETH_MAC_PHY_Write (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)
	Write Ethernet PHY Register through Management Interface.

void	ARM_ETH_MAC_SignalEvent (uint32_t event)
	Callback function that signals a Ethernet Event.

Description

Driver API for Ethernet MAC Peripheral (Driver_ETH_MAC.h)

The following section describes the Ethernet MAC Interface as defined in the Driver_ETH_MAC.h header file.

Data Structure Documentation

◆ ARM_ETH_MAC_CAPABILITIES

struct ARM_ETH_MAC_CAPABILITIES

Ethernet MAC Capabilities.

An Ethernet MAC driver can be implemented with different capabilities.
The data fields of this struct encode the capabilities implemented by this driver.

Returned by:

ARM_ETH_MAC_GetCapabilities

Data Fields
uint32_t	checksum_offload_rx_ip4: 1	1 = IPv4 header checksum verified on receive
uint32_t	checksum_offload_rx_ip6: 1	1 = IPv6 checksum verification supported on receive
uint32_t	checksum_offload_rx_udp: 1	1 = UDP payload checksum verified on receive
uint32_t	checksum_offload_rx_tcp: 1	1 = TCP payload checksum verified on receive
uint32_t	checksum_offload_rx_icmp: 1	1 = ICMP payload checksum verified on receive
uint32_t	checksum_offload_tx_ip4: 1	1 = IPv4 header checksum generated on transmit
uint32_t	checksum_offload_tx_ip6: 1	1 = IPv6 checksum generation supported on transmit
uint32_t	checksum_offload_tx_udp: 1	1 = UDP payload checksum generated on transmit
uint32_t	checksum_offload_tx_tcp: 1	1 = TCP payload checksum generated on transmit
uint32_t	checksum_offload_tx_icmp: 1	1 = ICMP payload checksum generated on transmit
uint32_t	media_interface: 2	Ethernet Media Interface type.
uint32_t	mac_address: 1	1 = driver provides initial valid MAC address
uint32_t	event_rx_frame: 1	1 = callback event ARM_ETH_MAC_EVENT_RX_FRAME generated
uint32_t	event_tx_frame: 1	1 = callback event ARM_ETH_MAC_EVENT_TX_FRAME generated
uint32_t	event_wakeup: 1	1 = wakeup event ARM_ETH_MAC_EVENT_WAKEUP generated
uint32_t	precision_timer: 1	1 = Precision Timer supported
uint32_t	reserved: 15	Reserved (must be zero)

◆ ARM_DRIVER_ETH_MAC

struct ARM_DRIVER_ETH_MAC

Access structure of the Ethernet MAC Driver.

The functions of the Ethernet MAC are accessed by function pointers. Refer to Common Driver Functions for overview information.

Each instance of an Ethernet MAC provides such an access struct. The instance is indicated by a postfix in the symbol name of the access struct, for example:

Driver_ETH_MAC0 is the name of the access struct of the first instance (no. 0).
Driver_ETH_MAC1 is the name of the access struct of the second instance (no. 1).

A configuration setting in the middleware allows connecting the middleware to a specific driver instance Driver_ETH_MACn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields
ARM_DRIVER_VERSION(*	GetVersion )(void)
	Pointer to ARM_ETH_MAC_GetVersion : Get driver version.

ARM_ETH_MAC_CAPABILITIES(*	GetCapabilities )(void)
	Pointer to ARM_ETH_MAC_GetCapabilities : Get driver capabilities.

int32_t(*	Initialize )(ARM_ETH_MAC_SignalEvent_t cb_event)
	Pointer to ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.

int32_t(*	Uninitialize )(void)
	Pointer to ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.

int32_t(*	PowerControl )(ARM_POWER_STATE state)
	Pointer to ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.

int32_t(*	GetMacAddress )(ARM_ETH_MAC_ADDR *ptr_addr)
	Pointer to ARM_ETH_MAC_GetMacAddress : Get Ethernet MAC Address.

int32_t(*	SetMacAddress )(const ARM_ETH_MAC_ADDR *ptr_addr)
	Pointer to ARM_ETH_MAC_SetMacAddress : Set Ethernet MAC Address.

int32_t(*	SetAddressFilter )(const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr)
	Pointer to ARM_ETH_MAC_SetAddressFilter : Configure Address Filter.

int32_t(*	SendFrame )(const uint8_t *frame, uint32_t len, uint32_t flags)
	Pointer to ARM_ETH_MAC_SendFrame : Send Ethernet frame.

int32_t(*	ReadFrame )(uint8_t *frame, uint32_t len)
	Pointer to ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.

uint32_t(*	GetRxFrameSize )(void)
	Pointer to ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.

int32_t(*	GetRxFrameTime )(ARM_ETH_MAC_TIME *time)
	Pointer to ARM_ETH_MAC_GetRxFrameTime : Get time of received Ethernet frame.

int32_t(*	GetTxFrameTime )(ARM_ETH_MAC_TIME *time)
	Pointer to ARM_ETH_MAC_GetTxFrameTime : Get time of transmitted Ethernet frame.

int32_t(*	ControlTimer )(uint32_t control, ARM_ETH_MAC_TIME *time)
	Pointer to ARM_ETH_MAC_ControlTimer : Control Precision Timer.

int32_t(*	Control )(uint32_t control, uint32_t arg)
	Pointer to ARM_ETH_MAC_Control : Control Ethernet Interface.

int32_t(*	PHY_Read )(uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
	Pointer to ARM_ETH_MAC_PHY_Read : Read Ethernet PHY Register through Management Interface.

int32_t(*	PHY_Write )(uint8_t phy_addr, uint8_t reg_addr, uint16_t data)
	Pointer to ARM_ETH_MAC_PHY_Write : Write Ethernet PHY Register through Management Interface.

Field Documentation

◆ GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_ETH_MAC_GetVersion : Get driver version.

◆ GetCapabilities

ARM_ETH_MAC_CAPABILITIES(* GetCapabilities) (void)

Pointer to ARM_ETH_MAC_GetCapabilities : Get driver capabilities.

◆ Initialize

int32_t(* Initialize) (ARM_ETH_MAC_SignalEvent_t cb_event)

Pointer to ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.

◆ Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.

◆ PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.

◆ GetMacAddress

int32_t(* GetMacAddress) (ARM_ETH_MAC_ADDR *ptr_addr)

Pointer to ARM_ETH_MAC_GetMacAddress : Get Ethernet MAC Address.

◆ SetMacAddress

int32_t(* SetMacAddress) (const ARM_ETH_MAC_ADDR *ptr_addr)

Pointer to ARM_ETH_MAC_SetMacAddress : Set Ethernet MAC Address.

◆ SetAddressFilter

int32_t(* SetAddressFilter) (const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr)

Pointer to ARM_ETH_MAC_SetAddressFilter : Configure Address Filter.

◆ SendFrame

int32_t(* SendFrame) (const uint8_t *frame, uint32_t len, uint32_t flags)

Pointer to ARM_ETH_MAC_SendFrame : Send Ethernet frame.

◆ ReadFrame

int32_t(* ReadFrame) (uint8_t *frame, uint32_t len)

Pointer to ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.

◆ GetRxFrameSize

uint32_t(* GetRxFrameSize) (void)

Pointer to ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.

◆ GetRxFrameTime

int32_t(* GetRxFrameTime) (ARM_ETH_MAC_TIME *time)

Pointer to ARM_ETH_MAC_GetRxFrameTime : Get time of received Ethernet frame.

◆ GetTxFrameTime

int32_t(* GetTxFrameTime) (ARM_ETH_MAC_TIME *time)

Pointer to ARM_ETH_MAC_GetTxFrameTime : Get time of transmitted Ethernet frame.

◆ ControlTimer

int32_t(* ControlTimer) (uint32_t control, ARM_ETH_MAC_TIME *time)

Pointer to ARM_ETH_MAC_ControlTimer : Control Precision Timer.

◆ Control

int32_t(* Control) (uint32_t control, uint32_t arg)

Pointer to ARM_ETH_MAC_Control : Control Ethernet Interface.

◆ PHY_Read

int32_t(* PHY_Read) (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)

Pointer to ARM_ETH_MAC_PHY_Read : Read Ethernet PHY Register through Management Interface.

◆ PHY_Write

int32_t(* PHY_Write) (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)

Pointer to ARM_ETH_MAC_PHY_Write : Write Ethernet PHY Register through Management Interface.

◆ ARM_ETH_MAC_TIME

struct ARM_ETH_MAC_TIME

Ethernet MAC Time.

The two members of this struct provide fields to encode time values in the order Nano seconds and seconds.

The member ns is also used as a correction factor for ARM_ETH_MAC_TIMER_ADJUST_CLOCK.

Used in:

Data Fields
uint32_t	ns	Nano seconds.
uint32_t	sec	Seconds.

Typedef Documentation

◆ ARM_ETH_MAC_SignalEvent_t

ARM_ETH_MAC_SignalEvent_t

Pointer to ARM_ETH_MAC_SignalEvent : Signal Ethernet Event.

Provides the typedef for the callback function ARM_ETH_MAC_SignalEvent.

Parameter for:

ARM_ETH_MAC_Initialize

Function Documentation

◆ ARM_ETH_MAC_GetVersion()

ARM_DRIVER_VERSION ARM_ETH_MAC_GetVersion ( void )

Get driver version.

Returns: ARM_DRIVER_VERSION

The function ARM_ETH_MAC_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION

API version is the version of the CMSIS-Driver specification used to implement this driver.
Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_ETH_MAC Driver_ETH_MAC0;
ARM_DRIVER_ETH_MAC *mac;
 
void setup_ethernet (void)  {
  ARM_DRIVER_VERSION  version;
 
  mac = &Driver_ETH_MAC0;  
  version = mac->GetVersion ();
  if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
    // error handling
    return;
  }
}

◆ ARM_ETH_MAC_GetCapabilities()

ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities ( void )

Get driver capabilities.

Returns: ARM_ETH_MAC_CAPABILITIES

The function ARM_ETH_MAC_GetCapabilities retrieves information about capabilities in this driver implementation. The data fields of the struct ARM_ETH_MAC_CAPABILITIES encode various capabilities, for example if a hardware is capable to create checksums in hardware or signal events using the ARM_ETH_MAC_SignalEvent callback function.

Example:

extern ARM_DRIVER_ETH_MAC Driver_ETH_MAC0;
ARM_DRIVER_ETH_MAC *mac;
  
void read_capabilities (void)  {
  ARM_ETH_MAC_CAPABILITIES mac_capabilities;
 
  mac = &Driver_ETH_MAC0;  
  mac_capabilities = mac->GetCapabilities ();
  // interrogate capabilities
 
}

◆ ARM_ETH_MAC_Initialize()

int32_t ARM_ETH_MAC_Initialize ( ARM_ETH_MAC_SignalEvent_t cb_event )

Initialize Ethernet MAC Device.

Parameters

[in] cb_event Pointer to ARM_ETH_MAC_SignalEvent

Returns: Status Error Codes

The function ARM_ETH_MAC_Initialize initializes the Ethernet MAC interface. It is called when the middleware component starts operation.

The ARM_ETH_MAC_Initialize function performs the following operations:

Initializes the resources needed for the Ethernet MAC peripheral.
Registers the ARM_ETH_MAC_SignalEvent callback function.

The parameter cb_event is a pointer to the ARM_ETH_MAC_SignalEvent callback function; use a NULL pointer when no callback signals are required.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_MAC_Uninitialize()

int32_t ARM_ETH_MAC_Uninitialize ( void )

De-initialize Ethernet MAC Device.

Returns: Status Error Codes

The function ARM_ETH_MAC_Uninitialize de-initializes the resources of Ethernet MAC interface.

It is called when the middleware component stops operation and releases the software resources used by the interface.

◆ ARM_ETH_MAC_PowerControl()

int32_t ARM_ETH_MAC_PowerControl ( ARM_POWER_STATE state )

Control Ethernet MAC Device Power.

Parameters

[in] state Power state

Returns: Status Error Codes

The function ARM_ETH_MAC_PowerControl allows you to configure the power modes of the Ethernet MAC interface.

The parameter state can be:

ARM_POWER_OFF: Ethernet MAC peripheral is turned off.
ARM_POWER_FULL: Ethernet MAC peripheral is turned on and fully operational.

If power state specifies an unsupported mode, the function returns ARM_DRIVER_ERROR_UNSUPPORTED as status information and the previous power state of the peripheral is unchanged. Multiple calls with the same state generate no error.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_MAC_GetMacAddress()

int32_t ARM_ETH_MAC_GetMacAddress ( ARM_ETH_MAC_ADDR * ptr_addr )

Get Ethernet MAC Address.

Parameters

[in] ptr_addr Pointer to address

Returns: Status Error Codes

The function ARM_ETH_MAC_GetMacAddress retrieves the Ethernet MAC own address from the driver.

◆ ARM_ETH_MAC_SetMacAddress()

int32_t ARM_ETH_MAC_SetMacAddress ( const ARM_ETH_MAC_ADDR * ptr_addr )

Set Ethernet MAC Address.

Parameters

[in] ptr_addr Pointer to address

Returns: Status Error Codes

The function ARM_ETH_MAC_SetMacAddress configures Ethernet MAC own address. The Ethernet MAC accepts packets Ethernet frames which contains a MAC destination address that matches the address specified with ptr_addr.

The Ethernet MAC receiver will accept also packets with addresses configured by ARM_ETH_MAC_SetAddressFilter function.

MAC receiver can be configured to accept also packets with broadcast address, any multicast address or even all packets regardless of address (Promiscuity Mode). This is configured by function ARM_ETH_MAC_Control with ARM_ETH_MAC_CONFIGURE as control parameter.

◆ ARM_ETH_MAC_SetAddressFilter()

int32_t ARM_ETH_MAC_SetAddressFilter	(	const ARM_ETH_MAC_ADDR *	ptr_addr,
		uint32_t	num_addr
	)

Configure Address Filter.

Parameters

[in]	ptr_addr	Pointer to addresses
[in]	num_addr	Number of addresses to configure

Returns: Status Error Codes

The function ARM_ETH_MAC_SetAddressFilter configures Ethernet MAC receiver address filtering. The Ethernet MAC accepts packets Ethernet frames which contains a MAC destination address of the list supplied with ptr_addr. The parameter ptr_addr provides and array of Ethernet MAC addresses. The number of addresses is supplied by num_addr. Specifying num_adr = 0 disables address filtering previously set with this function.

The Ethernet MAC receiver will accept packets addressed to its own address and packets with addresses configured by this function.

MAC receiver can be configured to accept also packets with broadcast address, any multicast address or even all packets regardless of address (Promiscuity Mode). This is configured by function ARM_ETH_MAC_Control with ARM_ETH_MAC_CONFIGURE as control parameter.

◆ ARM_ETH_MAC_SendFrame()

int32_t ARM_ETH_MAC_SendFrame	(	const uint8_t *	frame,
		uint32_t	len,
		uint32_t	flags
	)

Send Ethernet frame.

Parameters

[in]	frame	Pointer to frame buffer with data to send
[in]	len	Frame buffer length in bytes
[in]	flags	Frame transmit flags (see ARM_ETH_MAC_TX_FRAME_...)

Returns: Status Error Codes

The function ARM_ETH_MAC_SendFrame writes an Ethernet frame to the Ethernet MAC transmit buffer.

The Ethernet MAC transmit engine must be enabled by using the function ARM_ETH_MAC_Control (ARM_ETH_MAC_CONTROL_TX, 1) before a call to this function.

The frame data addressed by buf starts with MAC destination and ends with the last Payload data byte. The frame data is copied into the transmit buffer of the Ethernet MAC interface. The function does not wait until the transmission over the Ethernet is complete, however the memory addressed by buf is available for the next Ethernet frame after return.

The maximum value for len is implied by the size restrictions of the Ethernet frame but is not verified. Using an invalid value for len may generate unpredicted results.

The parameter flags specifies additional attributes for the function as shown in the following table. Multiple flags can be combined, for example: ARM_ETH_MAC_TX_FRAME_EVENT | ARM_ETH_MAC_TX_FRAME_TIMESTAMP.

Flag bit	Description
ARM_ETH_MAC_TX_FRAME_FRAGMENT	Indicates that it is a fragment of the frame. allows you to collect multiple fragments before the frame is sent.
ARM_ETH_MAC_TX_FRAME_EVENT	ARM_ETH_MAC_SignalEvent with event bit ARM_ETH_MAC_EVENT_TX_FRAME set will be called when frame send is complete.
ARM_ETH_MAC_TX_FRAME_TIMESTAMP	Capture the time stamp of the frame. The time stamp can be obtained using the function ARM_ETH_MAC_GetTxFrameTime.

Example:

status = mac->SendFrame (&frame->data[0], frame->length, 0);
if (status != ARM_DRIVER_OK)  {
  // error handling
}

◆ ARM_ETH_MAC_ReadFrame()

int32_t ARM_ETH_MAC_ReadFrame	(	uint8_t *	frame,
		uint32_t	len
	)

Read data of received Ethernet frame.

Parameters

[in]	frame	Pointer to frame buffer for data to read into
[in]	len	Frame buffer length in bytes

Returns

number of data bytes read or execution status

value >= 0: number of data bytes read
value < 0: error occurred, value is execution status as defined with Status Error Codes

The function ARM_ETH_MAC_ReadFrame reads an Ethernet frame from the Ethernet MAC receive buffer.

The Ethernet MAC receive engine must be enabled using the function ARM_ETH_MAC_Control (ARM_ETH_MAC_CONTROL_RX , 1) before a call to this function. The len of the Ethernet frame can be checked using the function ARM_ETH_MAC_GetRxFrameSize.

The frame data addressed by buf starts with MAC destination and ends with the last Payload data byte. The frame data is read from the receive buffer of the Ethernet MAC interface and the number of bytes written into the memory addressed by buf is returned. A negative return value indicates an error whereby the status code is defined with driver common return codes.

The function ARM_ETH_MAC_ReadFrame may be called with buf = NULL and len = 0 to discard or release an frame. This is useful when an incorrect frame has been received or no memory is available to hold the Ethernet frame.

Example:

size = mac->GetRxFrameSize ();
if ((size < 14) || (size > 1514)) {    // frame excludes CRC
  mac->ReadFrame (NULL, 0);            // Frame error, release it
}
len = mac->ReadFrame (&frame->data[0], size);
if (len < 0)  {
  // error handling
}

◆ ARM_ETH_MAC_GetRxFrameSize()

uint32_t ARM_ETH_MAC_GetRxFrameSize ( void )

Get size of received Ethernet frame.

Returns: number of bytes in received frame

The function ARM_ETH_MAC_GetRxFrameSize returns the size of a received Ethernet frame. This function is called before ARM_ETH_MAC_ReadFrame and supplies the value len.

The frame size includes MAC destination and ends with the last Payload data byte. Value 0 indicates that no Ethernet frame is available in the receive buffer. Values smaller than minimum size of Ethernet frame or larger than maximum size of Ethernet frame indicate an invalid frame which needs to be discarded by calling ARM_ETH_MAC_ReadFrame.

Example:

see ARM_ETH_MAC_ReadFrame

◆ ARM_ETH_MAC_GetRxFrameTime()

int32_t ARM_ETH_MAC_GetRxFrameTime ( ARM_ETH_MAC_TIME * time )

Get time of received Ethernet frame.

Parameters

[in] time Pointer to time structure for data to read into

Returns: Status Error Codes

Retrieve time stamp of a received Ethernet frame. This function must be called before the frame is read using ARM_ETH_MAC_ReadFrame.

◆ ARM_ETH_MAC_GetTxFrameTime()

int32_t ARM_ETH_MAC_GetTxFrameTime ( ARM_ETH_MAC_TIME * time )

Get time of transmitted Ethernet frame.

Parameters

[in] time Pointer to time structure for data to read into

Returns: Status Error Codes

The function returns the time stamp of a transmitted Ethernet frame.

◆ ARM_ETH_MAC_Control()

int32_t ARM_ETH_MAC_Control	(	uint32_t	control,
		uint32_t	arg
	)

Control Ethernet Interface.

Parameters

[in]	control	Operation
[in]	arg	Argument of operation (optional)

Returns: Status Error Codes

The function ARM_ETH_MAC_Control controls the Ethernet MAC interface and executes various operations. After initialization, the Ethernet transceiver and receiver are disabled.

The parameter control specifies an operation as defined in the table Parameter control.
The parameter arg provides, depending on the operation, additional information or values.

The table lists values for the parameter control.

Parameter control	Operation
ARM_ETH_MAC_CONFIGURE	Configure the Ethernet MAC interface; For arg values, see table *Parameter arg* for CONFIGURE**
ARM_ETH_MAC_CONTROL_TX	Enable or disable the transmitter; arg : 0=disable; 1=enable
ARM_ETH_MAC_CONTROL_RX	Enable or disable the receiver; arg : 0=disable; 1=enable
ARM_ETH_MAC_FLUSH	Flush a buffer; arg : see table *Parameter arg* for FLUSH**
ARM_ETH_MAC_SLEEP	Exit/Enter Sleep mode; arg : 0=exit; 1=enter and wait for Magic packet
ARM_ETH_MAC_VLAN_FILTER	Configure VLAN Filter for received frames; arg : See table *Parameter arg* for VLAN Filter**

The table Parameter arg for CONFIGURE lists the arg values for the control ARM_ETH_MAC_CONFIGURE. The values can be ORed in the following way:

mac->Control(ARM_ETH_MAC_CONFIGURE, ARM_ETH_MAC_SPEED_100M | ARM_ETH_MAC_DUPLEX_FULL | ARM_ETH_MAC_LOOPBACK);

ARM_ETH_MAC_SPEED_100M

#define ARM_ETH_MAC_SPEED_100M

100 Mbps link speed

ARM_ETH_MAC_LOOPBACK

#define ARM_ETH_MAC_LOOPBACK

Loop-back test mode.

ARM_ETH_MAC_DUPLEX_FULL

#define ARM_ETH_MAC_DUPLEX_FULL

Full duplex link.

ARM_ETH_MAC_CONFIGURE

#define ARM_ETH_MAC_CONFIGURE

Configure MAC; arg = configuration.

Parameter arg CONFIGURE
Parameter arg	Bit	Category	Description
ARM_ETH_MAC_SPEED_10M	0..1	Link Speed	Set the link speed to 10 [Mbps]
ARM_ETH_MAC_SPEED_100M			Set the link speed to 100 [Mbps]
ARM_ETH_MAC_SPEED_1G			Set the link speed to 1 [Gbps]
ARM_ETH_MAC_DUPLEX_HALF	2	Link Mode	Set the link mode to half duplex
ARM_ETH_MAC_DUPLEX_FULL	2	Link Mode	Set the link mode to full duplex
n.a.	3	n.a.	reserved
ARM_ETH_MAC_LOOPBACK	4	Loopback Test Mode	Set the interface into a Loop-back test mode
ARM_ETH_MAC_CHECKSUM_OFFLOAD_RX	5	Receiver Checksum offload	Enable Receiver Checksum offload
ARM_ETH_MAC_CHECKSUM_OFFLOAD_TX	6	Transmitter Checksum offload	Enable Transmitter Checksum offload
ARM_ETH_MAC_ADDRESS_BROADCAST	7	Broadcast Frame address	Accept frames with Broadcast address
ARM_ETH_MAC_ADDRESS_MULTICAST	8	Multicast Frame address	Accept frames with any Multicast address
ARM_ETH_MAC_ADDRESS_ALL	9	Any Frame address	Accept frames with any address (Promiscuous Mode)

The table Parameter arg for FLUSH lists the arg values for the control ARM_ETH_MAC_FLUSH. The arg values can be ORed.

Parameter arg for FLUSH
Parameter arg	Bit	Category	Description
ARM_ETH_MAC_FLUSH_RX	1	Receive buffer	Flush the Receive buffer
ARM_ETH_MAC_FLUSH_TX	2	Transmit buffer	Flush the Transmit buffer

The table Parameter arg for VLAN Filter lists the arg values for the control ARM_ETH_MAC_VLAN_FILTER. The arg values can be ORed.

Parameter arg for VLAN Filter
Parameter arg	Bit	Category	Description
value	0..15	VLAN Tag	Set VLAN Tag value
0	16	Use of VLAN	Compare the complete 16-bit VLAN Tag value
ARM_ETH_MAC_VLAN_FILTER_ID_ONLY	16	Use of VLAN	Compare only the 12-bit VLAN Identifier
0	0..16	Disable	Disable the VLAN Filter

Example:

...
                                         // start transfer
    mac->Control(ARM_ETH_MAC_CONFIGURE, ARM_ETH_MAC_SPEED_100M | ARM_ETH_MAC_DUPLEX_FULL | ARM_ETH_MAC_ADDRESS_BROADCAST);
    mac->Control(ARM_ETH_MAC_CONTROL_TX, 1);
    mac->Control(ARM_ETH_MAC_CONTROL_RX, 1);
   
...                                      // stop transfer
    mac->Control(ARM_ETH_MAC_FLUSH, ARM_ETH_MAC_FLUSH_TX | ARM_ETH_MAC_FLUSH_RX);
    mac->Control(ARM_ETH_MAC_CONTROL_TX, 0);
    mac->Control(ARM_ETH_MAC_CONTROL_RX, 0);
  }
}

For a complete example, refer to Ethernet Interface - Driver Functions.

◆ ARM_ETH_MAC_ControlTimer()

int32_t ARM_ETH_MAC_ControlTimer	(	uint32_t	control,
		ARM_ETH_MAC_TIME *	time
	)

Control Precision Timer.

Parameters

[in]	control	Operation
[in]	time	Pointer to time structure

Returns: Status Error Codes

The function ARM_ETH_MAC_ControlTimer controls the timer required for PTP (Precision Time Protocol).

The parameter control receives ARM_ETH_MAC_TIMER_xxx codes to manage the timer for a PTP enabled Ethernet MAC interface.
The parameter time is pointer to a structure that holds time information.

Mode Parameters: Timer Controls	Description
ARM_ETH_MAC_TIMER_GET_TIME	Retrieve the current time and update the content ARM_ETH_MAC_TIME *time.
ARM_ETH_MAC_TIMER_SET_TIME	Set the new time using the values provided with ARM_ETH_MAC_TIME *time.
ARM_ETH_MAC_TIMER_INC_TIME	Increment the current time by using the values provided with ARM_ETH_MAC_TIME *time.
ARM_ETH_MAC_TIMER_DEC_TIME	Decrement the current time by using the values provided with ARM_ETH_MAC_TIME *time.
ARM_ETH_MAC_TIMER_SET_ALARM	Set the alarm time to the values provided with ARM_ETH_MAC_TIME *time.
ARM_ETH_MAC_TIMER_ADJUST_CLOCK	Set the clock frequency; the value in time->ns is the correction factor in fractional format q31.

◆ ARM_ETH_MAC_PHY_Read()

int32_t ARM_ETH_MAC_PHY_Read	(	uint8_t	phy_addr,
		uint8_t	reg_addr,
		uint16_t *	data
	)

Read Ethernet PHY Register through Management Interface.

Parameters

[in]	phy_addr	5-bit device address
[in]	reg_addr	5-bit register address
[out]	data	Pointer where the result is written to

Returns: Status Error Codes

Read Ethernet PHY Register through the Management Interface. The function is passed to ARM_ETH_PHY_Initialize. The Ethernet PHY driver uses this function to read the value of PHY registers.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_MAC_PHY_Write()

int32_t ARM_ETH_MAC_PHY_Write	(	uint8_t	phy_addr,
		uint8_t	reg_addr,
		uint16_t	data
	)

Write Ethernet PHY Register through Management Interface.

Parameters

[in]	phy_addr	5-bit device address
[in]	reg_addr	5-bit register address
[in]	data	16-bit data to write

Returns: Status Error Codes

The function ARM_ETH_MAC_PHY_Write writes to a Ethernet PHY register through the Management Interface. The function is passed to ARM_ETH_PHY_Initialize. The Ethernet PHY driver uses this function to write data to PHY registers.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_MAC_SignalEvent()

void ARM_ETH_MAC_SignalEvent ( uint32_t event )

Callback function that signals a Ethernet Event.

Parameters

[in] event event notification mask

The function ARM_ETH_MAC_SignalEvent is a callback function registered by the function ARM_ETH_MAC_Initialize. This function is typically called from interrupt service routines (ISR) to indicate that a frame is processed or a special event occurred.

The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_ETH_MAC_CAPABILITIES, which can be retrieved with the function ARM_ETH_MAC_GetCapabilities.

The following events can be generated:

Parameter event	Bit	Description
ARM_ETH_MAC_EVENT_RX_FRAME	0	Occurs after a frame is received. Frame can be read by calling ARM_ETH_MAC_ReadFrame.
ARM_ETH_MAC_EVENT_TX_FRAME	1	Occurs after call to ARM_ETH_MAC_SendFrame to indicate that the frame is transmitted.
ARM_ETH_MAC_EVENT_WAKEUP	2	Indicates that a Magic Packet is received while the driver is in Sleep mode (set by ARM_ETH_MAC_SLEEP using ARM_ETH_MAC_Control).
ARM_ETH_MAC_EVENT_TIMER_ALARM	3	Indicates that a Timer Alarm occurred that was set with ARM_ETH_MAC_TIMER_SET_ALARM using ARM_ETH_MAC_ControlTimer.

Content

Data Structures

Typedefs

Functions

Description

Data Structure Documentation

◆ ARM_ETH_MAC_CAPABILITIES

◆ ARM_DRIVER_ETH_MAC

Data Fields

Field Documentation

◆ GetVersion

◆ GetCapabilities

◆ Initialize

◆ Uninitialize

◆ PowerControl

◆ GetMacAddress

◆ SetMacAddress

◆ SetAddressFilter

◆ SendFrame

◆ ReadFrame

◆ GetRxFrameSize

◆ GetRxFrameTime

◆ GetTxFrameTime

◆ ControlTimer

◆ Control

◆ PHY_Read

◆ PHY_Write

◆ ARM_ETH_MAC_TIME

Typedef Documentation

◆ ARM_ETH_MAC_SignalEvent_t

Function Documentation

◆ ARM_ETH_MAC_GetVersion()

◆ ARM_ETH_MAC_GetCapabilities()

◆ ARM_ETH_MAC_Initialize()

◆ ARM_ETH_MAC_Uninitialize()

◆ ARM_ETH_MAC_PowerControl()

◆ ARM_ETH_MAC_GetMacAddress()

◆ ARM_ETH_MAC_SetMacAddress()

◆ ARM_ETH_MAC_SetAddressFilter()

◆ ARM_ETH_MAC_SendFrame()

◆ ARM_ETH_MAC_ReadFrame()

◆ ARM_ETH_MAC_GetRxFrameSize()

◆ ARM_ETH_MAC_GetRxFrameTime()

◆ ARM_ETH_MAC_GetTxFrameTime()

◆ ARM_ETH_MAC_Control()

◆ ARM_ETH_MAC_ControlTimer()

◆ ARM_ETH_MAC_PHY_Read()

◆ ARM_ETH_MAC_PHY_Write()

◆ ARM_ETH_MAC_SignalEvent()