ixethaal5app.h

intel IXP400系列cpu（2.3版）的库文件

/**
 * @file IxEthAal5App.h
 *
 * @author Intel Corporation
 * @date 3 Apr 2002
 *
 * @brief This file contains the declaration of the IxEthAal5App
 * component's main functions, etc.
 *
 * 
 * @par
 * IXP400 SW Release version 2.3
 * 
 * -- Copyright Notice --
 * 
 * @par
 * Copyright (c) 2001-2005, Intel Corporation.
 * All rights reserved.
 * 
 * @par
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * 
 * @par
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * 
 * @par
 * -- End of Copyright Notice --
*/
#ifndef IXETHAAL5APP_H
#define IXETHAAL5APP_H

/**
 * @defgroup Codelets Intel (R) IXP400 Software Codelets
 *
 * @brief Intel (R) IXP400 Software Codelets
 *
 * @{
 */

/**
 * @ingroup Codelets
 *
 * @defgroup IxEthAal5App Intel (R) IXP400 Software Ethenet Aal5 (IxEthAal5App) API 
 *
 * @brief Intel (R) IXP400 Software Ethernet Aal5 Codelet component API
 * 
 * @par
 * IxEthAal5App application is also called as IXP4XX Mini Bridge application
 * which  bridges traffic between Ethernet and Utopia ports or Ethernet
 * and ADSL ports. It uses ixEthAcc,ixAtmdAcc, ixAtmm, ixAtmSch and ixQmgr
 * software components.
 *
 * <b> VxWorks User Guide </b><br>
 * ixEthAal5AppCodeletMain() function is used as a single point of execution
 * for EthAal5 Codelet, which allows the user to enter in 2 type of modes:
 * Utopia or ADSL, in order to operate together with ethernet.
 *
 * <pre>
 *  <i> Usage :
 *      ixEthAal5AppCodeletMain (modeType)
 *	  modeType:
 *                  1 = Utopia
 *                  2 = ADSL
 * </i>
 * </pre>
 *
 * <b> Linux* User Guide </b><br>
 * ixEthAal5AppCodeletMain() function is used as a single point of execution 
 * for EthAal5 Codelet, which allows the user to enter in 2 type of modes:
 * Utopia or ADSL, in order to operate together with ethernet.
 *
 * <pre>
 *  <i> Usage :
 *      # insmod ixp400_codelets_ethAal5App.o modeType=<x>
 *      Where x:
 *                  1 = Utopia
 *                  2 = ADSL
 * </i>
 * </pre>
 *
 * Note for VxWorks* and Linux* Usage:
 * In order to observe the current traffic counters, the ixEAAShow() function
 * is executed every 15seconds. This applys to both Utopia and ADSL mode.
 *
 *
 * @par
 * <B>Features</B><br>
 * This codelet currently supports 2 Ethernet ports and up to 8VCs per 8 
 * Utopia phys (MPHY mode) or up to 8VCs per Utopia phy (SPHY mode), which will
 * be initialized at the start of application. In SPHY mode, the codelet sets
 * up 1 VC per UTOPIA phy by default. The codelet is also capable to configure
 * up to 32VCs (see "How to Setup 32VCs" section)
 * 
 * Ethernet frames are transferred across ATM link (through Utopia interface) 
 * using AAL5 protocol and Ethernet frame encapsulation described by RFC 1483. 
 * MAC address learning is performed on Ethernet frames, received by Ethernet 
 * ports and ATM interface (encapsulated). Application filters packets base 
 * on destination MAC addresses - packets are forwarded to other port only if 
 * the port has ever received packet/frame with the same source MAC address. 
 * Forwarding is done only between Ethernet and Utopia port. 
 * 
 * Several simplifications were made to keep code simple: 
 *  - Application doesn't allow packet forwarding between Ethernet ports (nor 
 *    Utopia ports).
 *  - flooding (forwarding frames/packets with unknown MAC addresses) is
 *    not supported. Two IxEthAal5App will never transfer any packets between 
 *    each other, because initialy MAC data base is empty, so all packets will
 *    be filtered out. However there is function ixEAAAddMAC which can be used
 *    to add MAC address to the data base and assign it to one of available 
 *    ports. To enable simplified flooding see comments in ixEAAEthRxCallback.
 *  - This application can not be executed more than once. It doesn't 
 *    deinitialize itself. If user wishes to change configuration and run 
 *    application again the whole system (vxWorks*) must be restarted.
 *  - currently Mac Learning/Filtering database in ixEthAcc component supports
 *    only Ethernet ports. For that reason it couldn't be used in this 
 *    application for learning Mac addresses from encapsulated Ethernet frames
 *    received from Utopia. In the near future ixEthAcc component will support
 *    all possible ports (including Utopia), but by this time a very simplified
 *    approach is used in this application: 
 *       only one Mac address is stored per VC (and there is one VC per Phy). 
 *       It means, that only one Mac address is supported simultaneously per
 *       Phy. This is done to keep code as simple as possible.
 *  - This application provides two choices of connection: DSL or UTOPIA. 
 *    DSL will be established (modeType = 2) if the DSL card is attached to the 
 *    IXDP4XX board
 *  - 2 protocols from RFC 1483 are recognized: The first packet received from 
 *    ATM will decide the behaviour of the application (ether bridged or 
 *    routed)
 *
 * @par
 * <B>How to Setup 32VC</B><br>
 * In order to setup 32VCs there are several steps involved:
 *    1) Change the IX_EAA_NUM_ATM_VCS to 32
 *    2) In ixEAASetupVc function, 
 *           - Change the configuration of each VC, i.e. which VC setup what
 *             what type of QoS and its parameters
 *           - Add more VPI and VCI values to the atmVpi and atmVci variables
 *             respectively
 *
 * @par
 * <B>From RFC 1483</B><br>
 *  VC Based Multiplexing of Routed Protocols
 *
 *  PDUs of routed protocols shall be carried as such in the Payload of
 *  the AAL5 CPCS-PDU.  The format of the AAL5 CPCS-PDU Payload field
 *  thus becomes:
 *
 * @verbatim
               Payload Format for Routed PDUs
               +-------------------------------+
               |             .                 |
               |         Carried PDU           |
               |    (up to 2^16 - 1 octets)    |
               |             .                 |
               |             .                 |
               +-------------------------------+
   @endverbatim
 *
 * VC Based Multiplexing of Bridged Protocols
 *
 *  PDUs of bridged protocols shall be carried in the Payload of the AAL5
 *  CPCS-PDU.
 *
 * @verbatim
               Payload Format for Bridged Ethernet/802.3 PDUs
               +-------------------------------+
               |         PAD 0x00-00           |
               +-------------------------------+
               |    MAC destination address    |
               +-------------------------------+
               |                               |
               |   (remainder of MAC frame)    |
               |                               |
               +-------------------------------+
               | LAN FCS (VC dependent option) |
               +-------------------------------+
   @endverbatim
 *  
 * EthAal5App Codelet Data flow is illustrated in the diagram below:
 * @verbatim
   +--------------------------------------------------------------------------+
   |       IXP4XX                                                             |
   | +------------------------------------------------------------------------+
   | |       XScale                                                           |
   | |                                                                        |
   | |    +-------------------------------------------------------------------+
   | |    |       ethAal5App                                                  |
   | |    |                                                                   |
   | |    |   +--------------------------+      +------------------------+    |
   | |    |   | ixEAAEthTxDoneCallback   |      | ixEAAAtmTDonexCallback |    |
   | |    |   | -----------------        |      | -----------------      |    |
   | |  +---->| After mbuffer data was   |      | After mbuffer data was |    |
   | |  | |   | sent, ixEthAcc component |   +--|sent, ixEthAcc component|<-+ |
   | |  | |   | returns buffer back. It  |   |  | returns buffer back. It|  | |
   | |  | |   | will be given back to    |   |  | will be given back to  |  | |
   | |  | |   | ixAtmdAcc component.     |   |  | ixAtmdAcc component.   |  | |
   | |  | |   +--------------------------+   |  +------------------------+  | |
   | |  | |                           |      |                              | |
   | |  | |                           |      |                              | |
   | |  | |   +--------------------+  |      |  +--------------------+      | |
   | |  | |   | ixEAAEthRxCallback |  |      |  | ixEAAAtmRxCallback |      | |
   | |  | |   | -----------------  |  |      |  | -----------------  |      | |
   | |  | | +>| Received frame is  |  |      |  | Ethernet frame is  |      | |
   | |  | | | | encapsulated into  |  |      |  | extracted from Atm |<-+   | |
   | |  | | | | Atm packet and sent|  |   +--+  | packet and sent    |  |   | |
   | |  | |Rx | to Utopia through  |  |   |     | to Eth phy through |  |   | |
   | |  | | | |ixAtmdAcc component.|  |   |     |ixEthAcc component. |  |   | |
   | |  | | | +--------------------+  |   |     +--------------------+  |   | |
   | |  | +---------------------|-----|---|--------------------|--------|---|-+
   | |  |   |         +--Tx-----|-----|---|--------------------+        |   | |
   | |  +---------+   |    +----|-----|---+  +---------+                |   | |
   | |  |ixEthAcc |<--+    |    |     +----->|ixAtmdAcc|-----Rx---------+   | |
   | |  |         |<-------+    +----Tx----->|         |--------------------+ |
   | +------------------------------------------------------------------------+
   |     |        \                               |
   |     |         \                              |
   | +-------+     +-------+                      |
   | | NPE B |     | NPE C |                      |
   | +-------+     +-------+                +-----------+
   |   |   |          |  |                  | Utopia    |
   |   |   |          |  |                  |           |
   |  Eth Mac        Eth Mac                |           |
   +-----------------------------------------------------------
       |                |                          |
       |                |                          |
     +---------+    +---------+                    |
     |Eth Phy 1|    |Eth Phy 2|                    
     +---------+    +---------+
   @endverbatim
 *     
 * @par
 * <B>Configuration Example 1: Using Smartbit and Adtech with UTOPIA 
 * connection </B>
 *
 * @verbatim
   +-----------+          +-----------------------+          +---------+
   | Smartbits | <------> | (Eth) IXP4XX (Utopia) | <------> | Adtech  |
   +-----------+          +-----------------------+          +---------+
   @endverbatim 

 *   On smartbits set: dst. mac = MAC1  and src mac = MAC2 <br>
 *   On Adtech add AAL5 with eth. encapsulation, dst. mac = MAC2, 
 *   src. mac = MAC1 <br>
 *
 *   Dependently which Phy is used Adtech must use same VPI/VCI address as 
 *   assigned to Phy by ethAal5App. By default there are 8 pre-configured VCs
 *   with default VPI and VCI values:
 *      VPI/VCI = 10/63
 *      VPI/VCI = 10/91
 *      VPI/VCI = 10/92
 *      VPI/VCI = 10/93
 *      VPI/VCI = 10/94
 *      VPI/VCI = 10/95
 *      VPI/VCI = 10/96
 *
 * Configuration Example 2: Using Smartbits/PCs with ADSL connection<br>
 * 
 * @verbatim
  +----------+       +--------+        +-------+       +----------+
  |Smartbits1| <---> | IXP4XX |<------>|  CO   | <---> |Smartbits2|
  |          |  Eth  |  CPE   |  ADSL  |       |  Eth  |          |
  +----------+       +--------+        +-------+       +----------+
   @endverbatim 
 *
 *   The ADSL connection is enabled by the codelet when the modeType=2
 *   and it is operating on SPHY mode.
 *
 *   On smartbits1 set: dst. mac = MAC1  and src mac = MAC2 <br>
 *   On smartbits2 set: dst. mac = MAC2  and src mac = MAC1 <br>
 *
 * Configuration Example 3: Using DSLAM and Adtech with ADSL connection<br>
 *
 * @verbatim
 *                         +------------------+
 *                         |      Adtech      |
 *                         +------------------+
 *              +----------| Eth     |   OC3  |-------+