ixhssacc.h

u-boot-1.1.6 源码包

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn BOOL ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId, 
           IxHssAccHdlcPort hdlcPortId)
 *
 * @brief This function is called to check if a given HSS/HDLC port 
 * combination is in a connected state or not. This function may be called 
 * at any time to determine a ports state.  No other HssAccPacketised 
 * interface should be called while this interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
 * to disconnect and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
 *
 * @return 
 *         - TRUE The state of this HSS/HDLC port combination is disconnected,
 *                so if a disconnect was called, it is now completed.
 *         - FALSE The state of this HSS/HDLC port combination is connected,
 *                so if a disconnect was called, it is not yet completed.
 */
PUBLIC BOOL 
ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId, 
				     IxHssAccHdlcPort hdlcPortId);


/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId, 
              IxHssAccHdlcPort hdlcPortId, 
	      IX_OSAL_MBUF *buffer)
 *
 * @brief Function which the client calls at regular intervals to provide
 * mbufs to the access component for RX. A connection should exist for
 * the specified hssPortId/hdlcPortId combination before attempting to call this 
 * interface. Also, the connection should not be in a disconnecting state.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
 * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
 * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a free mbuf to filled with payload.
 *
 * @return 
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
 *                          to a resource error
 *         - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
 *                                      overflow
 */
PUBLIC IX_STATUS 
ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId, 
				IxHssAccHdlcPort hdlcPortId, 
				IX_OSAL_MBUF *buffer);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccPktPortTx (IxHssAccHssPort hssPortId, 
    IxHssAccHdlcPort hdlcPortId, 
    IX_OSAL_MBUF *buffer)
 *
 * @brief Function which the client calls when it wants to transmit
 * packetised data. An enabled connection should exist on the specified
 * hssPortId/hdlcPortId combination before attempting to call this interface.
 * No other HssAccPacketised 
 * interface should be called while this interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
 * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
 * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a chain of mbufs which the
 * client has filled with the payload
 *
 * @return 
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
 *                          to a resource error. See note.
 *         - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
 *                                      overflow
 *
 * @note IX_HSSACC_RESOURCE_ERR is returned when a free descriptor cannot be
 * obtained to send the chain of mbufs to the NPE.  This is a normal scenario.
 * HssAcc has a pool of descriptors and this error means that they are currently
 * all in use.
 * The recommended approach to this is to retry until a descriptor becomes free
 * and the packet is successfully transmitted.
 * Alternatively, the user could wait until the next IxHssAccPktTxDoneCallback
 * callback is triggered, and then retry, as it is this event that causes a
 * transmit descriptor to be freed. 
 */
PUBLIC IX_STATUS 
ixHssAccPktPortTx (IxHssAccHssPort hssPortId, 
		   IxHssAccHdlcPort hdlcPortId, 
		   IX_OSAL_MBUF *buffer);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccChanConnect (IxHssAccHssPort hssPortId, 
           unsigned bytesPerTSTrigger, 
	   UINT8 *rxCircular, 
	   unsigned numRxBytesPerTS, 
	   UINT32 *txPtrList, 
	   unsigned numTxPtrLists, 
	   unsigned numTxBytesPerBlk, 
	   IxHssAccChanRxCallback rxCallback)
 *
 * @brief This function allows the client to connect to the Tx/Rx NPE
 * Channelised Service. There can only be one client per HSS port. The
 * client is responsible for ensuring that the HSS port is configured
 * appropriately before its connect request. No other HssAccChannelised 
 * interface should be called while this interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 * @param bytesPerTSTrigger unsigned [in] - The NPE will trigger the access
 * component after bytesPerTSTrigger have been received for all trunk
 * timeslots. This figure is a multiple of 8 e.g. 8 for 1ms trigger, 16 for
 * 2ms trigger.
 * @param *rxCircular UINT8 [in] - A pointer to memory allocated by the
 * client to be filled by data received. The buffer at this address is part
 * of a pool of buffers to be accessed in a circular fashion. This address
 * will be written to by the NPE. Therefore, it needs to be a physical address.
 * @param numRxBytesPerTS unsigned [in] - The number of bytes allocated per
 * timeslot within the receive memory. This figure will depend on the
 * latency of the system. It needs to be deep enough for data to be read by
 * the client before the NPE re-writes over that memory e.g. if the client
 * samples at a rate of 40bytes per timeslot, numRxBytesPerTS may need to
 * be 40bytes * 3. This would give the client 3 * 5ms of time before
 * received data is over-written.
 * @param *txPtrList UINT32 [in] - The address of an area of contiguous
 * memory allocated by the client to be populated with pointers to data for
 * transmission. Each pointer list contains a pointer per active channel.
 * The txPtrs will point to data to be transmitted by the NPE. Therefore,
 * they must point to physical addresses.
 * @param numTxPtrLists unsigned [in] - The number of pointer lists in
 * txPtrList. This figure is dependent on jitter.
 * @param numTxBytesPerBlk unsigned [in] - The size of the Tx data, in
 * bytes, that each pointer within the PtrList points to.
 * @param rxCallback @ref IxHssAccChanRxCallback [in] - A client function
 * pointer to be called back to handle the actual tx/rx of channelised
 * data. If this is not NULL, an ISR will call this function. If this
 * pointer is NULL, it implies that the client will use a polling mechanism
 * to detect when the tx and rx of channelised data is to occur. The client
 * will use hssChanAccStatus for this.
 *
 * @return
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 */
 
PUBLIC IX_STATUS 
ixHssAccChanConnect (IxHssAccHssPort hssPortId, 
		     unsigned bytesPerTSTrigger, 
		     UINT8 *rxCircular, 
		     unsigned numRxBytesPerTS, 
		     UINT32 *txPtrList, 
		     unsigned numTxPtrLists, 
		     unsigned numTxBytesPerBlk, 
		     IxHssAccChanRxCallback rxCallback);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccChanPortEnable (IxHssAccHssPort hssPortId)
 *
 * @brief This function is responsible for enabling a channelised service
 * for the specified HSS port. It enables the NPE RX flow. The client must
 * have already connected to a channelised service before enabling the
 * channelised service. No other HssAccChannelised 
 * interface should be called while this interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 *
 * @return
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 */
PUBLIC IX_STATUS 
ixHssAccChanPortEnable (IxHssAccHssPort hssPortId);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccChanPortDisable (IxHssAccHssPort hssPortId)
 *
 * @brief This function is responsible for disabling a channelised service
 * for the specified HSS port. It disables the NPE RX flow. The client must
 * have already connected to and enabled a channelised service for the
 * specified HSS port. This disable interface can be called before a
 * disconnect, but is not required to. No other HssAccChannelised 
 * interface should be called while this interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 *
 * @return 
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 */
PUBLIC IX_STATUS 
ixHssAccChanPortDisable (IxHssAccHssPort hssPortId);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccChanDisconnect (IxHssAccHssPort hssPortId)
 *
 * @brief This function allows the client to Disconnect from a channelised
 * service. If the NPE RX Flow has not been disabled, the disconnect will
 * disable it before proceeding with other disconnect functionality.
 * No other HssAccChannelised interface should be called while this 
 * interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 *
 * @return 
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 */
PUBLIC IX_STATUS 
ixHssAccChanDisconnect (IxHssAccHssPort hssPortId);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn IX_STATUS ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId, 
           BOOL *dataRecvd, 
	   unsigned *rxOffset, 
	   unsigned *txOffset, 
	   unsigned *numHssErrs)
 *
 * @brief This function is called by the client to query whether or not
 * channelised data has been received. If there is, hssChanAcc will return
 * the details in the output parameters. An enabled connection should
 * exist on the specified hssPortId before attempting to call this interface.  
 * No other HssAccChannelised interface should be called while this 
 * interface is being processed.
 *
 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 * identical ports (0-1). 
 * @param *dataRecvd BOOL [out] - This BOOL indicates to the client whether
 * or not the access component has read any data for the client. If
 * FALSE, the other output parameters will not have been written to.
 * @param *rxOffset unsigned [out] - An offset to indicate to the client
 * where within the receive buffers the NPE has just written the received
 * data to.
 * @param *txOffset unsigned [out] - An offset to indicate to the client
 * from where within the txPtrList the NPE is currently transmitting from
 * @param *numHssErrs unsigned [out] - The total number of HSS port errors
 * since initial port configuration
 *
 *
 * @return 
 *         - IX_SUCCESS The function executed successfully
 *         - IX_FAIL The function did not execute successfully
 *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 *                          parameter error
 */
PUBLIC IX_STATUS 
ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId, 
			 BOOL *dataRecvd, 
			 unsigned *rxOffset, 
			 unsigned *txOffset, 
			 unsigned *numHssErrs);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn void ixHssAccShow (void)
 *
 * @brief This function will display the current state of the IxHssAcc
 * component. The output is sent to stdout.
 *
 * @return void
 */
PUBLIC void 
ixHssAccShow (void);

/**
 *
 * @ingroup IxHssAccAPI
 *
 * @fn void ixHssAccStatsInit (void)
 *
 * @brief This function will reset the IxHssAcc statistics.
 *
 * @return void
 */
PUBLIC void 
ixHssAccStatsInit (void);

#endif /* IXHSSACC_H */

/**
 * @} defgroup IxHssAcc
 */