Custom Ethernet PHY Integration Guide

New PHY Driver implemetation 

The following list of steps is provided as guideline when adding a new PHY driver for a device which is not supported by Enet LLD.

Note: For the list of PHY drivers supported by Enet LLD, refer to Using Ethphy devices supported out-of-box

Select “CUSTOM” (ETHPHY (ENET CPSW/ICSS) -> ETHPHY Device) option in Sys-Cfg gui. This will modify the auto-generated ti_board_config.c file based on the “Custom Device Name” specified in the GUI.
Add the PHY extendedCfg (if needed) to the “Extended Configuration” text box for the custom device. This configuration will be automtically updated in ti_board_config.c file.
Copy the sample source file, public PHY specific header file and private header file (if needed) from source/networking/enet/core/internal_docs/templates into the directory that contains your example main.c file.
- This header file should have the device extended configuration structure definition (if applicable) as well as auxiliary structures or enumerations.
In the source file, modify the function pointers of Phy_DrvObj_t structure if needed for device specific implementation.
- Look for reuse of PHY generic functions if a device specific implementation is not needed.
- Add the required device specific functionality to the sample functions. Refer to the existing code in source/board/ethphy/enet/rtos_drivers/src for driver source files.

Build the project with new PHY driver 

When using CCS to build, add the source file and header files to the CCS example.
- Select the file operation as “Link to files” and select yes for Adjust Compiler Include-Paths
When using makefiles to build, add the PHY source file to “FILES_common” and header file path to “INCLUDES_common” in the example makefile.

FILES_common := \
  l2_cpsw_main.c \
  main.c \
  myethphy.c \    /*New PHY source file*/

...

INCLUDES_common := \
  -I../ \         /*Path to PHY header files*/
  -I${CG_TOOL_ROOT}/include/c \
  -I${MCU_PLUS_SDK_PATH}/source \

...

API 

ENETPHY_SOK: Success.

ENETPHY_EFAIL: Generic failure error condition (typically caused by hardware).

ENETPHY_EBADARGS: Bad arguments (i.e. NULL pointer).

ENETPHY_EINVALIDPARAMS: Invalid parameters (i.e. value out-of-range).

ENETPHY_ETIMEOUT: Time out while waiting for a given condition to happen.

ENETPHY_EALLOC: Allocation failure.

ENETPHY_EPERM: Operation not permitted.

ENETPHY_ENOTSUPPORTED: Operation not supported.

ENETPHY_EUNAVAILABLE: Operation not supported.

ENETPHY_LINK_CAP_HD10: 10-Mbps, half-duplex capability mask.

ENETPHY_LINK_CAP_FD10: 10-Mbps, full-duplex capability mask.

ENETPHY_LINK_CAP_HD100: 100-Mbps, half-duplex capability mask.

ENETPHY_LINK_CAP_FD100: 100-Mbps, full-duplex capability mask.

ENETPHY_LINK_CAP_HD1000: 1-Gbps, half-duplex capability mask.

ENETPHY_LINK_CAP_FD1000: 1-Gbps, full-duplex capability mask.

ENETPHY_LINK_CAP_10: 10-Mbps, full and half-duplex capability mask.

ENETPHY_LINK_CAP_100: 100-Mbps, full and half-duplex capability mask.

ENETPHY_LINK_CAP_1000: 1-Gbps, full and half-duplex capability mask.

ENETPHY_LINK_CAP_ALL: Auto-negotiation mask with all duplexity and speed values set.

enum EnetPhy_Magic

EnetPhy driver magic value, used to indicate if driver is open or not.

Values:

enumerator ENETPHY_MAGIC: Magic number used to identify when driver has been opened.

enumerator ENETPHY_NO_MAGIC: Magic number used to identify when driver is closed.

enum EnetPhy_Mii

MAC Media-Independent Interface (MII).

Values:

enumerator ENETPHY_MAC_MII_MII: MII interface.

enumerator ENETPHY_MAC_MII_RMII: RMII interface.

enumerator ENETPHY_MAC_MII_GMII: GMII interface.

enumerator ENETPHY_MAC_MII_RGMII: RGMII interface.

enumerator ENETPHY_MAC_MII_SGMII: SGMII interface.

enumerator ENETPHY_MAC_MII_QSGMII: QSGMII interface.

enum EnetPhy_Speed

MAC interface speed.

Values:

enumerator ENETPHY_SPEED_10MBIT: 10 Mbps

enumerator ENETPHY_SPEED_100MBIT: 100 Mbps

enumerator ENETPHY_SPEED_1GBIT: 1 Gbps

enumerator ENETPHY_SPEED_AUTO: Speed determined automatically

enum EnetPhy_Duplexity

MAC interface duplexity.

Values:

enumerator ENETPHY_DUPLEX_HALF: Half duplex

enumerator ENETPHY_DUPLEX_FULL: Full duplex

enumerator ENETPHY_DUPLEX_AUTO: Duplexity determined automatically

enum EnetPhy_LinkStatus

PHY link status.

Values:

enumerator ENETPHY_GOT_LINK: PHY got link up

enumerator ENETPHY_LINK_UP: PHY link is still up

enumerator ENETPHY_LOST_LINK: PHY lost link

enumerator ENETPHY_LINK_DOWN: PHY link is still down

enum EnetPhy_FsmState

PHY driver state-machine states.

Values:

enumerator ENETPHY_FSM_STATE_INIT: INIT state.

enumerator ENETPHY_FSM_STATE_FINDING: FINDING state.

enumerator ENETPHY_FSM_STATE_RESET_WAIT: RESET_WAIT state.

enumerator ENETPHY_FSM_STATE_ENABLE: ENABLE state.

enumerator ENETPHY_FSM_STATE_FOUND: FOUND state.

enumerator ENETPHY_FSM_STATE_NWAY_START: NWAY_START state (auto-negotiation path)

enumerator ENETPHY_FSM_STATE_NWAY_WAIT: NWAY_WAIT state (auto-negotiation path)

enumerator ENETPHY_FSM_STATE_LINK_WAIT: LINK_WAIT state.

enumerator ENETPHY_FSM_STATE_LINKED: LINKED state.

enumerator ENETPHY_FSM_STATE_LOOPBACK: LOOPBACK state.

enumerator ENETPHY_FSM_STATE_ISOLATE: ISOLATE state.

typedef struct Mdio_Obj_s Mdio_Obj

typedef EnetPhy_Mdio *EnetPhy_MdioHandle: MDIO driver handle.

typedef struct EnetPhy_Obj_s *EnetPhy_Handle

PHY driver object handle.

PHY driver opaque handle used to call any PHY related APIs.

void EnetPhy_initCfg(EnetPhy_Cfg *phyCfg)

Initialize PHY config params.

Initializes PHY driver configuration parameters.

Parameters:: phyCfg – PHY configuration params

void EnetPhy_setExtendedCfg(EnetPhy_Cfg *phyCfg, const void *extendedCfg, uint32_t extendedCfgSize)

Set PHY extended parameters.

Sets the PHY-specific extended parameters to the PHY config structure.

Parameters:

phyCfg – Pointer to the PHY config
extendedCfg – Pointer to the PHY extended config
extendedCfgSize – Size of the PHY extended config

EnetPhy_Handle EnetPhy_open(const EnetPhy_Cfg *phyCfg, EnetPhy_Mii mii, const EnetPhy_LinkCfg *linkCfg, uint32_t macPortCaps, EnetPhy_MdioHandle hMdio, Mdio_Obj *mdioArgs)

Open the PHY driver.

Open the Ethernet PHY driver for the given MAC port number. The PHY driver takes PHY specific configuration parameters, the MAC port type connection and the desired link configuration (auto or manual).

Parameters:

phyCfg – PHY configuration params
mii – PHY MII interface type
linkCfg – Link configuration (speed and duplexity)
macPortCaps – MAC port speed/duplex capabilities. It’s a bit mask of EnetPhy_LinkCaps
hMdio – MDIO driver to be used for PHY register read/write
mdioArgs – Private data passed to the MDIO driver functions

Returns:

PHY device handle if successful, NULL otherwise.

void EnetPhy_close(EnetPhy_Handle hPhy)

Close the PHY driver.

Closes the Ethernet PHY driver.

Parameters:: hPhy – PHY device handle

EnetPhy_LinkStatus EnetPhy_tick(EnetPhy_Handle hPhy)

Run PHY state machine.

Runs the PHY FSM.

Parameters:: hPhy – PHY device handle
Returns:: Whether PHY got or lost link, or no change.

int32_t EnetPhy_getId(EnetPhy_Handle hPhy, EnetPhy_Version *version)

Get PHY id.

Gets the device ID of a PHY, read from IDR1 and IDR2 registers.

Parameters:

hPhy – PHY device handle
version – Pointer to PHY version.

Returns:

EnetPhy_ErrorCodes

bool EnetPhy_isAlive(EnetPhy_Handle hPhy)

Get PHY alive status.

Gets the PHY alive status. Whether PHY is responding to read accesses.

Parameters:: hPhy – PHY device handle
Returns:: true if PHY is alive, false otherwise

bool EnetPhy_isLinked(EnetPhy_Handle hPhy)

Get link status.

Gets the link status: linked or not, based on driver’s state machine. The PHY driver state machine can take a little longer to detect link up because it runs on tick period intervals and need to traverse few states to reach link up FSM state.

Parameters:: hPhy – PHY device handle
Returns:: true if PHY is linked, false otherwise

int32_t EnetPhy_getLinkCfg(EnetPhy_Handle hPhy, EnetPhy_LinkCfg *linkCfg)

Get link configuration.

Gets the link configuration, that is, the configuration that the PHY has negotiated with the link partner or the manual link configuration it was set to.

Parameters:

hPhy – PHY device handle
linkCfg – Link configuration

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getLinkStatus(EnetPhy_Handle hPhy, EnetPhy_Speed *speed, EnetPhy_Duplexity *duplex)

Get link speed, duplex from phy registers.

Gets the link speed and duplexity from phy registers. This API will not have longterm support and it will eventually be merged to EnetPhy_getLinkCfg() in upcoming release. So EnetPhy_getLinkCfg() API can be continued to use to get the phy link speed, duplexity

Parameters:

hPhy – PHY device handle
speed – Link speed read from phy register
duplex – Link duplexity read from phy register

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_readReg(void *pArgs, uint32_t reg, uint16_t *val)

Read PHY register.

Reads a PHY register. It’s not meant for extended registers.

Parameters:

pArgs – PHY device handle
reg – Register number
val – Pointer to the read value

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_writeReg(void *pArgs, uint32_t reg, uint16_t val)

Write PHY register.

Writes a PHY register. It’s not meant for extended registers.

Parameters:

pArgs – PHY device handle
reg – Register number
val – Value to be written

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_rmwReg(void *pArgs, uint32_t reg, uint16_t mask, uint16_t val)

Read-modify-write PHY register.

Read-modify-write a PHY register. It’s not meant for extended registers.

Parameters:

pArgs – PHY device handle
reg – Register number
mask – Bitmask to be applied on read value and value to be written
val – Value to be written

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_readExtReg(void *pArgs, uint32_t reg, uint16_t *val)

Read PHY extended register.

Reads a PHY extended register.

Parameters:

pArgs – PHY device handle
reg – Register number
val – Pointer to the read value

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_writeExtReg(void *pArgs, uint32_t reg, uint16_t val)

Write PHY extended register.

Writes a PHY extended register.

Parameters:

pArgs – PHY device handle
reg – Register number
val – Value to be written

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_rmwExtReg(EnetPhy_Handle hPhy, uint32_t reg, uint16_t mask, uint16_t val)

Read-modify-write PHY extended register.

Read-modify-write a PHY extended register.

Parameters:

hPhy – PHY device handle
reg – Register number
mask – Bitmask to be applied on read value and value to be written
val – Value to be written

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_readC45Reg(EnetPhy_Handle hPhy, uint8_t mmd, uint32_t reg, uint16_t *val)

Read PHY register using Clause-45 frame.

Reads a PHY register using Clause-45 frame.

Parameters:

hPhy – PHY device handle
mmd – MMD
reg – Register number
val – Pointer to the read value

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_writeC45Reg(EnetPhy_Handle hPhy, uint8_t mmd, uint32_t reg, uint16_t val)

Write PHY register using Clause-45 frame.

Writes a PHY register using Clause-45 frame.

Parameters:

hPhy – PHY device handle
mmd – MMD
reg – Register number
val – Value to be written

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_rmwC45Reg(EnetPhy_Handle hPhy, uint8_t mmd, uint32_t reg, uint16_t mask, uint16_t val)

Read-modify-write PHY register using Clause-45 frame.

Read-modify-write a PHY register using Clause-45 frame.

Parameters:

hPhy – PHY device handle
mmd – MMD
reg – Register number
mask – Bitmask to be applied on read value and value to be written
val – Value to be written

Returns:

EnetPhy_ErrorCodes

void EnetPhy_printRegs(EnetPhy_Handle hPhy)

Print all PHY registers.

Prints all registers of a PHY.

Parameters:: hPhy – PHY device handle

int32_t EnetPhy_adjPtpFreq(EnetPhy_Handle hPhy, int64_t ppb)

Adjust PHY PTP clock frequency.

Parameters:

hPhy – PHY device handle
ppb – Part per billion

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_adjPtpPhase(EnetPhy_Handle hPhy, int64_t offset)

Adjust PHY PTP clock phase.

Parameters:

hPhy – PHY device handle
offset – Offset to current clock time in nanosec unit.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getPtpTime(EnetPhy_Handle hPhy, uint64_t *ts64)

Get current PHY PTP clock time.

Parameters:

hPhy – PHY device handle
ts64 – Output current PTP clock time in nanosec unit.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_setPtpTime(EnetPhy_Handle hPhy, uint64_t ts64)

Set PHY PTP clock time.

Parameters:

hPhy – PHY device handle
ts64 – PTP time in nanosec unit will be set.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getPtpTxTime(EnetPhy_Handle hPhy, uint32_t domain, uint32_t msgType, uint32_t seqId, uint64_t *ts64)

Get PHY PTP TX packet timestamp.

Parameters:

hPhy – PHY device handle
domain – PTP domain (in the packet header)
msgType – PTP message type (in the packet header)
seqId – PTP packet sequence ID (in the packet header)
ts64 – Output PTP TX packet timestamp in nanosec unit.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getPtpRxTime(EnetPhy_Handle hPhy, uint32_t domain, uint32_t msgType, uint32_t seqId, uint64_t *ts64)

Get PHY PTP RX packet timestamp.

Parameters:

hPhy – PHY device handle
domain – PTP domain (in the packet header)
msgType – PTP message type (in the packet header)
seqId – PTP packet sequence ID (in the packet header)
ts64 – Output PTP RX packet timestamp in nanosec unit.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_waitPtpTxTime(EnetPhy_Handle hPhy, uint32_t domain, uint32_t msgType, uint32_t seqId)

Add PHY PTP TX packet info to a waiting TX timestamp list.

Parameters:

hPhy – PHY device handle
domain – PTP domain (in the packet header)
msgType – PTP message type (in the packet header)
seqId – PTP packet sequence ID (in the packet header)

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_procStatusFrame(EnetPhy_Handle hPhy, uint8_t *frame, uint32_t size, uint32_t *types)

Process PHY status frame.

Parameters:

hPhy – PHY device handle
frame – Ethernet PHY status frame
size – Frame size
types – Types of processed frame

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getStatusFrameEthHeader(EnetPhy_Handle hPhy, uint8_t *ethhdr, uint32_t size)

Get PHY status frame header.

Parameters:

hPhy – PHY device handle
ethhdr – Buffer to get the ethernet header of the PHY status frame.
size – Buffer size (at least 14 bytes)

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_enablePtp(EnetPhy_Handle hPhy, bool on, uint32_t srcMacStatusFrameType)

Enable/Disable PHY PTP module.

Parameters:

hPhy – PHY device handle
on – Flag indicate enable (on=true) or disable(on=false) PTP module
srcMacStatusFrameType – The PHY-specific src MAC of the status frame.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_tickDriver(EnetPhy_Handle hPhy)

Provide timer tick to the driver.

Parameters:: hPhy – PHY device handle
Returns:: EnetPhy_ErrorCodes

int32_t EnetPhy_enableEventCapture(EnetPhy_Handle hPhy, uint32_t eventIdx, bool falling, bool on)

Enable/Disable an event capture on a PHY GPIO pin.

Parameters:

hPhy – PHY device handle
eventIdx – Event index
falling – Capture event on falling edge or rising edge if falling is false.
on – Enable when on is true, otherwise disable the event.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_enableTriggerOutput(EnetPhy_Handle hPhy, uint32_t triggerIdx, uint64_t start, uint64_t period, bool repeat)

Enable/Disable clock trigger on a GPIO pin.

Parameters:

hPhy – PHY device handle
triggerIdx – Trigger index
start – Start trigger time in nanosec unit.
period – Period of the clock in nanosec unit. Disable the trigger if the period is equal to 0.
repeat – Repeat the clock or one shot if repeat is false.

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_getEventTs(EnetPhy_Handle hPhy, uint32_t *eventIdx, uint32_t *seqId, uint64_t *ts64)

Get event timestamp.

Get event timestamp

Parameters:

hPhy – PHY device handle
eventIdx – Output event index
seqId – Output event sequence identifier
ts64 – Output event timestamp

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_configMediaClock(EnetPhy_Handle hPhy, bool isMaster, uint8_t *streamIDMatchValue, bool enTrigOut)

config Media Clock

Parameters:

hPhy – PHY device handle
isMaster – Media Clock Master/Slave Mode
streamIDMatchValue – Stream ID Match Value for CRF Parsing
enTrigOut – If true, starts 100Hz phase aligned signal to the media clock at LED0

Returns:

EnetPhy_ErrorCodes

int32_t EnetPhy_nudgeCodecClock(EnetPhy_Handle hPhy, int8_t nudgeValue)

Nudge Codec Clock.

Nudge Codec Clock

Parameters:

hPhy – PHY device handle
nudgeValue – int8_t value to nudge Codec clock.

Returns:

EnetPhy_ErrorCodes

ENETPHY_IS_ADDR_VALID(addr): Check if PHY address is valid (0 - 31).

ENETPHY_BIT(n): Macro to set bit at given bit position.

ENETPHY_IS_BIT_SET(val, n): Macro to check if bit at given bit position is set.

ENETPHY_ARRAYSIZE(x): Macro to get the size of an array.

ENETPHY_EXTENDED_CFG_SIZE_MAX: Max extended configuration size, arbitrarily chosen.

ENETPHY_FSM_TICK_PERIOD_MS: Enet PHY State Machine tick period.

ENETPHY_INVALID_PHYADDR: Invalid PHY address indicator.

ENETPHY_TIMEOUT_WAIT_FOREVER: State timeout value to set to disable timeout.

ENETPHY_TIMEOUT_NO_WAIT: State timeout value to set to expire immediately.

struct EnetPhy_Version: #include <enetphy.h>

PHY version (ID).

struct EnetPhy_LinkCfg: #include <enetphy.h>

Link speed and duplexity configuration.

struct EnetPhy_FsmTimeoutCfg: #include <enetphy.h>

PHY State-Machine time-out values.

struct EnetPhy_Cfg: #include <enetphy.h>

PHY configuration parameters.

struct EnetPhy_Mdio: #include <enetphy.h>

MDIO driver.

struct EnetPhy_State: #include <enetphy.h>

PHY driver FSM state.

struct EnetPhy_Obj: #include <enetphy.h>

PHY driver object.

Custom Ethernet PHY Integration Guide

New PHY Driver implemetation

Build the project with new PHY driver

API

New PHY Driver implemetation 

Build the project with new PHY driver 

API 