diff options
Diffstat (limited to 'cpu/ixp/npe/include/IxAtmm.h')
| -rw-r--r-- | cpu/ixp/npe/include/IxAtmm.h | 795 |
1 files changed, 795 insertions, 0 deletions
diff --git a/cpu/ixp/npe/include/IxAtmm.h b/cpu/ixp/npe/include/IxAtmm.h new file mode 100644 index 00000000000..fcf523fca4a --- /dev/null +++ b/cpu/ixp/npe/include/IxAtmm.h @@ -0,0 +1,795 @@ +/** + * @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 + * 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 indicated ATM port rates have been + * successfully modified. + * + * @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 update the port because the + * inputs are not understood, or the interface was called before + * the port was initialized. */ +PUBLIC IX_STATUS +ixAtmmPortModify (IxAtmLogicalPort port, + unsigned txPortRate, + unsigned rxPortRate); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmPortQuery (IxAtmLogicalPort port, + unsigned *txPortRate, + unsigned *rxPortRate); + + * + * @brief The client may call this interface to request details on + * currently registered transmit and receive rates for an ATM + * port. + * + * @param port @ref IxAtmLogicalPort [in] - Value identifies the port from which the + * rate details are requested. + * + * @param *txPortRate unsigned [out] - Pointer to a value + * which will be filled with the value of the transmit port + * rate specified in bits/second. + * + * @param *rxPortRate unsigned [out] - Pointer to a value + * which will be filled with the value of the receive port + * rate specified in bits/second. + * + * @return @li IX_SUCCESS : The information requested on the specified + * port has been successfully supplied in the output. + * + * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the + * input is not valid. The request is rejected. + * + * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was + * NULL. + * + * @return @li IX_FAIL : IxAtmm could not update the port because the + * inputs are not understood, or the interface was called before + * the port was initialized. */ +PUBLIC IX_STATUS +ixAtmmPortQuery (IxAtmLogicalPort port, + unsigned *txPortRate, + unsigned *rxPortRate); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmPortEnable(IxAtmLogicalPort port) + * + * @brief The client call this interface to enable transmit for an ATM + * port. At initialisation, all the ports are disabled. + * + * @param port @ref IxAtmLogicalPort [in] - Value identifies the port + * + * @return @li IX_SUCCESS : Transmission over this port is started. + * + * @return @li IX_FAIL : The port parameter is not valid, or the + * port is already enabled + * + * @note - When a port is disabled, Rx and Tx VC Connect requests will fail + * + * @note - This function uses system resources and should not be used + * inside an interrupt context. + * + * @sa ixAtmmPortDisable */ +PUBLIC IX_STATUS +ixAtmmPortEnable(IxAtmLogicalPort port); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmPortDisable(IxAtmLogicalPort port) + * + * @brief The client call this interface to disable transmit for an ATM + * port. At initialisation, all the ports are disabled. + * + * @param port @ref IxAtmLogicalPort [in] - Value identifies the port + * + * @return @li IX_SUCCESS : Transmission over this port is stopped. + * + * @return @li IX_FAIL : The port parameter is not valid, or the + * port is already disabled + * + * @note - When a port is disabled, Rx and Tx VC Connect requests will fail + * + * @note - This function call does not stop RX traffic. It is supposed + * that this function is invoked when a serious problem + * is detected (e.g. physical layer broken). Then, the RX traffic + * is not passing. + * + * @note - This function is blocking until the hw acknowledge that the + * transmission is stopped. + * + * @note - This function uses system resources and should not be used + * inside an interrupt context. + * + * @sa ixAtmmPortEnable */ +PUBLIC IX_STATUS +ixAtmmPortDisable(IxAtmLogicalPort port); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcRegister (IxAtmLogicalPort port, + IxAtmmVc *vcToAdd, + IxAtmSchedulerVcId *vcId) + * + * @brief This interface is used to register an ATM Virtual + * Connection on the specified ATM port. + * + * Each call to this interface registers a unidirectional virtual + * connection with the parameters specified. If a bi-directional VC + * is needed, the function should be called twice (once for each + * direction, Tx & Rx) where the VPI and VCI and port parameters in + * each call are identical. + * + * With the addition of each new VC to a port, a series of + * callback functions are invoked by the IxAtmm component to notify + * possible external components of the change. The callback functions + * are registered using the @ref ixAtmmVcChangeCallbackRegister interface. + * + * The IxAtmSch component is notified of the registration of transmit + * VCs. + * + * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the specified VC is + * to be registered. + * + * @param *vcToAdd @ref IxAtmmVc [in] - Pointer to an @ref IxAtmmVc structure + * containing a description of the VC to be registered. The + * client shall fill the vpi, vci and direction and relevant + * trafficDesc members of this structure before calling this + * function. + * + * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which is filled + * with the per-port unique identifier value for this VC. + * This identifier will be required when a request is + * made to deregister or change this VC. VC identifiers + * for transmit VCs will have a value between 0-43, + * i.e. 32 data Tx VCs + 12 OAM Tx Port VCs. + * Receive VCs will have a value between 44-66, + * i.e. 32 data Rx VCs + 1 OAM Rx VC. + * + * @return @li IX_SUCCESS : The VC has been successfully registered on + * this port. The VC is ready for a client to configure IxAtmdAcc + * for receive and transmit operations on the VC. + * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the + * input is not valid or has not been initialized. The request + * is rejected. + * @return @li IX_ATMM_RET_INVALID_VC_DESCRIPTOR : The descriptor + * pointed to by vcToAdd is invalid. The registration request + * is rejected. + * @return @li IX_ATMM_RET_VC_CONFLICT : The VC requested conflicts with + * reserved VPI and/or VCI values or with another VC already activated + * on this port. + * @return @li IX_ATMM_RET_PORT_CAPACITY_IS_FULL : The VC cannot be + * registered in the port becuase the port capacity is + * insufficient to support the requested ATM traffic contract. + * The registration request is rejected. + * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was + * NULL. + * + * @warning IxAtmm has no capability of signaling or negotiating a virtual + * connection. Negotiation of the admission of the VC to the network + * is beyond the scope of this function. This is assumed to be + * performed by the calling client, if appropriate, + * before or after this function is called. + */ +PUBLIC IX_STATUS +ixAtmmVcRegister (IxAtmLogicalPort port, + IxAtmmVc *vcToAdd, + IxAtmSchedulerVcId *vcId); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId) + * + * @brief Function called by a client to deregister a VC from the + * system. + * + * With the removal of each new VC from a port, a series of + * registered callback functions are invoked by the IxAtmm component + * to notify possible external components of the change. The callback + * functions are registered using the @ref ixAtmmVcChangeCallbackRegister. + * + * The IxAtmSch component is notified of the removal of transmit VCs. + * + * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be + * removed is currently registered. + * + * @param vcId @ref IxAtmSchedulerVcId [in] - VC identifier value of the VC to + * be deregistered. This value was supplied to the client when + the VC was originally registered. This value can also be + queried from the IxAtmm component through the @ref ixAtmmVcQuery + * interface. + * + * @return @li IX_SUCCESS : The specified VC has been successfully + * removed from this port. + * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the + * input is not valid or has not been initialized. The request + * is rejected. + * @return @li IX_FAIL : There is no registered VC associated with the + * supplied identifier registered on this port. */ +PUBLIC IX_STATUS +ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcQuery (IxAtmLogicalPort port, + unsigned vpi, + unsigned vci, + IxAtmmVcDirection direction, + IxAtmSchedulerVcId *vcId, + IxAtmmVc *vcDesc) + * + * @brief This interface supplies information about an active VC on a + * particular port when supplied with the VPI, VCI and + * direction of that VC. + * + * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be + * queried is currently registered. + * + * @param vpi unsigned [in] - ATM VPI value of the requested VC. + * + * @param vci unsigned [in] - ATM VCI value of the requested VC. + * + * @param direction @ref IxAtmmVcDirection [in] - One of @ref + * IX_ATMM_VC_DIRECTION_TX or @ref IX_ATMM_VC_DIRECTION_RX + * indicating the direction (Tx or Rx) of the requested VC. + * + * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which will be + * filled with the VC identifier value for the requested + * VC (as returned by @ref ixAtmmVcRegister), if it + * exists on this port. + * + * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure + * which will be filled with the specific details of the + * requested VC, if it exists on this port. + * + * @return @li IX_SUCCESS : The specified VC has been found on this port + * and the requested details have been returned. + * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the + * input is not valid or has not been initialized. The request + * is rejected. + * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified + * port which matches the search criteria (VPI, VCI, direction) + * given. No data is returned. + * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was + * NULL. + * + */ +PUBLIC IX_STATUS +ixAtmmVcQuery (IxAtmLogicalPort port, + unsigned vpi, + unsigned vci, + IxAtmmVcDirection direction, + IxAtmSchedulerVcId *vcId, + IxAtmmVc *vcDesc); + + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc) + * + * @brief This interface supplies information about an active VC on a + * particular port when supplied with a vcId for that VC. + * + * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be + * queried is currently registered. + * + * @param vcId @ref IxAtmSchedulerVcId [in] - Value returned by @ref ixAtmmVcRegister which + * uniquely identifies the requested VC on this port. + * + * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure + * which will be filled with the specific details of the + * requested VC, if it exists on this port. + * + * @return @li IX_SUCCESS : The specified VC has been found on this port + * and the requested details have been returned. + * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the + * input is not valid or has not been initialized. The request + * is rejected. + * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified + * port which matches the supplied identifier. No data is + * returned. + * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was + * NULL. + */ +PUBLIC IX_STATUS +ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback) + * + * @brief This interface is invoked to supply a function to IxAtmm + * which will be called to notify the client if a new VC is + * registered with IxAtmm or an existing VC is removed. + * + * The callback, when invoked, will run within the context of the call + * to @ref ixAtmmVcRegister or @ref ixAtmmVcDeregister which caused + * the change of state. + * + * A maximum of 32 calbacks may be registered in with IxAtmm. + * + * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies + * with the @ref IxAtmmVcChangeCallback definition. This + * function will be invoked by IxAtmm with the appropiate + * parameters for the relevant VC when any VC has been + * registered or deregistered with IxAtmm. + * + * @return @li IX_SUCCESS : The specified callback has been registered + * successfully with IxAtmm and will be invoked when appropriate. + * @return @li IX_FAIL : Either the supplied callback is invalid, or + * IxAtmm has already registered 32 and connot accommodate + * any further registrations of this type. The request is + * rejected. + * + * @warning The client must not call either the @ref + * ixAtmmVcRegister or @ref ixAtmmVcDeregister interfaces + * from within the supplied callback function. */ +PUBLIC IX_STATUS ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback); + + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback) + * + * @brief This interface is invoked to deregister a previously supplied + * callback function. + * + * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies + * with the @ref IxAtmmVcChangeCallback definition. This + * function will removed from the table of callbacks. + * + * @return @li IX_SUCCESS : The specified callback has been deregistered + * successfully from IxAtmm. + * @return @li IX_FAIL : Either the supplied callback is invalid, or + * is not currently registered with IxAtmm. + */ +PUBLIC IX_STATUS +ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmUtopiaStatusShow (void) + * + * @brief Display utopia status counters + * + * @param "none" + * + * @return @li IX_SUCCESS : Show function was successful + * @return @li IX_FAIL : Internal failure + */ +PUBLIC IX_STATUS +ixAtmmUtopiaStatusShow (void); + +/** + * @ingroup IxAtmm + * + * @fn ixAtmmUtopiaCfgShow (void) + * + * @brief Display utopia information(config registers and status registers) + * + * @param "none" + * + * @return @li IX_SUCCESS : Show function was successful + * @return @li IX_FAIL : Internal failure + */ +PUBLIC IX_STATUS +ixAtmmUtopiaCfgShow (void); + +#endif +/* IXATMM_H */ + +/** @} */ |