![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
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. | |
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.
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:
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. | |
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.
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:
enum ARM_ETH_MAC_EVENT |
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:
ARM_ETH_STATUS ARM_ETH_MAC_EnableRx | ( | bool | enable | ) |
Enable the Ethernet MAC receive engine.
[in] | enable | Action
|
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.
[in] | enable | Action
|
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.
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:
int32_t ARM_ETH_MAC_GetRxFrameSize | ( | void | ) |
Get size of received Ethernet frame.
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.
The function ARM_ETH_MAC_GetVersion returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_ETH_STATUS ARM_ETH_MAC_Initialize | ( | ARM_ETH_MAC_SignalEvent_t | cb_event, |
ARM_ETH_MAC_ADDR * | mac_address | ||
) |
Initialize Ethernet MAC Device.
[in] | cb_event | Pointer to ARM_ETH_MAC_SignalEvent |
[in,out] | mac_address | Pointer to MAC address |
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:
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:
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.
[in] | phy_addr | 5-bit device address |
[in] | reg_addr | 5-bit register address |
[out] | data | Pointer where the result is written to |
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.
[in] | phy_addr | 5-bit device address |
[in] | reg_addr | 5-bit register address |
[in] | data | 16-bit data to write |
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.
[in] | state | Power state |
The function ARM_ETH_MAC_PowerControl allows to configure the power modes of the Ethernet MAC interface.
The argument state can be:
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.
[in] | buf | Pointer to frame buffer for data to read into |
[in] | len | Frame buffer length in bytes |
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:
ARM_ETH_STATUS ARM_ETH_MAC_SendFrame | ( | uint8_t * | buf, |
uint32_t | len | ||
) |
Send Ethernet frame.
[in] | buf | Pointer to frame buffer with data to send |
[in] | len | Frame buffer length in bytes |
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:
ARM_ETH_STATUS ARM_ETH_MAC_SetMode | ( | ARM_ETH_DUPLEX | duplex, |
ARM_ETH_SPEED | speed | ||
) |
Set the Ethernet MAC speed and duplex mode.
[in] | duplex | ARM_ETH_DUPLEX |
[in] | speed | ARM_ETH_SPEED |
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.
[in] | num_addr | Number of multicast addresses to configure |
[in] | ptr_addr | Pointer to multicast addresses |
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.
[in] | event | ARM_ETH_MAC_EVENT |
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.
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.