/** * @file    IxAtmm.h * * @date    3-DEC-2001 * * @brief   Header file for the IXP400 ATM Manager component (IxAtmm) * *  * @par * IXP400 SW Release version 2.0 *  * -- Copyright Notice -- *  * @par * Copyright 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 -- *//** * @defgroup IxAtmm IXP400 ATM Manager (IxAtmm) API * * @brief IXP400 ATM Manager component Public API * * @{ */#ifndef IXATMM_H#define IXATMM_H/* * Put the user defined include files required */#include "IxAtmSch.h"#include "IxOsalTypes.h"/* * #defines and macros used in this file. *//**  * @def IX_ATMM_RET_ALREADY_INITIALIZED *  * @brief Component has already been initialized  */#define IX_ATMM_RET_ALREADY_INITIALIZED 2/**  * @def IX_ATMM_RET_INVALID_PORT *  * @brief Specified port does not exist or is out of range */#define IX_ATMM_RET_INVALID_PORT 3/**  * @def IX_ATMM_RET_INVALID_VC_DESCRIPTOR *  * @brief The VC description does not adhere to ATM standards */#define IX_ATMM_RET_INVALID_VC_DESCRIPTOR 4/**  * @def IX_ATMM_RET_VC_CONFLICT *  * @brief The VPI/VCI values supplied are either reserved, or they *         conflict with a previously registered VC on this port */#define IX_ATMM_RET_VC_CONFLICT 5/**  * @def IX_ATMM_RET_PORT_CAPACITY_IS_FULL *  * @brief The virtual connection cannot be established on the port *         because the remaining port capacity is not sufficient to *         support it */#define IX_ATMM_RET_PORT_CAPACITY_IS_FULL 6/**  * @def IX_ATMM_RET_NO_SUCH_VC *  * @brief No registered VC, as described by the supplied VCI/VPI or *         VC identifier values, exists on this port */#define IX_ATMM_RET_NO_SUCH_VC 7/**  * @def IX_ATMM_RET_INVALID_VC_ID *  * @brief The specified VC identifier is out of range. */#define IX_ATMM_RET_INVALID_VC_ID 8/**  * @def IX_ATMM_RET_INVALID_PARAM_PTR *  * @brief A pointer parameter was NULL. */#define IX_ATMM_RET_INVALID_PARAM_PTR 9/**  * @def IX_ATMM_UTOPIA_SPHY_ADDR   *  * @brief The phy address when in SPHY mode */#define IX_ATMM_UTOPIA_SPHY_ADDR 31/** * @def IX_ATMM_THREAD_PRI_HIGH * * @brief The value of high priority thread */#define IX_ATMM_THREAD_PRI_HIGH 90/* * Typedefs whose scope is limited to this file. *//** @brief Definition for use in the @ref IxAtmmVc structure. *         Indicates the direction of a VC */typedef enum{    IX_ATMM_VC_DIRECTION_TX=0, /**< Atmm Vc direction transmit*/    IX_ATMM_VC_DIRECTION_RX, /**< Atmm Vc direction receive*/    IX_ATMM_VC_DIRECTION_INVALID /**< Atmm Vc direction invalid*/} IxAtmmVcDirection;/** @brief Definition for use with @ref IxAtmmVcChangeCallback *         callback.  Indicates that the event type represented by the *         callback for this VC. */typedef enum{    IX_ATMM_VC_CHANGE_EVENT_REGISTER=0, /**< Atmm Vc event register*/    IX_ATMM_VC_CHANGE_EVENT_DEREGISTER, /**< Atmm Vc event de-register*/    IX_ATMM_VC_CHANGE_EVENT_INVALID /**< Atmm Vc event invalid*/} IxAtmmVcChangeEvent;/** @brief Definitions for use with @ref ixAtmmUTOPIAInit interface to *         indicate that UTOPIA loopback should be enabled or disabled *         on initialisation. */typedef enum{    IX_ATMM_UTOPIA_LOOPBACK_DISABLED=0, /**< Atmm Utopia loopback mode disabled*/    IX_ATMM_UTOPIA_LOOPBACK_ENABLED, /**< Atmm Utopia loopback mode enabled*/    IX_ATMM_UTOPIA_LOOPBACK_INVALID /**< Atmm Utopia loopback mode invalid*/} IxAtmmUtopiaLoopbackMode;/** @brief This structure describes the required attributes of a *         virtual connection.*/typedef struct {    unsigned vpi;  /**< VPI value of this virtual connection */    unsigned vci;  /**< VCI value of this virtual connection. */    IxAtmmVcDirection direction; /**< VC direction */    /** Traffic descriptor of this virtual connection.  This structure     *  is defined by the @ref IxAtmSch component.  */    IxAtmTrafficDescriptor trafficDesc;} IxAtmmVc;/** @brief Definitions for use with @ref ixAtmmUtopiaInit interface to *         indicate that UTOPIA multi-phy/single-phy mode is used. */typedef enum{    IX_ATMM_MPHY_MODE = 0, /**< Atmm phy mode mphy*/    IX_ATMM_SPHY_MODE, /**< Atmm phy mode sphy*/    IX_ATMM_PHY_MODE_INVALID /**< Atmm phy mode invalid*/} IxAtmmPhyMode;/** @brief Structure contains port-specific information required to *         initialize IxAtmm, and specifically, the IXP400 UTOPIA *         Level-2 device. */typedef struct {    unsigned reserved_1:11;     /**< [31:21] Should be zero */    unsigned UtopiaTxPhyAddr:5; /**< [20:16] Address of the     *   transmit (Tx) PHY for this     *   port on the 5-bit UTOPIA     *   Level-2 address bus */    unsigned reserved_2:11;     /**< [15:5] Should be zero */    unsigned UtopiaRxPhyAddr:5; /**< [4:0] Address of the receive     *   (Rx) PHY for this port on the     *   5-bit UTOPIA  Level-2     *   address bus */} IxAtmmPortCfg;/** @brief Callback type used with @ref ixAtmmVcChangeCallbackRegister interface *         Defines a callback type  which will be used to notify registered *         users of registration/deregistration events on a particular port * * @param eventType @ref IxAtmmVcChangeEvent [in] - Event indicating *                        whether the VC supplied has been added or *                        removed * * @param port @ref IxAtmLogicalPort [in] - Specifies the port on which the event has *                        occurred * * @param vcChanged @ref IxAtmmVc* [in] - Pointer to a structure which gives *                              details of the VC which has been added *                              or removed on the port */typedef void (*IxAtmmVcChangeCallback) (IxAtmmVcChangeEvent eventType,					IxAtmLogicalPort port,					const IxAtmmVc* vcChanged);/* * Variable declarations global to this file only. Externs are followed by * static variables. *//* * Extern function prototypes *//* * Function declarations *//**  * @ingroup IxAtmm * * @fn ixAtmmInit (void) * * @brief Interface to initialize the IxAtmm software component.  Can *         be called once only. * *  Must be called before any other IxAtmm API is called. * * @param "none" * *  @return @li  IX_SUCCESS : IxAtmm has been successfully initialized. *      Calls to other IxAtmm interfaces may now be performed. *  @return @li  IX_FAIL : IxAtmm has already been initialized. */PUBLIC IX_STATUSixAtmmInit (void);/**   * @ingroup IxAtmm *  * @fn ixAtmmUtopiaInit (unsigned numPorts,		  IxAtmmPhyMode phyMode,		  IxAtmmPortCfg portCfgs[],		  IxAtmmUtopiaLoopbackMode loopbackMode) * * @brief Interface to initialize the UTOPIA Level-2 ATM coprocessor *         for the specified number of physical ports.  The function *         must be called before the ixAtmmPortInitialize interface *         can operate successfully. * * @param numPorts unsigned [in] - Indicates the total number of logical *          ports that are active on the device.  Up to 12 ports are *          supported. * * @param phyMode @ref IxAtmmPhyMode [in] - Put the Utopia coprocessor in SPHY *        or MPHY mode. * * @param portCfgs[] @ref IxAtmmPortCfg [in] - Pointer to an array of elements *          detailing the UTOPIA specific port characteristics.  The *          length of the array must be equal to the number of ports *          activated.  ATM ports are referred to by the relevant *          offset in this array in all subsequent IxAtmm interface *          calls. * * @param loopbackMode @ref IxAtmmUtopiaLoopbackMode [in] - Value must be one of *          @ref IX_ATMM_UTOPIA_LOOPBACK_ENABLED or @ref *          IX_ATMM_UTOPIA_LOOPBACK_DISABLED indicating whether *          loopback should be enabled on the device.  Loopback can *          only be supported on a single PHY, therefore the numPorts *          parameter must be 1 if loopback is enabled. * * @return @li IX_SUCCESS : Indicates that the  UTOPIA device has been *      successfully initialized for the supplied ports. * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : The UTOPIA device has *      already been initialized. * @return @li IX_FAIL : The supplied parameters are invalid or have been *     rejected by the UTOPIA-NPE device. * * @warning * This interface may only be called once. * Port identifiers are assumed to range from 0 to (numPorts - 1) in all  * instances. * In all subsequent calls to interfaces supplied by IxAtmm, the specified * port value is expected to represent the offset in the portCfgs array * specified in this interface.  i.e. The first port in this array will * subsequently be represented as port 0, the second port as port 1, * and so on.*/PUBLIC IX_STATUSixAtmmUtopiaInit (unsigned numPorts,		  IxAtmmPhyMode phyMode,		  IxAtmmPortCfg portCfgs[],		  IxAtmmUtopiaLoopbackMode loopbackMode);/**    * @ingroup IxAtmm *  * @fn ixAtmmPortInitialize (IxAtmLogicalPort port,		      unsigned txPortRate,		      unsigned rxPortRate) * * @brief The interface is called following @ref ixAtmmUtopiaInit () *         and before calls to any other IxAtmm interface.  It serves *         to activate the registered ATM port with IxAtmm. * *  The transmit and receive port rates are specified in bits per *  second.  This translates to ATM cells per second according to the *  following formula: CellsPerSecond = portRate / (53*8)  The *  IXP400 device supports only 53 byte cells. The client shall make *  sure that the off-chip physical layer device has already been *  initialized. * *  IxAtmm will configure IxAtmdAcc and IxAtmSch to enable scheduling *  on the port. * *  This interface must be called once for each active port in the *  system.  The first time the interface is invoked, it will configure *  the mechanism by which the handling of transmit, transmit-done and *  receive are driven with the IxAtmdAcc component. * *  This function is reentrant. * *  @note The minimum tx rate that will be accepted is 424 bit/s which equates *        to 1 cell (53 bytes) per second. * * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be *          initialized. * * @param txPortRate unsigned [in] - Value specifies the *          transmit port rate for this port in *          bits/second.  This value is used by the ATM Scheduler *          component is evaluating VC access requests for the port. * * @param rxPortRate unsigned [in] - Value specifies the *          receive port rate for this port in bits/second. * * @return @li IX_SUCCESS : The specificed ATM port has been successfully *       initialized. IxAtmm is ready to accept VC registrations on *       this port. * * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : ixAtmmPortInitialize has *       already been called successfully on this port.  The current *       call is rejected. * * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the *       input is not valid.  The request is rejected. * * @return @li IX_FAIL : IxAtmm could not initialize the port because the * inputs are not understood. * * @sa ixAtmmPortEnable, ixAtmmPortDisable * */PUBLIC IX_STATUSixAtmmPortInitialize (IxAtmLogicalPort port,		      unsigned txPortRate,		      unsigned rxPortRate);/**     * @ingroup IxAtmm *  * @fn ixAtmmPortModify (IxAtmLogicalPort port,		  unsigned txPortRate,		  unsigned rxPortRate) * * @brief A client may call this interface to change the existing *         port rate (expressed in bits/second) on an established ATM *         port. * * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be *          initialized. * * @param txPortRate unsigned [in] -  Value specifies the`` *          transmit port rate for this port in *          bits/second.  This value is used by the ATM Scheduler