CMSIS Driver  Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Ethernet MAC Interface

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

Data Structures

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

Typedefs

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

Enumerations

enum  ARM_ETH_MAC_EVENT { ARM_ETH_MAC_EVENT_RX_FRAME }
 Ethernet MAC Event. More...
 

Functions

ARM_DRV_VERSION ARM_ETH_MAC_GetVersion (void)
 Get driver version.
 
ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities (void)
 Get driver capabilities.
 
ARM_ETH_STATUS ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event, ARM_ETH_MAC_ADDR *mac_address)
 Initialize Ethernet MAC Device.
 
ARM_ETH_STATUS ARM_ETH_MAC_Uninitialize (void)
 De-initialize Ethernet MAC Device.
 
ARM_ETH_STATUS ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)
 Control Ethernet MAC Device Power.
 
ARM_ETH_STATUS ARM_ETH_MAC_SetMulticastAddr (uint32_t num_addr, ARM_ETH_MAC_ADDR *ptr_addr)
 Configure Ethernet multicast address filtering.
 
ARM_ETH_STATUS ARM_ETH_MAC_SetMode (ARM_ETH_DUPLEX duplex, ARM_ETH_SPEED speed)
 Set the Ethernet MAC speed and duplex mode.
 
ARM_ETH_STATUS ARM_ETH_MAC_EnableTx (bool enable)
 Enable the Ethernet MAC transmit engine.
 
ARM_ETH_STATUS ARM_ETH_MAC_EnableRx (bool enable)
 Enable the Ethernet MAC receive engine.
 
ARM_ETH_STATUS ARM_ETH_MAC_SendFrame (uint8_t *buf, uint32_t len)
 Send Ethernet frame.
 
int32_t ARM_ETH_MAC_ReadFrame (uint8_t *buf, uint32_t len)
 Read data of received Ethernet frame.
 
int32_t ARM_ETH_MAC_GetRxFrameSize (void)
 Get size of received Ethernet frame.
 
ARM_ETH_STATUS ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
 Read Ethernet PHY Register through Management Interface.
 
ARM_ETH_STATUS 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 (ARM_ETH_MAC_EVENT 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

struct ARM_ETH_MAC_CAPABILITIES

Ethernet MAC Capabilities.

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

Returned by:

Data Fields
uint32_t event_rx_frame: 1 1 = callback event ARM_ETH_MAC_EVENT_RX_FRAME generated
uint32_t mac_address: 1 1 = driver provides serialized MAC address
uint32_t media_interface: 2 Ethernet Media Interface type (see ARM_ETH_INTERFACE)
uint32_t reserved: 20 reserved for future extensions
uint32_t rx_checksum_offload_icmp: 1 1 = Receive ICMP payload checksum verified
uint32_t rx_checksum_offload_ip: 1 1 = Receive IP header checksum verified
uint32_t rx_checksum_offload_tcp: 1 1 = Receive TCP payload checksum verified
uint32_t rx_checksum_offload_udp: 1 1 = Receive UDP payload checksum verified
uint32_t tx_checksum_offload_icmp: 1 1 = Transmit ICMP payload checksum generated
uint32_t tx_checksum_offload_ip: 1 1 = Transmit IP header checksum generated
uint32_t tx_checksum_offload_tcp: 1 1 = Transmit TCP payload checksum generated
uint32_t tx_checksum_offload_udp: 1 1 = Transmit UDP payload checksum generated
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 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:

  • ARM_Driver_ETH_MAC0 is the name of the access struct of the first instance (no. 0).
  • ARM_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 ARM_Driver_ETH_MACn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields

ARM_DRV_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.
 
ARM_ETH_STATUS(* Initialize )(ARM_ETH_MAC_SignalEvent_t cb_event, ARM_ETH_MAC_ADDR *mac_address)
 Pointer to ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.
 
ARM_ETH_STATUS(* Uninitialize )(void)
 Pointer to ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.
 
ARM_ETH_STATUS(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.
 
ARM_ETH_STATUS(* SetMultiCastAddr )(uint32_t num_addr, ARM_ETH_MAC_ADDR *ptr_addr)
 Pointer to ARM_ETH_MAC_SetMulticastAddr : Configure Ethernet multicast address filtering.
 
ARM_ETH_STATUS(* SetMode )(ARM_ETH_DUPLEX duplex, ARM_ETH_SPEED speed)
 Pointer to ARM_ETH_MAC_SetMode : Set the Ethernet MAC speed and duplex mode.
 
ARM_ETH_STATUS(* EnableTx )(bool enable)
 Pointer to ARM_ETH_MAC_EnableTx : Enable the Ethernet MAC transmit engine.
 
ARM_ETH_STATUS(* EnableRx )(bool enable)
 Pointer to ARM_ETH_MAC_EnableRx : Enable the Ethernet MAC receive engine.
 
ARM_ETH_STATUS(* SendFrame )(uint8_t *buf, uint32_t len)
 Pointer to ARM_ETH_MAC_SendFrame : Send Ethernet frame.
 
int32_t(* ReadFrame )(uint8_t *buf, uint32_t len)
 Pointer to ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.
 
int32_t(* GetRxFrameSize )(void)
 Pointer to ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.
 
ARM_ETH_STATUS(* 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.
 
ARM_ETH_STATUS(* 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

ARM_ETH_STATUS(* EnableRx)(bool enable)

Pointer to ARM_ETH_MAC_EnableRx : Enable the Ethernet MAC receive engine.

ARM_ETH_STATUS(* EnableTx)(bool enable)

Pointer to ARM_ETH_MAC_EnableTx : Enable the Ethernet MAC transmit engine.

ARM_ETH_MAC_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_ETH_MAC_GetCapabilities : Get driver capabilities.

int32_t(* GetRxFrameSize)(void)

Pointer to ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.

ARM_DRV_VERSION(* GetVersion)(void)

Pointer to ARM_ETH_MAC_GetVersion : Get driver version.

ARM_ETH_STATUS(* Initialize)(ARM_ETH_MAC_SignalEvent_t cb_event, ARM_ETH_MAC_ADDR *mac_address)

Pointer to ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.

ARM_ETH_STATUS(* 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.

ARM_ETH_STATUS(* 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_STATUS(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.

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

Pointer to ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.

ARM_ETH_STATUS(* SendFrame)(uint8_t *buf, uint32_t len)

Pointer to ARM_ETH_MAC_SendFrame : Send Ethernet frame.

ARM_ETH_STATUS(* SetMode)(ARM_ETH_DUPLEX duplex, ARM_ETH_SPEED speed)

Pointer to ARM_ETH_MAC_SetMode : Set the Ethernet MAC speed and duplex mode.

ARM_ETH_STATUS(* SetMultiCastAddr)(uint32_t num_addr, ARM_ETH_MAC_ADDR *ptr_addr)

Pointer to ARM_ETH_MAC_SetMulticastAddr : Configure Ethernet multicast address filtering.

ARM_ETH_STATUS(* Uninitialize)(void)

Pointer to ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.

Typedef Documentation

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:

Enumeration Type Documentation

Ethernet MAC Event.

Provides the event information for the ARM_ETH_MAC_SignalEvent callback function (which is registered by the function ARM_ETH_MAC_Initialize). The function ARM_ETH_MAC_GetCapabilities returns information of the implemented callback events in a driver.

Parameter for:

Enumerator:
ARM_ETH_MAC_EVENT_RX_FRAME 

Packet Received.

Function Documentation

ARM_ETH_STATUS ARM_ETH_MAC_EnableRx ( bool  enable)

Enable the Ethernet MAC receive engine.

Parameters
[in]enableAction
  • true Enable
  • false Disable
Returns
execution status ARM_ETH_STATUS

The function ARM_ETH_MAC_EnableRx starts (enable = true) or stops (enable = false) the Ethernet MAC receive engine. Data over Ethernet is received using the function ARM_ETH_MAC_ReadFrame.

Subsequent calls to ARM_ETH_MAC_EnableRx are not accumulative - i.e. calling ARM_ETH_MAC_EnableRx (false) still only requires one call ARM_ETH_MAC_EnableRx (true) to enable the Ethernet MAC receive engine.

Example:

ARM_ETH_STATUS ARM_ETH_MAC_EnableTx ( bool  enable)

Enable the Ethernet MAC transmit engine.

Parameters
[in]enableAction
  • true Enable
  • false Disable
Returns
execution status ARM_ETH_STATUS

The function ARM_ETH_MAC_EnableTx starts (enable = true) or stops (enable = false) the Ethernet MAC transmit engine. Data over Ethernet is transmitted using the function ARM_ETH_MAC_SendFrame.

Subsequent calls to ARM_ETH_MAC_EnableTx are not accumulative - i.e. calling ARM_ETH_MAC_EnableTx (false) still only requires one call ARM_ETH_MAC_EnableTx (true) to enable the Ethernet MAC transmit engine.

Example:

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 bitfield members 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 ARM_Driver_ETH_MAC0;
void read_capabilities (void) {
ARM_ETH_MAC_CAPABILITIES mac_capabilities;
mac = &ARM_Driver_ETH_MAC0;
mac_capablilities = mac->GetCapabilities ();
// interrogate capabilities
}
int32_t ARM_ETH_MAC_GetRxFrameSize ( void  )

Get size of received Ethernet frame.

Returns
number of bytes in received frame or execution status
  • value >= 0: number of bytes in received frame
  • value < 0: error occurred, -value is execution status as defined with ARM_ETH_STATUS

Retrieve size or length 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.

Example:

ARM_DRV_VERSION ARM_ETH_MAC_GetVersion ( void  )

Get driver version.

Returns
ARM_DRV_VERSION

The function ARM_ETH_MAC_GetVersion returns version information of the driver implementation in ARM_DRV_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 ARM_Driver_ETH_MAC0;
void setup_ethernet (void) {
ARM_DRV_VERSION version;
mac = &ARM_Driver_ETH_MAC0;
version = mac->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_ETH_STATUS ARM_ETH_MAC_Initialize ( ARM_ETH_MAC_SignalEvent_t  cb_event,
ARM_ETH_MAC_ADDR mac_address 
)

Initialize Ethernet MAC Device.

Parameters
[in]cb_eventPointer to ARM_ETH_MAC_SignalEvent
[in,out]mac_addressPointer to MAC address
Returns
execution status ARM_ETH_STATUS

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 Ehternet MAC peripheral.
  • Registers the ARM_ETH_MAC_SignalEvent callback function.
  • Configures or retrieves the MAC address.
  • Sets the peripheral to ARM_POWER_LOW power mode.
  • Disables the Ethernet receive and transmit engine.

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.

The parameter mac_address must be a pointer to a 6-byte array. Depending on the bit mac_address in ARM_ETH_MAC_CAPABILITIES a MAC Address is provided by the driver or supplied to the driver:

  • ARM_ETH_MAC_CAPABILITIES bit mac_address=1: driver provides a fixed MAC address and stores it in the array addressed by mac_address.
  • ARM_ETH_MAC_CAPABILITIES bit mac_address=0: driver uses the MAC address provided in the array addressed by mac_address.

Example:

ARM_ETH_STATUS 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_addr5-bit device address
[in]reg_addr5-bit register address
[out]dataPointer where the result is written to
Returns
execution status ARM_ETH_STATUS

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:

ARM_ETH_STATUS 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_addr5-bit device address
[in]reg_addr5-bit register address
[in]data16-bit data to write
Returns
execution status ARM_ETH_STATUS

Write 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:

ARM_ETH_STATUS ARM_ETH_MAC_PowerControl ( ARM_POWER_STATE  state)

Control Ethernet MAC Device Power.

Parameters
[in]statePower state
Returns
execution status ARM_ETH_STATUS

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

The argument state can be:

  • ARM_POWER_OFF: Ethernet MAC peripheral is turned off.
  • ARM_POWER_FULL: Ethernet MAC peripheral is turned on and fully operational.
  • ARM_POWER_LOW: Etherner MAC retains state, detects and signals wake-up events.

If power state specifies an unsupported mode, the function returns ARM_ETH_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:

int32_t ARM_ETH_MAC_ReadFrame ( uint8_t *  buf,
uint32_t  len 
)

Read data of received Ethernet frame.

Parameters
[in]bufPointer to frame buffer for data to read into
[in]lenFrame 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 ARM_ETH_STATUS

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_EnableRx 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 -value as defined with ARM_ETH_STATUS.

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_STATUS ARM_ETH_MAC_SendFrame ( uint8_t *  buf,
uint32_t  len 
)

Send Ethernet frame.

Parameters
[in]bufPointer to frame buffer with data to send
[in]lenFrame buffer length in bytes
Returns
execution status ARM_ETH_STATUS

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

The Ethernet MAC transmit engine must be enabled using the function ARM_ETH_MAC_EnableTx before a call to this function.

The frame data addressed by buf starts with MAC destination and ends with the last Payload databyte. 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.

Example:

status = mac->SendFrame (&frame->data[0], frame->length);
if (status != ETH_OK) {
// error handling
}
ARM_ETH_STATUS ARM_ETH_MAC_SetMode ( ARM_ETH_DUPLEX  duplex,
ARM_ETH_SPEED  speed 
)

Set the Ethernet MAC speed and duplex mode.

Parameters
[in]duplexARM_ETH_DUPLEX
[in]speedARM_ETH_SPEED
Returns
execution status ARM_ETH_STATUS

The function ARM_ETH_MAC_SetMode is used to set the communication speed and duplex operating mode for the Ethernet communication. Typically the parameters are obtained using the function ARM_ETH_PHY_GetLinkInfo.

Example:

ARM_ETH_STATUS ARM_ETH_MAC_SetMulticastAddr ( uint32_t  num_addr,
ARM_ETH_MAC_ADDR ptr_addr 
)

Configure Ethernet multicast address filtering.

Parameters
[in]num_addrNumber of multicast addresses to configure
[in]ptr_addrPointer to multicast addresses
Returns
execution status ARM_ETH_STATUS

The function ARM_ETH_MAC_SetMulticastAddr configures Ethernet MAC receiver address filtering. The Ethernet MAC accepts MAC will accept packets Ethernet frames which contains an 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.

The Ethernet MAC receiver will accept packets addressed to its own address (unicast), broadcast packets and packets with multicast addresses configured by this function.

void ARM_ETH_MAC_SignalEvent ( ARM_ETH_MAC_EVENT  event)

Callback function that signals a Ethernet Event.

Parameters
[in]eventARM_ETH_MAC_EVENT
Returns
none

The function ARM_ETH_MAC_SignalEvent is called by the Ethernet MAC driver when certain events occur. The bitfield members of the struct ARM_ETH_MAC_CAPABILITIES encode which events are signalled. This function is typically called from interrupt service routines (ISR) to indicate that a frame is processed.

ARM_ETH_STATUS ARM_ETH_MAC_Uninitialize ( void  )

De-initialize Ethernet MAC Device.

Returns
execution status ARM_ETH_STATUS

The function ARM_ETH_MAC_Uninitialize de-initializes the resources of Ethernet MAC interface and sets the peripheral to ARM_POWER_OFF power mode.

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