raw/cnxk_bphy: add doxygen comments

Documentation in doxygen format is important for API
headers used by end user. This patch fills BPHY and CGX
interface with missing bits.

Signed-off-by: Jakub Palider <jpalider@marvell.com>
Reviewed-by: Jerin Jacob <jerinj@marvell.com>
This commit is contained in:
Jakub Palider 2022-06-04 18:26:44 +02:00 committed by Thomas Monjalon
parent 81388ad14b
commit d309d1e17c

View File

@ -13,103 +13,169 @@
#include <rte_memcpy.h>
#include <rte_rawdev.h>
/**
* @file rte_pmd_bphy.h
*
* Marvell CGX and BPHY PMD specific structures and interface
*
* This API allows applications to manage BPHY memory in user space along with
* installing interrupt handlers for low latency signal processing.
*/
#ifdef __cplusplus
extern "C" {
#endif
/** Available message types */
enum cnxk_bphy_cgx_msg_type {
/** Type used to obtain link information */
CNXK_BPHY_CGX_MSG_TYPE_GET_LINKINFO,
/** Type used to disable internal loopback */
CNXK_BPHY_CGX_MSG_TYPE_INTLBK_DISABLE,
/** Type used to enable loopback */
CNXK_BPHY_CGX_MSG_TYPE_INTLBK_ENABLE,
/** Type used to disable PTP on RX */
CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_DISABLE,
/** Type used to enable PTP on RX */
CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_ENABLE,
/** Type used to set link mode */
CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_MODE,
/** Type used to set link state */
CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_STATE,
/** Type used to start transmission and packet reception */
CNXK_BPHY_CGX_MSG_TYPE_START_RXTX,
/** Type used to stop transmission and packet reception */
CNXK_BPHY_CGX_MSG_TYPE_STOP_RXTX,
/** Type used to obtain supported FEC */
CNXK_BPHY_CGX_MSG_TYPE_GET_SUPPORTED_FEC,
/** Type used to set FEC */
CNXK_BPHY_CGX_MSG_TYPE_SET_FEC,
};
/** Available link speeds */
enum cnxk_bphy_cgx_eth_link_speed {
CNXK_BPHY_CGX_ETH_LINK_SPEED_NONE,
CNXK_BPHY_CGX_ETH_LINK_SPEED_10M,
CNXK_BPHY_CGX_ETH_LINK_SPEED_100M,
CNXK_BPHY_CGX_ETH_LINK_SPEED_1G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_2HG,
CNXK_BPHY_CGX_ETH_LINK_SPEED_5G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_10G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_20G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_25G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_40G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_50G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_80G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_100G,
CNXK_BPHY_CGX_ETH_LINK_SPEED_NONE, /**< None */
CNXK_BPHY_CGX_ETH_LINK_SPEED_10M, /**< 10 Mbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_100M, /**< 100 Mbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_1G, /**< 1 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_2HG, /**< 2.5 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_5G, /**< 5 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_10G, /**< 10 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_20G, /**< 20 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_25G, /**< 25 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_40G, /**< 40 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_50G, /**< 50 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_80G, /**< 80 Gbps */
CNXK_BPHY_CGX_ETH_LINK_SPEED_100G, /**< 100 Gbps */
__CNXK_BPHY_CGX_ETH_LINK_SPEED_MAX
};
/** Available FEC modes */
enum cnxk_bphy_cgx_eth_link_fec {
/** Disable FEC */
CNXK_BPHY_CGX_ETH_LINK_FEC_NONE,
/** Base FEC (IEEE 802.3 CLause 74) */
CNXK_BPHY_CGX_ETH_LINK_FEC_BASE_R,
/** Reed-Solomon FEC */
CNXK_BPHY_CGX_ETH_LINK_FEC_RS,
__CNXK_BPHY_CGX_ETH_LINK_FEC_MAX
};
/** Available link modes */
enum cnxk_bphy_cgx_eth_link_mode {
/** SGMII */
CNXK_BPHY_CGX_ETH_LINK_MODE_SGMII_BIT,
/** 1000BASE-X */
CNXK_BPHY_CGX_ETH_LINK_MODE_1000_BASEX_BIT,
/** QSGMII */
CNXK_BPHY_CGX_ETH_LINK_MODE_QSGMII_BIT,
/** 10GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_10G_C2C_BIT,
/** 10GBASE-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_10G_C2M_BIT,
/** 10GBASE-KR */
CNXK_BPHY_CGX_ETH_LINK_MODE_10G_KR_BIT,
/** 20GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_20G_C2C_BIT,
/** 25GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_25G_C2C_BIT,
/** 25GBASE-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_25G_C2M_BIT,
/** 25GBASE-2-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_25G_2_C2C_BIT,
/** 25GBASE-CR */
CNXK_BPHY_CGX_ETH_LINK_MODE_25G_CR_BIT,
/** 25GBASE-KR */
CNXK_BPHY_CGX_ETH_LINK_MODE_25G_KR_BIT,
/** 40GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_40G_C2C_BIT,
/** 40GBASE-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_40G_C2M_BIT,
/** 40GBASE-CR4 */
CNXK_BPHY_CGX_ETH_LINK_MODE_40G_CR4_BIT,
/** 40GBASE-KR4 */
CNXK_BPHY_CGX_ETH_LINK_MODE_40G_KR4_BIT,
/** 40GAUI-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_40GAUI_C2C_BIT,
/** 50GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_50G_C2C_BIT,
/** 50GBASE-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_50G_C2M_BIT,
/** 50GBASE-4-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_50G_4_C2C_BIT,
/** 50GBASE-CR */
CNXK_BPHY_CGX_ETH_LINK_MODE_50G_CR_BIT,
/** 50GBASE-KR */
CNXK_BPHY_CGX_ETH_LINK_MODE_50G_KR_BIT,
/** 80GAUI-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_80GAUI_C2C_BIT,
/** 100GBASE-C2C */
CNXK_BPHY_CGX_ETH_LINK_MODE_100G_C2C_BIT,
/** 100GBASE-C2M */
CNXK_BPHY_CGX_ETH_LINK_MODE_100G_C2M_BIT,
/** 100GBASE-CR4 */
CNXK_BPHY_CGX_ETH_LINK_MODE_100G_CR4_BIT,
/** 100GBASE-KR4 */
CNXK_BPHY_CGX_ETH_LINK_MODE_100G_KR4_BIT,
__CNXK_BPHY_CGX_ETH_LINK_MODE_MAX
};
struct cnxk_bphy_cgx_msg_link_mode {
/** Setting for full-duplex */
bool full_duplex;
/** Setting for automatic link negotiation */
bool autoneg;
/** Link speed */
enum cnxk_bphy_cgx_eth_link_speed speed;
/** Link mode */
enum cnxk_bphy_cgx_eth_link_mode mode;
};
struct cnxk_bphy_cgx_msg_link_info {
/** Link state information */
bool link_up;
/** Link full duplex state */
bool full_duplex;
/** Link speed */
enum cnxk_bphy_cgx_eth_link_speed speed;
/** Link auto-negotiation setting */
bool autoneg;
/** FEC mode */
enum cnxk_bphy_cgx_eth_link_fec fec;
/** Link configuration */
enum cnxk_bphy_cgx_eth_link_mode mode;
};
struct cnxk_bphy_cgx_msg_set_link_state {
/** Defines link state result */
bool state; /* up or down */
};
struct cnxk_bphy_cgx_msg {
/** Message type */
enum cnxk_bphy_cgx_msg_type type;
/*
* data depends on message type and whether
/**
* Data depends on message type and whether
* it's a request or a response
*/
void *data;
@ -117,42 +183,63 @@ struct cnxk_bphy_cgx_msg {
#define CNXK_BPHY_DEF_QUEUE 0
/**
* BPHY interrupt handler
*
* @param irq_num
* Zero-based interrupt number
* @param isr_data
* Cookie passed to interrupt handler
*/
typedef void (*cnxk_bphy_intr_handler_t)(int irq_num, void *isr_data);
struct cnxk_bphy_mem {
/** Memory for BAR0 */
struct rte_mem_resource res0;
/** Memory for BAR2 */
struct rte_mem_resource res2;
};
/** Available IRQ configuration commands */
enum cnxk_bphy_irq_msg_type {
/** Type used to initialize interrupts */
CNXK_BPHY_IRQ_MSG_TYPE_INIT,
/** Type used to deinitialize interrupts */
CNXK_BPHY_IRQ_MSG_TYPE_FINI,
/** Type used to register interrupt */
CNXK_BPHY_IRQ_MSG_TYPE_REGISTER,
/** Type used to unregister interrupt */
CNXK_BPHY_IRQ_MSG_TYPE_UNREGISTER,
/** Type used to retrieve BPHY memory */
CNXK_BPHY_IRQ_MSG_TYPE_MEM_GET,
/** Type used to retrieve NPA PF function */
CNXK_BPHY_MSG_TYPE_NPA_PF_FUNC,
/** Type used to retrieve NPA SSO function */
CNXK_BPHY_MSG_TYPE_SSO_PF_FUNC,
};
struct cnxk_bphy_irq_msg {
/** Message command type */
enum cnxk_bphy_irq_msg_type type;
/*
* The data field, depending on message type, may point to
* - (enq) full struct cnxk_bphy_irq_info for registration request
* - (enq) struct cnxk_bphy_irq_info with irq_num set for unregistration
* - (deq) struct cnxk_bphy_mem for memory range request response
* - (xxx) NULL
/**
* Data depends on message type and whether
* it is a request or a response
*/
void *data;
};
struct cnxk_bphy_irq_info {
/** Interrupt number */
int irq_num;
/** Interrupt handler */
cnxk_bphy_intr_handler_t handler;
/** Interrupt handler cookie */
void *data;
/** CPU zero-based number for interrupt execution */
int cpu;
};
/** @internal helper routine for enqueuing/dequeuing messages */
static __rte_always_inline int
__rte_pmd_bphy_enq_deq(uint16_t dev_id, unsigned int queue, void *req,
void *rsp, size_t rsp_size)
@ -187,6 +274,15 @@ __rte_pmd_bphy_enq_deq(uint16_t dev_id, unsigned int queue, void *req,
return 0;
}
/**
* Initialize BPHY subsystem
*
* @param dev_id
* The identifier of the device
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_intr_init(uint16_t dev_id)
{
@ -198,6 +294,15 @@ rte_pmd_bphy_intr_init(uint16_t dev_id)
NULL, 0);
}
/**
* Deinitialize BPHY subsystem
*
* @param dev_id
* The identifier of the device
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_intr_fini(uint16_t dev_id)
{
@ -209,6 +314,23 @@ rte_pmd_bphy_intr_fini(uint16_t dev_id)
NULL, 0);
}
/**
* Register BPHY interrupt handler
*
* @param dev_id
* The identifier of the device
* @param irq_num
* Zero-based interrupt number
* @param handler
* Interrupt handler to be executed
* @param data
* Data to be passed to interrupt handler
* @param cpu
* CPU number which will be handling interrupt
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_intr_register(uint16_t dev_id, int irq_num,
cnxk_bphy_intr_handler_t handler, void *data,
@ -229,6 +351,17 @@ rte_pmd_bphy_intr_register(uint16_t dev_id, int irq_num,
NULL, 0);
}
/**
* Unregister BPHY interrupt handler
*
* @param dev_id
* The identifier of the device
* @param irq_num
* Zero-based interrupt number used during registration
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_intr_unregister(uint16_t dev_id, int irq_num)
{
@ -244,6 +377,17 @@ rte_pmd_bphy_intr_unregister(uint16_t dev_id, int irq_num)
NULL, 0);
}
/**
* Obtain BPHY memory
*
* @param dev_id
* The identifier of the device
* @param mem
* Memory structure which will be filled for memory access
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_intr_mem_get(uint16_t dev_id, struct cnxk_bphy_mem *mem)
{
@ -255,6 +399,17 @@ rte_pmd_bphy_intr_mem_get(uint16_t dev_id, struct cnxk_bphy_mem *mem)
mem, sizeof(*mem));
}
/**
* Obtain NPA PF func
*
* @param dev_id
* The identifier of the device
* @param pf_func
* NPA PF function to obtain
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_npa_pf_func_get(uint16_t dev_id, uint16_t *pf_func)
{
@ -266,6 +421,17 @@ rte_pmd_bphy_npa_pf_func_get(uint16_t dev_id, uint16_t *pf_func)
pf_func, sizeof(*pf_func));
}
/**
* Obtain SSO PF func
*
* @param dev_id
* The identifier of the device
* @param pf_func
* SSO PF function to obtain
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_sso_pf_func_get(uint16_t dev_id, uint16_t *pf_func)
{
@ -277,6 +443,19 @@ rte_pmd_bphy_sso_pf_func_get(uint16_t dev_id, uint16_t *pf_func)
pf_func, sizeof(*pf_func));
}
/**
* Obtain link information
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
* @param info
* Link information structure
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_get_link_info(uint16_t dev_id, uint16_t lmac,
struct cnxk_bphy_cgx_msg_link_info *info)
@ -288,6 +467,17 @@ rte_pmd_bphy_cgx_get_link_info(uint16_t dev_id, uint16_t lmac,
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, info, sizeof(*info));
}
/**
* Disable loopback mode for an interface
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_intlbk_disable(uint16_t dev_id, uint16_t lmac)
{
@ -298,6 +488,17 @@ rte_pmd_bphy_cgx_intlbk_disable(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Enable loopback mode for an interface
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_intlbk_enable(uint16_t dev_id, uint16_t lmac)
{
@ -308,6 +509,17 @@ rte_pmd_bphy_cgx_intlbk_enable(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Disable PTP on RX path
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_ptp_rx_disable(uint16_t dev_id, uint16_t lmac)
{
@ -318,6 +530,17 @@ rte_pmd_bphy_cgx_ptp_rx_disable(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Enable PTP on RX path
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_ptp_rx_enable(uint16_t dev_id, uint16_t lmac)
{
@ -328,6 +551,19 @@ rte_pmd_bphy_cgx_ptp_rx_enable(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Set link mode for a CGX
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
* @param mode
* Link mode to set
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_set_link_mode(uint16_t dev_id, uint16_t lmac,
struct cnxk_bphy_cgx_msg_link_mode *mode)
@ -340,6 +576,19 @@ rte_pmd_bphy_cgx_set_link_mode(uint16_t dev_id, uint16_t lmac,
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Set link state for a CGX
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
* @param up
* Link state to set
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_set_link_state(uint16_t dev_id, uint16_t lmac, bool up)
{
@ -354,6 +603,17 @@ rte_pmd_bphy_cgx_set_link_state(uint16_t dev_id, uint16_t lmac, bool up)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Start CGX
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_start_rxtx(uint16_t dev_id, uint16_t lmac)
{
@ -364,6 +624,17 @@ rte_pmd_bphy_cgx_start_rxtx(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Stop CGX
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_stop_rxtx(uint16_t dev_id, uint16_t lmac)
{
@ -374,6 +645,19 @@ rte_pmd_bphy_cgx_stop_rxtx(uint16_t dev_id, uint16_t lmac)
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, NULL, 0);
}
/**
* Get supported list FEC mode
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
* @param fec
* FEC structure which holds information
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_get_supported_fec(uint16_t dev_id, uint16_t lmac,
enum cnxk_bphy_cgx_eth_link_fec *fec)
@ -385,6 +669,19 @@ rte_pmd_bphy_cgx_get_supported_fec(uint16_t dev_id, uint16_t lmac,
return __rte_pmd_bphy_enq_deq(dev_id, lmac, &msg, fec, sizeof(*fec));
}
/**
* Set FEC mode for a device
*
* @param dev_id
* The identifier of the device
* @param lmac
* LMAC number for operation
* @param fec
* FEC structure which holds information to set
*
* @return
* Returns 0 on success, negative error code otherwise
*/
static __rte_always_inline int
rte_pmd_bphy_cgx_set_fec(uint16_t dev_id, uint16_t lmac,
enum cnxk_bphy_cgx_eth_link_fec fec)