# EMAC Data Structures
[EMAC]

## Data Structures

struct | _EMAC_Pkt
| EMACObjects EMAC Objects. More...
struct | _pktq
| Packet Queue. More...
struct | _EMAC_DescCh
| Transmit/Receive Descriptor Channel Structure. More...
struct | _EMAC_ChannelInfo
| Transmit/Receive Channel info Structure. More...
struct | _EMAC_AddrConfig
| MAC addresses configuration Structure. More...
struct | _EMAC_Core_Config
| EMAC_Core_Config. More...
struct | _EMAC_Common_Config
| EMAC_Common_Config. More...
struct | _EMAC_Config
| EMAC_Config. More...
struct | _EMAC_Status
| EMAC_Status. More...
struct | _EMAC_Statistics
| EMAC_Statistics. More...
struct | _EMAC_Core
| EMAC Core Instance Structure. More...
struct | _EMAC_Device
| EMAC Main Device Instance Structure. More...

## Typedefs

typedef struct _EMAC_Pkt | EMAC_Pkt
| EMACObjects EMAC Objects.
typedef struct _pktq | PKTQ
| Packet Queue.
typedef struct _EMAC_DescCh | EMAC_DescCh
| Transmit/Receive Descriptor Channel Structure.
typedef struct _EMAC_ChannelInfo | EMAC_ChannelInfo
| Transmit/Receive Channel info Structure.
typedef struct _EMAC_AddrConfig | EMAC_AddrConfig
| MAC addresses configuration Structure.
typedef struct _EMAC_Core_Config | EMAC_Core_Config
| EMAC_Core_Config.
typedef struct _EMAC_Common_Config | EMAC_Common_Config
| EMAC_Common_Config.
typedef struct _EMAC_Config | EMAC_Config
| EMAC_Config.
typedef struct _EMAC_Status | EMAC_Status
| EMAC_Status.
typedef struct _EMAC_Statistics | EMAC_Statistics
| EMAC_Statistics.
typedef struct _EMAC_Core | EMAC_Core
| EMAC Core Instance Structure.
typedef struct _EMAC_Device | EMAC_Device
| EMAC Main Device Instance Structure.

## Typedef Documentation

typedef struct _EMAC_ChannelInfo EMAC_ChannelInfo

Transmit/Receive Channel info Structure.

(one receive and up to 8 transmit per core in this example)

typedef struct _EMAC_Common_Config EMAC_Common_Config

EMAC_Common_Config.

The EMAC_Common_Config structure defines configurations common to all the cors when the EMAC device is operating. It is passed to the device when the device is initialized one time by the master core (EMAC_commonInit()), and remains in effect until the device is de-initialized by the master core (EMAC_commonDeInit()).

The following is a short description of the configuration fields:

UseMdio - Uses MDIO configuration if required. In case of SGMII MAC to MAC communication MDIO is not required. If this field is one (1) configures MDIO zero (0) does not configure MDIO

ModeFlags - Specify the Fixed Operating Mode of the Device:

- EMAC_CONFIG_MODEFLG_CHPRIORITY - Treat TX channels as Priority Levels (Channel 7 is highest, 0 is lowest)
- EMAC_CONFIG_MODEFLG_MACLOOPBACK - Set MAC in Internal Loopback for Testing
- EMAC_CONFIG_MODEFLG_RXCRC - Include the 4 byte EtherCRC in RX frames
- EMAC_CONFIG_MODEFLG_TXCRC - Assume TX Frames Include 4 byte EtherCRC
- EMAC_CONFIG_MODEFLG_PASSERROR - Receive Error Frames for Testing
- EMAC_CONFIG_MODEFLG_PASSCONTROL - Receive Control Frames for Testing

MdioModeFlags - Specify the MDIO/PHY Operation (See csl_MDIO.H)

CoreNum - Specify the master core which does common initialization and de-initialization

PktMTU - Specify the maximal physical packet size

typedef struct _EMAC_Config EMAC_Config

EMAC_Config.

The EMAC_Config structure defines how the EMAC device should operate. It is passed to the device when the device is opened (EMAC_open()), and remains in effect until the device is closed (EMAC_close).

The following is a short description of the configuration fields:

EMACCommonConfig - Specify configurations common to all the cores

EMACCoreConfig - Specify configurations specific to individual cores

typedef struct _EMAC_Core_Config EMAC_Core_Config

EMAC_Core_Config.

The EMAC_Core_Config structure defines configurations specific to individual cores when the EMAC device is operating. It is passed to the device when the device is initialized for individual cores (EMAC_coreInit()), and remains in effect until the device is de-initialized for the corresponding cores (EMAC_coreDeInit()).

The following is a short description of the configuration fields:

A list of callback functions is used to register callback functions with a particular core the EMAC peripheral instance. Callback functions are used by EMAC to communicate with the application. These functions are REQUIRED for operation. The same callback table can be used for multiple cores and/or multiple driver instances.

pfcbGetPacket - Called by EMAC to get a free packet buffer from the application layer for receive data. This function should return NULL is no free packets are available. The size of the packet buffer must be large enough to accommodate a full sized packet (1514 or 1518 depending on the EMAC_CONFIG_MODEFLG_RXCRC flag), plus any application buffer padding (DataOffset).

pfcbFreePacket - Called by EMAC to give a free packet buffer back to the application layer. This function is used to return transmit packets. Note that at the time of the call, structure fields other than pDataBuffer and BufferLen are in an undefined state.

pfcbRxPacket - Called to give a received data packet to the application layer. The applicaiton must accept the packet. When the application is finished with the packet, it can return it to its own free queue. This function also returns a pointer to a free packet to replace the received packet on the EMAC free list. It returns NULL when no free packets are available. The return packet is the same as would be returned by pfcbGetPacket. Thus if a newly received packet is not desired, it can simply be returned to EMAC via the return value.

pfcbStatus - Called to indicate to the application that it should call EMAC_getStatus() to read the current device status. This call is made when device status changes.

pfcbStatistics - Called to indicate to the application that it should call EMAC_getStatistics() to read the current Ethernet statistics. Called when the statistic counters are to the point of overflow.

The hApplication calling argument is the application's handle as supplied to the EMAC device for individual cores in the EMAC_coreInit() function.

DescBase - Descriptor memory selction to place the EMAC descriptors

ChannelInfo - Tx and Rx Channel information to be used by the core

NumOfMacAddrs - Number of MAC addresses to be assigned to the core

MacAddr - Device MAC addresses for the core

RxMaxPktPool - Max Rx packet buffers to get from pool (Must be in the range of 8 to 192)

typedef struct _EMAC_DescCh EMAC_DescCh

Transmit/Receive Descriptor Channel Structure.

(One receive and up to 8 transmit in this example)

typedef struct _EMAC_Pkt EMAC_Pkt

EMACObjects EMAC Objects.

EMAC_Pkt The packet structure defines the basic unit of memory used to hold data packets for the EMAC device.

A packet is comprised of one or more packet buffers. Each packet buffer contains a packet buffer header, and a pointer to the buffer data. The EMAC_Pkt structure defines the packet buffer header.

The pDataBuffer field points to the packet data. This is set when the buffer is allocated, and is not altered.

BufferLen holds the the total length of the data buffer that is used to store the packet (or packet fragment). This size is set by the entity that originally allocates the buffer, and is not altered.

The Flags field contains additional information about the packet

ValidLen holds the length of the valid data currently contained in the data buffer.

DataOffset is the byte offset from the start of the data buffer to the first byte of valid data. Thus (ValidLen+DataOffet)<=BufferLen.

Note that for receive buffer packets, the DataOffset field may be assigned before there is any valid data in the packet buffer. This allows the application to reserve space at the top of data buffer for private use. In all instances, the DataOffset field must be valid for all packets handled by EMAC.

The data portion of the packet buffer represents a packet or a fragment of a larger packet. This is determined by the Flags parameter. At the start of every packet, the SOP bit is set in Flags. If the EOP bit is also set, then the packet is not fragmented. Otherwise; the next packet structure pointed to by the pNext field will contain the next fragment in the packet. On either type of buffer, when the SOP bit is set in Flags, then the PktChannel, PktLength, and PktFrags fields must also be valid. These fields contain additional information about the packet.

The PktChannel field detetmines what channel the packet has arrived on, or what channel it should be transmitted on. The EMAC library supports only a single receive channel, but allows for up to eight transmit channels. Transmit channels can be treated as round-robin or priority queues.

The PktLength field holds the size of the entire packet. On single frag packets (both SOP and EOP set in BufFlags), PktLength and ValidLen will be equal.

The PktFrags field holds the number of fragments (EMAC_Pkt records) used to describe the packet. If more than 1 frag is present, the first record must have EMAC_PKT_FLAGS_SOP flag set, with corresponding fields validated. Each frag/record must be linked list using the pNext field, and the final frag/record must have EMAC_PKT_FLAGS_EOP flag set and pNext=0.

In systems where the packet resides in cacheable memory, the data buffer must start on a cache line boundary and be an even multiple of cache lines in size. The EMAC_Pkt header must not appear in the same cache line as the data portion of the packet. On multi-fragment packets, some packet fragments may reside in cacheable memory where others do not.

        <b> NOTE: It is up to the caller to assure that all packet buffers
        residing in cacheable memory are not currently stored in L1 or L2
        cache when passed to any EMAC function. </b>

Some of the packet Flags can only be set if the device is in the proper configuration to receive the corresponding frames. In order to enable these flags, the following modes must be set: RxCrc Flag : RXCRC Mode in EMAC_Config RxErr Flags : PASSERROR Mode in EMAC_Config RxCtl Flags : PASSCONTROL Mode in EMAC_Config RxPrm Flag : EMAC_RXFILTER_ALL in EMAC_setReceiveFilter()

typedef struct _EMAC_Statistics EMAC_Statistics

EMAC_Statistics.

The statistics structure is the used to retrieve the current count of various packet events in the system. These values represent the delta values from the last time the statistics were read.

typedef struct _EMAC_Status EMAC_Status

EMAC_Status.

The status structure contains information about the MAC's run-time status.

The following is a short description of the configuration fields:

MdioLinkStatus - Current link stat (non-zero on link; see CSL_MDIO.H)

PhyDev - Current PHY device in use (0-31)

RxPktHeld - Current number of Rx packets held by the EMAC device

TxPktHeld - Current number of Tx packets held by the EMAC device

FatalError - Fatal Error Code (TBD)

typedef struct _pktq PKTQ

Packet Queue.

We keep a local packet queue for transmit and receive packets. The queue structure is OS independent.

Copyright 2012, Texas Instruments Incorporated