Driver API for Ethernet PHY Peripheral (Driver_ETH_PHY.h) More...

Content
	Ethernet PHY Mode
	Specify operation modes of the Ethernet PHY interface.

Data Structures
struct	ARM_DRIVER_ETH_PHY
	Access structure of the Ethernet PHY Driver. More...

Typedefs
typedef int32_t(*	ARM_ETH_PHY_Read_t) (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
	Pointer to ARM_ETH_MAC_PHY_Read : Read Ethernet PHY Register.

typedef int32_t(*	ARM_ETH_PHY_Write_t) (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)
	Pointer to ARM_ETH_MAC_PHY_Write : Write Ethernet PHY Register.

Functions
ARM_DRIVER_VERSION	ARM_ETH_PHY_GetVersion (void)
	Get driver version.

int32_t	ARM_ETH_PHY_Initialize (ARM_ETH_PHY_Read_t fn_read, ARM_ETH_PHY_Write_t fn_write)
	Initialize Ethernet PHY Device.

int32_t	ARM_ETH_PHY_Uninitialize (void)
	De-initialize Ethernet PHY Device.

int32_t	ARM_ETH_PHY_PowerControl (ARM_POWER_STATE state)
	Control Ethernet PHY Device Power.

int32_t	ARM_ETH_PHY_SetInterface (uint32_t interface)
	Set Ethernet Media Interface.

int32_t	ARM_ETH_PHY_SetMode (uint32_t mode)
	Set Ethernet PHY Device Operation mode.

ARM_ETH_LINK_STATE	ARM_ETH_PHY_GetLinkState (void)
	Get Ethernet PHY Device Link state.

ARM_ETH_LINK_INFO	ARM_ETH_PHY_GetLinkInfo (void)
	Get Ethernet PHY Device Link information.

Description

Driver API for Ethernet PHY Peripheral (Driver_ETH_PHY.h)

The following section describes the Ethernet PHY Interface as defined in the Driver_ETH_PHY.h header file.

The Driver_ETH_PHY.h contains two #defines that are used to configure the connection between the PHY and the microcontroller device:

ETH_PHY_NUM and
ETH_PHY_ADDR

Usually, the Serial Management Interface (SMI) (using MDC and MDIO) is used to access the PHY’s internal registers to read the state of the link (up/down), duplex mode, speed, and to restart auto-negotiation etc. SMI is a serial bus, which allows to connect up to 32 devices. Devices on the bus are accessed using a 5-bit device address. A default device address is hardware configurable by pin-strapping on the device (some pins are sampled when a reset is asserted or at power-up).

The device’s internal weak pull-up or pull-down resistors define a default device address. This address can be changed by connecting strong pull-up or pull-down resistors externally. In this case, the ETH_PHY_ADDR needs to be defined by the user.

If a microcontroller device offers more than one Ethernet PHY driver, the user needs to set the correct ETH_PHY_NUM in his application.

Data Structure Documentation

◆ ARM_DRIVER_ETH_PHY

struct ARM_DRIVER_ETH_PHY

Access structure of the Ethernet PHY Driver.

The functions of the Ethernet PHY are accessed by function pointers exposed by this structure. Refer to Common Driver Functions for overview information.

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

Driver_ETH_PHY0 is the name of the access struct of the first instance (no. 0).
Driver_ETH_PHY1 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_PHYn. 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_PHY_GetVersion : Get driver version.

int32_t(*	Initialize )(ARM_ETH_PHY_Read_t fn_read, ARM_ETH_PHY_Write_t fn_write)
	Pointer to ARM_ETH_PHY_Initialize : Initialize PHY Device.

int32_t(*	Uninitialize )(void)
	Pointer to ARM_ETH_PHY_Uninitialize : De-initialize PHY Device.

int32_t(*	PowerControl )(ARM_POWER_STATE state)
	Pointer to ARM_ETH_PHY_PowerControl : Control PHY Device Power.

int32_t(*	SetInterface )(uint32_t interface)
	Pointer to ARM_ETH_PHY_SetInterface : Set Ethernet Media Interface.

int32_t(*	SetMode )(uint32_t mode)
	Pointer to ARM_ETH_PHY_SetMode : Set Ethernet PHY Device Operation mode.

ARM_ETH_LINK_STATE(*	GetLinkState )(void)
	Pointer to ARM_ETH_PHY_GetLinkState : Get Ethernet PHY Device Link state.

ARM_ETH_LINK_INFO(*	GetLinkInfo )(void)
	Pointer to ARM_ETH_PHY_GetLinkInfo : Get Ethernet PHY Device Link information.

Field Documentation

◆ GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_ETH_PHY_GetVersion : Get driver version.

◆ Initialize

int32_t(* Initialize) (ARM_ETH_PHY_Read_t fn_read, ARM_ETH_PHY_Write_t fn_write)

Pointer to ARM_ETH_PHY_Initialize : Initialize PHY Device.

◆ Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_ETH_PHY_Uninitialize : De-initialize PHY Device.

◆ PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_ETH_PHY_PowerControl : Control PHY Device Power.

◆ SetInterface

int32_t(* SetInterface) (uint32_t interface)

Pointer to ARM_ETH_PHY_SetInterface : Set Ethernet Media Interface.

◆ SetMode

int32_t(* SetMode) (uint32_t mode)

Pointer to ARM_ETH_PHY_SetMode : Set Ethernet PHY Device Operation mode.

◆ GetLinkState

ARM_ETH_LINK_STATE(* GetLinkState) (void)

Pointer to ARM_ETH_PHY_GetLinkState : Get Ethernet PHY Device Link state.

◆ GetLinkInfo

ARM_ETH_LINK_INFO(* GetLinkInfo) (void)

Pointer to ARM_ETH_PHY_GetLinkInfo : Get Ethernet PHY Device Link information.

Typedef Documentation

◆ ARM_ETH_PHY_Read_t

ARM_ETH_PHY_Read_t

Pointer to ARM_ETH_MAC_PHY_Read : Read Ethernet PHY Register.

Provides the typedef for the register read function ARM_ETH_MAC_PHY_Read.

Parameter for:

ARM_ETH_PHY_Initialize

◆ ARM_ETH_PHY_Write_t

ARM_ETH_PHY_Write_t

Pointer to ARM_ETH_MAC_PHY_Write : Write Ethernet PHY Register.

Provides the typedef for the register write function ARM_ETH_MAC_PHY_Write.

Parameter for:

ARM_ETH_PHY_Initialize

Function Documentation

◆ ARM_ETH_PHY_GetVersion()

ARM_DRIVER_VERSION ARM_ETH_PHY_GetVersion ( void )

Get driver version.

Returns: ARM_DRIVER_VERSION

The function ARM_ETH_PHY_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_PHY Driver_ETH_PHY0;
ARM_DRIVER_ETH_PHY *drv_info;
 
void setup_ethernet_phy (void)  {
  ARM_DRIVER_VERSION  version;
 
  drv_info = &Driver_ETH_PHY0;  
  version = drv_info->GetVersion ();
  if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
    // error handling
    return;
  }
}

◆ ARM_ETH_PHY_Initialize()

int32_t ARM_ETH_PHY_Initialize	(	ARM_ETH_PHY_Read_t	fn_read,
		ARM_ETH_PHY_Write_t	fn_write
	)

Initialize Ethernet PHY Device.

Parameters

[in]	fn_read	Pointer to ARM_ETH_MAC_PHY_Read
[in]	fn_write	Pointer to ARM_ETH_MAC_PHY_Write

Returns: Status Error Codes

The function ARM_ETH_PHY_Initialize initializes the Ethernet PHY interface. It is called when the middleware component starts operation.

The ARM_ETH_PHY_Initialize function performs the following operations:

Initializes the resources needed for Ethernet PHY peripheral.
Registers the ARM_ETH_MAC_PHY_Read register read access function.
Registers the ARM_ETH_MAC_PHY_Write register write access function.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_PHY_Uninitialize()

int32_t ARM_ETH_PHY_Uninitialize ( void )

De-initialize Ethernet PHY Device.

Returns: Status Error Codes

The function ARM_ETH_PHY_Uninitialize de-initializes the resources of Ethernet PHY interface.

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

◆ ARM_ETH_PHY_PowerControl()

int32_t ARM_ETH_PHY_PowerControl ( ARM_POWER_STATE state )

Control Ethernet PHY Device Power.

Parameters

[in] state Power state

Returns: Status Error Codes

The function ARM_ETH_PHY_PowerControl operates the power modes of the Ethernet PHY interface.

The parameter state sets the operation and can have the following values:

ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode the function performs no operation and returns with ARM_DRIVER_OK.
ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Refer to Function Call Sequence for more information.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_PHY_SetInterface()

int32_t ARM_ETH_PHY_SetInterface ( uint32_t interface )

Set Ethernet Media Interface.

Parameters

[in] interface Media Interface type

Returns: Status Error Codes

The function ARM_ETH_PHY_SetInterface specifies the Media Interface Types that links the Ethernet MAC and Ethernet PHY. After initialization of the PHY interface, you can set the media type. The function ARM_ETH_MAC_GetCapabilities retrieves the media interface type encoded in the data field media_interface of the structure ARM_ETH_MAC_CAPABILITIES.

The parameter interface can have the following values:

Parameter interface	Media Type
ARM_ETH_INTERFACE_MII	Media Independent Interface (MII)
ARM_ETH_INTERFACE_RMII	Reduced Media Independent Interface (RMII)
ARM_ETH_INTERFACE_SMII	Serial Media Independent Interface (SMII);

Note: Some interface values may be unsupported by a driver implementation. For example ARM_ETH_INTERFACE_SMII may return ARM_DRIVER_ERROR_UNSUPPORTED.

Example:

static ARM_ETH_MAC_CAPABILITIES capabilities;
static ARM_DRIVER_ETH_MAC *mac;
static ARM_DRIVER_ETH_PHY *phy;
 
mac = &Driver_ETH_MAC0;
phy = &Driver_ETH_PHY0;
 
// Initialize Media Access Controller
capabilities = mac->GetCapabilities ();
...
status = phy->SetInterface (capabilities.media_interface);
if (status != ARM_DRIVER_OK) ...  // error handling
status = phy->SetMode (ARM_ETH_PHY_AUTO_NEGOTIATE);
if (status != ARM_DRIVER_OK) ...  // error handling
...

◆ ARM_ETH_PHY_SetMode()

int32_t ARM_ETH_PHY_SetMode ( uint32_t mode )

Set Ethernet PHY Device Operation mode.

Parameters

[in] mode Operation Mode

Returns: Status Error Codes

The function ARM_ETH_PHY_SetMode sets the operation mode parameters for the Ethernet PHY.

The table below lists the possible values for the parameter mode. Values from different categories can be ORed as shown in this example code:

phy->SetMode (ARM_ETH_PHY_SPEED_100M | ARM_ETH_PHY_LOOPBACK | ARM_ETH_PHY_DUPLEX_HALF );

ARM_ETH_PHY_LOOPBACK

#define ARM_ETH_PHY_LOOPBACK

Loop-back test mode.

ARM_ETH_PHY_DUPLEX_HALF

#define ARM_ETH_PHY_DUPLEX_HALF

Half duplex link.

ARM_ETH_PHY_SPEED_100M

#define ARM_ETH_PHY_SPEED_100M

100 Mbps link speed

Parameter mode	bit	Category	Description
ARM_ETH_PHY_SPEED_10M	0..1	Link Speed	Set the link speed to 10 [Mbps]
ARM_ETH_PHY_SPEED_100M			Set the link speed to 100 [Mbps]
ARM_ETH_PHY_SPEED_1G			Set the link speed to 1 [Gbps]
ARM_ETH_PHY_DUPLEX_HALF	2	Link Mode	Set the link mode to half duplex
ARM_ETH_PHY_DUPLEX_FULL	2	Link Mode	Set the link mode to full duplex
ARM_ETH_PHY_AUTO_NEGOTIATE	3	Autonegotiation	Set the interface to Auto Negotiation mode of transmission parameters
ARM_ETH_PHY_LOOPBACK	4	Loopback	Set the interface into a Loop-back test mode
ARM_ETH_PHY_ISOLATE	5	Isolation	Set to indicate electrical isolation of PHY interface from MII/RMII interface

Note: Some settings may be also taken from configuration pins (example ARM_ETH_PHY_ISOLATE). Check the effect of mode settings in the actual driver implementation.; Some mode values may be unsupported by a driver implementation. For example ARM_ETH_PHY_SPEED_1G may return ARM_DRIVER_ERROR_UNSUPPORTED.

Example:

static ARM_ETH_MAC_CAPABILITIES capabilities;
static ARM_DRIVER_ETH_MAC *mac;
static ARM_DRIVER_ETH_PHY *phy;
 
mac = &Driver_ETH_MAC0;
phy = &Driver_ETH_PHY0;
 
// Initialize Media Access Controller
capabilities = mac->GetCapabilities ();
...
status = phy->SetInterface (capabilities.media_interface);
if (status != ARM_DRIVER_OK) ...  // error handling
status = phy->SetMode (ARM_ETH_PHY_SPEED_100M | ARM_ETH_PHY_DUPLEX_FULL | ARM_ETH_PHY_ISOLATE);
if (status != ARM_DRIVER_OK) ...  // error handling
...

◆ ARM_ETH_PHY_GetLinkState()

ARM_ETH_LINK_STATE ARM_ETH_PHY_GetLinkState ( void )

Get Ethernet PHY Device Link state.

Returns: current link status ARM_ETH_LINK_STATE

The function ARM_ETH_PHY_GetLinkState retrieves the connection status of the physical Ethernet link.

Example:

see Ethernet Interface - Driver Functions

◆ ARM_ETH_PHY_GetLinkInfo()

ARM_ETH_LINK_INFO ARM_ETH_PHY_GetLinkInfo ( void )

Get Ethernet PHY Device Link information.

Returns: current link parameters ARM_ETH_LINK_INFO

The function ARM_ETH_PHY_GetLinkInfo retrieves information about the current established communication mode (half/full duplex) and communication speed. Information is only valid when link is up (see ARM_ETH_PHY_GetLinkState).

Example:

see Ethernet Interface - Driver Functions

Content

Data Structures

Typedefs

Functions

Description

Data Structure Documentation

◆ ARM_DRIVER_ETH_PHY

Data Fields

Field Documentation

◆ GetVersion

◆ Initialize

◆ Uninitialize

◆ PowerControl

◆ SetInterface

◆ SetMode

◆ GetLinkState

◆ GetLinkInfo

Typedef Documentation

◆ ARM_ETH_PHY_Read_t

◆ ARM_ETH_PHY_Write_t

Function Documentation

◆ ARM_ETH_PHY_GetVersion()

◆ ARM_ETH_PHY_Initialize()

◆ ARM_ETH_PHY_Uninitialize()

◆ ARM_ETH_PHY_PowerControl()

◆ ARM_ETH_PHY_SetInterface()

◆ ARM_ETH_PHY_SetMode()

◆ ARM_ETH_PHY_GetLinkState()

◆ ARM_ETH_PHY_GetLinkInfo()