drivers/net/npe/include/IxEthAcc.h

   1 /** @file    IxEthAcc.h
   2  *
   3  * @brief this file contains the public API of @ref IxEthAcc component
   4  *
   5  * Design notes:
   6  * The IX_OSAL_MBUF address is to be specified on bits [31-5] and must
   7  * be cache aligned (bits[4-0] cleared)
   8  *
   9  *
  10  * @par
  11  * IXP400 SW Release version 2.0
  12  *
  13  * -- Copyright Notice --
  14  *
  15  * @par
  16  * Copyright 2001-2005, Intel Corporation.
  17  * All rights reserved.
  18  *
  19  * @par
  20  * SPDX-License-Identifier:     BSD-3-Clause
  21  * @par
  22  * -- End of Copyright Notice --
  23  *
  24  */
  25
  26 #ifndef IxEthAcc_H
  27 #define IxEthAcc_H
  28
  29 #include <IxOsBuffMgt.h>
  30 #include <IxTypes.h>
  31
  32 /**
  33  * @defgroup IxEthAcc IXP400 Ethernet Access (IxEthAcc) API
  34  *
  35  * @brief ethAcc is a library that does provides access to the internal IXP400 10/100Bt Ethernet MACs.
  36  *
  37  *@{
  38  */
  39
  40 /**
  41  * @ingroup IxEthAcc
  42  * @brief Definition of the Ethernet Access status
  43  */
  44 typedef enum /* IxEthAccStatus */
  45 {
  46     IX_ETH_ACC_SUCCESS = IX_SUCCESS, /**< return success*/
  47     IX_ETH_ACC_FAIL = IX_FAIL, /**< return fail*/
  48     IX_ETH_ACC_INVALID_PORT, /**< return invalid port*/
  49     IX_ETH_ACC_PORT_UNINITIALIZED, /**< return uninitialized*/
  50     IX_ETH_ACC_MAC_UNINITIALIZED, /**< return MAC uninitialized*/
  51     IX_ETH_ACC_INVALID_ARG, /**< return invalid arg*/
  52     IX_ETH_TX_Q_FULL, /**< return tx queue is full*/
  53     IX_ETH_ACC_NO_SUCH_ADDR /**< return no such address*/
  54 } IxEthAccStatus;
  55
  56 /**
  57  * @ingroup IxEthAcc
  58  * @enum IxEthAccPortId
  59  * @brief Definition of the IXP400 Mac Ethernet device.
  60  */
  61 typedef enum
  62 {
  63         IX_ETH_PORT_1 = 0, /**< Ethernet Port 1 */
  64         IX_ETH_PORT_2 = 1  /**< Ethernet port 2 */
  65         ,IX_ETH_PORT_3 = 2 /**< Ethernet port 3 */
  66 } IxEthAccPortId;
  67
  68 /**
  69  * @ingroup IxEthAcc
  70  *
  71  * @def IX_ETH_ACC_NUMBER_OF_PORTS
  72  *
  73  * @brief  Definition of the number of ports
  74  *
  75  */
  76 #ifdef __ixp46X
  77 #define IX_ETH_ACC_NUMBER_OF_PORTS (3)
  78 #else
  79 #define IX_ETH_ACC_NUMBER_OF_PORTS (2)
  80 #endif
  81
  82 /**
  83  * @ingroup IxEthAcc
  84  *
  85  * @def IX_IEEE803_MAC_ADDRESS_SIZE
  86  *
  87  * @brief  Definition of the size of the MAC address
  88  *
  89  */
  90 #define IX_IEEE803_MAC_ADDRESS_SIZE (6)
  91
  92
  93 /**
  94  *
  95  * @brief Definition of the IEEE 802.3 Ethernet MAC address structure.
  96  *
  97  * The data should be packed with bytes xx:xx:xx:xx:xx:xx
  98  * @note
  99  * The data must be packed in network byte order.
 100  */
 101 typedef struct
 102 {
 103     UINT8 macAddress[IX_IEEE803_MAC_ADDRESS_SIZE]; /**< MAC address */
 104 } IxEthAccMacAddr;
 105
 106 /**
 107  * @ingroup IxEthAcc
 108  * @def IX_ETH_ACC_NUM_TX_PRIORITIES
 109  * @brief Definition of the number of transmit priorities
 110  *
 111  */
 112 #define IX_ETH_ACC_NUM_TX_PRIORITIES (8)
 113
 114 /**
 115  * @ingroup IxEthAcc
 116  * @enum IxEthAccTxPriority
 117  * @brief Definition of the relative priority used to transmit a frame
 118  *
 119  */
 120 typedef enum
 121 {
 122         IX_ETH_ACC_TX_PRIORITY_0 = 0, /**<Lowest Priority submission */
 123         IX_ETH_ACC_TX_PRIORITY_1 = 1, /**<submission prority of 1 (0 is lowest)*/
 124         IX_ETH_ACC_TX_PRIORITY_2 = 2, /**<submission prority of 2 (0 is lowest)*/
 125         IX_ETH_ACC_TX_PRIORITY_3 = 3, /**<submission prority of 3 (0 is lowest)*/
 126         IX_ETH_ACC_TX_PRIORITY_4 = 4, /**<submission prority of 4 (0 is lowest)*/
 127         IX_ETH_ACC_TX_PRIORITY_5 = 5, /**<submission prority of 5 (0 is lowest)*/
 128         IX_ETH_ACC_TX_PRIORITY_6 = 6, /**<submission prority of 6 (0 is lowest)*/
 129         IX_ETH_ACC_TX_PRIORITY_7 = 7, /**<Highest priority submission */
 130
 131         IX_ETH_ACC_TX_DEFAULT_PRIORITY = IX_ETH_ACC_TX_PRIORITY_0 /**< By default send all
 132                                                                  packets with lowest priority */
 133 } IxEthAccTxPriority;
 134
 135 /**
 136  * @ingroup IxEthAcc
 137  * @enum IxEthAccRxFrameType
 138  * @brief Identify the type of a frame.
 139  *
 140  * @sa IX_ETHACC_NE_FLAGS
 141  * @sa IX_ETHACC_NE_LINKMASK
 142  */
 143 typedef enum
 144 {
 145         IX_ETHACC_RX_LLCTYPE = 0x00, /**< 802.3 - 8802, with LLC/SNAP */
 146         IX_ETHACC_RX_ETHTYPE = 0x10, /**< 802.3 (Ethernet) without LLC/SNAP */
 147         IX_ETHACC_RX_STATYPE = 0x20, /**< 802.11, AP <=> STA */
 148         IX_ETHACC_RX_APTYPE  = 0x30  /**< 802.11, AP <=> AP */
 149 } IxEthAccRxFrameType;
 150
 151 /**
 152  * @ingroup IxEthAcc
 153  * @enum IxEthAccDuplexMode
 154  * @brief Definition to provision the duplex mode of the MAC.
 155  *
 156  */
 157 typedef enum
 158 {
 159     IX_ETH_ACC_FULL_DUPLEX, /**< Full duplex operation of the MAC */
 160     IX_ETH_ACC_HALF_DUPLEX  /**< Half duplex operation of the MAC */
 161 } IxEthAccDuplexMode;
 162
 163
 164 /**
 165  * @ingroup IxEthAcc
 166  * @struct IxEthAccNe
 167  * @brief Definition of service-specific informations.
 168  *
 169  * This structure defines the Ethernet service-specific informations
 170  * and enable QoS and VLAN features.
 171  */
 172 typedef struct
 173 {
 174     UINT32 ixReserved_next;    /**< reserved for chaining */
 175     UINT32 ixReserved_lengths; /**< reserved for buffer lengths */
 176     UINT32 ixReserved_data;    /**< reserved for buffer pointer */
 177     UINT8  ixDestinationPortId; /**< Destination portId for this packet, if known by NPE */
 178     UINT8  ixSourcePortId; /**< Source portId for this packet */
 179     UINT16 ixFlags;        /**< BitField of option for this frame */
 180     UINT8  ixQoS;          /**< QoS class of the frame */
 181     UINT8  ixReserved;     /**< reserved */
 182     UINT16 ixVlanTCI;      /**< Vlan TCI */
 183     UINT8  ixDestMac[IX_IEEE803_MAC_ADDRESS_SIZE]; /**< Destination MAC address */
 184     UINT8  ixSourceMac[IX_IEEE803_MAC_ADDRESS_SIZE]; /**< Source MAC address */
 185 } IxEthAccNe;
 186
 187 /**
 188  * @ingroup IxEthAcc
 189  *
 190  * @def IX_ETHACC_NE_PORT_UNKNOWN
 191  *
 192  * @brief  Contents of the field @a IX_ETHACC_NE_DESTPORTID when no
 193  * destination port can be found by the NPE for this frame.
 194  *
 195  */
 196 #define IX_ETHACC_NE_PORT_UNKNOWN   (0xff)
 197
 198 /**
 199  * @ingroup IxEthAcc
 200  *
 201  * @def IX_ETHACC_NE_DESTMAC
 202  *
 203  * @brief The location of the destination MAC address in the Mbuf header.
 204  *
 205  */
 206 #define IX_ETHACC_NE_DESTMAC(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixDestMac
 207
 208 /**
 209  * @ingroup IxEthAcc
 210  *
 211  * @def IX_ETHACC_NE_SOURCEMAC
 212  *
 213  * @brief The location of the source MAC address in the Mbuf header.
 214  *
 215  */
 216 #define IX_ETHACC_NE_SOURCEMAC(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixSourceMac
 217
 218 /**
 219  * @ingroup IxEthAcc
 220  *
 221  * @def IX_ETHACC_NE_VLANTCI
 222  *
 223  * @brief The VLAN Tag Control Information associated with this frame
 224  *
 225  * The VLAN Tag Control Information associated with this frame. On Rx
 226  * path, this field is extracted from the packet header.
 227  * On Tx path, the value of this field is inserted in the frame when
 228  * the port is configured to insert or replace vlan tags in the
 229  * egress frames.
 230  *
 231  * @sa IX_ETHACC_NE_FLAGS
 232  */
 233 #define IX_ETHACC_NE_VLANTCI(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixVlanTCI
 234
 235 /**
 236  * @ingroup IxEthAcc
 237  *
 238  * @def IX_ETHACC_NE_SOURCEPORTID
 239  *
 240  * @brief The port where this frame came from.
 241  *
 242  * The port where this frame came from. This field is set on receive
 243  * with the port information. This field is ignored on Transmit path.
 244  */
 245 #define IX_ETHACC_NE_SOURCEPORTID(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixSourcePortId
 246
 247 /**
 248  * @ingroup IxEthAcc
 249  *
 250  * @def IX_ETHACC_NE_DESTPORTID
 251  *
 252  * @brief The destination port where this frame should be sent.
 253  *
 254  * The destination port where this frame should be sent.
 255  *
 256  * @li In the transmit direction, this field contains the destination port
 257  * and is ignored unless @a IX_ETHACC_NE_FLAG_DST is set.
 258  *
 259  * @li In the receive direction, this field contains the port where the
 260  * destination MAC addresses has been learned. If the destination
 261  * MAC address is unknown, then this value is set to the reserved value
 262  * @a IX_ETHACC_NE_PORT_UNKNOWN
 263  *
 264  */
 265 #define IX_ETHACC_NE_DESTPORTID(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixDestinationPortId
 266
 267 /**
 268  * @ingroup IxEthAcc
 269  *
 270  * @def IX_ETHACC_NE_QOS
 271  *
 272  * @brief QualityOfService class (QoS) for this received frame.
 273  *
 274  */
 275 #define IX_ETHACC_NE_QOS(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixQoS
 276
 277 /**
 278  * @ingroup IxEthAcc
 279  *
 280  * @def IX_ETHACC_NE_FLAGS
 281  *
 282  * @brief Bit Mask of the different flags associated with a frame
 283  *
 284  * The flags are the bit-oring combination
 285  * of the following different fields :
 286  *
 287  *      @li IP flag (Rx @a IX_ETHACC_NE_IPMASK)
 288  *      @li Spanning Tree flag (Rx @a IX_ETHACC_NE_STMASK)
 289  *      @li Link layer type (Rx and Tx @a IX_ETHACC_NE_LINKMASK)
 290  *      @li VLAN Tagged Frame (Rx @a IX_ETHACC_NE_VLANMASK)
 291  *      @li New source MAC address (Rx @a IX_ETHACC_NE_NEWSRCMASK)
 292  *      @li Multicast flag (Rx @a IX_ETHACC_NE_MCASTMASK)
 293  *      @li Broadcast flag (Rx @a IX_ETHACC_NE_BCASTMASK)
 294  *      @li Destination port flag (Tx @a IX_ETHACC_NE_PORTMASK)
 295  *      @li Tag/Untag Tx frame (Tx @a IX_ETHACC_NE_TAGMODEMASK)
 296  *      @li Overwrite destination port (Tx @a IX_ETHACC_NE_PORTOVERMASK)
 297  *      @li Filtered frame (Rx @a IX_ETHACC_NE_STMASK)
 298  *      @li VLAN Enabled (Rx and Tx @a IX_ETHACC_NE_VLANENABLEMASK)
 299  */
 300 #define IX_ETHACC_NE_FLAGS(mBufPtr) ((IxEthAccNe *)&((mBufPtr)->ix_ne))->ixFlags
 301
 302 /**
 303  * @ingroup IxEthAcc
 304  *
 305  * @def IX_ETHACC_NE_BCASTMASK
 306  *
 307  * @brief This mask defines if a received frame is a broadcast frame.
 308  *
 309  * This mask defines if a received frame is a broadcast frame.
 310  * The BCAST flag is set when the destination MAC address of
 311  * a frame is broadcast.
 312  *
 313  * @sa IX_ETHACC_NE_FLAGS
 314  *
 315  */
 316 #define IX_ETHACC_NE_BCASTMASK      (0x1)
 317
 318 /**
 319  * @ingroup IxEthAcc
 320  *
 321  * @def IX_ETHACC_NE_MCASTMASK
 322  *
 323  * @brief This mask defines if a received frame is a multicast frame.
 324  *
 325  * This mask defines if a received frame is a multicast frame.
 326  * The MCAST flag is set when the destination MAC address of
 327  * a frame is multicast.
 328  *
 329  * @sa IX_ETHACC_NE_FLAGS
 330  *
 331  */
 332 #define IX_ETHACC_NE_MCASTMASK      (0x1 << 1)
 333
 334 /**
 335  * @ingroup IxEthAcc
 336  *
 337  * @def IX_ETHACC_NE_IPMASK
 338  *
 339  * @brief This mask defines if a received frame is a IP frame.
 340  *
 341  * This mask applies to @a IX_ETHACC_NE_FLAGS and defines if a received
 342  * frame is a IP frame. The IP flag is set on Rx direction, depending on
 343  * the frame contents. The flag is set when the length/type field of a
 344  * received frame is 0x8000.
 345  *
 346  * @sa IX_ETHACC_NE_FLAGS
 347  *
 348  */
 349 #define IX_ETHACC_NE_IPMASK         (0x1 << 2)
 350
 351 /**
 352  * @ingroup IxEthAcc
 353  *
 354  * @def IX_ETHACC_NE_VLANMASK
 355  *
 356  * @brief This mask defines if a received frame is VLAN tagged.
 357  *
 358  * This mask defines if a received frame is VLAN tagged.
 359  * When set, the Rx frame is VLAN-tagged and the tag value
 360  * is available thru @a IX_ETHACC_NE_VLANID.
 361  * Note that when sending frames which are already tagged
 362  * this flag should be set, to avoid inserting another VLAN tag.
 363  *
 364  * @sa IX_ETHACC_NE_FLAGS
 365  * @sa IX_ETHACC_NE_VLANID
 366  *
 367  */
 368 #define IX_ETHACC_NE_VLANMASK       (0x1 << 3)
 369
 370 /**
 371  * @ingroup IxEthAcc
 372  *
 373  * @def IX_ETHACC_NE_LINKMASK
 374  *
 375  * @brief This mask is the link layer protocol indicator
 376  *
 377  * This mask applies to @a IX_ETHACC_NE_FLAGS.
 378  * It reflects the state of a frame as it exits an NPE on the Rx path
 379  * or enters an NPE on the Tx path. Its values are as follows:
 380  *      @li 0x00 - IEEE802.3 - 8802 (Rx) / IEEE802.3 - 8802 (Tx)
 381  *      @li 0x01 - IEEE802.3 - Ethernet (Rx) / IEEE802.3 - Ethernet (Tx)
 382  *      @li 0x02 - IEEE802.11 AP -> STA (Rx) / IEEE802.11 STA -> AP (Tx)
 383  *      @li 0x03 - IEEE802.11 AP -> AP (Rx) / IEEE802.11 AP->AP (Tx)
 384  *
 385  * @sa IX_ETHACC_NE_FLAGS
 386  *
 387  */
 388 #define IX_ETHACC_NE_LINKMASK       (0x3 << 4)
 389
 390 /**
 391  * @ingroup IxEthAcc
 392  *
 393  * @def IX_ETHACC_NE_STMASK
 394  *
 395  * @brief This mask defines if a received frame is a Spanning Tree frame.
 396  *
 397  * This mask applies to @a IX_ETHACC_NE_FLAGS.
 398  * On rx direction, it defines if a received if frame is a Spanning Tree frame.
 399  * Setting this fkag on transmit direction overrides the port settings
 400  * regarding the VLAN options and
 401  *
 402  * @sa IX_ETHACC_NE_FLAGS
 403  *
 404  */
 405 #define IX_ETHACC_NE_STMASK         (0x1 << 6)
 406
 407 /**
 408  * @ingroup IxEthAcc
 409  *
 410  * @def IX_ETHACC_NE_FILTERMASK
 411  *
 412  * @brief This bit indicates whether a frame has been filtered by the Rx service.
 413  *
 414  * This mask applies to @a IX_ETHACC_NE_FLAGS.
 415  * Certain frames, which should normally be fully filtered by the NPE to due
 416  * the destination MAC address being on the same segment as the Rx port are
 417  * still forwarded to the XScale (although the payload is invalid) in order
 418  * to learn the MAC address of the transmitting station, if this is unknown.
 419  * Normally EthAcc will filter and recycle these framess internally and no
 420  * frames with the FILTER bit set will be received by the client.
 421  *
 422  * @sa IX_ETHACC_NE_FLAGS
 423  *
 424  */
 425 #define IX_ETHACC_NE_FILTERMASK     (0x1 << 7)
 426
 427 /**
 428  * @ingroup IxEthAcc
 429  *
 430  * @def IX_ETHACC_NE_PORTMASK
 431  *
 432  * @brief This mask defines the rule to transmit a frame
 433  *
 434  * This mask defines the rule to transmit a frame. When set, a frame
 435  * is transmitted to the destination port as set by the macro
 436  * @a IX_ETHACC_NE_DESTPORTID. If not set, the destination port
 437  * is searched using the destination MAC address.
 438  *
 439  * @note This flag is meaningful only for multiport Network Engines.
 440  *
 441  * @sa IX_ETHACC_NE_FLAGS
 442  * @sa IX_ETHACC_NE_DESTPORTID
 443  *
 444  */
 445 #define IX_ETHACC_NE_PORTOVERMASK   (0x1 << 8)
 446
 447 /**
 448  * @ingroup IxEthAcc
 449  *
 450  * @def IX_ETHACC_NE_TAGMODEMASK
 451  *
 452  * @brief This mask defines the tagging rules to apply to a transmit frame.
 453  *
 454  * This mask defines the tagging rules to apply to a transmit frame
 455  * regardless of the default setting for a port. When used together
 456  * with @a IX_ETHACC_NE_TAGOVERMASK and when set, the
 457  * frame will be tagged prior to transmission. When not set,
 458  * the frame will be untagged prior to transmission. This is accomplished
 459  * irrespective of the Egress tagging rules, constituting a per-frame override.
 460  *
 461  * @sa IX_ETHACC_NE_FLAGS
 462  * @sa IX_ETHACC_NE_TAGOVERMASK
 463  *
 464  */
 465 #define IX_ETHACC_NE_TAGMODEMASK    (0x1 << 9)
 466
 467 /**
 468  * @ingroup IxEthAcc
 469  *
 470  * @def IX_ETHACC_NE_TAGOVERMASK
 471  *
 472  * @brief This mask defines the rule to transmit a frame
 473  *
 474  * This mask defines the rule to transmit a frame. When set, the
 475  * default transmit rules of a port are overriden.
 476  * When not set, the default rules as set by @ref IxEthDB should apply.
 477  *
 478  * @sa IX_ETHACC_NE_FLAGS
 479  * @sa IX_ETHACC_NE_TAGMODEMASK
 480  *
 481  */
 482 #define IX_ETHACC_NE_TAGOVERMASK    (0x1 << 10)
 483
 484 /**
 485  * @ingroup IxEthAcc
 486  *
 487  * @def IX_ETHACC_NE_VLANENABLEMASK
 488  *
 489  * @brief This mask defines if a frame is a VLAN frame or not
 490  *
 491  * When set, frames undergo normal VLAN processing on the Tx path
 492  * (membership filtering, tagging, tag removal etc). If this flag is
 493  * not set, the frame is considered to be a regular non-VLAN frame
 494  * and no VLAN processing will be performed.
 495  *
 496  * Note that VLAN-enabled NPE images will always set this flag in all
 497  * Rx frames, and images which are not VLAN enabled will clear this
 498  * flag for all received frames.
 499  *
 500  * @sa IX_ETHACC_NE_FLAGS
 501  *
 502  */
 503 #define IX_ETHACC_NE_VLANENABLEMASK (0x1 << 14)
 504
 505 /**
 506  * @ingroup IxEthAcc
 507  *
 508  * @def IX_ETHACC_NE_NEWSRCMASK
 509  *
 510  * @brief This mask defines if a received frame has been learned.
 511  *
 512  * This mask defines if the source MAC address of a frame is
 513  * already known. If the bit is set, the source MAC address was
 514  * unknown to the NPE at the time the frame was received.
 515  *
 516  * @sa IX_ETHACC_NE_FLAGS
 517  *
 518  */
 519 #define IX_ETHACC_NE_NEWSRCMASK     (0x1 << 15)
 520
 521 /**
 522  * @ingroup IxEthAcc
 523  *
 524  * @brief This defines the recommanded minimum size of MBUF's submitted
 525  * to the frame receive service.
 526  *
 527  */
 528 #define IX_ETHACC_RX_MBUF_MIN_SIZE (2048)
 529
 530 /**
 531  * @ingroup IxEthAcc
 532  *
 533  * @brief This defines the highest MII address of any attached PHYs
 534  *
 535  * The maximum number for PHY address is 31, add on for range checking.
 536  *
 537  */
 538 #define IXP425_ETH_ACC_MII_MAX_ADDR   32
 539
 540 /**
 541  * @ingroup IxEthAcc
 542  *
 543  * @fn ixEthAccInit(void)
 544  *
 545  * @brief Initializes the IXP400 Ethernet Access Service.
 546  *
 547  * @li Reentrant    - no
 548  * @li ISR Callable - no
 549  *
 550  * This should be called once per module initialization.
 551  * @pre
 552  *   The NPE must first be downloaded with the required microcode which supports all
 553  *   required features.
 554  *
 555  * @return IxEthAccStatus
 556  * @li @a IX_ETH_ACC_SUCCESS
 557  * @li @a IX_ETH_ACC_FAIL       :  Service has failed to initialize.
 558  *
 559  * <hr>
 560  */
 561 PUBLIC IxEthAccStatus ixEthAccInit(void);
 562
 563
 564 /**
 565  * @ingroup IxEthAcc
 566  *
 567  * @fn ixEthAccUnload(void)
 568  *
 569  * @brief Unload the Ethernet Access Service.
 570  *
 571  * @li Reentrant    - no
 572  * @li ISR Callable - no
 573  *
 574  * @return void
 575  *
 576  * <hr>
 577  */
 578 PUBLIC void ixEthAccUnload(void);
 579
 580 /**
 581  * @ingroup IxEthAcc
 582  *
 583  * @fn ixEthAccPortInit( IxEthAccPortId portId)
 584  *
 585  * @brief Initializes an NPE/Ethernet MAC Port.
 586  *
 587  * The NPE/Ethernet port initialisation includes the following steps
 588  * @li Initialize the NPE/Ethernet MAC hardware.
 589  * @li Verify NPE downloaded and operational.
 590  * @li The NPE shall be available for usage once this API returns.
 591  * @li Verify that the Ethernet port is present before initializing
 592  *
 593  * @li Reentrant    - no
 594  * @li ISR Callable - no
 595  *
 596  * This should be called once per mac device.
 597  * The NPE/MAC shall be in disabled state after init.
 598  *
 599  * @pre
 600  *   The component must be initialized via @a ixEthAccInit
 601  *   The NPE must first be downloaded with the required microcode which supports all
 602  *   required features.
 603  *
 604  * Dependant on Services: (Must be initialized before using this service may be initialized)
 605  *      ixNPEmh - NPE Message handling service.
 606  *      ixQmgr  - Queue Manager component.
 607  *
 608  * @param portId  @ref IxEthAccPortId [in]
 609  *
 610  * @return IxEthAccStatus
 611  * @li @a IX_ETH_ACC_SUCCESS: if the ethernet port is not present, a warning is issued.
 612  * @li @a IX_ETH_ACC_FAIL : The NPE processor has failed to initialize.
 613  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 614  *
 615  * <hr>
 616  */
 617 PUBLIC IxEthAccStatus ixEthAccPortInit(IxEthAccPortId portId);
 618
 619
 620 /*************************************************************************
 621
 622  #####     ##     #####    ##            #####     ##     #####  #    #
 623  #    #   #  #      #     #  #           #    #   #  #      #    #    #
 624  #    #  #    #     #    #    #          #    #  #    #     #    ######
 625  #    #  ######     #    ######          #####   ######     #    #    #
 626  #    #  #    #     #    #    #          #       #    #     #    #    #
 627  #####   #    #     #    #    #          #       #    #     #    #    #
 628
 629 *************************************************************************/
 630
 631
 632 /**
 633  * @ingroup IxEthAcc
 634  *
 635  * @fn ixEthAccPortTxFrameSubmit(
 636     IxEthAccPortId portId,
 637     IX_OSAL_MBUF *buffer,
 638     IxEthAccTxPriority priority)
 639  *
 640  * @brief This function shall be used to submit MBUFs buffers for transmission on a particular MAC device.
 641  *
 642  * When the frame is transmitted, the buffer shall be returned thru the
 643  * callback @a IxEthAccPortTxDoneCallback.
 644  *
 645  * In case of over-submitting, the order of the frames on the
 646  * network may be modified.
 647  *
 648  * Buffers shall be not queued for transmission if the port is disabled.
 649  * The port can be enabled using @a ixEthAccPortEnable
 650  *
 651  *
 652  * @li Reentrant    - yes
 653  * @li ISR Callable - yes
 654  *
 655  *
 656  * @pre
 657  *  @a ixEthAccPortTxDoneCallbackRegister must be called to register a function to allow this service to
 658  *   return the buffer to the calling service.
 659  *
 660  * @note
 661  *  If the buffer submit fails for any reason the user has retained ownership of the buffer.
 662  *
 663  * @param portId @ref IxEthAccPortId [in] - MAC port ID to transmit Ethernet frame on.
 664  * @param buffer @ref IX_OSAL_MBUF [in] - pointer to an MBUF formatted buffer. Chained buffers are supported for transmission.
 665  *             Chained packets are not supported and the field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is ignored.
 666  * @param priority @ref IxEthAccTxPriority [in]
 667  *
 668  * @return IxEthAccStatus
 669  * @li @a IX_ETH_ACC_SUCCESS
 670  * @li @a IX_ETH_ACC_FAIL  : Failed to queue frame for transmission.
 671  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 672  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 673  *
 674  * <hr>
 675  */
 676
 677 PUBLIC IxEthAccStatus ixEthAccPortTxFrameSubmit(
 678     IxEthAccPortId portId,
 679     IX_OSAL_MBUF *buffer,
 680     IxEthAccTxPriority priority);
 681
 682 /**
 683  * @ingroup IxEthAcc
 684  *
 685  * @brief Function prototype for Ethernet Tx Buffer Done callback. Registered
 686  *  via @a ixEthAccTxBufferDoneCallbackRegister
 687  *
 688  * This function is called once the previously submitted buffer is no longer required by this service.
 689  * It may be returned upon successful transmission of the frame or during the shutdown of
 690  * the port prior to the transmission of a queued frame.
 691  * The calling of this registered function is not a guarantee of successful transmission of the buffer.
 692  *
 693  *
 694  * @li Reentrant    - yes , The user provided function should be reentrant.
 695  * @li ISR Callable - yes , The user provided function must be callable from an ISR.
 696  *
 697  *
 698  * <b>Calling Context </b>:
 699  * @par
 700  *   This callback is called in the context of the queue manager dispatch loop @a ixQmgrgrDispatcherLoopRun
 701  *   within the @ref IxQMgrAPI component. The calling context may be from interrupt or high priority thread.
 702  *   The decision is system specific.
 703  *
 704  * @param callbackTag UINT32 [in] - This tag is that provided when the callback was registered for a particular MAC
 705  * via @a ixEthAccPortTxDoneCallbackRegister. It allows the same callback to be used for multiple MACs.
 706  * @param mbuf @ref IX_OSAL_MBUF [in] - Pointer to the Tx mbuf descriptor.
 707  *
 708  * @return void
 709  *
 710  * @note
 711  * The field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is modified by the access layer and reset to NULL.
 712  *
 713  * <hr>
 714  */
 715 typedef void (*IxEthAccPortTxDoneCallback) ( UINT32 callbackTag, IX_OSAL_MBUF *buffer );
 716
 717
 718
 719 /**
 720  * @ingroup IxEthAcc
 721  *
 722  * @fn ixEthAccPortTxDoneCallbackRegister( IxEthAccPortId portId,
 723                                            IxEthAccPortTxDoneCallback txCallbackFn,
 724                                            UINT32 callbackTag)
 725  *
 726  * @brief Register a callback function to allow
 727  * the transmitted buffers to return to the user.
 728  *
 729  * This function registers the transmit buffer done function callback for a particular port.
 730  *
 731  * The registered callback function is called once the previously submitted buffer is no longer required by this service.
 732  * It may be returned upon successful transmission of the frame or  shutdown of port prior to submission.
 733  * The calling of this registered function is not a guarantee of successful transmission of the buffer.
 734  *
 735  * If called several times the latest callback shall be registered for a particular port.
 736  *
 737  * @li Reentrant    - yes
 738  * @li ISR Callable - yes
 739  *
 740  * @pre
 741  *      The port must be initialized via @a ixEthAccPortInit
 742  *
 743  *
 744  * @param portId @ref IxEthAccPortId [in] - Register callback for a particular MAC device.
 745  * @param txCallbackFn @ref IxEthAccPortTxDoneCallback [in] - Function to be called to return transmit buffers to the user.
 746  * @param callbackTag UINT32 [in] -  This tag shall be provided to the callback function.
 747  *
 748  * @return IxEthAccStatus
 749  * @li @a IX_ETH_ACC_SUCCESS
 750  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 751  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 752  * @li @a IX_ETH_ACC_INVALID_ARG : An argument other than portId is invalid.
 753  *
 754  * <hr>
 755  */
 756 PUBLIC IxEthAccStatus
 757 ixEthAccPortTxDoneCallbackRegister(IxEthAccPortId portId,
 758                                                                    IxEthAccPortTxDoneCallback txCallbackFn,
 759                                                                    UINT32 callbackTag);
 760
 761
 762
 763 /**
 764  * @ingroup IxEthAcc
 765  *
 766  * @brief Function prototype for Ethernet Frame Rx callback. Registered via @a ixEthAccPortRxCallbackRegister
 767  *
 768  * It is the responsibility of the user function to free any MBUF's which it receives.
 769  *
 770  * @li Reentrant    - yes , The user provided function should be reentrant.
 771  * @li ISR Callable - yes , The user provided function must be callable from an ISR.
 772  * @par
 773  *
 774  * This function dispatches frames to the user level
 775  * via the provided function. The invocation shall be made for each
 776  * frame dequeued from the Ethernet QM queue. The user is required to free any MBUF's
 777  * supplied via this callback. In addition the registered callback must free up MBUF's
 778  * from the receive free queue when the port is disabled
 779  *
 780  * If called several times the latest callback shall be registered for a particular port.
 781  *
 782  * <b>Calling Context </b>:
 783  * @par
 784  *   This callback is called in the context of the queue manager dispatch loop @a ixQmgrgrDispatcherLoopRun
 785  *   within the @ref IxQMgrAPI component. The calling context may be from interrupt or high priority thread.
 786  *   The decision is system specific.
 787  *
 788  *
 789  * @param callbackTag UINT32 [in] - This tag is that provided when the callback was registered for a particular MAC
 790  * via @a ixEthAccPortRxCallbackRegister. It allows the same callback to be used for multiple MACs.
 791  * @param mbuf @ref IX_OSAL_MBUF [in] - Pointer to the Rx mbuf header. Mbufs may be chained if
 792  *               the frame length is greater than the supplied mbuf length.
 793  * @param reserved [in] - deprecated parameter The information is passed
 794  *      thru the IxEthAccNe header destination port ID field
 795  *      (@sa IX_ETHACC_NE_DESTPORTID). For backward
 796  *      compatibility,the value is equal to IX_ETH_DB_UNKNOWN_PORT (0xff).
 797  *
 798  * @return void
 799  *
 800  * @note
 801  * Buffers may not be filled up to the length supplied in
 802  * @a ixEthAccPortRxFreeReplenish(). The firmware fills
 803  * them to the previous 64 bytes boundary. The user has to be aware
 804  * that the length of the received mbufs may be smaller than the length
 805  * of the supplied mbufs.
 806  * The mbuf header contains the following modified field
 807  * @li @a IX_OSAL_MBUF_PKT_LEN is set in the header of the first mbuf and indicates
 808  *  the total frame size
 809  * @li @a IX_OSAL_MBUF_MLEN is set each mbuf header and indicates the payload length
 810  * @li @a IX_OSAL_MBUF_NEXT_BUFFER_IN_PKT_PTR contains a pointer to the next
 811  *     mbuf, or NULL at the end of a chain.
 812  * @li @a IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is modified. Its value is reset to NULL
 813  * @li @a IX_OSAL_MBUF_FLAGS contains the bit 4 set for a broadcast packet and the bit 5
 814  *     set for a multicast packet. Other bits are unmodified.
 815  *
 816  * <hr>
 817  */
 818 typedef void (*IxEthAccPortRxCallback) (UINT32 callbackTag, IX_OSAL_MBUF *buffer, UINT32 reserved);
 819
 820 /**
 821  * @ingroup IxEthAcc
 822  *
 823  * @brief Function prototype for Ethernet Frame Rx callback. Registered via @a ixEthAccPortMultiBufferRxCallbackRegister
 824  *
 825  * It is the responsibility of the user function to free any MBUF's which it receives.
 826  *
 827  * @li Reentrant    - yes , The user provided function should be reentrant.
 828  * @li ISR Callable - yes , The user provided function must be callable from an ISR.
 829  * @par
 830  *
 831  * This function dispatches many frames to the user level
 832  * via the provided function. The invocation shall be made for multiple frames
 833  * dequeued from the Ethernet QM queue. The user is required to free any MBUF's
 834  * supplied via this callback. In addition the registered callback must free up MBUF's
 835  * from the receive free queue when the port is disabled
 836  *
 837  * If called several times the latest callback shall be registered for a particular port.
 838  *
 839  * <b>Calling Context </b>:
 840  * @par
 841  *   This callback is called in the context of the queue manager dispatch loop @a ixQmgrDispatcherLoopRun
 842  *   within the @ref IxQMgrAPI component. The calling context may be from interrupt or high priority thread.
 843  *   The decision is system specific.
 844  *
 845  *
 846  * @param callbackTag - This tag is that provided when the callback was registered for a particular MAC
 847  * via @a ixEthAccPortMultiBufferRxCallbackRegister. It allows the same callback to be used for multiple MACs.
 848  * @param mbuf - Pointer to an array of Rx mbuf headers. Mbufs
 849  *               may be chained if
 850  *               the frame length is greater than the supplied mbuf length.
 851  *               The end of the array contains a zeroed entry (NULL pointer).
 852  *
 853  * @return void
 854  *
 855  * @note The mbufs passed to this callback have the same structure than the
 856  *  buffers passed to @a IxEthAccPortRxCallback interfac.
 857  *
 858  * @note The usage of this callback is exclusive with the usage of
 859  *  @a ixEthAccPortRxCallbackRegister and @a IxEthAccPortRxCallback
 860  *
 861  * @sa ixEthAccPortMultiBufferRxCallbackRegister
 862  * @sa IxEthAccPortMultiBufferRxCallback
 863  * @sa ixEthAccPortRxCallbackRegister
 864  * @sa IxEthAccPortRxCallback
 865  * <hr>
 866  */
 867
 868 typedef void (*IxEthAccPortMultiBufferRxCallback) (UINT32 callbackTag, IX_OSAL_MBUF **buffer);
 869
 870
 871
 872
 873 /**
 874  * @ingroup IxEthAcc
 875  *
 876  * @fn ixEthAccPortRxCallbackRegister( IxEthAccPortId portId, IxEthAccPortRxCallback rxCallbackFn, UINT32 callbackTag)
 877  *
 878  * @brief Register a callback function to allow
 879  * the reception of frames.
 880  *
 881  * The registered callback function is called once a frame is received  by this service.
 882  *
 883  * If called several times the latest callback shall be registered for a particular port.
 884  *
 885  *
 886  * @li Reentrant    - yes
 887  * @li ISR Callable - yes
 888  *
 889  *
 890  * @param portId @ref IxEthAccPortId [in] - Register callback for a particular MAC device.
 891  * @param rxCallbackFn @ref IxEthAccPortRxCallback [in] - Function to be called when Ethernet frames are availble.
 892  * @param callbackTag UINT32 [in] -  This tag shall be provided to the callback function.
 893  *
 894  * @return IxEthAccStatus
 895  * @li @a IX_ETH_ACC_SUCCESS
 896  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 897  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 898  * @li @a IX_ETH_ACC_INVALID_ARG : An argument other than portId is invalid.
 899  *
 900  * <hr>
 901  */
 902 PUBLIC IxEthAccStatus
 903 ixEthAccPortRxCallbackRegister(IxEthAccPortId portId,
 904                                                            IxEthAccPortRxCallback rxCallbackFn,
 905                                                            UINT32 callbackTag);
 906
 907
 908 /**
 909  * @ingroup IxEthAcc
 910  *
 911  * @fn ixEthAccPortMultiBufferRxCallbackRegister( IxEthAccPortId portId, IxEthAccPortMultiBufferRxCallback rxCallbackFn, UINT32 callbackTag)
 912  *
 913  * @brief Register a callback function to allow
 914  * the reception of frames.
 915  *
 916  * The registered callback function is called once a frame is
 917  * received  by this service. If many frames are already received,
 918  * the function is called once.
 919  *
 920  * If called several times the latest callback shall be registered for a particular port.
 921  *
 922  * @li Reentrant    - yes
 923  * @li ISR Callable - yes
 924  *
 925  *
 926  * @param portId - Register callback for a particular MAC device.
 927  * @param rxCallbackFn - @a IxEthAccMultiBufferRxCallbackFn - Function to be called when Ethernet frames are availble.
 928  * @param callbackTag -  This tag shall be provided to the callback function.
 929  *
 930  * @return IxEthAccStatus
 931  * @li @a IX_ETH_ACC_SUCCESS
 932  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 933  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 934  * @li @a IX_ETH_ACC_INVALID_ARG : An argument other than portId is invalid.
 935  *
 936  * @sa ixEthAccPortMultiBufferRxCallbackRegister
 937  * @sa IxEthAccPortMultiBufferRxCallback
 938  * @sa ixEthAccPortRxCallbackRegister
 939  * @sa IxEthAccPortRxCallback
 940  * <hr>
 941  */
 942 PUBLIC IxEthAccStatus
 943 ixEthAccPortMultiBufferRxCallbackRegister(IxEthAccPortId portId,
 944                                                                                   IxEthAccPortMultiBufferRxCallback rxCallbackFn,
 945                                                                                   UINT32 callbackTag);
 946
 947 /**
 948  * @ingroup IxEthAcc
 949  *
 950  * @fn ixEthAccPortRxFreeReplenish( IxEthAccPortId portId, IX_OSAL_MBUF *buffer)
 951  *
 952  * @brief This function provides buffers for the Ethernet receive path.
 953  *
 954  * This component does not have a buffer management mechanisms built in. All Rx buffers must be supplied to it
 955  * via this interface.
 956  *
 957  * @li Reentrant    - yes
 958  * @li ISR Callable - yes
 959  *
 960  * @param portId @ref IxEthAccPortId [in] - Provide buffers only to specific Rx MAC.
 961  * @param buffer @ref IX_OSAL_MBUF [in] - Provide an MBUF to the Ethernet receive mechanism.
 962  *                 Buffers size smaller than IX_ETHACC_RX_MBUF_MIN_SIZE may result in poor
 963  *                 performances and excessive buffer chaining. Buffers
 964  *                 larger than this size may be suitable for jumbo frames.
 965  *                 Chained packets are not supported and the field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR must be NULL.
 966  *
 967  * @return IxEthAccStatus
 968  * @li @a IX_ETH_ACC_SUCCESS
 969  * @li @a IX_ETH_ACC_FAIL : Buffer has was not able to queue the
 970  *                     buffer in the receive service.
 971  * @li @a IX_ETH_ACC_FAIL : Buffer size is less than IX_ETHACC_RX_MBUF_MIN_SIZE
 972  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 973  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 974  *
 975  * @note
 976  * If the buffer replenish operation fails it is the responsibility
 977  * of the user to free the buffer.
 978  *
 979  * @note
 980  * Sufficient buffers must be supplied to the component to maintain
 981  * receive throughput and avoid rx buffer underflow conditions.
 982  * To meet this goal, It is expected that the user preload the
 983  * component with a sufficent number of buffers prior to enabling the
 984  * NPE Ethernet receive path. The recommended minimum number of
 985  * buffers is 8.
 986  *
 987  * @note
 988  * For maximum performances, the mbuf size should be greater
 989  * than the maximum frame size (Ethernet header, payload and FCS) + 64.
 990  * Supplying smaller mbufs to the service results in mbuf
 991  * chaining and degraded performances. The recommended size
 992  * is @a IX_ETHACC_RX_MBUF_MIN_SIZE, which is
 993  * enough to take care of 802.3 frames and "baby jumbo" frames without
 994  * chaining, and "jumbo" frame within chaining.
 995  *
 996  * @note
 997  * Buffers may not be filled up to their length. The firware fills
 998  * them up to the previous 64 bytes boundary. The user has to be aware
 999  * that the length of the received mbufs may be smaller than the length
1000  * of the supplied mbufs.
1001  *
1002  * @warning This function checks the parameters if the NDEBUG
1003  * flag is not defined. Turning on the argument checking (disabled by
1004  * default) results in a lower EthAcc performance as this function
1005  * is part of the data path.
1006  *
1007  * <hr>
1008  */
1009 PUBLIC IxEthAccStatus
1010 ixEthAccPortRxFreeReplenish( IxEthAccPortId portId, IX_OSAL_MBUF *buffer);
1011
1012
1013
1014 /***************************************************************
1015
1016   ####    ####   #    #   #####  #####    ####   #
1017  #    #  #    #  ##   #     #    #    #  #    #  #
1018  #       #    #  # #  #     #    #    #  #    #  #
1019  #       #    #  #  # #     #    #####   #    #  #
1020  #    #  #    #  #   ##     #    #   #   #    #  #
1021   ####    ####   #    #     #    #    #   ####   ######
1022
1023
1024          #####   #         ##    #    #  ######
1025          #    #  #        #  #   ##   #  #
1026          #    #  #       #    #  # #  #  #####
1027          #####   #       ######  #  # #  #
1028          #       #       #    #  #   ##  #
1029          #       ######  #    #  #    #  ######
1030
1031 ***************************************************************/
1032
1033 /**
1034  * @ingroup IxEthAcc
1035  *
1036  * @fn ixEthAccPortEnable(IxEthAccPortId portId)
1037  *
1038  * @brief This enables an Ethernet port for both Tx and Rx.
1039  *
1040  * @li Reentrant    - yes
1041  * @li ISR Callable - no
1042  *
1043  * @pre The port must first be initialized via @a ixEthAccPortInit and the MAC address
1044  * must be set using @a ixEthAccUnicastMacAddressSet before enabling it
1045  * The rx and Tx Done callbacks registration via @a
1046  * ixEthAccPortTxDoneCallbackRegister amd @a  ixEthAccPortRxCallbackRegister
1047  * has to be done before enabling the traffic.
1048  *
1049  * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
1050  *
1051  * @return IxEthAccStatus
1052  * @li @a IX_ETH_ACC_SUCCESS
1053  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1054  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is not initialized
1055  * @li @a IX_ETH_ACC_MAC_UNINITIALIZED : port MAC address is not initialized
1056  *
1057  * <hr>
1058  */
1059 PUBLIC IxEthAccStatus ixEthAccPortEnable(IxEthAccPortId portId);
1060
1061 /**
1062  * @ingroup IxEthAcc
1063  *
1064  * @fn ixEthAccPortDisable(IxEthAccPortId portId)
1065  *
1066  * @brief This disables an Ethernet port for both Tx and Rx.
1067  *
1068  * Free MBufs are returned to the user via the registered callback when the port is disabled
1069  *
1070  * @li Reentrant    - yes
1071  * @li ISR Callable - no
1072  *
1073  * @pre The port must be enabled with @a ixEthAccPortEnable, otherwise this
1074  * function has no effect
1075  *
1076  * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
1077  *
1078  * @return IxEthAccStatus
1079  * @li @a IX_ETH_ACC_SUCCESS
1080  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1081  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is not initialized
1082  * @li @a IX_ETH_ACC_MAC_UNINITIALIZED : port MAC address is not initialized
1083  *
1084  * <hr>
1085  */
1086 PUBLIC IxEthAccStatus ixEthAccPortDisable(IxEthAccPortId portId);
1087
1088 /**
1089  * @ingroup IxEthAcc
1090  *
1091  * @fn ixEthAccPortEnabledQuery(IxEthAccPortId portId, BOOL *enabled)
1092  *
1093  * @brief Get the enabled state of a port.
1094  *
1095  * @li Reentrant    - yes
1096  * @li ISR Callable - yes
1097  *
1098  * @pre The port must first be initialized via @a ixEthAccPortInit
1099  *
1100  * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
1101  * @param  enabled BOOL [out] - location to store the state of the port
1102  *
1103  * @return IxEthAccStatus
1104  * @li @a IX_ETH_ACC_SUCCESS
1105  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid
1106  *
1107  * <hr>
1108  */
1109 PUBLIC IxEthAccStatus
1110 ixEthAccPortEnabledQuery(IxEthAccPortId portId, BOOL *enabled);
1111
1112 /**
1113  * @ingroup IxEthAcc
1114  *
1115  * @fn ixEthAccPortPromiscuousModeClear(IxEthAccPortId portId)
1116  *
1117  * @brief Put the Ethernet MAC device in non-promiscuous mode.
1118  *
1119  * In non-promiscuous mode the MAC filters all frames other than
1120  * destination MAC address which matches the following criteria:
1121  * @li Unicast address provisioned via @a ixEthAccUnicastMacAddressSet
1122  * @li All broadcast frames.
1123  * @li Multicast addresses provisioned via @a ixEthAccMulticastAddressJoin
1124  *
1125  * Other functions modify the MAC filtering
1126  *
1127  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1128  *     frames are forwarded to the application
1129  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1130  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1131  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1132  *     filtering address
1133  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1134  *     filtering address
1135  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1136  *     forwarded to the application regardless of the multicast
1137  *     address provisioned
1138  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1139  *     to the application following the multicast address provisioned
1140  *
1141  * In all cases, unicast and broadcast addresses are forwarded to
1142  * the application.
1143  *
1144  * @li Reentrant    - yes
1145  * @li ISR Callable - no
1146  *
1147  * @sa ixEthAccPortPromiscuousModeSet
1148  *
1149  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1150  *
1151  * @return IxEthAccStatus
1152  * @li @a IX_ETH_ACC_SUCCESS
1153  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1154  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1155  *
1156  * <hr>
1157  */
1158 PUBLIC IxEthAccStatus ixEthAccPortPromiscuousModeClear(IxEthAccPortId portId);
1159
1160
1161 /**
1162  * @ingroup IxEthAcc
1163  *
1164  * @fn  ixEthAccPortPromiscuousModeSet(IxEthAccPortId portId)
1165  *
1166  * @brief Put the MAC device in promiscuous mode.
1167  *
1168  * If the device is in promiscuous mode then all all received frames shall be forwared
1169  * to the NPE for processing.
1170  *
1171  * Other functions modify the MAC filtering
1172  *
1173  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1174  *     frames are forwarded to the application
1175  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1176  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1177  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1178  *     filtering address
1179  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1180  *     filtering address
1181  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1182  *     forwarded to the application regardless of the multicast
1183  *     address provisioned
1184  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1185  *     to the application following the multicast address provisioned
1186  *
1187  * In all cases, unicast and broadcast addresses are forwarded to
1188  * the application.
1189  *
1190  * @li Reentrant    - yes
1191  * @li ISR Callable - no
1192  *
1193  * @sa ixEthAccPortPromiscuousModeClear
1194  *
1195  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1196  *
1197  * @return IxEthAccStatus
1198  * @li @a IX_ETH_ACC_SUCCESS
1199  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1200  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1201  *
1202  * <hr>
1203  */
1204 PUBLIC IxEthAccStatus ixEthAccPortPromiscuousModeSet(IxEthAccPortId portId);
1205
1206 /**
1207  * @ingroup IxEthAcc
1208  *
1209  * @fn ixEthAccPortUnicastMacAddressSet(      IxEthAccPortId portId,
1210                                                   IxEthAccMacAddr *macAddr)
1211  *
1212  * @brief Configure unicast MAC address for a particular port
1213  *
1214  *
1215  * @li Reentrant    - yes
1216  * @li ISR Callable - no
1217  *
1218  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1219  * @param *macAddr @ref IxEthAccMacAddr [in] - Ethernet Mac address.
1220  *
1221  * @return IxEthAccStatus
1222  * @li @a IX_ETH_ACC_SUCCESS
1223  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1224  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1225  *
1226  * <hr>
1227  */
1228 PUBLIC IxEthAccStatus ixEthAccPortUnicastMacAddressSet(IxEthAccPortId portId,
1229                                                                                                            IxEthAccMacAddr *macAddr);
1230
1231 /**
1232  * @ingroup IxEthAcc
1233  *
1234  * @fn ixEthAccPortUnicastMacAddressGet(        IxEthAccPortId portId,
1235                                         IxEthAccMacAddr *macAddr)
1236  *
1237  * @brief Get unicast MAC address for a particular MAC port
1238  *
1239  * @pre
1240  * The MAC address must first be set via @a ixEthAccMacPromiscuousModeSet
1241  * If the MAC address has not been set, the function returns a
1242  * IX_ETH_ACC_MAC_UNINITIALIZED status
1243  *
1244  * @li Reentrant    - yes
1245  * @li ISR Callable - no
1246  *
1247  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1248  * @param *macAddr @ref IxEthAccMacAddr [out] - Ethernet MAC address.
1249  *
1250  * @return  IxEthAccStatus
1251  * @li @a IX_ETH_ACC_SUCCESS
1252  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1253  * @li @a IX_ETH_ACC_MAC_UNINITIALIZED : port MAC address is not initialized.
1254  * @li @a IX_ETH_ACC_FAIL : macAddr is invalid.
1255  *
1256  * <hr>
1257  */
1258 PUBLIC IxEthAccStatus
1259 ixEthAccPortUnicastMacAddressGet(IxEthAccPortId portId,
1260                                                                  IxEthAccMacAddr *macAddr);
1261
1262
1263
1264
1265 /**
1266  * @ingroup IxEthAcc
1267  *
1268  * @fn ixEthAccPortMulticastAddressJoin(      IxEthAccPortId portId,
1269                                              IxEthAccMacAddr *macAddr)
1270  *
1271  * @brief Add a multicast address to the MAC address table.
1272  *
1273  *  @note
1274  *  Due to the operation of the Ethernet MAC multicast filtering mechanism, frames which do not
1275  *  have a multicast destination address which were provisioned via this API may be forwarded
1276  *  to the NPE's. This is a result of the hardware comparison  algorithm used in the destination mac address logic
1277  *  within the Ethernet MAC.
1278  *
1279  *  See Also: IXP425 hardware development manual.
1280  *
1281  * Other functions modify the MAC filtering
1282  *
1283  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1284  *     frames are forwarded to the application
1285  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1286  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1287  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1288  *     filtering address
1289  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1290  *     filtering address
1291  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1292  *     forwarded to the application regardless of the multicast
1293  *     address provisioned
1294  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1295  *     to the application following the multicast address provisioned
1296  *
1297  * In all cases, unicast and broadcast addresses are forwarded to
1298  * the application.
1299  *
1300  * @li Reentrant    - yes
1301  * @li ISR Callable - no
1302  *
1303  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1304  * @param *macAddr @ref IxEthAccMacAddr [in] - Ethernet Mac address.
1305  *
1306  * @return IxEthAccStatus
1307  * @li @a IX_ETH_ACC_SUCCESS
1308  * @li @a IX_ETH_ACC_FAIL : Error writing to the MAC registers
1309  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1310  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1311  *
1312  * <hr>
1313  */
1314 PUBLIC IxEthAccStatus
1315 ixEthAccPortMulticastAddressJoin(IxEthAccPortId portId,
1316                                                                  IxEthAccMacAddr *macAddr);
1317
1318 /**
1319  * @ingroup IxEthAcc
1320  *
1321  * @fn ixEthAccPortMulticastAddressJoinAll(  IxEthAccPortId portId)
1322  *
1323  * @brief Filter all frames with multicast dest.
1324  *
1325  * This function clears the MAC address table, and then sets
1326  * the MAC to forward ALL multicast frames to the NPE.
1327  * Specifically, it forwards all frames whose destination address
1328  * has the LSB of the highest byte set  (01:00:00:00:00:00).  This
1329  * bit is commonly referred to as the "multicast bit".
1330  * Broadcast frames will still be forwarded.
1331  *
1332  * Other functions modify the MAC filtering
1333  *
1334  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1335  *     frames are forwarded to the application
1336  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1337  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1338  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1339  *     filtering address
1340  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1341  *     filtering address
1342  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1343  *     forwarded to the application regardless of the multicast
1344  *     address provisioned
1345  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1346  *     to the application following the multicast address provisioned
1347  *
1348  * In all cases, unicast and broadcast addresses are forwarded to
1349  * the application.
1350  *
1351  * @li Reentrant    - yes
1352  * @li ISR Callable - no
1353  *
1354  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1355  *
1356  * @return IxEthAccStatus
1357  * @li @a IX_ETH_ACC_SUCCESS
1358  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1359  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1360  *
1361  * <hr>
1362  */
1363 PUBLIC IxEthAccStatus
1364 ixEthAccPortMulticastAddressJoinAll(IxEthAccPortId portId);
1365
1366 /**
1367  * @ingroup IxEthAcc
1368  *
1369  * @fn ixEthAccPortMulticastAddressLeave( IxEthAccPortId portId,
1370                                          IxEthAccMacAddr *macAddr)
1371  *
1372  * @brief Remove a multicast address from the MAC address table.
1373  *
1374  * Other functions modify the MAC filtering
1375  *
1376  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1377  *     frames are forwarded to the application
1378  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1379  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1380  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1381  *     filtering address
1382  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1383  *     filtering address
1384  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1385  *     forwarded to the application regardless of the multicast
1386  *     address provisioned
1387  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1388  *     to the application following the multicast address provisioned
1389  *
1390  * In all cases, unicast and broadcast addresses are forwarded to
1391  * the application.
1392  *
1393  * @li Reentrant    - yes
1394  * @li ISR Callable - no
1395  *
1396  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1397  * @param *macAddr @ref IxEthAccMacAddr [in] - Ethernet Mac address.
1398  *
1399  * @return IxEthAccStatus
1400  * @li @a IX_ETH_ACC_SUCCESS
1401  * @li @a IX_ETH_ACC_NO_SUCH_ADDR :  Failed if MAC address was not in the table.
1402  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1403  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1404  *
1405  * <hr>
1406  */
1407 PUBLIC IxEthAccStatus
1408 ixEthAccPortMulticastAddressLeave(IxEthAccPortId portId,
1409                                                                   IxEthAccMacAddr *macAddr);
1410
1411 /**
1412  * @ingroup IxEthAcc
1413  *
1414  * @fn ixEthAccPortMulticastAddressLeaveAll( IxEthAccPortId portId)
1415  *
1416  * @brief This function unconfigures the multicast filtering settings
1417  *
1418  * This function first clears the MAC address table, and then sets
1419  * the MAC as configured by the promiscuous mode current settings.
1420  *
1421  * Other functions modify the MAC filtering
1422  *
1423  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1424  *     frames are forwarded to the application
1425  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1426  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1427  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1428  *     filtering address
1429  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1430  *     filtering address
1431  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1432  *     forwarded to the application regardless of the multicast
1433  *     address provisioned
1434  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1435  *     to the application following the multicast address provisioned
1436  *
1437  * In all cases, unicast and broadcast addresses are forwarded to
1438  * the application.
1439  *
1440  * @li Reentrant    - yes
1441  * @li ISR Callable - no
1442  *
1443  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1444  *
1445  * @return IxEthAccStatus
1446  * @li @a IX_ETH_ACC_SUCCESS
1447  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1448  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1449  *
1450  * <hr>
1451  */
1452 PUBLIC IxEthAccStatus
1453 ixEthAccPortMulticastAddressLeaveAll(IxEthAccPortId portId);
1454
1455 /**
1456  * @ingroup IxEthAcc
1457  *
1458  * @fn ixEthAccPortUnicastAddressShow(IxEthAccPortId portId)
1459  *
1460  * @brief Displays unicast MAC address
1461  *
1462  * Displays unicast address which is configured using
1463  * @a ixEthAccUnicastMacAddressSet. This function also displays the MAC filter used
1464  * to filter multicast frames.
1465  *
1466  * Other functions modify the MAC filtering
1467  *
1468  * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
1469  *     frames are forwarded to the application
1470  * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
1471  *     effects of @a ixEthAccPortMulticastAddressJoinAll()
1472  * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new
1473  *     filtering address
1474  * @li @a ixEthAccPortMulticastAddressJoin() - provision a new
1475  *     filtering address
1476  * @li @a ixEthAccPortPromiscuousModeSet() - all frames are
1477  *     forwarded to the application regardless of the multicast
1478  *     address provisioned
1479  * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded
1480  *     to the application following the multicast address provisioned
1481  *
1482  * In all cases, unicast and broadcast addresses are forwarded to
1483  * the application.
1484  *
1485  * @li Reentrant    - yes
1486  * @li ISR Callable - no
1487  *
1488  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1489  *
1490  * @return void
1491  *
1492  * <hr>
1493  */
1494 PUBLIC IxEthAccStatus ixEthAccPortUnicastAddressShow(IxEthAccPortId portId);
1495
1496
1497 /**
1498  * @ingroup IxEthAcc
1499  *
1500  * @fn ixEthAccPortMulticastAddressShow( IxEthAccPortId portId)
1501  *
1502  * @brief Displays multicast MAC address
1503  *
1504  * Displays multicast address which have been configured using @a ixEthAccMulticastAddressJoin
1505  *
1506  * @li Reentrant    - yes
1507  * @li ISR Callable - no
1508  *
1509  * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
1510  *
1511  * @return void
1512  *
1513  * <hr>
1514  */
1515 PUBLIC void ixEthAccPortMulticastAddressShow( IxEthAccPortId portId);
1516
1517 /**
1518  * @ingroup IxEthAcc
1519  *
1520  * @fn ixEthAccPortDuplexModeSet( IxEthAccPortId portId, IxEthAccDuplexMode mode )
1521  *
1522  * @brief  Set the duplex mode for the MAC.
1523  *
1524  * Configure the IXP400 MAC to either full or half duplex.
1525  *
1526  * @note
1527  * The configuration should match that provisioned on the PHY.
1528  *
1529  * @li Reentrant    - yes
1530  * @li ISR Callable - no
1531  *
1532  * @param portId @ref IxEthAccPortId [in]
1533  * @param mode @ref IxEthAccDuplexMode [in]
1534  *
1535  * @return IxEthAccStatus
1536  * @li @a IX_ETH_ACC_SUCCESS
1537  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1538  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1539  *
1540  * <hr>
1541  */
1542 PUBLIC IxEthAccStatus
1543 ixEthAccPortDuplexModeSet(IxEthAccPortId portId,IxEthAccDuplexMode mode);
1544
1545 /**
1546  * @ingroup IxEthAcc
1547  *
1548  * @fn ixEthAccPortDuplexModeGet( IxEthAccPortId portId, IxEthAccDuplexMode *mode )
1549  *
1550  * @brief  Get the duplex mode for the MAC.
1551  *
1552  * return the duplex configuration of the IXP400 MAC.
1553  *
1554  * @note
1555  * The configuration should match that provisioned on the PHY.
1556  * See @a ixEthAccDuplexModeSet
1557  *
1558  * @li Reentrant    - yes
1559  * @li ISR Callable - no
1560  *
1561  * @param portId @ref IxEthAccPortId [in]
1562  * @param *mode @ref IxEthAccDuplexMode [out]
1563  *
1564  * @return IxEthAccStatus
1565  * @li @a IX_ETH_ACC_SUCCESS
1566  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1567  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1568  *
1569  * <hr>
1570  *
1571  */
1572 PUBLIC IxEthAccStatus
1573 ixEthAccPortDuplexModeGet(IxEthAccPortId portId,IxEthAccDuplexMode *mode );
1574
1575 /**
1576  * @ingroup IxEthAcc
1577  *
1578  * @fn ixEthAccPortTxFrameAppendPaddingEnable( IxEthAccPortId portId)
1579  *
1580  * @brief  Enable padding bytes to be appended to runt frames submitted to
1581  * this port
1582  *
1583  * Enable up to 60 null-bytes padding bytes to be appended to runt frames
1584  * submitted to this port. This is the default behavior of the access
1585  * component.
1586  *
1587  * @warning Do not change this behaviour while the port is enabled.
1588  *
1589  * @note When Tx padding is enabled, Tx FCS generation is turned on
1590  *
1591  * @li Reentrant    - yes
1592  * @li ISR Callable - no
1593  *
1594  * @sa ixEthAccPortTxFrameAppendFCSDusable
1595  *
1596  * @param portId @ref IxEthAccPortId [in]
1597  *
1598  * @return IxEthAccStatus
1599  * @li @a IX_ETH_ACC_SUCCESS
1600  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1601  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1602  *
1603  * <hr>
1604  */
1605 PUBLIC IxEthAccStatus
1606 ixEthAccPortTxFrameAppendPaddingEnable(IxEthAccPortId portId);
1607
1608 /**
1609  * @ingroup IxEthAcc
1610  *
1611  * @fn ixEthAccPortTxFrameAppendPaddingDisable( IxEthAccPortId portId)
1612  *
1613  * @brief  Disable padding bytes to be appended to runt frames submitted to
1614  * this port
1615  *
1616  * Disable padding bytes to be appended to runt frames
1617  * submitted to this port. This is not the default behavior of the access
1618  * component.
1619  *
1620  * @warning Do not change this behaviour while the port is enabled.
1621  *
1622  * @li Reentrant    - yes
1623  * @li ISR Callable - no
1624  *
1625  * @param portId @ref IxEthAccPortId [in]
1626  *
1627  * @return IxEthAccStatus
1628  * @li @a IX_ETH_ACC_SUCCESS
1629  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1630  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1631  *
1632  * <hr>
1633  */
1634 PUBLIC IxEthAccStatus
1635 ixEthAccPortTxFrameAppendPaddingDisable(IxEthAccPortId portId);
1636
1637 /**
1638  * @ingroup IxEthAcc
1639  *
1640  * @fn ixEthAccPortTxFrameAppendFCSEnable( IxEthAccPortId portId)
1641  *
1642  * @brief  Enable the appending of Ethernet FCS to all frames submitted to this port
1643  *
1644  * When enabled, the FCS is added to the submitted frames. This is the default
1645  * behavior of the access component.
1646  * Do not change this behaviour while the port is enabled.
1647  *
1648  * @li Reentrant    - yes
1649  * @li ISR Callable - no
1650  *
1651  * @param portId @ref IxEthAccPortId [in]
1652  *
1653  * @return IxEthAccStatus
1654  * @li @a IX_ETH_ACC_SUCCESS
1655  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1656  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1657  *
1658  * <hr>
1659  */
1660 PUBLIC IxEthAccStatus
1661 ixEthAccPortTxFrameAppendFCSEnable(IxEthAccPortId portId);
1662
1663 /**
1664  * @ingroup IxEthAcc
1665  *
1666  * @fn ixEthAccPortTxFrameAppendFCSDisable( IxEthAccPortId portId)
1667  *
1668  * @brief  Disable the appending of Ethernet FCS to all frames submitted to this port.
1669  *
1670  * When disabled, the Ethernet FCS is not added to the submitted frames.
1671  * This is not the default
1672  * behavior of the access component.
1673  *
1674  * @note Since the FCS is not appended to the frame it is expected that the frame submitted to the
1675  * component includes a valid FCS at the end of the data, although this will not be validated.
1676  *
1677  * The component shall forward the frame to the Ethernet MAC WITHOUT modification.
1678  *
1679  * Do not change this behaviour while the port is enabled.
1680  *
1681  * @note Tx FCS append is not disabled while Tx padding is enabled.
1682  *
1683  * @li Reentrant    - yes
1684  * @li ISR Callable - no
1685  *
1686  * @sa ixEthAccPortTxFrameAppendPaddingEnable
1687  *
1688  * @param portId @ref IxEthAccPortId [in]
1689  *
1690  * @return IxEthAccStatus
1691  * @li @a IX_ETH_ACC_SUCCESS
1692  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1693  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1694  *
1695  * <hr>
1696  */
1697 PUBLIC IxEthAccStatus
1698 ixEthAccPortTxFrameAppendFCSDisable(IxEthAccPortId portId);
1699
1700 /**
1701  * @ingroup IxEthAcc
1702  *
1703  * @fn ixEthAccPortRxFrameAppendFCSEnable( IxEthAccPortId portId)
1704  *
1705  * @brief Forward frames with FCS included in the receive buffer.
1706  *
1707  * The FCS is not striped from the receive buffer.
1708  * The received frame length includes the FCS size (4 bytes). ie.
1709  * A minimum sized ethernet frame shall have a length of 64bytes.
1710  *
1711  * Frame FCS validity checks are still carried out on all received frames.
1712  *
1713  * This is not the default
1714  * behavior of the access component.
1715  *
1716  * @li Reentrant    - yes
1717  * @li ISR Callable - no
1718  *
1719  * @param portId @ref IxEthAccPortId [in]
1720  *
1721  * @return IxEthAccStatus
1722  * @li @a IX_ETH_ACC_SUCCESS
1723  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1724  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1725  *
1726  * <hr>
1727  */
1728 PUBLIC IxEthAccStatus
1729 ixEthAccPortRxFrameAppendFCSEnable(IxEthAccPortId portId);
1730
1731 /**
1732  * @ingroup IxEthAcc
1733  *
1734  * @fn ixEthAccPortRxFrameAppendFCSDisable( IxEthAccPortId portId)
1735  *
1736  * @brief  Do not forward the FCS portion of the received Ethernet frame to the user.
1737  * The FCS is striped from the receive buffer.
1738  * The received frame length does not include the FCS size (4 bytes).
1739  * Frame FCS validity checks are still carried out on all received frames.
1740  *
1741  * This is the default behavior of the component.
1742  * Do not change this behaviour while the port is enabled.
1743  *
1744  * @li Reentrant    - yes
1745  * @li ISR Callable - no
1746  *
1747  * @param portId @ref IxEthAccPortId [in]
1748  *
1749  * @return IxEthAccStatus
1750  * @li @a IX_ETH_ACC_SUCCESS
1751  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1752  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1753  *
1754  * <hr>
1755  */
1756 PUBLIC IxEthAccStatus
1757 ixEthAccPortRxFrameAppendFCSDisable(IxEthAccPortId portId);
1758
1759
1760
1761
1762 /**
1763  * @ingroup IxEthAcc
1764  *
1765  * @enum IxEthAccSchedulerDiscipline
1766  *
1767  * @brief  Definition for the port scheduling discipline
1768  *
1769  * Select the port scheduling discipline on receive and transmit path
1770  * @li FIFO : No Priority : In this configuration all frames are processed
1771  *                       in the access component in the strict order in which
1772  *                        the component received them.
1773  * @li FIFO : Priority : This shall be a very simple priority mechanism.
1774  *                     Higher prior-ity frames shall be forwarded
1775  *                     before lower priority frames. There shall be no
1776  *                     fairness mechanisms applied across different
1777  *                     priorities. Higher priority frames could starve
1778  *                     lower priority frames indefinitely.
1779  */
1780 typedef  enum
1781 {
1782     FIFO_NO_PRIORITY, /**<frames submitted with no priority*/
1783     FIFO_PRIORITY /**<higher prority frames submitted before lower priority*/
1784 }IxEthAccSchedulerDiscipline;
1785
1786 /**
1787  * @ingroup IxEthAcc
1788  *
1789  * @def IxEthAccTxSchedulerDiscipline
1790  *
1791  * @brief  Deprecated definition for the port transmit scheduling discipline
1792  */
1793 #define IxEthAccTxSchedulerDiscipline IxEthAccSchedulerDiscipline
1794
1795
1796
1797 /**
1798  * @ingroup IxEthAcc
1799  *
1800  * @fn ixEthAccTxSchedulingDisciplineSet( IxEthAccPortId portId, IxEthAccSchedulerDiscipline sched)
1801  *
1802  * @brief Set the port scheduling to one of @a IxEthAccSchedulerDiscipline
1803  *
1804  * The default behavior of the component is @a FIFO_NO_PRIORITY.
1805  *
1806  * @li Reentrant    - yes
1807  * @li ISR Callable - no
1808  *
1809  * @pre
1810  *
1811  *
1812  * @param portId @ref IxEthAccPortId [in]
1813  * @param sched @ref IxEthAccSchedulerDiscipline [in]
1814  *
1815  * @return IxEthAccStatus
1816  * @li @a IX_ETH_ACC_SUCCESS : Set appropriate discipline.
1817  * @li @a IX_ETH_ACC_FAIL :  Invalid/unsupported discipline.
1818  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
1819  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
1820  *
1821  * <hr>
1822  */
1823 PUBLIC IxEthAccStatus
1824 ixEthAccTxSchedulingDisciplineSet(IxEthAccPortId portId,
1825                                                                   IxEthAccSchedulerDiscipline sched);
1826
1827
1828 /**
1829  * @ingroup IxEthAcc
1830  *
1831  * @fn ixEthAccRxSchedulingDisciplineSet(IxEthAccSchedulerDiscipline sched)
1832  *
1833  * @brief Set the Rx scheduling to one of @a IxEthAccSchedulerDiscipline
1834  *
1835  * The default behavior of the component is @a FIFO_NO_PRIORITY.
1836  *
1837  * @li Reentrant    - yes
1838  * @li ISR Callable - no
1839  *
1840  * @pre
1841  *
1842  * @param sched : @a IxEthAccSchedulerDiscipline
1843  *
1844  * @return IxEthAccStatus
1845  * @li @a IX_ETH_ACC_SUCCESS : Set appropriate discipline.
1846  * @li @a IX_ETH_ACC_FAIL :  Invalid/unsupported discipline.
1847  *
1848  * <hr>
1849  */
1850 PUBLIC IxEthAccStatus
1851 ixEthAccRxSchedulingDisciplineSet(IxEthAccSchedulerDiscipline sched);
1852
1853 /**
1854  * @ingroup IxEthAcc
1855  *
1856  * @fn IxEthAccStatus ixEthAccNpeLoopbackEnable(IxEthAccPortId portId)
1857  *
1858  * @brief Enable NPE loopback
1859  *
1860  * When this loopback mode is enabled all the transmitted frames are
1861  * received on the same port, without payload.
1862  *
1863  * This function is recommended for power-up diagnostic checks and
1864  * should never be used under normal Ethernet traffic operations.
1865  *
1866  * @li Reentrant    - yes
1867  * @li ISR Callable - no
1868  *
1869  * @pre
1870  *
1871  * @param portId : ID of the port
1872  *
1873  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
1874  * guaranteed to restore correct Ethernet Tx/Rx operation.
1875  *
1876  * @return IxEthAccStatus
1877  * @li @a IX_ETH_ACC_SUCCESS : NPE loopback mode enabled
1878  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
1879  *
1880  * <hr>
1881  */
1882 PUBLIC IxEthAccStatus
1883 ixEthAccPortNpeLoopbackEnable(IxEthAccPortId portId);
1884
1885 /**
1886  * @ingroup IxEthAcc
1887  *
1888  * @fn IxEthAccStatus ixEthAccPortNpeLoopbackDisable(IxEthAccPortId portId)
1889  *
1890  * @brief Disable NPE loopback
1891  *
1892  * This function is used to disable the NPE loopback if previously
1893  * enabled using ixEthAccNpeLoopbackEnable.
1894  *
1895  * This function is recommended for power-up diagnostic checks and
1896  * should never be used under normal Ethernet traffic operations.
1897  *
1898  * @li Reentrant    - yes
1899  * @li ISR Callable - no
1900  *
1901  * @pre
1902  *
1903  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
1904  * guaranteed to restore correct Ethernet Tx/Rx operation.
1905  *
1906  * @param portId : ID of the port
1907  *
1908  * @return IxEthAccStatus
1909  * @li @a IX_ETH_ACC_SUCCESS : NPE loopback successfully disabled
1910  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
1911  *
1912  * <hr>
1913  */
1914 PUBLIC IxEthAccStatus
1915 ixEthAccPortNpeLoopbackDisable(IxEthAccPortId portId);
1916
1917 /**
1918  * @ingroup IxEthAcc
1919  *
1920  * @fn IxEthAccStatus ixEthAccPortTxEnable(IxEthAccPortId portId)
1921  *
1922  * @brief Enable Tx on the port
1923  *
1924  * This function is the complement of ixEthAccPortTxDisable and should
1925  * be used only after Tx was disabled. A MAC core reset is required before
1926  * this function is called (see @a ixEthAccPortMacReset).
1927  *
1928  * This function is the recommended usage scenario for emergency security
1929  * shutdown and hardware failure recovery and should never be used for throttling
1930  * traffic.
1931  *
1932  * @li Reentrant    - yes
1933  * @li ISR Callable - no
1934  *
1935  * @pre
1936  *
1937  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
1938  * guaranteed to restore correct Ethernet Tx/Rx operation.
1939  *
1940  * @param portId : ID of the port
1941  *
1942  * @return IxEthAccStatus
1943  * @li @a IX_ETH_ACC_SUCCESS : Tx successfully enabled
1944  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
1945  *
1946  * <hr>
1947  */
1948 PUBLIC IxEthAccStatus
1949 ixEthAccPortTxEnable(IxEthAccPortId portId);
1950
1951 /**
1952  * @ingroup IxEthAcc
1953  *
1954  * @fn IxEthAccStatus ixEthAccPortTxDisable(IxEthAccPortId portId)
1955  *
1956  * @brief Disable Tx on the port
1957  *
1958  * This function can be used to disable Tx in the MAC core.
1959  * Tx can be re-enabled, although this is not guaranteed, by performing
1960  * a MAC core reset (@a ixEthAccPortMacReset) and calling ixEthAccPortTxEnable.
1961  * Note that using this function is not recommended, except for shutting
1962  * down Tx for emergency reasons. For proper port shutdown and re-enabling
1963  * see ixEthAccPortEnable and ixEthAccPortDisable.
1964  *
1965  * This function is the recommended usage scenario for emergency security
1966  * shutdown and hardware failure recovery and should never be used for throttling
1967  * traffic.
1968  *
1969  * @li Reentrant    - yes
1970  * @li ISR Callable - no
1971  *
1972  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
1973  * guaranteed to restore correct Ethernet Tx/Rx operation.
1974  *
1975  * @pre
1976  *
1977  * @param portId : ID of the port
1978  *
1979  * @return IxEthAccStatus
1980  * @li @a IX_ETH_ACC_SUCCESS : Tx successfully disabled
1981  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
1982  *
1983  * <hr>
1984  */
1985 PUBLIC IxEthAccStatus
1986 ixEthAccPortTxDisable(IxEthAccPortId portId);
1987
1988 /**
1989  * @ingroup IxEthAcc
1990  *
1991  * @fn IxEthAccStatus ixEthAccPortRxEnable(IxEthAccPortId portId)
1992  *
1993  * @brief Enable Rx on the port
1994  *
1995  * This function is the complement of ixEthAccPortRxDisable and should
1996  * be used only after Rx was disabled.
1997  *
1998  * This function is the recommended usage scenario for emergency security
1999  * shutdown and hardware failure recovery and should never be used for throttling
2000  * traffic.
2001  *
2002  * @li Reentrant    - yes
2003  * @li ISR Callable - no
2004  *
2005  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
2006  * guaranteed to restore correct Ethernet Tx/Rx operation.
2007  *
2008  * @pre
2009  *
2010  * @param portId : ID of the port
2011  *
2012  * @return IxEthAccStatus
2013  * @li @a IX_ETH_ACC_SUCCESS : Rx successfully enabled
2014  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
2015  *
2016  * <hr>
2017  */
2018 PUBLIC IxEthAccStatus
2019 ixEthAccPortRxEnable(IxEthAccPortId portId);
2020
2021 /**
2022  * @ingroup IxEthAcc
2023  *
2024  * @fn IxEthAccStatus ixEthAccPortRxDisable(IxEthAccPortId portId)
2025  *
2026  * @brief Disable Rx on the port
2027  *
2028  * This function can be used to disable Rx in the MAC core.
2029  * Rx can be re-enabled, although this is not guaranteed, by performing
2030  * a MAC core reset (@a ixEthAccPortMacReset) and calling ixEthAccPortRxEnable.
2031  * Note that using this function is not recommended, except for shutting
2032  * down Rx for emergency reasons. For proper port shutdown and re-enabling
2033  * see ixEthAccPortEnable and ixEthAccPortDisable.
2034  *
2035  * This function is the recommended usage scenario for emergency security
2036  * shutdown and hardware failure recovery and should never be used for throttling
2037  * traffic.
2038  *
2039  * @li Reentrant    - yes
2040  * @li ISR Callable - no
2041  *
2042  * @pre
2043  *
2044  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
2045  * guaranteed to restore correct Ethernet Tx/Rx operation.
2046  *
2047  * @param portId : ID of the port
2048  *
2049  * @return IxEthAccStatus
2050  * @li @a IX_ETH_ACC_SUCCESS : Rx successfully disabled
2051  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
2052  *
2053  * <hr>
2054  */
2055 PUBLIC IxEthAccStatus
2056 ixEthAccPortRxDisable(IxEthAccPortId portId);
2057
2058 /**
2059  * @ingroup IxEthAcc
2060  *
2061  * @fn IxEthAccStatus ixEthAccPortMacReset(IxEthAccPortId portId)
2062  *
2063  * @brief Reset MAC core on the port
2064  *
2065  * This function will perform a MAC core reset (NPE Ethernet coprocessor).
2066  * This function is inherently unsafe and the NPE recovery is not guaranteed
2067  * after this function is called. The proper manner of performing port disable
2068  * and enable (which will reset the MAC as well) is ixEthAccPortEnable/ixEthAccPortDisable.
2069  *
2070  * This function is the recommended usage scenario for hardware failure recovery
2071  * and should never be used for throttling traffic.
2072  *
2073  * @li Reentrant    - yes
2074  * @li ISR Callable - no
2075  *
2076  * @pre
2077  *
2078  * @note Calling ixEthAccPortDisable followed by ixEthAccPortEnable is
2079  * guaranteed to restore correct Ethernet Tx/Rx operation.
2080  *
2081  * @param portId : ID of the port
2082  *
2083  * @return IxEthAccStatus
2084  * @li @a IX_ETH_ACC_SUCCESS : MAC core reset
2085  * @li @a IX_ETH_ACC_FAIL : Invalid port or Ethernet service not initialized
2086  *
2087  * <hr>
2088  */
2089 PUBLIC IxEthAccStatus
2090 ixEthAccPortMacReset(IxEthAccPortId portId);
2091
2092 /*********************************************************************************
2093   ####    #####    ##     #####     #     ####    #####     #     ####    ####
2094  #          #     #  #      #       #    #          #       #    #    #  #
2095   ####      #    #    #     #       #     ####      #       #    #        ####
2096       #     #    ######     #       #         #     #       #    #            #
2097  #    #     #    #    #     #       #    #    #     #       #    #    #  #    #
2098   ####      #    #    #     #       #     ####      #       #     ####    ####
2099 **********************************************************************************/
2100
2101
2102 /**
2103  *
2104  * @brief This struct defines the statistics returned by this component.
2105  *
2106  * The component returns MIB2 EthObj variables which are obtained from the
2107  * hardware or maintained by this component.
2108  *
2109  *
2110  */
2111 typedef struct
2112 {
2113     UINT32 dot3StatsAlignmentErrors;            /**< link error count (rx) */
2114     UINT32 dot3StatsFCSErrors;                  /**< link error count (rx) */
2115     UINT32 dot3StatsInternalMacReceiveErrors;   /**< link error count (rx) */
2116     UINT32 RxOverrunDiscards;                   /**< NPE: discarded frames count (rx) */
2117     UINT32 RxLearnedEntryDiscards;                /**< NPE: discarded frames count(rx)  */
2118     UINT32 RxLargeFramesDiscards;                 /**< NPE: discarded frames count(rx)  */
2119     UINT32 RxSTPBlockedDiscards;                  /**< NPE: discarded frames count(rx)  */
2120     UINT32 RxVLANTypeFilterDiscards;              /**< NPE: discarded frames count (rx) */
2121     UINT32 RxVLANIdFilterDiscards;                /**< NPE: discarded frames count (rx) */
2122     UINT32 RxInvalidSourceDiscards;               /**< NPE: discarded frames count (rx) */
2123     UINT32 RxBlackListDiscards;                   /**< NPE: discarded frames count (rx) */
2124     UINT32 RxWhiteListDiscards;                   /**< NPE: discarded frames count (rx) */
2125     UINT32 RxUnderflowEntryDiscards;              /**< NPE: discarded frames count (rx) */
2126     UINT32 dot3StatsSingleCollisionFrames;      /**< link error count (tx) */
2127     UINT32 dot3StatsMultipleCollisionFrames;    /**< link error count (tx) */
2128     UINT32 dot3StatsDeferredTransmissions;      /**< link error count (tx) */
2129     UINT32 dot3StatsLateCollisions;             /**< link error count (tx) */
2130     UINT32 dot3StatsExcessiveCollsions;         /**< link error count (tx) */
2131     UINT32 dot3StatsInternalMacTransmitErrors;  /**< link error count (tx) */
2132     UINT32 dot3StatsCarrierSenseErrors;         /**< link error count (tx) */
2133     UINT32 TxLargeFrameDiscards;                /**< NPE: discarded frames count (tx) */
2134     UINT32 TxVLANIdFilterDiscards;              /**< NPE: discarded frames count (tx) */
2135
2136 }IxEthEthObjStats;
2137
2138 /**
2139  * @ingroup IxEthAcc
2140  *
2141  * @fn ixEthAccMibIIStatsGet(IxEthAccPortId portId ,IxEthEthObjStats *retStats )
2142  *
2143  * @brief  Returns the statistics maintained for a port.
2144  *
2145  * @li Reentrant    - yes
2146  * @li ISR Callable - no
2147  *
2148  * @pre
2149  *
2150  *
2151  * @param portId @ref IxEthAccPortId [in]
2152  * @param retStats @ref IxEthEthObjStats [out]
2153  * @note Please note the user is responsible for cache coheriency of the retStat
2154  * buffer. The data is actually populated via the NPE's. As such cache safe
2155  * memory should be used in the retStats argument.
2156  *
2157  * @return IxEthAccStatus
2158  * @li @a IX_ETH_ACC_SUCCESS
2159  * @li @a IX_ETH_ACC_FAIL : Invalid arguments.
2160  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
2161  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
2162  *
2163  * <hr>
2164  */
2165 PUBLIC IxEthAccStatus
2166 ixEthAccMibIIStatsGet(IxEthAccPortId portId, IxEthEthObjStats *retStats );
2167
2168 /**
2169  * @ingroup IxEthAcc
2170  *
2171  * @fn ixEthAccMibIIStatsGetClear(IxEthAccPortId portId, IxEthEthObjStats *retStats)
2172  *
2173  * @brief  Returns and clears the statistics maintained for a port.
2174  *
2175  * @li Reentrant    - yes
2176  * @li ISR Callable - yes
2177  *
2178  * @pre
2179  *
2180  * @param portId @ref IxEthAccPortId [in]
2181  * @param retStats @ref IxEthEthObjStats [out]
2182  * @note Please note the user is responsible for cache coheriency of the retStats
2183  * buffer. The data is actually populated via the NPE's. As such cache safe
2184  * memory should be used in the retStats argument.
2185  *
2186  * @return IxEthAccStatus
2187  * @li @a IX_ETH_ACC_SUCCESS
2188  * @li @a IX_ETH_ACC_FAIL : invalid arguments.
2189  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
2190  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
2191  *
2192  * <hr>
2193  */
2194 PUBLIC IxEthAccStatus
2195 ixEthAccMibIIStatsGetClear(IxEthAccPortId portId, IxEthEthObjStats *retStats);
2196
2197 /**
2198  * @ingroup IxEthAcc
2199  *
2200  * @fn ixEthAccMibIIStatsClear(IxEthAccPortId portId)
2201  *
2202  * @brief   Clears the statistics maintained for a port.
2203  *
2204  * @li Reentrant    - yes
2205  * @li ISR Callable - no
2206  *
2207  * @pre
2208  *
2209  * @param portId @ref IxEthAccPortId [in]
2210  *
2211  * @return IxEthAccStatus
2212  * @li @a IX_ETH_ACC_SUCCESS
2213  * @li @a IX_ETH_ACC_FAIL : Invalid arguments.
2214  * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
2215  * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
2216  *
2217  * <hr>
2218  */
2219 PUBLIC IxEthAccStatus ixEthAccMibIIStatsClear(IxEthAccPortId portId);
2220
2221 /**
2222  * @ingroup IxEthAcc
2223  *
2224  * @fn ixEthAccMacInit(IxEthAccPortId portId)
2225  *
2226  * @brief Initializes the ethernet MAC settings
2227  *
2228  * @li Reentrant    - no
2229  * @li ISR Callable - no
2230  *
2231  * @param portId @ref IxEthAccPortId [in]
2232  *
2233  * @return IxEthAccStatus
2234  * @li @a IX_ETH_ACC_SUCCESS
2235  * @li @a IX_ETH_ACC_INVALID_PORT       :  portId is invalid.
2236  *
2237  * <hr>
2238  */
2239 PUBLIC IxEthAccStatus ixEthAccMacInit(IxEthAccPortId portId);
2240
2241 /**
2242  * @ingroup IxEthAcc
2243  *
2244  * @fn ixEthAccStatsShow(IxEthAccPortId portId)
2245  *
2246  *
2247  * @brief Displays a ports statistics on the standard io console using printf.
2248  *
2249  * @li Reentrant    - no
2250  * @li ISR Callable - no
2251  *
2252  * @pre
2253  *
2254  * @param portId @ref IxEthAccPortId [in]
2255  *
2256  * @return void
2257  *
2258  * <hr>
2259  */
2260 PUBLIC void ixEthAccStatsShow(IxEthAccPortId portId);
2261
2262 /*************************************************************************
2263
2264  #    #     #       #            #    #  #####      #     ####
2265  ##  ##     #       #            ##  ##  #    #     #    #    #
2266  # ## #     #       #            # ## #  #    #     #    #    #
2267  #    #     #       #            #    #  #    #     #    #    #
2268  #    #     #       #            #    #  #    #     #    #    #
2269  #    #     #       #            #    #  #####      #     ####
2270
2271 *************************************************************************/
2272
2273
2274 /**
2275  * @ingroup IxEthAcc
2276  *
2277  * @fn ixEthAccMiiReadRtn (UINT8 phyAddr,
2278                            UINT8 phyReg,
2279                            UINT16 *value)
2280  *
2281  *
2282  * @brief Reads a 16 bit value from a PHY
2283  *
2284  * Reads a 16-bit word from a register of a MII-compliant PHY. Reading
2285  * is performed through the MII management interface.  This function returns
2286  * when the read operation has successfully completed, or when a timeout has elapsed.
2287  *
2288  * @li Reentrant    - no
2289  * @li ISR Callable - no
2290  *
2291  * @pre The MAC on Ethernet Port 2 (NPE C) must be initialised, and generating the MDIO clock.
2292  *
2293  * @param phyAddr UINT8 [in] - the address of the Ethernet PHY (0-31)
2294  * @param phyReg UINT8 [in] -  the number of the MII register to read (0-31)
2295  * @param value UINT16 [in] -  the value read from the register
2296  *
2297  * @return IxEthAccStatus
2298  * @li @a IX_ETH_ACC_SUCCESS
2299  * @li @a IX_ETH_ACC_FAIL : failed to read the register.
2300  *
2301  * <hr>
2302  */
2303 PUBLIC IxEthAccStatus
2304 ixEthAccMiiReadRtn (UINT8 phyAddr, UINT8 phyReg, UINT16 *value);
2305
2306 /**
2307  * @ingroup IxEthAcc
2308  *
2309  * @fn ixEthAccMiiWriteRtn (UINT8 phyAddr,
2310                             UINT8 phyReg,
2311                             UINT16 value)
2312  *
2313  *
2314  * @brief Writes a 16 bit value to a PHY
2315  *
2316  * Writes a 16-bit word from a register of a MII-compliant PHY. Writing
2317  * is performed through the MII management interface.  This function returns
2318  * when the write operation has successfully completed, or when a timeout has elapsed.
2319  *
2320  * @li Reentrant    - no
2321  * @li ISR Callable - no
2322  *
2323  * @pre The MAC on Ethernet Port 2 (NPE C) must be initialised, and generating the MDIO clock.
2324  *
2325  * @param phyAddr UINT8 [in] - the address of the Ethernet PHY (0-31)
2326  * @param phyReg UINT8 [in] -  the number of the MII register to write (0-31)
2327  * @param value UINT16 [out] -  the value to write to the register
2328  *
2329  * @return IxEthAccStatus
2330  * @li @a IX_ETH_ACC_SUCCESS
2331  * @li @a IX_ETH_ACC_FAIL : failed to write register.
2332  *
2333  * <hr>
2334  */
2335 PUBLIC IxEthAccStatus
2336 ixEthAccMiiWriteRtn (UINT8 phyAddr, UINT8 phyReg, UINT16 value);
2337
2338 /**
2339  * @ingroup IxEthAcc
2340  *
2341  * @fn ixEthAccMiiAccessTimeoutSet(UINT32 timeout)
2342  *
2343  * @brief Overrides the default timeout value and retry count when reading or
2344  * writing MII registers using ixEthAccMiiWriteRtn or ixEthAccMiiReadRtn
2345  *
2346  * The default behavior of the component is to use a IX_ETH_ACC_MII_10TH_SEC_IN_MILLIS ms
2347  * timeout (declared as 100 in IxEthAccMii_p.h) and a retry count of IX_ETH_ACC_MII_TIMEOUT_10TH_SECS
2348  * (declared as 5 in IxEthAccMii_p.h).
2349  *
2350  * The MII read and write functions will attempt to read the status of the register up
2351  * to the retry count times, delaying between each attempt with the timeout value.
2352  *
2353  * @li Reentrant    - no
2354  * @li ISR Callable - no
2355  *
2356  * @pre
2357  *
2358  * @param timeout UINT32 [in] - new timeout value, in milliseconds
2359  * @param timeout UINT32 [in] - new retry count (a minimum value of 1 must be used)
2360  *
2361  * @return IxEthAccStatus
2362  * @li @a IX_ETH_ACC_SUCCESS
2363  * @li @a IX_ETH_ACC_FAIL : invalid parameter(s)
2364  *
2365  * <hr>
2366  */
2367 PUBLIC IxEthAccStatus
2368 ixEthAccMiiAccessTimeoutSet(UINT32 timeout, UINT32 retryCount);
2369
2370 /**
2371  * @ingroup IxEthAcc
2372  *
2373  * @fn ixEthAccMiiStatsShow (UINT32 phyAddr)
2374  *
2375  *
2376  * @brief Displays detailed information on a specified PHY
2377  *
2378  * Displays the current values of the first eigth MII registers for a PHY,
2379  *
2380  * @li Reentrant    - no
2381  * @li ISR Callable - no
2382  *
2383  * @pre The MAC on Ethernet Port 2 (NPE C) must be initialised, and
2384  *      generating the MDIO clock.
2385  *
2386  * @param phyAddr UINT32 [in] - the address of the Ethernet PHY (0-31)
2387  *
2388  * @return IxEthAccStatus
2389  * @li @a IX_ETH_ACC_SUCCESS
2390  * @li @a IX_ETH_ACC_FAIL : invalid arguments.
2391  *
2392  * <hr>
2393  */
2394 PUBLIC IxEthAccStatus ixEthAccMiiStatsShow (UINT32 phyAddr);
2395
2396
2397
2398 /******* BOARD SPECIFIC DEPRECATED API *********/
2399
2400 /* The following functions are high level functions which rely
2401  * on the properties and interface of some Ethernet PHYs. The
2402  * implementation is hardware specific and has been moved to
2403  * the hardware-specific component IxEthMii.
2404  */
2405
2406  #include "IxEthMii.h"
2407
2408 /**
2409  * @ingroup IxEthAcc
2410  *
2411  * @def  ixEthAccMiiPhyScan
2412  *
2413  * @brief : deprecated API entry point. This definition
2414  * ensures backward compatibility
2415  *
2416  * See @ref ixEthMiiPhyScan
2417  *
2418  * @note this feature is board specific
2419  *
2420  */
2421 #define ixEthAccMiiPhyScan(phyPresent) ixEthMiiPhyScan(phyPresent,IXP425_ETH_ACC_MII_MAX_ADDR)
2422
2423 /**
2424  * @ingroup IxEthAcc
2425  *
2426  * @def ixEthAccMiiPhyConfig
2427  *
2428  * @brief : deprecated API entry point. This definition
2429  * ensures backward compatibility
2430  *
2431  * See @ref ixEthMiiPhyConfig
2432  *
2433  * @note this feature is board specific
2434  */
2435 #define ixEthAccMiiPhyConfig(phyAddr,speed100,fullDuplex,autonegotiate) \
2436            ixEthMiiPhyConfig(phyAddr,speed100,fullDuplex,autonegotiate)
2437
2438 /**
2439  * @ingroup IxEthAcc
2440  *
2441  * @def ixEthAccMiiPhyReset
2442  *
2443  * @brief : deprecated API entry point. This definition
2444  * ensures backward compatibility
2445  *
2446  * See @ref ixEthMiiPhyReset
2447  *
2448  * @note this feature is board specific
2449  */
2450 #define ixEthAccMiiPhyReset(phyAddr) \
2451            ixEthMiiPhyReset(phyAddr)
2452
2453 /**
2454  * @ingroup IxEthAcc
2455  *
2456  * @def ixEthAccMiiLinkStatus
2457  *
2458  * @brief : deprecated API entry point. This definition
2459  * ensures backward compatibility
2460  *
2461  * See @ref ixEthMiiLinkStatus
2462  *
2463  * @note this feature is board specific
2464  */
2465 #define ixEthAccMiiLinkStatus(phyAddr,linkUp,speed100,fullDuplex,autoneg) \
2466            ixEthMiiLinkStatus(phyAddr,linkUp,speed100,fullDuplex,autoneg)
2467
2468
2469
2470 /**
2471  * @ingroup IxEthAcc
2472  *
2473  * @def ixEthAccMiiShow
2474  *
2475  * @brief : deprecated API entry point. This definition
2476  * ensures backward compatibility
2477  *
2478  * See @ref ixEthMiiPhyShow
2479  *
2480  * @note this feature is board specific
2481  */
2482 #define ixEthAccMiiShow(phyAddr) \
2483         ixEthMiiPhyShow(phyAddr)
2484
2485 #endif /* ndef IxEthAcc_H */
2486 /**
2487  *@}
2488  */