From ae6f4415a9b7374b43e4d4d63bcc5cc1e933ab62 Mon Sep 17 00:00:00 2001 From: Narayan Reddy Date: Tue, 16 Jul 2019 23:08:50 +0530 Subject: [PATCH] nvethernetrm: Update comments with Doxygen style replace kernel doc comments with Doxygen style comments Bug 200512422 Change-Id: I2e8e1f395674ab9e1b66bf40c1f6cc0551608163 Signed-off-by: Narayan Reddy Reviewed-on: https://git-master.nvidia.com/r/2154252 GVS: Gerrit_Virtual_Submit Reviewed-by: Srinivas Ramachandran Reviewed-by: Bitan Biswas Reviewed-by: mobile promotions Tested-by: mobile promotions --- include/mmc.h | 451 ++++++++-------- include/osd.h | 111 ++-- include/osi_common.h | 393 +++++++------- include/osi_core.h | 1099 +++++++++++++++++++-------------------- include/osi_dma.h | 646 ++++++++++++----------- include/osi_dma_txrx.h | 43 +- osi/common/osi_common.c | 11 - osi/core/eqos_core.c | 1005 ++++++++++++++++------------------- osi/core/eqos_core.h | 104 +++- osi/core/eqos_mmc.c | 49 +- osi/core/eqos_mmc.h | 31 ++ osi/core/osi_core.c | 50 +- osi/dma/eqos_dma.c | 355 ++++++------- osi/dma/eqos_dma.h | 33 +- osi/dma/osi_dma.c | 14 - osi/dma/osi_dma_txrx.c | 269 +++------- 16 files changed, 2258 insertions(+), 2406 deletions(-) diff --git a/include/mmc.h b/include/mmc.h index d75d096..3d064ad 100644 --- a/include/mmc.h +++ b/include/mmc.h @@ -23,362 +23,333 @@ #ifndef MMC_H #define MMC_H /** - * osi_mmc_counters - The structure to hold RMON counter values - * - * mmc_tx_octetcount_gb: This counter provides the number of bytes - * transmitted, exclusive of preamble and retried bytes, in good and - * bad packets. - * mmc_tx_framecount_gb: This counter provides the number of good and - * bad packets transmitted, exclusive of retried packets. - * mmc_tx_broadcastframe_g: This counter provides the number of good - * broadcast packets transmitted - * mmc_tx_multicastframe_g: This counter provides the number of good - * multicast packets transmitted - * mmc_tx_64_octets_gb: This counter provides the number of good and bad - * packets transmitted with length 64 bytes, exclusive of preamble and - * retried packets - * mmc_tx_65_to_127_octets_gb: This counter provides the number of good - * and bad packets transmitted with length 65-127 bytes, exclusive of - * preamble and retried packets - * mmc_tx_128_to_255_octets_gb: This counter provides the number of good - * and bad packets transmitted with length 128-255 bytes, exclusive of - * preamble and retried packets - * mmc_tx_256_to_511_octets_gb: This counter provides the number of good - * and bad packets transmitted with length 256-511 bytes, exclusive of - * preamble and retried packets - * mmc_tx_512_to_1023_octets_gb: This counter provides the number of good - * and bad packets transmitted with length 512-1023 bytes, exclusive of - * preamble and retried packets - * mmc_tx_1024_to_max_octets_gb: This counter provides the number of good - * and bad packets transmitted with length 1024-max bytes, exclusive of - * preamble and retried packets - * mmc_tx_unicast_gb: This counter provides the number of good and bad - * unicast packets - * mmc_tx_multicast_gb: This counter provides the number of good and bad - * multicast packets - * mmc_tx_broadcast_gb: This counter provides the number of good and bad - * braodcast packets - * mmc_tx_underflow_error: This counter provides the number of abort - * packets due to underflow error - * mmc_tx_singlecol_g: This counter provides the number of successfully - * transmitted packets after a single collision in the half-duplex mode - * mmc_tx_multicol_g: This counter provides the number of successfully - * transmitted packets after a multiple collision in the half-duplex mode - * mmc_tx_deferred: This counter provides the number of successfully - * transmitted after a deferral in the half-duplex mode - * mmc_tx_latecol: This counter provides the number of packets aborted - * because of late collision error - * mmc_tx_exesscol: This counter provides the number of packets aborted - * because of excessive (16) collision errors - * mmc_tx_carrier_error: This counter provides the number of packets - * aborted because of carrier sense error (no carrier or loss of carrier) - * mmc_tx_octetcount_g: This counter provides the number of bytes - * transmitted, exclusive of preamble, only in good packets. - * mmc_tx_framecount_g: This counter provides the number of good packets - * transmitted . - * mmc_tx_excessdef: This counter provides the number of packets aborted - * because of excessive deferral error (deferred for more than two - * max-sized packet times). - * mmc_tx_pause_frame: This counter provides the number of good Pause - * packets transmitted. - * mmc_tx_vlan_frame_g: This counter provides the number of good - * VLAN packets transmitted - * mmc_tx_osize_frame_g: This counter provides the number of packets - * transmitted without errors and with length greater than the maxsize - * (1,518 or 1,522 bytes for VLAN tagged packets; 2000 bytes. - * mmc_rx_framecount_gb: This counter provides the number of good and bad - * packets received - * mmc_rx_octetcount_gb: This counter provides the number of bytes - * received by DWC_ther_qos, exclusive of preamble, in good and bad packets - * mmc_rx_octetcount_g: This counter provides the number of bytes - * received by DWC_ther_qos, exclusive of preamble, in good and bad packets - * mmc_rx_broadcastframe_g: This counter provides the number of good - * broadcast packets received - * mmc_rx_multicastframe_g: This counter provides the number of good - * multicast packets received - * mmc_rx_crc_error: This counter provides the number of packets received - * with CRC error - * mmc_rx_align_error: This counter provides the number of packets - * received with alignment (dribble) error. It is valid only in 10/100 - * mode. - * mmc_rx_runt_error: This counter provides the number of packets - * received with runt (length less than 64 bytes and CRC error) error - * mmc_rx_jabber_error: This counter provides the number of giant packets - * received with length (including CRC) greater than 1,518 bytes - * (1,522 bytes for VLAN tagged) and with CRC error. - * mmc_rx_undersize_g: This counter provides the number of packets - * received with length less than 64 bytes, without any errors - * mmc_rx_oversize_g: This counter provides the number of packets - * received without errors, with length greater than the maxsize - * mmc_rx_64_octets_gb: This counter provides the number of good and bad - * packets received with length 64 bytes, exclusive of the preamble. - * mmc_rx_65_to_127_octets_gb: This counter provides the number of good - * and bad packets received with length 65-127 bytes, exclusive of the - * preamble. - * mmc_rx_128_to_255_octets_gb: This counter provides the number of good - * and bad packets received with length 128-255 bytes, exclusive of the - * preamble. - * mmc_rx_256_to_511_octets_gb: This counter provides the number of good - * and bad packets received with length 256-511 bytes, exclusive of the - * preamble. - * mmc_rx_512_to_1023_octets_gb: This counter provides the number of good - * and bad packets received with length 512-1023 bytes, exclusive of the - * preamble. - * mmc_rx_1024_to_max_octets_gb: This counter provides the number of good - * and bad packets received with length 1024-max bytes, exclusive of the - * preamble. - * mmc_rx_unicast_g: This counter provides the number of good unicast - * packets received mmc_rx_length_error: This counter provides the - * number of packets received with length error (Length Type field - * not equal to packet size), for all packets with valid length field. - * mmc_rx_outofrangetype: This counter provides the number of packets - * received with length field not equal to the - * valid packet size (greater than 1,500 but less than 1,536). - * mmc_rx_pause_frames: This counter provides the number of good and - * valid Pause packets received - * mmc_rx_fifo_overflow: This counter provides the number of missed - * received packets because of FIFO overflow in DWC_ether_qos - * mmc_rx_vlan_frames_gb: This counter provides the number of good and - * bad VLAN packets received - * mmc_rx_watchdog_error: This counter provides the number of packets - * received with error because of watchdog timeout error - * mmc_rx_receive_error: This counter provides the number of packets - * received with Receive error or Packet Extension error on the GMII or - * MII interface - * mmc_rx_ctrl_frames_g: This counter provides the number of packets - * received with Receive error or Packet Extension error on the GMII - * or MII interface - * mmc_rx_ipv4_gd: This counter provides the number of good IPv4 - * datagrams received with the TCP, UDP, or ICMP payload - * mmc_rx_ipv4_hderr: RxIPv4 Header Error Packets - * mmc_rx_ipv4_nopay: This counter provides the number of IPv4 datagram - * packets received that did not have a TCP, UDP, or ICMP payload - * mmc_rx_ipv4_frag: This counter provides the number of good IPv4 - * datagrams received with fragmentation. - * mmc_rx_ipv4_udsbl: This counter provides the number of good IPv4 - * datagrams received that had a UDP payload with checksum disabled - * mmc_rx_ipv6_gd_octets: This counter provides the number of good IPv6 - * datagrams received with the TCP, UDP, or ICMP payload - * mmc_rx_ipv6_hderr_octets: This counter provides the number of IPv6 - * datagrams received with header (length or version mismatch) errors - * mmc_rx_ipv6_nopay_octets: This counter provides the number of IPv6 - * datagram packets received that did not have a TCP, UDP, or ICMP - * payload - * mmc_rx_udp_gd: This counter provides the number of good IP datagrams - * received by DWC_ether_qos with a good UDP payload. - * mmc_rx_udp_err: This counter provides the number of good IP datagrams - * received by DWC_ether_qos with a good UDP payload. This counter is not - * updated when the RxIPv4_UDP_Checksum_Disabled_Packets counter is - * incremented. - * mmc_rx_tcp_gd: This counter provides the number of good IP datagrams - * received with a good TCP payload - * mmc_rx_tcp_err: This counter provides the number of good IP datagrams - * received with a good TCP payload - * mmc_rx_icmp_gd: This counter provides the number of good IP datagrams - * received with a good ICMP payload - * mmc_rx_icmp_err: This counter provides the number of good IP - * datagrams received whose ICMP payload has a checksum error - * mmc_rx_ipv4_gd_octets: This counter provides the number of bytes - * received by DWC_ether_qos in good IPv4 datagrams encapsulating TCP, - * UDP, or ICMP data. (Ethernet header, FCS, pad, or IP pad bytes are - * not included in this counter - * mmc_rx_ipv4_hderr_octets: This counter provides the number of bytes - * received in IPv4 datagrams with header errors (checksum, length, - * version mismatch). The value in the Length field of IPv4 header is - * used to update this counter. (Ethernet header, FCS, pad, - * or IP pad bytes are not included in this counter - * mmc_rx_ipv4_nopay_octets: This counter provides the number of bytes - * received in IPv4 datagrams that did not have a TCP, UDP, or - * ICMP payload. The value in the Length field of IPv4 header is used - * to update this counter. (Ethernet header, FCS, pad, or IP pad bytes - * are not included in this counter. - * mmc_rx_ipv4_frag_octets: This counter provides the number of bytes - * received in fragmented IPv4 datagrams. The value in the Length - * field of IPv4 header is used to update this counter. (Ethernet header, - * FCS, pad, or IP pad bytes are not included in this counter - * mmc_rx_ipv4_udsbl_octets: This counter provides the number of bytes - * received in a UDP segment that had the UDP checksum disabled. This - * counter does not count IP Header bytes. (Ethernet header, FCS, pad, - * or IP pad bytes are not included in this counter. - * mmc_rx_ipv6_gd: This counter provides the number of bytes received - * in good IPv6 datagrams encapsulating TCP, UDP, or ICMP data. - * (Ethernet header, FCS, pad, or IP pad bytes are not included in - * this counter - * mmc_rx_ipv6_hderr: This counter provides the number of bytes received - * in IPv6 datagrams with header errors (length, version mismatch). The - * value in the Length field of IPv6 header is used to update this - * counter. (Ethernet header, FCS, pad, or IP pad bytes are not included - * in this counter. - * mmc_rx_ipv6_nopay: This counter provides the number of bytes received - * in IPv6 datagrams that did not have a TCP, UDP, or ICMP payload. The - * value in the Length field of IPv6 header is used to update this - * counter. (Ethernet header, FCS, pad, or IP pad bytes are not included - * in this counter - * mmc_rx_udp_gd_octets: This counter provides the number of bytes - * received in a good UDP segment. This counter does not count IP header - * bytes. - * mmc_rx_udp_err_octets: This counter provides the number of bytes - * received in a UDP segment that had checksum errors. This counter - * does not count IP header bytes - * mmc_rx_tcp_gd_octets: This counter provides the number of bytes - * received in a good TCP segment. This counter does not count IP - * header bytes - * mmc_rx_tcp_err_octets: This counter provides the number of bytes - * received in a TCP segment that had checksum errors. This counter - * does not count IP header bytes - * mmc_rx_icmp_gd_octets: This counter provides the number of bytes - * received in a good ICMP segment. This counter does not count - * IP header bytes - * mmc_rx_icmp_err_octets: This counter provides the number of bytes - * received in a ICMP segment that had checksum errors. - * This counter does not count IP header bytes + * @brief osi_mmc_counters - The structure to hold RMON counter values */ struct osi_mmc_counters { - /* MMC TX counters */ + /** This counter provides the number of bytes transmitted, exclusive of + * preamble and retried bytes, in good and bad packets */ unsigned long mmc_tx_octetcount_gb; + /** This counter provides the number of good and + * bad packets transmitted, exclusive of retried packets */ unsigned long mmc_tx_framecount_gb; + /** This counter provides number of good broadcast + * packets transmitted */ unsigned long mmc_tx_broadcastframe_g; + /** This counter provides number of good multicast + * packets transmitted */ unsigned long mmc_tx_multicastframe_g; + /** This counter provides the number of good and bad packets + * transmitted with length 64 bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_64_octets_gb; + /** This counter provides the number of good and bad packets + * transmitted with length 65-127 bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_65_to_127_octets_gb; + /** This counter provides the number of good and bad packets + * transmitted with length 128-255 bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_128_to_255_octets_gb; + /** This counter provides the number of good and bad packets + * transmitted with length 256-511 bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_256_to_511_octets_gb; + /** This counter provides the number of good and bad packets + * transmitted with length 512-1023 bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_512_to_1023_octets_gb; + /** This counter provides the number of good and bad packets + * transmitted with length 1024-max bytes, exclusive of preamble and + * retried packets */ unsigned long mmc_tx_1024_to_max_octets_gb; + /** This counter provides the number of good and bad unicast packets */ unsigned long mmc_tx_unicast_gb; + /** This counter provides the number of good and bad + * multicast packets */ unsigned long mmc_tx_multicast_gb; + /** This counter provides the number of good and bad + * broadcast packets */ unsigned long mmc_tx_broadcast_gb; + /** mmc_tx_underflow_error: This counter provides the number of abort + * packets due to underflow error */ unsigned long mmc_tx_underflow_error; + /** This counter provides the number of successfully transmitted + * packets after a single collision in the half-duplex mode */ unsigned long mmc_tx_singlecol_g; + /** This counter provides the number of successfully transmitted + * packets after a multi collision in the half-duplex mode */ unsigned long mmc_tx_multicol_g; + /** This counter provides the number of successfully transmitted + * after a deferral in the half-duplex mode */ unsigned long mmc_tx_deferred; + /** This counter provides the number of packets aborted because of + * late collision error */ unsigned long mmc_tx_latecol; + /** This counter provides the number of packets aborted because of + * excessive (16) collision errors */ unsigned long mmc_tx_exesscol; + /** This counter provides the number of packets aborted because of + * carrier sense error (no carrier or loss of carrier) */ unsigned long mmc_tx_carrier_error; + /** This counter provides the number of bytes transmitted, + * exclusive of preamble, only in good packets */ unsigned long mmc_tx_octetcount_g; + /** This counter provides the number of good packets transmitted */ unsigned long mmc_tx_framecount_g; + /** This counter provides the number of packets aborted because of + * excessive deferral error + * (deferred for more than two max-sized packet times) */ unsigned long mmc_tx_excessdef; + /** This counter provides the number of good Pause + * packets transmitted */ unsigned long mmc_tx_pause_frame; + /** This counter provides the number of good VLAN packets transmitted */ unsigned long mmc_tx_vlan_frame_g; + /** This counter provides the number of packets transmitted without + * errors and with length greater than the maxsize (1,518 or 1,522 bytes + * for VLAN tagged packets; 2000 bytes */ unsigned long mmc_tx_osize_frame_g; - - /* MMC RX counters */ + /** This counter provides the number of good and bad packets received */ unsigned long mmc_rx_framecount_gb; + /** This counter provides the number of bytes received by DWC_ther_qos, + * exclusive of preamble, in good and bad packets */ unsigned long mmc_rx_octetcount_gb; + /** This counter provides the number of bytes received by DWC_ther_qos, + * exclusive of preamble, in good and bad packets */ unsigned long mmc_rx_octetcount_g; + /** This counter provides the number of good + * broadcast packets received */ unsigned long mmc_rx_broadcastframe_g; + /** This counter provides the number of good + * multicast packets received */ unsigned long mmc_rx_multicastframe_g; + /** This counter provides the number of packets + * received with CRC error */ unsigned long mmc_rx_crc_error; + /** This counter provides the number of packets received with + * alignment (dribble) error. It is valid only in 10/100 mode */ unsigned long mmc_rx_align_error; + /** This counter provides the number of packets received with + * runt (length less than 64 bytes and CRC error) error */ unsigned long mmc_rx_runt_error; + /** This counter provides the number of giant packets received with + * length (including CRC) greater than 1,518 bytes (1,522 bytes for + * VLAN tagged) and with CRC error */ unsigned long mmc_rx_jabber_error; + /** This counter provides the number of packets received with length + * less than 64 bytes, without any errors */ unsigned long mmc_rx_undersize_g; + /** This counter provides the number of packets received without error, + * with length greater than the maxsize */ unsigned long mmc_rx_oversize_g; + /** This counter provides the number of good and bad packets received + * with length 64 bytes, exclusive of the preamble */ unsigned long mmc_rx_64_octets_gb; + /** This counter provides the number of good and bad packets received + * with length 65-127 bytes, exclusive of the preamble */ unsigned long mmc_rx_65_to_127_octets_gb; + /** This counter provides the number of good and bad packets received + * with length 128-255 bytes, exclusive of the preamble */ unsigned long mmc_rx_128_to_255_octets_gb; + /** This counter provides the number of good and bad packets received + * with length 256-511 bytes, exclusive of the preamble */ unsigned long mmc_rx_256_to_511_octets_gb; + /** This counter provides the number of good and bad packets received + * with length 512-1023 bytes, exclusive of the preamble */ unsigned long mmc_rx_512_to_1023_octets_gb; + /** This counter provides the number of good and bad packets received + * with length 1024-maxbytes, exclusive of the preamble */ unsigned long mmc_rx_1024_to_max_octets_gb; + /** This counter provides the number of good unicast packets received */ unsigned long mmc_rx_unicast_g; + /** This counter provides the number of packets received with length + * error (Length Type field not equal to packet size), for all packets + * with valid length field */ unsigned long mmc_rx_length_error; + /** This counter provides the number of packets received with length + * field not equal to the valid packet size (greater than 1,500 but + * less than 1,536) */ unsigned long mmc_rx_outofrangetype; + /** This counter provides the number of good and valid Pause packets + * received */ unsigned long mmc_rx_pause_frames; + /** This counter provides the number of missed received packets + * because of FIFO overflow in DWC_ether_qos */ unsigned long mmc_rx_fifo_overflow; + /** This counter provides the number of good and bad VLAN packets + * received */ unsigned long mmc_rx_vlan_frames_gb; + /** This counter provides the number of packets received with error + * because of watchdog timeout error */ unsigned long mmc_rx_watchdog_error; + /** This counter provides the number of packets received with Receive + * error or Packet Extension error on the GMII or MII interface */ unsigned long mmc_rx_receive_error; + /** This counter provides the number of packets received with Receive + * error or Packet Extension error on the GMII or MII interface */ unsigned long mmc_rx_ctrl_frames_g; - /* IPv4 */ + /** This counter provides the number of good IPv4 datagrams received + * with the TCP, UDP, or ICMP payload */ unsigned long mmc_rx_ipv4_gd; + /** RxIPv4 Header Error Packets */ unsigned long mmc_rx_ipv4_hderr; + /** This counter provides the number of IPv4 datagram packets received + * that did not have a TCP, UDP, or ICMP payload */ unsigned long mmc_rx_ipv4_nopay; + /** This counter provides the number of good IPv4 datagrams received + * with fragmentation */ unsigned long mmc_rx_ipv4_frag; + /** This counter provides the number of good IPv4 datagrams received + * that had a UDP payload with checksum disabled */ unsigned long mmc_rx_ipv4_udsbl; - /* IPV6 */ + /** This counter provides the number of good IPv6 datagrams received + * with the TCP, UDP, or ICMP payload */ unsigned long mmc_rx_ipv6_gd_octets; + /** This counter provides the number of IPv6 datagrams received + * with header (length or version mismatch) errors */ unsigned long mmc_rx_ipv6_hderr_octets; + /** This counter provides the number of IPv6 datagram packets received + * that did not have a TCP, UDP, or ICMP payload */ unsigned long mmc_rx_ipv6_nopay_octets; - /* Protocols */ + /** This counter provides the number of good IP datagrams received by + * DWC_ether_qos with a good UDP payload */ unsigned long mmc_rx_udp_gd; + /** This counter provides the number of good IP datagrams received by + * DWC_ether_qos with a good UDP payload. This counter is not updated + * when the RxIPv4_UDP_Checksum_Disabled_Packets counter is + * incremented */ unsigned long mmc_rx_udp_err; + /** This counter provides the number of good IP datagrams received + * with a good TCP payload */ unsigned long mmc_rx_tcp_gd; + /** This counter provides the number of good IP datagrams received + * with a good TCP payload */ unsigned long mmc_rx_tcp_err; + /** This counter provides the number of good IP datagrams received + * with a good ICMP payload */ unsigned long mmc_rx_icmp_gd; + /** This counter provides the number of good IP datagrams received + * whose ICMP payload has a checksum error */ unsigned long mmc_rx_icmp_err; - /* IPv4 */ + /** This counter provides the number of bytes received by DWC_ether_qos + * in good IPv4 datagrams encapsulating TCP, UDP, or ICMP data. + * (Ethernet header, FCS, pad, or IP pad bytes are not included + * in this counter */ unsigned long mmc_rx_ipv4_gd_octets; + /** This counter provides the number of bytes received in IPv4 datagram + * with header errors (checksum, length, version mismatch). The value + * in the Length field of IPv4 header is used to update this counter. + * (Ethernet header, FCS, pad, or IP pad bytes are not included + * in this counter */ unsigned long mmc_rx_ipv4_hderr_octets; + /** This counter provides the number of bytes received in IPv4 datagram + * that did not have a TCP, UDP, or ICMP payload. The value in the + * Length field of IPv4 header is used to update this counter. + * (Ethernet header, FCS, pad, or IP pad bytes are not included + * in this counter */ unsigned long mmc_rx_ipv4_nopay_octets; + /** This counter provides the number of bytes received in fragmented + * IPv4 datagrams. The value in the Length field of IPv4 header is + * used to update this counter. (Ethernet header, FCS, pad, or IP pad + * bytes are not included in this counter */ unsigned long mmc_rx_ipv4_frag_octets; + /** This counter provides the number of bytes received in a UDP segment + * that had the UDP checksum disabled. This counter does not count IP + * Header bytes. (Ethernet header, FCS, pad, or IP pad bytes are not + * included in this counter */ unsigned long mmc_rx_ipv4_udsbl_octets; - - /* IPV6 */ + /** This counter provides the number of bytes received in good IPv6 + * datagrams encapsulating TCP, UDP, or ICMP data. (Ethernet header, + * FCS, pad, or IP pad bytes are not included in this counter */ unsigned long mmc_rx_ipv6_gd; + /** This counter provides the number of bytes received in IPv6 datagrams + * with header errors (length, version mismatch). The value in the + * Length field of IPv6 header is used to update this counter. + * (Ethernet header, FCS, pad, or IP pad bytes are not included in + * this counter */ unsigned long mmc_rx_ipv6_hderr; + /** This counter provides the number of bytes received in IPv6 + * datagrams that did not have a TCP, UDP, or ICMP payload. The value + * in the Length field of IPv6 header is used to update this counter. + * (Ethernet header, FCS, pad, or IP pad bytes are not included + * in this counter */ unsigned long mmc_rx_ipv6_nopay; /* Protocols */ + /** This counter provides the number of bytes received in a good UDP + * segment. This counter does not count IP header bytes */ unsigned long mmc_rx_udp_gd_octets; + /** This counter provides the number of bytes received in a UDP + * segment that had checksum errors. This counter does not count + * IP header bytes */ unsigned long mmc_rx_udp_err_octets; + /** This counter provides the number of bytes received in a good + * TCP segment. This counter does not count IP header bytes */ unsigned long mmc_rx_tcp_gd_octets; + /** This counter provides the number of bytes received in a TCP + * segment that had checksum errors. This counter does not count + * IP header bytes */ unsigned long mmc_rx_tcp_err_octets; + /** This counter provides the number of bytes received in a good + * ICMP segment. This counter does not count IP header bytes */ unsigned long mmc_rx_icmp_gd_octets; + /** This counter provides the number of bytes received in a ICMP + * segment that had checksum errors. This counter does not count + * IP header bytes */ unsigned long mmc_rx_icmp_err_octets; }; /** - * osi_xtra_stat_counters - OSI core extra stat counters - * - * rx_buf_unavail_irq_n: RX buffer unavailable irq count - * tx_proc_stopped_irq_n: Transmit Process Stopped irq count - * tx_buf_unavail_irq_n: Transmit Buffer Unavailable irq count - * rx_proc_stopped_irq_n: Receive Process Stopped irq count - * rx_watchdog_irq_n: Receive Watchdog Timeout irq count - * fatal_bus_error_irq_n: Fatal Bus Error irq count - * q_re_alloc_rx_buf_failed: rx sbk allocation failure count - * tx_normal_irq_n: TX per channel interrupt count - * rx_normal_irq_n: RX per cannel interrupt count - * link_connect_count: link disconnect count - * link_disconnect_count: link connect count + * @brief osi_xtra_stat_counters - OSI core extra stat counters */ struct osi_xtra_stat_counters { + /** RX buffer unavailable irq count */ unsigned long rx_buf_unavail_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Transmit Process Stopped irq count */ unsigned long tx_proc_stopped_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Transmit Buffer Unavailable irq count */ unsigned long tx_buf_unavail_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Receive Process Stopped irq count */ unsigned long rx_proc_stopped_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Receive Watchdog Timeout irq count */ unsigned long rx_watchdog_irq_n; + /** Fatal Bus Error irq count */ unsigned long fatal_bus_error_irq_n; + /** rx skb allocation failure count */ unsigned long re_alloc_rxbuf_failed[OSI_EQOS_MAX_NUM_QUEUES]; + /** TX per channel interrupt count */ unsigned long tx_normal_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** RX per channel interrupt count */ unsigned long rx_normal_irq_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** link connect count */ unsigned long link_connect_count; + /** link disconnect count */ unsigned long link_disconnect_count; }; /** - * osi_xtra_dma_stat_counters - OSI dma extra stats counters - * q_tx_pkt_n: Per Q TX packet count - * q_rx_pkt_n: Per Q RX packet count - * tx_clean_n: Per Q TX complete call count - * tx_pkt_n: Total number of tx packets count - * rx_pkt_n: Total number of rx packet count - * rx_vlan_pkt_n: Total number of VLAN RX packet count - * tx_vlan_pkt_n: Total number of VLAN TX packet count - * tx_tso_pkt_n: Total number of TSO packet count + * @brief osi_xtra_dma_stat_counters - OSI DMA extra stats counters */ struct osi_xtra_dma_stat_counters { + /** Per Q TX packet count */ unsigned long q_tx_pkt_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Per Q RX packet count */ unsigned long q_rx_pkt_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Per Q TX complete call count */ unsigned long tx_clean_n[OSI_EQOS_MAX_NUM_QUEUES]; + /** Total number of tx packets count */ unsigned long tx_pkt_n; + /** Total number of rx packet count */ unsigned long rx_pkt_n; + /** Total number of VLAN RX packet count */ unsigned long rx_vlan_pkt_n; + /** Total number of VLAN TX packet count */ unsigned long tx_vlan_pkt_n; + /** Total number of TSO packet count */ unsigned long tx_tso_pkt_n; }; diff --git a/include/osd.h b/include/osd.h index f216e5d..beb70fe 100644 --- a/include/osd.h +++ b/include/osd.h @@ -23,70 +23,91 @@ #ifndef OSD_H #define OSD_H +/** + * @brief osd_usleep_range - sleep in micro seconds + * + * @param[in] umin: Minimum time in usecs to sleep + * @param[in] umax: Maximum time in usecs to sleep + */ void osd_usleep_range(unsigned long umin, unsigned long umax); +/** + * @brief osd_msleep - sleep in milli seconds + * + * @param[in] msec: time in milli seconds + */ void osd_msleep(unsigned int msec); +/** + * @brief osd_udelay - delay in micro seconds + * + * @param[in] usec: time in usec + */ void osd_udelay(unsigned long usec); +/** + * @brief osd_info - logging function + * + * @param[in] priv: OSD private data + * @param[in] fmt: fragments + */ void osd_info(void *priv, const char *fmt, ...); + +/** + * @brief osd_err - logging function + * + * @param[in] priv: OSD private data + * @param[in] fmt: fragments + */ void osd_err(void *priv, const char *fmt, ...); /** - * 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. - * @rxpkt_cx: Received packet context. - * @rx_pkt_swcx: Received packet sw context. + * @brief osd_receive_packet - 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 - * OS network stack. - * 3) Refill the Rx ring based on threshold. - * 4) Fills the rxpkt_cx->flags with the below bit fields accordingly - * OSI_PKT_CX_VLAN - * OSI_PKT_CX_VALID - * OSI_PKT_CX_CSUM - * OSI_PKT_CX_TSO - * OSI_PKT_CX_PTP + * Algorithm: + * 1) Unmap the DMA buffer address. + * 2) Updates socket buffer with len and ether type and handover to + * OS network stack. + * 3) Refill the Rx ring based on threshold. + * 4) Fills the rxpkt_cx->flags with the below bit fields accordingly + * OSI_PKT_CX_VLAN + * OSI_PKT_CX_VALID + * OSI_PKT_CX_CSUM + * OSI_PKT_CX_TSO + * OSI_PKT_CX_PTP * - * 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, void *rx_pkt_swcx); /** - * 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, Time stamp availability, - * if TS available txdone_pkt_cx->ns stores the time stamp. - * Below are the valid bit maps set for txdone_pkt_cx->flags - * #define OSI_TXDONE_CX_PAGED_BUF OSI_BIT(0) - * #define OSI_TXDONE_CX_ERROR OSI_BIT(1) - * #define OSI_TXDONE_CX_TS OSI_BIT(2) + * @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 updated 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 updated 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] txdone_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, Time stamp availability, + * if TS available txdone_pkt_cx->ns stores the time stamp. + * Below are the valid bit maps set for txdone_pkt_cx->flags + * OSI_TXDONE_CX_PAGED_BUF OSI_BIT(0) + * OSI_TXDONE_CX_ERROR OSI_BIT(1) + * OSI_TXDONE_CX_TS OSI_BIT(2) * - * 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 *txdone_pkt_cx); diff --git a/include/osi_common.h b/include/osi_common.h index 0ff3b42..b926b4b 100644 --- a/include/osi_common.h +++ b/include/osi_common.h @@ -23,9 +23,12 @@ #ifndef OSI_COMMON_H #define OSI_COMMON_H +/** + * @addtogroup EQOS-Helper Helper MACROS + * @{ + */ #define OSI_UNLOCKED 0x0U #define OSI_LOCKED 0x1U - #define TEN_POWER_9 0x3B9ACA00U #define TWO_POWER_32 0x100000000ULL #define TWO_POWER_31 0x80000000U @@ -143,7 +146,14 @@ #define H32(data) (((data) & 0xFFFFFFFF00000000UL) >> 32UL) #define OSI_INVALID_CHAN_NUM 0xFFU +/** @} */ +/** + * @addtogroup EQOS-MAC EQOS MAC HW supported features + * + * @brief Helps in identifying the features that are set in MAC HW + * @{ + */ #define EQOS_MAC_HFR0 0x11c #define EQOS_MAC_HFR1 0x120 #define EQOS_MAC_HFR2 0x124 @@ -185,195 +195,184 @@ #define EQOS_MAC_HFR2_TXCHCNT_MASK 0xfU #define EQOS_MAC_HFR2_PPSOUTNUM_MASK 0x7U #define EQOS_MAC_HFR2_AUXSNAPNUM_MASK 0x7U +/** @} */ /** - * struct osi_hw_features - MAC HW supported features. - * @mii_sel: It sets to 1 when 10/100 Mbps is selected as the Mode of - * Operation - * @gmii_sel: It sets to 1 when 1000 Mbps is selected as the Mode of - * Operation. - * @hd_sel: It sets to 1 when the half-duplex mode is selected. - * @pcs_sel: It sets to 1 when the TBI, SGMII, or RTBI PHY interface - * option is selected. - * @vlan_hash_en: It sets to 1 when the Enable VLAN Hash Table Based - * Filtering option is selected. - * @sma_sel: It sets to 1 when the Enable Station Management - * (MDIO Interface) option is selected. - * @rwk_sel: It sets to 1 when the Enable Remote Wake-Up Packet Detection - * option is selected. - * @mgk_sel: It sets to 1 when the Enable Magic Packet Detection option is - * selected. - * @mmc_sel: It sets to 1 when the Enable MAC Management Counters (MMC) - * option is selected. - * @arp_offld_en: It sets to 1 when the Enable IPv4 ARP Offload option is - * selected. - * @ts_sel: It sets to 1 when the Enable IEEE 1588 Timestamp Support - * option is selected. - * @eee_sel: It sets to 1 when the Enable Energy Efficient Ethernet (EEE) - * option is selected. - * @tx_coe_sel: It sets to 1 when the Enable Transmit TCP/IP Checksum - * Insertion option is selected. - * @rx_coe_sel: It sets to 1 when the Enable Receive TCP/IP Checksum Check - * option is selected. - * @mac_addr16_sel: It sets to 1 when the Enable Additional 1-31 MAC - * Address Registers option is selected. - * @mac_addr32_sel: It sets to 1 when the Enable Additional 32 MAC - * Address Registers (32-63) option is selected - * @mac_addr64_sel: It sets to 1 when the Enable Additional 64 MAC - * Address Registers (64-127) option is selected. - * @tsstssel: It sets to 1 when the Enable IEEE 1588 Timestamp Support - * option is selected. - * @sa_vlan_ins: It sets to 1 when the Enable SA and VLAN Insertion on Tx - * option is selected. - * @act_phy_sel: Active PHY Selected - * When you have multiple PHY interfaces in your configuration, - * this field indicates the sampled value of phy_intf_sel_i during - * reset de-assertion: - * 000: GMII or MII - * 001: RGMII - * 010: SGMII - * 011: TBI - * 100: RMII - * 101: RTBI - * 110: SMII - * 111: RevMII - * All Others: Reserved. - * @rx_fifo_size: MTL Receive FIFO Size - * This field contains the configured value of MTL Rx FIFO in - * bytes expressed as Log to base 2 minus 7, that is, - * Log2(RXFIFO_SIZE) -7: - * 00000: 128 bytes - * 00001: 256 bytes - * 00010: 512 bytes - * 00011: 1,024 bytes - * 00100: 2,048 bytes - * 00101: 4,096 bytes - * 00110: 8,192 bytes - * 00111: 16,384 bytes - * 01000: 32,767 bytes - * 01000: 32 KB - * 01001: 64 KB - * 01010: 128 KB - * 01011: 256 KB - * 01100-11111: Reserved. - * @tx_fifo_size: MTL Transmit FIFO Size. - * This field contains the configured value of MTL Tx FIFO in - * bytes expressed as Log to base 2 minus 7, that is, - * Log2(TXFIFO_SIZE) -7: - * 00000: 128 bytes - * 00001: 256 bytes - * 00010: 512 bytes - * 00011: 1,024 bytes - * 00100: 2,048 bytes - * 00101: 4,096 bytes - * 00110: 8,192 bytes - * 00111: 16,384 bytes - * 01000: 32 KB - * 01001: 64 KB - * 01010: 128 KB - * 01011-11111: Reserved. - * @adv_ts_hword: It set to 1 when Advance timestamping High Word selected. - * @addr_64: Address Width. - * This field indicates the configured address width: - * 00: 32 - * 01: 40 - * 10: 48 - * 11: Reserved - * @dcb_en: It sets to 1 when DCB Feature Enable. - * @sph_en: It sets to 1 when Split Header Feature Enable. - * @tso_en: It sets to 1 when TCP Segmentation Offload Enable. - * @dma_debug_gen: It seys to 1 when DMA debug registers are enabled. - * @av_sel: It sets to 1 AV Feature Enabled. - * @hash_tbl_sz: This field indicates the size of the hash table: - * 00: No hash table - * 01: 64 - * 10: 128 - * 11: 256. - * @l3l4_filter_num: This field indicates the total number of L3 or L4 - * filters: - * 0000: No L3 or L4 Filter - * 0001: 1 L3 or L4 Filter - * 0010: 2 L3 or L4 Filters - * .. - * 1000: 8 L3 or L4. - * @rx_q_cnt: It holds number of MTL Receive Queues. - * @tx_q_cnt: It holds number of MTL Transmit Queues. - * @rx_ch_cnt: It holds number of DMA Receive channels. - * @tx_ch_cnt: This field indicates the number of DMA Transmit channels: - * 0000: 1 DMA Tx Channel - * 0001: 2 DMA Tx Channels - * .. - * 0111: 8 DMA Tx. - * @pps_out_num: This field indicates the number of PPS outputs: - * 000: No PPS output - * 001: 1 PPS output - * 010: 2 PPS outputs - * 011: 3 PPS outputs - * 100: 4 PPS outputs - * 101-111: Reserved - * @aux_snap_num: Number of Auxiliary Snapshot Inputs - * This field indicates the number of auxiliary snapshot inputs: - * 000: No auxiliary input - * 001: 1 auxiliary input - * 010: 2 auxiliary inputs - * 011: 3 auxiliary inputs - * 100: 4 auxiliary inputs - * 101-111: Reserved + * @brief struct osi_hw_features - MAC HW supported features. */ struct osi_hw_features { - /* HW Feature Register0 */ + /** It is set to 1 when 10/100 Mbps is selected as the Mode of + * Operation */ unsigned int mii_sel; + /** It sets to 1 when 1000 Mbps is selected as the Mode of Operation */ unsigned int gmii_sel; + /** It sets to 1 when the half-duplex mode is selected */ unsigned int hd_sel; + /** It sets to 1 when the TBI, SGMII, or RTBI PHY interface + * option is selected */ unsigned int pcs_sel; + /** It sets to 1 when the Enable VLAN Hash Table Based Filtering + * option is selected */ unsigned int vlan_hash_en; + /** It sets to 1 when the Enable Station Management (MDIO Interface) + * option is selected */ unsigned int sma_sel; + /** It sets to 1 when the Enable Remote Wake-Up Packet Detection + * option is selected */ unsigned int rwk_sel; + /** It sets to 1 when the Enable Magic Packet Detection option is + * selected */ unsigned int mgk_sel; + /** It sets to 1 when the Enable MAC Management Counters (MMC) option + * is selected */ unsigned int mmc_sel; + /** It sets to 1 when the Enable IPv4 ARP Offload option is selected */ unsigned int arp_offld_en; + /** It sets to 1 when the Enable IEEE 1588 Timestamp Support option + * is selected */ unsigned int ts_sel; + /** It sets to 1 when the Enable Energy Efficient Ethernet (EEE) option + * is selected */ unsigned int eee_sel; + /** It sets to 1 when the Enable Transmit TCP/IP Checksum Insertion + * option is selected */ unsigned int tx_coe_sel; + /** It sets to 1 when the Enable Receive TCP/IP Checksum Check option + * is selected */ unsigned int rx_coe_sel; + /** It sets to 1 when the Enable Additional 1-31 MAC Address Registers + * option is selected */ unsigned int mac_addr16_sel; + /** It sets to 1 when the Enable Additional 32-63 MAC Address Registers + * option is selected */ unsigned int mac_addr32_sel; + /** It sets to 1 when the Enable Additional 64-127 MAC Address Registers + * option is selected */ unsigned int mac_addr64_sel; + /** It sets to 1 when the Enable IEEE 1588 Timestamp Support option + * is selected */ unsigned int tsstssel; + /** It sets to 1 when the Enable SA and VLAN Insertion on Tx option + * is selected */ unsigned int sa_vlan_ins; + /** Active PHY Selected + * When you have multiple PHY interfaces in your configuration, + * this field indicates the sampled value of phy_intf_sel_i during + * reset de-assertion: + * 000: GMII or MII + * 001: RGMII + * 010: SGMII + * 011: TBI + * 100: RMII + * 101: RTBI + * 110: SMII + * 111: RevMII + * All Others: Reserved */ unsigned int act_phy_sel; - /* HW Feature Register1 */ + /** MTL Receive FIFO Size + * This field contains the configured value of MTL Rx FIFO in bytes + * expressed as Log to base 2 minus 7, that is, Log2(RXFIFO_SIZE) -7: + * 00000: 128 bytes + * 00001: 256 bytes + * 00010: 512 bytes + * 00011: 1,024 bytes + * 00100: 2,048 bytes + * 00101: 4,096 bytes + * 00110: 8,192 bytes + * 00111: 16,384 bytes + * 01000: 32,767 bytes + * 01000: 32 KB + * 01001: 64 KB + * 01010: 128 KB + * 01011: 256 KB + * 01100-11111: Reserved */ unsigned int rx_fifo_size; + /** MTL Transmit FIFO Size. + * This field contains the configured value of MTL Tx FIFO in + * bytes expressed as Log to base 2 minus 7, that is, + * Log2(TXFIFO_SIZE) -7: + * 00000: 128 bytes + * 00001: 256 bytes + * 00010: 512 bytes + * 00011: 1,024 bytes + * 00100: 2,048 bytes + * 00101: 4,096 bytes + * 00110: 8,192 bytes + * 00111: 16,384 bytes + * 01000: 32 KB + * 01001: 64 KB + * 01010: 128 KB + * 01011-11111: Reserved */ unsigned int tx_fifo_size; + /** It set to 1 when Advance timestamping High Word selected */ unsigned int adv_ts_hword; + /** Address Width. + * This field indicates the configured address width: + * 00: 32 + * 01: 40 + * 10: 48 + * 11: Reserved */ unsigned int addr_64; + /** It sets to 1 when DCB Feature Enable */ unsigned int dcb_en; + /** It sets to 1 when Split Header Feature Enable */ unsigned int sph_en; + /** It sets to 1 when TCP Segmentation Offload Enable */ unsigned int tso_en; + /** It sets to 1 when DMA debug registers are enabled */ unsigned int dma_debug_gen; + /** It sets to 1 if AV Feature Enabled */ unsigned int av_sel; + /** This field indicates the size of the hash table: + * 00: No hash table + * 01: 64 + * 10: 128 + * 11: 256 */ unsigned int hash_tbl_sz; + /** This field indicates the total number of L3 or L4 filters: + * 0000: No L3 or L4 Filter + * 0001: 1 L3 or L4 Filter + * 0010: 2 L3 or L4 Filters + * .. + * 1000: 8 L3 or L4 */ unsigned int l3l4_filter_num; - /* HW Feature Register2 */ + /** It holds number of MTL Receive Queues */ unsigned int rx_q_cnt; + /** It holds number of MTL Transmit Queues */ unsigned int tx_q_cnt; + /** It holds number of DMA Receive channels */ unsigned int rx_ch_cnt; + /** This field indicates the number of DMA Transmit channels: + * 0000: 1 DMA Tx Channel + * 0001: 2 DMA Tx Channels + * .. + * 0111: 8 DMA Tx */ unsigned int tx_ch_cnt; + /** This field indicates the number of PPS outputs: + * 000: No PPS output + * 001: 1 PPS output + * 010: 2 PPS outputs + * 011: 3 PPS outputs + * 100: 4 PPS outputs + * 101-111: Reserved */ unsigned int pps_out_num; + /** Number of Auxiliary Snapshot Inputs + * This field indicates the number of auxiliary snapshot inputs: + * 000: No auxiliary input + * 001: 1 auxiliary input + * 010: 2 auxiliary inputs + * 011: 3 auxiliary inputs + * 100: 4 auxiliary inputs + * 101-111: Reserved */ unsigned int aux_snap_num; }; /** - * osi_lock_init - Initialize lock to unlocked state. - * @lock - Pointer to lock to be initialized + * @brief osi_lock_init - Initialize lock to unlocked state. * - * Algorithm: Set lock to unlocked state. + * Algorithm: Set lock to unlocked state. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] lock - Pointer to lock to be initialized */ static inline void osi_lock_init(unsigned int *lock) { @@ -381,17 +380,14 @@ static inline void osi_lock_init(unsigned int *lock) } /** - * osi_lock_irq_enabled - Spin lock. Busy loop till lock is acquired. - * @lock - Pointer to lock to be acquired. + * @brief osi_lock_irq_enabled - Spin lock. Busy loop till lock is acquired. * - * Algorithm: Atomic compare and swap operation till lock is held. + * Algorithm: Atomic compare and swap operation till lock is held. * - * Dependencies: Does not disable irq. Do not call this API to acquire any + * @param[in] lock - Pointer to lock to be acquired. + * + * @note Does not disable irq. Do not call this API to acquire any * lock that is shared between top/bottom half. It will result in deadlock. - * - * Protection: None. - * - * Return: None. */ static inline void osi_lock_irq_enabled(unsigned int *lock) { @@ -407,17 +403,14 @@ static inline void osi_lock_irq_enabled(unsigned int *lock) } /** - * osi_unlock_irq_enabled - Release lock. - * @lock - Pointer to lock to be released. + * @brief osi_unlock_irq_enabled - Release lock. * - * Algorithm: Atomic compare and swap operation to release lock. + * Algorithm: Atomic compare and swap operation to release lock. * - * Dependencies: Does not disable irq. Do not call this API to release any + * @param[in] lock - Pointer to lock to be released. + * + * @note Does not disable irq. Do not call this API to release any * lock that is shared between top/bottom half. - * - * Protection: None. - * - * Return: None. */ static inline void osi_unlock_irq_enabled(unsigned int *lock) { @@ -428,16 +421,13 @@ static inline void osi_unlock_irq_enabled(unsigned int *lock) } /** - * osi_readl - Read a memory mapped regsiter. - * @addr: Memory mapped address. + * @brief osi_readl - Read a memory mapped register. * - * Algorithm: None. + * @param[in] addr: Memory mapped address. * - * Dependencies: Physical address has to be memmory mapped. + * @note Physical address has to be memmory mapped. * - * Protection: None. - * - * Return: Data from memory mapped register - success. + * @return Data from memory mapped register - success. */ static inline unsigned int osi_readl(void *addr) { @@ -445,17 +435,12 @@ static inline unsigned int osi_readl(void *addr) } /** - * osi_writel - Write to a memory mapped regsiter. - * @val: Value to be written. - * @addr: Memory mapped address. + * @brief osi_writel - Write to a memory mapped register. * - * Algorithm: None. + * @param[in] val: Value to be written. + * @param[in] addr: Memory mapped address. * - * Dependencies: Physical address has to be memmory mapped. - * - * Protection: None. - * - * Return: None. + * @note Physical address has to be memmory mapped. */ static inline void osi_writel(unsigned int val, void *addr) { @@ -463,16 +448,14 @@ static inline void osi_writel(unsigned int val, void *addr) } /** - * is_valid_mac_version - Check if read MAC IP is valid or not. - * @mac_ver: MAC version read. + * @brief is_valid_mac_version - Check if read MAC IP is valid or not. * - * Algorithm: None. + * @param[in] mac_ver: MAC version read. * - * Dependencies: MAC has to be out of reset. + * @note MAC has to be out of reset. * - * Protection: None. - * - * Return: 0 - for not Valid MAC, 1 - for Valid MAC + * @retval 0 - for not Valid MAC + * @retval 1 - for Valid MAC */ static inline int is_valid_mac_version(unsigned int mac_ver) { @@ -486,17 +469,17 @@ static inline int is_valid_mac_version(unsigned int mac_ver) } /** - * osi_update_stats_counter - update value by increment passed as parameter - * @last_value: last value of stat counter - * @incr: increment value + * @brief osi_update_stats_counter - update value by increment passed + * as parameter * - * Algorithm: Check for boundary and return sum + * Algorithm: Check for boundary and return sum * - * Dependencies: Input parameter should be only unsigned long type + * @param[in] last_value: last value of stat counter + * @param[in] incr: increment value * - * Protection: None + * @note Input parameter should be only unsigned long type * - * Return: unsigned long value + * @return unsigned long value */ static inline unsigned long osi_update_stats_counter(unsigned long last_value, unsigned long incr) @@ -515,20 +498,36 @@ static inline unsigned long osi_update_stats_counter(unsigned long last_value, } /** - * osi_get_mac_version - Reading MAC version - * @addr: io-remap MAC base address. - * @mac_ver: holds mac version. + * @brief osi_get_mac_version - Reading MAC version * - * Algorithm: Reads MAC version and check whether its valid or not. + * Algorithm: Reads MAC version and check whether its valid or not. * - * Dependencies: MAC has to be out of reset. + * @param[in] addr: io-remap MAC base address. + * @param[in] mac_ver: holds mac version. * - * Protection: None + * @note MAC has to be out of reset. * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_get_mac_version(void *addr, unsigned int *mac_ver); +/** + * @brief osi_get_hw_features - Reading MAC HW features + * + * @param[in] base: io-remap MAC base address. + * @param[in] hw_feat: holds the supported features of the hardware. + * + * @note MAC has to be out of reset. + */ void osi_get_hw_features(void *base, struct osi_hw_features *hw_feat); +/** + * @brief osi_memset - osi memset + * + * @param[in] s: source that need to be set + * @param[in] c: value to fill in source + * @param[in] count: first n bytes of source + * + */ void osi_memset(void *s, unsigned int c, unsigned long count); #endif /* OSI_COMMON_H */ diff --git a/include/osi_core.h b/include/osi_core.h index c2e899d..c9e8b70 100644 --- a/include/osi_core.h +++ b/include/osi_core.h @@ -29,179 +29,170 @@ struct osi_core_priv_data; /** - * struct osi_filter - The OSI core structure for filters - * @pr_mode: promiscuous mode - * @huc_mode: hash unicast - * @hmc_mode: hash milticast - * @pm_mode: pass all multicast - * @hpf_mode: hash or perfact filter + * @brief OSI core structure for filters */ struct osi_filter { + /** promiscuous mode enable(1) or disable(0) */ unsigned int pr_mode; + /** hash unicast enable(1) or disable(0) */ unsigned int huc_mode; + /** hash multicast enable(1) or disable(0) */ unsigned int hmc_mode; + /** pass all multicast enable(1) or disable(0) */ unsigned int pm_mode; + /** 0x0 (DISABLE): Hash or Perfect Filter is disabled + * + * 0x1 (ENABLE): Hash or Perfect Filter is enabled */ unsigned int hpf_mode; }; /** - * Structure osi_l3_l4_filter - L3/L4 filter Function dependent - * parameter - * - * @filter_no: filter index 0- 7 - * @filter_enb_dis: enable/disable - * @src_dst_addr_match: source(0) or destination(1) - * @perfect_inverse_match: perfect(0) or inverse(1) - * @ip4_addr: ipv4 address - * @ip6_addr: ipv6 address - * @port_no: Port number + * @brief L3/L4 filter function dependent parameter */ struct osi_l3_l4_filter { + /** Indicates the index of the filter to be modified. + * Filter index must be between 0 - 7 */ unsigned int filter_no; + /** filter enable(1) or disable(0) */ unsigned int filter_enb_dis; + /** source(0) or destination(1) */ unsigned int src_dst_addr_match; + /** perfect(0) or inverse(1) */ unsigned int perfect_inverse_match; + /** ipv4 address */ unsigned char ip4_addr[4]; + /** ipv6 address */ unsigned short ip6_addr[8]; + /** Port number */ unsigned short port_no; }; /** - * Structure osi_vlan_filter - Vlan filter Function dependent parameter - * - * @filter_enb_dis: enable/disable - * @perfect_hash: perfect(0) or hash(1) - * @perfect_inverse_match: perfect(0) or inverse(1) + * @brief Vlan filter Function dependent parameter */ struct osi_vlan_filter { + /** vlan filter enable(1) or disable(0) */ unsigned int filter_enb_dis; + /** perfect(0) or hash(1) */ unsigned int perfect_hash; + /** perfect(0) or inverse(1) */ unsigned int perfect_inverse_match; }; /** - * Struct osi_l2_da_filter - L2 filter function depedent parameter - * @perfect_hash: perfect(0) or hash(1) - * @perfect_inverse_match: perfect(0) or inverse(1) + * @brief L2 filter function dependent parameter */ struct osi_l2_da_filter { + /** perfect(0) or hash(1) */ unsigned int perfect_hash; + /** perfect(0) or inverse(1) */ unsigned int perfect_inverse_match; }; /** - * struct osi_core_avb_algorithm - The OSI Core avb data structure per - * queue. - * @qindex: TX Queue/TC index - * @algo: AVB algorithm 1:CBS - * @credit_control: credit control When this bit is set, the accumulated - * credit. Parameter in the credit-based shaper algorithm logic is not - * reset to zero when there is positive credit and no packet to transmit - * in Channel - * @idle_slope: idleSlopeCredit value required for CBS - * @send_slope: sendSlopeCredit value required for CBS - * @hi_credit: hiCredit value required for CBS - * @low_credit: lowCredit value required for CBS - * @oper_mode: Transmit queue enable 01: avb 10: enable 00: disable + * @brief OSI Core avb data structure per queue. */ struct osi_core_avb_algorithm { + /** TX Queue/TC index */ unsigned int qindex; + /** CBS Algorithm enable(1) or disable(0) */ unsigned int algo; + /** When this bit is set, the accumulated credit parameter in the + * credit-based shaper algorithm logic is not reset to zero when + * there is positive credit and no packet to transmit in Channel. + * + * Expected values are enable(1) or disable(0) */ unsigned int credit_control; - unsigned int idle_slope; + /** idleSlopeCredit value required for CBS */ + unsigned int idle_slope; + /** sendSlopeCredit value required for CBS */ unsigned int send_slope; + /** hiCredit value required for CBS */ unsigned int hi_credit; + /** lowCredit value required for CBS */ unsigned int low_credit; + /** Transmit queue operating mode + * + * 00: disable + * + * 01: avb + * + * 10: enable */ unsigned int oper_mode; }; /** - * struct osi_core_ops - Core (MAC & MTL) operations. - * @poll_for_swr: Called to poll for software reset bit. - * @core_init: Called to initialize MAC and MTL registers. - * @core_deinit: Called to deinitialize MAC and MTL registers. - * @validate_regs: Called periodically to read and validate safety critical - * registers against last written value. - * @start_mac: Called to start MAC Tx and Rx engine. - * @stop_mac: Called to stop MAC Tx and Rx engine. - * @handle_common_intr: Called to handle common interrupt. - * @set_mode: Called to set the mode at MAC (full/duplex). - * @set_speed: Called to set the speed (10/100/1000) at MAC. - * @pad_calibrate: Called to do pad caliberation. - * @set_mdc_clk_rate: Called to set MDC clock rate for MDIO operation. - * @flush_mtl_tx_queue: Called to flush MTL Tx queue. - * @config_mac_loopback: Called to configure MAC in loopback mode. - * @set_avb_algorithm: Called to set av parameter. - * @get_avb_algorithm: Called to get av parameter, - * @config_fw_err_pkts: Called to configure MTL RxQ to forward the err pkt. - * @config_tx_status: Called to configure the MTL to forward/drop tx status - * @config_rx_crc_check: Called to configure the MAC rx crc. - * @config_flow_control: Called to configure the MAC flow control. - * @config_arp_offload: Called to enable/disable HW ARP offload feature. - * @config_rxcsum_offload: Called to configure Rx Checksum offload engine. - * @config_mac_pkt_filter_reg: Called to config mac packet filter. - * @update_mac_addr_low_high_reg: Called to update MAC address 1-127. - * @config_l3_l4_filter_enable: Called to configure l3/L4 filter. - * @config_l2_da_perfect_inverse_match: Called to configure L2 DA filter. - * @config_l3_filters: Called to configure L3 filter. - * @update_ip4_addr: Called to update ip4 src or desc address. - * @update_ip6_addr: Called to update ip6 address. - * @config_l4_filters: Called to configure L4 filter. - * @update_l4_port_no: Called to update L4 Port for filter packet. - * @config_vlan_filtering: Called to configure VLAN filtering. - * @update_vlan_id: called to update VLAN id. - * @set_systime_to_mac: Called to set current system time to MAC. - * @config_addend: Called to set the addend value to adjust the time. - * @adjust_systime: Called to adjust the system time. - * @get_systime_from_mac: Called to get the current time from MAC. - * @config_tscr: Called to configure the TimeStampControl register. - * @config_ssir: Called to configure the sub second increment register. - * @read_mmc: called to update MMC counter from HW register - * @reset_mmc: called to reset MMC HW counter and Structure + * @brief Initialize MAC & MTL core operations. */ struct osi_core_ops { - /* initialize MAC/MTL/DMA Common registers */ + /** Called to poll for software reset bit */ int (*poll_for_swr)(void *ioaddr); + /** Called to initialize MAC and MTL registers */ int (*core_init)(struct osi_core_priv_data *osi_core, unsigned int tx_fifo_size, unsigned int rx_fifo_size); + /** Called to deinitialize MAC and MTL registers */ void (*core_deinit)(struct osi_core_priv_data *osi_core); + /** Called periodically to read and validate safety critical + * registers against last written value */ int (*validate_regs)(struct osi_core_priv_data *osi_core); + /** Called to start MAC Tx and Rx engine */ void (*start_mac)(void *addr); + /** Called to stop MAC Tx and Rx engine */ void (*stop_mac)(void *addr); + /** Called to handle common interrupt */ void (*handle_common_intr)(struct osi_core_priv_data *osi_core); + /** Called to set the mode at MAC (full/duplex) */ void (*set_mode)(void *ioaddr, int mode); + /** Called to set the speed (10/100/1000) at MAC */ void (*set_speed)(void *ioaddr, int speed); + /** Called to do pad caliberation */ int (*pad_calibrate)(void *ioaddr); + /** Called to set MDC clock rate for MDIO operation */ void (*set_mdc_clk_rate)(struct osi_core_priv_data *osi_core, unsigned long csr_clk_rate); + /** Called to flush MTL Tx queue */ int (*flush_mtl_tx_queue)(void *ioaddr, unsigned int qinx); + /** Called to configure MAC in loopback mode */ int (*config_mac_loopback)(void *addr, unsigned int lb_mode); + /** Called to set av parameter */ int (*set_avb_algorithm)(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb); + /** Called to get av parameter */ int (*get_avb_algorithm)(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb); + /** Called to configure MTL RxQ to forward the err pkt */ int (*config_fw_err_pkts)(void *addr, unsigned int qinx, unsigned int fw_err); + /** Called to configure the MTL to forward/drop tx status */ int (*config_tx_status)(void *addr, unsigned int tx_status); + /** Called to configure the MAC rx crc */ int (*config_rx_crc_check)(void *addr, unsigned int crc_chk); + /** Called to configure the MAC flow control */ int (*config_flow_control)(void *addr, unsigned int flw_ctrl); + /** Called to enable/disable HW ARP offload feature */ int (*config_arp_offload)(unsigned int mac_ver, void *addr, unsigned int enable, unsigned char *ip_addr); + /** Called to configure Rx Checksum offload engine */ int (*config_rxcsum_offload)(void *addr, unsigned int enabled); + /** Called to config mac packet filter */ void (*config_mac_pkt_filter_reg)(struct osi_core_priv_data *osi_core, struct osi_filter filter); + /** Called to update MAC address 1-127 */ int (*update_mac_addr_low_high_reg)( - struct osi_core_priv_data *osi_core, + struct osi_core_priv_data *osi_core, unsigned int index, unsigned char value[], unsigned int dma_routing_enable, unsigned int dma_chan, unsigned int addr_mask, unsigned int src_dest); + /** Called to configure l3/L4 filter */ int (*config_l3_l4_filter_enable)(void *base, unsigned int enable); + /** Called to configure L2 DA filter */ int (*config_l2_da_perfect_inverse_match)(void *base, unsigned int perfect_inverse_match); + /** Called to configure L3 filter */ int (*config_l3_filters)(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned int enb_dis, unsigned int ipv4_ipv6_match, @@ -209,11 +200,14 @@ struct osi_core_ops { unsigned int perfect_inverse_match, unsigned int dma_routing_enable, unsigned int dma_chan); + /** Called to update ip4 src or desc address */ int (*update_ip4_addr)(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned char addr[], unsigned int src_dst_addr_match); + /** Called to update ip6 address */ int (*update_ip6_addr)(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned short addr[]); + /** Called to configure L4 filter */ int (*config_l4_filters)(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned int enb_dis, unsigned int tcp_udp_match, @@ -221,527 +215,543 @@ struct osi_core_ops { unsigned int perfect_inverse_match, unsigned int dma_routing_enable, unsigned int dma_chan); + /** Called to update L4 Port for filter packet */ int (*update_l4_port_no)(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned short port_no, unsigned int src_dst_port_match); - /* for VLAN filtering */ - int (*config_vlan_filtering)(struct osi_core_priv_data *osi_core, - unsigned int filter_enb_dis, - unsigned int perfect_hash_filtering, - unsigned int perfect_inverse_match); + /** Called to configure VLAN filtering */ + int (*config_vlan_filtering)(struct osi_core_priv_data *osi_core, + unsigned int filter_enb_dis, + unsigned int perfect_hash_filtering, + unsigned int perfect_inverse_match); + /** called to update VLAN id */ int (*update_vlan_id)(void *base, unsigned int vid); + /** Called to set current system time to MAC */ int (*set_systime_to_mac)(void *addr, unsigned int sec, unsigned int nsec); + /** Called to set the addend value to adjust the time */ int (*config_addend)(void *addr, unsigned int addend); + /** Called to adjust the system time */ int (*adjust_systime)(void *addr, unsigned int sec, unsigned int nsec, unsigned int neg_adj, unsigned int one_nsec_accuracy); + /** Called to get the current time from MAC */ unsigned long long (*get_systime_from_mac)(void *addr); + /** Called to configure the TimeStampControl register */ void (*config_tscr)(void *addr, unsigned int ptp_filter); + /** Called to configure the sub second increment register */ void (*config_ssir)(void *addr, unsigned int ptp_clock); + /** Called to update MMC counter from HW register */ void (*read_mmc)(struct osi_core_priv_data *osi_core); + /** Called to reset MMC HW counter structure */ void (*reset_mmc)(struct osi_core_priv_data *osi_core); }; /** - * struct osi_ptp_config - PTP configuration - * @ptp_filter: PTP filter parameters bit fields. - * Enable Time stamp,Fine Timestamp,1 nanosecond accuracy are enabled by - * default. - * Need to set below bit fields accordingly as per the requirements. - * Enable Timestamp for All Packets OSI_BIT(8) - * Enable PTP Packet Processing for Version 2 Format OSI_BIT(10) - * Enable Processing of PTP over Ethernet Packets OSI_BIT(11) - * Enable Processing of PTP Packets Sent over IPv6-UDP OSI_BIT(12) - * Enable Processing of PTP Packets Sent over IPv4-UDP OSI_BIT(13) - * Enable Timestamp Snapshot for Event Messages OSI_BIT(14) - * Enable Snapshot for Messages Relevant to Master OSI_BIT(15) - * Select PTP packets for Taking Snapshots OSI_BIT(16) - * Select PTP packets for Taking Snapshots OSI_BIT(17) - * Select PTP packets for Taking Snapshots (OSI_BIT(16) | OSI_BIT(17)) - * AV 802.1AS Mode Enable OSI_BIT(28) - * if ptp_fitler is set to Zero then Time stamping is disabled. - * @sec: Seconds - * @nsec: Nano seconds - * @ptp_ref_clk_rate: PTP reference clock read from DT - * @one_nsec_accuracy: Use one nsec accuracy (need to set 1) - * @ptp_clock: PTP system clock which is 62500000Hz + * @brief PTP configuration structure */ struct osi_ptp_config { + /** PTP filter parameters bit fields. + * + * Enable Time stamp,Fine Timestamp,1 nanosecond accuracy + * are enabled by default. + * + * Need to set below bit fields accordingly as per the requirements. + * + * Enable Timestamp for All Packets OSI_BIT(8) + * + * Enable PTP Packet Processing for Version 2 Format OSI_BIT(10) + * + * Enable Processing of PTP over Ethernet Packets OSI_BIT(11) + * + * Enable Processing of PTP Packets Sent over IPv6-UDP OSI_BIT(12) + * + * Enable Processing of PTP Packets Sent over IPv4-UDP OSI_BIT(13) + * + * Enable Timestamp Snapshot for Event Messages OSI_BIT(14) + * + * Enable Snapshot for Messages Relevant to Master OSI_BIT(15) + * + * Select PTP packets for Taking Snapshots OSI_BIT(16) + * + * Select PTP packets for Taking Snapshots OSI_BIT(17) + * + * Select PTP packets for Taking Snapshots (OSI_BIT(16) + OSI_BIT(17)) + * + * AV 802.1AS Mode Enable OSI_BIT(28) + * + * if ptp_fitler is set to Zero then Time stamping is disabled */ unsigned int ptp_filter; + /** seconds to be updated to MAC */ unsigned int sec; + /** nano seconds to be updated to MAC */ unsigned int nsec; + /** PTP reference clock read from DT */ unsigned int ptp_ref_clk_rate; + /** Use one nsec accuracy (need to set 1) */ unsigned int one_nsec_accuracy; + /** PTP system clock which is 62500000Hz */ unsigned int ptp_clock; }; /** - * struct osi_core_priv_data - The OSI Core (MAC & MTL) private data - structure. - * @base: Memory mapped base address of MAC IP. - * @osd: Pointer to OSD private data structure. - * @ops: Address of HW Core operations structure. - * @num_mtl_queues: Number of MTL queues enabled in MAC. - * @mtl_queues: Array of MTL queues. - * @rxq_ctrl: List of MTL Rx queue mode that need to be enabled - * @rxq_prio: Rx MTl Queue mapping based on User Priority field - * @mac: MAC HW type EQOS based on DT compatible. - * @mac_ver: MAC version. - * @mdc_cr: MDC clock rate. - * @mtu: MTU size - * @mac_addr: Ethernet MAC address. - * @pause_frames: DT entry to enable(0) or disable(1) pause frame support - * @flow_ctrl: Current flow control settings - * @ptp_config: PTP configuration settings. - * @default_addend: Default addend value. - * @mmc: mmc counter structure - * @xstats: xtra sw error counters - * @dcs_en: DMA channel selection enable (1) - * @safety_config: Functional safety config to do periodic read-verify of - * certain safety critical registers. + * @brief The OSI Core (MAC & MTL) private data structure. */ struct osi_core_priv_data { + /** Memory mapped base address of MAC IP */ void *base; + /** Pointer to OSD private data structure */ void *osd; + /** Address of HW Core operations structure */ struct osi_core_ops *ops; + /** Number of MTL queues enabled in MAC */ unsigned int num_mtl_queues; - unsigned int mtl_queues[OSI_EQOS_MAX_NUM_QUEUES]; - unsigned int rxq_ctrl[OSI_EQOS_MAX_NUM_QUEUES]; - unsigned int rxq_prio[OSI_EQOS_MAX_NUM_QUEUES]; + /** Array of MTL queues */ + unsigned int mtl_queues[OSI_EQOS_MAX_NUM_CHANS]; + /** List of MTL Rx queue mode that need to be enabled */ + unsigned int rxq_ctrl[OSI_EQOS_MAX_NUM_CHANS]; + /** Rx MTl Queue mapping based on User Priority field */ + unsigned int rxq_prio[OSI_EQOS_MAX_NUM_CHANS]; + /** MAC HW type EQOS based on DT compatible */ unsigned int mac; + /** MAC version */ unsigned int mac_ver; + /** MDC clock rate */ unsigned int mdc_cr; + /** MTU size */ unsigned int mtu; + /** Ethernet MAC address */ unsigned char mac_addr[OSI_ETH_ALEN]; + /** DT entry to enable(0) or disable(1) pause frame support */ unsigned int pause_frames; + /** Current flow control settings */ unsigned int flow_ctrl; + /** PTP configuration settings */ struct osi_ptp_config ptp_config; + /** Default addend value */ unsigned int default_addend; + /** mmc counter structure */ struct osi_mmc_counters mmc; + /** xtra sw error counters */ struct osi_xtra_stat_counters xstats; + /** DMA channel selection enable (1) */ unsigned int dcs_en; + /** Functional safety config to do periodic read-verify of + * certain safety critical registers */ void *safety_config; }; /** - * osi_poll_for_swr - Poll Software reset bit in MAC HW - * @osi: OSI Core private data structure. + * @brief osi_poll_for_swr - Poll Software reset bit in MAC HW * - * Algorithm: Invokes EQOS routine to check for SWR (software reset) - * bit in DMA Basic mooe register to make sure IP reset was successful. + * Algorithm: Invokes EQOS routine to check for SWR (software reset) + * bit in DMA Basic mode register to make sure IP reset was successful. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clock configured. + * @param[in] osi_core: OSI Core private data structure. * - * Protection: None + * @note MAC needs to be out of reset and proper clock configured. * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_poll_for_swr(struct osi_core_priv_data *osi_core); /** - * osi_set_mdc_clk_rate - Derive MDC clock based on provided AXI_CBB clk. - * @osi: OSI core private data structure. - * @csr_clk_rate: CSR (AXI CBB) clock rate. + * @brief osi_set_mdc_clk_rate - Derive MDC clock based on provided AXI_CBB clk. * - * Algorithm: MDC clock rate will be populated in OSI core private data - * structure based on AXI_CBB clock rate. + * Algorithm: MDC clock rate will be populated in OSI core private data + * structure based on AXI_CBB clock rate. * - * Dependencies: - * 1) OSD layer needs get the AXI CBB clock rate with OSD clock API + * @param[in] osi_core: OSI core private data structure. + * @param[in] csr_clk_rate: CSR (AXI CBB) clock rate. + * + * @note OSD layer needs get the AXI CBB clock rate with OSD clock API * (ex - clk_get_rate()) * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_mdc_clk_rate(struct osi_core_priv_data *osi_core, unsigned long csr_clk_rate); /** - * osi_hw_core_init - EQOS MAC, MTL and common DMA initialization. - * @osi: OSI core private data structure. + * @brief osi_hw_core_init - EQOS MAC, MTL and common DMA initialization. + * + * Algorithm: Invokes EQOS MAC, MTL and common DMA register init code. * - * Algorithm: Invokes EQOS MAC, MTL and common DMA register init code. + * @param[in] osi_core: OSI core private data structure. + * @param[in] tx_fifo_size: OSI core private data structure. + * @param[in] rx_fifo_size: OSI core private data structure. * - * Dependencies: - * 1) MAC should be out of reset. See osi_poll_for_swr() for details. - * 2) osi_core->base needs to be filled based on ioremap. - * 3) osi_core->num_mtl_queues needs to be filled. - * 4) osi_core->mtl_queues[qinx] need to be filled. + * @note + * 1) MAC should be out of reset. See osi_poll_for_swr() for details. + * 2) osi_core->base needs to be filled based on ioremap. + * 3) osi_core->num_mtl_queues needs to be filled. + * 4)osi_core->mtl_queues[qinx] need to be filled. * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_hw_core_init(struct osi_core_priv_data *osi_core, unsigned int tx_fifo_size, unsigned int rx_fifo_size); /** - * osi_hw_core_deinit - EQOS MAC deinitialization. - * @osi: OSI core private data structure. + * @brief osi_hw_core_deinit - EQOS MAC deinitialization. + * + * Algorithm: Stops MAC transmisson and reception. * - * Algorithm: Stops MAC transmisson and reception. + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: MAC has to be out of reset. + * @note MAC has to be out of reset. * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_hw_core_deinit(struct osi_core_priv_data *osi_core); /** - * osi_validate_core_regs - Read-validate HW registers for func safety. - * @osi_core: OSI core private data structure. + * @brief osi_validate_core_regs - Read-validate HW registers for func safety. * - * Algorithm: Reads pre-configured list of MAC/MTL configuration registers + * Algorithm: Reads pre-configured list of MAC/MTL configuration registers * and compares with last written value for any modifications. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * + * @note * 1) MAC has to be out of reset. * 2) osi_hw_core_init has to be called. Internally this would initialize - * the safety_config (see @osi_core_priv_data) based on MAC version and + * the safety_config (see osi_core_priv_data) based on MAC version and * which specific registers needs to be validated periodically. * 3) Invoke this call iff (osi_core_priv_data->safety_config != OSI_NULL) * - * Protection: None - * - * Return: 0 - success, -1 - failure (reg value has changed) + * @retval 0 on success + * @retval -1 on failure. */ int osi_validate_core_regs(struct osi_core_priv_data *osi_core); /** - * osi_start_mac - Start MAC Tx/Rx engine - * @osi_core: OSI core private data. + * @brief osi_start_mac - Start MAC Tx/Rx engine + * + * Algorithm: Enable MAC Tx and Rx engine. * - * Algorimthm: Enable MAC Tx and Rx engine. + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: - * 1) MAC init should be complete. See osi_hw_core_init() and - * osi_hw_dma_init() + * @note MAC init should be complete. See osi_hw_core_init() and + * osi_hw_dma_init() * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_start_mac(struct osi_core_priv_data *osi_core); /** - * osi_stop_mac - Stop MAC Tx/Rx engine - * @osi_core: OSI core private data. + * @brief osi_stop_mac - Stop MAC Tx/Rx engine + * + * Algorithm: Stop MAC Tx and Rx engine * - * Algorimthm: Stop MAC Tx and Rx engine + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: - * 1) MAC DMA deinit should be complete. See osi_hw_dma_deinit() + * @note MAC DMA deinit should be complete. See osi_hw_dma_deinit() * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_stop_mac(struct osi_core_priv_data *osi_core); /** - * osi_common_isr - Common ISR. - * @osi_core: OSI core private data structure. + * @brief osi_common_isr - Common ISR. + * + * Algorithm: Takes care of handling the common interrupts accordingly as per + * the MAC IP * - * Algorithm: Takes care of handling the - * common interrupts accordingly as per the - * MAC IP + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_common_isr(struct osi_core_priv_data *osi_core); /** - * osi_set_mode - Set FD/HD mode. - * @osi: OSI private data structure. - * @mode: Operating mode. + * @brief osi_set_mode - Set FD/HD mode. * - * Algorithm: Takes care of setting HD or FD mode - * accordingly as per the MAC IP. + * Algorithm: Takes care of setting HD or FD mode accordingly as per the MAC IP * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] mode: Operating mode. * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_mode(struct osi_core_priv_data *osi_core, int mode); /** - * osi_set_speed - Set operating speed. - * @osi: OSI private data structure. - * @speed: Operating speed. + * @brief osi_set_speed - Set operating speed. + * + * Algorithm: Takes care of setting the operating speed accordingly as per + * the MAC IP. * - * Algorithm: Takes care of setting the operating - * speed accordingly as per the MAC IP. + * @param[in] osi_core: OSI core private data structure. + * @param[in] speed: Operating speed. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_speed(struct osi_core_priv_data *osi_core, int speed); /** - * osi_pad_calibrate - PAD calibration - * @osi: OSI core private data structure. + * @brief osi_pad_calibrate - PAD calibration * - * Algorithm: Takes care of doing the pad calibration - * accordingly as per the MAC IP. + * Algorithm: Takes care of doing the pad calibration + * accordingly as per the MAC IP. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * + * @note * 1) MAC should out of reset and clocks enabled. * 2) RGMII and MDIO interface needs to be IDLE before performing PAD * calibration. * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_pad_calibrate(struct osi_core_priv_data *osi_core); /** - * osi_flush_mtl_tx_queue - Flushing a MTL Tx Queue. - * @osi_core: OSI private data structure. - * @qinx: MTL queue index. + * @brief osi_flush_mtl_tx_queue - Flushing a MTL Tx Queue. * - * Algorithm: Invokes EQOS flush Tx queue routine. + * Algorithm: Invokes EQOS flush Tx queue routine. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] qinx: MTL queue index. + * + * @note * 1) MAC should out of reset and clocks enabled. * 2) hw core initialized. see osi_hw_core_init(). * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_flush_mtl_tx_queue(struct osi_core_priv_data *osi_core, unsigned int qinx); /** - * osi_config_mac_loopback - Configure MAC loopback - * @osi: OSI private data structure. - * @lb_mode: Enable or disable MAC loopback + * @brief osi_config_mac_loopback - Configure MAC loopback * - * Algorithm: Configure the MAC to support the loopback. + * Algorithm: Configure the MAC to support the loopback. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] lb_mode: Enable or disable MAC loopback * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_mac_loopback(struct osi_core_priv_data *osi_core, unsigned int lb_mode); /** - * osi_set_avb - Set CBS algo and parameters - * @osi: OSI core private data structure. - * @avb: osi core avb data structure. + * @brief osi_set_avb - Set CBS algo and parameters * - * Algorithm: Set AVB algo and populated parameter from osi_core_avb - * structure for TC/TQ + * Algorithm: Set AVB algo and populated parameter from osi_core_avb + * structure for TC/TQ * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] avb: osi core avb data structure. + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated. * - * Return: Success = 0; failure = -1; + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_avb(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb); -/** osi_get_avb - Get CBS algo and parameters - * @osi: OSI core private data structure. - * @avb: osi core avb data structure. +/** + * @brief osi_get_avb - Get CBS algo and parameters * - * Algorithm: get AVB algo and populated parameter from osi_core_avb - * structure for TC/TQ + * Algorithm: get AVB algo and populated parameter from osi_core_avb + * structure for TC/TQ * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[out] avb: osi core avb data structure. + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated. * - * Return: Success = 0; failure = -1; + * @retval 0 on success + * @retval -1 on failure. */ int osi_get_avb(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb); /** - * osi_configure_txstatus - Configure Tx packet status reporting - * @osi_core: OSI private data structure. - * @tx_status: Enable or disable tx packet status reporting + * @brief osi_configure_txstatus - Configure Tx packet status reporting * - * Algorithm: Configure MAC to enable/disable Tx status error - * reporting. + * Algorithm: Configure MAC to enable/disable Tx status error + * reporting. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] tx_status: Enable or disable tx packet status reporting * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_configure_txstatus(struct osi_core_priv_data *osi_core, unsigned int tx_status); /** - * osi_config_fw_err_pkts - Configure forwarding of error packets - * @osi_core: OSI core private data structure. - * @qinx: Q index - * @fw_err: Enable or disable forwarding of error packets + * @brief osi_config_fw_err_pkts - Configure forwarding of error packets * - * Algorithm: Configure MAC to enable/disable forwarding of error packets. + * Algorithm: Configure MAC to enable/disable forwarding of error packets. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] qinx: Q index + * @param[in] fw_err: Enable or disable forwarding of error packets * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_fw_err_pkts(struct osi_core_priv_data *osi_core, unsigned int qinx, unsigned int fw_err); /** - * osi_config_rx_crc_check - Configure CRC Checking for Received Packets - * @osi_core: OSI core private data structure. - * @crc_chk: Enable or disable checking of CRC field in received packets + * @brief osi_config_rx_crc_check - Configure CRC Checking for Received Packets * - * Algorithm: When this bit is set, the MAC receiver does not check the CRC - * field in the received packets. When this bit is reset, the MAC receiver - * always checks the CRC field in the received packets. + * Algorithm: When this bit is set, the MAC receiver does not check the CRC + * field in the received packets. When this bit is reset, the MAC receiver + * always checks the CRC field in the received packets. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] crc_chk: Enable or disable checking of CRC field in received pkts * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_rx_crc_check(struct osi_core_priv_data *osi_core, unsigned int crc_chk); /** - * osi_configure_flow_ctrl - Configure flow control settings - * @osi_core: OSI core private data structure. - * @crc_chk: Enable or disable flow control settings + * @brief osi_configure_flow_ctrl - Configure flow control settings * - * Algorithm: This will enable or disable the flow control. - * flw_ctrl BIT0 is for tx flow ctrl enable/disable - * flw_ctrl BIT1 is for rx flow ctrl enable/disable + * Algorithm: This will enable or disable the flow control. + * flw_ctrl BIT0 is for tx flow ctrl enable/disable + * flw_ctrl BIT1 is for rx flow ctrl enable/disable * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] flw_ctrl: Enable or disable flow control settings * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_configure_flow_control(struct osi_core_priv_data *osi_core, unsigned int flw_ctrl); -/** osi_config_arp_offload - Configure ARP offload in MAC. - * @osi_core: OSI private data structure. - * @flags: Enable/disable flag. - * @ip_addr: Char array representation of IP address - * to be set in HW to compare with ARP requests received. +/** + * @brief osi_config_arp_offload - Configure ARP offload in MAC. * - * Algorithm: Invokes EQOS config ARP offload routine. + * Algorithm: Invokes EQOS config ARP offload routine. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] flags: Enable/disable flag. + * @param[in] ip_addr: Char array representation of IP address + * + * @note * 1) MAC should be init and started. see osi_start_mac() - * 2) Valid 4 byte IP address as argument @ip_addr + * 2) Valid 4 byte IP address as argument ip_addr * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_arp_offload(struct osi_core_priv_data *osi_core, unsigned int flags, unsigned char *ip_addr); -/* - * osi_config_rxcsum_offload - Configure RX checksum offload in MAC. - * @osi_core: OSI private data structure. - * @enable: Enable/disable flag. +/** + * @brief osi_config_rxcsum_offload - Configure RX checksum offload in MAC. * - * Algorithm: Invokes EQOS config RX checksum offload routine. + * Algorithm: Invokes EQOS config RX checksum offload routine. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] enable: Enable/disable flag. * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_rxcsum_offload(struct osi_core_priv_data *osi_core, unsigned int enable); /** - * osi_config_mac_pkt_filter_reg - configure mac filter register. - * @osi_core: OSI private data structure. - * @pfilter: OSI filter structure. + * @brief osi_config_mac_pkt_filter_reg - configure mac filter register. * - * Algorithm: This sequence is used to configure MAC in differnet pkt - * processing modes like promiscuous, multicast, unicast, - * hash unicast/multicast. + * Algorithm: This sequence is used to configure MAC in differnet packet + * processing modes like promiscuous, multicast, unicast, + * hash unicast/multicast. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] pfilter: OSI filter structure. + * + * @note * 1) MAC should be initialized and started. see osi_start_mac() * 2) MAC addresses should be configured in HW registers. see * osi_update_mac_addr_low_high_reg(). * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_mac_pkt_filter_reg(struct osi_core_priv_data *osi_core, struct osi_filter pfilter); /** - * osi_update_mac_addr_low_high_reg- invoke API to update L2 address + * @brief osi_update_mac_addr_low_high_reg- invoke API to update L2 address * in filter register * - * @osi_core: OSI private data structure. - * @index: filter index - * @value: MAC address to write - * @dma_routing_enable: dma channel routing enable(1) - * @dma_chan: dma channel number - * @addr_mask: filter will not consider byte in comparison + * Algorithm: This routine update MAC address to register for filtering + * based on dma_routing_enable, addr_mask and src_dest. Validation of + * dma_chan as well as DCS bit enabled in RXQ to DMA mapping register + * performed before updating DCS bits. + * + * @param[in] osi_core: OSI core private data structure. + * @param[in] index: filter index + * @param[in] value: MAC address to write + * @param[in] dma_routing_enable: dma channel routing enable(1) + * @param[in] dma_chan: dma channel number + * @param[in] addr_mask: filter will not consider byte in comparison * Bit 29: MAC_Address${i}_High[15:8] * Bit 28: MAC_Address${i}_High[7:0] * Bit 27: MAC_Address${i}_Low[31:24] * .. * Bit 24: MAC_Address${i}_Low[7:0] - * @src_dest: SA(1) or DA(0) + * @param[in] src_dest: SA(1) or DA(0) * - * Algorithm: This routine update MAC address to register for filtering - * based on dma_routing_enable, addr_mask and src_dest. Validation of - * dma_chan as well as DCS bit enabled in RXQ to DMA mapping register - * performed before updating DCS bits. - * - * Dependencies: + * @note * 1) MAC should be initialized and stated. see osi_start_mac() * 2) osi_core->osd should be populated. * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_mac_addr_low_high_reg(struct osi_core_priv_data *osi_core, unsigned int index, @@ -752,51 +762,48 @@ int osi_update_mac_addr_low_high_reg(struct osi_core_priv_data *osi_core, unsigned int src_dest); /** - * osi_config_l3_l4_filter_enable - invoke OSI call to eanble L3/L4 + * @brief osi_config_l3_l4_filter_enable - invoke OSI call to enable L3/L4 * filters. * - * @osi_core: OSI private data structure. - * @enable: enable/disable + * Algorithm: This routine to enable/disable L4/l4 filter * - * Algorithm: This routine to enable/disable L4/l4 filter + * @param[in] osi_core: OSI core private data structure. + * @param[in] enable: enable/disable * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_l3_l4_filter_enable(struct osi_core_priv_data *osi_core, unsigned int enable); /** - * osi_config_l3_filters - invoke OSI call config_l3_filters. + * @brief osi_config_l3_filters - invoke OSI call config_l3_filters. * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @enb_dis: 1 - enable otherwise - disable L3 filter - * @ipv4_ipv6_match: 1 - IPv6, otherwise - IPv4 - * @src_dst_addr_match: 0 - source, otherwise - destination - * @perfect_inverse_match: normal match(0) or inverse map(1) - * @dma_routing_enable: filter based dma routing enable(1) - * @dma_chan: dma channel for routing based on filter + * Algorithm: Check for DCS_enable as well as validate channel + * number and if dcs_enable is set. After validation, code flow + * is used to configure L3(IPv4/IPv6) filters resister + * for address matching. * - * Algorithm: Check for DCS_enable as well as validate channel - * number and if dcs_enable is set. After validation, code flow - * is used to configure L3((IPv4/IPv6) filters resister - * for address matching. + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] enb_dis: 1 - enable otherwise - disable L3 filter + * @param[in] ipv4_ipv6_match: 1 - IPv6, otherwise - IPv4 + * @param[in] src_dst_addr_match: 0 - source, otherwise - destination + * @param[in] perfect_inverse_match: normal match(0) or inverse map(1) + * @param[in] dma_routing_enable: filter based dma routing enable(1) + * @param[in] dma_chan: dma channel for routing based on filter * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) L3/L4 filtering should be enabled in MAC PFR register. See * osi_config_l3_l4_filter_enable() * 3) osi_core->osd should be populated * 4) DCS bits should be enabled in RXQ to DMA map register * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_l3_filters(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -808,23 +815,23 @@ int osi_config_l3_filters(struct osi_core_priv_data *osi_core, unsigned int dma_chan); /** - * osi_update_ip4_addr - invoke OSI call update_ip4_addr. - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @addr: ipv4 address - * @src_dst_addr_match: 0- source(addr0) 1- dest (addr1) + * @brief osi_update_ip4_addr - invoke OSI call update_ip4_addr. * - * Algorithm: This sequence is used to update IPv4 source/destination - * Address for L3 layer filtering + * Algorithm: This sequence is used to update IPv4 source/destination + * Address for L3 layer filtering * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] addr: ipv4 address + * @param[in] src_dst_addr_match: 0- source(addr0) 1- dest (addr1) + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) L3/L4 filtering should be enabled in MAC PFR register. See * osi_config_l3_l4_filter_enable() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_ip4_addr(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -832,51 +839,50 @@ int osi_update_ip4_addr(struct osi_core_priv_data *osi_core, unsigned int src_dst_addr_match); /** - * osi_update_ip6_addr - invoke OSI call update_ip6_addr. - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @addr: ipv6 adderss + * @brief osi_update_ip6_addr - invoke OSI call update_ip6_addr. * - * Algorithm: This sequence is used to update IPv6 source/destination - * Address for L3 layer filtering + * Algorithm: This sequence is used to update IPv6 source/destination + * Address for L3 layer filtering * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] addr: ipv6 adderss + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) L3/L4 filtering should be enabled in MAC PFR register. See * osi_config_l3_l4_filter_enable() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_ip6_addr(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned short addr[]); /** - * osi_config_l4_filters - invoke OSI call config_l4_filters. + * @brief osi_config_l4_filters - invoke OSI call config_l4_filters. * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @enb_dis: enable/disable L4 filter - * @tcp_udp_match: 1 - udp, 0 - tcp - * @src_dst_port_match: port matching enable/disable - * @perfect_inverse_match: normal match(0) or inverse map(1) - * @dma_routing_enable: filter based dma routing enable(1) - * @dma_chan: dma channel for routing based on filter + * Algorithm: This sequence is used to configure L4(TCP/UDP) filters for + * SA and DA Port Number matching * - * Algorithm: This sequence is used to configure L4(TCP/UDP) filters for - * SA and DA Port Number matching + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] enb_dis: enable/disable L4 filter + * @param[in] tcp_udp_match: 1 - udp, 0 - tcp + * @param[in] src_dst_port_match: port matching enable/disable + * @param[in] perfect_inverse_match: normal match(0) or inverse map(1) + * @param[in] dma_routing_enable: filter based dma routing enable(1) + * @param[in] dma_chan: dma channel for routing based on filter * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) L3/L4 filtering should be enabled in MAC PFR register. See * osi_config_l3_l4_filter_enable() * 3) osi_core->osd should be populated * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_l4_filters(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -888,50 +894,45 @@ int osi_config_l4_filters(struct osi_core_priv_data *osi_core, unsigned int dma_chan); /** - * osi_update_l4_port_no - invoke OSI call for - * update_l4_port_no. + * @brief osi_update_l4_port_no - invoke OSI call for update_l4_port_no. + * Algoriths sequence is used to update Source Port Number for + * L4(TCP/UDP) layer filtering. * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @port_no: port number - * @src_dst_port_match: source port - 0, dest port - 1 + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] port_no: port number + * @param[in] src_dst_port_match: source port - 0, dest port - 1 * - * Algoriths sequence is used to update Source Port Number for - * L4(TCP/UDP) layer filtering. - * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) L3/L4 filtering should be enabled in MAC PFR register. See * osi_config_l3_l4_filter_enable() * 3) osi_core->osd should be populated * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_l4_port_no(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned short port_no, unsigned int src_dst_port_match); /** - * osi_config_vlan_filter_reg - invoke OSI call for - * config_vlan_filtering. + * @brief osi_config_vlan_filtering - OSI call for configuring VLAN filter * - * @osi_core: OSI private data structure. - * @filter_enb_dis: vlan filter enable/disable - * @perfect_hash_filtering: perfect or hash filter - * @perfect_inverse_match: normal or inverse filter + * Algorithm: This sequence is used to enable/disable VLAN filtering and + * also selects VLAN filtering mode- perfect/hash * - * Algorithm: This sequence is used to enable/disable VLAN filtering and - * also selects VLAN filtering mode- perfect/hash + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_enb_dis: vlan filter enable(1) disable(0) + * @param[in] perfect_hash_filtering: perfect(0) or hash filter(1) + * @param[in] perfect_inverse_match: normal(0) or inverse filter(1) * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_vlan_filtering(struct osi_core_priv_data *osi_core, unsigned int filter_enb_dis, @@ -939,217 +940,214 @@ int osi_config_vlan_filtering(struct osi_core_priv_data *osi_core, unsigned int perfect_inverse_match); /** - * osi_config_l2_da_perfect_inverse_match - trigger OSI call for - * config_l2_da_perfect_inverse_match. + * @brief osi_config_l2_da_perfect_inverse_match - + * trigger OSI call for config_l2_da_perfect_inverse_match. * - * @osi_core: OSI private data structure. - * @perfect_inverse_match: 1 - inverse mode 0- normal mode + * Algorithm: This sequence is used to select perfect/inverse matching + * for L2 DA * - * Algorithm: This sequence is used to select perfect/inverse matching - * for L2 DA + * @param[in] osi_core: OSI core private data structure. + * @param[in] perfect_inverse_match: 1 - inverse mode 0- normal mode * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_config_l2_da_perfect_inverse_match(struct osi_core_priv_data *osi_core, unsigned int perfect_inverse_match); /** - * osi_update_vlan_id - invoke osi call to update VLAN ID + * @brief osi_update_vlan_id - invoke osi call to update VLAN ID * - * @osi_core: OSI private data structure. - * @vid: VLAN ID + * Algorithm: return 16 bit VLAN ID * - * Algorithm: return 16 bit VLAN ID + * @param[in] osi_core: OSI core private data structure. + * @param[in] vid: VLAN ID * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_vlan_id(struct osi_core_priv_data *osi_core, unsigned int vid); /** - * osi_write_phy_reg - Write to a PHY register through MAC over MDIO bus. - * @osi_core: OSI private data structure. - * @phyaddr: PHY address (PHY ID) associated with PHY - * @phyreg: Register which needs to be write to PHY. - * @phydata: Data to write to a PHY register. + * @brief osi_write_phy_reg - Write to a PHY register through MAC over MDIO bus. * - * Algorithm: - * 1) Before proceding for reading for PHY register check whether any MII - * operation going on MDIO bus by polling MAC_GMII_BUSY bit. - * 2) Program data into MAC MDIO data register. - * 3) Populate required parameters like phy address, phy register etc,, + * Algorithm: + * 1) Before proceeding for reading for PHY register check whether any MII + * operation going on MDIO bus by polling MAC_GMII_BUSY bit. + * 2) Program data into MAC MDIO data register. + * 3) Populate required parameters like phy address, phy register etc,, * in MAC MDIO Address register. write and GMII busy bits needs to be set * in this operation. - * 4) Write into MAC MDIO address register poll for GMII busy for MDIO + * 4) Write into MAC MDIO address register poll for GMII busy for MDIO * operation to complete. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] phyaddr: PHY address (PHY ID) associated with PHY + * @param[in] phyreg: Register which needs to be write to PHY. + * @param[in] phydata: Data to write to a PHY register. * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_write_phy_reg(struct osi_core_priv_data *osi_core, unsigned int phyaddr, unsigned int phyreg, unsigned short phydata); /** - * osi_read_mmc - invoke function to read actual registers and update - * structure variable mmc + * @brief osi_read_mmc - invoke function to read actual registers and update + * structure variable mmc + * + * Algorithm: Read the registers, mask reserve bits if required, update + * structure. * - * @osi_core: OSI core private data structure. + * @param[in] osi_core: OSI core private data structure. * - * Algorithm: Read the registers, mask reserve bits if requied, update - * structure. - * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_read_mmc(struct osi_core_priv_data *osi_core); /** - * osi_reset_mmc - invoke function to reset MMC counter and data structure + * @brief osi_reset_mmc - invoke function to reset MMC counter and data + * structure * - * @osi_core: OSI core private data structure. + * Algorithm: Read the registers, mask reserve bits if required, update + * structure. * - * Algorithm: Read the registers, mask reserve bits if requied, update - * structure. + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_reset_mmc(struct osi_core_priv_data *osi_core); /** - * osi_read_phy_reg - Read from a PHY register through MAC over MDIO bus. - * @osi_core: OSI private data structure. - * @phyaddr: PHY address (PHY ID) associated with PHY - * @phyreg: Register which needs to be read from PHY. + * @brief osi_read_phy_reg - Read from a PHY register through MAC over MDIO bus. * - * Algorithm: - * 1) Before proceding for reading for PHY register check whether any MII - * operation going on MDIO bus by polling MAC_GMII_BUSY bit. - * 2) Populate required parameters like phy address, phy register etc,, - * in program it in MAC MDIO Address register. Read and GMII busy bits - * needs to be set in this operation. - * 3) Write into MAC MDIO address register poll for GMII busy for MDIO - * operation to complete. After this data will be available at MAC MDIO - * data register. + * Algorithm: + * 1) Before proceeding for reading for PHY register check whether any MII + * operation going on MDIO bus by polling MAC_GMII_BUSY bit. + * 2) Populate required parameters like phy address, phy register etc,, + * in program it in MAC MDIO Address register. Read and GMII busy bits + * needs to be set in this operation. + * 3) Write into MAC MDIO address register poll for GMII busy for MDIO + * operation to complete. After this data will be available at MAC MDIO + * data register. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] phyaddr: PHY address (PHY ID) associated with PHY + * @param[in] phyreg: Register which needs to be read from PHY. * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: data from PHY register - success, -1 - failure + * @retval data from PHY register on success + * @retval -1 on failure */ int osi_read_phy_reg(struct osi_core_priv_data *osi_core, unsigned int phyaddr, unsigned int phyreg); + +/** + * @brief initializing the core operations + * + * @param[in] osi_core: OSI core private data structure. + * + * @retval data from PHY register on success + * @retval -1 on failure + */ int osi_init_core_ops(struct osi_core_priv_data *osi_core); /** - * osi_set_systime_to_mac - Handles setting of system time. - * @osi_core: OSI private data structure. - * @sec: Seconds to be configured. - * @nsec: Nano seconds to be configured. + * @brief osi_set_systime_to_mac - Handles setting of system time. * - * Algorithm: Set current system time to MAC. + * Algorithm: Set current system time to MAC. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] sec: Seconds to be configured. + * @param[in] nsec: Nano seconds to be configured. * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_systime_to_mac(struct osi_core_priv_data *osi_core, unsigned int sec, unsigned int nsec); + /** - * osi_adjust_freq - Adjust frequency - * @osi: OSI private data structure. - * @ppb: Parts per Billion + * @brief osi_adjust_freq - Adjust frequency * - * Algorithm: Adjust a drift of +/- comp nanoseconds per second. - * "Compensation" is the difference in frequency between - * the master and slave clocks in Parts Per Billion. + * Algorithm: Adjust a drift of +/- comp nanoseconds per second. + * "Compensation" is the difference in frequency between + * the master and slave clocks in Parts Per Billion. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[in] ppb: Parts per Billion * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_adjust_freq(struct osi_core_priv_data *osi_core, int ppb); /** + * @brief osi_adjust_time - Adjust time * - * osi_adjust_time - Adjust time - * @osi_core: OSI private data structure. - * @delta: Delta time + * Algorithm: Adjust/update the MAC time (delta time from MAC to system time + * passed in nanoseconds, can be + or -). * - * Algorithm: Adjust/update the MAC system time (delta passed in - * nanoseconds, can be + or -). + * @param[in] osi_core: OSI core private data structure. + * @param[in] delta: Delta time * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->ptp_config.one_nsec_accuracy need to be set to 1 * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_adjust_time(struct osi_core_priv_data *osi_core, long delta); /** - * osi_get_systime_from_mac - Get system time - * @osi: OSI private data structure. - * @sec: Value read in Seconds - * @nsec: Value read in Nano seconds + * @brief osi_get_systime_from_mac - Get system time * - * Algorithm: Gets the current system time + * Algorithm: Gets the current system time * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. + * @param[out] sec: Value read in Seconds + * @param[out] nsec: Value read in Nano seconds * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure - * (sec and nsec stores the read seconds and nanoseconds - * values from MAC if success) + * @retval 0 on success + * @retval -1 on failure. */ int osi_get_systime_from_mac(struct osi_core_priv_data *osi_core, unsigned int *sec, unsigned int *nsec); /** - * osi_ptp_configuration - Configure PTP - * @osi: OSI private data structure. - * @enable: Enable or disable Time Stamping. - * 0: Disable 1: Enable + * @brief osi_ptp_configuration - Configure PTP * - * Algorithm: Configure the PTP registers that are required for PTP. + * Algorithm: Configure the PTP registers that are required for PTP. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * @param[in] enable: Enable or disable Time Stamping. 0: Disable 1: Enable + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi->ptp_config.ptp_filter need to be filled accordingly to the * filter that need to be set for PTP packets. Please check osi_ptp_config @@ -1162,9 +1160,8 @@ int osi_get_systime_from_mac(struct osi_core_priv_data *osi_core, * 6) osi->ptp_config.nsec need to be filled with current time of nseconds * 7) osi->base need to be filled with the ioremapped base address * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_ptp_configuration(struct osi_core_priv_data *osi_core, unsigned int enable); diff --git a/include/osi_dma.h b/include/osi_dma.h index d076a6b..7b1fc68 100644 --- a/include/osi_dma.h +++ b/include/osi_dma.h @@ -27,617 +27,647 @@ #include "osi_dma_txrx.h" #include "mmc.h" -#define OSI_PKT_CX_VLAN OSI_BIT(0) -#define OSI_PKT_CX_VALID OSI_BIT(10) -#define OSI_PKT_CX_CSUM OSI_BIT(1) -#define OSI_PKT_CX_TSO OSI_BIT(2) -#define OSI_PKT_CX_PTP OSI_BIT(3) - -/* Flag to indicate if buffer programmed in desc. is DMA map'd from - * linear/Paged buffer from OS layer. +/** + * @addtogroup EQOS-PKT Packet context fields + * + * @brief These flags are used to convey context information about a packet + * between HW and SW. The context information includes + * whether a VLAN tag is to be inserted for a packet, + * whether a received packet is valid, + * whether checksum offload is to be enabled for the packet upon transmit, + * whether TCP segmentation offload is to be enabled for the packet, + * whether the HW should timestamp transmit/arrival of a packet respectively + * @{ */ -#define OSI_TXDONE_CX_PAGED_BUF OSI_BIT(0) -/* Flag to indicate if there was any tx error */ -#define OSI_TXDONE_CX_ERROR OSI_BIT(1) -#define OSI_TXDONE_CX_TS OSI_BIT(2) +/** VLAN packet */ +#define OSI_PKT_CX_VLAN OSI_BIT(0) +/** Valid packet */ +#define OSI_PKT_CX_VALID OSI_BIT(10) +/** CSUM packet */ +#define OSI_PKT_CX_CSUM OSI_BIT(1) +/** TSO packet */ +#define OSI_PKT_CX_TSO OSI_BIT(2) +/** PTP packet */ +#define OSI_PKT_CX_PTP OSI_BIT(3) +/** @} */ +/** + * @addtogroup EQOS-TX Tx done packet context fields + * + * @brief These flags used to convey transmit done packet context information, + * whether transmitted packet used a pagged buffer, whether transmitted packet + * has an tx error, whether tranmitted packet has an TS + * + * @{ + */ +/** Flag to indicate if buffer programmed in desc. is DMA map'd from + * linear/Paged buffer from OS layer */ +#define OSI_TXDONE_CX_PAGED_BUF OSI_BIT(0) +/** Flag to indicate if there was any tx error */ +#define OSI_TXDONE_CX_ERROR OSI_BIT(1) +/** Flag to indicate the availability of time stamp */ +#define OSI_TXDONE_CX_TS OSI_BIT(2) +/** @} */ + +/** + * @addtogroup EQOS-CHK Checksum offload results + * + * @brief Flag to indicate the result from checksum offload engine + * to SW network stack in receive path + * @{ + */ /* Checksum offload result flags */ #define OSI_CHECKSUM_NONE 0x0U #define OSI_CHECKSUM_UNNECESSARY 0x1U +/** @} */ /** - * struct osi_pkt_err_stats: OSI packet error stats - * @ip_header_error: IP Header Error - * @jabber_timeout_error: Jabber time out Error - * @pkt_flush_error: Packet Flush Error - * @payload_cs_error: Payload Checksum Error - * @loss_of_carrier_error: Loss of Carrier Error - * @no_carrier_error: No Carrier Error - * @late_collision_error: Late Collision Error - * @excessive_collision_error: Excessive Collision Error - * @excessive_deferal_error: Excessive Deferal Error - * @underflow_error: Under Flow Error - * @rx_crc_error: Rx CRC Error + * @brief OSI packet error stats */ struct osi_pkt_err_stats { - /* Transmit errors */ + /** IP Header Error */ unsigned long ip_header_error; + /** Jabber time out Error */ unsigned long jabber_timeout_error; + /** Packet Flush Error */ unsigned long pkt_flush_error; + /** Payload Checksum Error */ unsigned long payload_cs_error; + /** Loss of Carrier Error */ unsigned long loss_of_carrier_error; + /** No Carrier Error */ unsigned long no_carrier_error; + /** Late Collision Error */ unsigned long late_collision_error; + /** Excessive Collision Error */ unsigned long excessive_collision_error; + /** Excessive Deferal Error */ unsigned long excessive_deferal_error; + /** Under Flow Error */ unsigned long underflow_error; - /* Receive Errors */ + /** Rx CRC Error */ unsigned long rx_crc_error; }; /** - * struct osi_rx_desc - Receive Descriptor - * @rdes0: Receive Descriptor 0 - * @rdes1: Receive Descriptor 1 - * @rdes2: Receive Descriptor 2 - * @rdes3: Receive Descriptor 3 + * @brief Receive Descriptor */ struct osi_rx_desc { + /** Receive Descriptor 0 */ unsigned int rdes0; + /** Receive Descriptor 1 */ unsigned int rdes1; + /** Receive Descriptor 2 */ unsigned int rdes2; + /** Receive Descriptor 3 */ unsigned int rdes3; }; /** - * struct osi_rx_swcx - Receive descriptor software context - * @buf_phy_addr: DMA buffer physical address - * @buf_virt_addr: DMA buffer virtual address - * @len: Length of buffer + * @brief Receive descriptor software context */ struct osi_rx_swcx { + /** DMA buffer physical address */ unsigned long buf_phy_addr; + /** DMA buffer virtual address */ void *buf_virt_addr; + /** Length of buffer */ unsigned int len; }; /** - * struct osi_rx_pkt_cx - Received packet context. - * @flags: Bit map which holds the features that rx packets supports. - * @rxcsum: Stores the Rx csum - * @vlan_tag: Stores the VLAN tag ID in received packet. - * @pkt_len: Length of received packet. - * @ns: TS in nsec for the received packet + * @brief - Received packet context. This is a single instance + * and it is reused for all rx packets. */ struct osi_rx_pkt_cx { + /** Bit map which holds the features that rx packets supports */ unsigned int flags; + /** Stores the Rx csum */ unsigned int rxcsum; + /** Stores the VLAN tag ID in received packet */ unsigned int vlan_tag; + /** Length of received packet */ unsigned int pkt_len; + /** TS in nsec for the received packet */ unsigned long long ns; }; /** - * struct osi_rx_ring - DMA Rx channel ring - * @rx_desc: Pointer to Rx DMA descriptor - * @rx_swcx: Pointer to Rx DMA descriptor software context information - * @dma_rx_desc: Physical address of Rx DMA descriptor - * @cur_rx_idx: Descriptor index current reception. - * @refill_idx: Descriptor index for descriptor re-allocation. - * @rx_pkt_cx: Received packet context. + * @brief DMA channel Rx ring. The number of instances depends on the + * number of DMA channels configured */ struct osi_rx_ring { + /** Pointer to Rx DMA descriptor */ struct osi_rx_desc *rx_desc; + /** Pointer to Rx DMA descriptor software context information */ struct osi_rx_swcx *rx_swcx; + /** Physical address of Rx DMA descriptor */ unsigned long rx_desc_phy_addr; + /** Descriptor index current reception */ unsigned int cur_rx_idx; + /** Descriptor index for descriptor re-allocation */ unsigned int refill_idx; + /** Receive packet context */ struct osi_rx_pkt_cx rx_pkt_cx; }; /** - * struct osi_tx_swcx - Transmit descriptor software context - * @buf_phy_addr: Physical address of DMA mapped buffer. - * @buf_virt_addr: Virtual address of DMA buffer. - * @len: Length of buffer - * @is_paged_buf: Flag to keep track of whether buffer pointed - * by buf_phy_addr is a paged buffer/linear buffer. + *@brief Transmit descriptor software context */ struct osi_tx_swcx { + /** Physical address of DMA mapped buffer */ unsigned long buf_phy_addr; + /** Virtual address of DMA buffer */ void *buf_virt_addr; + /** Length of buffer */ unsigned int len; + /** Flag to keep track of whether buffer pointed by buf_phy_addr + * is a paged buffer/linear buffer */ unsigned int is_paged_buf; }; /** - * struct osi_tx_desc - Transmit descriptor - * @tdes0: Transmit descriptor 0 - * @tdes1: Transmit descriptor 1 - * @tdes2: Transmit descriptor 2 - * @tdes3: Transmit descriptor 3 + * @brief Transmit descriptor */ struct osi_tx_desc { + /** Transmit descriptor 0 */ unsigned int tdes0; + /** Transmit descriptor 1 */ unsigned int tdes1; + /** Transmit descriptor 2 */ unsigned int tdes2; + /** Transmit descriptor 3 */ unsigned int tdes3; }; /** - * struct osi_tx_pkt_cx - Transmit packet context for a packet - * @flags: Holds the features which a Tx packets supports. - * @vtag_id: Stores the VLAN tag ID. - * @desc_cnt: Descriptor count - * @mss: Max. segment size for TSO/USO/GSO/LSO packet - * @payload_len: Length of application payload - * @tcp_udp_hdrlen: Length of transport layer tcp/udp header - * @total_hdrlen: Length of all headers (ethernet/ip/tcp/udp) + * @brief Transmit packet context for a packet. This is a single instance + * and it is reused for all tx packets. */ struct osi_tx_pkt_cx { + /** Holds the features which a Tx packets supports */ unsigned int flags; + /** Stores the VLAN tag ID */ unsigned int vtag_id; + /** Descriptor count */ unsigned int desc_cnt; + /** Max. segment size for TSO/USO/GSO/LSO packet */ unsigned int mss; + /** Length of application payload */ unsigned int payload_len; + /** Length of transport layer tcp/udp header */ unsigned int tcp_udp_hdrlen; + /** Length of all headers (ethernet/ip/tcp/udp) */ unsigned int total_hdrlen; }; /** - * struct osi_txdone_pkt_cx - Transmit done packet context for a packet - * @flags: Indicates status flags for Tx complete (tx error occured, or - * indicate whether desc. had buf mapped from paged/linear memory etc.) - * @ns: TS captured for the tx packet and this is valid only when the PTP - * bit is set in fields + * @brief Transmit done packet context for a packet */ struct osi_txdone_pkt_cx { + /** Indicates status flags for Tx complete (tx error occurred, or + * indicate whether desc had buf mapped from paged/linear memory etc) */ unsigned int flags; + /** TS captured for the tx packet and this is valid only when the PTP + * bit is set in fields */ unsigned long long ns; }; /** - * struct osi_tx_ring - DMA channel Tx ring - * @tx_desc: Pointer to tx dma descriptor - * @tx_swcx: Pointer to tx dma descriptor software context information - * @tx_desc_phy_addr: Physical address of Tx descriptor. - * @cur_tx_idx: Descriptor index current transmission. - * @clean_idx: Descriptor index for descriptor cleanup. - * @tx_pkt_cx: Transmit packet context. - * @txdone_pkt_cx: Transmit complete packet context information. + * @brief DMA channel Tx ring. The number of instances depends on the + * number of DMA channels configured */ struct osi_tx_ring { + /** Pointer to tx dma descriptor */ struct osi_tx_desc *tx_desc; + /** Pointer to tx dma descriptor software context information */ struct osi_tx_swcx *tx_swcx; + /** Physical address of Tx descriptor */ unsigned long tx_desc_phy_addr; + /** Descriptor index current transmission */ unsigned int cur_tx_idx; + /** Descriptor index for descriptor cleanup */ unsigned int clean_idx; + /** Transmit packet context */ struct osi_tx_pkt_cx tx_pkt_cx; + /** Transmit complete packet context information */ struct osi_txdone_pkt_cx txdone_pkt_cx; }; struct osi_dma_priv_data; + /** - * struct osi_dma_chan_ops - MAC Hardware operations - * @set_tx_ring_len: Called to set Transmit Ring length. - * @set_tx_ring_start_addr: Called to set Transmit Ring Base address. - * @update_tx_tailptr: Called to update Tx Ring tail pointer. - * @set_rx_ring_len: Called to set Receive channel ring length. - * @set_rx_ring_start_addr: Called to set receive channel ring base address - * @update_rx_tailptr: Called to update Rx ring tail pointer. - * @clear_tx_intr: Invoked by OSD layer to clear Tx interrupt source. - * @clear_rx_intr: Invoked by OSD layer to clear Rx interrupt source. - * @disable_chan_tx_intr: Called to disable DMA tx channel interrupts at - * wrapper level. - * @enable_chan_tx_intr: Called to enable DMA tx channel interrupts at - * wrapper level. - * @disable_chan_rx_intr: Called to disable DMA Rx channel interrupts at - * wrapper level. - * @enable_chan_rx_intr: Called to enable DMA rx channel interrupts at - * wrapper level. - * @start_dma: Called to start the Tx/Rx DMA. - * @set_rx_buf_len: Called to set Rx buffer length. - * @validate_regs: Called periodically to read and validate safety critical - * registers against last written value. + *@brief MAC DMA Channel operations */ struct osi_dma_chan_ops { + /** Called to set Transmit Ring length */ void (*set_tx_ring_len)(void *addr, unsigned int chan, unsigned int len); + /** Called to set Transmit Ring Base address */ void (*set_tx_ring_start_addr)(void *addr, unsigned int chan, unsigned long base_addr); + /** Called to update Tx Ring tail pointer */ void (*update_tx_tailptr)(void *addr, unsigned int chan, unsigned long tailptr); + /** Called to set Receive channel ring length */ void (*set_rx_ring_len)(void *addr, unsigned int chan, unsigned int len); + /** Called to set receive channel ring base address */ void (*set_rx_ring_start_addr)(void *addr, unsigned int chan, unsigned long base_addr); + /** Called to update Rx ring tail pointer */ void (*update_rx_tailptr)(void *addr, unsigned int chan, unsigned long tailptr); + /** Called to clear Tx interrupt source */ void (*clear_tx_intr)(void *addr, unsigned int chan); + /** Called to clear Rx interrupt source */ void (*clear_rx_intr)(void *addr, unsigned int chan); + /** Called to disable DMA Tx channel interrupts at wrapper level */ void (*disable_chan_tx_intr)(void *addr, unsigned int chan); + /** Called to enable DMA Tx channel interrupts at wrapper level */ void (*enable_chan_tx_intr)(void *addr, unsigned int chan); + /** Called to disable DMA Rx channel interrupts at wrapper level */ void (*disable_chan_rx_intr)(void *addr, unsigned int chan); + /** Called to enable DMA Rx channel interrupts at wrapper level */ void (*enable_chan_rx_intr)(void *addr, unsigned int chan); + /** Called to start the Tx/Rx DMA */ void (*start_dma)(void *addr, unsigned int chan); + /** Called to stop the Tx/Rx DMA */ void (*stop_dma)(void *addr, unsigned int chan); + /** Called to initialize the DMA channel */ void (*init_dma_channel) (struct osi_dma_priv_data *osi_dma); + /** Called to set Rx buffer length */ void (*set_rx_buf_len)(struct osi_dma_priv_data *osi_dma); + /** Called periodically to read and validate safety critical + * registers against last written value */ int (*validate_regs)(struct osi_dma_priv_data *osi_dma); }; /** - * struct osi_dma_priv_data - The OSI private data structure. - * @tx_ring: Array of pointers to DMA Tx channel Ring. - * @rx_ring: Array of pointers to DMA Rx channel Ring. - * @base: Memory mapped base address of MAC IP. - * @osd: Pointer to OSD private data structure. - * @ops: Address of HW operations structure. - * @mac: MAC HW type (EQOS). - * @num_dma_chans: Number of channels enabled in MAC. - * @dma_chans[]: Array of supported DMA channels - * @rx_buf_len: DMA Rx channel buffer length at HW level. - * @mtu: MTU size - * @pkt_err_stats: Packet error stats - * @dstats: Extra DMA stats - * @rx_riwt: Receive Interrupt Watchdog Timer Count Units - * @use_riwt: Flag which decides riwt is enabled(1) or disabled(0) - * @safety_config: Functional safety config to do periodic read-verify of - * certain safety critical dma registers. + * @brief The OSI DMA private data structure. */ struct osi_dma_priv_data { + /** Array of pointers to DMA Tx channel Ring */ struct osi_tx_ring *tx_ring[OSI_EQOS_MAX_NUM_CHANS]; + /** Array of pointers to DMA Rx channel Ring */ struct osi_rx_ring *rx_ring[OSI_EQOS_MAX_NUM_CHANS]; + /** Memory mapped base address of MAC IP */ void *base; + /** Pointer to OSD private data structure */ void *osd; + /** Address of HW operations structure */ struct osi_dma_chan_ops *ops; + /** MAC HW type (EQOS) */ unsigned int mac; + /** Number of channels enabled in MAC */ unsigned int num_dma_chans; + /** Array of supported DMA channels */ unsigned int dma_chans[OSI_EQOS_MAX_NUM_CHANS]; + /** DMA Rx channel buffer length at HW level */ unsigned int rx_buf_len; + /** MTU size */ unsigned int mtu; + /** Packet error stats */ struct osi_pkt_err_stats pkt_err_stats; + /** Extra DMA stats */ struct osi_xtra_dma_stat_counters dstats; + /** Receive Interrupt Watchdog Timer Count Units */ unsigned int rx_riwt; + /** Flag which decides riwt is enabled(1) or disabled(0) */ unsigned int use_riwt; + /** Functional safety config to do periodic read-verify of + * certain safety critical dma registers */ void *safety_config; }; /** - * osi_validate_dma_regs - Read-validate HW registers for func safety. - * @osi_dma: OSI dma private data structure. + * @brief - Read-validate HW registers for func safety. * - * Algorithm: Reads pre-configured list of DMA configuration registers + * Algorithm: Reads pre-configured list of DMA configuration registers * and compares with last written value for any modifications. * - * Dependencies: + * @param[in] osi_dma: OSI DMA private data structure. + * + * @note * 1) MAC has to be out of reset. * 2) osi_hw_dma_init has to be called. Internally this would initialize - * the safety_config (see @osi_dma_priv_data) based on MAC version and + * the safety_config (see osi_dma_priv_data) based on MAC version and * which specific registers needs to be validated periodically. * 3) Invoke this call iff (osi_dma_priv_data->safety_config != OSI_NULL) * - * Protection: None - * - * Return: 0 - success, -1 - failure (reg value has changed) + * @retval 0 on success + * @retval -1 on failure. */ int osi_validate_dma_regs(struct osi_dma_priv_data *osi_dma); /** - * osi_disable_chan_tx_intr - Disables DMA Tx channel interrupts. - * @osi_dma: DMA private data. - * @chan: DMA Tx channel number. + * @brief osi_disable_chan_tx_intr - Disables DMA Tx channel interrupts. * - * Algorithm: Disables Tx interrupts at wrapper level. + * Algorithm: Disables Tx interrupts at wrapper level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA Tx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. + * OS Dependent layer and pass corresponding channel number. * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_disable_chan_tx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_enable_chan_tx_intr - Enable DMA Tx channel interrupts. - * @osi_dma: DMA private data. - * @chan: DMA Tx channel number. + * @brief osi_enable_chan_tx_intr - Enable DMA Tx channel interrupts. * - * Algorithm: Enables Tx interrupts at wrapper level. + * Algorithm: Enables Tx interrupts at wrapper level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA Tx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. + * OS Dependent layer and pass corresponding channel number. * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_enable_chan_tx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_disable_chan_rx_intr - Disable DMA Rx channel interrupts. - * @osi_dma: DMA private data. - * @chan: DMA rx channel number. + * @brief osi_disable_chan_rx_intr - Disable DMA Rx channel interrupts. * - * Algorithm: Disables Rx interrupts at wrapper level. + * Algorithm: Disables Rx interrupts at wrapper level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA rx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. + * OS Dependent layer and pass corresponding channel number. * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_disable_chan_rx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_enable_chan_rx_intr - Enable DMA Rx channel interrupts. - * @osi_dma: DMA private data. - * @chan: DMA rx channel number. + * @brief osi_enable_chan_rx_intr - Enable DMA Rx channel interrupts. * - * Algorithm: Enables Rx interrupts at wrapper level. + * Algorithm: Enables Rx interrupts at wrapper level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA rx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. + * OS Dependent layer and pass corresponding channel number. * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_enable_chan_rx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_clear_tx_intr - Handles Tx interrupt source. - * @osi_dma: DMA private data. - * @chan: DMA tx channel number. + * @brief osi_clear_tx_intr - Handles Tx interrupt source. * - * Algorithm: Clear Tx interrupt source at wrapper level and DMA level. + * Algorithm: Clear Tx interrupt source at wrapper level and DMA level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA tx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_clear_tx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_clear_rx_intr - Handles Rx interrupt source. - * @osi_dma: DMA private data. - * @chan: DMA rx channel number. + * @brief osi_clear_rx_intr - Handles Rx interrupt source. * - * Algorithm: Clear Rx interrupt source at wrapper level and DMA level. + * Algorithm: Clear Rx interrupt source at wrapper level and DMA level. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA rx channel number. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. + * OS Dependent layer and pass corresponding channel number. * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_clear_rx_intr(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_start_dma - Start DMA - * @osi_dma: DMA private data. - * @chan: DMA Tx/Rx channel number + * @brief Start DMA * - * Algorimthm: Start the DMA for specific MAC + * Algorithm: Start the DMA for specific MAC * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA Tx/Rx channel number + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_start_dma(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_stop_dma - Stop DMA - * @osi_dma: DMA private data. - * @chan: DMA Tx/Rx channel number + * @brief osi_stop_dma - Stop DMA * - * Algorimthm: Stop the DMA for specific MAC + * Algorithm: Stop the DMA for specific MAC * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * @param[in] chan: DMA Tx/Rx channel number + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_stop_dma(struct osi_dma_priv_data *osi_dma, unsigned int chan); /** - * osi_get_refill_rx_desc_cnt - Rx descriptors count that needs to refill. - * @rx_ring: DMA channel Rx ring. + * @brief osi_get_refill_rx_desc_cnt - Rx descriptors count that needs to refill * - * Algorithm: subtract current index with fill (need to cleanup) - * to get Rx descriptors count that needs to refill. + * Algorithm: subtract current index with fill (need to cleanup) + * to get Rx descriptors count that needs to refill. * - * Dependencies: None. + * @param[in] rx_ring: DMA channel Rx ring. * - * Protection: None. + * @note None. * - * Return: Number of available free descriptors. + * @retval "Number of available free descriptors." */ unsigned int osi_get_refill_rx_desc_cnt(struct osi_rx_ring *rx_ring); /** - * osi_rx_dma_desc_init - DMA Rx descriptor init - * @rx_swcx: OSI DMA Rx ring software context - * @rx_desc: OSI DMA Rx ring descriptor - * @use_riwt: to enable Rx WDT and disable IOC + * @brief osi_rx_dma_desc_init - DMA Rx descriptor init * - * Algorithm: Initialise a Rx DMA descriptor. + * Algorithm: Initialise a Rx DMA descriptor. * - * Dependencies: + * @param[in] rx_swcx: OSI DMA Rx ring software context + * @param[in] rx_desc: OSI DMA Rx ring descriptor + * @param[in] use_riwt: to enable Rx WDT and disable IOC + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) rx_swcx->buf_phy_addr need to be filled with DMA mapped address - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * 3) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_rx_dma_desc_init(struct osi_rx_swcx *rx_swcx, struct osi_rx_desc *rx_desc, unsigned int use_riwt); /** - * osi_update_rx_tailptr - Updates DMA Rx ring tail pointer - * @osi_dma: OSI DMA private data struture. - * @rx_ring: Pointer to DMA Rx ring. - * @chan: DMA channel number. + * @brief osi_update_rx_tailptr - Updates DMA Rx ring tail pointer * - * Algorithm: Updates DMA Rx ring tail pointer. + * @param[in] osi_dma: OSI DMA private data struture. + * @param[in] rx_ring: Pointer to DMA Rx ring. + * @param[in] chan: DMA channel number. * - * Dependencies: + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_update_rx_tailptr(struct osi_dma_priv_data *osi_dma, struct osi_rx_ring *rx_ring, unsigned int chan); /** - * osi_set_rx_buf_len - Updates rx buffer length. - * @osi_dma: OSI DMA private data struture. + * @brief Updates rx buffer length. * - * Algorithm: Updates Rx buffer length. + * @param[in] osi_dma: OSI DMA private data struture. * - * Dependencies: + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) osi_dma->mtu need to be filled with current MTU size <= 9K * - * Protection: None. - * - * Return: 0 - success , -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_set_rx_buf_len(struct osi_dma_priv_data *osi_dma); /** - * osi_hw_transmit - Initialize Tx DMA descriptors for a channel - * @osi_dma: DMA private data. - * @chan: DMA Tx channel number. + * @brief osi_hw_transmit - Initialize Tx DMA descriptors for a channel * - * Algorithm: Initialize Transmit descriptors with DMA mappabled buffers, - * set OWN bit, Tx ring length and set starting address of Tx DMA channel. - * Tx ring base address in Tx DMA registers. + * Algorithm: Initialize Transmit descriptors with DMA mappable buffers, + * set OWN bit, Tx ring length and set starting address of Tx DMA channel + * Tx ring base address in Tx DMA registers. * - * Dependencies: + * @param[in] osi: DMA private data. + * @param[in] chan: DMA Tx channel number. + * + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) DMA channel need to be started, see osi_start_dma * 4) Need to set update tx_pkt_cx->flags accordingly as per the * requirements - * #define OSI_PKT_CX_VLAN OSI_BIT(0) - * #define OSI_PKT_CX_CSUM OSI_BIT(1) - * #define OSI_PKT_CX_TSO OSI_BIT(2) - * #define OSI_PKT_CX_PTP OSI_BIT(3) + * OSI_PKT_CX_VLAN OSI_BIT(0) + * OSI_PKT_CX_CSUM OSI_BIT(1) + * OSI_PKT_CX_TSO OSI_BIT(2) + * OSI_PKT_CX_PTP OSI_BIT(3) * 5) tx_pkt_cx->desc_cnt need to be populated which holds the number * of swcx descriptors allocated for that packet * 6) tx_swcx structure need to be filled for per packet with the * buffer len, DMA mapped address of buffer for each descriptor * consumed by the packet - * - * Protection: None. - * - * Return: None. */ void osi_hw_transmit(struct osi_dma_priv_data *osi, unsigned int chan); /** - * osi_process_tx_completions - Process Tx complete on DMA channel ring. - * @osi: OSI private data structure. - * @chan: Channel number on which Tx complete need to be done. + * @brief osi_process_tx_completions - Process Tx complete on DMA channel ring. * - * Algorithm: This function will be invoked by OSD layer to process Tx - * complete interrupt. - * 1) First checks whether descriptor owned by DMA or not. - * 2) Invokes OSD layer to release DMA address and Tx buffer which are - * updated as part of transmit routine. + * Algorithm: This function will be invoked by OSD layer to process Tx + * complete interrupt. + * 1) First checks whether descriptor owned by DMA or not. + * 2) Invokes OSD layer to release DMA address and Tx buffer which are + * updated as part of transmit routine. * - * Dependencies: + * @param[in] osi: OSI private data structure. + * @param[in] chan: Channel number on which Tx complete need to be done. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) DMA need to be started, see osi_start_dma * - * Protection: None - * - * Return: Number of decriptors (buffers) proccessed. + * @returns Number of decriptors (buffers) proccessed. */ int osi_process_tx_completions(struct osi_dma_priv_data *osi, unsigned int chan); /** - * osi_process_rx_completions - Read data from receive channel descriptors - * @osi: OSI private data structure. - * @chan: Rx DMA channel number - * @budget: Threshould for reading the packets at a time. + * @brief osi_process_rx_completions - Read data from rx channel descriptors * - * Algorimthm: This routine will be invoked by OSD layer to get the - * data from Rx descriptors and deliver the packet to the stack. - * 1) Checks descriptor owned by DMA or not. - * 2) Get the length from Rx descriptor - * 3) Invokes OSD layer to deliver the packet to network stack. - * 4) Re-allocate the receive buffers, populate Rx descriptor and - * handover to DMA. + * Algorithm: This routine will be invoked by OSD layer to get the + * data from Rx descriptors and deliver the packet to the stack. + * 1) Checks descriptor owned by DMA or not. + * 2) Get the length from Rx descriptor + * 3) Invokes OSD layer to deliver the packet to network stack. + * 4) Re-allocate the receive buffers, populate Rx descriptor and + * handover to DMA. * - * Dependencies: + * @param[in] osi: OSI private data structure. + * @param[in] chan: Rx DMA channel number + * @param[in] budget: Threshould for reading the packets at a time. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) DMA need to be started, see osi_start_dma * - * Protection: None. - * - * Return: None. + * @returns Number of decriptors (buffers) proccessed. */ int osi_process_rx_completions(struct osi_dma_priv_data *osi, unsigned int chan, int budget); /** - * osi_hw_dma_init - Initialize DMA - * @osi_dma: DMA private data. + * @brief osi_hw_dma_init - Initialize DMA * - * Algorithm: Takes care of initializing the tx, rx ring and descriptors - * based on the number of channels selected. + * Algorithm: Takes care of initializing the tx, rx ring and descriptors + * based on the number of channels selected. * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * + * + * @note * 1) Allocate memory for osi_dma * 2) MAC needs to be out of reset and proper clocks need to be configured. * 3) Numer of dma channels osi_dma->num_dma_chans @@ -658,73 +688,71 @@ int osi_process_rx_completions(struct osi_dma_priv_data *osi, * 12) osi_dma->use_riwt ==> OSI_DISABLE/OSI_ENABLE * 13) osi_dma->rx_riwt ===> Actual value read from DT * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_hw_dma_init(struct osi_dma_priv_data *osi_dma); /** - * osi_hw_dma_deinit - Deinitialize DMA - * @osi_dma: DMA private data. + * @brief osi_hw_dma_deinit - De initialize DMA * - * Algorithm: Takes care of stopping the MAC + * Algorithm: Takes care of stopping the MAC * - * Dependencies: + * @param[in] osi_dma: DMA private data. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_hw_dma_deinit(struct osi_dma_priv_data *osi_dma); /** - * osi_init_dma_ops - Initialize DMA operations - * @osi_dma: DMA private data. + * @brief osi_init_dma_ops - Initialize DMA operations * - * Algorithm: Takes care of initializing the DMA operations + * @param[in] osi_dma: DMA private data. * - * Dependencies: None. + * @note None * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_init_dma_ops(struct osi_dma_priv_data *osi_dma); /** - * osi_clear_tx_pkt_err_stats - Clear tx packet error stats. - * @osi: OSI dma private data structure. + * @brief osi_clear_tx_pkt_err_stats - Clear tx packet error stats. * - * Algorithm: This function will be invoked by OSD layer to clear the - * tx stats mentioned in osi_dma->pkt_err_stats structure - - * Dependencies: + * Algorithm: This function will be invoked by OSD layer to clear the + * tx stats mentioned in osi_dma->pkt_err_stats structure + * + * @param[in] osi_dma: OSI DMA private data structure. + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_clear_tx_pkt_err_stats(struct osi_dma_priv_data *osi_dma); /** - * osi_clear_rx_pkt_err_stats - Clear rx packet error stats. - * @osi: OSI dma private data structure. + * @brief osi_clear_rx_pkt_err_stats - Clear rx packet error stats. * - * Algorithm: This function will be invoked by OSD layer to clear the - * rx_crc_error mentioned in osi_dma->pkt_err_stats structure. + * Algorithm: This function will be invoked by OSD layer to clear the + * rx_crc_error mentioned in osi_dma->pkt_err_stats structure. * - * Dependencies: + * @param[in] osi_dma: OSI DMA private data structure. + * + * + * @note * 1) MAC needs to be out of reset and proper clocks need to be configured. * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ int osi_clear_rx_pkt_err_stats(struct osi_dma_priv_data *osi_dma); diff --git a/include/osi_dma_txrx.h b/include/osi_dma_txrx.h index da0c56b..97c0c5c 100644 --- a/include/osi_dma_txrx.h +++ b/include/osi_dma_txrx.h @@ -23,16 +23,43 @@ #ifndef OSI_DMA_TXRX_H #define OSI_DMA_TXRX_H +/** + * @addtogroup EQOS_Help Descriptor Helper MACROS + * + * @brief Helper macros for defining Tx/Rx descriptor count + * @{ + */ #define TX_DESC_CNT 256U #define RX_DESC_CNT 256U +/** @} */ +/** TSO Header length divisor */ #define OSI_TSO_HDR_LEN_DIVISOR 4U +/** + * @addtogroup EQOS_Help1 Helper MACROS for descriptor index operations + * + * @brief Helper macros for incrementing or decrementing Tx/Rx descriptor index + * @{ + */ +/** Increment the tx descriptor index */ #define INCR_TX_DESC_INDEX(idx, i) ((idx) = ((idx) + (i)) & (TX_DESC_CNT - 1U)) +/** Decrement the tx descriptor index */ #define DECR_TX_DESC_INDEX(idx, i) ((idx) = ((idx) - (i)) & (TX_DESC_CNT - 1U)) +/** Increment the rx descriptor index */ #define INCR_RX_DESC_INDEX(idx, i) ((idx) = ((idx) + (i)) & (RX_DESC_CNT - 1U)) +/** Decrement the rx descriptor index */ #define DECR_RX_DESC_INDEX(idx, i) ((idx) = ((idx) - (i)) & (RX_DESC_CNT - 1U)) +/** @} */ +/** + * @addtogroup EQOS_RxDesc Receive Descriptors bit fields + * + * @brief These macros are used to check the value in specific bit fields of + * the descriptor. The fields in the descriptor are mapped as + * defined in the HW manual + * @{ + */ #define RDES3_OWN OSI_BIT(31) #define RDES3_CTXT OSI_BIT(30) #define RDES3_IOC OSI_BIT(30) @@ -51,17 +78,27 @@ #define RDES3_RS0V OSI_BIT(25) #define RDES3_RS1V OSI_BIT(26) #define RDES0_OVT 0x0000FFFFU -#define RDES1_TSA OSI_BIT(14) /* Timestamp available */ -#define RDES1_TD OSI_BIT(15) /* Timestamp Dropped */ +#define RDES1_TSA OSI_BIT(14) +#define RDES1_TD OSI_BIT(15) #define RDES1_IPCE OSI_BIT(7) #define RDES1_IPCB OSI_BIT(6) #define RDES1_IPHE OSI_BIT(3) +/** @} */ +/** Error Summary bits for Received packet */ #define RDES3_ES_BITS \ (RDES3_ERR_CRC | RDES3_ERR_GP | RDES3_ERR_WD | \ RDES3_ERR_ORUN | RDES3_ERR_RE | RDES3_ERR_DRIB) +/** + * @addtogroup EQOS_TxDesc Transmit Descriptors bit fields + * + * @brief These macros are used to check the value in specific bit fields of + * the descriptor. The fields in the descriptor are mapped as + * defined in the HW manual + * @{ + */ #define TDES2_IOC OSI_BIT(31) #define TDES2_MSS_MASK 0x3FFFU #define TDES3_OWN OSI_BIT(31) @@ -95,7 +132,9 @@ */ #define TDES2_VTIR ((unsigned int)0x2 << 14U) #define TDES2_TTSE ((unsigned int)0x1 << 30U) +/** @} */ +/** Error Summary bits for Transmitted packet */ #define TDES3_ES_BITS (TDES3_IP_HEADER_ERR | \ TDES3_UNDER_FLOW_ERR | \ TDES3_EXCESSIVE_DEF_ERR | \ diff --git a/osi/common/osi_common.c b/osi/common/osi_common.c index df137b4..d371f04 100644 --- a/osi/common/osi_common.c +++ b/osi/common/osi_common.c @@ -23,17 +23,6 @@ #include #include -/** - * osi_get_hw_features: Get MAC Hardware features from features registers - * @osi: OSI private data structure. - * - * Algorithm: Reads HW features from HW registers and populate those - * in hw features structure. - * - * Dependencies: CAR reset should be success before calling this function - * - * Return: None - */ void osi_get_hw_features(void *base, struct osi_hw_features *hw_feat) { unsigned int mac_hfr0; diff --git a/osi/core/eqos_core.c b/osi/core/eqos_core.c index 9b5f89e..3782332 100644 --- a/osi/core/eqos_core.c +++ b/osi/core/eqos_core.c @@ -26,15 +26,15 @@ #include "eqos_core.h" #include "eqos_mmc.h" +/** + * @brief eqos_core_safety_config - EQOS MAC core safety configuration + */ static struct core_func_safety eqos_core_safety_config; /** - * eqos_core_safety_writel - Write to safety critical register. - * @val: Value to be written. - * @addr: memory mapped register address to be written to. - * @idx: Index of register corresponding to enum func_safety_core_regs. + * @brief eqos_core_safety_writel - Write to safety critical register. * - * Algorithm: + * Algorithm: * 1) Acquire RW lock, so that eqos_validate_core_regs does not run while * updating the safety critical register. * 2) call osi_writel() to actually update the memory mapped register. @@ -42,12 +42,11 @@ static struct core_func_safety eqos_core_safety_config; * so that this latest value will be compared when eqos_validate_core_regs * is scheduled. * - * Dependencies: - * 1) MAC has to be out of reset, and clocks supplied. + * @param[in] val: Value to be written. + * @param[in] addr: memory mapped register address to be written to. + * @param[in] idx: Index of register corresponding to enum func_safety_core_regs. * - * Protection: None. - * - * Return: None. + * @note MAC has to be out of reset, and clocks supplied. */ static inline void eqos_core_safety_writel(unsigned int val, void *addr, unsigned int idx) @@ -61,21 +60,16 @@ static inline void eqos_core_safety_writel(unsigned int val, void *addr, } /** - * eqos_core_safety_init - Initialize the eqos_core_safety_config. - * @base_addr: Base address of memory mapped register space. + * @brief Initialize the eqos_core_safety_config. * - * Algorithm: Populate the list of safety critical registers and provide + * Algorithm: Populate the list of safety critical registers and provide * 1) the address of the register * 2) Register mask (to ignore reserved/self-critical bits in the reg). - * See @eqos_validate_core_regs which can be ivoked periodically to compare + * See eqos_validate_core_regs which can be ivoked periodically to compare * the last written value to this register vs the actual value read when * eqos_validate_core_regs is scheduled. * - * Dependencies: None - * - * Protection: None - * - * Return: None + * @param[in] osi_core: OSI core private data structure. */ static void eqos_core_safety_init(struct osi_core_priv_data *osi_core) { @@ -171,21 +165,22 @@ static void eqos_core_safety_init(struct osi_core_priv_data *osi_core) } /** - * eqos_validate_core_regs - Read-validate HW registers for functional safety. - * @osi: OSI core private data structure. - * Algorithm: Reads pre-configured list of MAC/MTL configuration registers + * @brief Read-validate HW registers for functional safety. + * + * Algorithm: Reads pre-configured list of MAC/MTL configuration registers * and compares with last written value for any modifications. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * + * @note * 1) MAC has to be out of reset. * 2) osi_hw_core_init has to be called. Internally this would initialize - * the safety_config (see @osi_core_priv_data) based on MAC version and + * the safety_config (see osi_core_priv_data) based on MAC version and * which specific registers needs to be validated periodically. * 3) Invoke this call iff (osi_core_priv_data->safety_config != OSI_NULL) * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_validate_core_regs(struct osi_core_priv_data *osi_core) { @@ -219,18 +214,16 @@ static int eqos_validate_core_regs(struct osi_core_priv_data *osi_core) } /** - * eqos_config_flow_control - Configure MAC flow control settings - * @addr: MAC base address. - * @flw_ctrl: flw_ctrl settings + * @brief eqos_config_flow_control - Configure MAC flow control settings * - * Algorithm: + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] flw_ctrl: flw_ctrl settings * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_flow_control(void *addr, unsigned int flw_ctrl) { @@ -286,20 +279,20 @@ static int eqos_config_flow_control(void *addr, unsigned int flw_ctrl) } /** - * eqos_config_rx_crc_check - Configure CRC Checking for Rx Packets - * @addr: MAC base address. - * @crc_chk: Enable or disable checking of CRC field in received packets + * @brief eqos_config_rx_crc_check - Configure CRC Checking for Rx Packets * - * Algorithm: When this bit is set, the MAC receiver does not check the CRC + * Algorithm: When this bit is set, the MAC receiver does not check the CRC * field in the received packets. When this bit is reset, the MAC receiver * always checks the CRC field in the received packets. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] crc_chk: Enable or disable checking of CRC field in received pkts * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @note MAC should be init and started. see osi_start_mac() + * + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_rx_crc_check(void *addr, unsigned int crc_chk) { @@ -331,22 +324,22 @@ static int eqos_config_rx_crc_check(void *addr, unsigned int crc_chk) } /** - * eqos_config_fw_err_pkts - Configure forwarding of error packets - * @addr: MAC base address. - * @qinx: Q index - * @fw_err: Enable or Disable the forwarding of error packets + * @brief eqos_config_fw_err_pkts - Configure forwarding of error packets * - * Algorithm: When this bit is reset, the Rx queue drops packets with error - * status (CRC error, GMII_ER, watchdog timeout, or overflow). - * When this bit is set, all packets except the runt error packets - * are forwarded to the application or DMA. + * Algorithm: When this bit is reset, the Rx queue drops packets with + * error status (CRC error, GMII_ER, watchdog timeout, or overflow). + * When this bit is set, all packets except the runt error packets + * are forwarded to the application or DMA. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] qinx: Q index + * @param[in] fw_err: Enable or Disable the forwarding of error packets * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_fw_err_pkts(void *addr, unsigned int qinx, unsigned int fw_err) @@ -388,21 +381,21 @@ static int eqos_config_fw_err_pkts(void *addr, unsigned int qinx, } /** - * eqos_config_tx_status - Configure MAC to forward the tx pkt status - * @addr: MAC base address. - * @tx_status: Enable or Disable the forwarding of tx pkt status + * @brief eqos_config_tx_status - Configure MAC to forward the tx pkt status * - * Algorithm: When DTXSTS bit is reset, the Tx packet status received - * from the MAC is forwarded to the application. - * When DTXSTS bit is set, the Tx packet status received from the MAC - * are dropped in MTL. + * Algorithm: When DTXSTS bit is reset, the Tx packet status received + * from the MAC is forwarded to the application. + * When DTXSTS bit is set, the Tx packet status received from the MAC + * are dropped in MTL. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] tx_status: Enable or Disable the forwarding of tx pkt status * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_tx_status(void *addr, unsigned int tx_status) { @@ -439,18 +432,16 @@ static int eqos_config_tx_status(void *addr, unsigned int tx_status) } /** - * eqos_config_mac_loopback - Configure MAC to support loopback - * @addr: MAC base address. - * @lb_mode: Enable or Disable MAC loopback mode + * @brief eqos_config_mac_loopback - Configure MAC to support loopback * - * Algorithm: Configure MAC to enable or disable loopback + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] lb_mode: Enable or Disable MAC loopback mode * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None. - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_mac_loopback(void *addr, unsigned int lb_mode) { @@ -493,18 +484,17 @@ static int eqos_config_mac_loopback(void *addr, unsigned int lb_mode) } /** - * eqos_poll_for_swr - Poll for software reset (SWR bit in DMA Mode) - * @addr: EQOS virtual base address. + * @brief eqos_poll_for_swr - Poll for software reset (SWR bit in DMA Mode) * - * Algorithm: CAR reset will be issued through MAC reset pin. - * Waits for SWR reset to be cleared in DMA Mode register. + * Algorithm: CAR reset will be issued through MAC reset pin. + * Waits for SWR reset to be cleared in DMA Mode register. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clock configured. + * @param[in] addr: EQOS virtual base address. * - * Protection: None + * @note MAC needs to be out of reset and proper clock configured. * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_poll_for_swr(void *addr) { @@ -537,18 +527,16 @@ static int eqos_poll_for_swr(void *addr) } /** - * eqos_set_mdc_clk_rate - Derive MDC clock based on provided AXI_CBB clk. - * @osi_core: OSI core private data structure. - * @csr_clk_rate: CSR (AXI CBB) clock rate. + * @brief eqos_set_mdc_clk_rate - Derive MDC clock based on provided AXI_CBB clk * - * Algorithm: MDC clock rate will be polulated OSI private data structure - * based on AXI_CBB clock rate. + * Algorithm: MDC clock rate will be polulated OSI core private data structure + * based on AXI_CBB clock rate. * - * Dependencies: - * 1) OSD layer needs get the AXI CBB clock rate with OSD clock API - * (ex - clk_get_rate()) + * @param[in] osi_core: OSI core private data structure. + * @param[in] csr_clk_rate: CSR (AXI CBB) clock rate. * - * Return: None + * @note OSD layer needs get the AXI CBB clock rate with OSD clock API + * (ex - clk_get_rate()) */ static void eqos_set_mdc_clk_rate(struct osi_core_priv_data *osi_core, unsigned long csr_clk_rate) @@ -576,19 +564,15 @@ static void eqos_set_mdc_clk_rate(struct osi_core_priv_data *osi_core, } /** - * eqos_set_speed - Set operating speed - * @base: EQOS virtual base address. - * @speed: Operating speed. + * @brief eqos_set_speed - Set operating speed * - * Algorithm: Based on the speed (10/100/1000Mbps) MAC will be configured - * accordingly. + * Algorithm: Based on the speed (10/100/1000Mbps) MAC will be configured + * accordingly. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] base: EQOS virtual base address. + * @param[in] speed: Operating speed. * - * Protection: None - * - * Return: None + * @note MAC should be init and started. see osi_start_mac() */ static void eqos_set_speed(void *base, int speed) { @@ -619,19 +603,15 @@ static void eqos_set_speed(void *base, int speed) } /** - * eqos_set_mode - Set operating mode - * @base: EQOS virtual base address - * @mode: Operating mode. + * @brief eqos_set_mode - Set operating mode * - * Algorithm: Based on the mode (HALF/FULL Duplex) MAC will be configured - * accordingly. + * Algorithm: Based on the mode (HALF/FULL Duplex) MAC will be configured + * accordingly. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] base: EQOS virtual base address + * @param[in] mode: Operating mode. * - * Protection: None - * - * Return: None + * @note MAC should be init and started. see osi_start_mac() */ static void eqos_set_mode(void *base, int mode) { @@ -650,19 +630,18 @@ static void eqos_set_mode(void *base, int mode) } /** - * eqos_calculate_per_queue_fifo - Calculate per queue FIFO size - * @fifo_size: Total Tx/RX HW FIFO size. - * @queue_count: Total number of Queues configured. + * @brief eqos_calculate_per_queue_fifo - Calculate per queue FIFO size * - * Algorithm: Total Tx/Rx FIFO size which is read from + * Algorithm: Total Tx/Rx FIFO size which is read from * MAC HW is being shared equally among the queues that are * configured. * - * Dependencies: MAC has to be out of reset. + * @param[in] fifo_size: Total Tx/RX HW FIFO size. + * @param[in] queue_count: Total number of Queues configured. * - * Protection: None + * @note MAC has to be out of reset. * - * Return: Queue size that need to be programmed + * @retval Queue size that need to be programmed. */ static unsigned int eqos_calculate_per_queue_fifo(unsigned int fifo_size, unsigned int queue_count) @@ -743,10 +722,9 @@ static unsigned int eqos_calculate_per_queue_fifo(unsigned int fifo_size, } /** - * eqos_pad_calibrate - PAD calibration - * @ioaddr: Base address of the MAC HW. + * @brief eqos_pad_calibrate - PAD calibration * - * Algorithm: + * Algorithm: * 1) Set field PAD_E_INPUT_OR_E_PWRD in reg ETHER_QOS_SDMEMCOMPPADCTRL_0 * 2) Delay for 1 usec. * 3)Set AUTO_CAL_ENABLE and AUTO_CAL_START in reg @@ -755,14 +733,14 @@ static unsigned int eqos_calculate_per_queue_fifo(unsigned int fifo_size, * 5) Re-program the value PAD_E_INPUT_OR_E_PWRD in * ETHER_QOS_SDMEMCOMPPADCTRL_0 to save power * - * Dependencies: - * 1) MAC should out of reset and clocks enabled. - * 2) RGMII and MDIO interface needs to be IDLE before performing PAD - * calibration. + * @param[in] ioaddr: Base address of the MAC HW. * - * Protection: None + * @note 1) MAC should out of reset and clocks enabled. + * 2) RGMII and MDIO interface needs to be IDLE before performing PAD + * calibration. * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_pad_calibrate(void *ioaddr) { @@ -824,19 +802,16 @@ calibration_failed: } /** - * eqos_flush_mtl_tx_queue - Flush MTL Tx queue - * @addr: OSI core private data structure. - * @qinx: MTL queue index. + * @brief eqos_flush_mtl_tx_queue - Flush MTL Tx queue * - * Algorithm: Flush a MTL Tx queue. + * @param[in] addr: OSI core private data structure. + * @param[in] qinx: MTL queue index. * - * Dependencies: - * 1) MAC should out of reset and clocks enabled. - * 2) hw core initialized. see osi_hw_core_init(). - * - * Protection: None. - * - * Return: None. + * @note 1) MAC should out of reset and clocks enabled. + * 2) hw core initialized. see osi_hw_core_init(). + * + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_flush_mtl_tx_queue(void *addr, unsigned int qinx) { @@ -875,19 +850,14 @@ static int eqos_flush_mtl_tx_queue(void *addr, unsigned int qinx) } /** - * update_ehfc_rfa_rfd - Update EHFC, RFD and RSA values - * @rx_fifo: Rx FIFO size. - * @value: Stores RFD and RSA values + * @brief update_ehfc_rfa_rfd - Update EHFC, RFD and RSA values * - * Algorithm: Calulates and stores the RSD (Threshold for Dectivating - * Flow control) and RSA (Threshold for Activating Flow Control) values - * based on the Rx FIFO size and also enables HW flow control + * Algorithm: Calulates and stores the RSD (Threshold for Dectivating + * Flow control) and RSA (Threshold for Activating Flow Control) values + * based on the Rx FIFO size and also enables HW flow control * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] rx_fifo: Rx FIFO size. + * @param[in] value: Stores RFD and RSA values */ void update_ehfc_rfa_rfd(unsigned int rx_fifo, unsigned int *value) { @@ -974,13 +944,9 @@ void update_ehfc_rfa_rfd(unsigned int rx_fifo, unsigned int *value) } /** - * eqos_configure_mtl_queue - Configure MTL Queue - * @qinx: Queue number that need to be configured. - * @osi_core: OSI core private data. - * @tx_fifo: MTL TX queue size for a MTL queue. - * @rx_fifo: MTL RX queue size for a MTL queue. + * @brief eqos_configure_mtl_queue - Configure MTL Queue * - * Algorithm: This takes care of configuring the below + * Algorithm: This takes care of configuring the below * parameters for the MTL Queue * 1) Mapping MTL Rx queue and DMA Rx channel * 2) Flush TxQ @@ -989,11 +955,15 @@ void update_ehfc_rfa_rfd(unsigned int rx_fifo, unsigned int *value) * 5) Configure TxQ weight * 6) Enable Rx Queues * - * Dependencies: MAC has to be out of reset. + * @param[in] qinx: Queue number that need to be configured. + * @param[in] osi_core: OSI core private data. + * @param[in] tx_fifo: MTL TX queue size for a MTL queue. + * @param[in] rx_fifo: MTL RX queue size for a MTL queue. + * + * @note MAC has to be out of reset. * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_configure_mtl_queue(unsigned int qinx, struct osi_core_priv_data *osi_core, @@ -1052,21 +1022,20 @@ static int eqos_configure_mtl_queue(unsigned int qinx, } /** - * eqos_config_rxcsum_offload - Enable/Disale rx checksum offload in HW - * @addr: EQOS virtual base address. - * @enabled: Flag to indicate feature is to be enabled/disabled. + * @brief eqos_config_rxcsum_offload - Enable/Disale rx checksum offload in HW * - * Algorithm: + * Algorithm: * 1) Read the MAC configuration register. * 2) Enable the IP checksum offload engine COE in MAC receiver. * 3) Update the MAC configuration register. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: EQOS virtual base address. + * @param[in] enabled: Flag to indicate feature is to be enabled/disabled. * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_rxcsum_offload(void *addr, unsigned int enabled) { @@ -1091,23 +1060,19 @@ static int eqos_config_rxcsum_offload(void *addr, unsigned int enabled) } /** - * eqos_configure_rxq_priority - Configure Priorities Selected in - * the Receive Queue + * @brief eqos_configure_rxq_priority - Configure Priorities Selected in + * the Receive Queue * - * @osi_core: OSI private data structure. - * - * Algorithm: This takes care of mapping user priority to Rx queue. + * Algorithm: This takes care of mapping user priority to Rx queue. * User provided priority mask updated to register. Valid input can have * all TC(0xFF) in one queue to None(0x00) in rx queue. * The software must ensure that the content of this field is mutually * exclusive to the PSRQ fields for other queues, that is, the same * priority is not mapped to multiple Rx queues. * - * Dependencies: MAC has to be out of reset. + * @param[in] osi_core: OSI core private data structure. * - * Protection: None - * - * Return: None + * @note MAC has to be out of reset. */ static void eqos_configure_rxq_priority(struct osi_core_priv_data *osi_core) { @@ -1161,10 +1126,9 @@ static void eqos_configure_rxq_priority(struct osi_core_priv_data *osi_core) } /** - * eqos_configure_mac - Configure MAC - * @osi_core: OSI private data structure. + * @brief eqos_configure_mac - Configure MAC * - * Algorithm: This takes care of configuring the below + * Algorithm: This takes care of configuring the below * parameters for the MAC * 1) Programming the MAC address * 2) Enable required MAC control fields in MCR @@ -1172,11 +1136,9 @@ static void eqos_configure_rxq_priority(struct osi_core_priv_data *osi_core) * 4) Disable MMC interrupts and Configure the MMC counters * 5) Enable required MAC interrupts * - * Dependencies: MAC has to be out of reset. + * @param[in] osi_core: OSI core private data structure. * - * Protection: None - * - * Return: NONE + * @note MAC has to be out of reset. */ static void eqos_configure_mac(struct osi_core_priv_data *osi_core) { @@ -1285,20 +1247,17 @@ static void eqos_configure_mac(struct osi_core_priv_data *osi_core) } /** - * eqos_configure_dma - Configure DMA - * @base: EQOS virtual base address. + * @brief eqos_configure_dma - Configure DMA * - * Algorithm: This takes care of configuring the below + * Algorithm: This takes care of configuring the below * parameters for the DMA * 1) Programming different burst length for the DMA * 2) Enable enhanced Address mode * 3) Programming max read outstanding request limit * - * Dependencies: MAC has to be out of reset. + * @param[in] base: EQOS virtual base address. * - * Protection: None - * - * Return: NONE + * @note MAC has to be out of reset. */ static void eqos_configure_dma(void *base) { @@ -1324,23 +1283,22 @@ static void eqos_configure_dma(void *base) } /** - * eqos_core_init - EQOS MAC, MTL and common DMA Initialization - * @osi_core: OSI core private data structure. - * @tx_fifo_size: MTL TX FIFO size - * @rx_fifo_size: MTL RX FIFO size + * @brief eqos_core_init - EQOS MAC, MTL and common DMA Initialization * - * Algorithm: This function will take care of initializing MAC, MTL and + * Algorithm: This function will take care of initializing MAC, MTL and * common DMA registers. * - * Dependencies: - * 1) MAC should be out of reset. See osi_poll_for_swr() for details. - * 2) osi_core->base needs to be filled based on ioremap. - * 3) osi_core->num_mtl_queues needs to be filled. - * 4) osi_core->mtl_queues[qinx] need to be filled. + * @param[in] osi_core: OSI core private data structure. + * @param[in] tx_fifo_size: MTL TX FIFO size + * @param[in] rx_fifo_size: MTL RX FIFO size * - * Protection: None + * @note 1) MAC should be out of reset. See osi_poll_for_swr() for details. + * 2) osi_core->base needs to be filled based on ioremap. + * 3) osi_core->num_mtl_queues needs to be filled. + * 4) osi_core->mtl_queues[qinx] need to be filled. * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_core_init(struct osi_core_priv_data *osi_core, unsigned int tx_fifo_size, @@ -1405,18 +1363,15 @@ static int eqos_core_init(struct osi_core_priv_data *osi_core, } /** - * eqos_handle_mac_intrs - Hanle MAC interrupts - * @osi_core: OSI core private data structure. - * @dma_isr: DMA ISR register read value. + * @brief eqos_handle_mac_intrs - Handle MAC interrupts * - * Algorithm: This function takes care of handling the + * Algorithm: This function takes care of handling the * MAC interrupts which includes speed, mode detection. * - * Dependencies: MAC interrupts need to be enabled + * @param[in] osi_core: OSI core private data structure. + * @param[in] dma_isr: DMA ISR register read value. * - * Protection: None - * - * Return: NONE + * @note MAC interrupts need to be enabled */ static void eqos_handle_mac_intrs(struct osi_core_priv_data *osi_core, unsigned int dma_isr) @@ -1470,18 +1425,13 @@ static void eqos_handle_mac_intrs(struct osi_core_priv_data *osi_core, } /** - * update_dma_sr_stats - stats for dma_status error - * @osi_core: OSI core private data structure. - * @dma_sr: Dma status register read value - * @qinx: Queue index + * @brief update_dma_sr_stats - stats for dma_status error * - * Algorithm: increament error stats based on corresponding bit filed. + * Algorithm: increament error stats based on corresponding bit filed. * - * Dependencies: None - * - * Protection: None. - * - * Return: None. + * @param[in] osi_core: OSI core private data structure. + * @param[in] dma_sr: Dma status register read value + * @param[in] qinx: Queue index */ static inline void update_dma_sr_stats(struct osi_core_priv_data *osi_core, unsigned int dma_sr, unsigned int qinx) @@ -1521,17 +1471,13 @@ static inline void update_dma_sr_stats(struct osi_core_priv_data *osi_core, } /** - * eqos_handle_common_intr - Handles common interrupt. - * @osi_core: OSI core private data structure. + * @brief eqos_handle_common_intr - Handles common interrupt. * - * Algorithm: Clear common interrupt source. + * Algorithm: Clear common interrupt source. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] osi_core: OSI core private data structure. * - * Protection: None. - * - * Return: None. + * @note MAC should be init and started. see osi_start_mac() */ static void eqos_handle_common_intr(struct osi_core_priv_data *osi_core) { @@ -1583,18 +1529,14 @@ static void eqos_handle_common_intr(struct osi_core_priv_data *osi_core) } /** - * eqos_start_mac - Start MAC Tx/Rx engine - * @addr: EQOS virtual base address. + * @brief eqos_start_mac - Start MAC Tx/Rx engine * - * Algorithm: Enable MAC Transmitter and Receiver + * Algorithm: Enable MAC Transmitter and Receiver * - * Dependencies: - * 1) MAC init should be complete. See osi_hw_core_init() and - * osi_hw_dma_init() + * @param[in] addr: EQOS virtual base address. * - * Protection: None. - * - * Return: None. + * @note 1) MAC init should be complete. See osi_hw_core_init() and + * osi_hw_dma_init() */ static void eqos_start_mac(void *addr) { @@ -1609,17 +1551,13 @@ static void eqos_start_mac(void *addr) } /** - * eqos_stop_mac - Stop MAC Tx/Rx engine - * @addr: EQOS virtual base address. + * @brief eqos_stop_mac - Stop MAC Tx/Rx engine * - * Algorithm: Disables MAC Transmitter and Receiver + * Algorithm: Disables MAC Transmitter and Receiver * - * Dependencies: - * 1) MAC DMA deinit should be complete. See osi_hw_dma_deinit() + * @param[in] addr: EQOS virtual base address. * - * Protection: None. - * - * Return: None. + * @note MAC DMA deinit should be complete. See osi_hw_dma_deinit() */ static void eqos_stop_mac(void *addr) { @@ -1635,11 +1573,9 @@ static void eqos_stop_mac(void *addr) } /** - * eqos_set_avb_algorithm - Set TxQ/TC avb config - * @osi_core: osi core priv data structure - * @avb: structure having configuration for avb algorithm + * @brief eqos_set_avb_algorithm - Set TxQ/TC avb config * - * Algorithm: + * Algorithm: * 1) Check if queue index is valid * 2) Update operation mode of TxQ/TC * 2a) Set TxQ operation mode @@ -1650,13 +1586,14 @@ static void eqos_stop_mac(void *addr) * 2f) Set low credit * 3) Update register values * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) osi_core->osd should be populated. + * @param[in] osi_core: osi core priv data structure + * @param[in] avb: structure having configuration for avb algorithm * - * Protection: None. + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->osd should be populated. * - * Return: 0: success, -1: error. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_set_avb_algorithm(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb) @@ -1732,23 +1669,19 @@ static int eqos_set_avb_algorithm(struct osi_core_priv_data *osi_core, return 0; } -/* - * eqos_config_mac_pkt_filter_reg - configure mac filter register. - * @osi_core: OSI private data structure. - * @filter: OSI filter structure. +/** + * @brief eqos_config_mac_pkt_filter_reg - configure mac filter register. * - * Algorithm: This sequence is used to configure MAC in differnet pkt + * Algorithm: This sequence is used to configure MAC in differnet pkt * processing modes like promiscuous, multicast, unicast, * hash unicast/multicast. * - * Dependencies: - * 1) MAC should be initialized and started. see osi_start_mac() - * 2) MAC addresses should be configured in HW registers. see - * osi_update_mac_addr_low_high_reg(). + * @param[in] osi_core: OSI core private data structure. + * @param[in] pfilter: OSI filter structure. * - * Protection: None - * - * Return: None + * @note 1) MAC should be initialized and started. see osi_start_mac() + * 2) MAC addresses should be configured in HW registers. see + * osi_update_mac_addr_low_high_reg(). */ static void eqos_config_mac_pkt_filter_reg(struct osi_core_priv_data *osi_core, struct osi_filter pfilter) @@ -1775,32 +1708,29 @@ static void eqos_config_mac_pkt_filter_reg(struct osi_core_priv_data *osi_core, } /** - * eqos_update_mac_addr_helper - Function to update DCS and MBC + * @brief eqos_update_mac_addr_helper - Function to update DCS and MBC * - * @osi_core: OSI private data structure. - * @*value: unsigned int pointer which has value read from register. - * @index: filter index - * @value: MAC address to write - * @dma_routing_enable: dma channel routing enable(1) - * @dma_chan: dma channel number - * @addr_mask: filter will not consider byte in comparison - * Bit 29: MAC_Address${i}_High[15:8] - * Bit 28: MAC_Address${i}_High[7:0] - * Bit 27: MAC_Address${i}_Low[31:24] - * .. - * Bit 24: MAC_Address${i}_Low[7:0] - * - * Algorithm: This helper routine is to update passed prameter value + * Algorithm: This helper routine is to update passed prameter value * based on DCS and MBC parameter. Validation of dma_chan as well as * dsc_en status performed before updating DCS bits. * - * Dependencies: - * 1) MAC should be initialized and stated. see osi_start_mac() - * 2) osi_core->osd should be populated. + * @param[in] osi_core: OSI core private data structure. + * @param[out] value: unsigned int pointer which has value read from register. + * @param[in] idx: filter index + * @param[in] dma_routing_enable: dma channel routing enable(1) + * @param[in] dma_chan: dma channel number + * @param[in] addr_mask: filter will not consider byte in comparison + * Bit 29: MAC_Address${i}_High[15:8] + * Bit 28: MAC_Address${i}_High[7:0] + * Bit 27: MAC_Address${i}_Low[31:24] + * .. + * Bit 24: MAC_Address${i}_Low[7:0] * - * Protection: None + * @note 1) MAC should be initialized and stated. see osi_start_mac() + * 2) osi_core->osd should be populated. * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static inline int eqos_update_mac_addr_helper( struct osi_core_priv_data *osi_core, @@ -1844,34 +1774,32 @@ err_dma_chan: } /** - * eqos_update_mac_addr_low_high_reg- Update L2 address - * in filter register + * @brief eqos_update_mac_addr_low_high_reg- Update L2 address in filter + * register * - * @osi_core: OSI private data structure. - * @index: filter index - * @value: MAC address to write - * @dma_routing_enable: dma channel routing enable(1) - * @dma_chan: dma channel number - * @addr_mask: filter will not consider byte in comparison - * Bit 29: MAC_Address${i}_High[15:8] - * Bit 28: MAC_Address${i}_High[7:0] - * Bit 27: MAC_Address${i}_Low[31:24] - * .. - * Bit 24: MAC_Address${i}_Low[7:0] - * @src_dest: SA(1) or DA(0) - * - * Algorithm: This routine update MAC address to register for filtering + * Algorithm: This routine update MAC address to register for filtering * based on dma_routing_enable, addr_mask and src_dest. Validation of * dma_chan as well as DCS bit enabled in RXQ to DMA mapping register * performed before updating DCS bits. * - * Dependencies: - * 1) MAC should be initialized and stated. see osi_start_mac() - * 2) osi_core->osd should be populated. + * @param[in] osi_core: OSI core private data structure. + * @param[in] idx: filter index + * @param[in] addr: MAC address to write + * @param[in] dma_routing_enable: dma channel routing enable(1) + * @param[in] dma_chan: dma channel number + * @param[in] addr_mask: filter will not consider byte in comparison + * Bit 29: MAC_Address${i}_High[15:8] + * Bit 28: MAC_Address${i}_High[7:0] + * Bit 27: MAC_Address${i}_Low[31:24] + * .. + * Bit 24: MAC_Address${i}_Low[7:0] + * @param[in] src_dest: SA(1) or DA(0) * - * Protection: None + * @note 1) MAC should be initialized and stated. see osi_start_mac() + * 2) osi_core->osd should be populated. * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_update_mac_addr_low_high_reg( struct osi_core_priv_data *osi_core, @@ -1923,11 +1851,9 @@ static int eqos_update_mac_addr_low_high_reg( } /** - * eqos_get_avb_algorithm - Get TxQ/TC avb config - * @osi_core: osi core priv data structure - * @avb: structure pointer having configuration for avb algorithm + * @brief eqos_get_avb_algorithm - Get TxQ/TC avb config * - * Algorithm: + * Algorithm: * 1) Check if queue index is valid * 2) read operation mode of TxQ/TC * 2a) read TxQ operation mode @@ -1938,13 +1864,14 @@ static int eqos_update_mac_addr_low_high_reg( * 2f) read low credit * 3) updated pointer * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) osi_core->osd should be populated. + * @param[in] osi_core: osi core priv data structure + * @param[out] avb: structure pointer having configuration for avb algorithm * - * Protection: None. + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->osd should be populated. * - * Return: 0: Success -1: Failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_get_avb_algorithm(struct osi_core_priv_data *osi_core, struct osi_core_avb_algorithm *avb) @@ -2006,27 +1933,26 @@ static int eqos_get_avb_algorithm(struct osi_core_priv_data *osi_core, } /** - * eqos_config_arp_offload - Enable/Disable ARP offload - * @mac_ver: MAC version number (different MAC HW version - * need different register offset/fields for ARP offload. - * @addr: EQOS virtual base address. - * @enable: Flag variable to enable/disable ARP offload - * @ip_addr: IP address of device to be programmed in HW. - * HW will use this IP address to respond to ARP requests. + * @brief eqos_config_arp_offload - Enable/Disable ARP offload * - * Algorithm: + * Algorithm: * 1) Read the MAC configuration register * 2) If ARP offload is to be enabled, program the IP address in * ARPPA register * 3) Enable/disable the ARPEN bit in MCR and write back to the MCR. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) Valid 4 byte IP address as argument @ip_addr + * @param[in] mac_ver: MAC version number (different MAC HW version + * need different register offset/fields for ARP offload. + * @param[in] addr: EQOS virtual base address. + * @param[in] enable: Flag variable to enable/disable ARP offload + * @param[in] ip_addr: IP address of device to be programmed in HW. + * HW will use this IP address to respond to ARP requests. * - * Protection: None. + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) Valid 4 byte IP address as argument ip_addr * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_arp_offload(unsigned int mac_ver, void *addr, unsigned int enable, @@ -2069,21 +1995,19 @@ static int eqos_config_arp_offload(unsigned int mac_ver, void *addr, return 0; } -/* - * eqos_config_l3_l4_filter_enable - register write to eanble L3/L4 +/** + * @brief eqos_config_l3_l4_filter_enable - register write to enable L3/L4 * filters. * - * @base: Base address from OSI private data structure. - * @enable: enable/disable + * Algorithm: This routine to enable/disable L4/l4 filter * - * Algorithm: This routine to enable/disable L4/l4 filter + * @param[in] base: Base address from OSI core private data structure. + * @param[in] filter_enb_dis: enable/disable * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @note MAC should be init and started. see osi_start_mac() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_l3_l4_filter_enable(void *base, unsigned int filter_enb_dis) @@ -2100,21 +2024,19 @@ static int eqos_config_l3_l4_filter_enable(void *base, } /** - * eqos_config_l2_da_perfect_inverse_match - configure register for inverse - * or perfect match. + * @brief eqos_config_l2_da_perfect_inverse_match - configure register for + * inverse or perfect match. * - * @base: Base address from OSI private data structure. - * @perfect_inverse_match: 1 - inverse mode 0- normal mode - * - * Algorithm: This sequence is used to select perfect/inverse matching + * Algorithm: This sequence is used to select perfect/inverse matching * for L2 DA * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] base: Base address from OSI core private data structure. + * @param[in] perfect_inverse_match: 1 - inverse mode 0- normal mode * - * Protection: None + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_l2_da_perfect_inverse_match(void *base, unsigned int perfect_inverse_match) @@ -2132,23 +2054,22 @@ static int eqos_config_l2_da_perfect_inverse_match(void *base, unsigned int } /** - * eqos_update_ip4_addr - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @addr: ipv4 address - * @src_dst_addr_match: 0 - source addr otherwise - dest addr + * @brief eqos_update_ip4_addr - configure register for IPV4 address filtering * - * Algorithm: This sequence is used to update IPv4 source/destination + * Algorithm: This sequence is used to update IPv4 source/destination * Address for L3 layer filtering * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) L3/L4 filtering should be enabled in MAC PFR register. See - * osi_config_l3_l4_filter_enable() + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] addr: ipv4 address + * @param[in] src_dst_addr_match: 0 - source addr otherwise - dest addr * - * Protection: None + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) L3/L4 filtering should be enabled in MAC PFR register. See + * osi_config_l3_l4_filter_enable() * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_update_ip4_addr(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -2189,23 +2110,21 @@ static int eqos_update_ip4_addr(struct osi_core_priv_data *osi_core, } /** - * eqos_update_ip6_addr - add ipv6 address in register + * @brief eqos_update_ip6_addr - add ipv6 address in register * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @addr: ipv6 adderss + * Algorithm: This sequence is used to update IPv6 source/destination + * Address for L3 layer filtering * - * Algorithm: This sequence is used to update IPv6 source/destination - * Address for L3 layer filtering + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] addr: ipv6 adderss * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) L3/L4 filtering should be enabled in MAC PFR register. See - * osi_config_l3_l4_filter_enable() + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) L3/L4 filtering should be enabled in MAC PFR register. See + * osi_config_l3_l4_filter_enable() * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_update_ip6_addr(struct osi_core_priv_data *osi_core, unsigned int filter_no, unsigned short addr[]) @@ -2254,26 +2173,24 @@ static int eqos_update_ip6_addr(struct osi_core_priv_data *osi_core, } /** - * eqos_update_l4_port_no -program source port no + * @brief eqos_update_l4_port_no -program source port no * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @port_no: port number - * @src_dst_port_match: 0 - source port, otherwise - dest port - * - * Algorithm: sequence is used to update Source Port Number for + * Algorithm: sequence is used to update Source Port Number for * L4(TCP/UDP) layer filtering. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) L3/L4 filtering should be enabled in MAC PFR register. See - * osi_config_l3_l4_filter_enable() - * 3) osi_core->osd should be populated - * 4) DCS bits should be enabled in RXQ to DMA mapping register + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] port_no: port number + * @param[in] src_dst_port_match: 0 - source port, otherwise - dest port * - * Protection: None + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) L3/L4 filtering should be enabled in MAC PFR register. See + * osi_config_l3_l4_filter_enable() + * 3) osi_core->osd should be populated + * 4) DCS bits should be enabled in RXQ to DMA mapping register * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_update_l4_port_no(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -2305,25 +2222,22 @@ static int eqos_update_l4_port_no(struct osi_core_priv_data *osi_core, } /** - * eqos_set_dcs - check and update dma routing register + * @brief eqos_set_dcs - check and update dma routing register * - * @osi_core: OSI private data structure. - * @value: unsigned int value for caller - * @dma_routing_enable: filter based dma routing enable(1) - * @dma_chan: dma channel for routing based on filter - * - * Algorithm: Check for request for DCS_enable as well as validate chan + * Algorithm: Check for request for DCS_enable as well as validate chan * number and dcs_enable is set. After validation, this sequence is used * to configure L3((IPv4/IPv6) filters for address matching. * - * Dependencies: - * 1) MAC IP should be out of reset and need to be initialized - * as the requirements. - * 2) DCS bits should be enabled in RXQ to DMA mapping register + * @param[in] osi_core: OSI core private data structure. + * @param[in] value: unsigned int value for caller + * @param[in] dma_routing_enable: filter based dma routing enable(1) + * @param[in] dma_chan: dma channel for routing based on filter * - * Protection: None + * @note 1) MAC IP should be out of reset and need to be initialized + * as the requirements. + * 2) DCS bits should be enabled in RXQ to DMA mapping register * - * Return: updated unsigned int value + *@return updated unsigned int value */ static inline unsigned int eqos_set_dcs(struct osi_core_priv_data *osi_core, unsigned int value, @@ -2344,32 +2258,30 @@ static inline unsigned int eqos_set_dcs(struct osi_core_priv_data *osi_core, return value; } /** - * eqos_config_l3_filters - config L3 filters. + * @brief eqos_config_l3_filters - config L3 filters. * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @enb_dis: 1 - enable otherwise - disable L3 filter - * @ipv4_ipv6_match: 1 - IPv6, otherwise - IPv4 - * @src_dst_addr_match: 0 - source, otherwise - destination - * @perfect_inverse_match: normal match(0) or inverse map(1) - * @dma_routing_enable: filter based dma routing enable(1) - * @dma_chan: dma channel for routing based on filter - * - * Algorithm: Check for DCS_enable as well as validate channel + * Algorithm: Check for DCS_enable as well as validate channel * number and if dcs_enable is set. After validation, code flow * is used to configure L3((IPv4/IPv6) filters resister * for address matching. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) L3/L4 filtering should be enabled in MAC PFR register. See - * osi_config_l3_l4_filter_enable() - * 3) osi_core->osd should be populated - * 4) DCS bits should be enabled in RXQ to DMA map register + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] enb_dis: 1 - enable otherwise - disable L3 filter + * @param[in] ipv4_ipv6_match: 1 - IPv6, otherwise - IPv4 + * @param[in] src_dst_addr_match: 0 - source, otherwise - destination + * @param[in] perfect_inverse_match: normal match(0) or inverse map(1) + * @param[in] dma_routing_enable: filter based dma routing enable(1) + * @param[in] dma_chan: dma channel for routing based on filter * - * Protection: None + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) L3/L4 filtering should be enabled in MAC PFR register. See + * osi_config_l3_l4_filter_enable() + * 3) osi_core->osd should be populated + * 4) DCS bits should be enabled in RXQ to DMA map register * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_l3_filters(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -2516,29 +2428,27 @@ static int eqos_config_l3_filters(struct osi_core_priv_data *osi_core, } /** - * osi_config_l4_filters - Config L4 filters. + * @brief osi_config_l4_filters - Config L4 filters. * - * @osi_core: OSI private data structure. - * @filter_no: filter index - * @enb_dis: 1 - enable, otherwise - disable L4 filter - * @tcp_udp_match: 1 - udp, 0 - tcp - * @src_dst_port_match: 0 - source port, otherwise - dest port - * @perfect_inverse_match: normal match(0) or inverse map(1) - * @dma_routing_enable: filter based dma routing enable(1) - * @dma_chan: dma channel for routing based on filter - * - * Algorithm: This sequence is used to configure L4(TCP/UDP) filters for + * Algorithm: This sequence is used to configure L4(TCP/UDP) filters for * SA and DA Port Number matching * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) L3/L4 filtering should be enabled in MAC PFR register. See - * osi_config_l3_l4_filter_enable() - * 3) osi_core->osd should be populated + * @param[in] osi_core: OSI core private data structure. + * @param[in] filter_no: filter index + * @param[in] enb_dis: 1 - enable, otherwise - disable L4 filter + * @param[in] tcp_udp_match: 1 - udp, 0 - tcp + * @param[in] src_dst_port_match: 0 - source port, otherwise - dest port + * @param[in] perfect_inverse_match: normal match(0) or inverse map(1) + * @param[in] dma_routing_enable: filter based dma routing enable(1) + * @param[in] dma_chan: dma channel for routing based on filter * - * Protection: None + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) L3/L4 filtering should be enabled in MAC PFR register. See + * osi_config_l3_l4_filter_enable() + * 3) osi_core->osd should be populated * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_l4_filters(struct osi_core_priv_data *osi_core, unsigned int filter_no, @@ -2628,23 +2538,21 @@ static int eqos_config_l4_filters(struct osi_core_priv_data *osi_core, } /** - * eqos_config_vlan_filter_reg - config vlan filter register + * @brief eqos_config_vlan_filter_reg - config vlan filter register * - * @base: Base address from OSI private data structure. - * @filter_enb_dis: vlan filter enable/disable - * @perfect_hash_filtering: perfect or hash filter - * @perfect_inverse_match: normal or inverse filter - * - * Algorithm: This sequence is used to enable/disable VLAN filtering and + * Algorithm: This sequence is used to enable/disable VLAN filtering and * also selects VLAN filtering mode- perfect/hash * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) osi_core->osd should be populated + * @param[in] osi_core: Base address from OSI core private data structure. + * @param[in] filter_enb_dis: vlan filter enable/disable + * @param[in] perfect_hash_filtering: perfect or hash filter + * @param[in] perfect_inverse_match: normal or inverse filter * - * Protection: None + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->osd should be populated * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_vlan_filtering(struct osi_core_priv_data *osi_core, unsigned int filter_enb_dis, @@ -2672,20 +2580,17 @@ static int eqos_config_vlan_filtering(struct osi_core_priv_data *osi_core, } /** - * eqos_update_vlan_id - update VLAN ID in Tag register + * @brief eqos_update_vlan_id - update VLAN ID in Tag register * - * @base: Base address from OSI private data structure. + * @param[in] base: Base address from OSI core private data structure. + * @param[in] vid: VLAN ID to be programmed. * - * Algorithm: update vid at VLAN tag register + * @note MAC should be init and started. see osi_start_mac() * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * - * Protection: None - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ -static inline int eqos_update_vlan_id(void *base, unsigned int vid) +static inline int eqos_update_vlan_id(void *base, unsigned int vid) { unsigned int value; @@ -2699,19 +2604,19 @@ static inline int eqos_update_vlan_id(void *base, unsigned int vid) } /** - * eqos_poll_for_tsinit_complete - Poll for time stamp init complete - * @addr: MAC base address. - * @mac_tcr: Address to store time stamp control register read value + * @brief eqos_poll_for_tsinit_complete - Poll for time stamp init complete * - * Algorithm: Read TSINIT value from MAC TCR register until it is + * Algorithm: Read TSINIT value from MAC TCR register until it is * equal to zero. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] mac_tcr: Address to store time stamp control register read value * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static inline int eqos_poll_for_tsinit_complete(void *addr, unsigned int *mac_tcr) @@ -2741,20 +2646,20 @@ static inline int eqos_poll_for_tsinit_complete(void *addr, } /** - * eqos_set_systime - Set system time - * @addr: MAC base address. - * @sec: Seconds to be configured - * @nsec: Nano Seconds to be configured + * @brief eqos_set_systime - Set system time * - * Algorithm: Updates system time (seconds and nano seconds) + * Algorithm: Updates system time (seconds and nano seconds) * in hardware registers * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] sec: Seconds to be configured + * @param[in] nsec: Nano Seconds to be configured * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_set_systime_to_mac(void *addr, unsigned int sec, unsigned int nsec) @@ -2789,19 +2694,19 @@ static int eqos_set_systime_to_mac(void *addr, unsigned int sec, } /** - * eqos_poll_for_tsinit_complete - Poll for addend value write complete - * @addr: MAC base address. - * @mac_tcr: Address to store time stamp control register read value + * @brief eqos_poll_for_tsinit_complete - Poll for addend value write complete * - * Algorithm: Read TSADDREG value from MAC TCR register until it is + * Algorithm: Read TSADDREG value from MAC TCR register until it is * equal to zero. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] mac_tcr: Address to store time stamp control register read value * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static inline int eqos_poll_for_addend_complete(void *addr, unsigned int *mac_tcr) @@ -2830,18 +2735,18 @@ static inline int eqos_poll_for_addend_complete(void *addr, } /** - * eqos_config_addend - Configure addend - * @addr: MAC base address. - * @addend: Addend value to be configured + * @brief eqos_config_addend - Configure addend * - * Algorithm: Updates the Addend value in HW register + * Algorithm: Updates the Addend value in HW register * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] addend: Addend value to be configured * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_config_addend(void *addr, unsigned int addend) { @@ -2871,19 +2776,19 @@ static int eqos_config_addend(void *addr, unsigned int addend) } /** - * eqos_poll_for_update_ts_complete - Poll for update time stamp - * @addr: MAC base address. - * @mac_tcr: Address to store time stamp control register read value + * @brief eqos_poll_for_update_ts_complete - Poll for update time stamp * - * Algorithm: Read time stamp update value from TCR register until it is + * Algorithm: Read time stamp update value from TCR register until it is * equal to zero. * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] mac_tcr: Address to store time stamp control register read value * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static inline int eqos_poll_for_update_ts_complete(void *addr, unsigned int *mac_tcr) @@ -2912,22 +2817,22 @@ static inline int eqos_poll_for_update_ts_complete(void *addr, } /** - * eqos_adjust_systime - Adjust system time - * @addr: MAC base address. - * @sec: Seconds to be configured - * @nsec: Nano seconds to be configured - * @add_sub: To decide on add/sub with system time - * @one_nsec_accuracy: One nano second accuracy + * @brief eqos_adjust_systime - Adjust system time * - * Algorithm: Update the system time + * Algorithm: Update the system time * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * 2) osi_core->ptp_config.one_nsec_accuracy need to be set to 1 + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] sec: Seconds to be configured + * @param[in] nsec: Nano seconds to be configured + * @param[in] add_sub: To decide on add/sub with system time + * @param[in] one_nsec_accuracy: One nano second accuracy * - * Protection: None. + * @note 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->ptp_config.one_nsec_accuracy need to be set to 1 * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_adjust_systime(void *addr, unsigned int sec, unsigned int nsec, unsigned int add_sub, @@ -2998,17 +2903,17 @@ static int eqos_adjust_systime(void *addr, unsigned int sec, unsigned int nsec, } /** - * eqos_get_systime - Get system time from MAC - * @addr: MAC base address. + * @brief eqos_get_systime - Get system time from MAC * - * Algorithm: Get current system time + * Algorithm: Get current system time * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. * - * Protection: None. + * @note MAC should be init and started. see osi_start_mac() * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static unsigned long long eqos_get_systime_from_mac(void *addr) { @@ -3046,19 +2951,14 @@ static unsigned long long eqos_get_systime_from_mac(void *addr) } /** - * eqos_config_tscr - Configure Time Stamp Register - * @addr: MAC base address. - * @ptp_filter: PTP rx filter parameters + * @brief eqos_config_tscr - Configure Time Stamp Register * - * Algorithm: Configure Time Stamp Register + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] ptp_filter: PTP rx filter parameters * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * - * Protection: None. - * - * Return: None. - **/ + * @note MAC should be init and started. see osi_start_mac() + */ static void eqos_config_tscr(void *addr, unsigned int ptp_filter) { unsigned int mac_tcr = 0; @@ -3122,18 +3022,13 @@ static void eqos_config_tscr(void *addr, unsigned int ptp_filter) } /** - * eqos_config_ssir - Configure SSIR - * @addr: MAC base address. - * @ptp_clock: PTP clock + * @brief eqos_config_ssir - Configure SSIR * - * Algorithm: Configure Sub Second Increment Register + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] ptp_clock: PTP clock * - * Dependencies: - * 1) MAC should be init and started. see osi_start_mac() - * - * Protection: None. - * - * Return: None. + * @note MAC should be init and started. see osi_start_mac() */ static void eqos_config_ssir(void *addr, unsigned int ptp_clock) { @@ -3169,16 +3064,13 @@ static void eqos_config_ssir(void *addr, unsigned int ptp_clock) } /** - * eqos_core_deinit - EQOS MAC core deinitialization - * @osi_core: OSI core private data structure. + * @brief eqos_core_deinit - EQOS MAC core deinitialization * - * Algorithm: This function will take care of deinitializing MAC + * Algorithm: This function will take care of deinitializing MAC * - * Dependencies: Required clks and resets has to be enabled + * @param[in] osi_core: OSI core private data structure. * - * Protection: None - * - * Return: None + * @note Required clks and resets has to be enabled */ static void eqos_core_deinit(struct osi_core_priv_data *osi_core) { @@ -3186,6 +3078,9 @@ static void eqos_core_deinit(struct osi_core_priv_data *osi_core) eqos_stop_mac(osi_core->base); } +/** + * @brief eqos_core_ops - EQOS MAC core operations + */ static struct osi_core_ops eqos_core_ops = { .poll_for_swr = eqos_poll_for_swr, .core_init = eqos_core_init, @@ -3230,11 +3125,17 @@ static struct osi_core_ops eqos_core_ops = { .reset_mmc = eqos_reset_mmc, }; +/** + * @brief eqos_get_core_safety_config - EQOS MAC safety configuration + */ void *eqos_get_core_safety_config(void) { return &eqos_core_safety_config; } +/** + * @brief eqos_get_hw_core_ops - EQOS MAC get core operations + */ struct osi_core_ops *eqos_get_hw_core_ops(void) { return &eqos_core_ops; diff --git a/osi/core/eqos_core.h b/osi/core/eqos_core.h index 93b7851..0d49f5b 100644 --- a/osi/core/eqos_core.h +++ b/osi/core/eqos_core.h @@ -23,8 +23,12 @@ #ifndef EQOS_CORE_H_ #define EQOS_CORE_H_ -/* These bits control the threshold (fill-level of Rx queue) at which +/** + * @addtogroup EQOS-FC Flow Control Threshold Macros + * + * @brief These bits control the threshold (fill-level of Rx queue) at which * the flow control is asserted or de-asserted + * @{ */ #define FULL_MINUS_1_5K (unsigned int)1 #define FULL_MINUS_2_K (unsigned int)2 @@ -34,20 +38,26 @@ #define FULL_MINUS_6_K (unsigned int)10 #define FULL_MINUS_10_K (unsigned int)18 #define FULL_MINUS_16_K (unsigned int)30 +/** @} */ /** - * MTL queue operation mode - * EQOS_MTL_QUEUE_DISABLED - queue disabled - * EQOS_MTL_QUEUE_QAVB - queue in AVB mode - * EQOS_MTL_QUEUE_QDCB - queue in DCB mode - * EQOS_MTL_QUEUE_QGENERIC - queue in gerneric mode + * @addtogroup EQOS-MTLQ MTL queue operation mode + * + * @brief MTL queue operation mode options + * @{ */ #define EQOS_MTL_QUEUE_DISABLED 0x0U #define EQOS_MTL_QUEUE_AVB 0x1U #define EQOS_MTL_QUEUE_DCB 0x2U #define EQOS_MTL_QUEUE_GENERIC 0x3U +/** @} */ -/* MDC Clock Selection define*/ +/** + * @addtogroup EQOS-MDC MDC Clock Selection defines + * + * @brief MDC Clock defines + * @{ + */ #define EQOS_CSR_60_100M 0x0 /* MDC = clk_csr/42 */ #define EQOS_CSR_100_150M 0x1 /* MDC = clk_csr/62 */ #define EQOS_CSR_20_35M 0x2 /* MDC = clk_csr/16 */ @@ -56,11 +66,24 @@ #define EQOS_CSR_250_300M 0x5 /* MDC = clk_csr/124 */ #define EQOS_CSR_300_500M 0x6 /* MDC = clk_csr/204 */ #define EQOS_CSR_500_800M 0x7 /* MDC = clk_csr/324 */ +/** @} */ +/** + * @addtogroup EQOS-SIZE SIZE calculation helper Macros + * + * @brief SIZE calculation defines + * @{ + */ #define FIFO_SIZE_B(x) (x) #define FIFO_SIZE_KB(x) ((x) * 1024U) +/** @} */ -/* per queue fifo size programmable value */ +/** + * @addtogroup EQOS-QUEUE QUEUE fifo size programmable values + * + * @brief Queue FIFO size programmable values + * @{ + */ #define EQOS_256 0x00U #define EQOS_512 0x01U #define EQOS_1K 0x03U @@ -71,8 +94,14 @@ #define EQOS_16K 0x3FU #define EQOS_32K 0x7FU #define EQOS_36K 0x8FU +/** @} */ -/* EQOS HW Registers */ +/** + * @addtogroup EQOS-HW Hardware Register offsets + * + * @brief EQOS HW register offsets + * @{ + */ #define EQOS_5_00_MAC_ARPPA 0x0210 #define EQOS_4_10_MAC_ARPPA 0x0AE0 #define EQOS_DMA_SBUS 0x1004 @@ -120,8 +149,14 @@ #define EQOS_MAC_STSUR 0x0B10 #define EQOS_MAC_STNSUR 0x0B14 #define EQOS_MAC_TAR 0x0B18 +/** @} */ -/* EQOS MTL registers*/ +/** + * @addtogroup EQOS-MTL MTL HW Register offsets + * + * @brief EQOS MTL HW Register offsets + * @{ + */ #define EQOS_MTL_CHX_TX_OP_MODE(x) ((0x0040U * (x)) + 0x0D00U) #define EQOS_MTL_TXQ_QW(x) ((0x0040U * (x)) + 0x0D18U) #define EQOS_MTL_CHX_RX_OP_MODE(x) ((0x0040U * (x)) + 0x0D30U) @@ -131,14 +166,26 @@ #define EQOS_MTL_TXQ_ETS_LCR(x) ((0x0040U * (x)) + 0x0D24U) #define EQOS_MTL_RXQ_DMA_MAP0 0x0C30 #define EQOS_MTL_OP_MODE 0x0C00 +/** @} */ -/* EQOS Wrapper registers*/ +/** + * @addtogroup EQOS-Wrapper EQOS Wrapper HW Register offsets + * + * @brief EQOS Wrapper register offsets + * @{ + */ #define EQOS_PAD_AUTO_CAL_CFG 0x8804U #define EQOS_PAD_AUTO_CAL_STAT 0x880CU #define EQOS_PAD_CRTL 0x8800U #define EQOS_CLOCK_CTRL_0 0x8000U +/** @} */ -/* EQOS Register BIT Masks */ +/** + * @addtogroup HW Register BIT values + * + * @brief consists of corresponding EQOS MAC, MTL register bit values + * @{ + */ #define EQOS_PAD_AUTO_CAL_CFG_ENABLE OSI_BIT(29) #define EQOS_PAD_AUTO_CAL_CFG_START OSI_BIT(31) #define EQOS_PAD_AUTO_CAL_STAT_ACTIVE OSI_BIT(31) @@ -335,11 +382,25 @@ #define EQOS_DMA_CHX_STATUS_RPS OSI_BIT(8) #define EQOS_DMA_CHX_STATUS_RWT OSI_BIT(9) #define EQOS_DMA_CHX_STATUS_FBE OSI_BIT(10) +/** @} */ +/** + * @brief update_ehfc_rfa_rfd - Update EHFC, RFD and RSA values + * + * Algorithm: Calculates and stores the RSD (Threshold for Deactivating + * Flow control) and RSA (Threshold for Activating Flow Control) values + * based on the Rx FIFO size and also enables HW flow control + * + * @param[in] rx_fifo: Rx FIFO size. + * @param[in] value: Stores RFD and RSA values + */ void update_ehfc_rfa_rfd(unsigned int rx_fifo, unsigned int *value); -/* Below macros are used for periodic reg validation for functional safety. - * HW register mask - to mask reserved and self-clearing bits +/** + * @addtogroup EQOS-Safety-Register EQOS Safety Register Mask + * + * @brief EQOS HW register masks and index + * @{ */ #define EQOS_MAC_MCR_MASK 0xFFFFFF7FU #define EQOS_MAC_PFR_MASK 0x803107FFU @@ -398,21 +459,22 @@ void update_ehfc_rfa_rfd(unsigned int rx_fifo, unsigned int *value); #define EQOS_MTL_CH3_RX_OP_MODE_IDX 29U #define EQOS_DMA_SBUS_IDX 30U #define EQOS_MAX_CORE_SAFETY_REGS 31U +/** @} */ /** - * struct core_func_safety - Struct used to store last written values of + * @brief core_func_safety - Struct used to store last written values of * critical core HW registers. - * @reg_addr: Array of reg MMIO addresses (base of EQoS + offset of reg) - * @reg_mask: Array of bit-mask value of each corresponding reg (used to - * ignore self-clearing/reserved bits in reg). - * @reg_val: Array of value stored in each corresponding register. - * @core_safety_lock: OSI lock variable used to protect writes to reg while - * validation is in-progress. */ struct core_func_safety { + /** Array of reg MMIO addresses (base of EQoS + offset of reg) */ void *reg_addr[EQOS_MAX_CORE_SAFETY_REGS]; + /** Array of bit-mask value of each corresponding reg + * (used to ignore self-clearing/reserved bits in reg) */ unsigned int reg_mask[EQOS_MAX_CORE_SAFETY_REGS]; + /** Array of value stored in each corresponding register */ unsigned int reg_val[EQOS_MAX_CORE_SAFETY_REGS]; + /** OSI lock variable used to protect writes to reg while + * validation is in-progress */ unsigned int core_safety_lock; }; #endif diff --git a/osi/core/eqos_mmc.c b/osi/core/eqos_mmc.c index 51975cd..2e5c8da 100644 --- a/osi/core/eqos_mmc.c +++ b/osi/core/eqos_mmc.c @@ -27,22 +27,21 @@ #include "eqos_core.h" /** - * update_mmc_val - function to read resgister and return vlaue to callee + * @brief update_mmc_val - function to read register and return value to callee * - * @osi_core: OSI core private data structure. - * @last_vlaue: previous value of stats variable. - * @offset: HW register offset + * Algorithm: Read the registers, check for boundary, if more, reset + * counters else return same to caller. * - * Algorithm: Read the registers, check for boundary, if more, reset - * counters else return same to caller. + * @param[in] osi_core: OSI core private data structure. + * @param[in] last_value: previous value of stats variable. + * @param[in] offset: HW register offset * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated * - * Protection: None - * - * Return: unsigned value + * @retval 0 on success + * @retval -1 on failure */ static inline unsigned long update_mmc_val(struct osi_core_priv_data *osi_core, unsigned long last_value, @@ -66,19 +65,14 @@ static inline unsigned long update_mmc_val(struct osi_core_priv_data *osi_core, } /** - * eqos_reset_mmc - To reset MMC registers and ether_mmc_counter structure - * variable - * @osi_core: OSI core private data structure. + * @brief eqos_reset_mmc - To reset MMC registers and ether_mmc_counter + * structure variable * - * Algorithm: reset HW counter and structure variable value. + * @param[in] osi_core: OSI core private data structure. * - * Dependencies: + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated - * - * Protection: None - * - * Return: None */ void eqos_reset_mmc(struct osi_core_priv_data *osi_core) { @@ -92,20 +86,17 @@ void eqos_reset_mmc(struct osi_core_priv_data *osi_core) } /** - * eqos_read_mmc - To read MMC registers and ether_mmc_counter structure - * variable - * @osi_core: OSI core private data structure. + * @brief eqos_read_mmc - To read MMC registers and ether_mmc_counter structure + * variable * - * Algorithm: Pass register offset and old value to helper function and - * update structure. + * Algorithm: Pass register offset and old value to helper function and + * update structure. * - * Dependencies: + * @param[in] osi_core: OSI core private data structure. + * + * @note * 1) MAC should be init and started. see osi_start_mac() * 2) osi_core->osd should be populated - * - * Protection: None - * - * Return: None */ void eqos_read_mmc(struct osi_core_priv_data *osi_core) { diff --git a/osi/core/eqos_mmc.h b/osi/core/eqos_mmc.h index d581792..8c293fa 100644 --- a/osi/core/eqos_mmc.h +++ b/osi/core/eqos_mmc.h @@ -23,6 +23,12 @@ #ifndef EQOS_MMC_H_ #define EQOS_MMC_H_ +/** + * @addtogroup EQOS-MMC MMC HW register offsets + * + * @brief MMC HW register offsets + * @{ + */ #define MMC_TXOCTETCOUNT_GB 0x00714 #define MMC_TXPACKETCOUNT_GB 0x00718 #define MMC_TXBROADCASTPACKETS_G 0x0071c @@ -103,7 +109,32 @@ #define MMC_RXTCP_ERR_OCTETS 0x0087c #define MMC_RXICMP_GD_OCTETS 0x00880 #define MMC_RXICMP_ERR_OCTETS 0x00884 +/** @} */ +/** + * @brief eqos_read_mmc - To read MMC registers and ether_mmc_counter structure + * variable + * + * Algorithm: Pass register offset and old value to helper function and + * update structure. + * + * @param[in] osi_core: OSI core private data structure. + * + * @note + * 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->osd should be populated + */ void eqos_read_mmc(struct osi_core_priv_data *osi_core); + +/** + * @brief eqos_reset_mmc - To reset MMC registers and ether_mmc_counter + * structure variable + * + * @param[in] osi_core: OSI core private data structure. + * + * @note + * 1) MAC should be init and started. see osi_start_mac() + * 2) osi_core->osd should be populated + */ void eqos_reset_mmc(struct osi_core_priv_data *osi_core); #endif diff --git a/osi/core/osi_core.c b/osi/core/osi_core.c index 5523816..165aece 100644 --- a/osi/core/osi_core.c +++ b/osi/core/osi_core.c @@ -23,6 +23,11 @@ #include #include +/** + * @addtogroup MDIO Macros + * @brief Helper MACROS for MDIO + * @{ + */ #define MAC_MDIO_ADDRESS 0x200 #define MAC_GMII_BUSY 0x00000001U @@ -34,7 +39,18 @@ #define MDIO_PHY_ADDR_SHIFT 21U #define MDIO_PHY_REG_SHIFT 16U #define MDIO_MII_WRITE OSI_BIT(2) +/** @} */ +/** + * @brief poll_for_mii_idle Query the status of an ongoing DMA transfer + * + * @param[in] osi_core: OSI Core private data structure. + * + * @note MAC needs to be out of reset and proper clock configured. + * + * @retval 0 on Success + * @retval -1 on Failure + */ static inline int poll_for_mii_idle(struct osi_core_priv_data *osi_core) { unsigned int retry = 1000; @@ -645,20 +661,19 @@ int osi_set_systime_to_mac(struct osi_core_priv_data *osi_core, } /** - * div_u64_rem - updates remainder and returns Quotient - * @dividend: Dividend value - * @divisor: Divisor value - * @remainder: Remainder + *@brief div_u64_rem - updates remainder and returns Quotient * - * Algorithm: Dividend will be divided by divisor and stores the - * remainder value and returns quotient + * Algorithm: Dividend will be divided by divisor and stores the + * remainder value and returns quotient * - * Dependencies: MAC IP should be out of reset - * and need to be initialized as the requirements + * @param[in] dividend: Dividend value + * @param[in] divisor: Divisor value + * @param[out] remain: Remainder * - * Protection: None + * @note MAC IP should be out of reset and need to be initialized as the + * requirements * - * Return: Quotient + * @returns Quotient */ static inline unsigned long div_u64_rem(unsigned long dividend, unsigned long divisor, @@ -676,18 +691,15 @@ static inline unsigned long div_u64_rem(unsigned long dividend, } /** - * div_u64 - Calls a function which returns quotient - * @dividend: Dividend - * @divisor: Divisor + * @brief div_u64 - Calls a function which returns quotient * - * Algorithm: Calls a function which returns quotient. + * @param[in] dividend: Dividend + * @param[in] divisor: Divisor * - * Dependencies: MAC IP should be out of reset - * and need to be initialized as the requirements. + * @note MAC IP should be out of reset and need to be initialized as the + * requirements. * - * Protection: None - * - * Return: Quotient + * @returns Quotient */ static inline unsigned long div_u64(unsigned long dividend, unsigned long divisor) diff --git a/osi/dma/eqos_dma.c b/osi/dma/eqos_dma.c index 1d270fb..e7e501b 100644 --- a/osi/dma/eqos_dma.c +++ b/osi/dma/eqos_dma.c @@ -24,15 +24,15 @@ #include #include "eqos_dma.h" +/** + * @brief eqos_dma_safety_config - EQOS MAC DMA safety configuration + */ static struct dma_func_safety eqos_dma_safety_config; /** - * eqos_dma_safety_writel - Write to safety critical register. - * @val: Value to be written. - * @addr: memory mapped register address to be written to. - * @idx: Index of register corresponding to enum func_safety_dma_regs. + * @brief Write to safety critical register. * - * Algorithm: + * Algorithm: * 1) Acquire RW lock, so that eqos_validate_dma_regs does not run while * updating the safety critical register. * 2) call osi_writel() to actually update the memory mapped register. @@ -40,12 +40,11 @@ static struct dma_func_safety eqos_dma_safety_config; * this latest value will be compared when eqos_validate_dma_regs is * scheduled. * - * Dependencies: - * 1) MAC has to be out of reset, and clocks supplied. + * @param[in] val: Value to be written. + * @param[in] addr: memory mapped register address to be written to. + * @param[in] idx: Index of register corresponding to enum func_safety_dma_regs. * - * Protection: None. - * - * Return: None. + * @note MAC has to be out of reset, and clocks supplied. */ static inline void eqos_dma_safety_writel(unsigned int val, void *addr, unsigned int idx) @@ -59,21 +58,16 @@ static inline void eqos_dma_safety_writel(unsigned int val, void *addr, } /** - * eqos_dma_safety_init - Initialize the eqos_dma_safety_config. - * @base_addr: Base address of memory mapped register space. + * @brief Initialize the eqos_dma_safety_config. * - * Algorithm: Populate the list of safety critical registers and provide + * @param[in] osi_dma: OSI DMA private data structure. + * + * Algorithm: Populate the list of safety critical registers and provide * 1) the address of the register * 2) Register mask (to ignore reserved/self-critical bits in the reg). - * See @eqos_validate_dma_regs which can be ivoked periodically to compare + * See eqos_validate_dma_regs which can be ivoked periodically to compare * the last written value to this register vs the actual value read when * eqos_validate_dma_regs is scheduled. - * - * Dependencies: None - * - * Protection: None - * - * Return: None */ static void eqos_dma_safety_init(struct osi_dma_priv_data *osi_dma) { @@ -131,21 +125,22 @@ static void eqos_dma_safety_init(struct osi_dma_priv_data *osi_dma) } /** - * eqos_validate_dma_regs - Read-validate HW registers for functional safety. - * @osi_dma: OSI dma private data structure. - * Algorithm: Reads pre-configured list of MAC/MTL configuration registers + * @brief Read-validate HW registers for functional safety. + * + * Algorithm: Reads pre-configured list of MAC/MTL configuration registers * and compares with last written value for any modifications. * - * Dependencies: + * @param[in] osi_dma: OSI DMA private data structure. + * + * @note * 1) MAC has to be out of reset. * 2) osi_hw_dma_init has to be called. Internally this would initialize - * the safety_config (see @osi_dma_priv_data) based on MAC version and + * the safety_config (see osi_dma_priv_data) based on MAC version and * which specific registers needs to be validated periodically. * 3) Invoke this call iff (osi_dma_priv_data->safety_config != OSI_NULL) * - * Protection: None - * - * Return: 0 - success, -1 - failure + * @retval 0 on success + * @retval -1 on failure. */ static int eqos_validate_dma_regs(struct osi_dma_priv_data *osi_dma) { @@ -180,21 +175,16 @@ static int eqos_validate_dma_regs(struct osi_dma_priv_data *osi_dma) } /** - * eqos_disable_chan_tx_intr - Disables DMA Tx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Tx channel number. + * @brief eqos_disable_chan_tx_intr - Disables DMA Tx channel interrupts. * - * Algorithm: Disables Tx interrupts at wrapper level. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. - * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * 3) Mapping of physical IRQ line to DMA channel need to be maintained at + * OSDependent layer and pass corresponding channel number. */ static void eqos_disable_chan_tx_intr(void *addr, unsigned int chan) { @@ -206,21 +196,16 @@ static void eqos_disable_chan_tx_intr(void *addr, unsigned int chan) } /** - * eqos_enable_chan_tx_intr - Enable Tx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Tx channel number. + * @brief eqos_enable_chan_tx_intr - Enable Tx channel interrupts. * - * Algorithm: Enables EQOS DMA tx channel interrupts. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. - * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * 3) Mapping of physical IRQ line to DMA channel need to be maintained at + * OSDependent layer and pass corresponding channel number. */ static void eqos_enable_chan_tx_intr(void *addr, unsigned int chan) { @@ -232,19 +217,16 @@ static void eqos_enable_chan_tx_intr(void *addr, unsigned int chan) } /** - * eqos_disable_chan_rx_intr - Disable Rx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Rx channel number. + * @brief eqos_disable_chan_rx_intr - Disable Rx channel interrupts. * - * Algorithm: Disables EQOS DMA rx channel interrupts. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) Mapping of physical IRQ line to DMA channel need to be maintained at - * OSDependent layer and pass corresponding channel number. - * Protection: None. - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * 3) Mapping of physical IRQ line to DMA channel need to be maintained at + * OSDependent layer and pass corresponding channel number. */ static void eqos_disable_chan_rx_intr(void *addr, unsigned int chan) { @@ -256,19 +238,14 @@ static void eqos_disable_chan_rx_intr(void *addr, unsigned int chan) } /** - * eqos_enable_chan_rx_intr - Enable Rx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Rx channel number. + * @brief eqos_enable_chan_rx_intr - Enable Rx channel interrupts. * - * Algorithm: Enables EQOS DMA Rx channel interrupts. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init */ static void eqos_enable_chan_rx_intr(void *addr, unsigned int chan) { @@ -280,21 +257,18 @@ static void eqos_enable_chan_rx_intr(void *addr, unsigned int chan) } /** - * eqos_clear_tx_intr - Handle EQOS DMA Tx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Tx channel number. + * @brief eqos_clear_tx_intr - Handle EQOS DMA Tx channel interrupts. * - * Algorithm: Clear DMA Tx interrupt source at wrapper and DMA level. + * Algorithm: Clear DMA Tx interrupt source at wrapper and DMA level. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. + * + * @note 1) MAC needs to be out of reset and proper clocks need to be configured * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at * OSDependent layer and pass corresponding channel number. - * - * Protection: None. - * - * Return: None. */ static void eqos_clear_tx_intr(void *addr, unsigned int chan) { @@ -310,21 +284,18 @@ static void eqos_clear_tx_intr(void *addr, unsigned int chan) } /** - * eqos_clear_rx_intr - Handles DMA Rx channel interrupts. - * @addr: MAC base address. - * @chan: DMA Rx channel number. + * @brief eqos_clear_rx_intr - Handles DMA Rx channel interrupts. * - * Algorithm: Clear DMA Rx interrupt source at wrapper and DMA level. + * Algorithm: Clear DMA Rx interrupt source at wrapper and DMA level. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. + * + * @note 1) MAC needs to be out of reset and proper clocks need to be configured * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init * 3) Mapping of physical IRQ line to DMA channel need to be maintained at * OSDependent layer and pass corresponding channel number. - * - * Protection: None. - * - * Return: None. */ static void eqos_clear_rx_intr(void *addr, unsigned int chan) { @@ -340,18 +311,14 @@ static void eqos_clear_rx_intr(void *addr, unsigned int chan) } /** - * eqos_set_tx_ring_len - Set DMA Tx ring length. - * @addr: MAC base address. - * @chan: DMA Tx channel number. - * @len: Length. + * @brief eqos_set_tx_ring_len - Set DMA Tx ring length. * - * Algorithm: Set DMA Tx channel ring length for specific channel. + * Algorithm: Set DMA Tx channel ring length for specific channel. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. + * @param[in] len: Length. */ static void eqos_set_tx_ring_len(void *addr, unsigned int chan, unsigned int len) @@ -362,18 +329,14 @@ static void eqos_set_tx_ring_len(void *addr, unsigned int chan, } /** - * eqos_set_tx_ring_start_addr - Set DMA Tx ring base address. - * @addr: MAC base address. - * @chan: DMA Tx channel number. - * @tx_desc: Tx desc base addess. + * @brief eqos_set_tx_ring_start_addr - Set DMA Tx ring base address. * - * Algorithm: Sets DMA Tx ring base address for specific channel. + * Algorithm: Sets DMA Tx ring base address for specific channel. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. + * @param[in] tx_desc: Tx desc base addess. */ static void eqos_set_tx_ring_start_addr(void *addr, unsigned int chan, unsigned long tx_desc) @@ -383,20 +346,18 @@ static void eqos_set_tx_ring_start_addr(void *addr, unsigned int chan, } /** - * eqos_update_tx_tailptr - Updates DMA Tx ring tail pointer. - * @addr: MAC base address. - * @chan: DMA Tx channel number. - * @tailptr: DMA Tx ring tail pointer. + * @brief eqos_update_tx_tailptr - Updates DMA Tx ring tail pointer. * - * Algorithm: Updates DMA Tx ring tail pointer for specific channel. + * Algorithm: Updates DMA Tx ring tail pointer for specific channel. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx channel number. + * @param[in] tailptr: DMA Tx ring tail pointer. + * + * + * @note 1) MAC needs to be out of reset and proper clocks need to be configured * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * - * Protection: None. - * - * Return: None. */ static void eqos_update_tx_tailptr(void *addr, unsigned int chan, unsigned long tailptr) @@ -405,18 +366,14 @@ static void eqos_update_tx_tailptr(void *addr, unsigned int chan, } /** - * eqos_set_rx_ring_len - Set Rx channel ring length. - * @addr: MAC base address. - * @chan: DMA Rx channel number. - * @len: Length + * @brief eqos_set_rx_ring_len - Set Rx channel ring length. * - * Algorithm: Sets DMA Rx channel ring length for specific DMA channel. + * Algorithm: Sets DMA Rx channel ring length for specific DMA channel. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. + * @param[in] len: Length */ static void eqos_set_rx_ring_len(void *addr, unsigned int chan, unsigned int len) @@ -427,18 +384,14 @@ static void eqos_set_rx_ring_len(void *addr, unsigned int chan, } /** - * eqos_set_rx_ring_start_addr - Set DMA Rx ring base address. - * @addr: MAC base address. - * @chan: DMA Rx channel number. - * @tx_desc: DMA Rx desc base address. + * @brief eqos_set_rx_ring_start_addr - Set DMA Rx ring base address. * - * Algorithm: Sets DMA Rx channel ring base address. + * Algorithm: Sets DMA Rx channel ring base address. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. + * @param[in] tx_desc: DMA Rx desc base address. */ static void eqos_set_rx_ring_start_addr(void *addr, unsigned int chan, unsigned long tx_desc) @@ -448,41 +401,36 @@ static void eqos_set_rx_ring_start_addr(void *addr, unsigned int chan, } /** - * eqos_update_rx_tailptr - Update Rx ring tail pointer - * @addr: MAC base address. - * @chan: DMA Rx channel number. - * @tailptr: Tail pointer + * @brief eqos_update_rx_tailptr - Update Rx ring tail pointer * - * Algorithm: Updates DMA Rx channel tail pointer for specific channel. + * Algorithm: Updates DMA Rx channel tail pointer for specific channel. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Rx channel number. + * @param[in] tailptr: Tail pointer * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init */ static void eqos_update_rx_tailptr(void *addr, unsigned int chan, unsigned long tailptr) { - osi_writel((unsigned int)L32(tailptr), (unsigned char *)addr + EQOS_DMA_CHX_RDTP(chan)); + osi_writel((unsigned int)L32(tailptr), (unsigned char *)addr + + EQOS_DMA_CHX_RDTP(chan)); } /** - * eqos_start_dma - Start DMA. - * @addr: MAC base address. - * @chan: DMA Tx/Rx channel number. + * @brief eqos_start_dma - Start DMA. * - * Algorithm: Start Tx and Rx DMA for specific channel. + * Algorithm: Start Tx and Rx DMA for specific channel. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx/Rx channel number. * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init */ static void eqos_start_dma(void *addr, unsigned int chan) { @@ -504,19 +452,16 @@ static void eqos_start_dma(void *addr, unsigned int chan) } /** - * eqos_stop_dma - Stop DMA. - * @addr: MAC base address. - * @chan: DMA Tx/Rx channel number. + * @brief eqos_stop_dma - Stop DMA. * - * Algorithm: Start Tx and Rx DMA for specific channel. + * Algorithm: Start Tx and Rx DMA for specific channel. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * @param[in] addr: Base address indicating the start of + * memory mapped IO region of the MAC. + * @param[in] chan: DMA Tx/Rx channel number. * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init */ static void eqos_stop_dma(void *addr, unsigned int chan) { @@ -538,11 +483,9 @@ static void eqos_stop_dma(void *addr, unsigned int chan) } /** - * eqos_configure_dma_channel - Configure DMA channel - * @chan: DMA channel number that need to be configured. - * @osi_dma: OSI DMA private data structure. + * @brief eqos_configure_dma_channel - Configure DMA channel * - * Algorithm: This takes care of configuring the below + * Algorithm: This takes care of configuring the below * parameters for the DMA channel * 1) Enabling DMA channel interrupts * 2) Enable 8xPBL mode @@ -550,11 +493,10 @@ static void eqos_stop_dma(void *addr, unsigned int chan) * 4) Enable TSO if HW supports * 5) Program Rx Watchdog timer * - * Dependencies: MAC has to be out of reset. + * @param[in] chan: DMA channel number that need to be configured. + * @param[in] osi_dma: OSI DMA private data structure. * - * Protection: None - * - * Return: NONE + * @note MAC has to be out of reset. */ static void eqos_configure_dma_channel(unsigned int chan, struct osi_dma_priv_data *osi_dma) @@ -639,16 +581,9 @@ static void eqos_configure_dma_channel(unsigned int chan, } /** - * eqos_init_dma_channel - DMA channel INIT - * @osi_dma: OSI DMA private data structure. + * @brief eqos_init_dma_channel - DMA channel INIT * - * Description: Initialise all DMA channels. - * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] osi_dma: OSI DMA private data structure. */ static void eqos_init_dma_channel(struct osi_dma_priv_data *osi_dma) { @@ -663,20 +598,14 @@ static void eqos_init_dma_channel(struct osi_dma_priv_data *osi_dma) } /** - * eqos_set_rx_buf_len - Set Rx buffer length - * @osi_dma: OSI DMA private data structure. + * @brief eqos_set_rx_buf_len - Set Rx buffer length + * Sets the Rx buffer length based on the new MTU size set. * - * Description: Sets the Rx buffer lenght based on the new MTU size set. + * @param[in] osi_dma: OSI DMA private data structure. * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) osi_dma->mtu need to be filled with current MTU size <= 9K - * - * - * Protection: None. - * - * Return: None. + * @note 1) MAC needs to be out of reset and proper clocks need to be configured + * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init + * 3) osi_dma->mtu need to be filled with current MTU size <= 9K */ static void eqos_set_rx_buf_len(struct osi_dma_priv_data *osi_dma) { @@ -699,6 +628,10 @@ static void eqos_set_rx_buf_len(struct osi_dma_priv_data *osi_dma) ~(EQOS_AXI_BUS_WIDTH - 1U)); } +/** + * @brief eqos_dma_chan_ops - EQOS DMA operations + * + */ static struct osi_dma_chan_ops eqos_dma_chan_ops = { .set_tx_ring_len = eqos_set_tx_ring_len, .set_rx_ring_len = eqos_set_rx_ring_len, @@ -719,11 +652,17 @@ static struct osi_dma_chan_ops eqos_dma_chan_ops = { .validate_regs = eqos_validate_dma_regs, }; +/** + * @brief eqos_get_dma_safety_config - EQOS get DMA safety configuration + */ void *eqos_get_dma_safety_config(void) { return &eqos_dma_safety_config; } +/** + * @brief eqos_get_dma_chan_ops - EQOS get DMA channel operations + */ struct osi_dma_chan_ops *eqos_get_dma_chan_ops(void) { return &eqos_dma_chan_ops; diff --git a/osi/dma/eqos_dma.h b/osi/dma/eqos_dma.h index 405a2bd..571faf3 100644 --- a/osi/dma/eqos_dma.h +++ b/osi/dma/eqos_dma.h @@ -23,9 +23,12 @@ #ifndef EQOS_DMA_H_ #define EQOS_DMA_H_ -#define EQOS_AXI_BUS_WIDTH 0x10U - -/* EQOS DMA channel registers */ +/** + * @addtogroup EQOS1 DMA Channel Register offsets + * + * @brief EQOS DMA Channel register offsets + * @{ + */ #define EQOS_DMA_CHX_CTRL(x) ((0x0080U * (x)) + 0x1100U) #define EQOS_DMA_CHX_TX_CTRL(x) ((0x0080U * (x)) + 0x1104U) #define EQOS_DMA_CHX_RX_CTRL(x) ((0x0080U * (x)) + 0x1108U) @@ -42,6 +45,14 @@ #define EQOS_DMA_CHX_TDRL(x) ((0x0080U * (x)) + 0x112CU) #define EQOS_VIRT_INTR_CHX_STATUS(x) (0x8604U + ((x) * 8U)) #define EQOS_VIRT_INTR_CHX_CNTRL(x) (0x8600U + ((x) * 8U)) +/** @} */ + +/** + * @addtogroup EQOS2 BIT fields for EQOS MAC HW DMA Channel Registers + * + * @brief Values defined for the DMA channel registers + * @{ + */ #define EQOS_VIRT_INTR_CHX_STATUS_TX OSI_BIT(0) #define EQOS_VIRT_INTR_CHX_STATUS_RX OSI_BIT(1) #define EQOS_DMA_CHX_STATUS_TI OSI_BIT(0) @@ -110,21 +121,23 @@ #define EQOS_DMA_CH2_INTR_ENA_IDX 22U #define EQOS_DMA_CH3_INTR_ENA_IDX 23U #define EQOS_MAX_DMA_SAFETY_REGS 24U +#define EQOS_AXI_BUS_WIDTH 0x10U +/** @} */ /** - * struct dma_func_safety - Struct used to store last written values of + * @brief dma_func_safety - Struct used to store last written values of * critical DMA HW registers. - * @reg_addr: Array of reg MMIO addresses (base of EQoS + offset of reg) - * @reg_mask: Array of bit-mask value of each corresponding reg (used to - * ignore self-clearing/reserved bits in reg). - * @reg_val: Array of value stored in each corresponding register. - * @dma_safety_lock: OSI lock variable used to protect writes to reg while - * validation is in-progress. */ struct dma_func_safety { + /** Array of reg MMIO addresses (base EQoS + offset of reg) */ void *reg_addr[EQOS_MAX_DMA_SAFETY_REGS]; + /** Array of bit-mask value of each corresponding reg + * (used to ignore self-clearing/reserved bits in reg) */ unsigned int reg_mask[EQOS_MAX_DMA_SAFETY_REGS]; + /** Array of value stored in each corresponding register */ unsigned int reg_val[EQOS_MAX_DMA_SAFETY_REGS]; + /** OSI lock variable used to protect writes to reg + * while validation is in-progress */ unsigned int dma_safety_lock; }; #endif diff --git a/osi/dma/osi_dma.c b/osi/dma/osi_dma.c index 2ac3192..ec8f323 100644 --- a/osi/dma/osi_dma.c +++ b/osi/dma/osi_dma.c @@ -69,20 +69,6 @@ int osi_hw_dma_init(struct osi_dma_priv_data *osi_dma) return ret; } -/** - * osi_hw_deinit - De-init the HW - * @osi: OSI private data structure. - * - * Algorithm: - * 1) Stop the DMA - * 2) free all allocated resources. - * - * Dependencies: None - * - * Protection: None - * - * Return: 0 - Success, -ve - failure - */ int osi_hw_dma_deinit(struct osi_dma_priv_data *osi_dma) { unsigned int i; diff --git a/osi/dma/osi_dma_txrx.c b/osi/dma/osi_dma_txrx.c index 16ac2b7..6e938f7 100644 --- a/osi/dma/osi_dma_txrx.c +++ b/osi/dma/osi_dma_txrx.c @@ -27,11 +27,9 @@ int dma_desc_init(struct osi_dma_priv_data *osi_dma); /** - * get_rx_csum - Get the Rx checksum from descriptor if valid - * @rx_desc: Rx descriptor - * @rx_pkt_cx: Per-Rx packet context structure + * @brief get_rx_csum - Get the Rx checksum from descriptor if valid * - * Algorithm: + * Algorithm: * 1) Check if the descriptor has any checksum validation errors. * 2) If none, set a per packet context flag indicating no err in * Rx checksum @@ -39,11 +37,8 @@ int dma_desc_init(struct osi_dma_priv_data *osi_dma); * IP/TCP/UDP checksum validation in software based on whether * COE is enabled for the device. * - * Dependencies: None - * - * Protection: None - * - * Return: None. + * @param[in] rx_desc: Rx descriptor + * @param[in] rx_pkt_cx: Per-Rx packet context structure */ static inline void get_rx_csum(struct osi_rx_desc *rx_desc, struct osi_rx_pkt_cx *rx_pkt_cx) @@ -61,6 +56,18 @@ static inline void get_rx_csum(struct osi_rx_desc *rx_desc, } } +/** + * @brief get_rx_vlan_from_desc - Get Rx VLAN from descriptor + * + * Algorithm: + * 1) Check if the descriptor has any type set. + * 2) If set, set a per packet context flag indicating packet is VLAN + * tagged. + * 3) Extract VLAN tag ID from the descriptor + * + * @param[in] rx_desc: Rx descriptor + * @param[in] rx_pkt_cx: Per-Rx packet context structure + */ static inline void get_rx_vlan_from_desc(struct osi_rx_desc *rx_desc, struct osi_rx_pkt_cx *rx_pkt_cx) { @@ -78,18 +85,16 @@ static inline void get_rx_vlan_from_desc(struct osi_rx_desc *rx_desc, } /** - * get_rx_tstamp_status - Get Tx Time stamp status - * @context_desc: Rx context descriptor + * @brief get_rx_tstamp_status - Get Tx Time stamp status * - * Algorithm: + * Algorithm: * 1) Check if the received descriptor is a context descriptor. * 2) If yes, check whether the time stamp is valid or not. * - * Dependencies: None + * @param[in] context_desc: Rx context descriptor * - * Protection: None - * - * Return: -1 if TS is not valid and 0 if TS is valid. + * @retval -1 if TimeStamp is not valid + * @retval 0 if TimeStamp is valid. */ static inline int get_rx_tstamp_status(struct osi_rx_desc *context_desc) { @@ -108,22 +113,20 @@ static inline int get_rx_tstamp_status(struct osi_rx_desc *context_desc) } /** - * get_rx_hwstamp - Get Rx HW Time stamp - * @rx_desc: Rx descriptor - * @context_desc: Rx context descriptor - * @rx_pkt_cx: Rx packet context + * @brief get_rx_hwstamp - Get Rx HW Time stamp * - * Algorithm: + * Algorithm: * 1) Check for TS availability. * 2) call get_tx_tstamp_status if TS is valid or not. * 3) If yes, set a bit and update nano seconds in rx_pkt_cx so that OSD * layer can extract the time by checking this bit. * - * Dependencies: None + * @param[in] rx_desc: Rx descriptor + * @param[in] context_desc: Rx context descriptor + * @param[in] rx_pkt_cx: Rx packet context * - * Protection: None - * - * Return: -1 if TS is not available and 0 if TS is available. + * @retval -1 if TimeStamp is not available + * @retval 0 if TimeStamp is available. */ static int get_rx_hwstamp(struct osi_rx_desc *rx_desc, struct osi_rx_desc *context_desc, @@ -164,19 +167,14 @@ static int get_rx_hwstamp(struct osi_rx_desc *rx_desc, /** - * get_rx_err_stats - Detect Errors from Rx Descriptor - * @rx_desc: Rx Descriptor. - * @pkt_err_stats: Packet error stats which stores the errors reported + * @brief get_rx_err_stats - Detect Errors from Rx Descriptor * - * Algorimthm: This routine will be invoked by OSI layer itself which + * Algorithm: This routine will be invoked by OSI layer itself which * checks for the Last Descriptor and updates the receive status errors * accordingly. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] rx_desc: Rx Descriptor. + * @param[in] pkt_err_stats: Packet error stats which stores the errors reported */ static inline void get_rx_err_stats(struct osi_rx_desc *rx_desc, struct osi_pkt_err_stats pkt_err_stats) @@ -189,29 +187,6 @@ static inline void get_rx_err_stats(struct osi_rx_desc *rx_desc, } } -/** - * osi_process_rx_completions - Read data from receive channel descriptors - * @osi: OSI private data structure. - * @chan: Rx DMA channel number - * @budget: Threshould for reading the packets at a time. - * - * Algorimthm: This routine will be invoked by OSD layer to get the - * data from Rx descriptors and deliver the packet to the stack. - * 1) Checks descriptor owned by DMA or not. - * 2) Get the length from Rx descriptor - * 3) Invokes OSD layer to deliver the packet to network stack. - * 4) Re-allocate the receive buffers, populate Rx descriptor and - * handover to DMA. - * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) DMA need to be started, see osi_start_dma - * - * Protection: None. - * - * Return: None. - */ int osi_process_rx_completions(struct osi_dma_priv_data *osi, unsigned int chan, int budget) { @@ -278,19 +253,14 @@ int osi_process_rx_completions(struct osi_dma_priv_data *osi, } /** - * get_tx_err_stats - Detect Errors from Tx Status - * @tx_desc: Tx Descriptor. - * @pkt_err_stats: Pakcet error stats which stores the errors reported + * @brief get_tx_err_stats - Detect Errors from Tx Status * - * Algorimthm: This routine will be invoked by OSI layer itself which + * Algorithm: This routine will be invoked by OSI layer itself which * checks for the Last Descriptor and updates the transmit status errors * accordingly. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] tx_desc: Tx Descriptor. + * @param[in] pkt_err_stats: Pakcet error stats which stores the errors reported */ static inline void get_tx_err_stats(struct osi_tx_desc *tx_desc, struct osi_pkt_err_stats pkt_err_stats) @@ -370,21 +340,6 @@ static inline void get_tx_err_stats(struct osi_tx_desc *tx_desc, } } -/** - * osi_clear_tx_pkt_err_stats - Clear tx packet error stats. - * @osi: OSI dma private data structure. - * - * Algorithm: This function will be invoked by OSD layer to clear the - * tx packet error stats - * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * - * Protection: None - * - * Return: 0 - success, -1 - failure. - */ int osi_clear_tx_pkt_err_stats(struct osi_dma_priv_data *osi_dma) { int ret = -1; @@ -407,21 +362,6 @@ int osi_clear_tx_pkt_err_stats(struct osi_dma_priv_data *osi_dma) return ret; } -/** - * osi_clear_rx_pkt_err_stats - Clear rx packet error stats. - * @osi: OSI dma private data structure. - * - * Algorithm: This function will be invoked by OSD layer to clear the - * rx packet error stats - * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * - * Protection: None - * - * Return: 0 - success, -1 - failure. - */ int osi_clear_rx_pkt_err_stats(struct osi_dma_priv_data *osi_dma) { int ret = -1; @@ -435,27 +375,6 @@ int osi_clear_rx_pkt_err_stats(struct osi_dma_priv_data *osi_dma) return ret; } -/** - * osi_process_tx_completions - Process Tx complete on DMA channel ring. - * @osi: OSI private data structure. - * @chan: Channel number on which Tx complete need to be done. - * - * Algorithm: This function will be invoked by OSD layer to process Tx - * complete interrupt. - * 1) First checks whether descriptor owned by DMA or not. - * 2) Invokes OSD layer to release DMA address and Tx buffer which are - * updated as part of transmit routine. - * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) DMA need to be started, see osi_start_dma - * - * - * Protection: None - * - * Return: Number of decriptors (buffers) proccessed. - */ int osi_process_tx_completions(struct osi_dma_priv_data *osi, unsigned int chan) { @@ -544,20 +463,18 @@ int osi_process_tx_completions(struct osi_dma_priv_data *osi, } /** - * need_cntx_desc - Helper function to check if context desc is needed. - * @tx_pkt_cx: Pointer to transmit packet context structure - * @tx_desc: Pointer to tranmit descriptor to be filled. + * @brief need_cntx_desc - Helper function to check if context desc is needed. * - * Algorithm: + * Algorithm: * 1) Check if transmit packet context flags are set * 2) If set, set the context descriptor bit along * with other context information in the transmit descriptor. * - * Dependencies: None. + * @param[in] tx_pkt_cx: Pointer to transmit packet context structure + * @param[in] tx_desc: Pointer to tranmit descriptor to be filled. * - * Protection: None - * - * Return: 0 - cntx desc not used, 1 - cntx desc used. + * @retval 0 - cntx desc not used + * @retval 1 - cntx desc used. */ static inline int need_cntx_desc(struct osi_tx_pkt_cx *tx_pkt_cx, struct osi_tx_desc *tx_desc) @@ -594,22 +511,18 @@ static inline int need_cntx_desc(struct osi_tx_pkt_cx *tx_pkt_cx, } /** - * fill_first_desc - Helper function to fill the first transmit descriptor. - * @tx_pkt_cx: Pointer to transmit packet context structure - * @tx_desc: Pointer to tranmit descriptor to be filled. - * @tx_swcx: Pointer to corresponding tranmit descriptor software context. + * @brief fill_first_desc - Helper function to fill the first transmit + * descriptor. * - * Algorithm: - * 1) Update the buffer address and length of buffer in first desc. - * 2) Check if any features like HW checksum offload, TSO, VLAN insertion - * etc. are flagged in transmit packet context. If so, set the fiels in - * first desc corresponding to those features. + * Algorithm: + * 1) Update the buffer address and length of buffer in first desc. + * 2) Check if any features like HW checksum offload, TSO, VLAN insertion + * etc. are flagged in transmit packet context. If so, set the fiels in + * first desc corresponding to those features. * - * Dependencies: None. - * - * Protection: None - * - * Return: None. + * @param[in] tx_pkt_cx: Pointer to transmit packet context structure + * @param[in] tx_desc: Pointer to tranmit descriptor to be filled. + * @param[in] tx_swcx: Pointer to corresponding tx descriptor software context. */ static inline void fill_first_desc(struct osi_tx_pkt_cx *tx_pkt_cx, struct osi_tx_desc *tx_desc, @@ -658,35 +571,6 @@ static inline void fill_first_desc(struct osi_tx_pkt_cx *tx_pkt_cx, } } -/** - * osi_hw_transmit - Initialize Tx DMA descriptors for a channel - * @osi: OSI private data structure. - * @chan: DMA Tx channel number - * - * Algorithm: Initialize Transmit descriptors with DMA mappabled buffers, - * set OWN bit, Tx ring length and set starting address of Tx DMA channel. - * Tx ring base address in Tx DMA registers. - * - * Dependencies: - * 1) MAC needs to be out of reset and proper clocks need to be configured. - * 2) DMA HW init need to be completed successfully, see osi_hw_dma_init - * 3) DMA channel need to be started, see osi_start_dma - * 4) Need to set update tx_pkt_cx->flags accordingly as per the - * requirements - * #define OSI_PKT_CX_VLAN OSI_BIT(0) - * #define OSI_PKT_CX_CSUM OSI_BIT(1) - * #define OSI_PKT_CX_TSO OSI_BIT(2) - * #define OSI_PKT_CX_PTP OSI_BIT(3) - * 5) tx_pkt_cx->desc_cnt need to be populated which holds the number - * of swcx descriptors allocated for that packet - * 6) tx_swcx structure need to be filled for per packet with the - * buffer len, DMA mapped address of buffer for each descriptor - * consumed by the packet - * - * Protection: None. - * - * Return: None. - */ void osi_hw_transmit(struct osi_dma_priv_data *osi, unsigned int chan) { struct osi_tx_ring *tx_ring = osi->tx_ring[chan]; @@ -773,19 +657,17 @@ void osi_hw_transmit(struct osi_dma_priv_data *osi, unsigned int chan) } /** - * rx_dma_desc_initialization - Initialize DMA Receive descriptors for Rx. - * @osi: OSI private data structure. - * @chan: Rx channel number. + * @brief rx_dma_desc_initialization - Initialize DMA Receive descriptors for Rx * - * Algorithm: Initialize Receive descriptors with DMA mappable buffers, + * Algorithm: Initialize Receive descriptors with DMA mappable buffers, * set OWN bit, Rx ring length and set starting address of Rx DMA channel. * Tx ring base address in Tx DMA registers. * - * Dependencies: None. + * @param[in] osi: OSI private data structure. + * @param[in] chan: Rx channel number. * - * Protection: None. - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int rx_dma_desc_initialization(struct osi_dma_priv_data *osi, unsigned int chan) @@ -826,18 +708,16 @@ static int rx_dma_desc_initialization(struct osi_dma_priv_data *osi, } /** - * rx_dma_desc_init - Initialize DMA Receive descriptors for Rx channel. - * @osi: OSI private data structure. + * @brief rx_dma_desc_init - Initialize DMA Receive descriptors for Rx channel. * - * Algorithm: Initialize Receive descriptors with DMA mappabled buffers, + * Algorithm: Initialize Receive descriptors with DMA mappabled buffers, * set OWN bit, Rx ring length and set starting address of Rx DMA channel. * Tx ring base address in Tx DMA registers. * - * Dependencies: None. + * @param[in] osi: OSI private data structure. * - * Protection: None. - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ static int rx_dma_desc_init(struct osi_dma_priv_data *osi) { @@ -858,17 +738,12 @@ static int rx_dma_desc_init(struct osi_dma_priv_data *osi) } /** - * tx_dma_desc_init - Initialize DMA Transmit descriptors. - * @osi: OSI private data structure. + * @brief tx_dma_desc_init - Initialize DMA Transmit descriptors. * - * Algorithm: Initialize Trannsmit descriptors and set Tx ring length, + * Algorithm: Initialize Trannsmit descriptors and set Tx ring length, * Tx ring base address in Tx DMA registers. * - * Dependencies: None. - * - * Protection: None. - * - * Return: None. + * @param[in] osi_dma: OSI DMA private data structure. */ static void tx_dma_desc_init(struct osi_dma_priv_data *osi_dma) { @@ -901,17 +776,15 @@ static void tx_dma_desc_init(struct osi_dma_priv_data *osi_dma) } /** - * dma_desc_init - Initialize DMA Tx/Rx descriptors - * @osi: OSI private data structure. + * @brief dma_desc_init - Initialize DMA Tx/Rx descriptors * - * Algorithm: Transmit and Receive desctiptors will be initialized with + * Algorithm: Transmit and Receive desctiptors will be initialized with * required values so that MAC DMA can understand and act accordingly. * - * Dependencies: None. + * @param[in] osi_dma: OSI DMA private data structure. * - * Protection: None. - * - * Return: 0 - success, -1 - failure. + * @retval 0 on success + * @retval -1 on failure. */ int dma_desc_init(struct osi_dma_priv_data *osi_dma) {