Eth.h

Go to the documentation of this file.

/*
*
* Copyright (c) 2023 Texas Instruments Incorporated
*
* All rights reserved not granted herein.
*
* Limited License.
*
* Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive
* license under copyrights and patents it now or hereafter owns or controls to make,
* have made, use, import, offer to sell and sell ("Utilize") this software subject to the
* terms herein.  With respect to the foregoing patent license, such license is granted
* solely to the extent that any such patent is necessary to Utilize the software alone.
* The patent license shall not apply to any combinations which include this software,
* other than combinations with devices manufactured by or for TI ("TI Devices").
* No hardware patent is licensed hereunder.
*
* Redistributions must preserve existing copyright notices and reproduce this license
* (including the above copyright notice and the disclaimer and (if applicable) source
* code license limitations below) in the documentation and/or other materials provided
* with the distribution
*
* Redistribution and use in binary form, without modification, are permitted provided
* that the following conditions are met:
*
* *       No reverse engineering, decompilation, or disassembly of this software is
* permitted with respect to any software provided in binary form.
*
* *       any redistribution and use are licensed by TI for use only with TI Devices.
*
* *       Nothing shall obligate TI to provide you with source code for the software
* licensed and provided to you in object code.
*
* If software source code is provided to you, modification and redistribution of the
* source code are permitted provided that the following conditions are met:
*
* *       any redistribution and use of the source code, including any resulting derivative
* works, are licensed by TI for use only with TI Devices.
*
* *       any redistribution and use of any object code compiled from the source code
* and any resulting derivative works, are licensed by TI for use only with TI Devices.
*
* Neither the name of Texas Instruments Incorporated nor the names of its suppliers
*
* may be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* DISCLAIMER.
*
* THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "AS IS" AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL TI AND TI'S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
* OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/

/*
 * Below are the generic requirements met by this Eth driver which can't be
 * mapped to a specific piece of code
 */
/*
 * Design:       ETH_DesignId_001
 * Requirements: MCAL-1519, MCAL-1520, MCAL-1522, MCAL-1523,
 *               MCAL-1525, MCAL-1526, MCAL-1531, MCAL-1614,
 *               MCAL-1635, MCAL-1636, MCAL-1703, MCAL-981
 */

#ifndef ETH_H_
#define ETH_H_

/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */

/*
 * Design:       ETH_DesignId_001
 * Requirements: MCAL-1635
 *
 * Note: As per "Header file structure" in Ethernet Driver spec:
 * Eth.h --> Eth_Types.h --> Eth_GeneralTypes.h --> ComStack_Types.h
 */
#include "Eth_Types.h"
#include "Eth_Cfg.h"
#include "Eth_Packet.h"

#ifdef __cplusplus
extern "C"
{
#endif

/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */

/*
 * Design:       ETH_DesignId_001
 * Requirements: MCAL-1522
 */
#define ETH_SW_MAJOR_VERSION            (9U)

#define ETH_SW_MINOR_VERSION            (1U)

#define ETH_SW_PATCH_VERSION            (0U)

#define ETH_AR_RELEASE_MAJOR_VERSION    (4U)

#define ETH_AR_RELEASE_MINOR_VERSION    (3U)

#define ETH_AR_RELEASE_REVISION_VERSION (1U)

#define ETH_VENDOR_ID                   ((uint16) 44U)

#define ETH_MODULE_ID                   ((uint16) 88U)

#define ETH_INSTANCE_ID                 ((uint8) 0U)

/*
 * Design:       ETH_DesignId_003
 * Requirements: MCAL-1530
 */
#ifndef ETH_E_INV_CTRL_IDX

#define ETH_E_INV_CTRL_IDX              ((uint8) 0x01U)
#endif
#ifndef ETH_E_UNINIT

#define ETH_E_UNINIT                    ((uint8) 0x02U)
#endif
#ifndef ETH_E_PARAM_POINTER

#define ETH_E_PARAM_POINTER             ((uint8) 0x03U)
#endif
#ifndef ETH_E_INV_PARAM

#define ETH_E_INV_PARAM                 ((uint8) 0x04U)
#endif
#ifndef ETH_E_INV_MODE

#define ETH_E_INV_MODE                  ((uint8) 0x05U)
#endif
#ifndef ETH_E_VIRTMAC_APIMISMATCH

#define ETH_E_VIRTMAC_APIMISMATCH       ((uint8) 0x07U)
#endif
#ifndef ETH_E_VIRTMAC_RPCCMDFAILED

#define ETH_E_VIRTMAC_RPCCMDFAILED      ((uint8) 0x08U)
#endif
#ifndef ETH_E_VIRTMAC_UNSUPPORTECLIENTNOTIFY

#define ETH_E_VIRTMAC_UNSUPPORTECLIENTNOTIFY ((uint8) 0x09U)
#endif
#ifndef ETH_E_VIRTMAC_UNSUPPORTEDSRVCMD

#define ETH_E_VIRTMAC_UNSUPPORTEDSRVCMD       ((uint8) 0x0AU)
#endif
#ifndef ETH_E_BUSY

#define ETH_E_BUSY                      ((uint8) 0x0BU)
#endif

#define ETH_SID_INIT                    ((uint8) 0x01U)

#define ETH_SID_SET_CONTROLLER_MODE     ((uint8) 0x03U)

#define ETH_SID_GET_CONTROLLER_MODE     ((uint8) 0x04U)

#define ETH_SID_WRITE_MII               ((uint8) 0x05U)

#define ETH_SID_READ_MII                ((uint8) 0x06U)

#define ETH_SID_GET_COUNTER_STATE       ((uint8) 0x07U)

#define ETH_SID_GET_PHYS_ADDR           ((uint8) 0x08U)

#define ETH_SID_PROVIDE_TX_BUFFER       ((uint8) 0x09U)

/* REVISIT: Same as below? */
#define ETH_SID_MAIN_FUNCTION           ((uint8) 0x20U)

#define ETH_SID_TRANSMIT                ((uint8) 0x0AU)

#define ETH_SID_RECEIVE                 ((uint8) 0x0BU)

#define ETH_SID_TX_CONFIRMATION         ((uint8) 0x0CU)

#define ETH_SID_GET_VERSION_INFO        ((uint8) 0x0DU)

#define ETH_SID_RX_IRQ_HDLR             ((uint8) 0x10U)

#define ETH_SID_TX_IRQ_HDLR             ((uint8) 0x11U)

#define ETH_SID_UPDATE_PHYS_ADDR_FILTER ((uint8) 0x12U)

#define ETH_SID_SET_PHYS_ADDR           ((uint8) 0x13U)

#define ETH_SID_GET_COUNTER_VALUES      ((uint8) 0x14U)

#define ETH_SID_GET_RX_STATS            ((uint8) 0x15U)

#define ETH_SID_GET_TX_STATS            ((uint8) 0x1CU)

#define ETH_SID_GET_TXERROR_COUNTERVALUES   ((uint8) 0x1DU)

#define ETH_SID_GET_CURRENT_TIME        ((uint8) 0x16U)

#define ETH_SID_ENABLE_EGRESS_TIMESTAMP ((uint8) 0x17U)

#define ETH_SID_GET_EGRESS_TIMESTAMP    ((uint8) 0x18U)

#define ETH_SID_GET_INGRESS_TIMESTAMP   ((uint8) 0x19U)

#define ETH_SID_DISPATCH_VIRTMAC_INIT  ((uint8) 0x30U)

#define ETH_SID_DISPATCH_VIRTMAC_DEINIT  ((uint8) 0x31U)

#define ETH_SID_NOTIFY_VIRTMAC_MSGRECV ((uint8) 0x32U)

#define ETH_SID_DISPATCH_VIRTMAC_SUBSCRIBE_ALLTRAFFIC   ((uint8) 0x33U)

#define ETH_SID_DISPATCH_VIRTMAC_UNSUBSCRIBE_ALLTRAFFIC ((uint8) 0x34U)

#define ETH_SID_DISPATCH_VIRTMAC_SUBSCRIBE_DSTMAC       ((uint8) 0x35U)

#define ETH_SID_DISPATCH_VIRTMAC_UNSUBSCRIBE_DSTMAC     ((uint8) 0x36U)

#define ETH_SID_DISPATCH_VIRTMAC_IPV4_MACADDR_ASSOCIATE    ((uint8) 0x37U)

#define ETH_SID_DISPATCH_VIRTMAC_IPV4_MACADDR_DISASSOCIATE ((uint8) 0x38U)

#define ETH_SID_DISPATCH_VIRTMAC_ADD_UNICAST_MACADDR ((uint8) 0x39U)

#define ETH_SID_DISPATCH_VIRTMAC_ADD_MCAST_MACADDR ((uint8) 0x3AU)

#define ETH_SID_DISPATCH_VIRTMAC_DEL_MACADDR ((uint8) 0x3BU)

#define ETH_SID_DISPATCH_VIRTMAC_ADD_VLAN ((uint8) 0x3CU)

#define ETH_SID_DISPATCH_VIRTMAC_DEL_VLAN ((uint8) 0x3DU)

#define ETH_SID_VIRTMAC_RPC_INIT   ((uint8) 0x3FU)

#define ETH_SID_SET_BANDWIDTH_LIMIT   ((uint8) 0x50U)

#define ETH_SID_GET_BANDWIDTH_LIMIT   ((uint8) 0x51U)

#define ETH_SID_RELEASE_RX_BUFFER     ((uint8) 0x52U)

#define ETH_SID_PROVIDE_EXT_TX_BUFFER ((uint8) 0x53U)

#define ETH_SID_GET_TX_HEADER_PTR     ((uint8) 0x54U)

#define ETH_SID_GET_RX_HEADER_PTR     ((uint8) 0x55U)

#define ETH_SID_REGISTER_READBACK    ((uint8) 0x56U)


/* ========================================================================== */
/*                         Structures and Enums                               */
/* ========================================================================== */

/* None */

/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */

FUNC(void, ETH_CODE)
Eth_Init(P2CONST(Eth_ConfigType, AUTOMATIC, ETH_PBCFG) CfgPtr);

FUNC(Std_ReturnType, ETH_CODE)
Eth_SetControllerMode(uint8 CtrlIdx,
                      Eth_ModeType CtrlMode);

#if (STD_ON == ETH_VIRTUALMAC_SUPPORT)

FUNC(Std_ReturnType, ETH_CODE)
Eth_SetControllerModeByVirtMac(uint8 CtrlIdx,
                      Eth_ModeType CtrlMode);
#endif

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetControllerMode(uint8 CtrlIdx,
                      P2VAR(Eth_ModeType, AUTOMATIC, ETH_APPL_DATA) CtrlModePtr);

FUNC(void, ETH_CODE)
Eth_GetPhysAddr(uint8 CtrlIdx,
                P2VAR(uint8, AUTOMATIC, ETH_APPL_DATA) PhysAddrPtr);

FUNC(void, ETH_CODE)
Eth_SetPhysAddr(uint8 CtrlIdx,
                P2CONST(uint8, AUTOMATIC, ETH_APPL_DATA) PhysAddrPtr);

#if (STD_ON == ETH_UPDATE_PHYS_ADDR_FILTER_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_UpdatePhysAddrFilter(uint8 CtrlIdx,
                         P2CONST(uint8, AUTOMATIC, ETH_APPL_DATA) PhysAddrPtr,
                         Eth_FilterActionType Action);
#endif /* (STD_ON == ETH_UPDATE_PHYS_ADDR_FILTER_API) */

#if (STD_ON == ETH_ENABLE_MII_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_WriteMii(uint8 CtrlIdx,
             uint8 TrcvIdx,
             uint8 RegIdx,
             uint16 RegVal);

FUNC(Std_ReturnType, ETH_CODE)
Eth_ReadMii(uint8 CtrlIdx,
            uint8 TrcvIdx,
            uint8 RegIdx,
            P2VAR(uint16, AUTOMATIC, ETH_APPL_DATA) RegValPtr);
#endif /* (STD_ON == ETH_ENABLE_MII_API) */

#if (STD_ON == ETH_GET_COUNTER_VALUES_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetCounterValues(uint8 CtrlIdx,
                     Eth_CounterType* CounterPtr);
#endif /* (STD_ON == ETH_GET_COUNTER_VALUES_API) */

#if (STD_ON == ETH_GET_COUNTER_STATE_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetCounterState(uint8 CtrlIdx,
                    uint16 CtrOffs,
                    uint32* CtrValPtr);
#endif /* (STD_ON == ETH_GET_COUNTER_STATE_API) */

#if (STD_ON == ETH_GET_RX_STATS_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetRxStats(uint8 CtrlIdx,
               P2VAR(Eth_RxStatsType, AUTOMATIC, ETH_APPL_DATA) RxStats);
#endif /* (STD_ON == ETH_GET_RX_STATS_API) */

#if (STD_ON == ETH_GET_TX_STATS_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetTxStats(uint8 CtrlIdx,
               P2VAR(Eth_TxStatsType, AUTOMATIC, ETH_APPL_DATA) TxStats);
#endif /* (STD_ON == ETH_GET_TX_STATS_API) */

#if (STD_ON == ETH_GET_TX_ERROR_COUNTERSVALUES_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetTxErrorCounterValues(uint8 CtrlIdx,
               P2VAR(Eth_TxErrorCounterValuesType, AUTOMATIC, ETH_APPL_DATA) TxErrorCounterValues);
#endif

#if (STD_ON == ETH_GLOBALTIMESUPPORT_API)

FUNC(Std_ReturnType, ETH_CODE)
Eth_GetCurrentTime(uint8 CtrlIdx,
                   P2VAR(Eth_TimeStampQualType, AUTOMATIC, ETH_APPL_DATA) timeQualPtr,
                   P2VAR(Eth_TimeStampType, AUTOMATIC, ETH_APPL_DATA) timeStampPtr);

FUNC(void, ETH_CODE)
Eth_EnableEgressTimeStamp(uint8 CtrlIdx, Eth_BufIdxType BufIdx);

FUNC(void, ETH_CODE)
Eth_GetEgressTimeStamp(uint8 CtrlIdx,
                       Eth_BufIdxType BufIdx,
                       P2VAR(Eth_TimeStampQualType, AUTOMATIC, ETH_APPL_DATA) timeQualPtr,
                       P2VAR(Eth_TimeStampType, AUTOMATIC, ETH_APPL_DATA) timeStampPtr);

FUNC(void, ETH_CODE)
Eth_GetIngressTimeStamp(uint8 CtrlIdx,
                        P2VAR(Eth_DataType, AUTOMATIC, ETH_APPL_DATA) DataPtr,
                        P2VAR(Eth_TimeStampQualType, AUTOMATIC, ETH_APPL_DATA) timeQualPtr,
                        P2VAR(Eth_TimeStampType, AUTOMATIC, ETH_APPL_DATA) timeStampPtr);

#endif /* (STD_ON == ETH_GLOBALTIMESUPPORT_API) */

FUNC(BufReq_ReturnType, ETH_CODE)
Eth_ProvideTxBuffer(uint8 CtrlIdx,
                    uint8 Priority,
                    P2VAR(Eth_BufIdxType, AUTOMATIC, ETH_APPL_DAT) BufIdxPtr,
                    P2VAR(uint8, AUTOMATIC, ETH_APPL_DAT) *BufPtr,
                    P2VAR(uint16, AUTOMATIC, ETH_APPL_DAT) LenBytePtr);

FUNC(Std_ReturnType, ETH_CODE)
Eth_Transmit(uint8 CtrlIdx,
             Eth_BufIdxType BufIdx,
             Eth_FrameType FrameType,
             boolean TxConfirmation,
             uint16 LenByte,
             P2CONST(uint8, AUTOMATIC, ETH_APPL_DAT) PhysAddrPtr);

FUNC(void, ETH_CODE)
Eth_Receive(uint8 CtrlIdx,
            uint8 FifoIdx,
            P2VAR(Eth_RxStatusType, AUTOMATIC, ETH_APPL_DAT) RxStatusPtr);

FUNC(void, ETH_CODE)
Eth_TxConfirmation(uint8 CtrlIdx);

#if (STD_ON == ETH_VERSION_INFO_API)

FUNC(void, ETH_CODE)
Eth_GetVersionInfo(P2VAR(Std_VersionInfoType, AUTOMATIC, ETH_APPL_DATA) VersionInfo);
#endif  /* (STD_ON == ETH_VERSION_INFO_API) */

FUNC(void, ETH_CODE)
Eth_MainFunction(void);

#if (STD_ON == ETH_TRAFFIC_SHAPING_API)

FUNC(Std_ReturnType, ETH_CODE) Eth_SetBandwidthLimit(
  uint8   CtrlIdx,
  uint8   QueuePrio,
  uint32  BandwidthLimit);

FUNC(Std_ReturnType, ETH_CODE) Eth_GetBandwidthLimit(
    uint8              CtrlIdx,
    uint8              QueuePrio,
    P2VAR(uint32, AUTOMATIC, ETH_APPL_DAT)  BandwidthLimitPtr);
#endif /* (STD_ON == ETH_TRAFFIC_SHAPING_API) */

#if (STD_ON == ETH_ZERO_COPY_API)

FUNC(Std_ReturnType, ETH_CODE) Eth_ReleaseRxBuffer(uint8 CtrlIdx,
    P2VAR(Eth_DataType, AUTOMATIC, ETH_APPL_DATA) BufPtr);

FUNC(BufReq_ReturnType, ETH_CODE) Eth_ProvideExtTxBuffer(uint8 CtrlIdx,
    uint8 Priority,
    P2VAR(Eth_BufIdxType, AUTOMATIC, ETH_APPL_DATA) BufIdxPtr,
    P2VAR(Eth_DataType, AUTOMATIC, ETH_APPL_DATA) *BufPtr,
    P2VAR(uint16, AUTOMATIC, ETH_APPL_DATA) LenBytePtr);
#endif /* (STD_ON == ETH_ZERO_COPY_API) */

#if (STD_ON == ETH_HEADER_ACCESS_API)

FUNC(Std_ReturnType, ETH_CODE) Eth_GetTxHeaderPtr(uint8 CtrlIdx,
    uint8 BufIdx,
    P2VAR(Eth_DataType, AUTOMATIC, ETH_APPL_DATA) *BufPtr,
    P2VAR(uint16, AUTOMATIC, ETH_APPL_DATA) LenBytePtr);

FUNC(Std_ReturnType, ETH_CODE) Eth_GetRxHeaderPtr(uint8 CtrlIdx,
    P2VAR(Eth_DataType, AUTOMATIC, ETH_APPL_DATA) *BufPtr,
    P2VAR(uint16, AUTOMATIC, ETH_APPL_DATA) LenBytePtr);
#endif /* (STD_ON == ETH_HEADER_ACCESS_API) */

#if (STD_ON == ETH_REGISTER_READBACK_API)

Std_ReturnType Eth_RegisterReadback(
    VAR(uint8, AUTOMATIC)CtrlIdx,
    P2VAR(Eth_RegisterReadbackType, AUTOMATIC, ETH_APPL_DATA) RegRbPtr);
#endif /* (STD_ON == ETH_REGISTER_READBACK_API) */

#ifdef __cplusplus
}
#endif

#endif  /* ETH_H_ */