/** * @file IxAtmdAccCtrl.h * * @date 20-Mar-2002 * * @brief IxAtmdAcc Public API * * This file contains the public API of IxAtmdAcc, related to the * control functions of the component. * * * @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 -- */ /* ------------------------------------------------------ Doxygen group definitions ------------------------------------------------------ */ /** * * @defgroup IxAtmdAccCtrlAPI IXP400 ATM Driver Access (IxAtmdAcc) Control API * * @brief The public API for the IXP400 Atm Driver Control component * * IxAtmdAcc is the low level interface by which AAL PDU get transmitted * to,and received from the Utopia bus * * This part is related to the Control configuration * * @{ */ #ifndef IXATMDACCCTRL_H #define IXATMDACCCTRL_H #include "IxAtmdAcc.h" /* ------------------------------------------------------ AtmdAccCtrl Data Types definition ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @def IX_ATMDACC_PORT_DISABLE_IN_PROGRESS * * @brief Port enable return code * * This constant is used to tell IxAtmDAcc user that the port disable * functions are not complete. The user can call ixAtmdAccPortDisableComplete() * to find out when the disable has finished. The port enable can then proceed. * */ #define IX_ATMDACC_PORT_DISABLE_IN_PROGRESS 5 /** * * @ingroup IxAtmdAccCtrlAPI * * @def IX_ATMDACC_ALLPDUS * * @brief All PDUs * * This constant is used to tell IxAtmDAcc to process all PDUs from * the RX queue or the TX Done * * @sa IxAtmdAccRxDispatcher * @sa IxAtmdAccTxDoneDispatcher * */ #define IX_ATMDACC_ALLPDUS 0xffffffff /* ------------------------------------------------------ Part of the IxAtmdAcc interface related to RX traffic ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @brief Callback prototype for notification of available PDUs for * an Rx Q. * * This a protoype for a function which is called when there is at * least one Pdu available for processing on a particular Rx Q. * * This function should call @a ixAtmdAccRxDispatch() with * the aprropriate number of parameters to read and process the Rx Q. * * @sa ixAtmdAccRxDispatch * @sa ixAtmdAccRxVcConnect * @sa ixAtmdAccRxDispatcherRegister * * @param rxQueueId @ref IxAtmRxQueueId [in] indicates which RX queue to has Pdus to process. * @param numberOfPdusToProcess unsigned int [in] indicates the minimum number of * PDUs available to process all PDUs from the queue. * @param reservedPtr unsigned int* [out] pointer to a int location which can * be written to, but does not retain written values. This is * provided to make this prototype compatible * with @a ixAtmdAccRxDispatch() * * @return @li int - ignored. * */ typedef IX_STATUS (*IxAtmdAccRxDispatcher) (IxAtmRxQueueId rxQueueId, unsigned int numberOfPdusToProcess, unsigned int *reservedPtr); /* ------------------------------------------------------ Part of the IxAtmdAcc interface related to TX traffic ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @brief Callback prototype for transmitted mbuf when threshold level is * crossed. * * IxAtmdAccTxDoneDispatcher is the prototype of the user function * which get called when pdus are completely transmitted. This function * is likely to call the @a ixAtmdAccTxDoneDispatch() function. * * This function is called when the number of available pdus for * reception is crossing the threshold level as defined * in @a ixAtmdAccTxDoneDispatcherRegister() * * This function is called inside an Qmgr dispatch context. No system * resource or interrupt-unsafe feature should be used inside this * callback. * * Transmitted buffers recycling implementation is a sytem-wide mechanism * and needs to be set before any traffic is started. If this threshold * mechanism is not used, the user is responsible for polling the * transmitted buffers with @a ixAtmdAccTxDoneDispatch() * and @a ixAtmdAccTxDoneLevelQuery() functions. * * @sa ixAtmdAccTxDoneDispatcherRegister * @sa ixAtmdAccTxDoneDispatch * @sa ixAtmdAccTxDoneLevelQuery * * @param numberOfPdusToProcess unsigned int [in] - The current number of pdus currently * available for recycling * @param *reservedPtr unsigned int [out] - pointer to a int location which can be * written to but does not retain written values. This is provided * to make this prototype compatible * with @a ixAtmdAccTxDoneDispatch() * * @return @li IX_SUCCESS This is provided to make * this prototype compatible with @a ixAtmdAccTxDoneDispatch() * @return @li IX_FAIL invalid parameters or some unspecified internal * error occured. This is provided to make * this prototype compatible with @a ixAtmdAccTxDoneDispatch() * */ typedef IX_STATUS (*IxAtmdAccTxDoneDispatcher) (unsigned int numberOfPdusToProcess, unsigned int *reservedPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @brief Notification that the threshold number of scheduled cells * remains in a port's transmit Q. * * The is the prototype for of the user notification function which * gets called on a per-port basis, when the number of remaining * scheduled cells to be transmitted decreases to the threshold level. * The number of cells passed as a parameter can be used for scheduling * purposes as the maximum number of cells that can be passed in a * schedule table to the @a ixAtmdAccPortTxProcess() function. * * @sa ixAtmdAccPortTxCallbackRegister * @sa ixAtmdAccPortTxProcess * @sa ixAtmdAccPortTxFreeEntriesQuery * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * @param numberOfAvailableCells unsigned int [in] - number of available * cell entries.for the port * * @note - This functions shall not use system resources when used * inside an interrupt context. * */ typedef void (*IxAtmdAccPortTxLowCallback) (IxAtmLogicalPort port, unsigned int numberOfAvailableCells); /** * * @ingroup IxAtmdAccCtrlAPI * * @brief Prototype to submit cells for transmission * * IxAtmdAccTxVcDemandUpdateCallback is the prototype of the callback * function used by AtmD to notify an ATM Scheduler that the user of * a VC has submitted cells for transmission. * * @sa IxAtmdAccTxVcDemandUpdateCallback * @sa IxAtmdAccTxVcDemandClearCallback * @sa IxAtmdAccTxSchVcIdGetCallback * @sa ixAtmdAccPortTxScheduledModeEnable * * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be updated * is established * @param vcId int [in] - Identifies the VC to be updated. This is the value * returned by the @a IxAtmdAccTxSchVcIdGetCallback() call . * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should be added * to the queue for this VC. * * @return @li IX_SUCCESS the function is registering the cell demand for * this VC. * @return @li IX_FAIL the function cannot register cell for this VC : the * scheduler maybe overloaded or misconfigured * */ typedef IX_STATUS (*IxAtmdAccTxVcDemandUpdateCallback) (IxAtmLogicalPort port, int vcId, unsigned int numberOfCells); /** * * @ingroup IxAtmdAccCtrlAPI * * @brief prototype to remove all currently queued cells from a * registered VC * * IxAtmdAccTxVcDemandClearCallback is the prototype of the function * to remove all currently queued cells from a registered VC. The * pending cell count for the specified VC is reset to zero. After the * use of this callback, the scheduler shall not schedule more cells * for this VC. * * This callback function is called during a VC disconnection * @a ixAtmdAccTxVcTryDisconnect() * * @sa IxAtmdAccTxVcDemandUpdateCallback * @sa IxAtmdAccTxVcDemandClearCallback * @sa IxAtmdAccTxSchVcIdGetCallback * @sa ixAtmdAccPortTxScheduledModeEnable * @sa ixAtmdAccTxVcTryDisconnect * * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be cleared * is established * @param vcId int [in] - Identifies the VC to be cleared. This is the value * returned by the @a IxAtmdAccTxSchVcIdGetCallback() call . * * @return none * */ typedef void (*IxAtmdAccTxVcDemandClearCallback) (IxAtmLogicalPort port, int vcId); /** * * @ingroup IxAtmdAccCtrlAPI * * @brief prototype to get a scheduler vc id * * IxAtmdAccTxSchVcIdGetCallback is the prototype of the function to get * a scheduler vcId * * @sa IxAtmdAccTxVcDemandUpdateCallback * @sa IxAtmdAccTxVcDemandClearCallback * @sa IxAtmdAccTxSchVcIdGetCallback * @sa ixAtmdAccPortTxScheduledModeEnable * * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM logical port on which the VC is * established * @param vpi unsigned int [in] - For AAL0/AAL5 specifies the ATM vpi on which the * VC is established. * For OAM specifies the dedicated "OAM Tx channel" VPI. * @param vci unsigned int [in] - For AAL0/AAL5 specifies the ATM vci on which the * VC is established. * For OAM specifies the dedicated "OAM Tx channel" VCI. * @param connId @ref IxAtmConnId [in] - specifies the IxAtmdAcc connection Id already * associated with this VC * @param vcId int* [out] - pointer to a vcId * * @return @li IX_SUCCESS the function is returning a Scheduler vcId for this * VC * @return @li IX_FAIL the function cannot process scheduling for this VC. * the contents of vcId is unspecified * */ typedef IX_STATUS (*IxAtmdAccTxSchVcIdGetCallback) (IxAtmLogicalPort port, unsigned int vpi, unsigned int vci, IxAtmConnId connId, int *vcId); /* ------------------------------------------------------ Part of the IxAtmdAcc interface related to RX traffic ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccRxDispatcherRegister ( IxAtmRxQueueId queueId, IxAtmdAccRxDispatcher callback) * * @brief Register a notification callback to be invoked when there is * at least one entry on a particular Rx queue. * * This function registers a callback to be invoked when there is at * least one entry in a particular queue. The registered callback is * called every time when the hardware adds one or more pdus to the * specified Rx queue. * * This function cannot be used when a Rx Vc using this queue is * already existing. * * @note -The callback function can be the API function * @a ixAtmdAccRxDispatch() : every time the threhold level * of the queue is reached, the ixAtmdAccRxDispatch() is * invoked to remove all entries from the queue. * * @sa ixAtmdAccRxDispatch * @sa IxAtmdAccRxDispatcher * * @param queueId @ref IxAtmRxQueueId [in] RX queue identification * @param callback @ref IxAtmdAccRxDispatcher [in] function triggering the delivery of incoming * traffic. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS Successful call to @a ixAtmdAccRxDispatcherRegister() * @return @li IX_FAIL error in the parameters, or there is an * already active RX VC for this queue or some unspecified * internal error occurred. * */ PUBLIC IX_STATUS ixAtmdAccRxDispatcherRegister ( IxAtmRxQueueId queueId, IxAtmdAccRxDispatcher callback); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId, unsigned int numberOfPdusToProcess, unsigned int *numberOfPdusProcessedPtr) * * * @brief Control function which executes Rx processing for a particular * Rx stream. * * The @a IxAtmdAccRxDispatch() function is used to process received Pdus * available from one of the two incoming RX streams. When this function * is invoked, the incoming traffic (up to the number of PDUs passed as * a parameter) will be transferred to the IxAtmdAcc users through the * callback @a IxAtmdAccRxVcRxCallback(), as registered during the * @a ixAtmdAccRxVcConnect() call. * * The user receive callbacks will be executed in the context of this * function. * * Failing to use this function on a regular basis when there is traffic * will block incoming traffic and can result in Pdus being dropped by * the hardware. * * This should be used to control when received pdus are handed off from * the hardware to Aal users from a particluar stream. The function can * be used from a timer context, or can be registered as a callback in * response to an rx stream threshold event, or can be used inside an * active polling mechanism which is under user control. * * @note - The signature of this function is directly compatible with the * callback prototype which can be register with @a ixAtmdAccRxDispatcherRegister(). * * @sa ixAtmdAccRxDispatcherRegister * @sa IxAtmdAccRxVcRxCallback * @sa ixAtmdAccRxVcFreeEntriesQuery * * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which RX queue to process. * @param numberOfPdusToProcess unsigned int [in] - indicates the maxiumum number of PDU to * remove from the RX queue. A value of IX_ATMDACC_ALLPDUS indicates * to process all PDUs from the queue. This includes at least the PDUs * in the queue when the fuction is invoked. Because of real-time * constraints, there is no guarantee thatthe queue will be empty * when the function exits. If this parameter is greater than the * number of entries of the queues, the function will succeed * and the parameter numberOfPdusProcessedPtr will reflect the exact * number of PDUs processed. * @param *numberOfPdusProcessedPtr unsigned int [out] - indicates the actual number of PDU * processed during this call. This parameter cannot be a null * pointer. * * @return @li IX_SUCCESS the number of PDUs as indicated in * numberOfPdusProcessedPtr are removed from the RX queue and the VC callback * are called. * @return @li IX_FAIL invalid parameters or some unspecified internal * error occured. * */ PUBLIC IX_STATUS ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId, unsigned int numberOfPdusToProcess, unsigned int *numberOfPdusProcessedPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId, unsigned int *numberOfPdusPtr) * * @brief Query the number of entries in a particular RX queue. * * This function is used to retrieve the number of pdus received by * the hardware and ready for distribution to users. * * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query. * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of available * PDUs in the RX queue. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the * number of incoming pdus waiting in this queue * @return @li IX_FAIL an error occurs during processing. * The value in numberOfPdusPtr is unspecified. * * @note - This function is reentrant, doesn't use system resources * and can be used from an interrupt context. * */ PUBLIC IX_STATUS ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId, unsigned int *numberOfPdusPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId, unsigned int *numberOfPdusPtr) * * @brief Query the size of a particular RX queue. * * This function is used to retrieve the number of pdus the system is * able to queue when reception is complete. * * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query. * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of pdus * the system is able to queue in the RX queue. This parameter * cannot be a null pointer. * * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the * number of pdus the system is able to queue. * @return @li IX_FAIL an error occurs during processing. * The value in numberOfPdusPtr is unspecified. * * @note - This function is reentrant, doesn't use system resources * and can be used from an interrupt context. * */ PUBLIC IX_STATUS ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId, unsigned int *numberOfPdusPtr); /* ------------------------------------------------------ Part of the IxAtmdAcc interface related to TX traffic ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port, unsigned int *numberOfCellsPtr) * * @brief Get the number of available cells the system can accept for * transmission. * * The function is used to retrieve the number of cells that can be * queued for transmission to the hardware. * * This number is based on the worst schedule table where one cell * is stored in one schedule table entry, depending on the pdus size * and mbuf size and fragmentation. * * This function doesn't use system resources and can be used from a * timer context, or can be associated with a threshold event, or can * be used inside an active polling mechanism * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * @param numberOfCellsPtr unsigned int* [out] - number of available cells. * This parameter cannot be a null pointer. * * @sa ixAtmdAccPortTxProcess * * @return @li IX_SUCCESS numberOfCellsPtr contains the number of cells that can be scheduled * for this port. * @return @li IX_FAIL error in the parameters, or some processing error * occured. * */ PUBLIC IX_STATUS ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port, unsigned int *numberOfCellsPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port, unsigned int numberOfCells, IxAtmdAccPortTxLowCallback callback) * * @brief Configure the Tx port threshold value and register a callback to handle * threshold notifications. * * This function sets the threshold in cells * * @sa ixAtmdAccPortTxCallbackRegister * @sa ixAtmdAccPortTxProcess * @sa ixAtmdAccPortTxFreeEntriesQuery * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * @param numberOfCells unsigned int [in] - threshold value which triggers the callback * invocation, This number has to be one of the * values 0,1,2,4,8,16,32 .... * The maximum value cannot be more than half of the txVc queue * size (which can be retrieved using @a ixAtmdAccPortTxFreeEntriesQuery() * before any Tx traffic is sent for this port) * @param callback @ref IxAtmdAccPortTxLowCallback [in] - callback function to invoke when the threshold * level is reached. * This parameter cannot be a null pointer. * * @return @li IX_SUCCESS Successful call to @a ixAtmdAccPortTxCallbackRegister() * @return @li IX_FAIL error in the parameters, Tx channel already set for this port * threshold level is not correct or within the range regarding the * queue size:or unspecified error during processing: * * @note - This callback function get called when the threshold level drops from * (numberOfCells+1) cells to (numberOfCells) cells * * @note - This function should be called during system initialisation, * outside an interrupt context * */ PUBLIC IX_STATUS ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port, unsigned int numberOfCells, IxAtmdAccPortTxLowCallback callback); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port, IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback, IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback, IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback) * * @brief Put the port into Scheduled Mode * * This function puts the specified port into scheduled mode of * transmission which means an external s/w entity controls the * transmission of cells on this port. This faciltates traffic shaping on * the port. * * Any buffers submitted on a VC for this port will be queued in IxAtmdAcc. * The transmission of these buffers to and by the hardware will be driven * by a transmit schedule submitted regulary in calls to * @a ixAtmdAccPortTxProcess() by traffic shaping entity. * * The transmit schedule is expected to be dynamic in nature based on * the demand in cells for each VC on the port. Hence the callback * parameters provided to this function allow IxAtmdAcc to inform the * shaping entity of demand changes for each VC on the port. * * By default a port is in Unscheduled Mode so if this function is not * called, transmission of data is done without sheduling rules, on a * first-come, first-out basis. * * Once a port is put in scheduled mode it cannot be reverted to * un-scheduled mode. Note that unscheduled mode is not supported * in ixp425 1.0 * * @note - This function should be called before any VCs have be * connected on a port. Otherwise this function call will return failure. * * @note - This function uses internal locks and should not be called from * an interrupt context * * @sa IxAtmdAccTxVcDemandUpdateCallback * @sa IxAtmdAccTxVcDemandClearCallback * @sa IxAtmdAccTxSchVcIdGetCallback * @sa ixAtmdAccPortTxProcess * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * @param vcDemandUpdateCallback @ref IxAtmdAccTxVcDemandUpdateCallback [in] - callback function used to update * the number of outstanding cells for transmission. This parameter * cannot be a null pointer. * @param vcDemandClearCallback @ref IxAtmdAccTxVcDemandClearCallback [in] - callback function used to remove all * clear the number of outstanding cells for a VC. This parameter * cannot be a null pointer. * @param vcIdGetCallback @ref IxAtmdAccTxSchVcIdGetCallback [in] - callback function used to exchange vc * Identifiers between IxAtmdAcc and the entity supplying the * transmit schedule. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS scheduler registration is complete and the port * is now in scheduled mode. * @return @li IX_FAIL failed (wrong parameters, or traffic is already * enabled on this port, possibly without ATM shaping) * */ PUBLIC IX_STATUS ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port, IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback, IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback, IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortTxProcess (IxAtmLogicalPort port, IxAtmScheduleTable* scheduleTablePtr) * * @brief Transmit queue cells to the H/W based on the supplied schedule * table. * * This function @a ixAtmdAccPortTxProcess() process the schedule * table provided as a parameter to the function. As a result cells are * sent to the underlaying hardware for transmission. * * The schedule table is executed in its entirety or not at all. So the * onus is on the caller not to submit a table containing more cells than * can be transmitted at that point. The maximum numbers that can be * transmitted is guaranteed to be the number of cells as returned by the * function @a ixAtmdAccPortTxFreeEntriesQuery(). * * When the scheduler is invoked on a threshold level, IxAtmdAcc gives the * minimum number of cells (to ensure the callback will fire again later) * and the maximum number of cells that @a ixAtmdAccPortTxProcess() * will be able to process (assuming the ATM scheduler is able * to produce the worst-case schedule table, i.e. one entry per cell). * * When invoked ouside a threshold level, the overall number of cells of * the schedule table should be less than the number of cells returned * by the @a ixAtmdAccPortTxFreeEntriesQuery() function. * * After invoking the @a ixAtmdAccPortTxProcess() function, it is the * user choice to query again the queue level with the function * @a ixAtmdAccPortTxFreeEntriesQuery() and, depending on a new cell * number, submit an other schedule table. * * IxAtmdAcc will check that the number of cells in the schedule table * is compatible with the current transmit level. If the * * Obsolete or invalid connection Id will be silently discarded. * * This function is not reentrant for the same port. * * This functions doesn't use system resources and can be used inside an * interrupt context. * * This function is used as a response to the hardware requesting more * cells to transmit. * * @sa ixAtmdAccPortTxScheduledModeEnable * @sa ixAtmdAccPortTxFreeEntriesQuery * @sa ixAtmdAccPortTxCallbackRegister * @sa ixAtmdAccPortEnable * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * @param scheduleTablePtr @ref IxAtmScheduleTable* [in] - pointer to a scheduler update table. The * content of this table is not modified by this function. This * parameter cannot be a null pointer. * * @return @li IX_SUCCESS the schedule table process is complete * and cells are transmitted to the hardware * @return @li IX_ATMDACC_WARNING : Traffic will be dropped: the schedule table exceed * the hardware capacity If this error is ignored, further traffic * and schedule will work correctly. * Overscheduling does not occur when the schedule table does * not contain more entries that the number of free entries returned * by @a ixAtmdAccPortTxFreeEntriesQuery(). * However, Disconnect attempts just after this error will fail permanently * with the error code @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED, and it is * necessary to disable the port to make @a ixAtmdAccTxVcTryDisconnect() * successful. * @return @li IX_FAIL a wrong parameter is supplied, or the format of * the schedule table is invalid, or the port is not Enabled, or * an internal severe error occured. No cells is transmitted to the hardware * * @note - If the failure is linked to an overschedule of data cells * the result is an inconsistency in the output traffic (one or many * cells may be missing and the traffic contract is not respected). * */ PUBLIC IX_STATUS ixAtmdAccPortTxProcess (IxAtmLogicalPort port, IxAtmScheduleTable* scheduleTablePtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccTxDoneDispatch (unsigned int numberOfPdusToProcess, unsigned int *numberOfPdusProcessedPtr) * * @brief Process a number of pending transmit done pdus from the hardware. * * As a by-product of Atm transmit operation buffers which transmission * is complete need to be recycled to users. This function is invoked * to service the oustanding list of transmitted buffers and pass them * to VC users. * * Users are handed back pdus by invoking the free callback registered * during the @a ixAtmdAccTxVcConnect() call. * * There is a single Tx done stream servicing all active Atm Tx ports * which can contain a maximum of 64 entries. If this stream fills port * transmission will stop so this function must be call sufficently * frequently to ensure no disruption to the transmit operation. * * This function can be used from a timer context, or can be associated * with a TxDone level threshold event (see @a ixAtmdAccTxDoneDispatcherRegister() ), * or can be used inside an active polling mechanism under user control. * * For ease of use the signature of this function is compatible with the * TxDone threshold event callback prototype. * * This functions can be used inside an interrupt context. * * @sa ixAtmdAccTxDoneDispatcherRegister * @sa IxAtmdAccTxVcBufferReturnCallback * @sa ixAtmdAccTxDoneLevelQuery * * @param numberOfPdusToProcess unsigned int [in] - maxiumum number of pdus to remove * from the TX Done queue * @param *numberOfPdusProcessedPtr unsigned int [out] - number of pdus removed from * the TX Done queue. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS the number of pdus as indicated in * numberOfPdusToProcess are removed from the TX Done hardware * and passed to the user through the Tx Done callback registered * during a call to @a ixAtmdAccTxVcConnect() * @return @li IX_FAIL invalid parameters or numberOfPdusProcessedPtr is * a null pointer or some unspecified internal error occured. * */ PUBLIC IX_STATUS ixAtmdAccTxDoneDispatch (unsigned int numberOfPdusToProcess, unsigned int *numberOfPdusProcessedPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccTxDoneLevelQuery (unsigned int *numberOfPdusPtr) * * @brief Query the current number of transmit pdus ready for * recycling. * * This function is used to get the number of transmitted pdus which * the hardware is ready to hand back to user. * * This function can be used from a timer context, or can be associated * with a threshold event, on can be used inside an active polling * mechanism * * @sa ixAtmdAccTxDoneDispatch * * @param *numberOfPdusPtr unsigned int [out] - Pointer to the number of pdus transmitted * at the time of this function call, and ready for recycling * This parameter cannot be a null pointer. * * @return @li IX_SUCCESS numberOfPdusPtr contains the number of pdus * ready for recycling at the time of this function call * * @return @li IX_FAIL wrong parameter (null pointer as parameter).or * unspecified rocessing error occurs..The value in numberOfPdusPtr * is unspecified. * */ PUBLIC IX_STATUS ixAtmdAccTxDoneLevelQuery (unsigned int *numberOfPdusPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccTxDoneQueueSizeQuery (unsigned int *numberOfPdusPtr) * * @brief Query the TxDone queue size. * * This function is used to get the number of pdus which * the hardware is able to store after transmission is complete * * The returned value can be used to set a threshold and enable * a callback to be notified when the number of pdus is going over * the threshold. * * @sa ixAtmdAccTxDoneDispatcherRegister * * @param *numberOfPdusPtr unsigned int [out] - Pointer to the number of pdus the system * is able to queue after transmission * * @return @li IX_SUCCESS numberOfPdusPtr contains the the number of * pdus the system is able to queue after transmission * @return @li IX_FAIL wrong parameter (null pointer as parameter).or * unspecified rocessing error occurs..The value in numberOfPdusPtr * is unspecified. * * @note - This function is reentrant, doesn't use system resources * and can be used from an interrupt context. */ PUBLIC IX_STATUS ixAtmdAccTxDoneQueueSizeQuery (unsigned int *numberOfPdusPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccTxDoneDispatcherRegister (unsigned int numberOfPdus, IxAtmdAccTxDoneDispatcher notificationCallback) * * @brief Configure the Tx Done stream threshold value and register a * callback to handle threshold notifications. * * This function sets the threshold level in term of number of pdus at * which the supplied notification function should be called. * * The higher the threshold value is, the less events will be necessary * to process transmitted buffers. * * Transmitted buffers recycling implementation is a sytem-wide mechanism * and needs to be set prior any traffic is started. If this threshold * mechanism is not used, the user is responsible for polling the * transmitted buffers thanks to @a ixAtmdAccTxDoneDispatch() and * @a ixAtmdAccTxDoneLevelQuery() functions. * * This function should be called during system initialisation outside * an interrupt context * * @sa ixAtmdAccTxDoneDispatcherRegister * @sa ixAtmdAccTxDoneDispatch * @sa ixAtmdAccTxDoneLevelQuery * * @param numberOfPdus unsigned int [in] - The number of TxDone pdus which triggers the * callback invocation This number has to be a power of 2, one of the * values 0,1,2,4,8,16,32 ... * The maximum value cannot be more than half of the txDone queue * size (which can be retrieved using @a ixAtmdAccTxDoneQueueSizeQuery()) * @param notificationCallback @ref IxAtmdAccTxDoneDispatcher [in] - The function to invoke. (This * parameter can be @a ixAtmdAccTxDoneDispatch()).This * parameter ust not be a null pointer. * * @return @li IX_SUCCESS Successful call to ixAtmdAccTxDoneDispatcherRegister * @return @li IX_FAIL error in the parameters: * * @note - The notificationCallback will be called exactly when the threshold level * will increase from (numberOfPdus) to (numberOfPdus+1) * * @note - If there is no Tx traffic, there is no guarantee that TxDone Pdus will * be released to the user (when txDone level is permanently under the threshold * level. One of the preffered way to return resources to the user is to use * a mix of txDone notifications, used together with a slow * rate timer and an exclusion mechanism protecting from re-entrancy * * @note - The TxDone threshold will only hand back buffers when the threshold level is * crossed. Setting this threshold to a great number reduce the interrupt rate * and the cpu load, but also increase the number of outstanding mbufs and has * a system wide impact when these mbufs are needed by other components. * */ PUBLIC IX_STATUS ixAtmdAccTxDoneDispatcherRegister (unsigned int numberOfPdus, IxAtmdAccTxDoneDispatcher notificationCallback); /* ------------------------------------------------------ Part of the IxAtmdAcc interface related to Utopia config ------------------------------------------------------ */ /** * * @ingroup IxAtmdAccCtrlAPI * * @defgroup IxAtmdAccUtopiaCtrlAPI IXP400 ATM Driver Access (IxAtmdAcc) Utopia Control API * * @brief The public API for the IXP400 Atm Driver Control component * * IxAtmdAcc is the low level interface by which AAL PDU get * transmitted to,and received from the Utopia bus * * This part is related to the UTOPIA configuration. * * @{ */ /** * * @brief Utopia configuration * * This structure is used to set the Utopia parameters * @li contains the values of Utopia registers, to be set during initialisation * @li contains debug commands for NPE, to be used during development steps * * @note - the exact description of all parameters is done in the Utopia reference * documents. * */ typedef struct { /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxConfig_ * @brief Utopia Tx Config Register */ struct UtTxConfig_ { unsigned int reserved_1:1; /**< [31] These bits are always 0.*/ unsigned int txInterface:1; /**< [30] Utopia Transmit Interface. The following encoding * is used to set the Utopia Transmit interface as ATM master * or PHY slave: * @li 1 - PHY * @li 0 - ATM */ unsigned int txMode:1; /**< [29] Utopia Transmit Mode. The following encoding is used * to set the Utopia Transmit mode to SPHY or MPHY: * @li 1 - SPHY * @li 0 - MPHY */ unsigned int txOctet:1; /**< [28] Utopia Transmit cell transfer protocol. Used to set * the Utopia cell transfer protocol to Octet-level handshaking. * Note this is only applicable in SPHY mode. * @li 1 - Octet-handshaking enabled * @li 0 - Cell-handshaking enabled */ unsigned int txParity:1; /**< [27] Utopia Transmit parity enabled when set. TxEvenParity * defines the parity format odd/even. * @li 1 - Enable Parity generation. * @li 0 - ut_op_prty held low. */ unsigned int txEvenParity:1; /**< [26] Utopia Transmit Parity Mode * @li 1 - Even Parity Generated. * @li 0 - Odd Parity Generated. */ unsigned int txHEC:1; /**< [25] Header Error Check Insertion Mode. Specifies if the transmit * cell header check byte is calculated and inserted when set. * @li 1 - Generate HEC. * @li 0 - Disable HEC generation. */ unsigned int txCOSET:1; /**< [24] If enabled the HEC is Exclusive-ORÆed with the value 0x55 before * being presented on the Utopia bus. * @li 1 - Enable HEC ExOR with value 0x55 * @li 0 - Use generated HEC value. */ unsigned int reserved_2:1; /**< [23] These bits are always 0 */ unsigned int txCellSize:7; /**< [22:16] Transmit expected cell size. Configures the cell size * for the transmit module: Values between 52-64 are valid. */ unsigned int reserved_3:3; /**< [15:13] These bits are always 0 */ unsigned int txAddrRange:5; /**< [12:8] When configured as an ATM master in MPHY mode this * register specifies the upper limit of the PHY polling logical * range. The number of active PHYs are TxAddrRange + 1. */ unsigned int reserved_4:3; /**< [7:5] These bits are always 0 */ unsigned int txPHYAddr:5; /**< [4:0] When configured as a slave in an MPHY system this register * specifies the physical address of the PHY. */ } utTxConfig; /**< Tx config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxStatsConfig_ * @brief Utopia Tx stats Register */ struct UtTxStatsConfig_ { unsigned int vpi:12; /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0] @li Note: if VCStatsTxGFC is set to 0 the GFC field is ignored in test. */ unsigned int vci:16; /**< [19:4] ATM VCI [15:0] or PHY Address[4] */ unsigned int pti:3; /**< [3:1] ATM PTI [2:0] or PHY Address[3:1] @li Note: if VCStatsTxPTI is set to 0 the PTI field is ignored in test. @li Note: if VCStatsTxEnb is set to 0 only the transmit PHY port address as defined by this register is used for ATM statistics [4:0]. */ unsigned int clp:1; /**< [0] ATM CLP or PHY Address [0] @li Note: if VCStatsTxCLP is set to 0 the CLP field is ignored in test. @li Note: if VCStatsTxEnb is set to 0 only the transmit PHY port address as defined by this register is used for ATM statistics [4:0]. */ } utTxStatsConfig; /**< Tx stats config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxDefineIdle_ * @brief Utopia Tx idle cells Register */ struct UtTxDefineIdle_ { unsigned int vpi:12; /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0] @li Note: if VCIdleTxGFC is set to 0 the GFC field is ignored in test. */ unsigned int vci:16; /**< [19:4] ATM VCI [15:0] */ unsigned int pti:3; /**< [3:1] ATM PTI PTI [2:0] @li Note: if VCIdleTxPTI is set to 0 the PTI field is ignored in test.*/ unsigned int clp:1; /**< [0] ATM CLP [0] @li Note: if VCIdleTxCLP is set to 0 the CLP field is ignored in test.*/ } utTxDefineIdle; /**< Tx idle cell config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxEnableFields_ * @brief Utopia Tx ienable fields Register */ struct UtTxEnableFields_ { unsigned int defineTxIdleGFC:1; /**< [31] This register is used to include or exclude the GFC field of the ATM header when testing for Idle cells. @li 1 - GFC field is valid. @li 0 - GFC field ignored.*/ unsigned int defineTxIdlePTI:1; /**< [30] This register is used to include or exclude the PTI field of the ATM header when testing for Idle cells. @li 1 - PTI field is valid @li 0 - PTI field ignored.*/ unsigned int defineTxIdleCLP:1; /**< [29] This register is used to include or exclude the CLP field of the ATM header when testing for Idle cells. @li 1 - CLP field is valid. @li 0 - CLP field ignored. */ unsigned int phyStatsTxEnb:1; /**< [28] This register is used to enable or disable ATM statistics gathering based on the specified PHY address as defined in TxStatsConfig register. @li 1 - Enable statistics for specified transmit PHY address. @li 0 - Disable statistics for specified transmit PHY address. */ unsigned int vcStatsTxEnb:1; /**< [27] This register is used to change the ATM statistics-gathering mode from the specified logical PHY address to a specific VPI/VCI address. @li 1 - Enable statistics for specified VPI/VCI address. @li 0 - Disable statistics for specified VPI/VCI address */ unsigned int vcStatsTxGFC:1; /**< [26] This register is used to include or exclude the GFC field of the ATM header when ATM VPI/VCI statistics are enabled. GFC is only available at the UNI and uses the first 4-bits of the VPI field. @li 1 - GFC field is valid @li 0 - GFC field ignored.*/ unsigned int vcStatsTxPTI:1; /**< [25] This register is used to include or exclude the PTI field of the ATM header when ATM VPI/VCI statistics are enabled. @li 1 - PTI field is valid @li 0 - PTI field ignored.*/ unsigned int vcStatsTxCLP:1; /**< [24] This register is used to include or exclude the CLP field of the ATM header when ATM VPI/VCI statistics are enabled. @li 1 - CLP field is valid @li 0 - CLP field ignored. */ unsigned int reserved_1:3; /**< [23-21] These bits are always 0 */ unsigned int txPollStsInt:1; /**< [20] Enable the assertion of the ucp_tx_poll_sts condition where there is a change in polling status. @li 1 - ucp_tx_poll_sts asserted whenever there is a change in status @li 0 - ucp_tx_poll_sts asserted if ANY transmit PHY is available */ unsigned int txCellOvrInt:1; /**< [19] Enable TxCellCount overflow CBI Transmit Status condition assertion. @li 1 - If TxCellCountOvr is set assert the Transmit Status Condition. @li 0 - No CBI Transmit Status condition assertion */ unsigned int txIdleCellOvrInt:1; /**< [18] Enable TxIdleCellCount overflow Transmit Status Condition @li 1 - If TxIdleCellCountOvr is set assert the Transmit Status Condition @li 0 - No CBI Transmit Status condition assertion..*/ unsigned int enbIdleCellCnt:1; /**< [17] Enable Transmit Idle Cell Count. @li 1 - Enable count of Idle cells transmitted. @li 0 - No count is maintained. */ unsigned int enbTxCellCnt:1; /**< [16] Enable Transmit Valid Cell Count of non-idle/non-error cells @li 1 - Enable count of valid cells transmitted- non-idle/non-error @li 0 - No count is maintained.*/ unsigned int reserved_2:16; /**< [15:0] These bits are always 0 */ } utTxEnableFields; /**< Tx enable Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable0_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable0_ { unsigned int phy0:5; /**< [31-27] Tx Mapping value of logical phy 0 */ unsigned int phy1:5; /**< [26-22] Tx Mapping value of logical phy 1 */ unsigned int phy2:5; /**< [21-17] Tx Mapping value of logical phy 2 */ unsigned int reserved_1:1; /**< [16] These bits are always 0.*/ unsigned int phy3:5; /**< [15-11] Tx Mapping value of logical phy 3 */ unsigned int phy4:5; /**< [10-6] Tx Mapping value of logical phy 4 */ unsigned int phy5:5; /**< [5-1] Tx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utTxTransTable0; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable1_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable1_ { unsigned int phy6:5; /**< [31-27] Tx Mapping value of logical phy 6 */ unsigned int phy7:5; /**< [26-22] Tx Mapping value of logical phy 7 */ unsigned int phy8:5; /**< [21-17] Tx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy9:5; /**< [15-11] Tx Mapping value of logical phy 3 */ unsigned int phy10:5; /**< [10-6] Tx Mapping value of logical phy 4 */ unsigned int phy11:5; /**< [5-1] Tx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utTxTransTable1; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable2_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable2_ { unsigned int phy12:5; /**< [31-27] Tx Mapping value of logical phy 6 */ unsigned int phy13:5; /**< [26-22] Tx Mapping value of logical phy 7 */ unsigned int phy14:5; /**< [21-17] Tx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy15:5; /**< [15-11] Tx Mapping value of logical phy 3 */ unsigned int phy16:5; /**< [10-6] Tx Mapping value of logical phy 4 */ unsigned int phy17:5; /**< [5-1] Tx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utTxTransTable2; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable3_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable3_ { unsigned int phy18:5; /**< [31-27] Tx Mapping value of logical phy 6 */ unsigned int phy19:5; /**< [26-22] Tx Mapping value of logical phy 7 */ unsigned int phy20:5; /**< [21-17] Tx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy21:5; /**< [15-11] Tx Mapping value of logical phy 3 */ unsigned int phy22:5; /**< [10-6] Tx Mapping value of logical phy 4 */ unsigned int phy23:5; /**< [5-1] Tx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utTxTransTable3; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable4_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable4_ { unsigned int phy24:5; /**< [31-27] Tx Mapping value of logical phy 6 */ unsigned int phy25:5; /**< [26-22] Tx Mapping value of logical phy 7 */ unsigned int phy26:5; /**< [21-17] Tx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy27:5; /**< [15-11] Tx Mapping value of logical phy 3 */ unsigned int phy28:5; /**< [10-6] Tx Mapping value of logical phy 4 */ unsigned int phy29:5; /**< [5-1] Tx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utTxTransTable4; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxTransTable5_ * @brief Utopia Tx translation table Register */ struct UtTxTransTable5_ { unsigned int phy30:5; /**< [31-27] Tx Mapping value of logical phy 6 */ unsigned int reserved_1:27; /**< [26-0] These bits are always 0 */ } utTxTransTable5; /**< Tx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxConfig_ * @brief Utopia Rx config Register */ struct UtRxConfig_ { unsigned int rxInterface:1; /**< [31] Utopia Receive Interface. The following encoding is used to set the Utopia Receive interface as ATM master or PHY slave: @li 1 - PHY @li 0 - ATM */ unsigned int rxMode:1; /**< [30] Utopia Receive Mode. The following encoding is used to set the Utopia Receive mode to SPHY or MPHY: @li 1 - SPHY @li 0 - MPHY */ unsigned int rxOctet:1; /**< [29] Utopia Receive cell transfer protocol. Used to set the Utopia cell transfer protocol to Octet-level handshaking. Note this is only applicable in SPHY mode. @li 1 - Octet-handshaking enabled @li 0 - Cell-handshaking enabled */ unsigned int rxParity:1; /**< [28] Utopia Receive Parity Checking enable. @li 1 - Parity checking enabled @li 0 - Parity checking disabled */ unsigned int rxEvenParity:1;/**< [27] Utopia Receive Parity Mode @li 1 - Check for Even Parity @li 0 - Check for Odd Parity.*/ unsigned int rxHEC:1; /**< [26] RxHEC Header Error Check Mode. Enables/disables cell header error checking on the received cell header. @li 1 - HEC checking enabled @li 0 - HEC checking disabled */ unsigned int rxCOSET:1; /**< [25] If enabled the HEC is Exclusive-ORÆed with the value 0x55 before being tested with the received HEC. @li 1 - Enable HEC ExOR with value 0x55. @li 0 - Use generated HEC value.*/ unsigned int rxHECpass:1; /**< [24] Specifies if the incoming cell HEC byte should be transferred after optional processing to the NPE2 Coprocessor Bus Interface or if it should be discarded. @li 1 - HEC maintained 53-byte/UDC cell sent to NPE2. @li 0 - HEC discarded 52-byte/UDC cell sent to NPE2 coprocessor.*/ unsigned int reserved_1:1; /**< [23] These bits are always 0 */ unsigned int rxCellSize:7; /**< [22:16] Receive cell size. Configures the receive cell size. Values between 52-64 are valid */ unsigned int rxHashEnbGFC:1; /**< [15] Specifies if the VPI field [11:8]/GFC field should be included in the Hash data input or if the bits should be padded with 1Æb0. @li 1 - VPI [11:8]/GFC field valid and used in Hash residue calculation. @li 0 - VPI [11:8]/GFC field padded with 1Æb0 */ unsigned int rxPreHash:1; /**< [14] Enable Pre-hash value generation. Specifies if the incoming cell data should be pre-hashed to allow VPI/VCI header look-up in a hash table. @li 1 - Pre-hashing enabled @li 0 - Pre-hashing disabled */ unsigned int reserved_2:1; /**< [13] These bits are always 0 */ unsigned int rxAddrRange:5; /**< [12:8] In ATM master, MPHY mode, * this register specifies the upper * limit of the PHY polling logical range. The number of active PHYs are * RxAddrRange + 1. */ unsigned int reserved_3:3; /**< [7-5] These bits are always 0 .*/ unsigned int rxPHYAddr:5; /**< [4:0] When configured as a slave in an MPHY system this register * specifies the physical address of the PHY. */ } utRxConfig; /**< Rx config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxStatsConfig_ * @brief Utopia Rx stats config Register */ struct UtRxStatsConfig_ { unsigned int vpi:12; /**< [31:20] ATM VPI VPI [11:0] OR GFC [3:0] and VPI [7:0] @li Note: if VCStatsRxGFC is set to 0 the GFC field is ignored in test. */ unsigned int vci:16; /**< [19:4] VCI [15:0] or PHY Address [4] */ unsigned int pti:3; /**< [3:1] PTI [2:0] or or PHY Address [3:1] @li Note: if VCStatsRxPTI is set to 0 the PTI field is ignored in test. @li Note: if VCStatsRxEnb is set to 0 only the PHY port address is used for statistics gathering.. */ unsigned int clp:1; /**< [0] CLP [0] or PHY Address [0] @li Note: if VCStatsRxCLP is set to 0 the CLP field is ignored in test. @li Note: if VCStatsRxEnb is set to 0 only the PHY port address is used for statistics gathering.. */ } utRxStatsConfig; /**< Rx stats config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxDefineIdle_ * @brief Utopia Rx idle cells config Register */ struct UtRxDefineIdle_ { unsigned int vpi:12; /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0] @li Note: if VCIdleRxGFC is set to 0 the GFC field is ignored in test. */ unsigned int vci:16; /**< [19:4] ATM VCI [15:0] */ unsigned int pti:3; /**< [3:1] ATM PTI PTI [2:0] @li Note: if VCIdleRxPTI is set to 0 the PTI field is ignored in test.*/ unsigned int clp:1; /**< [0] ATM CLP [0] @li Note: if VCIdleRxCLP is set to 0 the CLP field is ignored in test.*/ } utRxDefineIdle; /**< Rx idle cell config Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxEnableFields_ * @brief Utopia Rx enable Register */ struct UtRxEnableFields_ { unsigned int defineRxIdleGFC:1;/**< [31] This register is used to include or exclude the GFC field of the ATM header when testing for Idle cells. @li 1 - GFC field is valid. @li 0 - GFC field ignored.*/ unsigned int defineRxIdlePTI:1;/**< [30] This register is used to include or exclude the PTI field of the ATM header when testing for Idle cells. @li 1 - PTI field is valid. @li 0 - PTI field ignored.*/ unsigned int defineRxIdleCLP:1;/**< [29] This register is used to include or exclude the CLP field of the ATM header when testing for Idle cells. @li 1 - CLP field is valid. @li 0 - CLP field ignored.*/ unsigned int phyStatsRxEnb:1;/**< [28] This register is used to enable or disable ATM statistics gathering based on the specified PHY address as defined in RxStatsConfig register. @li 1 - Enable statistics for specified receive PHY address. @li 0 - Disable statistics for specified receive PHY address.*/ unsigned int vcStatsRxEnb:1;/**< [27] This register is used to enable or disable ATM statistics gathering based on a specific VPI/VCI address. @li 1 - Enable statistics for specified VPI/VCI address. @li 0 - Disable statistics for specified VPI/VCI address.*/ unsigned int vcStatsRxGFC:1;/**< [26] This register is used to include or exclude the GFC field of the ATM header when ATM VPI/VCI statistics are enabled. GFC is only available at the UNI and uses the first 4-bits of the VPI field. @li 1 - GFC field is valid. @li 0 - GFC field ignored. */ unsigned int vcStatsRxPTI:1;/**< [25] This register is used to include or exclude the PTI field of the ATM header when ATM VPI/VCI statistics are enabled. @li 1 - PTI field is valid. @li 0 - PTI field ignored.*/ unsigned int vcStatsRxCLP:1;/**< [24] This register is used to include or exclude the CLP field of the ATM header when ATM VPI/VCI statistics are enabled. @li 1 - CLP field is valid. @li 0 - CLP field ignored. */ unsigned int discardHecErr:1;/**< [23] Discard cells with an invalid HEC. @li 1 - Discard cells with HEC errors @li 0 - Cells with HEC errors are passed */ unsigned int discardParErr:1;/**< [22] Discard cells containing parity errors. @li 1 - Discard cells with parity errors @li 0 - Cells with parity errors are passed */ unsigned int discardIdle:1; /**< [21] Discard Idle Cells based on DefineIdle register values @li 1 - Discard IDLE cells @li 0 - IDLE cells passed */ unsigned int enbHecErrCnt:1;/**< [20] Enable Receive HEC Error Count. @li 1 - Enable count of received cells containing HEC errors @li 0 - No count is maintained. */ unsigned int enbParErrCnt:1;/**< [19] Enable Parity Error Count @li 1 - Enable count of received cells containing Parity errors @li 0 - No count is maintained. */ unsigned int enbIdleCellCnt:1;/**< [18] Enable Receive Idle Cell Count. @li 1 - Enable count of Idle cells received. @li 0 - No count is maintained.*/ unsigned int enbSizeErrCnt:1;/**< [17] Enable Receive Size Error Count. @li 1 - Enable count of received cells of incorrect size @li 0 - No count is maintained. */ unsigned int enbRxCellCnt:1;/**< [16] Enable Receive Valid Cell Count of non-idle/non-error cells. @li 1 - Enable count of valid cells received - non-idle/non-error @li 0 - No count is maintained. */ unsigned int reserved_1:3; /**< [15:13] These bits are always 0 */ unsigned int rxCellOvrInt:1; /**< [12] Enable CBI Utopia Receive Status Condition if the RxCellCount register overflows. @li 1 - CBI Receive Status asserted. @li 0 - No CBI Receive Status asserted.*/ unsigned int invalidHecOvrInt:1; /**< [11] Enable CBI Receive Status Condition if the InvalidHecCount register overflows. @li 1 - CBI Receive Condition asserted. @li 0 - No CBI Receive Condition asserted */ unsigned int invalidParOvrInt:1; /**< [10] Enable CBI Receive Status Condition if the InvalidParCount register overflows @li 1 - CBI Receive Condition asserted. @li 0 - No CBI Receive Condition asserted */ unsigned int invalidSizeOvrInt:1; /**< [9] Enable CBI Receive Status Condition if the InvalidSizeCount register overflows. @li 1 - CBI Receive Status Condition asserted. @li¸0 - No CBI Receive Status asserted */ unsigned int rxIdleOvrInt:1; /**< [8] Enable CBI Receive Status Condition if the RxIdleCount overflows. @li 1 - CBI Receive Condition asserted. @li 0 - No CBI Receive Condition asserted */ unsigned int reserved_2:3; /**< [7:5] These bits are always 0 */ unsigned int rxAddrMask:5; /**< [4:0] This register is used as a mask to allow the user to increase the PHY receive address range. The register should be programmed with the address-range limit, i.e. if set to 0x3 the address range increases to a maximum of 4 addresses. */ } utRxEnableFields; /**< Rx enable Utopia register */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable0_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable0_ { unsigned int phy0:5; /**< [31-27] Rx Mapping value of logical phy 0 */ unsigned int phy1:5; /**< [26-22] Rx Mapping value of logical phy 1 */ unsigned int phy2:5; /**< [21-17] Rx Mapping value of logical phy 2 */ unsigned int reserved_1:1; /**< [16] These bits are always 0 */ unsigned int phy3:5; /**< [15-11] Rx Mapping value of logical phy 3 */ unsigned int phy4:5; /**< [10-6] Rx Mapping value of logical phy 4 */ unsigned int phy5:5; /**< [5-1] Rx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utRxTransTable0; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable1_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable1_ { unsigned int phy6:5; /**< [31-27] Rx Mapping value of logical phy 6 */ unsigned int phy7:5; /**< [26-22] Rx Mapping value of logical phy 7 */ unsigned int phy8:5; /**< [21-17] Rx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy9:5; /**< [15-11] Rx Mapping value of logical phy 3 */ unsigned int phy10:5; /**< [10-6] Rx Mapping value of logical phy 4 */ unsigned int phy11:5; /**< [5-1] Rx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utRxTransTable1; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable2_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable2_ { unsigned int phy12:5; /**< [31-27] Rx Mapping value of logical phy 6 */ unsigned int phy13:5; /**< [26-22] Rx Mapping value of logical phy 7 */ unsigned int phy14:5; /**< [21-17] Rx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy15:5; /**< [15-11] Rx Mapping value of logical phy 3 */ unsigned int phy16:5; /**< [10-6] Rx Mapping value of logical phy 4 */ unsigned int phy17:5; /**< [5-1] Rx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utRxTransTable2; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable3_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable3_ { unsigned int phy18:5; /**< [31-27] Rx Mapping value of logical phy 6 */ unsigned int phy19:5; /**< [26-22] Rx Mapping value of logical phy 7 */ unsigned int phy20:5; /**< [21-17] Rx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy21:5; /**< [15-11] Rx Mapping value of logical phy 3 */ unsigned int phy22:5; /**< [10-6] Rx Mapping value of logical phy 4 */ unsigned int phy23:5; /**< [5-1] Rx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utRxTransTable3; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable4_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable4_ { unsigned int phy24:5; /**< [31-27] Rx Mapping value of logical phy 6 */ unsigned int phy25:5; /**< [26-22] Rx Mapping value of logical phy 7 */ unsigned int phy26:5; /**< [21-17] Rx Mapping value of logical phy 8 */ unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */ unsigned int phy27:5; /**< [15-11] Rx Mapping value of logical phy 3 */ unsigned int phy28:5; /**< [10-6] Rx Mapping value of logical phy 4 */ unsigned int phy29:5; /**< [5-1] Rx Mapping value of logical phy 5 */ unsigned int reserved_2:1; /**< [0] These bits are always 0 */ } utRxTransTable4; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxTransTable5_ * @brief Utopia Rx translation table Register */ struct UtRxTransTable5_ { unsigned int phy30:5; /**< [31-27] Rx Mapping value of logical phy 6 */ unsigned int reserved_1:27; /**< [26-0] These bits are always 0 */ } utRxTransTable5; /**< Rx translation table */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtSysConfig_ * @brief NPE setup Register */ struct UtSysConfig_ { unsigned int reserved_1:2; /**< [31-30] These bits are always 0 */ unsigned int txEnbFSM:1; /**< [29] Enables the operation ofthe Utopia Transmit FSM * @li 1 - FSM enabled * @li 0 - FSM inactive */ unsigned int rxEnbFSM:1; /**< [28] Enables the operation ofthe Utopia Revieve FSM * @li 1 - FSM enabled * @li 0 - FSM inactive */ unsigned int disablePins:1; /**< [27] Disable Utopia interface I/O pins forcing the signals to an * inactive state. Note that this bit is set on reset and must be * de-asserted * @li 0 - Normal data transfer * @li 1 - Utopia interface pins are forced inactive */ unsigned int tstLoop:1; /**< [26] Test Loop Back Enable. * @li Note: For loop back to function RxMode and Tx Mode must both be set * to single PHY mode. * @li 0 - Loop back * @li 1 - Normal operating mode */ unsigned int txReset:1; /**< [25] Resets the Utopia Coprocessor transmit module to a known state. * @li Note: All transmit configuration and status registers will be reset * to their reset values. * @li 0 - Normal operating mode¸ * @li 1 - Reset transmit modules */ unsigned int rxReset:1; /**< [24] Resets the Utopia Coprocessor receive module to a known state. * @li Note: All receive configuration and status registers will be reset * to their reset values. * @li 0 - Normal operating mode * @li 1 - Reset receive modules */ unsigned int reserved_2:24; /**< [23-0] These bits are always 0 */ } utSysConfig; /**< NPE debug config */ } IxAtmdAccUtopiaConfig; /** * * @brief Utopia status * * This structure is used to set/get the Utopia status parameters * @li contains debug cell counters, to be accessed during a read operation * * @note - the exact description of all parameters is done in the Utopia reference * documents. * */ typedef struct { unsigned int utTxCellCount; /**< count of cells transmitted */ unsigned int utTxIdleCellCount; /**< count of idle cells transmitted */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtTxCellConditionStatus_ * @brief Utopia Tx Status Register */ struct UtTxCellConditionStatus_ { unsigned int reserved_1:2; /**< [31:30] These bits are always 0 */ unsigned int txFIFO2Underflow:1; /**< [29] This bit is set if 64-byte * Transmit FIFO2 indicates a FIFO underflow * error condition. */ unsigned int txFIFO1Underflow:1; /**< [28] This bit is set if * 64-byte Transmit FIFO1 indicates a FIFO * underflow error condition. */ unsigned int txFIFO2Overflow:1; /**< [27] This bit is set if 64-byte * Transmit FIFO2 indicates a FIFO overflow * error condition. */ unsigned int txFIFO1Overflow:1; /**< [26] This bit is set if 64-byte * Transmit FIFO1 indicates a FIFO overflow * error condition. */ unsigned int txIdleCellCountOvr:1; /**< [25] This bit is set if the * TxIdleCellCount register overflows. */ unsigned int txCellCountOvr:1; /**< [24] This bit is set if the * TxCellCount register overflows */ unsigned int reserved_2:24; /**< [23:0] These bits are always 0 */ } utTxCellConditionStatus; /**< Tx cells condition status */ unsigned int utRxCellCount; /**< count of cell received */ unsigned int utRxIdleCellCount; /**< count of idle cell received */ unsigned int utRxInvalidHECount; /**< count of invalid cell * received because of HEC errors */ unsigned int utRxInvalidParCount; /**< count of invalid cell received * because of parity errors */ unsigned int utRxInvalidSizeCount; /**< count of invalid cell * received because of cell * size errors */ /** * @ingroup IxAtmdAccUtopiaCtrlAPI * @struct UtRxCellConditionStatus_ * @brief Utopia Rx Status Register */ struct UtRxCellConditionStatus_ { unsigned int reserved_1:3; /**< [31:29] These bits are always 0.*/ unsigned int rxCellCountOvr:1; /**< [28] This bit is set if the RxCellCount register overflows. */ unsigned int invalidHecCountOvr:1; /**< [27] This bit is set if the InvalidHecCount register overflows.*/ unsigned int invalidParCountOvr:1; /**< [26] This bit is set if the InvalidParCount register overflows.*/ unsigned int invalidSizeCountOvr:1; /**< [25] This bit is set if the InvalidSizeCount register overflows.*/ unsigned int rxIdleCountOvr:1; /**< [24] This bit is set if the RxIdleCount register overflows.*/ unsigned int reserved_2:4; /**< [23:20] These bits are always 0 */ unsigned int rxFIFO2Underflow:1; /**< [19] This bit is set if 64-byte Receive FIFO2 * indicates a FIFO underflow error condition. */ unsigned int rxFIFO1Underflow:1; /**< [18] This bit is set if 64-byte Receive * FIFO1 indicates a FIFO underflow error condition . */ unsigned int rxFIFO2Overflow:1; /**< [17] This bit is set if 64-byte Receive FIFO2 * indicates a FIFO overflow error condition. */ unsigned int rxFIFO1Overflow:1; /**< [16] This bit is set if 64-byte Receive FIFO1 * indicates a FIFO overflow error condition. */ unsigned int reserved_3:16; /**< [15:0] These bits are always 0. */ } utRxCellConditionStatus; /**< Rx cells condition status */ } IxAtmdAccUtopiaStatus; /** * @} defgroup IxAtmdAccUtopiaCtrlAPI */ /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccUtopiaConfigSet (const IxAtmdAccUtopiaConfig * ixAtmdAccUtopiaConfigPtr) * * @brief Send the configuration structure to the Utopia interface * * This function downloads the @a IxAtmdAccUtopiaConfig structure to * the Utopia and has the following effects * @li setup the Utopia interface * @li initialise the NPE * @li reset the Utopia cell counters and status registers to known values * * This action has to be done once at initialisation. A lock is preventing * the concurrent use of @a ixAtmdAccUtopiaStatusGet() and * @A ixAtmdAccUtopiaConfigSet() * * @param *ixAtmdAccNPEConfigPtr @ref IxAtmdAccUtopiaConfig [in] - pointer to a structure to download to * Utopia. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS successful download * @return @li IX_FAIL error in the parameters, or configuration is not * complete or failed * * @sa ixAtmdAccUtopiaStatusGet * */ PUBLIC IX_STATUS ixAtmdAccUtopiaConfigSet (const IxAtmdAccUtopiaConfig * ixAtmdAccUtopiaConfigPtr); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccUtopiaStatusGet (IxAtmdAccUtopiaStatus * ixAtmdAccUtopiaStatus) * * @brief Get the Utopia interface configuration. * * This function reads the Utopia registers and the Cell counts * and fills the @a IxAtmdAccUtopiaStatus structure * * A lock is preventing the concurrent * use of @a ixAtmdAccUtopiaStatusGet() and @A ixAtmdAccUtopiaConfigSet() * * @param ixAtmdAccUtopiaStatus @ref IxAtmdAccUtopiaStatus [out] - pointer to structure to be updated from internal * hardware counters. This parameter cannot be a NULL pointer. * * @return @li IX_SUCCESS successful read * @return @li IX_FAIL error in the parameters null pointer, or * configuration read is not complete or failed * * @sa ixAtmdAccUtopiaConfigSet * */ PUBLIC IX_STATUS ixAtmdAccUtopiaStatusGet (IxAtmdAccUtopiaStatus * ixAtmdAccUtopiaStatus); /** * * @ingroup IxAtmdAcc * * @fn ixAtmdAccPortEnable (IxAtmLogicalPort port) * * @brief enable a PHY logical port * * This function enables the transmission over one port. It should be * called before accessing any resource from this port and before the * establishment of a VC. * * When a port is enabled, the cell transmission to the Utopia interface * is started. If there is no traffic already running, idle cells are * sent over the interface. * * This function can be called multiple times. * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * * @return @li IX_SUCCESS enable is complete * @return @li IX_ATMDACC_WARNING port already enabled * @return @li IX_FAIL enable failed, wrong parameter, or cannot * initialise this port (the port is maybe already in use, * or there is a hardware issue) * * @note - This function needs internal locks and should not be * called from an interrupt context * * @sa ixAtmdAccPortDisable * */ PUBLIC IX_STATUS ixAtmdAccPortEnable (IxAtmLogicalPort port); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortDisable (IxAtmLogicalPort port) * * @brief disable a PHY logical port * * This function disable the transmission over one port. * * When a port is disabled, the cell transmission to the Utopia interface * is stopped. * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * * @return @li IX_SUCCESS disable is complete * @return @li IX_ATMDACC_WARNING port already disabled * @return @li IX_FAIL disable failed, wrong parameter . * * @note - This function needs internal locks and should not be called * from an interrupt context * * @note - The response from hardware is done through the txDone mechanism * to ensure the synchrnisation with tx resources. Therefore, the * txDone mechanism needs to be serviced to make a PortDisable complete. * * @sa ixAtmdAccPortEnable * @sa ixAtmdAccPortDisableComplete * @sa ixAtmdAccTxDoneDispatch * */ PUBLIC IX_STATUS ixAtmdAccPortDisable (IxAtmLogicalPort port); /** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccPortDisableComplete (IxAtmLogicalPort port) * * @brief disable a PHY logical port * * This function indicates if the port disable for a port has completed. This * function will return TRUE if the port has never been enabled. * * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1] * * @return @li TRUE disable is complete * @return @li FALSE disable failed, wrong parameter . * * @note - This function needs internal locks and should not be called * from an interrupt context * * @sa ixAtmdAccPortEnable * @sa ixAtmdAccPortDisable * */ PUBLIC BOOL ixAtmdAccPortDisableComplete (IxAtmLogicalPort port); #endif /* IXATMDACCCTRL_H */ /** * @} defgroup IxAtmdAccCtrlAPI */