net/macb: Adding comments to various #defs to make interpretation easier
authorXander Huff <xander.huff@ni.com>
Tue, 13 Jan 2015 22:15:50 +0000 (16:15 -0600)
committerDavid S. Miller <davem@davemloft.net>
Wed, 14 Jan 2015 05:25:50 +0000 (00:25 -0500)
This change is to help improve at-a-glace knowledge of the purpose of the
various Cadence MACB/GEM registers. Comments are more helpful for human
readability than short acronyms.

Describe various #define varibles Cadence MACB/GEM registers as documented
in Xilinix's "Zynq-7000 All Programmable SoC TechnicalReference Manual, v1.9.1
(UG-585)"

Signed-off-by: Xander Huff <xander.huff@ni.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
drivers/net/ethernet/cadence/macb.h

index 084191b..8e8c3c9 100644 (file)
 #define MACB_MAX_QUEUES 8
 
 /* MACB register offsets */
-#define MACB_NCR                               0x0000
-#define MACB_NCFGR                             0x0004
-#define MACB_NSR                               0x0008
+#define MACB_NCR                               0x0000 /* Network Control */
+#define MACB_NCFGR                             0x0004 /* Network Config */
+#define MACB_NSR                               0x0008 /* Network Status */
 #define MACB_TAR                               0x000c /* AT91RM9200 only */
 #define MACB_TCR                               0x0010 /* AT91RM9200 only */
-#define MACB_TSR                               0x0014
-#define MACB_RBQP                              0x0018
-#define MACB_TBQP                              0x001c
-#define MACB_RSR                               0x0020
-#define MACB_ISR                               0x0024
-#define MACB_IER                               0x0028
-#define MACB_IDR                               0x002c
-#define MACB_IMR                               0x0030
-#define MACB_MAN                               0x0034
+#define MACB_TSR                               0x0014 /* Transmit Status */
+#define MACB_RBQP                              0x0018 /* RX Q Base Address */
+#define MACB_TBQP                              0x001c /* TX Q Base Address */
+#define MACB_RSR                               0x0020 /* Receive Status */
+#define MACB_ISR                               0x0024 /* Interrupt Status */
+#define MACB_IER                               0x0028 /* Interrupt Enable */
+#define MACB_IDR                               0x002c /* Interrupt Disable */
+#define MACB_IMR                               0x0030 /* Interrupt Mask */
+#define MACB_MAN                               0x0034 /* PHY Maintenance */
 #define MACB_PTR                               0x0038
 #define MACB_PFR                               0x003c
 #define MACB_FTO                               0x0040
 #define MACB_MID                               0x00fc
 
 /* GEM register offsets. */
-#define GEM_NCFGR                              0x0004
-#define GEM_USRIO                              0x000c
-#define GEM_DMACFG                             0x0010
-#define GEM_HRB                                        0x0080
-#define GEM_HRT                                        0x0084
-#define GEM_SA1B                               0x0088
-#define GEM_SA1T                               0x008C
-#define GEM_SA2B                               0x0090
-#define GEM_SA2T                               0x0094
-#define GEM_SA3B                               0x0098
-#define GEM_SA3T                               0x009C
-#define GEM_SA4B                               0x00A0
-#define GEM_SA4T                               0x00A4
-#define GEM_OTX                                        0x0100
-#define GEM_DCFG1                              0x0280
-#define GEM_DCFG2                              0x0284
-#define GEM_DCFG3                              0x0288
-#define GEM_DCFG4                              0x028c
-#define GEM_DCFG5                              0x0290
-#define GEM_DCFG6                              0x0294
-#define GEM_DCFG7                              0x0298
+#define GEM_NCFGR                              0x0004 /* Network Config */
+#define GEM_USRIO                              0x000c /* User IO */
+#define GEM_DMACFG                             0x0010 /* DMA Configuration */
+#define GEM_HRB                                        0x0080 /* Hash Bottom */
+#define GEM_HRT                                        0x0084 /* Hash Top */
+#define GEM_SA1B                               0x0088 /* Specific1 Bottom */
+#define GEM_SA1T                               0x008C /* Specific1 Top */
+#define GEM_SA2B                               0x0090 /* Specific2 Bottom */
+#define GEM_SA2T                               0x0094 /* Specific2 Top */
+#define GEM_SA3B                               0x0098 /* Specific3 Bottom */
+#define GEM_SA3T                               0x009C /* Specific3 Top */
+#define GEM_SA4B                               0x00A0 /* Specific4 Bottom */
+#define GEM_SA4T                               0x00A4 /* Specific4 Top */
+#define GEM_OTX                                        0x0100 /* Octets transmitted */
+#define GEM_DCFG1                              0x0280 /* Design Config 1 */
+#define GEM_DCFG2                              0x0284 /* Design Config 2 */
+#define GEM_DCFG3                              0x0288 /* Design Config 3 */
+#define GEM_DCFG4                              0x028c /* Design Config 4 */
+#define GEM_DCFG5                              0x0290 /* Design Config 5 */
+#define GEM_DCFG6                              0x0294 /* Design Config 6 */
+#define GEM_DCFG7                              0x0298 /* Design Config 7 */
 
 #define GEM_ISR(hw_q)                          (0x0400 + ((hw_q) << 2))
 #define GEM_TBQP(hw_q)                         (0x0440 + ((hw_q) << 2))
 #define GEM_IMR(hw_q)                          (0x0640 + ((hw_q) << 2))
 
 /* Bitfields in NCR */
-#define MACB_LB_OFFSET                         0
+#define MACB_LB_OFFSET                         0 /* reserved */
 #define MACB_LB_SIZE                           1
-#define MACB_LLB_OFFSET                                1
+#define MACB_LLB_OFFSET                                1 /* Loop back local */
 #define MACB_LLB_SIZE                          1
-#define MACB_RE_OFFSET                         2
+#define MACB_RE_OFFSET                         2 /* Receive enable */
 #define MACB_RE_SIZE                           1
-#define MACB_TE_OFFSET                         3
+#define MACB_TE_OFFSET                         3 /* Transmit enable */
 #define MACB_TE_SIZE                           1
-#define MACB_MPE_OFFSET                                4
+#define MACB_MPE_OFFSET                                4 /* Management port enable */
 #define MACB_MPE_SIZE                          1
-#define MACB_CLRSTAT_OFFSET                    5
+#define MACB_CLRSTAT_OFFSET                    5 /* Clear stats regs */
 #define MACB_CLRSTAT_SIZE                      1
-#define MACB_INCSTAT_OFFSET                    6
+#define MACB_INCSTAT_OFFSET                    6 /* Incremental stats regs */
 #define MACB_INCSTAT_SIZE                      1
-#define MACB_WESTAT_OFFSET                     7
+#define MACB_WESTAT_OFFSET                     7 /* Write enable stats regs */
 #define MACB_WESTAT_SIZE                       1
-#define MACB_BP_OFFSET                         8
+#define MACB_BP_OFFSET                         8 /* Back pressure */
 #define MACB_BP_SIZE                           1
-#define MACB_TSTART_OFFSET                     9
+#define MACB_TSTART_OFFSET                     9 /* Start transmission */
 #define MACB_TSTART_SIZE                       1
-#define MACB_THALT_OFFSET                      10
+#define MACB_THALT_OFFSET                      10 /* Transmit halt */
 #define MACB_THALT_SIZE                                1
-#define MACB_NCR_TPF_OFFSET                    11
+#define MACB_NCR_TPF_OFFSET                    11 /* Transmit pause frame */
 #define MACB_NCR_TPF_SIZE                      1
-#define MACB_TZQ_OFFSET                                12
+#define MACB_TZQ_OFFSET                                12 /* Transmit zero quantum
+                                                   * pause frame
+                                                   */
 #define MACB_TZQ_SIZE                          1
 
 /* Bitfields in NCFGR */
-#define MACB_SPD_OFFSET                                0
+#define MACB_SPD_OFFSET                                0 /* Speed */
 #define MACB_SPD_SIZE                          1
-#define MACB_FD_OFFSET                         1
+#define MACB_FD_OFFSET                         1 /* Full duplex */
 #define MACB_FD_SIZE                           1
-#define MACB_BIT_RATE_OFFSET                   2
+#define MACB_BIT_RATE_OFFSET                   2 /* Discard non-VLAN frames */
 #define MACB_BIT_RATE_SIZE                     1
-#define MACB_JFRAME_OFFSET                     3
+#define MACB_JFRAME_OFFSET                     3 /* reserved */
 #define MACB_JFRAME_SIZE                       1
-#define MACB_CAF_OFFSET                                4
+#define MACB_CAF_OFFSET                                4 /* Copy all frames */
 #define MACB_CAF_SIZE                          1
-#define MACB_NBC_OFFSET                                5
+#define MACB_NBC_OFFSET                                5 /* No broadcast */
 #define MACB_NBC_SIZE                          1
-#define MACB_NCFGR_MTI_OFFSET                  6
+#define MACB_NCFGR_MTI_OFFSET                  6 /* Multicast hash enable */
 #define MACB_NCFGR_MTI_SIZE                    1
-#define MACB_UNI_OFFSET                                7
+#define MACB_UNI_OFFSET                                7 /* Unicast hash enable */
 #define MACB_UNI_SIZE                          1
-#define MACB_BIG_OFFSET                                8
+#define MACB_BIG_OFFSET                                8 /* Receive 1536 byte frames */
 #define MACB_BIG_SIZE                          1
-#define MACB_EAE_OFFSET                                9
+#define MACB_EAE_OFFSET                                9 /* External address match
+                                                  * enable
+                                                  */
 #define MACB_EAE_SIZE                          1
 #define MACB_CLK_OFFSET                                10
 #define MACB_CLK_SIZE                          2
-#define MACB_RTY_OFFSET                                12
+#define MACB_RTY_OFFSET                                12 /* Retry test */
 #define MACB_RTY_SIZE                          1
-#define MACB_PAE_OFFSET                                13
+#define MACB_PAE_OFFSET                                13 /* Pause enable */
 #define MACB_PAE_SIZE                          1
 #define MACB_RM9200_RMII_OFFSET                        13 /* AT91RM9200 only */
 #define MACB_RM9200_RMII_SIZE                  1  /* AT91RM9200 only */
-#define MACB_RBOF_OFFSET                       14
+#define MACB_RBOF_OFFSET                       14 /* Receive buffer offset */
 #define MACB_RBOF_SIZE                         2
-#define MACB_RLCE_OFFSET                       16
+#define MACB_RLCE_OFFSET                       16 /* Length field error frame
+                                                   * discard
+                                                   */
 #define MACB_RLCE_SIZE                         1
-#define MACB_DRFCS_OFFSET                      17
+#define MACB_DRFCS_OFFSET                      17 /* FCS remove */
 #define MACB_DRFCS_SIZE                                1
 #define MACB_EFRHD_OFFSET                      18
 #define MACB_EFRHD_SIZE                                1
 #define MACB_IRXFCS_SIZE                       1
 
 /* GEM specific NCFGR bitfields. */
-#define GEM_GBE_OFFSET                         10
+#define GEM_GBE_OFFSET                         10 /* Gigabit mode enable */
 #define GEM_GBE_SIZE                           1
-#define GEM_CLK_OFFSET                         18
+#define GEM_CLK_OFFSET                         18 /* MDC clock division */
 #define GEM_CLK_SIZE                           3
-#define GEM_DBW_OFFSET                         21
+#define GEM_DBW_OFFSET                         21 /* Data bus width */
 #define GEM_DBW_SIZE                           2
 #define GEM_RXCOEN_OFFSET                      24
 #define GEM_RXCOEN_SIZE                                1
 
 /* Constants for data bus width. */
-#define GEM_DBW32                              0
-#define GEM_DBW64                              1
-#define GEM_DBW128                             2
+#define GEM_DBW32                              0 /* 32 bit AMBA AHB data bus
+                                                  * width
+                                                  */
+#define GEM_DBW64                              1 /* 64 bit AMBA AHB data bus
+                                                  * width
+                                                  */
+#define GEM_DBW128                             2 /* 128 bit AMBA AHB data bus
+                                                  * width
+                                                  */
 
 /* Bitfields in DMACFG. */
-#define GEM_FBLDO_OFFSET                       0
+#define GEM_FBLDO_OFFSET                       0 /* AHB fixed burst length for
+                                                  * DMA data operations
+                                                  */
 #define GEM_FBLDO_SIZE                         5
-#define GEM_ENDIA_OFFSET                       7
+#define GEM_ENDIA_OFFSET                       7 /* AHB endian swap mode enable
+                                                  * for packet data accesses
+                                                  */
 #define GEM_ENDIA_SIZE                         1
-#define GEM_RXBMS_OFFSET                       8
+#define GEM_RXBMS_OFFSET                       8 /* Receiver packet buffer
+                                                  * memory size select
+                                                  */
 #define GEM_RXBMS_SIZE                         2
-#define GEM_TXPBMS_OFFSET                      10
+#define GEM_TXPBMS_OFFSET                      10 /* Transmitter packet buffer
+                                                   * memory size select
+                                                   */
 #define GEM_TXPBMS_SIZE                                1
-#define GEM_TXCOEN_OFFSET                      11
+#define GEM_TXCOEN_OFFSET                      11 /* Transmitter IP, TCP and
+                                                   * UDP checksum generation
+                                                   * offload enable
+                                                   */
 #define GEM_TXCOEN_SIZE                                1
-#define GEM_RXBS_OFFSET                                16
+#define GEM_RXBS_OFFSET                                16 /* DMA receive buffer size in
+                                                   * AHB system memory
+                                                   */
 #define GEM_RXBS_SIZE                          8
-#define GEM_DDRP_OFFSET                                24
+#define GEM_DDRP_OFFSET                                24 /* disc_when_no_ahb */
 #define GEM_DDRP_SIZE                          1
 
 
 /* Bitfields in NSR */
-#define MACB_NSR_LINK_OFFSET                   0
+#define MACB_NSR_LINK_OFFSET                   0 /* pcs_link_state */
 #define MACB_NSR_LINK_SIZE                     1
-#define MACB_MDIO_OFFSET                       1
+#define MACB_MDIO_OFFSET                       1 /* status of the mdio_in
+                                                  * pin
+                                                  */
 #define MACB_MDIO_SIZE                         1
-#define MACB_IDLE_OFFSET                       2
+#define MACB_IDLE_OFFSET                       2 /* The PHY management logic is
+                                                  * idle (i.e. has completed)
+                                                  */
 #define MACB_IDLE_SIZE                         1
 
 /* Bitfields in TSR */
-#define MACB_UBR_OFFSET                                0
+#define MACB_UBR_OFFSET                                0 /* Used bit read */
 #define MACB_UBR_SIZE                          1
-#define MACB_COL_OFFSET                                1
+#define MACB_COL_OFFSET                                1 /* Collision occurred */
 #define MACB_COL_SIZE                          1
-#define MACB_TSR_RLE_OFFSET                    2
+#define MACB_TSR_RLE_OFFSET                    2 /* Retry limit exceeded */
 #define MACB_TSR_RLE_SIZE                      1
-#define MACB_TGO_OFFSET                                3
+#define MACB_TGO_OFFSET                                3 /* Transmit go */
 #define MACB_TGO_SIZE                          1
-#define MACB_BEX_OFFSET                                4
+#define MACB_BEX_OFFSET                                4 /* Transmit frame corruption
+                                                  * due to AHB error
+                                                  */
 #define MACB_BEX_SIZE                          1
 #define MACB_RM9200_BNQ_OFFSET                 4 /* AT91RM9200 only */
 #define MACB_RM9200_BNQ_SIZE                   1 /* AT91RM9200 only */
-#define MACB_COMP_OFFSET                       5
+#define MACB_COMP_OFFSET                       5 /* Trnasmit complete */
 #define MACB_COMP_SIZE                         1
-#define MACB_UND_OFFSET                                6
+#define MACB_UND_OFFSET                                6 /* Trnasmit under run */
 #define MACB_UND_SIZE                          1
 
 /* Bitfields in RSR */
-#define MACB_BNA_OFFSET                                0
+#define MACB_BNA_OFFSET                                0 /* Buffer not available */
 #define MACB_BNA_SIZE                          1
-#define MACB_REC_OFFSET                                1
+#define MACB_REC_OFFSET                                1 /* Frame received */
 #define MACB_REC_SIZE                          1
-#define MACB_OVR_OFFSET                                2
+#define MACB_OVR_OFFSET                                2 /* Receive overrun */
 #define MACB_OVR_SIZE                          1
 
 /* Bitfields in ISR/IER/IDR/IMR */
-#define MACB_MFD_OFFSET                                0
+#define MACB_MFD_OFFSET                                0 /* Management frame sent */
 #define MACB_MFD_SIZE                          1
-#define MACB_RCOMP_OFFSET                      1
+#define MACB_RCOMP_OFFSET                      1 /* Receive complete */
 #define MACB_RCOMP_SIZE                                1
-#define MACB_RXUBR_OFFSET                      2
+#define MACB_RXUBR_OFFSET                      2 /* RX used bit read */
 #define MACB_RXUBR_SIZE                                1
-#define MACB_TXUBR_OFFSET                      3
+#define MACB_TXUBR_OFFSET                      3 /* TX used bit read */
 #define MACB_TXUBR_SIZE                                1
-#define MACB_ISR_TUND_OFFSET                   4
+#define MACB_ISR_TUND_OFFSET                   4 /* Enable trnasmit buffer
+                                                  * under run interrupt
+                                                  */
 #define MACB_ISR_TUND_SIZE                     1
-#define MACB_ISR_RLE_OFFSET                    5
+#define MACB_ISR_RLE_OFFSET                    5 /* Enable retry limit exceeded
+                                                  * or late collision interrupt
+                                                  */
 #define MACB_ISR_RLE_SIZE                      1
-#define MACB_TXERR_OFFSET                      6
+#define MACB_TXERR_OFFSET                      6 /* Enable transmit frame
+                                                  * corruption due to AHB error
+                                                  * interrupt
+                                                  */
 #define MACB_TXERR_SIZE                                1
-#define MACB_TCOMP_OFFSET                      7
+#define MACB_TCOMP_OFFSET                      7 /* Enable transmit complete
+                                                  * interrupt
+                                                  */
 #define MACB_TCOMP_SIZE                                1
-#define MACB_ISR_LINK_OFFSET                   9
+#define MACB_ISR_LINK_OFFSET                   9 /* Enable link change
+                                                  * interrupt
+                                                  */
 #define MACB_ISR_LINK_SIZE                     1
-#define MACB_ISR_ROVR_OFFSET                   10
+#define MACB_ISR_ROVR_OFFSET                   10 /* Enable receive overrun
+                                                   * interrupt
+                                                   */
 #define MACB_ISR_ROVR_SIZE                     1
-#define MACB_HRESP_OFFSET                      11
+#define MACB_HRESP_OFFSET                      11 /* Enable hrsep not OK
+                                                   * interrupt
+                                                   */
 #define MACB_HRESP_SIZE                                1
-#define MACB_PFR_OFFSET                                12
+#define MACB_PFR_OFFSET                                12 /* Enable pause frame with
+                                                   * non-zero pause quantum
+                                                   * interrupt
+                                                   */
 #define MACB_PFR_SIZE                          1
-#define MACB_PTZ_OFFSET                                13
+#define MACB_PTZ_OFFSET                                13 /* Enable pause time zero
+                                                   * interrupt
+                                                   */
 #define MACB_PTZ_SIZE                          1
 
 /* Bitfields in MAN */
-#define MACB_DATA_OFFSET                       0
+#define MACB_DATA_OFFSET                       0 /* data */
 #define MACB_DATA_SIZE                         16
-#define MACB_CODE_OFFSET                       16
+#define MACB_CODE_OFFSET                       16 /* Must be written to 10 */
 #define MACB_CODE_SIZE                         2
-#define MACB_REGA_OFFSET                       18
+#define MACB_REGA_OFFSET                       18 /* Register address */
 #define MACB_REGA_SIZE                         5
-#define MACB_PHYA_OFFSET                       23
+#define MACB_PHYA_OFFSET                       23 /* PHY address */
 #define MACB_PHYA_SIZE                         5
-#define MACB_RW_OFFSET                         28
+#define MACB_RW_OFFSET                         28 /* Operation. 10 is read. 01
+                                                   * is write.
+                                                   */
 #define MACB_RW_SIZE                           2
-#define MACB_SOF_OFFSET                                30
+#define MACB_SOF_OFFSET                                30 /* Must be written to 1 for
+                                                   * Clause 22 operation
+                                                   */
 #define MACB_SOF_SIZE                          2
 
 /* Bitfields in USRIO (AVR32) */
 /* Bitfields in USRIO (AT91) */
 #define MACB_RMII_OFFSET                       0
 #define MACB_RMII_SIZE                         1
-#define GEM_RGMII_OFFSET                       0       /* GEM gigabit mode */
+#define GEM_RGMII_OFFSET                       0 /* GEM gigabit mode */
 #define GEM_RGMII_SIZE                         1
 #define MACB_CLKEN_OFFSET                      1
 #define MACB_CLKEN_SIZE                                1