ixatmm.h

AMCC POWERPC 44X系列的U-BOOT文件

/**
 * @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_STATUS
ixAtmmInit (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_STATUS
ixAtmmUtopiaInit (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_STATUS
ixAtmmPortInitialize (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