rt-thread/bsp/hpmicro/libraries/hpm_sdk/drivers/inc/hpm_enet_drv.h

/*
 * Copyright (c) 2021 hpmicro
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

#ifndef HPM_ENET_DRV_H
#define HPM_ENET_DRV_H

/*---------------------------------------------------------------------*
 * Includes
 *---------------------------------------------------------------------*/
#include "hpm_common.h"
#include "hpm_enet_regs.h"
#include "hpm_soc_feature.h"
#include "hpm_enet_soc_drv.h"

/**
 * @brief Enet driver APIs
 * @defgroup enet_interface Enet driver APIs
 * @ingroup communication_interfaces
 * @{
 */

/*---------------------------------------------------------------------*
 *  Macro Constant Declarations
 *---------------------------------------------------------------------*/
#define ENET_HEADER               (14U)    /**< 6-byte Dest addr, 6-byte Src addr, 2-byte type */
#define ENET_EXTRA                (2U)     /**< Extra bytes in some cases */
#define ENET_VLAN_TAG             (4U)     /**< optional 802.1q VLAN Tag */
#define ENET_CRC                  (4U)     /**< Ethernet CRC */
#define ENET_MIN_PAYLOAD          (46U)    /**< Minimum Ethernet payload size */
#define ENET_MAX_PAYLOAD          (1500U)  /**< Maximum Ethernet payload size */
#define ENET_MAX_FRAME_SIZE       (1524U)  /**< ENET_HEADER + ENET_EXTRA + VLAN_TAG + MAX_ENET_PAYLOAD + ENET_CRC */
#define ENET_JUMBO_FRAME_PAYLOAD  (9000U)  /**< Jumbo frame payload size */

#define ENET_ERROR                (0)   /**< ENET error */
#define ENET_SUCCESS              (1)   /**< ENET success */

#define ENET_ADJ_FREQ_BASE_ADDEND (0x7fffffffUL)  /**< PTP base adjustment addend */
#define ENET_ONE_SEC_IN_NANOSEC   (1000000000UL)  /**< one second in nanoseconds */
/*---------------------------------------------------------------------*
 *  Typedef Enum Declarations
 *---------------------------------------------------------------------*/
/** @brief Programmable burst length selections */
typedef enum {
    enet_pbl_1  = 1,
    enet_pbl_2  = 2,
    enet_pbl_4  = 4,
    enet_pbl_8  = 8,
    enet_pbl_16 = 16,
    enet_pbl_32 = 32
} enet_pbl_t;

/** @brief Checksum insertion control selections */
typedef enum {
    enet_cic_bypass = 0,
    enet_cic_insert_ipv4_header,
    enet_cic_insert_tcp_udp_icmp,
    enet_cic_insert_tcp_upd_icmp,
} enet_insert_t;

/** @brief PHY opeartion selections */
typedef enum {
    enet_phy_op_read = 0,
    enet_phy_op_write
} enet_phy_op_t;


/** @brief PHY status */
typedef enum {
    enet_phy_idle = 0,
    enet_phy_busy
} enet_phy_status_t;

/** @brief CSR clock range and MDC clock selections */
/** @note The suggested range of CSR clock is approximately
 *        between the frequency range 1.0MHz-2.5MHz.
 *        You can achieve higher frequency of the MDC clock than the frequency limit of 2.5MHz(specified in the IEEE Std 802.3)
 *        and program a clock divider of lower value. Program the value which is no less than enet_csr_60m_to_100m_mdc_csr_div_4
 *        only if the interfacing chips support faster MDC clocks.
 */
typedef enum {
    enet_csr_60m_to_100m_mdc_csr_div_42 = 0,    /**< CSR clock range: 60-100MHz <==> MDC clock: CSR clock / 42 */
    enet_csr_100m_to_150m_mdc_csr_div_62,       /**< CSR clock range: 100-150MHz <==> MDC clock: CSR clock / 62 */
    enet_csr_20m_to_35m_mdc_csr_div_16,         /**< CSR clock range: 20-35MHz <==> MDC clock: CSR clock / 16 */
    enet_csr_35m_to_60m_mdc_csr_div_26,         /**< CSR clock range: 35-60MHz <==> MDC clock: CSR clock / 26 */
    enet_csr_150m_to_250m_mdc_csr_div_102,      /**< CSR clock range: 150-250MHz <==> MDC clock: CSR clock / 102 */
    enet_csr_250m_to_300m_mdc_csr_div_124,      /**< CSR clock range: 250-300MHz <==> MDC clock: CSR clock / 124 */

    enet_csr_60m_to_100m_mdc_csr_div_4 = 8,     /**< CSR clock / 4 */
    enet_csr_60m_to_100m_mdc_csr_div_6,         /**< CSR clock / 6 */
    enet_csr_60m_to_100m_mdc_csr_div_8,         /**< CSR clock / 8 */
    enet_csr_60m_to_100m_mdc_csr_div_10,        /**< CSR clock / 10 */
    enet_csr_60m_to_100m_mdc_csr_div_12,        /**< CSR clock / 12 */
    enet_csr_60m_to_100m_mdc_csr_div_14,        /**< CSR clock / 14 */
    enet_csr_60m_to_100m_mdc_csr_div_16,        /**< CSR clock / 16 */
    enet_csr_60m_to_100m_mdc_csr_div_18         /**< CSR clock / 18 */
} enet_csr_clk_range_t;

/** @brief enet interface selections */
typedef enum {
    enet_inf_rmii = 4,
    enet_inf_rgmii = 1
} enet_inf_type_t;

/** @brief enet timestamp update methods */
typedef enum {
    enet_ptp_time_coarse_update = 0,
    enet_ptp_time_fine_update
} enet_ptp_time_update_method_t;

/** @brief PTP versions */
typedef enum {
    enet_ptp_v1 = 0,
    enet_ptp_v2
} enet_ptp_version_t;

/** @brief PTP frame types */
typedef enum {
    enet_ptp_frame_ipv4 = 0,
    enet_ptp_frame_ipv6,
    enet_ptp_frame_ethernet
} enet_ptp_frame_type_t;

/** @brief PTP message type for snapshots */
typedef enum {
    enet_ts_ss_ptp_msg_0 = 0, /* SYNC, Follow_Up, Delay_Req, Delay_Resp */
    enet_ts_ss_ptp_msg_1 = 1, /* SYNC */
    enet_ts_ss_ptp_msg_2 = 3, /* Delay_Req */
    enet_ts_ss_ptp_msg_3 = 4, /* SYNC, Follow_Up, Delay_Req, Delay_Resp, Pdelay_Req, Pdelay_Resp, Pdelay_Resp_Follow_Up */
    enet_ts_ss_ptp_msg_4 = 5, /* SYNC, Pdelay_Req, Pdelay_Resp */
    enet_ts_ss_ptp_msg_5 = 7, /* Delay_Req, Pdelay_Req, Pdelay_Resp */
    enet_ts_ss_ptp_msg_6 = 8, /* SYNC, Delay_Req */
    enet_ts_ss_ptp_msg_7 = 12 /* Pdelay_Req, Pdelay_Resp */
} enet_ts_ss_ptp_msg_t;

typedef enum {
    enet_ptp_count_res_high = 0,  /* ptp sub-second count resolution at 0.465 ns */
    enet_ptp_count_res_low        /* ptp su-second count resolution at 1 ns */
} enet_ptp_count_res_t;

/*---------------------------------------------------------------------*
 *  Typedef Struct Declarations
 *---------------------------------------------------------------------*/
/** @brief enet buffer config struct */
typedef struct {
    uint32_t buffer;
    uint32_t count;
    uint16_t size;
} enet_buff_config_t;


/** @brief enet mac config struct */
typedef struct {
    uint32_t mac_addr_high[ENET_SOC_ADDR_MAX_COUNT];
    uint32_t mac_addr_low[ENET_SOC_ADDR_MAX_COUNT];
    uint8_t  valid_max_count;
} enet_mac_config_t;

/** @brief transmission descriptor struct */
typedef struct {
    union {
        uint32_t tdes0;
        struct {
            uint32_t db:   1; /**< * Deferred Bit*/
            uint32_t uf:   1; /**< * Underflow Error */
            uint32_t ed:   1; /**< * Excessive Deferral */
            uint32_t cc:   4; /**< * Collision Count */
            uint32_t vf:   1; /**< * VLAN Frame */
            uint32_t ec:   1; /**< * Excessive Collision */
            uint32_t lc:   1; /**< * Late Collision */
            uint32_t nc:   1; /**< * No Carrier */
            uint32_t loc:  1; /**< * Loss of Carrier */
            uint32_t ipe:  1; /**< * IP Payload Error */
            uint32_t ff:   1; /**< * Frame Flushed */
            uint32_t jt:   1; /**< * Jabber Timeout */
            uint32_t es:   1; /**< * Error Summary */
            uint32_t ihe:  1; /**< * IP Header Error */
            uint32_t ttss: 1; /**< * Transmit Timestamp Status */
            uint32_t vlic: 2; /**< * VLAN Insertion Control */
            uint32_t tch:  1; /**< * Second Address Chained */
            uint32_t ter:  1; /**< * Transmit End of Ring */
            uint32_t cic:  2; /**< * Checksum Insertion Control */
            uint32_t crcr: 1; /**< * CRC Replacement Control */
            uint32_t ttse: 1; /**< * Transmit Timestamp Enable */
            uint32_t dp:   1; /**< * Disable Pad */
            uint32_t dc:   1; /**< * Disable CRC */
            uint32_t fs:   1; /**< * First Segment */
            uint32_t ls:   1; /**< * Last Segment */
            uint32_t ic:   1; /**< * Interrupt on Completion */
            uint32_t own:  1; /**< * Own Bit */
        } tdes0_bm;
    };

    union {
        uint32_t tdes1;
        struct {
            uint32_t tbs1    : 13; /**< Transmit Buffer 1 Size */
            uint32_t reserved:  3; /**< Reserved */
            uint32_t tbs2    : 13; /**< Transmit Buffer 2 Size */
            uint32_t saic    :  3; /**< SA Inertion Control */
        } tdes1_bm;
    };

    union {
        uint32_t tdes2;
        struct {
             uint32_t buffer1;  /**< Buffer 1 Address */
        } tdes2_bm;
    };

    union {
        uint32_t tdes3;
        union {
            uint32_t buffer2;   /**< Buffer 2 Address */
            uint32_t next_desc; /**< Next Descriptor Address */
        } tdes3_bm;
    };

#if ENET_SOC_ALT_EHD_DES_LEN == ENET_SOC_ALT_EHD_DES_MAX_LEN
    struct {
        uint32_t reserved;
    } tdes4_bm;

    struct {
        uint32_t reserved;
    } tdes5_bm;

    struct {
        uint32_t ttsl;  /**< Transmit Frame Timestamp Low */
    } tdes6_bm;

    struct {
        uint32_t ttsh;  /**< Transmit Frame Timestamp High */
    } tdes7_bm;
#endif
} enet_tx_desc_t;


/** @brief reception descriptor struct */
typedef struct
{
    union {
        uint32_t rdes0;

        struct {
                uint32_t ex_sta_rx_addr      : 1;  /**< Extended Status Available or Rx MAC Address*/
                uint32_t ce                  : 1;  /**< CRC Error */
                uint32_t dbe                 : 1;  /**< Dribble Bit Error */
                uint32_t re                  : 1;  /**< Receive Error */
                uint32_t rwt                 : 1;  /**< Receive Watchdog Timeout */
                uint32_t ft                  : 1;  /**< Frame Type */
                uint32_t lc                  : 1;  /**< Late Collision */
                uint32_t ts_ip_gf            : 1;  /**< Timestamp Available, IP Checksum Error or Giant Frame*/
                uint32_t ls                  : 1;  /**< Last Descriptor */
                uint32_t fs                  : 1;  /**< First Descriptor */
                uint32_t vlan                : 1;  /**< VLAN Tag */
                uint32_t oe                  : 1;  /**< Overflow Error */
                uint32_t le                  : 1;  /**< Length Error */
                uint32_t saf                 : 1;  /**< Source Address Filter Fail */
                uint32_t dse                 : 1;  /**< Descriptor Error */
                uint32_t es                  : 1;  /**< Error Summary */
                uint32_t fl                  : 14; /**< Frame Length */
                uint32_t afm                 : 1;  /**< Destination Address Filter Fail */
                uint32_t own                 : 1;  /**< Own Bit */
        } rdes0_bm;
    };

    union {
        uint32_t rdes1;
        struct {
            uint32_t rbs1     : 13; /**< Receive Buffer 1 Size */
            uint32_t reserved0: 1;  /**< Reserved */
            uint32_t rch      : 1;  /**< Second Address Chained */
            uint32_t rer      : 1;  /**< Receive End of Ring */
            uint32_t rbs2     : 13; /**< Receive Buffer 2 Size */
            uint32_t reserved1: 2;  /**< Reserved */
            uint32_t dic      : 1;  /**< Disable Interrupt on Completion */
        } rdes1_bm;
    };

    union {
        uint32_t rdes2;
        struct {
        uint32_t buffer1;       /**< Buffer 1 Address */
        } rdes2_bm;
    };

    union {
        uint32_t rdes3;
        union {
            uint32_t buffer2;   /**< Buffer 2 Address */
            uint32_t next_desc; /**< Next Descriptor Address */
        } rdes3_bm;
    };

#if ENET_SOC_ALT_EHD_DES_LEN == ENET_SOC_ALT_EHD_DES_MAX_LEN
    union {
        uint32_t rdes4;
        struct {
                uint32_t ip_payload_type     : 3; /**< IP Payload Type */
                uint32_t ip_header_err       : 1; /**< IP Header Error */
                uint32_t ip_payload_err      : 1; /**< IP Payload Error */
                uint32_t ip_chksum_bypassed  : 1; /**< IP Checksum Bypassed */
                uint32_t ipv4_pkt_received   : 1; /**< IPv4 Packet Received */
                uint32_t ipv6_pkt_received   : 1; /**< IPv6 Packet Received */
                uint32_t msg_type            : 4; /**< Message Type */
                uint32_t ptp_frame_type      : 1; /**< PTP Frame Type */
                uint32_t ptp_version         : 1; /**< PTP Version */
                uint32_t ts_dp               : 1; /**< Timestamp Dropped */
                uint32_t reserved0           : 1; /**< Reserved */
                uint32_t av_pkt_recv         : 1; /**< AV Packet Received */
                uint32_t av_tagged_pkt_recv  : 1; /**< AV Tagged Packet Received */
                uint32_t vlan_tag_pri_value  : 3; /**< VLAN Tag Priority Value */
                uint32_t reserved1           : 3; /**< Reserved */
                uint32_t l3_fm               : 1; /**< Layer 3 Filter Matched */
                uint32_t l4_fm               : 1; /**< Layer 4 Filter Matched */
                uint32_t l3_l4_fnl           : 2; /**< Layer 3 and Layer 4 Filter Number Matched */
                uint32_t reserved2           : 4; /**< Reserved */
            } rdes4_bm;
    };

    struct {
        uint32_t reserved;
    } rdes5_bm;

    struct {
        uint32_t rtsl;  /**< Receive Frame Timestamp Low */
    }rdes6_bm;

    struct {
        uint32_t rtsh;  /**< Receive Frame Timestamp High */
    } rdes7_bm;
#endif
} enet_rx_desc_t;

/** @brief enet frame struct */
typedef struct{
    uint32_t length;
    uint32_t buffer;
    enet_rx_desc_t *rx_desc;
} enet_frame_t;

/** @brief enet reception frame info struct */
typedef struct  {
    enet_rx_desc_t *fs_rx_desc;
    enet_rx_desc_t *ls_rx_desc;
    uint32_t  seg_count;
} enet_rx_frame_info_t;

/** @brief enet description struct */
typedef struct {
    enet_tx_desc_t *tx_desc_list_head;
    enet_rx_desc_t *rx_desc_list_head;
    enet_tx_desc_t *tx_desc_list_cur;
    enet_rx_desc_t *rx_desc_list_cur;
    enet_buff_config_t tx_buff_cfg;
    enet_buff_config_t rx_buff_cfg;
    enet_rx_frame_info_t rx_frame_info;
} enet_desc_t;

/** @brief PTP timestamp struct */
typedef struct {
    uint32_t sec;
    uint32_t nsec;
    uint8_t sign;
} enet_ptp_time_t;

/* PTP config strcut */
typedef struct {
    uint8_t ssinc;
    uint8_t sub_sec_count_res;
    uint8_t update_method;
    uint32_t addend;
} enet_ptp_config_t;

/*
 *  @brief Bit definition of TDES1
 */
#define ENET_DMATxDesc_TBS2  ((uint32_t)0x1FFF0000)  /**< Transmit Buffer2 Size */
#define ENET_DMATxDesc_TBS1  ((uint32_t)0x00001FFF)  /**< Transmit Buffer1 Size */

#if defined __cplusplus
extern "C" {
#endif /* __cplusplus */
/*---------------------------------------------------------------------*
 * Exported Functions
 *---------------------------------------------------------------------*/
/**
 * @brief Initialize controller
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] inf_type the specified interface
 * @param[in] desc A pointer to descriptor config
 * @param[in] config A pointer to mac config
 * @param[in] intr A mask of all required interrupts
 * @pramm[in] mask_intr A mask of all not required interrupts
 */
int enet_controller_init(ENET_Type *ptr, enet_inf_type_t inf_type, enet_desc_t *desc, enet_mac_config_t *config, uint32_t intr, uint32_t mask_intr);
/**
 * @brief Read phy
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] phy_addr the specified address of phy
 * @param[in] addr the specified address of register
 * @retval A value corresponding to the specifeid register address
 */
uint16_t enet_read_phy(ENET_Type *ptr, uint32_t phy_addr, uint32_t addr);

/**
 * @brief Write phy
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] phy_addr a specified address of phy
 * @param[in] addr a specified address of the register
 * @param[in] data a specified data to be written
 */
void enet_write_phy(ENET_Type *ptr, uint32_t phy_addr, uint32_t addr, uint32_t data);

/**
 * @brief Check if there is a received frame
 *
 * @param[out] parent_rx_desc_list_cur a parrent pointer to the current reception descritpion list
 * @param[in] rx_frame_info A pointer to the information of the reception frames
 * @retval A result of reception frame.
 *         1 means that a reception of frame is successful.
 *         0 means that a reception of frame is unsuccessful.
 */
uint32_t enet_check_received_frame(enet_rx_desc_t **parent_rx_desc_list_cur, enet_rx_frame_info_t *rx_frame_info);

/**
 * @brief get a received frame
 *
 * @param[out] parent_rx_desc_list_cur A parrent pointer to the current reception descritpion list
 * @param[in] rx_frame_info A pointer to the information of the reception frames
 * @retval A struct of the current reception frame
 */
enet_frame_t enet_get_received_frame(enet_rx_desc_t **parent_rx_desc_list_cur, enet_rx_frame_info_t *rx_frame_info);

/**
 * @brief get a received frame from interrupt
 *
 * @param[out] parent_rx_desc_list_cur the parrent pointer to the current reception descritpion list
 * @param[in] rx_frame_info A pointer to the information of the reception frames
 * @param[in] rx_desc_count A total count of the reception descriptors
 * @retval A struct of the current reception frame
 */
enet_frame_t enet_get_received_frame_interrupt(enet_rx_desc_t **parent_rx_desc_list_cur, enet_rx_frame_info_t *rx_frame_info, uint32_t rx_desc_count);

/**
 * @brief prepare for the transmission descriptors
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[out] parent_tx_desc_list_cur a pointer to the information of the reception frames
 * @param[in] frame_length the length of the transmission
 * @param[in] tx_buff_size the size of the transmission buffer
 * @retval a result of the transmission preparation.
 *         1 means that the preparation is successful.
 *         0 means that the prepartion is unsuccessful.
 */
uint32_t enet_prepare_transmission_descriptors(ENET_Type *ptr, enet_tx_desc_t **parent_tx_desc_list_cur, uint16_t frame_length, uint16_t tx_buff_size);

/**
 * @brief Initialize DMA transmission descriptors in chain mode
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] desc A pointer to transmission descriptors
 */
void enet_dma_tx_desc_chain_init(ENET_Type *ptr, enet_desc_t *desc);

/**
 * @brief Initialize DMA reception descriptors in chain mode
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] desc A pointer to reception descriptors
 */
void enet_dma_rx_desc_chain_init(ENET_Type *ptr,  enet_desc_t *desc);

/**
 * @brief Flush DMA
 *
 * @param[in] ptr An Ethernet peripheral base address
 */
void enet_dma_flush(ENET_Type *ptr);

/**
 * @brief Initialize a PTP timer
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] config A pointer to an enet_ptp_config struct instance
 */
void enet_init_ptp(ENET_Type *ptr, enet_ptp_config_t *config);

/**
 * @brief Set a timestamp to the PTP timer
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] timestamp A pointer to a timestamp structure instance
 */
void enet_set_ptp_timestamp(ENET_Type *ptr, enet_ptp_time_t *timestamp);

/**
 * @brief Get a timestamp from the PTP timer
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[out] timestamp A pointer to a timestamp structure instance
 */
void enet_get_ptp_timestamp(ENET_Type *ptr, enet_ptp_time_t *timestamp);

/**
 * @brief Update a timestamp to the PTP timer
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] timeoffset A pointer to a timestamp structure instance
 */
void enet_update_ptp_timeoffset(ENET_Type *ptr, enet_ptp_time_t *timeoffset);

/**
 * @brief Adjust the count frequency of the PTP timer
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] adj An adjustment value for the count frequency of the PTP timer
 */
void enet_adjust_ptp_time_freq(ENET_Type *ptr, int32_t adj);

/**
 * @brief Set the PTP version
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] ptp_ver An enum value indicating the PTP protocol
 */
void enet_set_ptp_version(ENET_Type *ptr, enet_ptp_version_t ptp_ver);

/**
 * @brief Enable the specified ptp frame type for MAC process
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] ptp_frame_type An enum value indicating the transport protocol of PTP frames
 * @param[in] enable A value to enable or disable the transport protocol of PTP frames which is specified by ptp_frame_type parameter
 * @retval hpm_stat_t @ref status_invalid_argument or @ref status_success
 */
hpm_stat_t enet_enable_ptp_frame_type(ENET_Type *ptr, enet_ptp_frame_type_t ptp_frame_type, bool enable);

/**
 * @brief Set the ptp message type for snapshots
 *
 * @param[in] ptr An Ethernet peripheral base address
 * @param[in] ts_ss_ptp_msg An enum value indicating the specified ptp message type for snapshots
 */
void enet_set_snapshot_ptp_message_type(ENET_Type *ptr, enet_ts_ss_ptp_msg_t ts_ss_ptp_msg);

#if defined __cplusplus
}
#endif /* __cplusplus */

/** @} */
#endif /* HPM_ENET_DRV_H */