/** * * @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