From 58301a3ef2624e22075232acc195b39b73f8e0d7 Mon Sep 17 00:00:00 2001 From: Bhadram Varka Date: Wed, 21 Aug 2019 17:16:31 +0530 Subject: [PATCH] nvethernet: Update comments with Doxygen style replace kernel doc comments with Doxygen style comments Bug 200512422 Change-Id: I1445cab3fb6708ddc21b4bfacebe213ed22f7aa2 Signed-off-by: Bhadram Varka Reviewed-on: https://git-master.nvidia.com/r/2180213 Reviewed-by: Narayan Reddy Tested-by: Narayan Reddy GVS: Gerrit_Virtual_Submit Reviewed-by: Srinivas Ramachandran Reviewed-by: Bitan Biswas Reviewed-by: mobile promotions Tested-by: mobile promotions --- .../ethernet/nvidia/nvethernet/ether_linux.c | 1121 ++++++++--------- .../ethernet/nvidia/nvethernet/ether_linux.h | 286 +++-- .../net/ethernet/nvidia/nvethernet/ethtool.c | 193 +-- .../net/ethernet/nvidia/nvethernet/ioctl.c | 261 ++-- .../net/ethernet/nvidia/nvethernet/ioctl.h | 72 +- drivers/net/ethernet/nvidia/nvethernet/osd.c | 163 +-- drivers/net/ethernet/nvidia/nvethernet/ptp.c | 136 +- .../net/ethernet/nvidia/nvethernet/sysfs.c | 68 +- 8 files changed, 1101 insertions(+), 1199 deletions(-) diff --git a/drivers/net/ethernet/nvidia/nvethernet/ether_linux.c b/drivers/net/ethernet/nvidia/nvethernet/ether_linux.c index 90f22c0e..96fc9605 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ether_linux.c +++ b/drivers/net/ethernet/nvidia/nvethernet/ether_linux.c @@ -17,17 +17,12 @@ #include "ether_linux.h" /** - * ether_disable_clks - Disable all MAC related clks. - * @pdata: OSD private data. + * @brief Disable all MAC related clks * - * Algorithm: Release the reference counter for the clks by using - * clock subsystem provided API's. + * Algorithm: Release the reference counter for the clks by using + * clock subsystem provided API's * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] pdata: OSD private data. */ static void ether_disable_clks(struct ether_priv_data *pdata) { @@ -57,16 +52,14 @@ static void ether_disable_clks(struct ether_priv_data *pdata) } /** - * ether_enable_clks - Enable all MAC related clks. - * @pdata: OSD private data. + * @brief Enable all MAC related clks. * - * Algorithm: Enables the clks by using clock subsystem provided API's. + * Algorithm: Enables the clks by using clock subsystem provided API's. * - * Dependencies: None. + * @param[in] pdata: OSD private data. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_enable_clks(struct ether_priv_data *pdata) { @@ -141,18 +134,15 @@ err_axi_cbb: } /** - * ether_adjust_link - Adjust link call back - * @dev: Net device data. + * @brief Adjust link call back * - * Algorithm: Callback function called by the PHY subsystem - * whenever there is a link detected or link changed on the - * physical layer. + * Algorithm: Callback function called by the PHY subsystem + * whenever there is a link detected or link changed on the + * physical layer. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] dev: Network device data. * - * Protection: None. - * - * Return: None. + * @note MAC and PHY need to be initialized. */ static void ether_adjust_link(struct net_device *dev) { @@ -221,18 +211,16 @@ static void ether_adjust_link(struct net_device *dev) } /** - * ether_phy_init - Initialize the PHY - * @dev: Net device data. + * @brief Initialize the PHY * - * Algorithm: - * 1) Reset the PHY - * 2) Connect to the phy described in the device tree. + * Algorithm: 1) Resets the PHY. 2) Connect to the phy described in the device tree. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] dev: Network device data. * - * Protection: None. + * @note MAC needs to be out of reset. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_phy_init(struct net_device *dev) { @@ -276,21 +264,21 @@ static int ether_phy_init(struct net_device *dev) } /** - * ether_tx_chan_isr - Tx done ISR Routine. - * @irq: IRQ number. - * @data: Tx NAPI private data structure. + * @brief Transmit done ISR Routine. * - * Algorithm: - * 1) Get channel number private data passed to ISR. - * 2) Invoke OSI layer to clear Tx interrupt source. - * 3) Disable DMA Tx channel interrupt. - * 4) Schedule TX NAPI poll handler to cleanup the buffer. + * Algorithm: + * 1) Get channel number private data passed to ISR. + * 2) Invoke OSI layer to clear Tx interrupt source. + * 3) Disable DMA Tx channel interrupt. + * 4) Schedule TX NAPI poll handler to cleanup the buffer. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] irq: IRQ number. + * @param[in] data: Tx NAPI private data structure. * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: IRQ_HANDLED - success, IRQ_NONE - failure. + * @retval IRQ_HANDLED on success + * @retval IRQ_NONE on failure. */ static irqreturn_t ether_tx_chan_isr(int irq, void *data) { @@ -318,23 +306,23 @@ static irqreturn_t ether_tx_chan_isr(int irq, void *data) } /** - * ether_rx_chan_isr - Rx done ISR Routine - * @irq: IRQ number - * @data: Rx NAPI private data structure. + * @brief Receive done ISR Routine * - * Algorithm: - * 1) Get Rx channel number from Rx NAPI private data which will be passed - * during request_irq() API. - * 2) Invoke OSI layer to clear Rx interrupt source. - * 3) Disable DMA Rx channel interrupt. - * 4) Schedule Rx NAPI poll handler to get data from HW and pass to the - * Linux network stack. + * Algorithm: + * 1) Get Rx channel number from Rx NAPI private data which will be passed + * during request_irq() API. + * 2) Invoke OSI layer to clear Rx interrupt source. + * 3) Disable DMA Rx channel interrupt. + * 4) Schedule Rx NAPI poll handler to get data from HW and pass to the + * Linux network stack. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] irq: IRQ number + * @param[in] data: Rx NAPI private data structure. * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: IRQ_HANDLED - success, IRQ_NONE - failure. + * @retval IRQ_HANDLED on success + * @retval IRQ_NONE on failure. */ static irqreturn_t ether_rx_chan_isr(int irq, void *data) { @@ -362,17 +350,17 @@ static irqreturn_t ether_rx_chan_isr(int irq, void *data) } /** - * ether_common_isr - Common ISR Routine - * @irq: IRQ number. - * @data: Private data from ISR. + * @brief Common ISR Routine * - * Algorithm: Invoker OSI layer to handle common interrupt. + * Algorithm: Invoke OSI layer to handle common interrupt. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] irq: IRQ number. + * @param[in] data: Private data from ISR. * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: IRQ_HANDLED - success, IRQ_NONE - failure. + * @retval IRQ_HANDLED on success + * @retval IRQ_NONE on failure. */ static irqreturn_t ether_common_isr(int irq, void *data) { @@ -383,20 +371,16 @@ static irqreturn_t ether_common_isr(int irq, void *data) } /** - * ether_free_irqs - Free IRQs - * @pdata: OS dependent private data structure. + * @brief Free IRQs * - * Algorithm: This routine takes care of freeing - * below IRQs - * 1) Common IRQ - * 2) TX IRQ - * 3) RX IRQ + * Algorithm: This routine takes care of freeing below IRQs + * 1) Common IRQ + * 2) TX IRQ + * 3) RX IRQ * - * Dependencies: IRQs should have registered. + * @param[in] pdata: OS dependent private data structure. * - * Protection: None. - * - * Return: NONE. + * @note IRQs should have registered. */ static void ether_free_irqs(struct ether_priv_data *pdata) { @@ -425,20 +409,19 @@ static void ether_free_irqs(struct ether_priv_data *pdata) } /** - * ether_request_irqs - register IRQs - * @pdata: OS dependent private data structure. + * @brief Register IRQs * - * Algorithm: This routine takes care of requesting - * below IRQs - * 1) Common IRQ - * 2) TX IRQ - * 3) RX IRQ + * Algorithm: This routine takes care of requesting below IRQs + * 1) Common IRQ + * 2) TX IRQ + * 3) RX IRQ * - * Dependencies: IRQ numbers need to be known. + * @param[in] pdata: OS dependent private data structure. * - * Protection: None. + * @note IRQ numbers need to be known. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_request_irqs(struct ether_priv_data *pdata) { @@ -497,16 +480,13 @@ err_chan_irq: } /** - * ether_napi_disable - Disable NAPI. - * @pdata: OSD private data structure. + * @brief Disable NAPI. * - * Algorithm: Disable Tx and Rx NAPI for the channels which are enabled. + * Algorithm: Disable Tx and Rx NAPI for the channels which are enabled. * - * Dependencies: NAPI resources need to be allocated as part of probe(). + * @param[in] pdata: OSD private data structure. * - * Protection: None. - * - * Return: None. + * @note NAPI resources need to be allocated as part of probe(). */ static void ether_napi_disable(struct ether_priv_data *pdata) { @@ -523,16 +503,13 @@ static void ether_napi_disable(struct ether_priv_data *pdata) } /** - * ether_napi_enable - Enable NAPI. - * @pdata: OSD private data structure. + * @brief Enable NAPI. * - * Algorithm: Enable Tx and Rx NAPI for the channels which are enabled. + * Algorithm: Enable Tx and Rx NAPI for the channels which are enabled. * - * Dependencies: NAPI resources need to be allocated as part of probe(). + * @param[in] pdata: OSD private data structure. * - * Protection: None. - * - * Return: None. + * @note NAPI resources need to be allocated as part of probe(). */ static void ether_napi_enable(struct ether_priv_data *pdata) { @@ -548,6 +525,13 @@ static void ether_napi_enable(struct ether_priv_data *pdata) } } +/** + * @brief Free receive skbs + * + * @param[in] rx_swcx: Rx pkt SW context + * @param[in] dev: device instance associated with driver. + * @param[in] rx_buf_len: Receive buffer length + */ static void ether_free_rx_skbs(struct osi_rx_swcx *rx_swcx, struct device *dev, unsigned int rx_buf_len) { @@ -568,17 +552,12 @@ static void ether_free_rx_skbs(struct osi_rx_swcx *rx_swcx, struct device *dev, } /** - * free_rx_dma_resources - Frees allocated Rx DMA resources. - * @osi: OSI private data structure. - * + * @brief free_rx_dma_resources - Frees allocated Rx DMA resources. * Algorithm: Release all DMA Rx resources which are allocated as part of * allocated_rx_dma_ring() API. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] osi_dma: OSI DMA private data structure. + * @param[in] dev: device instance associated with driver. */ static void free_rx_dma_resources(struct osi_dma_priv_data *osi_dma, struct device *dev) @@ -610,19 +589,20 @@ static void free_rx_dma_resources(struct osi_dma_priv_data *osi_dma, } /** - * allocate_rx_dma_resource - Allocate Rx DMA ring - * @osi: OSI private data structure. - * @chan: Rx DMA channel number. + * @brief Allocate Rx DMA channel ring resources * - * Algorithm: DMA receive ring will be created for valid channel number. - * Receive ring updates with descriptors and software context associated - * with each receive descriptor. + * Algorithm: DMA receive ring will be created for valid channel number. + * Receive ring updates with descriptors and software context associated + * with each receive descriptor. * - * Dependencies: Invalid channel need to be updated. + * @param[in] osi_dma: OSI DMA private data structure. + * @param[in] dev: device instance associated with driver. + * @param[in] chan: Rx DMA channel number. * - * Protection: None. + * @note Invalid channel need to be updated. * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int allocate_rx_dma_resource(struct osi_dma_priv_data *osi_dma, struct device *dev, @@ -672,6 +652,15 @@ err_rx_desc: return ret; } +/** + * @brief Allocate receive buffers for a DMA channel ring + * + * @param[in] pdata: OSD private data. + * @param[in] rx_ring: rxring data structure. + * + * @retval 0 on success + * @retval "negative value" on failure. + */ static int ether_allocate_rx_buffers(struct ether_priv_data *pdata, struct osi_rx_ring *rx_ring) { @@ -708,17 +697,18 @@ static int ether_allocate_rx_buffers(struct ether_priv_data *pdata, } /** - * allocate_rx_dma_resources - Allocate rx DMA resources. - * @osi: OSI private data structure. + * @brief Allocate Receive DMA channel ring resources. * - * Algorithm: DMA receive ring will be created for valid channel number - * provided through DT + * Algorithm: DMA receive ring will be created for valid channel number + * provided through DT * - * Dependencies: Invalid channel need to be updated. + * @param[in] osi_dma: OSI private data structure. + * @param[in] pdata: OSD private data. * - * Protection: None. + * @note Invalid channel need to be updated. * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_allocate_rx_dma_resources(struct osi_dma_priv_data *osi_dma, struct ether_priv_data *pdata) @@ -752,17 +742,13 @@ exit: } /** - * free_tx_dma_resources - Frees allocated DMA resources. - * @osi: OSI private data structure. + * @brief Frees allocated DMA resources. * - * Algorithm: Release all DMA Tx resources which are allocated as part of - * allocated_tx_dma_ring() API. + * Algorithm: Release all DMA Tx resources which are allocated as part of + * allocated_tx_dma_ring() API. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] osi_dma: OSI private data structure. + * @param[in] dev: device instance associated with driver. */ static void free_tx_dma_resources(struct osi_dma_priv_data *osi_dma, struct device *dev) @@ -793,19 +779,18 @@ static void free_tx_dma_resources(struct osi_dma_priv_data *osi_dma, } /** - * allocate_tx_dma_resource - Allocate Tx DMA ring - * @osi: OSI private data structure. - * @chan: Channel number. + * @brief Allocate Tx DMA ring * - * Algorithm: DMA transmit ring will be created for valid channel number. - * Transmit ring updates with descriptors and software context associated - * with each transmit descriptor. + * Algorithm: DMA transmit ring will be created for valid channel number. + * Transmit ring updates with descriptors and software context associated + * with each transmit descriptor. * - * Dependencies: None. + * @param[in] osi_dma: OSI DMA private data structure. + * @param[in] dev: device instance associated with driver. + * @param[in] chan: Channel number. * - * Protection: None. - * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int allocate_tx_dma_resource(struct osi_dma_priv_data *osi_dma, struct device *dev, @@ -855,17 +840,18 @@ err_tx_desc: } /** - * ether_allocate_tx_dma_resources - Allocate Tx DMA resources. - * @osi: OSI private data structure. + * @brief Allocate Tx DMA resources. * - * Algorithm: DMA transmit ring will be created for valid channel number - * provided through DT + * Algorithm: DMA transmit ring will be created for valid channel number + * provided through DT * - * Dependencies: Invalid channel need to be updated. + * @param[in] osi_dma: OSI DMA private data structure. + * @param[in] dev: device instance associated with driver. * - * Protection: None. + * @note Invalid channel need to be updated. * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_allocate_tx_dma_resources(struct osi_dma_priv_data *osi_dma, struct device *dev) @@ -892,41 +878,20 @@ exit: } /** - * ether_init_invalid_chan_ring - - * Updates invalid channels list and DMA rings. - * @osi: OSI private data structure. + * @brief Updates invalid channels list and DMA rings. * - * Algorithm: - * 1) Initialize all DMA Tx/Rx pointers to NULL so that for valid - * dma_addr_t *channels Tx/Rx rings will be created. + * Algorithm: Initialize all DMA Tx/Rx pointers to NULL so that for valid + * dma_addr_t *channels Tx/Rx rings will be created. * - * For ex: If the number of channels are 2 (nvidia,num_dma_chans = <2>) - * and channel numbers are 2 and 3 (nvidia,dma_chans = <2 3>), - * then only for channel 2 and 3 DMA rings will be allocated in - * allocate_tx/rx_dma_resources() function. + * For ex: If the number of channels are 2 (nvidia,num_dma_chans = <2>) + * and channel numbers are 2 and 3 (nvidia,dma_chans = <2 3>), + * then only for channel 2 and 3 DMA rings will be allocated in + * allocate_tx/rx_dma_resources() function. * - * Representation of Tx ring will be like - - * osi->tx_ring[0] = NULL, - * osi->tx_ring[1] = NULL, - * osi->tx_ring[2] = allocated pointer for DMA Tx 2 ring. - * osi->tx_ring[3] = allocated pointer for DMA Tx 3 ring. - * osi_>tx_ring[4] = NULL, - * . - * . - * osi_>tx_ring[9] = NULL. + * @param[in] osi_dma: OSI DMA private data structure. * - * This is useful in start_xmit() to get directly Tx ring based on the - * channel number return from select_queue() API. - * - * 2) Second for loop makes remaing channel numbers as invalid numbers - * so that only valid channel will go and allocate/free the DMA resources. - * - * Dependencies: OSD needs to be update number of channels and channel - * numbers in OSI private data structure. - * - * Protection: None. - * - * Return: None. + * @note OSD needs to be update number of channels and channel + * numbers in OSI private data structure. */ static void ether_init_invalid_chan_ring(struct osi_dma_priv_data *osi_dma) { @@ -943,16 +908,13 @@ static void ether_init_invalid_chan_ring(struct osi_dma_priv_data *osi_dma) } /** - * free_dma_resources - Freeing allocated DMA resources. - * @osi: OSI private data structure. + * @brief Frees allocated DMA resources. * - * Algorithm: Frees all DMA resources which are allocates with - * allocate_dma_resources() API. - * - * Dependencies: None. - * Protection: None. - * Return: None. + * Algorithm: Frees all DMA resources which are allocates with + * allocate_dma_resources() API. * + * @param[in] osi_dma: OSI private data structure. + * @param[in] dev: device instance associated with driver. */ void free_dma_resources(struct osi_dma_priv_data *osi_dma, struct device *dev) { @@ -961,19 +923,16 @@ void free_dma_resources(struct osi_dma_priv_data *osi_dma, struct device *dev) } /** - * allocate_dma_resources - Allocate DMA resources for Tx and Rx. - * @osi: OSI private data structure. + * @brief Allocate DMA resources for Tx and Rx. * - * Algorithm: - * 1) updates invalid channels with numbers. - * 2) Allocate Tx DMA resources. - * 3) Allocate Rx DMA resources. + * Algorithm: + * 1) Allocate Tx DMA resources. + * 2) Allocate Rx DMA resources. * - * Dependencies: None. + * @param[in] pdata: OSD private data structure. * - * Protection: None. - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_allocate_dma_resources(struct ether_priv_data *pdata) { @@ -998,20 +957,19 @@ static int ether_allocate_dma_resources(struct ether_priv_data *pdata) #ifdef THERMAL_CAL /** - * ether_get_max_therm_state - Set current thermal state. - * @tcd: Ethernet thermal cooling device pointer. - * @state: Variable to read max thermal state. + * @brief Set current thermal state. * - * Algorithm: Fill the max supported thermal state for ethernet cooling - * device in variable provided by caller. + * Algorithm: Fill the max supported thermal state for ethernet cooling + * device in variable provided by caller. * - * Dependencies: MAC needs to be out of reset. Once cooling device ops are - * registered, it can be called anytime from kernel. MAC has to be in - * sufficient state to allow pad calibration. + * @param[in] tcd: Ethernet thermal cooling device pointer. + * @param[in] state: Variable to read max thermal state. * - * Protection: None. + * @note MAC needs to be out of reset. Once cooling device ops are + * registered, it can be called anytime from kernel. MAC has to be in + * sufficient state to allow pad calibration. * - * Return: 0 - succcess. Does not fail as function is only reading var. + * return: 0 - succcess. Does not fail as function is only reading variable. */ static int ether_get_max_therm_state(struct thermal_cooling_device *tcd, unsigned long *state) @@ -1022,20 +980,19 @@ static int ether_get_max_therm_state(struct thermal_cooling_device *tcd, } /** - * ether_get_cur_therm_state - Get current thermal state. - * @tcd: Ethernet thermal cooling device pointer. - * @state: Variable to read current thermal state. + * @brief Get current thermal state. * - * Algorithm: Atomically get the current thermal state of etherent - * cooling device. + * Algorithm: Atomically get the current thermal state of etherent + * cooling device. * - * Dependencies: MAC needs to be out of reset. Once cooling device ops are - * registered, it can be called anytime from kernel. MAC has to be in - * sufficient state to allow pad calibration. + * @param[in] tcd: Ethernet thermal cooling device pointer. + * @param[in] state: Variable to read current thermal state. * - * Protection: None. + * @note MAC needs to be out of reset. Once cooling device ops are + * registered, it can be called anytime from kernel. MAC has to be in + * sufficient state to allow pad calibration. * - * Return: 0 - succcess. Does not fail as function is only reading var. + * @return: succcess on 0. */ static int ether_get_cur_therm_state(struct thermal_cooling_device *tcd, unsigned long *state) @@ -1048,20 +1005,20 @@ static int ether_get_cur_therm_state(struct thermal_cooling_device *tcd, } /** - * ether_set_cur_therm_state - Set current thermal state. - * @tcd: Ethernet thermal cooling device pointer. - * @state: The thermal state to set. + * @brief Set current thermal state. * - * Algorithm: Atomically set the desired state provided as argument. - * Trigger pad calibration for each state change. + * Algorithm: Atomically set the desired state provided as argument. + * Trigger pad calibration for each state change. * - * Dependencies: MAC needs to be out of reset. Once cooling device ops are - * registered, it can be called anytime from kernel. MAC has to be in - * sufficient state to allow pad calibration. + * @param[in] tcd: Ethernet thermal cooling device pointer. + * @param[in] state: The thermal state to set. * - * Protection: None. + * @note MAC needs to be out of reset. Once cooling device ops are + * registered, it can be called anytime from kernel. MAC has to be in + * sufficient state to allow pad calibration. * - * Return: 0 - succcess, -ve value - failure. + * @retval 0 on success + * @retval negative value on failure. */ static int ether_set_cur_therm_state(struct thermal_cooling_device *tcd, unsigned long state) @@ -1093,21 +1050,21 @@ static struct thermal_cooling_device_ops ether_cdev_ops = { }; /** - * ether_therm_init - Register thermal cooling device with kernel. - * @pdata: Pointer to driver private data structure. + * @brief Register thermal cooling device with kernel. * - * Algorithm: Register thermal cooling device read from DT. The cooling - * device ops struct passed as argument will be used by thermal framework - * to callback the ethernet driver when temperature trip points are - * triggered, so that ethernet driver can do pad calibration. + * Algorithm: Register thermal cooling device read from DT. The cooling + * device ops struct passed as argument will be used by thermal framework + * to callback the ethernet driver when temperature trip points are + * triggered, so that ethernet driver can do pad calibration. * - * Dependencies: MAC needs to be out of reset. Once cooling device ops are - * registered, it can be called anytime from kernel. MAC has to be in - * sufficient state to allow pad calibration. + * @param[in] pdata: Pointer to driver private data structure. * - * Protection: None. + * @ote MAC needs to be out of reset. Once cooling device ops are + * registered, it can be called anytime from kernel. MAC has to be in + * sufficient state to allow pad calibration. * - * Return: 0 - succcess, -ve value - failure. + * @retval 0 on success + * @retval negative value on failure. */ static int ether_therm_init(struct ether_priv_data *pdata) { @@ -1132,21 +1089,21 @@ static int ether_therm_init(struct ether_priv_data *pdata) #endif /* THERMAL_CAL */ /** - * ether_open - Call back to handle bring up of Ethernet interface - * @dev: Net device data structure. + * @brief Call back to handle bring up of Ethernet interface * - * Algorithm: This routine takes care of below - * 1) PHY initialization - * 2) request tx/rx/common irqs - * 3) HW initialization - * 4) Starting the PHY + * Algorithm: This routine takes care of below + * 1) PHY initialization + * 2) request tx/rx/common irqs + * 3) HW initialization + * 4) Starting the PHY * - * Dependencies: Ethernet driver probe need to be completed successfully - * with ethernet network device created. + * @param[in] dev: Net device data structure. * - * Protection: None. + * @note Ethernet driver probe need to be completed successfully + * with ethernet network device created. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_open(struct net_device *dev) { @@ -1285,18 +1242,18 @@ err_mac_rst: } /** - * ether_close - Call back to handle bring down of Ethernet interface - * @dev: Net device data structure. + * @brief Call back to handle bring down of Ethernet interface * - * Algorithm: This routine takes care of below - * 1) Stopping PHY - * 2) Freeing tx/rx/common irqs + * Algorithm: This routine takes care of below + * 1) Stopping PHY + * 2) Freeing tx/rx/common irqs * - * Dependencies: MAC Interface need to be registered. + * @param[in] dev: Net device data structure. * - * Protection: None. + * @note MAC Interface need to be registered. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_close(struct net_device *dev) { @@ -1350,20 +1307,19 @@ static int ether_close(struct net_device *dev) } /** - * ether_handle_tso - Helper func to check if TSO is used in given skb. - * @tx_pkt_cx: Pointer to packet context information structure. - * @skb: socket buffer. + * @brief Helper function to check if TSO is used in given skb. * - * Algorithm: - * 1) Check if driver received a TSO/LSO/GSO packet - * 2) If so, store the packet details like MSS(Maximum Segment Size), - * packet header length, packet payload length, tcp/udp header length. + * Algorithm: + * 1) Check if driver received a TSO/LSO/GSO packet + * 2) If so, store the packet details like MSS(Maximum Segment Size), + * packet header length, packet payload length, tcp/udp header length. * - * Dependencies: None. + * @param[in] tx_pkt_cx: Pointer to packet context information structure. + * @param[in] skb: socket buffer. * - * Protection: None. - * - * Return: 0 - Not a TSO packet, 1 - success, -ve value - failure. + * @retval 0 if not a TSO packet + * @retval 1 on success + * @retval "negative value" on failure. */ static int ether_handle_tso(struct osi_tx_pkt_cx *tx_pkt_cx, struct sk_buff *skb) @@ -1403,21 +1359,19 @@ static int ether_handle_tso(struct osi_tx_pkt_cx *tx_pkt_cx, } /** - * ether_tx_swcx_alloc - Tx ring software context allocation. - * @dev: device instance associated with driver. - * @tx_ring: Tx ring instance associated with channel number. - * @skb: socket buffer. + * @brief Tx ring software context allocation. * - * Algorithm: - * 1) Map skb data buffer to DMA mappable address. - * 2) Updated dma address, len and buffer address. This info will be used - * OSI layer for data transmission and buffer cleanup. + * Algorithm: + * 1) Map skb data buffer to DMA mappable address. + * 2) Updated dma address, len and buffer address. This info will be used + * OSI layer for data transmission and buffer cleanup. * - * Dependencies: None. + * @param[in] dev: device instance associated with driver. + * @param[in] tx_ring: Tx ring instance associated with channel number. + * @param[in] skb: socket buffer. * - * Protection: None. - * - * Return: number of descriptors - success, -1 - failure. + * @retval "number of descriptors" on success + * @retval "negative value" on failure. */ static int ether_tx_swcx_alloc(struct device *dev, struct osi_tx_ring *tx_ring, @@ -1613,22 +1567,19 @@ dma_map_failed: } /** - * ether_select_queue - Select queue based on user priority - * @dev: Network device pointer - * @skb: sk_buff pointer, buffer data to send - * @accel_priv: private data used for L2 forwarding offload - * @fallback: fallback function pointer + * @brief Select queue based on user priority * - * Algorithm: - * 1) Select the correct queue index based which has priority of queue - * same as skb->priority - * 2) default select queue array index 0 + * Algorithm: + * 1) Select the correct queue index based which has priority of queue + * same as skb->priority + * 2) default select queue array index 0 * - * Dependencies: None. + * @param[in] dev: Network device pointer + * @param[in] skb: sk_buff pointer, buffer data to send + * @param[in] accel_priv: private data used for L2 forwarding offload + * @param[in] fallback: fallback function pointer * - * Protection: None. - * - * Return: tx queue array index - success, -1 - failure. + * @retval "transmit queue index" */ static unsigned short ether_select_queue(struct net_device *dev, struct sk_buff *skb, @@ -1652,19 +1603,19 @@ static unsigned short ether_select_queue(struct net_device *dev, } /** - * ether_start_xmit - Network layer hook for data transmission. - * @skb: SKB data structure. - * @ndev: Net device structure. + * @brief Network layer hook for data transmission. * - * Algorithm: - * 1) Allocate software context (DMA address for the buffer) for the data. - * 2) Invoke OSI for data transmission. + * Algorithm: + * 1) Allocate software context (DMA address for the buffer) for the data. + * 2) Invoke OSI for data transmission. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] skb: SKB data structure. + * @param[in] ndev: Net device structure. * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_start_xmit(struct sk_buff *skb, struct net_device *ndev) { @@ -1697,21 +1648,17 @@ static int ether_start_xmit(struct sk_buff *skb, struct net_device *ndev) } /** - * ether_prepare_mc_list- function to configure the multicast - * address in device. + * @brief Function to configure the multicast address in device. * - * @dev: Pointer to net_device structure. + * Algorithm: This function collects all the multicast addresses and updates the + * device. * - * Algorithm: - * This function collects all the multicast addresses and updates the - * device. + * @param[in] dev: Pointer to net_device structure. * - * Dependencies: MAC and PHY need to be initialized. + * @note MAC and PHY need to be initialized. * - * Protection: None. - * - * Return: OSI_PERFECT_FILTER_MODE - perfect filtering is seleted - * OSI_HASH_FILTER_MODE - if hash filtering is seleted. + * @retval 0 if perfect filtering is seleted + * @retval 1 if hash filtering is seleted. */ static int ether_prepare_mc_list(struct net_device *dev) { @@ -1773,21 +1720,18 @@ static int ether_prepare_mc_list(struct net_device *dev) } /** - * ether_prepare_uc_list- function to configure the unicast address - * in device. + * @brief Function to configure the unicast address + * in device. * - * @dev - pointer to net_device structure. + * Algorithm: This function collects all the unicast addresses and updates the + * device. * - * Algorithm: - * This function collects all the unicast addresses and updates the - * device. + * @param[in] dev: pointer to net_device structure. * - * Dependencies: MAC and PHY need to be initialized. + * @note MAC and PHY need to be initialized. * - * Protection: None. - * - * Return: OSI_PERFECT_FILTER_MODE - perfect filtering is seleted - * OSI_HASH_FILTER_MODE - if hash filtering is seleted. + * @retval 0 if perfect filtering is seleted + * @retval 1 if hash filtering is seleted. */ static int ether_prepare_uc_list(struct net_device *dev) { @@ -1848,19 +1792,15 @@ static int ether_prepare_uc_list(struct net_device *dev) } /** - * ether_set_rx_mode - This function is used to set RX mode. + * @brief This function is used to set RX mode. * - * @dev - pointer to net_device structure. + * Algorithm: Based on Network interface flag, MAC registers are programmed to + * set mode. * - * Algorithm: - * Based on Network interface flag, MAC registers are programmed to set - * mode + * @param[in] dev - pointer to net_device structure. * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: Spinlock is used for protection. - * - * Return: None + * @note MAC and PHY need to be initialized. + * Spinlock is used for protection. */ static void ether_set_rx_mode(struct net_device *dev) { @@ -1924,20 +1864,20 @@ static void ether_set_rx_mode(struct net_device *dev) } /** - * ether_ioctl - network stack IOCTL hook to driver - * @ndev: network device structure - * @rq: Interface request structure used for socket - * @cmd: IOCTL command code + * @brief Network stack IOCTL hook to driver * - * Algorithm: - * 1) Invokes MII API for phy read/write based on IOCTL command - * 2) SIOCDEVPRIVATE for private ioctl + * Algorithm: + * 1) Invokes MII API for phy read/write based on IOCTL command + * 2) SIOCDEVPRIVATE for private ioctl * - * Dependencies: Ethernet interface need to be up. + * @param[in] dev: network device structure + * @param[in] rq: Interface request structure used for socket + * @param[in] cmd: IOCTL command code * - * Protection: None. + * @note Ethernet interface need to be up. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_ioctl(struct net_device *dev, struct ifreq *rq, int cmd) { @@ -1988,19 +1928,19 @@ static int ether_ioctl(struct net_device *dev, struct ifreq *rq, int cmd) } /** - * ether_set_mac_addr - Set MAC address - * @ndev: Network device structure - * @addr: MAC address to be programmed. + * @brief Set MAC address * - * Algorithm: - * 1) Checks whether given MAC address is valid or not - * 2) Stores the MAC address in OSI core structure + * Algorithm: + * 1) Checks whether given MAC address is valid or not + * 2) Stores the MAC address in OSI core structure * - * Dependencies: Ethernet interface need to be down to set MAC address + * @param[in] ndev: Network device structure + * @param[in] addr: MAC address to be programmed. * - * Protection: None. + * @note Ethernet interface need to be down to set MAC address * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_set_mac_addr(struct net_device *ndev, void *addr) { @@ -2021,19 +1961,19 @@ static int ether_set_mac_addr(struct net_device *ndev, void *addr) } /** - * ether_change_mtu - Change MAC MTU size - * @ndev: Network device structure - * @new_mtu: New MTU size to set. + * @brief Change MAC MTU size * - * Algorithm: - * 1) Check and return if interface is up. - * 2) Stores new MTU size set by user in OSI core data structure. + * Algorithm: + * 1) Check and return if interface is up. + * 2) Stores new MTU size set by user in OSI core data structure. + * + * @param[in] ndev: Network device structure + * @param[in] new_mtu: New MTU size to set. * - * Dependencies: Ethernet interface need to be down to change MTU size + * @note Ethernet interface need to be down to change MTU size * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_change_mtu(struct net_device *ndev, int new_mtu) { @@ -2056,21 +1996,21 @@ static int ether_change_mtu(struct net_device *ndev, int new_mtu) } /** - * ether_set_features - Change HW features for the given ndev - * @ndev: Network device structure - * @feat: New features to be updated + * @brief Change HW features for the given network device. * - * Algorithm: - * 1) Check if HW supports feature requested to be changed - * 2) If supported, check the current status of the feature and if it - * needs to be toggled, do so. + * Algorithm: + * 1) Check if HW supports feature requested to be changed + * 2) If supported, check the current status of the feature and if it + * needs to be toggled, do so. * - * Dependencies: Ethernet interface needs to be up. Stack will enforce - * the check. + * @param[in] ndev: Network device structure + * @param[in] feat: New features to be updated * - * Protection: None. + * @note Ethernet interface needs to be up. Stack will enforce + * the check. * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_set_features(struct net_device *ndev, netdev_features_t feat) { @@ -2105,24 +2045,23 @@ static int ether_set_features(struct net_device *ndev, netdev_features_t feat) } /** - * ether_vlan_rx_add_vid- Add VLAN ID. This function is invoked by upper - * layer when a new VLAN id is registered. This function updates the HW - * filter with new VLAN id. New vlan id can be added with vconfig - - * vconfig add + * @brief Adds VLAN ID. This function is invoked by upper + * layer when a new VLAN id is registered. This function updates the HW + * filter with new VLAN id. New vlan id can be added with vconfig - + * vconfig add interface_name vlan_id * - * @ndev: Network device structure - * @proto: VLAN proto VLAN_PROTO_8021Q = 0 VLAN_PROTO_8021AD = 1 - * @vid: VLAN ID. + * Algorithm: + * 1) Check for hash or perfect filtering. + * 2) invoke osi call accordingly. * - * Algorithm: - * 1) Check for hash or perfect filtering. - * 2) invoke osi call accordingly. + * @param[in] ndev: Network device structure + * @param[in] vlan_proto: VLAN proto VLAN_PROTO_8021Q = 0 VLAN_PROTO_8021AD = 1 + * @param[in] vid: VLAN ID. * - * Dependencies: Ethernet interface should be up + * @note Ethernet interface should be up * - * Protection: None. - * - * Return: 0 - success Negative - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_vlan_rx_add_vid(struct net_device *ndev, __be16 vlan_proto, u16 vid) @@ -2142,24 +2081,23 @@ static int ether_vlan_rx_add_vid(struct net_device *ndev, __be16 vlan_proto, } /** - * ether_vlan_rx_kill_vid- Remove VLAN ID. This function is invoked by - * upper layer when a new VALN id is removed. This function updates the HW - * filter. vlan id can be removed with vconfig - - * vconfig rem + * @brief Removes VLAN ID. This function is invoked by + * upper layer when a new VALN id is removed. This function updates the + * HW filter. vlan id can be removed with vconfig - + * vconfig rem interface_name vlan_id * - * @ndev: Network device structure - * @vlan_proto: VLAN proto VLAN_PROTO_8021Q = 0 VLAN_PROTO_8021AD = 1 - * @vid: VLAN ID. + * Algorithm: + * 1) Check for hash or perfect filtering. + * 2) invoke osi call accordingly. * - * Algorithm: - * 1) Check for hash or perfect filtering. - * 2) invoke osi call accordingly. + * @param[in] ndev: Network device structure + * @param[in] vlan_proto: VLAN proto VLAN_PROTO_8021Q = 0 VLAN_PROTO_8021AD = 1 + * @param[in] vid: VLAN ID. * - * Dependencies: Ethernet interface should be up + * @note Ethernet interface should be up * - * Protection: None. - * - * Return: 0 - success Negative - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_vlan_rx_kill_vid(struct net_device *ndev, __be16 vlan_proto, u16 vid) @@ -2180,7 +2118,9 @@ static int ether_vlan_rx_kill_vid(struct net_device *ndev, __be16 vlan_proto, return ret; } - +/** + * @brief Ethernet network device operations + */ static const struct net_device_ops ether_netdev_ops = { .ndo_open = ether_open, .ndo_stop = ether_close, @@ -2196,18 +2136,17 @@ static const struct net_device_ops ether_netdev_ops = { }; /** - * ether_napi_poll_rx - NAPI poll handler for receive. - * @napi: NAPI instance for Rx NAPI. - * @budget: NAPI budget. + * @brief NAPI poll handler for receive. * - * Algorithm: Invokes OSI layer to read data from HW and pass onto the - * Linux network stack. + * Algorithm: Invokes OSI layer to read data from HW and pass onto the + * Linux network stack. * - * Dependencies: Probe and INIT needs to be completed successfully. + * @param[in] napi: NAPI instance for Rx NAPI. + * @param[in] budget: NAPI budget. * - * Protection: None. + * @note Probe and INIT needs to be completed successfully. * - * Return: number of packets received. + *@return number of packets received. */ static int ether_napi_poll_rx(struct napi_struct *napi, int budget) { @@ -2231,18 +2170,17 @@ static int ether_napi_poll_rx(struct napi_struct *napi, int budget) } /** - * ether_napi_poll_tx - NAPI poll handler for transmission. - * @napi: NAPI instance for tx NAPI. - * @budget: NAPI budget. + * @brief NAPI poll handler for transmission. * - * Algorithm: Invokes OSI layer to read data from HW and pass onto the - * Linux network stack. + * Algorithm: Invokes OSI layer to read data from HW and pass onto the + * Linux network stack. * - * Dependencies: Probe and INIT needs to be completed successfully. + * @param[in] napi: NAPI instance for tx NAPI. + * @param[in] budget: NAPI budget. * - * Protection: None. + * @note Probe and INIT needs to be completed successfully. * - * Return: Number of Tx buffer cleaned. + * @return Number of Tx buffer cleaned. */ static int ether_napi_poll_tx(struct napi_struct *napi, int budget) { @@ -2267,17 +2205,17 @@ static int ether_napi_poll_tx(struct napi_struct *napi, int budget) } /** - * ether_alloc_napi - Allocate NAPI resources. - * @pdata: OSD private data structure. + * @brief Allocate NAPI resources. * - * Algorithm: Allocate NAPI instances for the channels which are enabled. + * Algorithm: Allocate NAPI instances for the channels which are enabled. * - * Dependencies: Number of channels and channel numbers needs to be - * updated in OSI private data structure. + * @param[in] pdata: OSD private data structure. * - * Protection: None. - * - * Return: None. + * @note Number of channels and channel numbers needs to be + * updated in OSI private data structure. + * + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_alloc_napi(struct ether_priv_data *pdata) { @@ -2321,20 +2259,20 @@ static int ether_alloc_napi(struct ether_priv_data *pdata) } /** - * ether_mdio_write - MII call back for MDIO register write. - * @bus: MDIO bus instances. - * @phyaddr: PHY address (ID). - * @phyreg: PHY register to write. - * @phydata: Data to be written in register. + * @brief MII call back for MDIO register write. * - * Algorimthm: Invoke OSI layer for PHY register write. - * phy_write() API from Linux PHY subsystem will call this. + * Algorithm: Invoke OSI layer for PHY register write. + * phy_write() API from Linux PHY subsystem will call this. * - * Dependencies: MAC has to be out of reset. + * @param[in] bus: MDIO bus instances. + * @param[in] phyaddr: PHY address (ID). + * @param[in] phyreg: PHY register to write. + * @param[in] phydata: Data to be written in register. * - * Protection: None. + * @note MAC has to be out of reset. * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_mdio_write(struct mii_bus *bus, int phyaddr, int phyreg, u16 phydata) @@ -2347,19 +2285,19 @@ static int ether_mdio_write(struct mii_bus *bus, int phyaddr, int phyreg, } /** - * ether_mdio_read - MII call back for MDIO register read. - * @bus: MDIO bus instances. - * @phyaddr: PHY address (ID). - * @phyreg: PHY register to read. + * @brief MII call back for MDIO register read. * - * Algorimthm: Invoke OSI layer for PHY register read. - * phy_read() API from Linux subsystem will call this. + * Algorithm: Invoke OSI layer for PHY register read. + * phy_read() API from Linux subsystem will call this. * - * Dependencies: MAC has to be out of reset. + * @param[in] bus: MDIO bus instances. + * @param[in] phyaddr: PHY address (ID). + * @param[in] phyreg: PHY register to read. * - * Protection: None. + * @note MAC has to be out of reset. * - * Return: data from PHY register - success, -1 - failure. + * @retval data from PHY register on success + * @retval "nagative value" on failure. */ static int ether_mdio_read(struct mii_bus *bus, int phyaddr, int phyreg) { @@ -2371,17 +2309,15 @@ static int ether_mdio_read(struct mii_bus *bus, int phyaddr, int phyreg) } /** - * ether_mdio_register - MDIO bus register - * @pdata: OSD private data. + * @brief MDIO bus registration. * - * Algorithm: Registers MDIO bus if there is mdio sub DT node - * as part of MAC DT node. + * Algorithm: Registers MDIO bus if there is mdio sub DT node + * as part of MAC DT node. * - * Dependencies: None. + * @param[in] pdata: OSD private data. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_mdio_register(struct ether_priv_data *pdata) { @@ -2422,18 +2358,16 @@ exit: } /** - * ether_get_irqs - Read IRQ numbers from DT. - * @pdev: Platform device associated with driver. - * @pdata: OSD private data. - * @num_chans: Number of channels. + * @brief Read IRQ numbers from DT. * - * Algorithm: Reads the IRQ numbers from DT based on number of channels. + * Algorithm: Reads the IRQ numbers from DT based on number of channels. * - * Dependencies: None. + * @param[in] pdev: Platform device associated with driver. + * @param[in] pdata: OSD private data. + * @param[in] num_chans: Number of channels. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_get_irqs(struct platform_device *pdev, struct ether_priv_data *pdata, @@ -2470,19 +2404,19 @@ static int ether_get_irqs(struct platform_device *pdev, } /** - * ether_get_mac_address_dtb - Get MAC address from DT - * @node_name: Device tree node name. - * @property_name: DT property name inside DT node. - * @mac_addr: MAC address. + * @brief Get MAC address from DT * - * Algorithm: Populates MAC address by reading DT node. + * Algorithm: Populates MAC address by reading DT node. * - * Dependencies: Bootloader needs to updates chosen DT node with MAC - * address. + * @param[in] node_name: Device tree node name. + * @param[in] property_name: DT property name inside DT node. + * @param[in] mac_addr: MAC address. * - * Protection: None. + * @note Bootloader needs to updates chosen DT node with MAC + * address. * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_get_mac_address_dtb(const char *node_name, const char *property_name, @@ -2539,17 +2473,16 @@ err_out: } /** - * ether_get_mac_address - Get MAC address from DT - * @pdata: OSD private data. + * @brief Get MAC address from DT * - * Algorithm: Populates MAC address by reading DT node. + * Algorithm: Populates MAC address by reading DT node. * - * Dependencies: Bootloader needs to updates chosen DT node with MAC - * address. + * @param[in] pdata: OSD private data. * - * Protection: None. + * @note Bootloader needs to updates chosen DT node with MAC address. * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_get_mac_address(struct ether_priv_data *pdata) { @@ -2576,16 +2509,11 @@ static int ether_get_mac_address(struct ether_priv_data *pdata) } /** - * ether_put_clks - Put back MAC related clocks. - * @pdata: OSD private data. + * @brief Put back MAC related clocks. * - * Algorithm: Put back or release the MAC related clocks. + * Algorithm: Put back or release the MAC related clocks. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] pdata: OSD private data. */ static inline void ether_put_clks(struct ether_priv_data *pdata) { @@ -2612,16 +2540,14 @@ static inline void ether_put_clks(struct ether_priv_data *pdata) } /** - * ether_get_clks - Get MAC related clocks. - * @pdata: OSD private data. + * @brief Get MAC related clocks. * - * Algorithm: Get the clocks from DT and stores in OSD private data. + * Algorithm: Get the clocks from DT and stores in OSD private data. * - * Dependencies: None. + * @param[in] pdata: OSD private data. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_get_clks(struct ether_priv_data *pdata) { @@ -2686,19 +2612,17 @@ err_axi_cbb: } /** - * ether_configure_car - Get Reset and MAC related clocks. - * @pdev: Platform device. - * @pdata: OSD private data. + * @brief Get Reset and MAC related clocks. * - * Algorithm: Get the resets and MAC related clocks from DT and stores in - * OSD private data. It also sets MDC clock rate by invoking OSI layer - * with osi_set_mdc_clk_rate(). + * Algorithm: Get the resets and MAC related clocks from DT and stores in + * OSD private data. It also sets MDC clock rate by invoking OSI layer + * with osi_set_mdc_clk_rate(). * - * Dependencies: None. + * @param[in] pdev: Platform device. + * @param[in] pdata: OSD private data. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_configure_car(struct platform_device *pdev, struct ether_priv_data *pdata) @@ -2793,17 +2717,15 @@ exit: } /** - * ether_init_plat_resources - Get platform resources - * @pdev: Platform device associated with platform driver. - * @pdata: OSD private data. + * @brief Get platform resources * - * Algorithm: Populates base address, clks, reset and MAC address. + * Algorithm: Populates base address, clks, reset and MAC address. * - * Dependencies: None. + * @param[in] pdev: Platform device associated with platform driver. + * @param[in] pdata: OSD private data. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_init_plat_resources(struct platform_device *pdev, struct ether_priv_data *pdata) @@ -2849,17 +2771,15 @@ rst_clk_fail: } /** - * ether_parse_phy_dt - Parse PHY DT. - * @pdata: OS dependent private data structure. - * @node: DT node entry of MAC + * @brief Parse PHY DT. * - * Algorithm: Reads PHY DT. Updates required data. + * Algorithm: Reads PHY DT. Updates required data. * - * Dependencies: None + * @param[in] pdata: OS dependent private data structure. + * @param[in] node: DT node entry of MAC * - * Protection: None - * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_parse_phy_dt(struct ether_priv_data *pdata, struct device_node *node) @@ -2890,22 +2810,19 @@ static int ether_parse_phy_dt(struct ether_priv_data *pdata, } /** - * ether_parse_queue_prio - Parse queue priority DT. - * @pdata: OS dependent private data structure. - * @pdt_prop: name of property - * @pval: structure pointer where value will be filed - * @val_def: default value if DT entry not reset - * @num_entries: number of entries to be read form DT + * @brief Parse queue priority DT. * - * Algorithm: Reads queue priority form DT. Updates - * data either by DT values or by default value. + * Algorithm: Reads queue priority form DT. Updates + * data either by DT values or by default value. * - * Dependencies: All queue priorities should be different - * from DT. + * @param[in] pdata: OS dependent private data structure. + * @param[in] pdt_prop: name of property + * @param[in] pval: structure pointer where value will be filed + * @param[in] val_def: default value if DT entry not reset + * @param[in] val_max: max value supported + * @param[in] num_entries: number of entries to be read form DT * - * Protection: None - * - * Return: void + * @note All queue priorities should be different from DT. */ static void ether_parse_queue_prio(struct ether_priv_data *pdata, const char *pdt_prop, @@ -2951,16 +2868,14 @@ static void ether_parse_queue_prio(struct ether_priv_data *pdata, } /** - * ether_parse_dt - Parse MAC and PHY DT. - * @pdata: OS dependent private data structure. + * @brief Parse MAC and PHY DT. * - * Algorithm: Reads MAC and PHY DT. Updates required data. + * Algorithm: Reads MAC and PHY DT. Updates required data. * - * Dependencies: None + * @param[in] pdata: OS dependent private data structure. * - * Protection: None - * - * Return: 0 - success, negative value - failure + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_parse_dt(struct ether_priv_data *pdata) { @@ -3132,22 +3047,17 @@ exit: } /** - * ether_get_num_dma_chan_mtl_q - Populate number of MTL and DMA channels. - * @pdev: Platform device - * @num_chans: Number of channels - * @mac: MAC type based on compatible property - * @num_mtl_queues: Number of MTL queues. + * @brief Populate number of MTL and DMA channels. * - * Algorithm: - * 1) Updates MAC HW type based on DT compatible property. - * 2) Read number of channels from DT. - * 3) Updates number of channels based on min and max number of channels + * Algorithm: + * 1) Updates MAC HW type based on DT compatible property. + * 2) Read number of channels from DT. + * 3) Updates number of channels based on min and max number of channels * - * Dependencies: None - * - * Protection: None - * - * Return: None. + * @param[in] pdev: Platform device + * @param[in] num_dma_chans: Number of channels + * @param[in] mac: MAC type based on compatible property + * @param[in] num_mtl_queues: Number of MTL queues. */ static void ether_get_num_dma_chan_mtl_q(struct platform_device *pdev, unsigned int *num_dma_chans, @@ -3197,19 +3107,18 @@ static void ether_get_num_dma_chan_mtl_q(struct platform_device *pdev, } /** - * ether_set_dma_mask - set dma mask. - * @pdata: OS dependent private data structure. + * @brief Set DMA address mask. * - * Algorithm: - * Based on the value read from HW addressing mode is set accordingly + * Algorithm: + * Based on the addressing capability (address bit length) supported in the HW, + * the dma mask is set accordingly. * - * Dependencies: MAC_HW_Feature1 register need to read and store the - * value of ADDR64. + * @param[in] pdata: OS dependent private data structure. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @note MAC_HW_Feature1 register need to read and store the value of ADDR64. * + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_set_dma_mask(struct ether_priv_data *pdata) { @@ -3244,21 +3153,20 @@ static int ether_set_dma_mask(struct ether_priv_data *pdata) return ret; } -/** ether_set_ndev_features - Set the network device feature flags - * @ndev: Network device instance - * @pdata: OS dependent private data structure. +/** + * @brief Set the network device feature flags * - * Algorithm: - * 1) Check the HW features supported - * 2) Enable corresponding feature flag so that network subsystem of OS - * is aware of device capabilities. - * 3) Update current enable/disable state of features currently enabled + * Algorithm: + * 1) Check the HW features supported + * 2) Enable corresponding feature flag so that network subsystem of OS + * is aware of device capabilities. + * 3) Update current enable/disable state of features currently enabled + * + * @param[in] ndev: Network device instance + * @param[in] pdata: OS dependent private data structure. * - * Dependencies: Netdev allocated and HW features are already parsed. + * @note Netdev allocated and HW features are already parsed. * - * Protection: None - * - * Return: None. */ static void ether_set_ndev_features(struct net_device *ndev, struct ether_priv_data *pdata) @@ -3302,21 +3210,14 @@ static void ether_set_ndev_features(struct net_device *ndev, } /** - * init_filter_values- static function to initialize filter reg - * count in private data structure + * @brief Static function to initialize filter register count + * in private data structure * - * @ether_priv_data: ethernet private data structure + * Algorithm: Updates addr_reg_cnt based on HW feature * - * Algorithm: - * 1) update addr_reg_cnt based on HW feature - * - * Dependencies: MAC_HW_Feature1 register need to read and store the - * value of ADDR64. - * - * Protection: None. - * - * Return: None. + * @param[in] pdata: ethernet private data structure * + * @note MAC_HW_Feature1 register need to read and store the value of ADDR64. */ static void init_filter_values(struct ether_priv_data *pdata) { @@ -3332,23 +3233,21 @@ static void init_filter_values(struct ether_priv_data *pdata) } /** - * ether_probe - Ethernet platform driver probe. - * @pdev: platform device associated with platform driver. + * @brief Ethernet platform driver probe. * - * Algorithm: - * 1) Get the number of channels from DT. - * 2) Allocate the network device for those many channels. - * 3) Parse MAC and PHY DT. - * 4) Get all required clks/reset/IRQ's - * 5) Register MDIO bus and network device. - * 6) initialize spinlock - * 7) Update filter value based on HW feature + * Algorithm: + * 1) Get the number of channels from DT. + * 2) Allocate the network device for those many channels. + * 3) Parse MAC and PHY DT. + * 4) Get all required clks/reset/IRQ's + * 5) Register MDIO bus and network device. + * 6) initialize spinlock + * 7) Update filter value based on HW feature * - * Dependencies: Device tree need to be updated with proper DT properties. + * @param[in] pdev: platform device associated with platform driver. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure * */ static int ether_probe(struct platform_device *pdev) @@ -3527,16 +3426,14 @@ err_dma_ops: } /** - * ether_remove - Ethernet platform driver remove. - * @pdev: Platform device associated with platform driver. + * @brief Ethernet platform driver remove. * - * Alogorithm: Release all the resources + * Alogorithm: Release all the resources * - * Dependencies: None. + * @param[in] pdev: Platform device associated with platform driver. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_remove(struct platform_device *pdev) { @@ -3708,12 +3605,18 @@ static const struct dev_pm_ops ether_pm_ops = { }; #endif +/** + * @brief Ethernet device tree compatible match name + */ static const struct of_device_id ether_of_match[] = { { .compatible = "nvidia,nveqos" }, {}, }; MODULE_DEVICE_TABLE(of, ether_of_match); +/** + * @brief Ethernet platform driver instance + */ static struct platform_driver ether_driver = { .probe = ether_probe, .remove = ether_remove, diff --git a/drivers/net/ethernet/nvidia/nvethernet/ether_linux.h b/drivers/net/ethernet/nvidia/nvethernet/ether_linux.h index 25da219a..7a793343 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ether_linux.h +++ b/drivers/net/ethernet/nvidia/nvethernet/ether_linux.h @@ -43,51 +43,103 @@ #include #include "ioctl.h" +/** + * @brief Max number of Ethernet IRQs supported in HW + */ #define ETHER_MAX_IRQS 4 +/** + * @brief Maximum index for IRQ numbers array. + */ #define ETHER_IRQ_MAX_IDX 8 +/** + * @brief Size of Ethernet IRQ name. + */ #define ETHER_IRQ_NAME_SZ 32 + +/** + * @addtogroup Ethernet Transmit Queue Priority + * + * @brief Macros to define the default, maximum and invalid range of Transmit + * queue priority. These macros are used to check the bounds of Tx queue + * priority provided in the device tree. + * @{ + */ #define ETHER_QUEUE_PRIO_DEFAULT 0U #define ETHER_QUEUE_PRIO_MAX 7U #define ETHER_QUEUE_PRIO_INVALID 0xFFU +/** @} */ + +/** + * @brief Ethernet default PTP clock frequency + */ #define ETHER_DFLT_PTP_CLK 312500000U +/** + * @addtogroup CONFIG Ethernet configuration error codes + * + * @brief Error codes for fail/success. + * @{ + */ #define EQOS_CONFIG_FAIL -3 #define EQOS_CONFIG_SUCCESS 0 +/** @} */ +/** + * @addtogroup ADDR Ethernet MAC address register count + * + * @brief MAC L2 address filter count + * @{ + */ #define ETHER_ADDR_REG_CNT_128 128 #define ETHER_ADDR_REG_CNT_64 64 #define ETHER_ADDR_REG_CNT_32 32 #define ETHER_ADDR_REG_CNT_1 1 +/** @} */ +/** + * @addtogroup HW MAC HW Filter Hash Table size + * + * @brief Represents Hash Table sizes. + * @{ + */ #define HW_HASH_TBL_SZ_3 3 #define HW_HASH_TBL_SZ_2 2 #define HW_HASH_TBL_SZ_1 1 #define HW_HASH_TBL_SZ_0 0 +/** @} */ +/** + * @brief Ethernet Maximum HW MTU + */ #define ETHER_MAX_HW_MTU 9000U +/** + * @brief Ethernet default platform supported MTU + */ #define ETHER_DEFAULT_PLATFORM_MTU 1500U -/* Map max. 4KB buffer per Tx descriptor */ +/** + * @brief Maximum buffer length per DMA descriptor (4KB). + */ #define ETHER_MAX_DATA_LEN_PER_TXD_BUF BIT(12) -/* Incase of TSO/GSO, Tx ring needs atmost MAX_SKB_FRAGS + - * one context descriptor + - * one descriptor for header/linear buffer payload +/** + * @brief In-case of TSO/GSO, Tx ring needs atleast MAX_SKB_FRAGS + + * one context descriptor + + * one descriptor for header/linear buffer payload */ #define TX_DESC_THRESHOLD (MAX_SKB_FRAGS + 2) /** - * ether_avail_txdesc_count - Return count of available tx desc. - * @tx_ring: Tx ring instance associated with channel number + *@brief Returns count of available transmit descriptors * - * Algorithm: Check the difference between current desc index - * and the desc. index to be cleaned. + * Algorithm: Check the difference between current descriptor index + * and the descriptor index to be cleaned. * - * Dependencies: MAC needs to be initialized and Tx ring allocated. + * @param[in] tx_ring: Tx ring instance associated with channel number * - * Protection: None. + * @note MAC needs to be initialized and Tx ring allocated. * - * Return: Number of available descriptors in the given Tx ring. + * @returns Number of available descriptors in the given Tx ring. */ static inline int ether_avail_txdesc_cnt(struct osi_tx_ring *tx_ring) { @@ -96,173 +148,219 @@ static inline int ether_avail_txdesc_cnt(struct osi_tx_ring *tx_ring) } #ifdef THERMAL_CAL -/* The DT binding for ethernet device has 5 thermal zones in steps of +/* @brief The DT binding for ethernet device has 5 thermal zones in steps of * 35 degress from -40C to 110C. Each zone corresponds to a state. */ #define ETHER_MAX_THERM_STATE 5UL #endif /* THERMAL_CAL */ /** - * struct ether_tx_napi - DMA Transmit Channel NAPI - * @chan: Transmit channel number - * @pdata: OSD private data - * @napi: NAPI instance associated with transmit channel + * @brief DMA Transmit Channel NAPI */ struct ether_tx_napi { + /** Transmit channel number */ unsigned int chan; + /** OSD private data */ struct ether_priv_data *pdata; + /** NAPI instance associated with transmit channel */ struct napi_struct napi; }; /** - * struct ether_rx_napi - DMA Receive Channel NAPI - * @chan: Receive channel number - * @pdata: OSD Private data - * @napi: NAPI instance associated with receive channel + *@brief DMA Receive Channel NAPI */ struct ether_rx_napi { + /** Receive channel number */ unsigned int chan; + /** OSD private data */ struct ether_priv_data *pdata; + /** NAPI instance associated with transmit channel */ struct napi_struct napi; }; /** - * struct ether_priv_data - Ethernet driver private data - * @osi_core: OSI core private data - * @osi_dma: OSI DMA private data - * @hwfeat: HW supported feature list - * @tx_napi: Array of DMA Transmit channel NAPI - * @rx_napi: Array of DMA Receive channel NAPI - * @ndev: Network device associated with driver - * @dev: Base device associated with driver - * @mac_rst: Reset for the MAC - * @pllrefe_clk: PLLREFE clock - * @axi_clk: Clock from AXI - * @axi_cbb_clk: Clock from AXI CBB - * @rx_clk: Receive clock (which will be driven from the PHY) - * @ptp_ref_clk: PTP reference clock from AXI - * @tx_clk: Transmit clock - * @phy_node: Pointer to PHY device tree node - * @mdio_node: Pointer to MDIO device tree node - * @mii: Pointer to MII bus instance - * @phydev: Pointer to the PHY device - * @interface: Interface type assciated with MAC (SGMII/RGMII/...) - * this information will be provided with phy-mode DT - * entry - * @oldlink: Previous detected link - * @speed: PHY link speed - * @oldduplex: Previous detected mode - * @phy_reset: Reset for PHY - * @rx_irq_alloc_mask: Tx IRQ alloc mask - * @tx_irq_alloc_mask: Rx IRQ alloc mask - * @common_irq: Common IRQ number for MAC - * @tx_irqs: Array of DMA Transmit channel IRQ numbers - * @rx_irqs: Array of DMA Receive channel IRQ numbers - * @dma_mask: memory allocation mask - * @mac_loopback_mode: MAC loopback mode - * @txq_prio: Array of MTL queue TX priority - * @hw_feat_cur_state: Current state of features enabled in HW - * @tcd: Pointer to thermal cooling device which this driver - * registers with the kernel. Kernel will invoke the - * callback ops for this cooling device when temperate - * in thermal zone defined in DT binding for this driver - * is tripped. - * @therm_state: Atomic variable to hold the current temperature zone - * which has triggered. - * @lock: Spin lock for filter code - * @ioctl_lock: Spin lock for filter code ioctl path - * @max_hash_table_size: hash table size; 0, 64,128 or 256 - * @num_mac_addr_regs: max address register count, 2*mac_addr64_sel - * @last_mc_filter_index: Last Multicast address reg filter index, If 0, - * no MC address added - * @last_uc_filter_index: Last Unicast address reg filter index, If 0, no - * MC and UC address added. - * @l3_l4_filter: L3_l4 filter enabled 1: enabled - * @vlan_hash_filtering: vlan hash filter 1: hash, 0: perfect - * @l2_filtering_mode: l2 filter mode 1: hash 0: perfect - * @ptp_clock_ops: PTP clock operations structure. - * @ptp_clock: PTP system clock - * @ptp_ref_clock_speed: PTP reference clock supported by platform - * @hwts_tx_en: HW tx time stamping enable - * @hwts_rx_en: HW rx time stamping enable - * @max_platform_mtu: Max MTU supported by platform - * @ptp_lock: Lock for accessing PTP registers + * @brief Ethernet driver private data */ struct ether_priv_data { + /** OSI core private data */ struct osi_core_priv_data *osi_core; + /** OSI DMA private data */ struct osi_dma_priv_data *osi_dma; - + /** HW supported feature list */ struct osi_hw_features hw_feat; + /** Array of DMA Transmit channel NAPI */ struct ether_tx_napi *tx_napi[OSI_EQOS_MAX_NUM_CHANS]; + /** Array of DMA Receive channel NAPI */ struct ether_rx_napi *rx_napi[OSI_EQOS_MAX_NUM_CHANS]; - + /** Network device associated with driver */ struct net_device *ndev; + /** Base device associated with driver */ struct device *dev; - + /** Reset for the MAC */ struct reset_control *mac_rst; + /** PLLREFE clock */ struct clk *pllrefe_clk; + /** Clock from AXI */ struct clk *axi_clk; + /** Clock from AXI CBB */ struct clk *axi_cbb_clk; + /** Receive clock (which will be driven from the PHY) */ struct clk *rx_clk; + /** PTP reference clock from AXI */ struct clk *ptp_ref_clk; + /** Transmit clock */ struct clk *tx_clk; - + /** Pointer to PHY device tree node */ struct device_node *phy_node; + /** Pointer to MDIO device tree node */ struct device_node *mdio_node; + /** Pointer to MII bus instance */ struct mii_bus *mii; + /** Pointer to the PHY device */ struct phy_device *phydev; + /** Interface type assciated with MAC (SGMII/RGMII/...) + * this information will be provided with phy-mode DT entry */ int interface; + /** Previous detected link */ unsigned int oldlink; + /** PHY link speed */ int speed; + /** Previous detected mode */ int oldduplex; + /** Reset for PHY */ int phy_reset; - + /** Rx IRQ alloc mask */ unsigned int rx_irq_alloc_mask; + /** Tx IRQ alloc mask */ unsigned int tx_irq_alloc_mask; + /** Common IRQ alloc mask */ unsigned int common_irq_alloc_mask; - + /** Common IRQ number for MAC */ int common_irq; + /** Array of DMA Transmit channel IRQ numbers */ int tx_irqs[ETHER_MAX_IRQS]; + /** Array of DMA Receive channel IRQ numbers */ int rx_irqs[ETHER_MAX_IRQS]; + /** memory allocation mask */ unsigned long long dma_mask; + /** Current state of features enabled in HW*/ netdev_features_t hw_feat_cur_state; - - /* for MAC loopback */ + /** MAC loopback mode */ unsigned int mac_loopback_mode; - unsigned int txq_prio[OSI_EQOS_MAX_NUM_QUEUES]; + /** Array of MTL queue TX priority */ + unsigned int txq_prio[OSI_EQOS_MAX_NUM_CHANS]; #ifdef THERMAL_CAL + /** Pointer to thermal cooling device which this driver registers + * with the kernel. Kernel will invoke the callback ops for this + * cooling device when temperate in thermal zone defined in DT + * binding for this driver is tripped */ struct thermal_cooling_device *tcd; + /** Atomic variable to hold the current temperature zone + * whcih has triggered */ atomic_t therm_state; #endif /* THERMAL_CAL */ - - /* for filtering */ + /** Spin lock for filter code */ spinlock_t lock; + /** Spin lock for Tx/Rx interrupt enable registers */ spinlock_t rlock; - /* spin lock for ioctl path */ + /** spin lock for filter code ioctl path */ spinlock_t ioctl_lock; + /** max address register count, 2*mac_addr64_sel */ int num_mac_addr_regs; + /** Last Multicast address reg filter index, If 0,no MC address added */ int last_mc_filter_index; + /** Last Unicast address reg filter index, If 0,no MC address added */ int last_uc_filter_index; + /** L3_l4 filter enabled 1: enabled */ unsigned int l3_l4_filter; + /** vlan hash filter 1: hash, 0: perfect */ unsigned int vlan_hash_filtering; + /** PTP clock operations structure */ unsigned int l2_filtering_mode; - - /* for PTP */ + /** PTP clock operations structure */ struct ptp_clock_info ptp_clock_ops; + /** PTP system clock */ struct ptp_clock *ptp_clock; + /** PTP reference clock supported by platform */ unsigned int ptp_ref_clock_speed; + /** HW tx time stamping enable */ unsigned int hwts_tx_en; + /** HW rx time stamping enable */ unsigned int hwts_rx_en; + /** Max MTU supported by platform */ unsigned int max_platform_mtu; + /** Spin lock for PTP registers */ raw_spinlock_t ptp_lock; }; +/** + * @brief Set ethtool operations + * + * @param[in] ndev: network device instance + * + * @note Network device needs to created. + */ void ether_set_ethtool_ops(struct net_device *ndev); +/** + * @brief Creates Ethernet sysfs group + * + * @param[in] dev: device instance + * + * @retval 0 - success, + * @retval "negative value" - failure. + */ int ether_sysfs_register(struct device *dev); + +/** + * @brief Removes Ethernet sysfs group + * + * @param[in] dev: device instance + * + * @note nvethernet sysfs group need to be registered during probe. + */ void ether_sysfs_unregister(struct device *dev); + +/** + * @brief Function to register ptp clock driver + * + * Algorithm: This function is used to register the ptp clock driver to kernel + * + * @param[in] pdata: Pointer to private data structure. + * + * @note Driver probe need to be completed successfully with ethernet + * network device created + * + * @retval 0 on success + * @retval "negative value" on Failure + */ int ether_ptp_init(struct ether_priv_data *pdata); + +/** + * @brief Function to unregister ptp clock driver + * + * Algorithm: This function is used to remove ptp clock driver from kernel. + * + * @param[in] pdata: Pointer to private data structure. + * + * @note PTP clock driver need to be successfully registered during init + */ void ether_ptp_remove(struct ether_priv_data *pdata); + +/** + * @brief Function to handle PTP settings. + * + * Algorithm: This function is used to handle the hardware PTP settings. + * + * @param[in] pdata Pointer to private data structure. + * @param[in] ifr Interface request structure used for socket ioctl + * + * @note PTP clock driver need to be successfully registered during + * initialization and HW need to support PTP functionality. + * + * @retval 0 on success + * @retval "negative value" on Failure + */ int ether_handle_hwtstamp_ioctl(struct ether_priv_data *pdata, struct ifreq *ifr); int ether_handle_priv_ts_ioctl(struct ether_priv_data *pdata, diff --git a/drivers/net/ethernet/nvidia/nvethernet/ethtool.c b/drivers/net/ethernet/nvidia/nvethernet/ethtool.c index 31d00dbe..d19e2fa6 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ethtool.c +++ b/drivers/net/ethernet/nvidia/nvethernet/ethtool.c @@ -16,21 +16,37 @@ #include "ether_linux.h" +/** + * @addtogroup MMC Stats array length. + * + * @brief Helper macro to find MMC stats array length. + * @{ + */ #define OSI_ARRAY_SIZE(x) ((int)sizeof((x)) / (int)sizeof((x)[0])) #define EQOS_MMC_STATS_LEN OSI_ARRAY_SIZE(eqos_mmc) +/** @} */ +/** + * @brief EQOS stats + */ struct eqos_stats { + /** Name of the stat */ char stat_string[ETH_GSTRING_LEN]; + /** size of the stat */ size_t sizeof_stat; + /** stat offset */ size_t stat_offset; }; -/* DMA extra status */ -/* Structure variable name MUST up to MAX length of ETH_GSTRING_LEN */ +/** + * @brief Name of extra DMA stat, with length of name not more than ETH_GSTRING_LEN + */ #define EQOS_DMA_EXTRA_STAT(a) \ { (#a), FIELD_SIZEOF(struct osi_xtra_dma_stat_counters, a), \ offsetof(struct osi_dma_priv_data, dstats.a)} - +/** + * @brief EQOS DMA extra statistics + */ static const struct eqos_stats eqos_dstrings_stats[] = { EQOS_DMA_EXTRA_STAT(tx_clean_n[0]), EQOS_DMA_EXTRA_STAT(tx_clean_n[1]), @@ -55,14 +71,20 @@ static const struct eqos_stats eqos_dstrings_stats[] = { EQOS_DMA_EXTRA_STAT(q_rx_pkt_n[3]), }; +/** + * @brief EQOS extra DMA statistics array length + */ #define EQOS_EXTRA_DMA_STAT_LEN OSI_ARRAY_SIZE(eqos_dstrings_stats) -/* core extra status */ -/* Structure variable name MUST up to MAX length of ETH_GSTRING_LEN */ +/** + * @brief Name of extra EQOS stats, with length of name not more than ETH_GSTRING_LEN MAC + */ #define EQOS_EXTRA_STAT(b) \ { #b, FIELD_SIZEOF(struct osi_xtra_stat_counters, b), \ offsetof(struct osi_core_priv_data, xstats.b)} - +/** + * @brief EQOS extra statistics + */ static const struct eqos_stats eqos_gstrings_stats[] = { EQOS_EXTRA_STAT(re_alloc_rxbuf_failed[0]), EQOS_EXTRA_STAT(re_alloc_rxbuf_failed[1]), @@ -102,14 +124,22 @@ static const struct eqos_stats eqos_gstrings_stats[] = { EQOS_EXTRA_STAT(link_connect_count), }; +/** + * @brief EQOS extra statistics array length + */ #define EQOS_EXTRA_STAT_LEN OSI_ARRAY_SIZE(eqos_gstrings_stats) -/* HW MAC Management counters */ -/* Structure variable name MUST up to MAX length of ETH_GSTRING_LEN */ +/** + * @brief HW MAC Management counters + * Structure variable name MUST up to MAX length of ETH_GSTRING_LEN + */ #define EQOS_MMC_STAT(c) \ { #c, FIELD_SIZEOF(struct osi_mmc_counters, c), \ offsetof(struct osi_core_priv_data, mmc.c)} +/** + * @brief MMC statistics + */ static const struct eqos_stats eqos_mmc[] = { /* MMC TX counters */ EQOS_MMC_STAT(mmc_tx_octetcount_gb), @@ -206,20 +236,16 @@ static const struct eqos_stats eqos_mmc[] = { }; /** - * ether_get_ethtool_stats: This function is invoked by kernel when user - * requests to get the extended statistics about the device. + * @brief This function is invoked by kernel when user requests to get the + * extended statistics about the device. * - * @dev: pointer to net device structure. - * @dummy: dummy parameter of ethtool_stats type. - * @data: Pointer in which MMC statistics should be put. + * Algorithm: read mmc register and create strings * - * Algorithm: read mmc register and create sctrings + * @param[in] dev: pointer to net device structure. + * @param[in] dummy: dummy parameter of ethtool_stats type. + * @param[in] data: Pointer in which MMC statistics should be put. * - * Dependencies: Network device needs to created. - * - * Protection: None. - * - * Return: void + * @note Network device needs to created. */ static void ether_get_ethtool_stats(struct net_device *dev, struct ethtool_stats *dummy, @@ -265,19 +291,16 @@ static void ether_get_ethtool_stats(struct net_device *dev, } /** - * ether_get_sset_count- This function gets number of strings that - * @get_strings will write. + * @brief This function gets number of strings * - * @dev: Pointer to net device structure. - * @sset: String set value. + * Algorithm: return number of strings. * - * Algorithm: retrun number of strings. + * @param[in] dev: Pointer to net device structure. + * @param[in] sset: String set value. * - * Dependencies: Network device needs to created. + * @note Network device needs to created. * - * Protection: None. - * - * Return: Numbers of strings(total length) + * @return Numbers of strings(total length) */ static int ether_get_sset_count(struct net_device *dev, int sset) { @@ -309,20 +332,17 @@ static int ether_get_sset_count(struct net_device *dev, int sset) return len; } -/** ether_get_strings - This function returns a set of strings that describe - * the requested objects. +/** + * @brief This function returns a set of strings that describe + * the requested objects. * - * @dev: Pointer to net device structure. - * @stringset: String set value. - * @data: Pointer in which requested string should be put. + * Algorithm: return number of strings. * - * Algorithm: retrun number of strings. + * @param[in] dev: Pointer to net device structure. + * @param[in] stringset: String set value. + * @param[in] data: Pointer in which requested string should be put. * - * Dependencies: Network device needs to created. - * - * Protection: None. - * - * Return: void + * @note Network device needs to created. */ static void ether_get_strings(struct net_device *dev, u32 stringset, u8 *data) { @@ -365,17 +385,14 @@ static void ether_get_strings(struct net_device *dev, u32 stringset, u8 *data) } /** - * ether_get_pauseparam - Get pause frame settings - * @ndev: network device instance - * @pause: Pause parameters that are set currently + * @brief Get pause frame settings * - * Algorithm: Gets pause frame configuration + * Algorithm: Gets pause frame configuration * - * Dependencies: Network device needs to created. + * @param[in] ndev: network device instance + * @param[out] pause: Pause parameters that are set currently * - * Protection: None. - * - * Return: None. + * @note Network device needs to created. */ static void ether_get_pauseparam(struct net_device *ndev, struct ethtool_pauseparam *pause) @@ -413,17 +430,17 @@ static void ether_get_pauseparam(struct net_device *ndev, } /** - * ether_set_pauseparam - Set pause frame settings - * @ndev: network device instance - * @pause: Pause frame settings + * @brief Set pause frame settings * - * Algorithm: Sets pause frame settings + * Algorithm: Sets pause frame settings * - * Dependencies: Network device needs to created. + * @param[in] ndev: network device instance + * @param[in] pause: Pause frame settings * - * Protection: None. + * @note Network device needs to created. * - * Return: 0 - success, negative value - failure. + * @retval 0 on Sucess + * @retval "negative value" on failure. */ static int ether_set_pauseparam(struct net_device *ndev, struct ethtool_pauseparam *pause) @@ -477,17 +494,16 @@ static int ether_set_pauseparam(struct net_device *ndev, } /** - * ether_get_ts_info: Get HW supported time stamping. - * @net: Net device data. - * @info: Holds device supported timestamping types + * @brief Get HW supported time stamping. * - * Algorithm: Function used to query the PTP capabilities for given netdev. + * Algorithm: Function used to query the PTP capabilities for given netdev. * - * Dependencies: HW need to support PTP functionality. + * @param[in] net: Net device data. + * @param[in] info: Holds device supported timestamping types * - * Protection: None. + * @note HW need to support PTP functionality. * - * Return: Return can't be a -ve value. + * @return zero on success */ static int ether_get_ts_info(struct net_device *net, struct ethtool_ts_info *info) @@ -515,21 +531,20 @@ static int ether_get_ts_info(struct net_device *net, } /** - * ether_set_coalesce: Set interrupt coalescing parameters. - * @dev: Net device data. - * @ec: pointer to ethtool_coalesce structure + * @brief Set interrupt coalescing parameters. * - * Algorithm: This function is invoked by kernel when user request to set - * interrupt coalescing parameters. This driver maintains same coalescing - * parameters for all the channels, hence same changes will be applied to - * all the channels. + * Algorithm: This function is invoked by kernel when user request to set + * interrupt coalescing parameters. This driver maintains same coalescing + * parameters for all the channels, hence same changes will be applied to + * all the channels. * - * Dependencies: - * 1) Interface need to be bring down for setting these parameters + * @param[in] dev: Net device data. + * @param[in] ec: pointer to ethtool_coalesce structure * - * Protection: None. + * @note Interface need to be bring down for setting these parameters * - * Return: 0 on success and -ve number on failure. + * @retval 0 on Sucess + * @retval "negative value" on failure. */ static int ether_set_coalesce(struct net_device *dev, struct ethtool_coalesce *ec) @@ -582,21 +597,19 @@ static int ether_set_coalesce(struct net_device *dev, } /** - * ether_get_coalesce: Set interrupt coalescing parameters. - * @dev: Net device data. - * @ec: pointer to ethtool_coalesce structure + * @brief Set interrupt coalescing parameters. * - * Algorithm: This function is invoked by kernel when user request to get - * interrupt coalescing parameters. As coalescing parameters are same - * for all the channels, so this function will get coalescing - * details from channel zero and return. + * Algorithm: This function is invoked by kernel when user request to get + * interrupt coalescing parameters. As coalescing parameters are same + * for all the channels, so this function will get coalescing + * details from channel zero and return. * - * Dependencies: - * 1) MAC and PHY need to be initialized. + * @param[in] dev: Net device data. + * @param[in] ec: pointer to ethtool_coalesce structure * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: 0. + * @retval 0 on Success. */ static int ether_get_coalesce(struct net_device *dev, struct ethtool_coalesce *ec) @@ -610,6 +623,9 @@ static int ether_get_coalesce(struct net_device *dev, return 0; } +/** + * @brief Set of ethtool operations + */ static const struct ethtool_ops ether_ethtool_ops = { .get_link = ethtool_op_get_link, .get_link_ksettings = phy_ethtool_get_link_ksettings, @@ -624,17 +640,6 @@ static const struct ethtool_ops ether_ethtool_ops = { .set_coalesce = ether_set_coalesce, }; -/** - * ether_set_ethtool_ops - Set ethtool operations - * @ndev: network device instance - * - * Algorithm: Sets ethtool operations in network - * device structure. - * - * Dependencies: Network device needs to created. - * Protection: None. - * Return: None. - */ void ether_set_ethtool_ops(struct net_device *ndev) { ndev->ethtool_ops = ðer_ethtool_ops; diff --git a/drivers/net/ethernet/nvidia/nvethernet/ioctl.c b/drivers/net/ethernet/nvidia/nvethernet/ioctl.c index 085de6ad..0b081276 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ioctl.c +++ b/drivers/net/ethernet/nvidia/nvethernet/ioctl.c @@ -17,19 +17,17 @@ #include "ether_linux.h" /** - * ether_set_avb_algo - function to handle private ioctl - * EQOS_AVB_ALGORITHM - * @ndev: network device structure - * @ifdata: interface private data structure + * @brief Function to handle private ioctl - EQOS_AVB_ALGORITHM * - * Algorithm: - * - Call osi_set_avb with user passed data + * Algorithm: Call osi_set_avb with user passed data * - * Dependencies: Ethernet interface need to be up. + * @param[in] ndev: network device structure + * @param[in] ifdata: interface private data structure * - * Protection: None. + * @note Ethernet interface need to be up. * - * Return: 0 - success, negative value - failure. + * @retval 0 on Sucess + * @retval "nagative value" on Failure */ static int ether_set_avb_algo(struct net_device *ndev, struct ether_ifr_data *ifdata) @@ -57,20 +55,19 @@ static int ether_set_avb_algo(struct net_device *ndev, } /** - * ether_get_avb_algo - function to get avb data from registers. - * This function is called for EQOS_GET_AVB_ALGORITHM - * @ndev: network device structure - * @ifdata: interface private data structure + * @brief Function to get avb data from registers. This function is called for + * EQOS_GET_AVB_ALGORITHM * - * Algorithm: - * - Call osi_get_avb with user passed data(qindex) + * Algorithm: Call osi_get_avb with user passed data(qindex) * - * Dependencies: Ethernet interface need to be up. Caller should - * check for return vlaue before using return value. + * @param[in] ndev: network device structure + * @param[in] ifdata: interface private data structure * - * Protection: None. + * @note Ethernet interface need to be up. Caller should check for return + * value before using return value. * - * Return: 0 - success, negative value - failure. + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_get_avb_algo(struct net_device *ndev, struct ether_ifr_data *ifdata) @@ -109,22 +106,22 @@ static int ether_get_avb_algo(struct net_device *ndev, return ret; } -/* - * ether_config_arp_offload - Handle ioctl to enable/disable ARP offload - * @pdata: OS dependent private data structure. - * @ifrd_p: Interface request private data pointer. +/** + * @brief Handle ioctl to enable/disable ARP offload * - * Algorithm: - * 1) Copy the priv data from user space. This includes the IP address - * to be updated in HW. - * 2) Check if IP address provided in priv data is valid. - * 3) If IP address is valid, invoke OSI API to update HW registers. + * Algorithm: + * 1) Copy the priv data from user space. This includes the IP address + * to be updated in HW. + * 2) Check if IP address provided in priv data is valid. + * 3) If IP address is valid, invoke OSI API to update HW registers. * - * Dependencies: Interface should be running (enforced by caller). + * @param[in] pdata: OS dependent private data structure. + * @param[in] ifrd_p: Interface request private data pointer. + * + * @note Interface should be running (enforced by caller). * - * Protection: None. - * - * Return: 0 - success, -ve value - failure + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_arp_offload(struct ether_priv_data *pdata, struct ether_ifr_data *ifrd_p) @@ -163,22 +160,21 @@ static int ether_config_arp_offload(struct ether_priv_data *pdata, } /** - * ether_config_l3_l4_filtering- This function is invoked by ioctl - * when user issues an ioctl command to enable/disable L3/L4 filtering. + * @brief This function is invoked by ioctl when user issues an ioctl command + * to enable/disable L3/L4 filtering. * - * @dev: pointer to net device structure. - * @filter_flags: flag to indicate whether L3/L4 filtering to be - * enabled/disabled. + * Algorithm: + * 1) check if filter enalbed/disable already and return success. + * 2) OSI call to update register * - * Algorithm: - * 1) check if filter enalbed/disable already and return success. - * 2) OSI call to update register + * @param[in] dev: pointer to net device structure. + * @param[in] filter_flags: flag to indicate whether L3/L4 filtering to be + * enabled/disabled. * - * Dependencies: MAC and PHY need to be initialized. + * @note MAC and PHY need to be initialized. * - * Protection: None. - * - * Return 0- sucessful, non-zero - error + * @retval 0 on Sucess + * @retval "negative value" on Failure * */ static int ether_config_l3_l4_filtering(struct net_device *dev, @@ -205,24 +201,23 @@ static int ether_config_l3_l4_filtering(struct net_device *dev, } /** - * ether_config_ip4_filters - this function is invoked by ioctl function - * when user issues an ioctl command to configure L3(IPv4) filtering. + * @brief This function is invoked by ioctl function when user issues an ioctl + * command to configure L3(IPv4) filtering. * - * @dev: Pointer to net device structure. - * @ifdata: pointer to IOCTL specific structure. + * Algorithm: + * 1) Layer 3 and Layer 4 Filter Enable, if already not. + * 2) Enable/disable IPv4 filtering. + * 3) Select source/destination address matching. + * 4) Select perfect/inverse matching. + * 5) Update the IPv4 address into MAC register. * - * Algorithm: - * 1) Layer 3 and Layer 4 Filter Enable, if already not. - * 2) Enable/disable IPv4 filtering. - * 3) Select source/destination address matching. - * 4) Select perfect/inverse matching. - * 5) Update the IPv4 address into MAC register. + * @param[in] dev: Pointer to net device structure. + * @param[in] ifdata: pointer to IOCTL specific structure. + * + * @note MAC and PHY need to be initialized. * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * - * Return 0- sucessful, non-zero - error + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_ip4_filters(struct net_device *dev, struct ether_ifr_data *ifdata) @@ -287,23 +282,22 @@ static int ether_config_ip4_filters(struct net_device *dev, } /** - * ether_config_ip6_filters- This function is invoked by ioctl when user - * issues an ioctl command to configure L3(IPv6) filtering. + * @brief This function is invoked by ioctl when user issues an ioctl command + * to configure L3 (IPv6) filtering. * - * @dev: pointer to net device structure. - * @ifdata:pointer to IOCTL specific structure. + * Algorithm: + * 1) Enable/disable IPv6 filtering. + * 2) Select source/destination address matching. + * 3) Select perfect/inverse matching. + * 4) Update the IPv6 address into MAC register. * - * Algorithm: - * 1) Enable/disable IPv6 filtering. - * 2) Select source/destination address matching. - * 3) Select perfect/inverse matching. - * 4) Update the IPv6 address into MAC register. + * @param[in] dev: net device structure instance. + * @param[in] ifdata: IOCTL specific structure instance. * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * Return 0- sucessful, non-zero - error + * @note MAC and PHY need to be initialized. * + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_ip6_filters(struct net_device *dev, struct ether_ifr_data *ifdata) @@ -365,27 +359,24 @@ static int ether_config_ip6_filters(struct net_device *dev, } /** - * ether_config_tcp_udp_filters- This function is invoked by - * ioctl function when user issues an ioctl command to configure - * L4(TCP/UDP) filtering. + * @brief This function is invoked by ioctl function when user issues an ioctl + * command to configure L4(TCP/UDP) filtering. * - * @dev: pointer to net device structure. - * @ifdata: pointer to IOCTL specific structure. - * @tcp_udp: flag to indicate TCP/UDP filtering. + * Algorithm: + * 1) Enable/disable L4 filtering. + * 2) Select TCP/UDP filtering. + * 3) Select source/destination port matching. + * 4) select perfect/inverse matching. + * 5) Update the port number into MAC register. * - * Algorithm: - * 1) Enable/disable L4 filtering. - * 2) Select TCP/UDP filtering. - * 3) Select source/destination port matching. - * 4) select perfect/inverse matching. - * 5) Update the port number into MAC register. - * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * - * Return 0- sucessful, non-zero - error + * @param[in] dev: pointer to net device structure. + * @param[in] ifdata: pointer to IOCTL specific structure. + * @param[in] tcp_udp: flag to indicate TCP/UDP filtering. + * + * @note MAC and PHY need to be initialized. * + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_tcp_udp_filters(struct net_device *dev, struct ether_ifr_data *ifdata, @@ -452,22 +443,20 @@ static int ether_config_tcp_udp_filters(struct net_device *dev, } /** - * ether_config_vlan_filter- This function is invoked by ioctl function - * when user issues an ioctl command to configure VALN filtering. + * @brief This function is invoked by ioctl functio when user issues an ioctl + * command to configure VALN filtering. * - * @dev: pointer to net device structure. - * @ifdata: pointer to IOCTL specific structure. + * Algorithm: + * 1) enable/disable VLAN filtering. + * 2) select perfect/hash filtering. * - * Algorithm: - * 1) enable/disable VLAN filtering. - * 2) select perfect/hash filtering. + * @param[in] dev: pointer to net device structure. + * @param[in] ifdata: pointer to IOCTL specific structure. * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * - * Return 0- sucessful, non-zero - error + * @note MAC and PHY need to be initialized. * + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_vlan_filter(struct net_device *dev, struct ether_ifr_data *ifdata) @@ -509,22 +498,20 @@ static int ether_config_vlan_filter(struct net_device *dev, } /** - * ether_config_l2_da_filter- This function is invoked by ioctl function - * when user issues an ioctl command to configure L2 destination - * addressing filtering mode. + * @brief This function is invoked by ioctl function when user issues an ioctl + * command to configure L2 destination addressing filtering mode. * - * @dev: Pointer to net device structure. - * @ifdata: Pointer to IOCTL specific structure. + * Algorithm: + * 1) Selects perfect/hash filtering. + * 2) Selects perfect/inverse matching. * - * Algorithm: - * 1) Selects perfect/hash filtering. - * 2) Selects perfect/inverse matching. + * @param[in] dev: Pointer to net device structure. + * @param[in] ifdata: Pointer to IOCTL specific structure. * - * Dependencies: MAC and PHY need to be initialized. + * @note MAC and PHY need to be initialized. * - * Protection: None. - * - * Return 0- sucessful, non-zero - error + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_l2_da_filter(struct net_device *dev, struct ether_ifr_data *ifdata) @@ -565,22 +552,21 @@ static int ether_config_l2_da_filter(struct net_device *dev, } /** - * ether_config_loopback_mode- This function is invoked by ioctl - * when user issues an ioctl command to enable/disable MAC loopback mode. + * @brief This function is invoked by ioctl when user issues an ioctl command + * to enable/disable MAC loopback mode. * - * @dev: pointer to net device structure. - * @flags: flag to indicate whether MAC loopback mode to be enabled or + * Algorithm: + * 1) check if loopback mode enalbed/disable already and return success. + * 2) OSI call to configure loopback mode in HW. + * + * @param[in] ndev: pointer to net device structure. + * @param[in] flags: flag to indicate whether MAC loopback mode to be enabled or * disabled. * - * Algorithm: - * 1) check if loopback mode enalbed/disable already and return success. - * 2) OSI call to configure loopback mode in HW. - * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * - * Return 0- sucessful, Negative - error + * @note MAC and PHY need to be initialized. + * + * @retval 0 on Sucess + * @retval "negative value" on Failure */ static int ether_config_loopback_mode(struct net_device *ndev, unsigned int flags) @@ -621,21 +607,20 @@ static int ether_config_loopback_mode(struct net_device *ndev, } /** - * ether_priv_ioctl - Handle private IOCTLs - * @ndev: network device structure - * @ifr: Interface request structure used for socket ioctl's. + * @brief ether_priv_ioctl - Handle private IOCTLs * - * Algorithm: - * 1) Copy the priv command data from user space. - * 2) Check the priv command cmd and invoke handler func. - * if it is supported. - * 3) Copy result back to user space. + * Algorithm: + * 1) Copy the priv command data from user space. + * 2) Check the priv command cmd and invoke handler function if it is supported + * 3) Copy result back to user space. * - * Dependencies: Interface should be running (enforced by caller). + * @param[in] ndev: network device structure + * @param[in] ifr: Interface request structure used for socket ioctl's. * - * Protection: None. + * @note Interface should be running (enforced by caller). * - * Return: 0 - success, negative value - failure. + * @retval 0 on Sucess + * @retval "negative value" on Failure */ int ether_handle_priv_ioctl(struct net_device *ndev, struct ifreq *ifr) diff --git a/drivers/net/ethernet/nvidia/nvethernet/ioctl.h b/drivers/net/ethernet/nvidia/nvethernet/ioctl.h index f027bbb2..0438071e 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ioctl.h +++ b/drivers/net/ethernet/nvidia/nvethernet/ioctl.h @@ -17,6 +17,10 @@ #ifndef IOCTL_H #define IOCTL_H +/** + *@addtogroup IOCTL Helper MACROS + * @{ + */ #define NUM_BYTES_IN_IPADDR 4 #define MAX_IP_ADDR_BYTE 0xFF /* Remote wakeup filter */ @@ -39,67 +43,75 @@ #define ETHER_CONFIG_ARP_OFFLOAD 36 #define ETHER_CONFIG_LOOPBACK_MODE 40 #define ETHER_GET_AVB_ALGORITHM 46 +/** @} */ /** - * struct ether_ifr_data - Private data of struct ifreq - * @flags: Flags used for specific ioctl - like enable/disable - * @qinx: Queue index to be used for certain ioctls. - * Not in use, keep for app compatibility. - * Some applications already use this same struct - * @cmd: The private ioctl command number. - * @context_setup: Used to indicate if context descriptor needs - * to be setup to handle ioctl. - * Not in use, keep for app compatibility. - * @connected_speed: Used to query the connected link speed. - * Not in use, keep for app compatibility. - * @rwk_filter_values: Used to set Remote wakeup filters. - * Not in use, keep for app compatibility. - * @rwk_filter_length: Number of remote wakeup filters to use. - * Not in use, keep for app compatibility. - * @command_error: The return value of IOCTL handler func. - * This is passed back to user space application. - * @test_done: Not in use, keep for app compatibility. - * @ptr: IOCTL cmd specific structure pointer. + * @brief struct ether_ifr_data - Private data of struct ifreq */ struct ether_ifr_data { + /** Flags used for specific ioctl - like enable/disable */ unsigned int if_flags; + /** qinx: Queue index to be used for certain ioctls */ unsigned int qinx; + /** The private ioctl command number */ unsigned int ifcmd; + /** Used to indicate if context descriptor needs to be setup to + * handle ioctl */ unsigned int context_setup; + /** Used to query the connected link speed */ unsigned int connected_speed; + /** Used to set Remote wakeup filters */ unsigned int rwk_filter_values[EQOS_RWK_FILTER_LENGTH]; + /** Number of remote wakeup filters to use */ unsigned int rwk_filter_length; + /** The return value of IOCTL handler func */ int command_error; + /** test_done: Not in use, keep for app compatibility */ int test_done; + /** IOCTL cmd specific structure pointer */ void *ptr; }; /** - * struct arp_offload_param - Parameter to support ARP offload. - * @ip_addr: Byte array for decimal representation of IP address. - * For example, 192.168.1.3 is represented as - * ip_addr[0] = '192' - * ip_addr[1] = '168' - * ip_addr[2] = '1' - * ip_addr[3] = '3' + * @brief struct arp_offload_param - Parameter to support ARP offload. */ struct arp_offload_param { + /** ip_addr: Byte array for decimal representation of IP address. + * For example, 192.168.1.3 is represented as + * ip_addr[0] = '192' ip_addr[1] = '168' ip_addr[2] = '1' + * ip_addr[3] = '3' */ unsigned char ip_addr[NUM_BYTES_IN_IPADDR]; }; /** - * struct ifr_data_timestamp_struct - common data structure between + * @brief struct ifr_data_timestamp_struct - common data structure between * driver and application for sharing info through private TS ioctl - * @clockid: Clock ID - * @kernel_ts: Store kernel time - * @hw_ptp_ts: Store HW time */ struct ifr_data_timestamp_struct { + /** Clock ID */ clockid_t clockid; + /** Store kernel time */ struct timespec kernel_ts; + /** Store HW time */ struct timespec hw_ptp_ts; }; +/** + * @brief ether_priv_ioctl - Handle private IOCTLs + * Algorithm: + * 1) Copy the priv command data from user space. + * 2) Check the priv command cmd and invoke handler func. + * if it is supported. + * 3) Copy result back to user space. + * + * @param[in] ndev: network device structure + * @param[in] ifr: Interface request structure used for socket ioctl's. + * + * @note Interface should be running (enforced by caller). + * + * @retval 0 on success + * @retval negative value on failure. + */ int ether_handle_priv_ioctl(struct net_device *ndev, struct ifreq *ifr); #endif diff --git a/drivers/net/ethernet/nvidia/nvethernet/osd.c b/drivers/net/ethernet/nvidia/nvethernet/osd.c index e34fa333..95798f1b 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/osd.c +++ b/drivers/net/ethernet/nvidia/nvethernet/osd.c @@ -18,16 +18,11 @@ #include /** - * osd_udelay - Adds delay in micro seconds. - * @usec: Delay number in micro seconds. + * @brief Adds delay in micro seconds. * - * Algorithm: Invokes OSD delay function for adding delay + * Algorithm: Invokes OSD delay function for adding delay * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] usec: Delay number in micro seconds. */ void osd_udelay(unsigned long usec) { @@ -35,17 +30,12 @@ void osd_udelay(unsigned long usec) } /** - * osd_usleep_range - Adds sleep in micro seconds - * @umin: Minimum sleep required in micro seconds. - * @umax: Maximum sleep required in micro seconds. + * @brief Adds sleep in micro seconds * - * Algorithm: Invokes OSD function to add sleep. + * Algorithm: Invokes OSD function to add sleep. * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] umin: Minimum sleep required in micro seconds. + * @param[in] umax: Maximum sleep required in micro seconds. */ void osd_usleep_range(unsigned long umin, unsigned long umax) { @@ -53,16 +43,11 @@ void osd_usleep_range(unsigned long umin, unsigned long umax) } /** - * osd_msleep - Adds sleep in milli seconds. - * @msec: Minimum sleep required in milli seconds. + * @brief Adds sleep in milli seconds. * - * Algorithm: Invokes OSD function to add sleep. + * Algorithm: Invokes OSD function to add sleep. * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] msec: Minimum sleep required in milli seconds. */ void osd_msleep(unsigned int msec) { @@ -70,17 +55,12 @@ void osd_msleep(unsigned int msec) } /** - * osd_info - Prints log at INFO log level - * @priv: OSD private data - * @fmt: log format + * @brief Prints log at INFO log level * - * Algorithm: Invokes OSD function to prints the data in kernel log + * Algorithm: Invokes OSD function to prints the data in kernel log * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] priv: OSD private data + * @param[in] fmt: log format */ void osd_info(void *priv, const char *fmt, ...) { @@ -88,17 +68,12 @@ void osd_info(void *priv, const char *fmt, ...) } /** - * osd_err - Prints log at ERR log level - * @priv: OSD private data - * @fmt: log format + * @brief Prints log at ERR log level * - * Algorithm: Invokes OSD function to prints the data in kernel log + * Algorithm: Invokes OSD function to prints the data in kernel log * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] priv: OSD private data + * @param[in] fmt: log format */ void osd_err(void *priv, const char *fmt, ...) { @@ -106,19 +81,17 @@ void osd_err(void *priv, const char *fmt, ...) } /** - * ether_alloc_skb - Allocate and DMA map Rx buffer. - * @pdata: OSD private data structure. - * @rx_swcx: Rx ring software context. - * @dma_rx_buf_len: DMA Rx buffer length. + * @brief Allocate and DMA map Rx buffer. * - * Algorithm: Allocate network buffer (skb) and map skb->data to - * DMA mappable address. + * Algorithm: Allocate network buffer (skb) and map skb->data to + * DMA mappable address. * - * Dependencies: None. + * @param[in] pdata: OSD private data structure. + * @param[in] rx_swcx: Rx ring software context. + * @param[in] dma_rx_buf_len: DMA Rx buffer length. * - * Protection: None. - * - * Return: 0 - success, ENOMEM - failure. + * @retval 0 on Sucess + * @retval ENOMEM on failure. */ static inline int ether_alloc_skb(struct ether_priv_data *pdata, struct osi_rx_swcx *rx_swcx, @@ -148,23 +121,18 @@ static inline int ether_alloc_skb(struct ether_priv_data *pdata, } /** - * ether_realloc_rx_skb - Re-fill DMA channel Rx ring - * @osi: OSI private data structure. - * @rx_ring: DMA channel Rx ring instance. - * @chan: DMA Rx channel number. + * @brief Re-fill DMA channel Rx ring. * - * Algorithm: Re-fill Rx DMA channel ring until dirty rx index is equal to - * current rx index. - * 1) Invokes OSD layer to allocate the buffer and map the buffer to DMA - * mappable address. - * 2) Fill Rx descriptors with required data. - * 3) Program DMA rx channel tail pointer. + * Algorithm: Re-fill Rx DMA channel ring until dirty rx index is equal + * to current rx index. + * 1) Invokes OSD layer to allocate the buffer and map the buffer to DMA + * mappable address. + * 2) Fill Rx descriptors with required data. + * 3) Program DMA rx channel tail pointer. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] pdata: OSD private data structure. + * @param[in] rx_ring: DMA channel Rx ring instance. + * @param[in] chan: DMA Rx channel number. */ static void ether_realloc_rx_skb(struct ether_priv_data *pdata, struct osi_rx_ring *rx_ring, @@ -196,25 +164,22 @@ static void ether_realloc_rx_skb(struct ether_priv_data *pdata, } /** - * osd_receive_packet - Handover received packet to network stack. - * @priv: OSD private data structure. - * @rxring: Pointer to DMA channel Rx ring. - * @chan: DMA Rx channel number. - * @dma_buf_len: Rx DMA buffer length. - * @rx_pkt_len: Received packet length. + * @brief Handover received packet to network stack. * - * Algorithm: - * 1) Unmap the DMA buffer address. - * 2) Updates socket buffer with len and ether type and handover to - * Linux network stack. - * 3) Refill the Rx ring based on threshold. + * Algorithm: + * 1) Unmap the DMA buffer address. + * 2) Updates socket buffer with len and ether type and handover to + * Linux network stack. + * 3) Refill the Rx ring based on threshold. * - * Dependencies: Rx completion need to make sure that Rx descriptors - * processed properly. + * @param[in] priv: OSD private data structure. + * @param[in] rxring: Pointer to DMA channel Rx ring. + * @param[in] chan: DMA Rx channel number. + * @param[in] dma_buf_len: Rx DMA buffer length. + * @param[in] rxpkt_cx: Received packet context. + * @param[in] rx_pkt_swcx: Received packet sw context. * - * Protection: None. - * - * Return: None. + * @note Rx completion need to make sure that Rx descriptors processed properly. */ void osd_receive_packet(void *priv, void *rxring, unsigned int chan, unsigned int dma_buf_len, void *rxpkt_cx, @@ -283,26 +248,22 @@ void osd_receive_packet(void *priv, void *rxring, unsigned int chan, } /** - * osd_transmit_complete - Transmit completion routine. - * @priv: OSD private data structure. - * @buffer: Buffer address to free. - * @dmaaddr: DMA address to unmap. - * @len: Length of data. - * @tx_done_pkt_cx: Pointer to struct which has tx done status info. - * This struct has flags to indicate tx error, whether DMA address - * is mapped from paged/linear buffer. + * @brief osd_transmit_complete - Transmit completion routine. * - * Algorithm: - * 1) Updates stats for linux network stack. - * 2) unmap and free the buffer DMA address and buffer. - * 3) Time stamp will be update to stack if available. + * Algorithm: + * 1) Updates stats for linux network stack. + * 2) unmap and free the buffer DMA address and buffer. + * 3) Time stamp will be update to stack if available. * - * Dependencies: Tx completion need to make sure that Tx descriptors - * processed properly. + * @param[in] priv: OSD private data structure. + * @param[in] buffer: Buffer address to free. + * @param[in] dmaaddr: DMA address to unmap. + * @param[in] len: Length of data. + * @param[in] tx_done_pkt_cx: Pointer to struct which has tx done status info. + * This struct has flags to indicate tx error, whether DMA address + * is mapped from paged/linear buffer. * - * Protection: None. - * - * Return: None. + * @note Tx completion need to make sure that Tx descriptors processed properly. */ void osd_transmit_complete(void *priv, void *buffer, unsigned long dmaaddr, unsigned int len, void *tx_done_pkt_cx) diff --git a/drivers/net/ethernet/nvidia/nvethernet/ptp.c b/drivers/net/ethernet/nvidia/nvethernet/ptp.c index f1eca30b..57ea3a01 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/ptp.c +++ b/drivers/net/ethernet/nvidia/nvethernet/ptp.c @@ -17,14 +17,17 @@ #include "ether_linux.h" #include -/* raw spinlock to get HW PTP time and kernel time atomically */ +/** + * @brief DEFINE_RAW_SPINLOCK: raw spinlock to get HW PTP time and kernel time atomically + * + */ static DEFINE_RAW_SPINLOCK(ether_ts_lock); /** - * ether_get_ptptime get PTP time - * @data: OSI core private data structure + * @brief Function used to get PTP time + * @param[in] data: OSI core private data structure * - * Return: nano seconds + * @retval "nano seconds" of MAC system time */ static inline u64 ether_get_ptptime(void *data) { @@ -50,18 +53,16 @@ static inline u64 ether_get_ptptime(void *data) } /** - * ether_adjust_time: Adjust hardware time - * @ptp: Pointer to ptp_clock_info structure. - * @delta: Desired change in nanoseconds. + * @brief Adjust MAC hardware time * - * Algorithm: This function is used to shift/adjust the time of the - * hardware clock. + * Algorithm: This function is used to shift/adjust the time of the + * hardware clock. * - * Dependencies: + * @param[in] ptp: Pointer to ptp_clock_info structure. + * @param[in] delta: Desired change in nanoseconds. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_adjust_time(struct ptp_clock_info *ptp, s64 delta) { @@ -86,18 +87,16 @@ static int ether_adjust_time(struct ptp_clock_info *ptp, s64 delta) } /** - * ether_adjust_freq: Adjust hardware time - * @ptp: Pointer to ptp_clock_info structure. - * @ppb: Desired period change in parts per billion. + * @brief Adjust MAC hardware frequency * - * Algorithm: This function is used to adjust the frequency of the - * hardware clock. + * Algorithm: This function is used to adjust the frequency of the + * hardware clock. * - * Dependencies: + * @param[in] ptp: Pointer to ptp_clock_info structure. + * @param[in] ppb: Desired period change in parts per billion. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_adjust_freq(struct ptp_clock_info *ptp, s32 ppb) { @@ -122,18 +121,16 @@ static int ether_adjust_freq(struct ptp_clock_info *ptp, s32 ppb) } /** - * ether_get_time: Get current time - * @ptp: Pointer to ptp_clock_info structure. - * @ts: Pointer to hole time. + * @brief Gets current hardware time * - * Algorithm: This function is used to read the current time from the - * hardware clock + * Algorithm: This function is used to read the current time from the + * hardware clock * - * Dependencies: + * @param[in] ptp: Pointer to ptp_clock_info structure. + * @param[in] ts: Pointer to hole time. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_get_time(struct ptp_clock_info *ptp, struct timespec *ts) { @@ -156,18 +153,16 @@ static int ether_get_time(struct ptp_clock_info *ptp, struct timespec *ts) } /** - * ether_set_time: Set current time - * @ptp: Pointer to ptp_clock_info structure. - * @ts: Time value to set. + * @brief Set current system time to MAC Hardware * - * Algorithm: This function is used to set the current time to the - * hardware clock. + * Algorithm: This function is used to set the current time to the + * hardware clock. * - * Dependencies: + * @param[in] ptp: Pointer to ptp_clock_info structure. + * @param[in] ts: Time value to set. * - * Protection: None. - * - * Return: 0 - success, negative value - failure. + * @retval 0 on success + * @retval "negative value" on failure. */ static int ether_set_time(struct ptp_clock_info *ptp, const struct timespec *ts) @@ -192,7 +187,9 @@ static int ether_set_time(struct ptp_clock_info *ptp, return ret; } -/* structure describing a PTP hardware clock */ +/** + * @brief Describing Ethernet PTP hardware clock + */ static struct ptp_clock_info ether_ptp_clock_ops = { .owner = THIS_MODULE, .name = "ether_ptp_clk", @@ -207,20 +204,6 @@ static struct ptp_clock_info ether_ptp_clock_ops = { .settime64 = ether_set_time, }; -/** - * ether_ptp_init: Function to register ptp clock driver. - * @pdata: Pointer to private data structure. - * - * Algorithm: This function is used to register the ptp clock - * driver to kernel. - * - * Dependencies: Ethernet driver probe need to be completed successfully - * with ethernet network device created. - * - * Protection: None. - * - * Return: 0 - success, negative value - failure. - */ int ether_ptp_init(struct ether_priv_data *pdata) { if (pdata->hw_feat.tsstssel == OSI_DISABLE) { @@ -247,19 +230,6 @@ int ether_ptp_init(struct ether_priv_data *pdata) return 0; } -/** - * ether_ptp_remove: Function to de register ptp clock driver. - * @pdata: Pointer to private data structure. - * - * Algorithm: This function is used to de register the ptp clock - * - * Dependencies: PTP clock driver need to be sucessfully registered during - * initialization - * - * Protection: None. - * - * Return: None. - */ void ether_ptp_remove(struct ether_priv_data *pdata) { if (pdata->ptp_clock) { @@ -267,20 +237,6 @@ void ether_ptp_remove(struct ether_priv_data *pdata) } } -/** - * ether_handle_hwtstamp_ioctl: Function to handle PTP settings. - * @pdata: Pointer to private data structure. - * @ifr: Interface request structure used for socket ioctl - * - * Algorithm: This function is used to handle the hardware PTP settings. - * - * Dependencies: PTP clock driver need to be sucessfully registered during - * initialization and HW need to support PTP functionality. - * - * Protection: None. - * - * Return: None. - */ int ether_handle_hwtstamp_ioctl(struct ether_priv_data *pdata, struct ifreq *ifr) { @@ -441,17 +397,19 @@ int ether_handle_hwtstamp_ioctl(struct ether_priv_data *pdata, } /** - * ether_handle_priv_ts_ioctl: Function to handle PTP priv IOCTL - * @pdata: Pointer to private data structure. - * @ifr: Interface request structure used for socket ioctl + * @brief Function to handle PTP private IOCTL * - * Algorithm: This function is used to query hardware time and - * the kernel time simultaneously. + * Algorithm: This function is used to query hardware time and + * the kernel time simultaneously. * - * Dependencies: PTP clock driver need to be successfully registered during + * @param [in] pdata: Pointer to private data structure. + * @param [in] ifr: Interface request structure used for socket ioctl + * + * @note PTP clock driver need to be successfully registered during * initialization and HW need to support PTP functionality. * - * Return: 0 on success, negative value on failure. + * @retval 0 on success. + * @retval "negative value" on failure. */ int ether_handle_priv_ts_ioctl(struct ether_priv_data *pdata, diff --git a/drivers/net/ethernet/nvidia/nvethernet/sysfs.c b/drivers/net/ethernet/nvidia/nvethernet/sysfs.c index 6efd4ae1..389c892d 100644 --- a/drivers/net/ethernet/nvidia/nvethernet/sysfs.c +++ b/drivers/net/ethernet/nvidia/nvethernet/sysfs.c @@ -17,18 +17,15 @@ #include "ether_linux.h" /** - * ether_mac_loopback_show - Shows the current setting of MAC loopback - * @dev: Device data. - * @attr: Device attribute - * @buf: Buffer to store the current MAC loopback setting + * @brief Shows the current setting of MAC loopback * - * Algorithm: Display the current MAC loopback setting. + * Algorithm: Display the current MAC loopback setting. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] dev: Device data. + * @param[in] attr: Device attribute + * @param[in] buf: Buffer to store the current MAC loopback setting * - * Protection: None. - * - * Return: None. + * @note MAC and PHY need to be initialized. */ static ssize_t ether_mac_loopback_show(struct device *dev, struct device_attribute *attr, char *buf) @@ -41,19 +38,18 @@ static ssize_t ether_mac_loopback_show(struct device *dev, } /** - * ether_mac_loopback_store - Set the user setting of MAC loopback mode - * @dev: Device data. - * @attr: Device attribute - * @buf: Buffer which contains the user settings of MAC loopback - * @size: size of buffer + * @brief Set the user setting of MAC loopback mode * - * Algorithm: This is used to set the user mode settings of MAC loopback. + * Algorithm: This is used to set the user mode settings of MAC loopback. * - * Dependencies: MAC and PHY need to be initialized. + * @param[in] dev: Device data. + * @param[in] attr: Device attribute + * @param[in] buf: Buffer which contains the user settings of MAC loopback + * @param[in] size: size of buffer * - * Protection: None. + * @note MAC and PHY need to be initialized. * - * Return: size of buffer. + * @return size of buffer. */ static ssize_t ether_mac_loopback_store(struct device *dev, struct device_attribute *attr, @@ -97,52 +93,36 @@ static ssize_t ether_mac_loopback_store(struct device *dev, return size; } +/** + * @brief Sysfs attribute for MAC loopback + * + */ static DEVICE_ATTR(mac_loopback, (S_IRUGO | S_IWUSR), ether_mac_loopback_show, ether_mac_loopback_store); +/** + * @brief Attributes for nvethernet sysfs + */ static struct attribute *ether_sysfs_attrs[] = { &dev_attr_mac_loopback.attr, NULL }; +/** + * @brief Ethernet sysfs attribute group + */ static struct attribute_group ether_attribute_group = { .name = "nvethernet", .attrs = ether_sysfs_attrs, }; -/** - * ether_sysfs_register - Creates nvethernet sysfs group - * @dev: Net device data. - * - * Algorithm: Creates the sysfs group. - * - * Dependencies: MAC and PHY need to be initialized. - * - * Protection: None. - * - * Return: 0 - success, negative value - failure. - */ - int ether_sysfs_register(struct device *dev) { /* Create nvethernet sysfs group under /sys/devices// */ return sysfs_create_group(&dev->kobj, ðer_attribute_group); } -/** - * ether_sysfs_unregister - Removes nvethernet sysfs group - * @dev: Net device data. - * - * Algorithm: Removes the sysfs group. - * - * Dependencies: nvethernet sysfs group need to be registered during probe. - * - * Protection: None. - * - * Return: None. - */ - void ether_sysfs_unregister(struct device *dev) { /* Remove nvethernet sysfs group under /sys/devices// */