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