6 * @brief This file contains the public API of the IXP400 HSS Access
11 * IXP400 SW Release version 2.0
13 * -- Copyright Notice --
16 * Copyright 2001-2005, Intel Corporation.
17 * All rights reserved.
20 * SPDX-License-Identifier: BSD-3-Clause
22 * -- End of Copyright Notice --
25 /* ------------------------------------------------------
26 Doxygen group definitions
27 ------------------------------------------------------ */
29 * @defgroup IxHssAccAPI IXP400 HSS Access (IxHssAcc) API
31 * @brief The public API for the IXP400 HssAccess component
33 * IxHssAcc is the access layer to the HSS packetised and channelised
36 * <b> Design Notes </b><br>
38 * <LI>When a packet-pipe is configured for 56Kbps RAW mode, byte alignment of
39 * the transmitted data is not preserved. All raw data that is transmitted
40 * will be received in proper order by the receiver, but the first bit of
41 * the packet may be seen at any offset within a byte; all subsequent bytes
42 * will have the same offset for the duration of the packet. The same offset
43 * also applies to all subsequent packets received on the packet-pipe too.
44 * (Similar results will occur for data received from remote end.) While
45 * this behavior will also occur for 56Kbps HDLC mode, the HDLC
46 * encoding/decoding will preserve the original byte alignment at the
50 * <b> 56Kbps Packetised Service Bandwidth Limitation </b><br>
52 * <LI>IxHssAcc supports 56Kbps packetised service at a maximum aggregate rate
53 * for all HSS ports/HDLC channels of 12.288Mbps[1] in each direction, i.e.
54 * it supports 56Kbps packetised service on up to 8 T1 trunks. It does
55 * not support 56Kbps packetised service on 8 E1 trunks (i.e. 4 trunks per
56 * HSS port) unless those trunks are running 'fractional E1' with maximum
57 * aggregate rate of 12.288 Mbps in each direction.<br>
58 * [1] 12.288Mbps = 1.536Mbp * 8 T1
68 * #defines for function return types, etc.
72 * @def IX_HSSACC_TSLOTS_PER_HSS_PORT
74 * @brief The max number of TDM timeslots supported per HSS port - 4E1's =
77 #define IX_HSSACC_TSLOTS_PER_HSS_PORT 128
79 /* -----------------------------------------------------------
80 The following are HssAccess return values returned through
81 service interfaces. The globally defined IX_SUCCESS (0) and
82 IX_FAIL (1) in IxOsalTypes.h are also used.
83 ----------------------------------------------------------- */
85 * @def IX_HSSACC_PARAM_ERR
87 * @brief HssAccess function return value for a parameter error
89 #define IX_HSSACC_PARAM_ERR 2
92 * @def IX_HSSACC_RESOURCE_ERR
94 * @brief HssAccess function return value for a resource error
96 #define IX_HSSACC_RESOURCE_ERR 3
99 * @def IX_HSSACC_PKT_DISCONNECTING
101 * @brief Indicates that a disconnect call is progressing and will
104 #define IX_HSSACC_PKT_DISCONNECTING 4
107 * @def IX_HSSACC_Q_WRITE_OVERFLOW
109 * @brief Indicates that an attempt to Tx or to replenish an
110 * RxFree Q failed due to Q overflow.
112 #define IX_HSSACC_Q_WRITE_OVERFLOW 5
114 /* -------------------------------------------------------------------
115 The following errors are HSS/NPE errors returned on error retrieval
116 ------------------------------------------------------------------- */
118 * @def IX_HSSACC_NO_ERROR
120 * @brief HSS port no error present
122 #define IX_HSSACC_NO_ERROR 0
125 * @def IX_HSSACC_TX_FRM_SYNC_ERR
127 * @brief HSS port TX Frame Sync error
129 #define IX_HSSACC_TX_FRM_SYNC_ERR 1
132 * @def IX_HSSACC_TX_OVER_RUN_ERR
134 * @brief HSS port TX over-run error
136 #define IX_HSSACC_TX_OVER_RUN_ERR 2
139 * @def IX_HSSACC_CHANNELISED_SW_TX_ERR
141 * @brief NPE software error in channelised TX
143 #define IX_HSSACC_CHANNELISED_SW_TX_ERR 3
146 * @def IX_HSSACC_PACKETISED_SW_TX_ERR
148 * @brief NPE software error in packetised TX
150 #define IX_HSSACC_PACKETISED_SW_TX_ERR 4
153 * @def IX_HSSACC_RX_FRM_SYNC_ERR
155 * @brief HSS port RX Frame Sync error
157 #define IX_HSSACC_RX_FRM_SYNC_ERR 5
160 * @def IX_HSSACC_RX_OVER_RUN_ERR
162 * @brief HSS port RX over-run error
164 #define IX_HSSACC_RX_OVER_RUN_ERR 6
167 * @def IX_HSSACC_CHANNELISED_SW_RX_ERR
169 * @brief NPE software error in channelised RX
171 #define IX_HSSACC_CHANNELISED_SW_RX_ERR 7
174 * @def IX_HSSACC_PACKETISED_SW_RX_ERR
176 * @brief NPE software error in packetised TX
178 #define IX_HSSACC_PACKETISED_SW_RX_ERR 8
180 /* -----------------------------------
181 Packetised service specific defines
182 ----------------------------------- */
185 * @def IX_HSSACC_PKT_MIN_RX_MBUF_SIZE
187 * @brief Minimum size of the Rx mbuf in bytes which the client must supply
190 #define IX_HSSACC_PKT_MIN_RX_MBUF_SIZE 64
192 /* --------------------------------------------------------------------
193 Enumerated Types - these enumerated values may be used in setting up
194 the contents of hardware registers
195 -------------------------------------------------------------------- */
197 * @enum IxHssAccHssPort
198 * @brief The HSS port ID - There are two identical ports (0-1).
203 IX_HSSACC_HSS_PORT_0, /**< HSS Port 0 */
204 IX_HSSACC_HSS_PORT_1, /**< HSS Port 1 */
205 IX_HSSACC_HSS_PORT_MAX /**< Delimiter for error checks */
209 * @enum IxHssAccHdlcPort
210 * @brief The HDLC port ID - There are four identical HDLC ports (0-3) per
211 * HSS port and they correspond to the 4 E1/T1 trunks.
216 IX_HSSACC_HDLC_PORT_0, /**< HDLC Port 0 */
217 IX_HSSACC_HDLC_PORT_1, /**< HDLC Port 1 */
218 IX_HSSACC_HDLC_PORT_2, /**< HDLC Port 2 */
219 IX_HSSACC_HDLC_PORT_3, /**< HDLC Port 3 */
220 IX_HSSACC_HDLC_PORT_MAX /**< Delimiter for error checks */
224 * @enum IxHssAccTdmSlotUsage
225 * @brief The HSS TDM stream timeslot assignment types
230 IX_HSSACC_TDMMAP_UNASSIGNED, /**< Unassigned */
231 IX_HSSACC_TDMMAP_HDLC, /**< HDLC - packetised */
232 IX_HSSACC_TDMMAP_VOICE56K, /**< Voice56K - channelised */
233 IX_HSSACC_TDMMAP_VOICE64K, /**< Voice64K - channelised */
234 IX_HSSACC_TDMMAP_MAX /**< Delimiter for error checks */
235 } IxHssAccTdmSlotUsage;
238 * @enum IxHssAccFrmSyncType
239 * @brief The HSS frame sync pulse type
244 IX_HSSACC_FRM_SYNC_ACTIVE_LOW, /**< Frame sync is sampled low */
245 IX_HSSACC_FRM_SYNC_ACTIVE_HIGH, /**< sampled high */
246 IX_HSSACC_FRM_SYNC_FALLINGEDGE, /**< sampled on a falling edge */
247 IX_HSSACC_FRM_SYNC_RISINGEDGE, /**< sampled on a rising edge */
248 IX_HSSACC_FRM_SYNC_TYPE_MAX /**< Delimiter for error checks */
249 } IxHssAccFrmSyncType;
252 * @enum IxHssAccFrmSyncEnable
253 * @brief The IxHssAccFrmSyncEnable determines how the frame sync pulse is
258 IX_HSSACC_FRM_SYNC_INPUT, /**< Frame sync is sampled as an input */
259 IX_HSSACC_FRM_SYNC_INVALID_VALUE, /**< 1 is not used */
260 IX_HSSACC_FRM_SYNC_OUTPUT_FALLING, /**< Frame sync is an output generated
261 off a falling clock edge */
262 IX_HSSACC_FRM_SYNC_OUTPUT_RISING, /**< Frame sync is an output generated
263 off a rising clock edge */
264 IX_HSSACC_FRM_SYNC_ENABLE_MAX /**< Delimiter for error checks */
265 } IxHssAccFrmSyncEnable;
268 * @enum IxHssAccClkEdge
269 * @brief IxHssAccClkEdge is used to determine the clk edge to use for
275 IX_HSSACC_CLK_EDGE_FALLING, /**< Clock sampled off a falling edge */
276 IX_HSSACC_CLK_EDGE_RISING, /**< Clock sampled off a rising edge */
277 IX_HSSACC_CLK_EDGE_MAX /**< Delimiter for error checks */
281 * @enum IxHssAccClkDir
282 * @brief The HSS clock direction
287 IX_HSSACC_SYNC_CLK_DIR_INPUT, /**< Clock is an input */
288 IX_HSSACC_SYNC_CLK_DIR_OUTPUT, /**< Clock is an output */
289 IX_HSSACC_SYNC_CLK_DIR_MAX /**< Delimiter for error checks */
293 * @enum IxHssAccFrmPulseUsage
294 * @brief The HSS frame pulse usage
299 IX_HSSACC_FRM_PULSE_ENABLED, /**< Generate/Receive frame pulses */
300 IX_HSSACC_FRM_PULSE_DISABLED, /**< Disregard frame pulses */
301 IX_HSSACC_FRM_PULSE_MAX /**< Delimiter for error checks */
302 } IxHssAccFrmPulseUsage;
305 * @enum IxHssAccDataRate
306 * @brief The HSS Data rate in relation to the clock
311 IX_HSSACC_CLK_RATE, /**< Data rate is at the configured clk speed */
312 IX_HSSACC_HALF_CLK_RATE, /**< Data rate is half the configured clk speed */
313 IX_HSSACC_DATA_RATE_MAX /**< Delimiter for error checks */
317 * @enum IxHssAccDataPolarity
318 * @brief The HSS data polarity type
323 IX_HSSACC_DATA_POLARITY_SAME, /**< Don't invert data between NPE and
325 IX_HSSACC_DATA_POLARITY_INVERT, /**< Invert data between NPE and HSS
327 IX_HSSACC_DATA_POLARITY_MAX /**< Delimiter for error checks */
328 } IxHssAccDataPolarity;
331 * @enum IxHssAccBitEndian
332 * @brief HSS Data endianness
337 IX_HSSACC_LSB_ENDIAN, /**< TX/RX Least Significant Bit first */
338 IX_HSSACC_MSB_ENDIAN, /**< TX/RX Most Significant Bit first */
339 IX_HSSACC_ENDIAN_MAX /**< Delimiter for the purposes of error checks */
344 * @enum IxHssAccDrainMode
345 * @brief Tx pin open drain mode
350 IX_HSSACC_TX_PINS_NORMAL, /**< Normal mode */
351 IX_HSSACC_TX_PINS_OPEN_DRAIN, /**< Open Drain mode */
352 IX_HSSACC_TX_PINS_MAX /**< Delimiter for error checks */
356 * @enum IxHssAccSOFType
357 * @brief HSS start of frame types
362 IX_HSSACC_SOF_FBIT, /**< Framing bit transmitted and expected on rx */
363 IX_HSSACC_SOF_DATA, /**< Framing bit not transmitted nor expected on rx */
364 IX_HSSACC_SOF_MAX /**< Delimiter for error checks */
368 * @enum IxHssAccDataEnable
369 * @brief IxHssAccDataEnable is used to determine whether or not to drive
375 IX_HSSACC_DE_TRI_STATE, /**< TRI-State the data pins */
376 IX_HSSACC_DE_DATA, /**< Push data out the data pins */
377 IX_HSSACC_DE_MAX /**< Delimiter for error checks */
378 } IxHssAccDataEnable;
381 * @enum IxHssAccTxSigType
382 * @brief IxHssAccTxSigType is used to determine how to drive the data pins
387 IX_HSSACC_TXSIG_LOW, /**< Drive the data pins low */
388 IX_HSSACC_TXSIG_HIGH, /**< Drive the data pins high */
389 IX_HSSACC_TXSIG_HIGH_IMP, /**< Drive the data pins with high impedance */
390 IX_HSSACC_TXSIG_MAX /**< Delimiter for error checks */
394 * @enum IxHssAccFbType
395 * @brief IxHssAccFbType determines how to drive the Fbit
397 * @warning This will only be used for T1 @ 1.544MHz
402 IX_HSSACC_FB_FIFO, /**< Fbit is dictated in FIFO */
403 IX_HSSACC_FB_HIGH_IMP, /**< Fbit is high impedance */
404 IX_HSSACC_FB_MAX /**< Delimiter for error checks */
408 * @enum IxHssAcc56kEndianness
409 * @brief 56k data endianness when using the 56k type
414 IX_HSSACC_56KE_BIT_7_UNUSED, /**< High bit is unused */
415 IX_HSSACC_56KE_BIT_0_UNUSED, /**< Low bit is unused */
416 IX_HSSACC_56KE_MAX /**< Delimiter for error checks */
417 } IxHssAcc56kEndianness;
420 * @enum IxHssAcc56kSel
421 * @brief 56k data transmission type when using the 56k type
426 IX_HSSACC_56KS_32_8_DATA, /**< 32/8 bit data */
427 IX_HSSACC_56KS_56K_DATA, /**< 56K data */
428 IX_HSSACC_56KS_MAX /**< Delimiter for error checks */
433 * @enum IxHssAccClkSpeed
434 * @brief IxHssAccClkSpeed represents the HSS clock speeds available
439 IX_HSSACC_CLK_SPEED_512KHZ, /**< 512KHz */
440 IX_HSSACC_CLK_SPEED_1536KHZ, /**< 1.536MHz */
441 IX_HSSACC_CLK_SPEED_1544KHZ, /**< 1.544MHz */
442 IX_HSSACC_CLK_SPEED_2048KHZ, /**< 2.048MHz */
443 IX_HSSACC_CLK_SPEED_4096KHZ, /**< 4.096MHz */
444 IX_HSSACC_CLK_SPEED_8192KHZ, /**< 8.192MHz */
445 IX_HSSACC_CLK_SPEED_MAX /**< Delimiter for error checking */
449 * @enum IxHssAccPktStatus
450 * @brief Indicates the status of packets passed to the client
455 IX_HSSACC_PKT_OK, /**< Error free.*/
456 IX_HSSACC_STOP_SHUTDOWN_ERROR, /**< Errored due to stop or shutdown
458 IX_HSSACC_HDLC_ALN_ERROR, /**< HDLC alignment error */
459 IX_HSSACC_HDLC_FCS_ERROR, /**< HDLC Frame Check Sum error.*/
460 IX_HSSACC_RXFREE_Q_EMPTY_ERROR, /**< RxFree Q became empty
461 while receiving this packet.*/
462 IX_HSSACC_HDLC_MAX_FRAME_SIZE_EXCEEDED, /**< HDLC frame size
463 received is greater than
464 max specified at connect.*/
465 IX_HSSACC_HDLC_ABORT_ERROR, /**< HDLC frame received is invalid due to an
466 abort sequence received.*/
467 IX_HSSACC_DISCONNECT_IN_PROGRESS /**< Packet returned
468 because a disconnect is in progress */
473 * @enum IxHssAccPktCrcType
474 * @brief HDLC CRC type
479 IX_HSSACC_PKT_16_BIT_CRC = 16, /**< 16 bit CRC is being used */
480 IX_HSSACC_PKT_32_BIT_CRC = 32 /**< 32 bit CRC is being used */
481 } IxHssAccPktCrcType;
484 * @enum IxHssAccPktHdlcIdleType
485 * @brief HDLC idle transmission type
490 IX_HSSACC_HDLC_IDLE_ONES, /**< idle tx/rx will be a succession of ones */
491 IX_HSSACC_HDLC_IDLE_FLAGS /**< idle tx/rx will be repeated flags */
492 } IxHssAccPktHdlcIdleType;
495 * @brief Structure containing HSS port configuration parameters
497 * Note: All of these are used for TX. Only some are specific to RX.
502 IxHssAccFrmSyncType frmSyncType; /**< frame sync pulse type (tx/rx) */
503 IxHssAccFrmSyncEnable frmSyncIO; /**< how the frame sync pulse is
505 IxHssAccClkEdge frmSyncClkEdge; /**< frame sync clock edge type
507 IxHssAccClkEdge dataClkEdge; /**< data clock edge type (tx/rx) */
508 IxHssAccClkDir clkDirection; /**< clock direction (tx/rx) */
509 IxHssAccFrmPulseUsage frmPulseUsage; /**< whether to use the frame sync
510 pulse or not (tx/rx) */
511 IxHssAccDataRate dataRate; /**< data rate in relation to the
513 IxHssAccDataPolarity dataPolarity; /**< data polarity type (tx/rx) */
514 IxHssAccBitEndian dataEndianness; /**< data endianness (tx/rx) */
515 IxHssAccDrainMode drainMode; /**< tx pin open drain mode (tx) */
516 IxHssAccSOFType fBitUsage; /**< start of frame types (tx/rx) */
517 IxHssAccDataEnable dataEnable; /**< whether or not to drive the data
519 IxHssAccTxSigType voice56kType; /**< how to drive the data pins for
520 voice56k type (tx) */
521 IxHssAccTxSigType unassignedType; /**< how to drive the data pins for
522 unassigned type (tx) */
523 IxHssAccFbType fBitType; /**< how to drive the Fbit (tx) */
524 IxHssAcc56kEndianness voice56kEndian;/**< 56k data endianness when using
526 IxHssAcc56kSel voice56kSel; /**< 56k data transmission type when
527 using the 56k type (tx) */
528 unsigned frmOffset; /**< frame pulse offset in bits wrt
529 the first timeslot (0-1023) (tx/rx) */
530 unsigned maxFrmSize; /**< frame size in bits (1-1024)
532 } IxHssAccPortConfig;
535 * @brief Structure containing HSS configuration parameters
540 IxHssAccPortConfig txPortConfig; /**< HSS tx port configuration */
541 IxHssAccPortConfig rxPortConfig; /**< HSS rx port configuration */
542 unsigned numChannelised; /**< The number of channelised
544 unsigned hssPktChannelCount; /**< The number of packetised
546 UINT8 channelisedIdlePattern; /**< The byte to be transmitted on
547 channelised service when there
548 is no client data to tx */
549 BOOL loopback; /**< The HSS loopback state */
550 unsigned packetizedIdlePattern; /**< The data to be transmitted on
551 packetised service when there is
552 no client data to tx */
553 IxHssAccClkSpeed clkSpeed; /**< The HSS clock speed */
554 } IxHssAccConfigParams;
557 * @brief This structure contains 56Kbps, HDLC-mode configuration parameters
562 BOOL hdlc56kMode; /**< 56kbps(true)/64kbps(false) HDLC */
563 IxHssAcc56kEndianness hdlc56kEndian; /**< 56kbps data endianness
564 - ignored if hdlc56kMode is false*/
565 BOOL hdlc56kUnusedBitPolarity0; /**< The polarity '0'(true)/'1'(false) of the unused
566 bit while in 56kbps mode
567 - ignored if hdlc56kMode is false*/
571 * @brief This structure contains information required by the NPE to
572 * configure the HDLC co-processor
577 IxHssAccPktHdlcIdleType hdlcIdleType; /**< What to transmit when a HDLC port is idle */
578 IxHssAccBitEndian dataEndian; /**< The HDLC data endianness */
579 IxHssAccPktCrcType crcType; /**< The CRC type to be used for this HDLC port */
580 } IxHssAccPktHdlcFraming;
583 * @typedef UINT32 IxHssAccPktUserId
585 * @brief The client supplied value which will be supplied as a parameter
586 * with a given callback.
588 * This value will be passed into the ixHssAccPktPortConnect function once each
589 * with given callbacks. This value will then be passed back to the client
590 * as one of the parameters to each of these callbacks,
591 * when these callbacks are called.
593 typedef UINT32 IxHssAccPktUserId;
597 * @typedef IxHssAccLastErrorCallback
598 * @brief Prototype of the clients function to accept notification of the
601 * This function is registered through the config. The client will initiate
602 * the last error retrieval. The HssAccess component will send a message to
603 * the NPE through the NPE Message Handler. When a response to the read is
604 * received, the NPE Message Handler will callback the HssAccess component
605 * which will execute this function in the same IxNpeMh context. The client
606 * will be passed the last error and the related service port (packetised
607 * 0-3, channelised 0)
609 * @param lastHssError unsigned [in] - The last Hss error registered that
610 * has been registered.
611 * @param servicePort unsigned [in] - This is the service port number.
612 * (packetised 0-3, channelised 0)
616 typedef void (*IxHssAccLastErrorCallback) (unsigned lastHssError,
617 unsigned servicePort);
620 * @typedef IxHssAccPktRxCallback
621 * @brief Prototype of the clients function to accept notification of
624 * This function is registered through the ixHssAccPktPortConnect. hssPktAcc will pass
625 * received data in the form of mbufs to the client. The mbuf passed back
626 * to the client could contain a chain of buffers, depending on the packet
629 * @param *buffer @ref IX_OSAL_MBUF [in] - This is the mbuf which contains the
631 * @param numHssErrs unsigned [in] - This is the number of hssErrors
632 * the Npe has received
633 * @param pktStatus @ref IxHssAccPktStatus [in] - This is the status of the
634 * mbuf that has been received.
635 * @param rxUserId @ref IxHssAccPktUserId [in] - This is the client supplied value
636 * passed in at ixHssAccPktPortConnect time which is now returned to the client.
640 typedef void (*IxHssAccPktRxCallback) (IX_OSAL_MBUF *buffer,
642 IxHssAccPktStatus pktStatus,
643 IxHssAccPktUserId rxUserId);
646 * @typedef IxHssAccPktRxFreeLowCallback
647 * @brief Prototype of the clients function to accept notification of
648 * requirement of more Rx Free buffers
650 * The client can choose to register a callback of this type when
651 * calling a connecting. This function is registered through the ixHssAccPktPortConnect.
652 * If defined, the access layer will provide the trigger for
653 * this callback. The callback will be responsible for supplying mbufs to
654 * the access layer for use on the receive path from the HSS using
655 * ixHssPktAccFreeBufReplenish.
659 typedef void (*IxHssAccPktRxFreeLowCallback) (IxHssAccPktUserId rxFreeLowUserId);
662 * @typedef IxHssAccPktTxDoneCallback
663 * @brief Prototype of the clients function to accept notification of
664 * completion with Tx buffers
666 * This function is registered through the ixHssAccPktPortConnect. It enables
667 * the hssPktAcc to pass buffers back to the client
668 * when transmission is complete.
670 * @param *buffer @ref IX_OSAL_MBUF [in] - This is the mbuf which contained
671 * the payload that was for Tx.
672 * @param numHssErrs unsigned [in] - This is the number of hssErrors
673 * the Npe has received
674 * @param pktStatus @ref IxHssAccPktStatus [in] - This is the status of the
675 * mbuf that has been transmitted.
676 * @param txDoneUserId @ref IxHssAccPktUserId [in] - This is the client supplied value
677 * passed in at ixHssAccPktPortConnect time which is now returned to the client.
681 typedef void (*IxHssAccPktTxDoneCallback) (IX_OSAL_MBUF *buffer,
683 IxHssAccPktStatus pktStatus,
684 IxHssAccPktUserId txDoneUserId);
687 * @typedef IxHssAccChanRxCallback
688 * @brief Prototype of the clients function to accept notification of
691 * This callback, if defined by the client in the connect, will get called
692 * in the context of an IRQ. The IRQ will be triggered when the hssSyncQMQ
693 * is not empty. The queued entry will be dequeued and this function will
696 * @param hssPortId @ref IxHssAccHssPort - The HSS port Id. There are two
697 * identical ports (0-1).
698 * @param txOffset unsigned [in] - an offset indicating from where within
699 * the txPtrList the NPE is currently transmitting from.
700 * @param rxOffset unsigned [in] - an offset indicating where within the
701 * receive buffers the NPE has just written the received data to.
702 * @param numHssErrs unsigned [in] - This is the number of hssErrors
703 * the Npe has received
707 typedef void (*IxHssAccChanRxCallback) (IxHssAccHssPort hssPortId,
710 unsigned numHssErrs);
713 * Prototypes for interface functions.
718 * @ingroup IxHssAccAPI
720 * @fn IX_STATUS ixHssAccPortInit (IxHssAccHssPort hssPortId,
721 IxHssAccConfigParams *configParams,
722 IxHssAccTdmSlotUsage *tdmMap,
723 IxHssAccLastErrorCallback lastHssErrorCallback)
725 * @brief Initialise a HSS port. No channelised or packetised connections
726 * should exist in the HssAccess layer while this interface is being called.
728 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
729 * identical ports (0-1).
730 * @param *configParams @ref IxHssAccConfigParams [in] - A pointer to the HSS
731 * configuration structure
732 * @param *tdmMap @ref IxHssAccTdmSlotUsage [in] - A pointer to an array of size
733 * IX_HSSACC_TSLOTS_PER_HSS_PORT, defining the slot usage over the HSS port
734 * @param lastHssErrorCallback @ref IxHssAccLastErrorCallback [in] - Client
735 * callback to report last error
738 * - IX_SUCCESS The function executed successfully
739 * - IX_FAIL The function did not execute successfully
740 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
744 ixHssAccPortInit (IxHssAccHssPort hssPortId,
745 IxHssAccConfigParams *configParams,
746 IxHssAccTdmSlotUsage *tdmMap,
747 IxHssAccLastErrorCallback lastHssErrorCallback);
751 * @ingroup IxHssAccAPI
753 * @fn IX_STATUS ixHssAccLastErrorRetrievalInitiate (
754 IxHssAccHssPort hssPortId)
756 * @brief Initiate the retrieval of the last HSS error. The HSS port
757 * should be configured before attempting to call this interface.
759 * @param hssPortId @ref IxHssAccHssPort [in] - the HSS port ID
762 * - IX_SUCCESS The function executed successfully
763 * - IX_FAIL The function did not execute successfully
764 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
768 ixHssAccLastErrorRetrievalInitiate (IxHssAccHssPort hssPortId);
773 * @ingroup IxHssAccAPI
775 * @fn IX_STATUS ixHssAccInit ()
777 * @brief This function is responsible for initialising resources for use
778 * by the packetised and channelised clients. It should be called after
779 * HSS NPE image has been downloaded into NPE-A and before any other
780 * HssAccess interface is called.
781 * No other HssAccPacketised interface should be called while this interface
782 * is being processed.
785 * - IX_SUCCESS The function executed successfully
786 * - IX_FAIL The function did not execute successfully
787 * - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
788 * to a resource error
796 * @ingroup IxHssAccAPI
798 * @fn ixHssAccPktPortConnect (IxHssAccHssPort hssPortId,
799 IxHssAccHdlcPort hdlcPortId,
801 IxHssAccHdlcMode hdlcMode,
803 unsigned blockSizeInWords,
804 UINT32 rawIdleBlockPattern,
805 IxHssAccPktHdlcFraming hdlcTxFraming,
806 IxHssAccPktHdlcFraming hdlcRxFraming,
807 unsigned frmFlagStart,
808 IxHssAccPktRxCallback rxCallback,
809 IxHssAccPktUserId rxUserId,
810 IxHssAccPktRxFreeLowCallback rxFreeLowCallback,
811 IxHssAccPktUserId rxFreeLowUserId,
812 IxHssAccPktTxDoneCallback txDoneCallback,
813 IxHssAccPktUserId txDoneUserId)
815 * @brief This function is responsible for connecting a client to one of
816 * the 4 available HDLC ports. The HSS port should be configured before
817 * attempting a connect. No other HssAccPacketised interface should be
818 * called while this connect is being processed.
820 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
821 * identical ports (0-1).
822 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port and
823 * it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
824 * @param hdlcFraming BOOL [in] - This value determines whether the service
825 * will use HDLC data or the debug, raw data type i.e. no HDLC processing
826 * @param hdlcMode @ref IxHssAccHdlcMode [in] - This structure contains 56Kbps, HDLC-mode
827 * configuration parameters
828 * @param hdlcBitInvert BOOL [in] - This value determines whether bit inversion
829 * will occur between HDLC and HSS co-processors i.e. post-HDLC processing for
830 * transmit and pre-HDLC processing for receive, for the specified HDLC Termination
832 * @param blockSizeInWords unsigned [in] - The max tx/rx block size
833 * @param rawIdleBlockPattern UINT32 [in] - Tx idle pattern in raw mode
834 * @param hdlcTxFraming @ref IxHssAccPktHdlcFraming [in] - This structure contains
835 * the following information required by the NPE to configure the HDLC
836 * co-processor for TX
837 * @param hdlcRxFraming @ref IxHssAccPktHdlcFraming [in] - This structure contains
838 * the following information required by the NPE to configure the HDLC
839 * co-processor for RX
840 * @param frmFlagStart unsigned - Number of flags to precede to
841 * transmitted flags (0-2).
842 * @param rxCallback @ref IxHssAccPktRxCallback [in] - Pointer to
843 * the clients packet receive function.
844 * @param rxUserId @ref IxHssAccPktUserId [in] - The client supplied rx value
845 * to be passed back as an argument to the supplied rxCallback
846 * @param rxFreeLowCallback @ref IxHssAccPktRxFreeLowCallback [in] - Pointer to
847 * the clients Rx free buffer request function. If NULL, assume client will
848 * trigger independently.
849 * @param rxFreeLowUserId @ref IxHssAccPktUserId [in] - The client supplied RxFreeLow value
850 * to be passed back as an argument to the supplied rxFreeLowCallback
851 * @param txDoneCallback @ref IxHssAccPktTxDoneCallback [in] - Pointer to the
852 * clients Tx done callback function
853 * @param txDoneUserId @ref IxHssAccPktUserId [in] - The client supplied txDone value
854 * to be passed back as an argument to the supplied txDoneCallback
857 * - IX_SUCCESS The function executed successfully
858 * - IX_FAIL The function did not execute successfully
859 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
861 * - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
862 * to a resource error
865 ixHssAccPktPortConnect (IxHssAccHssPort hssPortId,
866 IxHssAccHdlcPort hdlcPortId,
868 IxHssAccHdlcMode hdlcMode,
870 unsigned blockSizeInWords,
871 UINT32 rawIdleBlockPattern,
872 IxHssAccPktHdlcFraming hdlcTxFraming,
873 IxHssAccPktHdlcFraming hdlcRxFraming,
874 unsigned frmFlagStart,
875 IxHssAccPktRxCallback rxCallback,
876 IxHssAccPktUserId rxUserId,
877 IxHssAccPktRxFreeLowCallback rxFreeLowCallback,
878 IxHssAccPktUserId rxFreeLowUserId,
879 IxHssAccPktTxDoneCallback txDoneCallback,
880 IxHssAccPktUserId txDoneUserId);
884 * @ingroup IxHssAccAPI
886 * @fn IX_STATUS ixHssAccPktPortEnable (IxHssAccHssPort hssPortId,
887 IxHssAccHdlcPort hdlcPortId)
889 * @brief This function is responsible for enabling a packetised service
890 * for the specified HSS/HDLC port combination. It enables the RX flow. The
891 * client must have already connected to a packetised service and is responsible
892 * for ensuring an adequate amount of RX mbufs have been supplied to the access
893 * component before enabling the packetised service. This function must be called
894 * on a given port before any call to ixHssAccPktPortTx on the same port.
895 * No other HssAccPacketised interface should be called while this interface is
898 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
899 * identical ports (0-1).
900 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - The port id (0,1,2,3) to enable the service
904 * - IX_SUCCESS The function executed successfully
905 * - IX_FAIL The function did not execute successfully
906 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
910 ixHssAccPktPortEnable (IxHssAccHssPort hssPortId,
911 IxHssAccHdlcPort hdlcPortId);
914 * @fn IX_STATUS ixHssAccPktPortDisable (IxHssAccHssPort hssPortId,
915 IxHssAccHdlcPort hdlcPortId)
917 * @brief This function is responsible for disabling a packetised service
918 * for the specified HSS/HDLC port combination. It disables the RX flow.
919 * The client must have already connected to and enabled a packetised service
920 * for the specified HDLC port. This disable interface can be called before a
921 * disconnect, but is not required to.
923 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
924 * identical ports (0-1).
925 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - The port id (0,1,2,3) to disable
929 * - IX_SUCCESS The function executed successfully
930 * - IX_FAIL The function did not execute successfully
931 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
935 ixHssAccPktPortDisable (IxHssAccHssPort hssPortId,
936 IxHssAccHdlcPort hdlcPortId);
940 * @ingroup IxHssAccAPI
942 * @fn IX_STATUS ixHssAccPktPortDisconnect (IxHssAccHssPort hssPortId,
943 IxHssAccHdlcPort hdlcPortId)
945 * @brief This function is responsible for disconnecting a client from one
946 * of the 4 available HDLC ports. It is not required that the Rx Flow
947 * has been disabled before calling this function. If the RX Flow has not been
948 * disabled, the disconnect will disable it before proceeding with the
949 * disconnect. No other HssAccPacketised
950 * interface should be called while this interface is being processed.
952 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
953 * identical ports (0-1).
954 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
955 * to disconnect and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
958 * - IX_SUCCESS The function executed successfully
959 * - IX_FAIL The function did not execute successfully
960 * - IX_HSSACC_PKT_DISCONNECTING The function has initiated the disconnecting
961 * procedure but it has not completed yet.
964 ixHssAccPktPortDisconnect (IxHssAccHssPort hssPortId,
965 IxHssAccHdlcPort hdlcPortId);
969 * @ingroup IxHssAccAPI
971 * @fn BOOL ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId,
972 IxHssAccHdlcPort hdlcPortId)
974 * @brief This function is called to check if a given HSS/HDLC port
975 * combination is in a connected state or not. This function may be called
976 * at any time to determine a ports state. No other HssAccPacketised
977 * interface should be called while this interface is being processed.
979 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
980 * identical ports (0-1).
981 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
982 * to disconnect and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
985 * - true The state of this HSS/HDLC port combination is disconnected,
986 * so if a disconnect was called, it is now completed.
987 * - false The state of this HSS/HDLC port combination is connected,
988 * so if a disconnect was called, it is not yet completed.
991 ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId,
992 IxHssAccHdlcPort hdlcPortId);
997 * @ingroup IxHssAccAPI
999 * @fn IX_STATUS ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId,
1000 IxHssAccHdlcPort hdlcPortId,
1001 IX_OSAL_MBUF *buffer)
1003 * @brief Function which the client calls at regular intervals to provide
1004 * mbufs to the access component for RX. A connection should exist for
1005 * the specified hssPortId/hdlcPortId combination before attempting to call this
1006 * interface. Also, the connection should not be in a disconnecting state.
1008 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1009 * identical ports (0-1).
1010 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
1011 * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
1012 * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a free mbuf to filled with payload.
1015 * - IX_SUCCESS The function executed successfully
1016 * - IX_FAIL The function did not execute successfully
1017 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1019 * - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
1020 * to a resource error
1021 * - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
1025 ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId,
1026 IxHssAccHdlcPort hdlcPortId,
1027 IX_OSAL_MBUF *buffer);
1031 * @ingroup IxHssAccAPI
1033 * @fn IX_STATUS ixHssAccPktPortTx (IxHssAccHssPort hssPortId,
1034 IxHssAccHdlcPort hdlcPortId,
1035 IX_OSAL_MBUF *buffer)
1037 * @brief Function which the client calls when it wants to transmit
1038 * packetised data. An enabled connection should exist on the specified
1039 * hssPortId/hdlcPortId combination before attempting to call this interface.
1040 * No other HssAccPacketised
1041 * interface should be called while this interface is being processed.
1043 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1044 * identical ports (0-1).
1045 * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
1046 * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
1047 * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a chain of mbufs which the
1048 * client has filled with the payload
1051 * - IX_SUCCESS The function executed successfully
1052 * - IX_FAIL The function did not execute successfully
1053 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1055 * - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
1056 * to a resource error. See note.
1057 * - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
1060 * @note IX_HSSACC_RESOURCE_ERR is returned when a free descriptor cannot be
1061 * obtained to send the chain of mbufs to the NPE. This is a normal scenario.
1062 * HssAcc has a pool of descriptors and this error means that they are currently
1064 * The recommended approach to this is to retry until a descriptor becomes free
1065 * and the packet is successfully transmitted.
1066 * Alternatively, the user could wait until the next IxHssAccPktTxDoneCallback
1067 * callback is triggered, and then retry, as it is this event that causes a
1068 * transmit descriptor to be freed.
1071 ixHssAccPktPortTx (IxHssAccHssPort hssPortId,
1072 IxHssAccHdlcPort hdlcPortId,
1073 IX_OSAL_MBUF *buffer);
1077 * @ingroup IxHssAccAPI
1079 * @fn IX_STATUS ixHssAccChanConnect (IxHssAccHssPort hssPortId,
1080 unsigned bytesPerTSTrigger,
1082 unsigned numRxBytesPerTS,
1084 unsigned numTxPtrLists,
1085 unsigned numTxBytesPerBlk,
1086 IxHssAccChanRxCallback rxCallback)
1088 * @brief This function allows the client to connect to the Tx/Rx NPE
1089 * Channelised Service. There can only be one client per HSS port. The
1090 * client is responsible for ensuring that the HSS port is configured
1091 * appropriately before its connect request. No other HssAccChannelised
1092 * interface should be called while this interface is being processed.
1094 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1095 * identical ports (0-1).
1096 * @param bytesPerTSTrigger unsigned [in] - The NPE will trigger the access
1097 * component after bytesPerTSTrigger have been received for all trunk
1098 * timeslots. This figure is a multiple of 8 e.g. 8 for 1ms trigger, 16 for
1100 * @param *rxCircular UINT8 [in] - A pointer to memory allocated by the
1101 * client to be filled by data received. The buffer at this address is part
1102 * of a pool of buffers to be accessed in a circular fashion. This address
1103 * will be written to by the NPE. Therefore, it needs to be a physical address.
1104 * @param numRxBytesPerTS unsigned [in] - The number of bytes allocated per
1105 * timeslot within the receive memory. This figure will depend on the
1106 * latency of the system. It needs to be deep enough for data to be read by
1107 * the client before the NPE re-writes over that memory e.g. if the client
1108 * samples at a rate of 40bytes per timeslot, numRxBytesPerTS may need to
1109 * be 40bytes * 3. This would give the client 3 * 5ms of time before
1110 * received data is over-written.
1111 * @param *txPtrList UINT32 [in] - The address of an area of contiguous
1112 * memory allocated by the client to be populated with pointers to data for
1113 * transmission. Each pointer list contains a pointer per active channel.
1114 * The txPtrs will point to data to be transmitted by the NPE. Therefore,
1115 * they must point to physical addresses.
1116 * @param numTxPtrLists unsigned [in] - The number of pointer lists in
1117 * txPtrList. This figure is dependent on jitter.
1118 * @param numTxBytesPerBlk unsigned [in] - The size of the Tx data, in
1119 * bytes, that each pointer within the PtrList points to.
1120 * @param rxCallback @ref IxHssAccChanRxCallback [in] - A client function
1121 * pointer to be called back to handle the actual tx/rx of channelised
1122 * data. If this is not NULL, an ISR will call this function. If this
1123 * pointer is NULL, it implies that the client will use a polling mechanism
1124 * to detect when the tx and rx of channelised data is to occur. The client
1125 * will use hssChanAccStatus for this.
1128 * - IX_SUCCESS The function executed successfully
1129 * - IX_FAIL The function did not execute successfully
1130 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1135 ixHssAccChanConnect (IxHssAccHssPort hssPortId,
1136 unsigned bytesPerTSTrigger,
1138 unsigned numRxBytesPerTS,
1140 unsigned numTxPtrLists,
1141 unsigned numTxBytesPerBlk,
1142 IxHssAccChanRxCallback rxCallback);
1146 * @ingroup IxHssAccAPI
1148 * @fn IX_STATUS ixHssAccChanPortEnable (IxHssAccHssPort hssPortId)
1150 * @brief This function is responsible for enabling a channelised service
1151 * for the specified HSS port. It enables the NPE RX flow. The client must
1152 * have already connected to a channelised service before enabling the
1153 * channelised service. No other HssAccChannelised
1154 * interface should be called while this interface is being processed.
1156 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1157 * identical ports (0-1).
1160 * - IX_SUCCESS The function executed successfully
1161 * - IX_FAIL The function did not execute successfully
1162 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1166 ixHssAccChanPortEnable (IxHssAccHssPort hssPortId);
1170 * @ingroup IxHssAccAPI
1172 * @fn IX_STATUS ixHssAccChanPortDisable (IxHssAccHssPort hssPortId)
1174 * @brief This function is responsible for disabling a channelised service
1175 * for the specified HSS port. It disables the NPE RX flow. The client must
1176 * have already connected to and enabled a channelised service for the
1177 * specified HSS port. This disable interface can be called before a
1178 * disconnect, but is not required to. No other HssAccChannelised
1179 * interface should be called while this interface is being processed.
1181 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1182 * identical ports (0-1).
1185 * - IX_SUCCESS The function executed successfully
1186 * - IX_FAIL The function did not execute successfully
1187 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1191 ixHssAccChanPortDisable (IxHssAccHssPort hssPortId);
1195 * @ingroup IxHssAccAPI
1197 * @fn IX_STATUS ixHssAccChanDisconnect (IxHssAccHssPort hssPortId)
1199 * @brief This function allows the client to Disconnect from a channelised
1200 * service. If the NPE RX Flow has not been disabled, the disconnect will
1201 * disable it before proceeding with other disconnect functionality.
1202 * No other HssAccChannelised interface should be called while this
1203 * interface is being processed.
1205 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1206 * identical ports (0-1).
1209 * - IX_SUCCESS The function executed successfully
1210 * - IX_FAIL The function did not execute successfully
1211 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1215 ixHssAccChanDisconnect (IxHssAccHssPort hssPortId);
1219 * @ingroup IxHssAccAPI
1221 * @fn IX_STATUS ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId,
1225 unsigned *numHssErrs)
1227 * @brief This function is called by the client to query whether or not
1228 * channelised data has been received. If there is, hssChanAcc will return
1229 * the details in the output parameters. An enabled connection should
1230 * exist on the specified hssPortId before attempting to call this interface.
1231 * No other HssAccChannelised interface should be called while this
1232 * interface is being processed.
1234 * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1235 * identical ports (0-1).
1236 * @param *dataRecvd BOOL [out] - This BOOL indicates to the client whether
1237 * or not the access component has read any data for the client. If
1238 * false, the other output parameters will not have been written to.
1239 * @param *rxOffset unsigned [out] - An offset to indicate to the client
1240 * where within the receive buffers the NPE has just written the received
1242 * @param *txOffset unsigned [out] - An offset to indicate to the client
1243 * from where within the txPtrList the NPE is currently transmitting from
1244 * @param *numHssErrs unsigned [out] - The total number of HSS port errors
1245 * since initial port configuration
1249 * - IX_SUCCESS The function executed successfully
1250 * - IX_FAIL The function did not execute successfully
1251 * - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1255 ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId,
1259 unsigned *numHssErrs);
1263 * @ingroup IxHssAccAPI
1265 * @fn void ixHssAccShow (void)
1267 * @brief This function will display the current state of the IxHssAcc
1268 * component. The output is sent to stdout.
1273 ixHssAccShow (void);
1277 * @ingroup IxHssAccAPI
1279 * @fn void ixHssAccStatsInit (void)
1281 * @brief This function will reset the IxHssAcc statistics.
1286 ixHssAccStatsInit (void);
1288 #endif /* IXHSSACC_H */
1291 * @} defgroup IxHssAcc