drivers/net/npe/include/IxHssAcc.h

   1 /**
   2  * @file IxHssAcc.h
   3  *
   4  * @date 07-DEC-2001
   5  *
   6  * @brief This file contains the public API of the IXP400 HSS Access
   7  * component
   8  *
   9  *
  10  * @par
  11  * IXP400 SW Release version 2.0
  12  *
  13  * -- Copyright Notice --
  14  *
  15  * @par
  16  * Copyright 2001-2005, Intel Corporation.
  17  * All rights reserved.
  18  *
  19  * @par
  20  * Redistribution and use in source and binary forms, with or without
  21  * modification, are permitted provided that the following conditions
  22  * are met:
  23  * 1. Redistributions of source code must retain the above copyright
  24  *    notice, this list of conditions and the following disclaimer.
  25  * 2. Redistributions in binary form must reproduce the above copyright
  26  *    notice, this list of conditions and the following disclaimer in the
  27  *    documentation and/or other materials provided with the distribution.
  28  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  29  *    may be used to endorse or promote products derived from this software
  30  *    without specific prior written permission.
  31  *
  32  * @par
  33  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  34  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  35  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  36  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  37  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  38  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  39  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  40  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  41  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  42  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  43  * SUCH DAMAGE.
  44  *
  45  * @par
  46  * -- End of Copyright Notice --
  47 */
  48
  49 /* ------------------------------------------------------
  50    Doxygen group definitions
  51    ------------------------------------------------------ */
  52 /**
  53  * @defgroup IxHssAccAPI IXP400 HSS Access (IxHssAcc) API
  54  *
  55  * @brief The public API for the IXP400 HssAccess component
  56  *
  57  * IxHssAcc is the access layer to the HSS packetised and channelised
  58  * services
  59  *
  60  * <b> Design Notes </b><br>
  61  * <UL>
  62  * <LI>When a packet-pipe is configured for 56Kbps RAW mode, byte alignment of
  63  *     the transmitted data is not preserved. All raw data that is transmitted
  64  *     will be received in proper order by the receiver, but the first bit of
  65  *     the packet may be seen at any offset within a byte; all subsequent bytes
  66  *     will have the same offset for the duration of the packet. The same offset
  67  *     also applies to all subsequent packets received on the packet-pipe too.
  68  *     (Similar results will occur for data received from remote end.) While
  69  *     this behavior will also occur for 56Kbps HDLC mode, the HDLC
  70  *     encoding/decoding will preserve the original byte alignment at the
  71  *     receiver end.
  72  * </UL>
  73  *
  74  * <b> 56Kbps Packetised Service Bandwidth Limitation </b><br>
  75  * <UL>
  76  * <LI>IxHssAcc supports 56Kbps packetised service at a maximum aggregate rate
  77  *     for all HSS ports/HDLC channels of 12.288Mbps[1] in each direction, i.e.
  78  *     it supports 56Kbps packetised service on up to 8 T1 trunks. It does
  79  *     not support 56Kbps packetised service on 8 E1 trunks (i.e. 4 trunks per
  80  *     HSS port) unless those trunks are running 'fractional E1' with maximum
  81  *     aggregate rate of 12.288 Mbps in each direction.<br>
  82  *     [1] 12.288Mbps = 1.536Mbp * 8 T1
  83  * </UL>
  84  * @{ */
  85
  86 #ifndef IXHSSACC_H
  87 #define IXHSSACC_H
  88
  89 #include "IxOsal.h"
  90
  91 /*
  92  * #defines for function return types, etc.
  93  */
  94
  95 /**
  96  * @def IX_HSSACC_TSLOTS_PER_HSS_PORT
  97  *
  98  * @brief The max number of TDM timeslots supported per HSS port - 4E1's =
  99  *  32x4 = 128
 100  */
 101 #define IX_HSSACC_TSLOTS_PER_HSS_PORT 128
 102
 103 /* -----------------------------------------------------------
 104    The following are HssAccess return values returned through
 105    service interfaces. The globally defined IX_SUCCESS (0) and
 106    IX_FAIL (1) in IxOsalTypes.h are also used.
 107    ----------------------------------------------------------- */
 108 /**
 109  * @def IX_HSSACC_PARAM_ERR
 110  *
 111  * @brief HssAccess function return value for a parameter error
 112  */
 113 #define IX_HSSACC_PARAM_ERR 2
 114
 115 /**
 116  * @def IX_HSSACC_RESOURCE_ERR
 117  *
 118  * @brief HssAccess function return value for a resource error
 119  */
 120 #define IX_HSSACC_RESOURCE_ERR 3
 121
 122 /**
 123  * @def IX_HSSACC_PKT_DISCONNECTING
 124  *
 125  * @brief Indicates that a disconnect call is progressing and will
 126  * disconnect soon
 127  */
 128 #define IX_HSSACC_PKT_DISCONNECTING 4
 129
 130 /**
 131  * @def IX_HSSACC_Q_WRITE_OVERFLOW
 132  *
 133  * @brief Indicates that an attempt to Tx or to replenish an
 134  * RxFree Q failed due to Q overflow.
 135  */
 136 #define IX_HSSACC_Q_WRITE_OVERFLOW 5
 137
 138 /* -------------------------------------------------------------------
 139    The following errors are HSS/NPE errors returned on error retrieval
 140    ------------------------------------------------------------------- */
 141 /**
 142  * @def IX_HSSACC_NO_ERROR
 143  *
 144  * @brief HSS port no error present
 145  */
 146 #define IX_HSSACC_NO_ERROR 0
 147
 148 /**
 149  * @def IX_HSSACC_TX_FRM_SYNC_ERR
 150  *
 151  * @brief HSS port TX Frame Sync error
 152  */
 153 #define IX_HSSACC_TX_FRM_SYNC_ERR 1
 154
 155 /**
 156  * @def IX_HSSACC_TX_OVER_RUN_ERR
 157  *
 158  * @brief HSS port TX over-run error
 159  */
 160 #define IX_HSSACC_TX_OVER_RUN_ERR 2
 161
 162 /**
 163  * @def IX_HSSACC_CHANNELISED_SW_TX_ERR
 164  *
 165  * @brief NPE software error in channelised TX
 166  */
 167 #define IX_HSSACC_CHANNELISED_SW_TX_ERR 3
 168
 169 /**
 170  * @def IX_HSSACC_PACKETISED_SW_TX_ERR
 171  *
 172  * @brief NPE software error in packetised TX
 173  */
 174 #define IX_HSSACC_PACKETISED_SW_TX_ERR 4
 175
 176 /**
 177  * @def IX_HSSACC_RX_FRM_SYNC_ERR
 178  *
 179  * @brief HSS port RX Frame Sync error
 180  */
 181 #define IX_HSSACC_RX_FRM_SYNC_ERR 5
 182
 183 /**
 184  * @def IX_HSSACC_RX_OVER_RUN_ERR
 185  *
 186  * @brief HSS port RX over-run error
 187  */
 188 #define IX_HSSACC_RX_OVER_RUN_ERR 6
 189
 190 /**
 191  * @def IX_HSSACC_CHANNELISED_SW_RX_ERR
 192  *
 193  * @brief NPE software error in channelised RX
 194  */
 195 #define IX_HSSACC_CHANNELISED_SW_RX_ERR 7
 196
 197 /**
 198  * @def IX_HSSACC_PACKETISED_SW_RX_ERR
 199  *
 200  * @brief NPE software error in packetised TX
 201  */
 202 #define IX_HSSACC_PACKETISED_SW_RX_ERR 8
 203
 204 /* -----------------------------------
 205    Packetised service specific defines
 206    ----------------------------------- */
 207
 208 /**
 209  * @def IX_HSSACC_PKT_MIN_RX_MBUF_SIZE
 210  *
 211  * @brief Minimum size of the Rx mbuf in bytes which the client must supply
 212  * to the component.
 213  */
 214 #define IX_HSSACC_PKT_MIN_RX_MBUF_SIZE 64
 215
 216 /* --------------------------------------------------------------------
 217    Enumerated Types - these enumerated values may be used in setting up
 218    the contents of hardware registers
 219    -------------------------------------------------------------------- */
 220 /**
 221  * @enum IxHssAccHssPort
 222  * @brief The HSS port ID - There are two identical ports (0-1).
 223  *
 224  */
 225 typedef enum
 226 {
 227     IX_HSSACC_HSS_PORT_0,   /**< HSS Port 0 */
 228     IX_HSSACC_HSS_PORT_1,   /**< HSS Port 1 */
 229     IX_HSSACC_HSS_PORT_MAX  /**< Delimiter for error checks */
 230 } IxHssAccHssPort;
 231
 232 /**
 233  * @enum IxHssAccHdlcPort
 234  * @brief The HDLC port ID - There are four identical HDLC ports (0-3) per
 235  * HSS port and they correspond to the 4 E1/T1 trunks.
 236  *
 237  */
 238 typedef enum
 239 {
 240    IX_HSSACC_HDLC_PORT_0,   /**< HDLC Port 0 */
 241    IX_HSSACC_HDLC_PORT_1,   /**< HDLC Port 1 */
 242    IX_HSSACC_HDLC_PORT_2,   /**< HDLC Port 2 */
 243    IX_HSSACC_HDLC_PORT_3,   /**< HDLC Port 3 */
 244    IX_HSSACC_HDLC_PORT_MAX  /**< Delimiter for error checks */
 245 } IxHssAccHdlcPort;
 246
 247 /**
 248  * @enum IxHssAccTdmSlotUsage
 249  * @brief The HSS TDM stream timeslot assignment types
 250  *
 251  */
 252 typedef enum
 253 {
 254     IX_HSSACC_TDMMAP_UNASSIGNED,    /**< Unassigned */
 255     IX_HSSACC_TDMMAP_HDLC,          /**< HDLC - packetised */
 256     IX_HSSACC_TDMMAP_VOICE56K,      /**< Voice56K - channelised */
 257     IX_HSSACC_TDMMAP_VOICE64K,      /**< Voice64K - channelised */
 258     IX_HSSACC_TDMMAP_MAX            /**< Delimiter for error checks */
 259 } IxHssAccTdmSlotUsage;
 260
 261 /**
 262  * @enum IxHssAccFrmSyncType
 263  * @brief The HSS frame sync pulse type
 264  *
 265  */
 266 typedef enum
 267 {
 268     IX_HSSACC_FRM_SYNC_ACTIVE_LOW,   /**< Frame sync is sampled low */
 269     IX_HSSACC_FRM_SYNC_ACTIVE_HIGH,  /**< sampled high */
 270     IX_HSSACC_FRM_SYNC_FALLINGEDGE,  /**< sampled on a falling edge */
 271     IX_HSSACC_FRM_SYNC_RISINGEDGE,   /**< sampled on a rising edge */
 272     IX_HSSACC_FRM_SYNC_TYPE_MAX      /**< Delimiter for error checks */
 273 } IxHssAccFrmSyncType;
 274
 275 /**
 276  * @enum IxHssAccFrmSyncEnable
 277  * @brief The IxHssAccFrmSyncEnable determines how the frame sync pulse is
 278  * used
 279  * */
 280 typedef enum
 281 {
 282     IX_HSSACC_FRM_SYNC_INPUT,          /**< Frame sync is sampled as an input */
 283     IX_HSSACC_FRM_SYNC_INVALID_VALUE,  /**< 1 is not used */
 284     IX_HSSACC_FRM_SYNC_OUTPUT_FALLING, /**< Frame sync is an output generated
 285                                           off a falling clock edge */
 286     IX_HSSACC_FRM_SYNC_OUTPUT_RISING,  /**< Frame sync is an output generated
 287                                           off a rising clock edge */
 288     IX_HSSACC_FRM_SYNC_ENABLE_MAX      /**< Delimiter for error checks */
 289 } IxHssAccFrmSyncEnable;
 290
 291 /**
 292  * @enum IxHssAccClkEdge
 293  * @brief IxHssAccClkEdge is used to determine the clk edge to use for
 294  * framing and data
 295  *
 296  */
 297 typedef enum
 298 {
 299     IX_HSSACC_CLK_EDGE_FALLING,  /**< Clock sampled off a falling edge */
 300     IX_HSSACC_CLK_EDGE_RISING,   /**< Clock sampled off a rising edge */
 301     IX_HSSACC_CLK_EDGE_MAX       /**< Delimiter for error checks */
 302 } IxHssAccClkEdge;
 303
 304 /**
 305  * @enum IxHssAccClkDir
 306  * @brief The HSS clock direction
 307  *
 308  */
 309 typedef enum
 310 {
 311     IX_HSSACC_SYNC_CLK_DIR_INPUT,    /**< Clock is an input */
 312     IX_HSSACC_SYNC_CLK_DIR_OUTPUT,   /**< Clock is an output */
 313     IX_HSSACC_SYNC_CLK_DIR_MAX       /**< Delimiter for error checks */
 314 } IxHssAccClkDir;
 315
 316 /**
 317  * @enum IxHssAccFrmPulseUsage
 318  * @brief The HSS frame pulse usage
 319  *
 320  */
 321 typedef enum
 322 {
 323     IX_HSSACC_FRM_PULSE_ENABLED,     /**< Generate/Receive frame pulses */
 324     IX_HSSACC_FRM_PULSE_DISABLED,    /**< Disregard frame pulses */
 325     IX_HSSACC_FRM_PULSE_MAX          /**< Delimiter for error checks */
 326 } IxHssAccFrmPulseUsage;
 327
 328 /**
 329  * @enum IxHssAccDataRate
 330  * @brief The HSS Data rate in relation to the clock
 331  *
 332  */
 333 typedef enum
 334 {
 335     IX_HSSACC_CLK_RATE,      /**< Data rate is at the configured clk speed */
 336     IX_HSSACC_HALF_CLK_RATE, /**< Data rate is half the configured clk speed */
 337     IX_HSSACC_DATA_RATE_MAX  /**< Delimiter for error checks */
 338 } IxHssAccDataRate;
 339
 340 /**
 341  * @enum IxHssAccDataPolarity
 342  * @brief The HSS data polarity type
 343  *
 344  */
 345 typedef enum
 346 {
 347     IX_HSSACC_DATA_POLARITY_SAME,   /**< Don't invert data between NPE and
 348                                        HSS FIFOs */
 349     IX_HSSACC_DATA_POLARITY_INVERT, /**< Invert data between NPE and HSS
 350                                        FIFOs */
 351     IX_HSSACC_DATA_POLARITY_MAX     /**< Delimiter for error checks */
 352 } IxHssAccDataPolarity;
 353
 354 /**
 355  * @enum IxHssAccBitEndian
 356  * @brief HSS Data endianness
 357  *
 358  */
 359 typedef enum
 360 {
 361     IX_HSSACC_LSB_ENDIAN,    /**< TX/RX Least Significant Bit first */
 362     IX_HSSACC_MSB_ENDIAN,    /**< TX/RX Most Significant Bit first */
 363     IX_HSSACC_ENDIAN_MAX     /**< Delimiter for the purposes of error checks */
 364 } IxHssAccBitEndian;
 365
 366
 367 /**
 368  * @enum IxHssAccDrainMode
 369  * @brief Tx pin open drain mode
 370  *
 371  */
 372 typedef enum
 373 {
 374     IX_HSSACC_TX_PINS_NORMAL,       /**< Normal mode */
 375     IX_HSSACC_TX_PINS_OPEN_DRAIN,   /**< Open Drain mode */
 376     IX_HSSACC_TX_PINS_MAX           /**< Delimiter for error checks */
 377 } IxHssAccDrainMode;
 378
 379 /**
 380  * @enum IxHssAccSOFType
 381  * @brief HSS start of frame types
 382  *
 383  */
 384 typedef enum
 385 {
 386     IX_HSSACC_SOF_FBIT,  /**< Framing bit transmitted and expected on rx */
 387     IX_HSSACC_SOF_DATA,  /**< Framing bit not transmitted nor expected on rx */
 388     IX_HSSACC_SOF_MAX    /**< Delimiter for error checks */
 389 } IxHssAccSOFType;
 390
 391 /**
 392  * @enum IxHssAccDataEnable
 393  * @brief IxHssAccDataEnable is used to determine whether or not to drive
 394  * the data pins
 395  *
 396  */
 397 typedef enum
 398 {
 399     IX_HSSACC_DE_TRI_STATE,   /**< TRI-State the data pins */
 400     IX_HSSACC_DE_DATA,        /**< Push data out the data pins */
 401     IX_HSSACC_DE_MAX          /**< Delimiter for error checks */
 402 } IxHssAccDataEnable;
 403
 404 /**
 405  * @enum IxHssAccTxSigType
 406  * @brief IxHssAccTxSigType is used to determine how to drive the data pins
 407  *
 408  */
 409 typedef enum
 410 {
 411     IX_HSSACC_TXSIG_LOW,        /**< Drive the data pins low */
 412     IX_HSSACC_TXSIG_HIGH,       /**< Drive the data pins high */
 413     IX_HSSACC_TXSIG_HIGH_IMP,   /**< Drive the data pins with high impedance */
 414     IX_HSSACC_TXSIG_MAX         /**< Delimiter for error checks */
 415 } IxHssAccTxSigType;
 416
 417 /**
 418  * @enum IxHssAccFbType
 419  * @brief IxHssAccFbType determines how to drive the Fbit
 420  *
 421  * @warning This will only be used for T1 @ 1.544MHz
 422  *
 423  */
 424 typedef enum
 425 {
 426     IX_HSSACC_FB_FIFO,        /**< Fbit is dictated in FIFO */
 427     IX_HSSACC_FB_HIGH_IMP,    /**< Fbit is high impedance */
 428     IX_HSSACC_FB_MAX          /**< Delimiter for error checks */
 429 } IxHssAccFbType;
 430
 431 /**
 432  * @enum IxHssAcc56kEndianness
 433  * @brief 56k data endianness when using the 56k type
 434  *
 435  */
 436 typedef enum
 437 {
 438     IX_HSSACC_56KE_BIT_7_UNUSED,  /**< High bit is unused */
 439     IX_HSSACC_56KE_BIT_0_UNUSED,  /**< Low bit is unused */
 440     IX_HSSACC_56KE_MAX            /**< Delimiter for error checks */
 441 } IxHssAcc56kEndianness;
 442
 443 /**
 444  * @enum IxHssAcc56kSel
 445  * @brief 56k data transmission type when using the 56k type
 446  *
 447  */
 448 typedef enum
 449 {
 450     IX_HSSACC_56KS_32_8_DATA,  /**< 32/8 bit data */
 451     IX_HSSACC_56KS_56K_DATA,   /**< 56K data */
 452     IX_HSSACC_56KS_MAX         /**< Delimiter for error checks */
 453 } IxHssAcc56kSel;
 454
 455
 456 /**
 457  * @enum IxHssAccClkSpeed
 458  * @brief IxHssAccClkSpeed represents the HSS clock speeds available
 459  *
 460  */
 461 typedef enum
 462 {
 463     IX_HSSACC_CLK_SPEED_512KHZ,     /**< 512KHz */
 464     IX_HSSACC_CLK_SPEED_1536KHZ,    /**< 1.536MHz */
 465     IX_HSSACC_CLK_SPEED_1544KHZ,    /**< 1.544MHz */
 466     IX_HSSACC_CLK_SPEED_2048KHZ,    /**< 2.048MHz */
 467     IX_HSSACC_CLK_SPEED_4096KHZ,    /**< 4.096MHz */
 468     IX_HSSACC_CLK_SPEED_8192KHZ,    /**< 8.192MHz */
 469     IX_HSSACC_CLK_SPEED_MAX      /**< Delimiter for error checking */
 470 } IxHssAccClkSpeed;
 471
 472 /**
 473  * @enum IxHssAccPktStatus
 474  * @brief Indicates the status of packets passed to the client
 475  *
 476  */
 477 typedef enum
 478 {
 479     IX_HSSACC_PKT_OK,              /**< Error free.*/
 480     IX_HSSACC_STOP_SHUTDOWN_ERROR, /**< Errored due to stop or shutdown
 481                                       occurrance.*/
 482     IX_HSSACC_HDLC_ALN_ERROR,      /**< HDLC alignment error */
 483     IX_HSSACC_HDLC_FCS_ERROR,       /**< HDLC Frame Check Sum error.*/
 484     IX_HSSACC_RXFREE_Q_EMPTY_ERROR,       /**< RxFree Q became empty
 485                                              while receiving this packet.*/
 486     IX_HSSACC_HDLC_MAX_FRAME_SIZE_EXCEEDED,      /**< HDLC frame size
 487                                                    received is greater than
 488                                                    max specified at connect.*/
 489     IX_HSSACC_HDLC_ABORT_ERROR,   /**< HDLC frame received is invalid due to an
 490                                    abort sequence received.*/
 491     IX_HSSACC_DISCONNECT_IN_PROGRESS     /**< Packet returned
 492                                             because a disconnect is in progress */
 493 } IxHssAccPktStatus;
 494
 495
 496 /**
 497  * @enum IxHssAccPktCrcType
 498  * @brief HDLC CRC type
 499  *
 500  */
 501 typedef enum
 502 {
 503     IX_HSSACC_PKT_16_BIT_CRC = 16,  /**< 16 bit CRC is being used */
 504     IX_HSSACC_PKT_32_BIT_CRC = 32   /**< 32 bit CRC is being used */
 505 } IxHssAccPktCrcType;
 506
 507 /**
 508  * @enum IxHssAccPktHdlcIdleType
 509  * @brief HDLC idle transmission type
 510  *
 511  */
 512 typedef enum
 513 {
 514     IX_HSSACC_HDLC_IDLE_ONES,    /**< idle tx/rx will be a succession of ones */
 515     IX_HSSACC_HDLC_IDLE_FLAGS    /**< idle tx/rx will be repeated flags */
 516 } IxHssAccPktHdlcIdleType;
 517
 518 /**
 519  * @brief Structure containing HSS port configuration parameters
 520  *
 521  * Note: All of these are used for TX. Only some are specific to RX.
 522  *
 523  */
 524 typedef struct
 525 {
 526     IxHssAccFrmSyncType frmSyncType;     /**< frame sync pulse type (tx/rx) */
 527     IxHssAccFrmSyncEnable frmSyncIO;     /**< how the frame sync pulse is
 528                                             used (tx/rx) */
 529     IxHssAccClkEdge frmSyncClkEdge;      /**< frame sync clock edge type
 530                                             (tx/rx) */
 531     IxHssAccClkEdge dataClkEdge;         /**< data clock edge type (tx/rx) */
 532     IxHssAccClkDir clkDirection;         /**< clock direction (tx/rx) */
 533     IxHssAccFrmPulseUsage frmPulseUsage; /**< whether to use the frame sync
 534                                             pulse or not (tx/rx) */
 535     IxHssAccDataRate dataRate;           /**< data rate in relation to the
 536                                             clock (tx/rx) */
 537     IxHssAccDataPolarity dataPolarity;   /**< data polarity type (tx/rx) */
 538     IxHssAccBitEndian dataEndianness;    /**< data endianness (tx/rx) */
 539     IxHssAccDrainMode drainMode;         /**< tx pin open drain mode (tx) */
 540     IxHssAccSOFType fBitUsage;           /**< start of frame types (tx/rx) */
 541     IxHssAccDataEnable dataEnable;       /**< whether or not to drive the data
 542                                             pins (tx) */
 543     IxHssAccTxSigType voice56kType;      /**< how to drive the data pins for
 544                                             voice56k type (tx) */
 545     IxHssAccTxSigType unassignedType;    /**< how to drive the data pins for
 546                                             unassigned type (tx) */
 547     IxHssAccFbType fBitType;             /**< how to drive the Fbit (tx) */
 548     IxHssAcc56kEndianness voice56kEndian;/**< 56k data endianness when using
 549                                             the 56k type (tx) */
 550     IxHssAcc56kSel voice56kSel;          /**< 56k data transmission type when
 551                                             using the 56k type (tx) */
 552     unsigned frmOffset;                  /**< frame pulse offset in bits wrt
 553                                             the first timeslot (0-1023) (tx/rx) */
 554     unsigned maxFrmSize;                 /**< frame size in bits (1-1024)
 555                                             (tx/rx) */
 556 } IxHssAccPortConfig;
 557
 558 /**
 559  * @brief Structure containing HSS configuration parameters
 560  *
 561  */
 562 typedef struct
 563 {
 564     IxHssAccPortConfig txPortConfig; /**< HSS tx port configuration */
 565     IxHssAccPortConfig rxPortConfig; /**< HSS rx port configuration */
 566     unsigned numChannelised;         /**< The number of channelised
 567                                         timeslots (0-32) */
 568     unsigned hssPktChannelCount;     /**< The number of packetised
 569                                         clients (0 - 4) */
 570     UINT8 channelisedIdlePattern;    /**< The byte to be transmitted on
 571                                         channelised service when there
 572                                         is no client data to tx */
 573     BOOL loopback;                   /**< The HSS loopback state */
 574     unsigned packetizedIdlePattern;  /**< The data to be transmitted on
 575                                         packetised service when there is
 576                                         no client data to tx */
 577     IxHssAccClkSpeed clkSpeed;       /**< The HSS clock speed */
 578 } IxHssAccConfigParams;
 579
 580 /**
 581  * @brief This structure contains 56Kbps, HDLC-mode configuration parameters
 582  *
 583  */
 584 typedef struct
 585 {
 586     BOOL hdlc56kMode;                    /**< 56kbps(true)/64kbps(false) HDLC */
 587     IxHssAcc56kEndianness hdlc56kEndian; /**< 56kbps data endianness
 588                                             - ignored if hdlc56kMode is false*/
 589     BOOL hdlc56kUnusedBitPolarity0;      /**< The polarity '0'(true)/'1'(false) of the unused
 590                                            bit while in 56kbps mode
 591                                            - ignored if hdlc56kMode is false*/
 592 } IxHssAccHdlcMode;
 593
 594 /**
 595  * @brief This structure contains information required by the NPE to
 596  * configure the HDLC co-processor
 597  *
 598  */
 599 typedef struct
 600 {
 601     IxHssAccPktHdlcIdleType hdlcIdleType;   /**< What to transmit when a HDLC port is idle */
 602     IxHssAccBitEndian dataEndian;           /**< The HDLC data endianness */
 603     IxHssAccPktCrcType crcType;             /**< The CRC type to be used for this HDLC port */
 604 } IxHssAccPktHdlcFraming;
 605
 606 /**
 607  * @typedef UINT32 IxHssAccPktUserId
 608  *
 609  * @brief The client supplied value which will be supplied as a parameter
 610  * with a given callback.
 611  *
 612  * This value will be passed into the ixHssAccPktPortConnect function once each
 613  * with given callbacks.  This value will then be passed back to the client
 614  * as one of the parameters to each of these callbacks,
 615  * when these callbacks are called.
 616  */
 617 typedef UINT32 IxHssAccPktUserId;
 618
 619
 620 /**
 621  * @typedef IxHssAccLastErrorCallback
 622  * @brief Prototype of the clients function to accept notification of the
 623  * last error
 624  *
 625  * This function is registered through the config. The client will initiate
 626  * the last error retrieval. The HssAccess component will send a message to
 627  * the NPE through the NPE Message Handler. When a response to the read is
 628  * received, the NPE Message Handler will callback the HssAccess component
 629  * which will execute this function in the same IxNpeMh context. The client
 630  * will be passed the last error and the related service port (packetised
 631  * 0-3, channelised 0)
 632  *
 633  * @param lastHssError unsigned [in] - The last Hss error registered that
 634  *                                      has been registered.
 635  * @param servicePort unsigned [in] - This is the service port number.
 636  *                                     (packetised 0-3, channelised 0)
 637  *
 638  * @return void
 639  */
 640 typedef void (*IxHssAccLastErrorCallback) (unsigned lastHssError,
 641                                            unsigned servicePort);
 642
 643 /**
 644  * @typedef IxHssAccPktRxCallback
 645  * @brief  Prototype of the clients function to accept notification of
 646  * packetised rx
 647  *
 648  * This function is registered through the ixHssAccPktPortConnect. hssPktAcc will pass
 649  * received data in the form of mbufs to the client.  The mbuf passed back
 650  * to the client could contain a chain of buffers, depending on the packet
 651  * size received.
 652  *
 653  * @param *buffer @ref IX_OSAL_MBUF [in] - This is the mbuf which contains the
 654  * payload received.
 655  * @param numHssErrs unsigned [in] - This is the number of hssErrors
 656  * the Npe has received
 657  * @param pktStatus @ref IxHssAccPktStatus [in] - This is the status of the
 658  * mbuf that has been received.
 659  * @param rxUserId @ref IxHssAccPktUserId [in] - This is the client supplied value
 660  * passed in at ixHssAccPktPortConnect time which is now returned to the client.
 661  *
 662  * @return void
 663  */
 664 typedef void (*IxHssAccPktRxCallback) (IX_OSAL_MBUF *buffer,
 665                                        unsigned numHssErrs,
 666                                        IxHssAccPktStatus pktStatus,
 667                                        IxHssAccPktUserId rxUserId);
 668
 669 /**
 670  * @typedef IxHssAccPktRxFreeLowCallback
 671  * @brief Prototype of the clients function to accept notification of
 672  * requirement of more Rx Free buffers
 673  *
 674  * The client can choose to register a callback of this type when
 675  * calling a connecting. This function is registered through the ixHssAccPktPortConnect.
 676  * If defined, the access layer will provide the trigger for
 677  * this callback. The callback will be responsible for supplying mbufs to
 678  * the access layer for use on the receive path from the HSS using
 679  * ixHssPktAccFreeBufReplenish.
 680  *
 681  * @return void
 682  */
 683 typedef void (*IxHssAccPktRxFreeLowCallback) (IxHssAccPktUserId rxFreeLowUserId);
 684
 685 /**
 686  * @typedef IxHssAccPktTxDoneCallback
 687  * @brief  Prototype of the clients function to accept notification of
 688  * completion with Tx buffers
 689  *
 690  * This function is registered through the ixHssAccPktPortConnect.  It enables
 691  * the hssPktAcc to pass buffers back to the client
 692  * when transmission is complete.
 693  *
 694  * @param *buffer @ref IX_OSAL_MBUF [in] - This is the mbuf which contained
 695  * the payload that was for Tx.
 696  * @param numHssErrs unsigned [in] - This is the number of hssErrors
 697  * the Npe has received
 698  * @param pktStatus @ref IxHssAccPktStatus [in] - This is the status of the
 699  * mbuf that has been transmitted.
 700  * @param txDoneUserId @ref IxHssAccPktUserId [in] - This is the client supplied value
 701  * passed in at ixHssAccPktPortConnect time which is now returned to the client.
 702  *
 703  * @return void
 704  */
 705 typedef void (*IxHssAccPktTxDoneCallback) (IX_OSAL_MBUF *buffer,
 706                                            unsigned numHssErrs,
 707                                            IxHssAccPktStatus pktStatus,
 708                                            IxHssAccPktUserId txDoneUserId);
 709
 710 /**
 711  * @typedef IxHssAccChanRxCallback
 712  * @brief Prototype of the clients function to accept notification of
 713  * channelised rx
 714  *
 715  * This callback, if defined by the client in the connect, will get called
 716  * in the context of an IRQ. The IRQ will be triggered when the hssSyncQMQ
 717  * is not empty. The queued entry will be dequeued and this function will
 718  * be executed.
 719  *
 720  * @param hssPortId @ref IxHssAccHssPort - The HSS port Id. There are two
 721  * identical ports (0-1).
 722  * @param txOffset unsigned [in] - an offset indicating from where within
 723  * the txPtrList the NPE is currently transmitting from.
 724  * @param rxOffset unsigned [in] - an offset indicating where within the
 725  * receive buffers the NPE has just written the received data to.
 726  * @param numHssErrs unsigned [in] - This is the number of hssErrors
 727  * the Npe has received
 728  *
 729  * @return void
 730  */
 731 typedef void (*IxHssAccChanRxCallback) (IxHssAccHssPort hssPortId,
 732                                         unsigned rxOffset,
 733                                         unsigned txOffset,
 734                                         unsigned numHssErrs);
 735
 736 /*
 737  * Prototypes for interface functions.
 738  */
 739
 740 /**
 741  *
 742  * @ingroup IxHssAccAPI
 743  *
 744  * @fn IX_STATUS ixHssAccPortInit (IxHssAccHssPort hssPortId,
 745                IxHssAccConfigParams *configParams,
 746                IxHssAccTdmSlotUsage *tdmMap,
 747                IxHssAccLastErrorCallback lastHssErrorCallback)
 748  *
 749  * @brief Initialise a HSS port. No channelised or packetised connections
 750  * should exist in the HssAccess layer while this interface is being called.
 751  *
 752  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 753  * identical ports (0-1).
 754  * @param *configParams @ref IxHssAccConfigParams [in] - A pointer to the HSS
 755  * configuration structure
 756  * @param *tdmMap @ref IxHssAccTdmSlotUsage [in] - A pointer to an array of size
 757  * IX_HSSACC_TSLOTS_PER_HSS_PORT, defining the slot usage over the HSS port
 758  * @param lastHssErrorCallback @ref IxHssAccLastErrorCallback [in] - Client
 759  * callback to report last error
 760  *
 761  * @return
 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
 765  *                          parameter error
 766  */
 767 PUBLIC IX_STATUS
 768 ixHssAccPortInit (IxHssAccHssPort hssPortId,
 769                   IxHssAccConfigParams *configParams,
 770                   IxHssAccTdmSlotUsage *tdmMap,
 771                   IxHssAccLastErrorCallback lastHssErrorCallback);
 772
 773 /**
 774  *
 775  * @ingroup IxHssAccAPI
 776  *
 777  * @fn IX_STATUS ixHssAccLastErrorRetrievalInitiate (
 778                IxHssAccHssPort hssPortId)
 779  *
 780  * @brief Initiate the retrieval of the last HSS error. The HSS port
 781  * should be configured before attempting to call this interface.
 782  *
 783  * @param hssPortId @ref IxHssAccHssPort [in] - the HSS port ID
 784  *
 785  * @return
 786  *         - IX_SUCCESS The function executed successfully
 787  *         - IX_FAIL The function did not execute successfully
 788  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 789  *                          parameter error
 790  */
 791 PUBLIC IX_STATUS
 792 ixHssAccLastErrorRetrievalInitiate (IxHssAccHssPort hssPortId);
 793
 794
 795 /**
 796  *
 797  * @ingroup IxHssAccAPI
 798  *
 799  * @fn IX_STATUS ixHssAccInit ()
 800  *
 801  * @brief This function is responsible for initialising resources for use
 802  * by the packetised and channelised clients. It should be called after
 803  * HSS NPE image has been downloaded into NPE-A and before any other
 804  * HssAccess interface is called.
 805  * No other HssAccPacketised interface should be called while this interface
 806  * is being processed.
 807  *
 808  * @return
 809  *         - IX_SUCCESS The function executed successfully
 810  *         - IX_FAIL The function did not execute successfully
 811  *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
 812  *                          to a resource error
 813  */
 814 PUBLIC IX_STATUS
 815 ixHssAccInit (void);
 816
 817
 818 /**
 819  *
 820  * @ingroup IxHssAccAPI
 821  *
 822  * @fn ixHssAccPktPortConnect (IxHssAccHssPort hssPortId,
 823                         IxHssAccHdlcPort hdlcPortId,
 824                         BOOL hdlcFraming,
 825                         IxHssAccHdlcMode hdlcMode,
 826                         BOOL hdlcBitInvert,
 827                         unsigned blockSizeInWords,
 828                         UINT32 rawIdleBlockPattern,
 829                         IxHssAccPktHdlcFraming hdlcTxFraming,
 830                         IxHssAccPktHdlcFraming hdlcRxFraming,
 831                         unsigned frmFlagStart,
 832                         IxHssAccPktRxCallback rxCallback,
 833                         IxHssAccPktUserId rxUserId,
 834                         IxHssAccPktRxFreeLowCallback rxFreeLowCallback,
 835                         IxHssAccPktUserId rxFreeLowUserId,
 836                         IxHssAccPktTxDoneCallback txDoneCallback,
 837                         IxHssAccPktUserId txDoneUserId)
 838  *
 839  * @brief This function is responsible for connecting a client to one of
 840  * the 4 available HDLC ports. The HSS port should be configured before
 841  * attempting a connect. No other HssAccPacketised interface should be
 842  * called while this connect is being processed.
 843  *
 844  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 845  * identical ports (0-1).
 846  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port and
 847  * it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
 848  * @param hdlcFraming BOOL [in] - This value determines whether the service
 849  * will use HDLC data or the debug, raw data type i.e. no HDLC processing
 850  * @param hdlcMode @ref IxHssAccHdlcMode [in] - This structure contains 56Kbps, HDLC-mode
 851  * configuration parameters
 852  * @param hdlcBitInvert BOOL [in] - This value determines whether bit inversion
 853  * will occur between HDLC and HSS co-processors i.e. post-HDLC processing for
 854  * transmit and pre-HDLC processing for receive, for the specified HDLC Termination
 855  * Point
 856  * @param blockSizeInWords unsigned [in] -  The max tx/rx block size
 857  * @param rawIdleBlockPattern UINT32 [in] -  Tx idle pattern in raw mode
 858  * @param hdlcTxFraming @ref IxHssAccPktHdlcFraming [in] - This structure contains
 859  * the following information required by the NPE to configure the HDLC
 860  * co-processor for TX
 861  * @param hdlcRxFraming @ref IxHssAccPktHdlcFraming [in] -  This structure contains
 862  * the following information required by the NPE to configure the HDLC
 863  * co-processor for RX
 864  * @param frmFlagStart unsigned - Number of flags to precede to
 865  * transmitted flags (0-2).
 866  * @param rxCallback @ref IxHssAccPktRxCallback [in] - Pointer to
 867  * the clients packet receive function.
 868  * @param rxUserId @ref IxHssAccPktUserId [in] - The client supplied rx value
 869  * to be passed back as an argument to the supplied rxCallback
 870  * @param rxFreeLowCallback @ref IxHssAccPktRxFreeLowCallback [in] - Pointer to
 871  * the clients Rx free buffer request function.  If NULL, assume client will
 872  * trigger independently.
 873  * @param rxFreeLowUserId @ref IxHssAccPktUserId [in] - The client supplied RxFreeLow value
 874  * to be passed back as an argument to the supplied rxFreeLowCallback
 875  * @param txDoneCallback @ref IxHssAccPktTxDoneCallback [in] - Pointer to the
 876  * clients Tx done callback function
 877  * @param txDoneUserId @ref IxHssAccPktUserId [in] - The client supplied txDone value
 878  * to be passed back as an argument to the supplied txDoneCallback
 879  *
 880  * @return
 881  *         - IX_SUCCESS The function executed successfully
 882  *         - IX_FAIL The function did not execute successfully
 883  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 884  *                          parameter error
 885  *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
 886  *                          to a resource error
 887  */
 888 PUBLIC IX_STATUS
 889 ixHssAccPktPortConnect (IxHssAccHssPort hssPortId,
 890                         IxHssAccHdlcPort hdlcPortId,
 891                         BOOL hdlcFraming,
 892                         IxHssAccHdlcMode hdlcMode,
 893                         BOOL hdlcBitInvert,
 894                         unsigned blockSizeInWords,
 895                         UINT32 rawIdleBlockPattern,
 896                         IxHssAccPktHdlcFraming hdlcTxFraming,
 897                         IxHssAccPktHdlcFraming hdlcRxFraming,
 898                         unsigned frmFlagStart,
 899                         IxHssAccPktRxCallback rxCallback,
 900                         IxHssAccPktUserId rxUserId,
 901                         IxHssAccPktRxFreeLowCallback rxFreeLowCallback,
 902                         IxHssAccPktUserId rxFreeLowUserId,
 903                         IxHssAccPktTxDoneCallback txDoneCallback,
 904                         IxHssAccPktUserId txDoneUserId);
 905
 906 /**
 907  *
 908  * @ingroup IxHssAccAPI
 909  *
 910  * @fn IX_STATUS ixHssAccPktPortEnable (IxHssAccHssPort hssPortId,
 911            IxHssAccHdlcPort hdlcPortId)
 912  *
 913  * @brief This function is responsible for enabling a packetised service
 914  * for the specified HSS/HDLC port combination. It enables the RX flow. The
 915  * client must have already connected to a packetised service and is responsible
 916  * for ensuring an adequate amount of RX mbufs have been supplied to the access
 917  * component before enabling the packetised service. This function must be called
 918  * on a given port before any call to ixHssAccPktPortTx on the same port.
 919  * No other HssAccPacketised interface should be called while this interface is
 920  * being processed.
 921  *
 922  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 923  * identical ports (0-1).
 924  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - The port id (0,1,2,3) to enable the service
 925  * on.
 926  *
 927  * @return
 928  *         - IX_SUCCESS The function executed successfully
 929  *         - IX_FAIL The function did not execute successfully
 930  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 931  *                          parameter error
 932  */
 933 PUBLIC IX_STATUS
 934 ixHssAccPktPortEnable (IxHssAccHssPort hssPortId,
 935                        IxHssAccHdlcPort hdlcPortId);
 936
 937 /**
 938  * @fn IX_STATUS ixHssAccPktPortDisable (IxHssAccHssPort hssPortId,
 939            IxHssAccHdlcPort hdlcPortId)
 940  *
 941  * @brief This function is responsible for disabling a packetised service
 942  * for the specified HSS/HDLC port combination. It disables the RX flow.
 943  * The client must have already connected to and enabled a packetised service
 944  * for the specified HDLC port. This disable interface can be called before a
 945  * disconnect, but is not required to.
 946  *
 947  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 948  * identical ports (0-1).
 949  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - The port id (0,1,2,3) to disable
 950  * the service on.
 951  *
 952  * @return
 953  *         - IX_SUCCESS The function executed successfully
 954  *         - IX_FAIL The function did not execute successfully
 955  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
 956  *                          parameter error
 957  */
 958 PUBLIC IX_STATUS
 959 ixHssAccPktPortDisable (IxHssAccHssPort hssPortId,
 960                         IxHssAccHdlcPort hdlcPortId);
 961
 962 /**
 963  *
 964  * @ingroup IxHssAccAPI
 965  *
 966  * @fn IX_STATUS ixHssAccPktPortDisconnect (IxHssAccHssPort hssPortId,
 967            IxHssAccHdlcPort hdlcPortId)
 968  *
 969  * @brief This function is responsible for disconnecting a client from one
 970  * of the 4 available HDLC ports. It is not required that the Rx Flow
 971  * has been disabled before calling this function.  If the RX Flow has not been
 972  * disabled, the disconnect will disable it before proceeding with the
 973  * disconnect.  No other HssAccPacketised
 974  * interface should be called while this interface is being processed.
 975  *
 976  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
 977  * identical ports (0-1).
 978  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
 979  * to disconnect and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
 980  *
 981  * @return
 982  *         - IX_SUCCESS The function executed successfully
 983  *         - IX_FAIL The function did not execute successfully
 984  *         - IX_HSSACC_PKT_DISCONNECTING The function has initiated the disconnecting
 985  *                             procedure but it has not completed yet.
 986  */
 987 PUBLIC IX_STATUS
 988 ixHssAccPktPortDisconnect (IxHssAccHssPort hssPortId,
 989                            IxHssAccHdlcPort hdlcPortId);
 990
 991 /**
 992  *
 993  * @ingroup IxHssAccAPI
 994  *
 995  * @fn BOOL ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId,
 996            IxHssAccHdlcPort hdlcPortId)
 997  *
 998  * @brief This function is called to check if a given HSS/HDLC port
 999  * combination is in a connected state or not. This function may be called
1000  * at any time to determine a ports state.  No other HssAccPacketised
1001  * interface should be called while this interface is being processed.
1002  *
1003  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1004  * identical ports (0-1).
1005  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
1006  * to disconnect and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
1007  *
1008  * @return
1009  *         - true The state of this HSS/HDLC port combination is disconnected,
1010  *                so if a disconnect was called, it is now completed.
1011  *         - false The state of this HSS/HDLC port combination is connected,
1012  *                so if a disconnect was called, it is not yet completed.
1013  */
1014 PUBLIC BOOL
1015 ixHssAccPktPortIsDisconnectComplete (IxHssAccHssPort hssPortId,
1016                                      IxHssAccHdlcPort hdlcPortId);
1017
1018
1019 /**
1020  *
1021  * @ingroup IxHssAccAPI
1022  *
1023  * @fn IX_STATUS ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId,
1024               IxHssAccHdlcPort hdlcPortId,
1025               IX_OSAL_MBUF *buffer)
1026  *
1027  * @brief Function which the client calls at regular intervals to provide
1028  * mbufs to the access component for RX. A connection should exist for
1029  * the specified hssPortId/hdlcPortId combination before attempting to call this
1030  * interface. Also, the connection should not be in a disconnecting state.
1031  *
1032  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1033  * identical ports (0-1).
1034  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
1035  * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
1036  * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a free mbuf to filled with payload.
1037  *
1038  * @return
1039  *         - IX_SUCCESS The function executed successfully
1040  *         - IX_FAIL The function did not execute successfully
1041  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1042  *                          parameter error
1043  *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
1044  *                          to a resource error
1045  *         - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
1046  *                                      overflow
1047  */
1048 PUBLIC IX_STATUS
1049 ixHssAccPktPortRxFreeReplenish (IxHssAccHssPort hssPortId,
1050                                 IxHssAccHdlcPort hdlcPortId,
1051                                 IX_OSAL_MBUF *buffer);
1052
1053 /**
1054  *
1055  * @ingroup IxHssAccAPI
1056  *
1057  * @fn IX_STATUS ixHssAccPktPortTx (IxHssAccHssPort hssPortId,
1058     IxHssAccHdlcPort hdlcPortId,
1059     IX_OSAL_MBUF *buffer)
1060  *
1061  * @brief Function which the client calls when it wants to transmit
1062  * packetised data. An enabled connection should exist on the specified
1063  * hssPortId/hdlcPortId combination before attempting to call this interface.
1064  * No other HssAccPacketised
1065  * interface should be called while this interface is being processed.
1066  *
1067  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1068  * identical ports (0-1).
1069  * @param hdlcPortId @ref IxHssAccHdlcPort [in] - This is the number of the HDLC port
1070  * and it corresponds to the physical E1/T1 trunk i.e. 0, 1, 2, 3
1071  * @param *buffer @ref IX_OSAL_MBUF [in] - A pointer to a chain of mbufs which the
1072  * client has filled with the payload
1073  *
1074  * @return
1075  *         - IX_SUCCESS The function executed successfully
1076  *         - IX_FAIL The function did not execute successfully
1077  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1078  *                          parameter error
1079  *         - IX_HSSACC_RESOURCE_ERR The function did not execute successfully due
1080  *                          to a resource error. See note.
1081  *         - IX_HSSACC_Q_WRITE_OVERFLOW The function did not succeed due to a Q
1082  *                                      overflow
1083  *
1084  * @note IX_HSSACC_RESOURCE_ERR is returned when a free descriptor cannot be
1085  * obtained to send the chain of mbufs to the NPE.  This is a normal scenario.
1086  * HssAcc has a pool of descriptors and this error means that they are currently
1087  * all in use.
1088  * The recommended approach to this is to retry until a descriptor becomes free
1089  * and the packet is successfully transmitted.
1090  * Alternatively, the user could wait until the next IxHssAccPktTxDoneCallback
1091  * callback is triggered, and then retry, as it is this event that causes a
1092  * transmit descriptor to be freed.
1093  */
1094 PUBLIC IX_STATUS
1095 ixHssAccPktPortTx (IxHssAccHssPort hssPortId,
1096                    IxHssAccHdlcPort hdlcPortId,
1097                    IX_OSAL_MBUF *buffer);
1098
1099 /**
1100  *
1101  * @ingroup IxHssAccAPI
1102  *
1103  * @fn IX_STATUS ixHssAccChanConnect (IxHssAccHssPort hssPortId,
1104            unsigned bytesPerTSTrigger,
1105            UINT8 *rxCircular,
1106            unsigned numRxBytesPerTS,
1107            UINT32 *txPtrList,
1108            unsigned numTxPtrLists,
1109            unsigned numTxBytesPerBlk,
1110            IxHssAccChanRxCallback rxCallback)
1111  *
1112  * @brief This function allows the client to connect to the Tx/Rx NPE
1113  * Channelised Service. There can only be one client per HSS port. The
1114  * client is responsible for ensuring that the HSS port is configured
1115  * appropriately before its connect request. No other HssAccChannelised
1116  * interface should be called while this interface is being processed.
1117  *
1118  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1119  * identical ports (0-1).
1120  * @param bytesPerTSTrigger unsigned [in] - The NPE will trigger the access
1121  * component after bytesPerTSTrigger have been received for all trunk
1122  * timeslots. This figure is a multiple of 8 e.g. 8 for 1ms trigger, 16 for
1123  * 2ms trigger.
1124  * @param *rxCircular UINT8 [in] - A pointer to memory allocated by the
1125  * client to be filled by data received. The buffer at this address is part
1126  * of a pool of buffers to be accessed in a circular fashion. This address
1127  * will be written to by the NPE. Therefore, it needs to be a physical address.
1128  * @param numRxBytesPerTS unsigned [in] - The number of bytes allocated per
1129  * timeslot within the receive memory. This figure will depend on the
1130  * latency of the system. It needs to be deep enough for data to be read by
1131  * the client before the NPE re-writes over that memory e.g. if the client
1132  * samples at a rate of 40bytes per timeslot, numRxBytesPerTS may need to
1133  * be 40bytes * 3. This would give the client 3 * 5ms of time before
1134  * received data is over-written.
1135  * @param *txPtrList UINT32 [in] - The address of an area of contiguous
1136  * memory allocated by the client to be populated with pointers to data for
1137  * transmission. Each pointer list contains a pointer per active channel.
1138  * The txPtrs will point to data to be transmitted by the NPE. Therefore,
1139  * they must point to physical addresses.
1140  * @param numTxPtrLists unsigned [in] - The number of pointer lists in
1141  * txPtrList. This figure is dependent on jitter.
1142  * @param numTxBytesPerBlk unsigned [in] - The size of the Tx data, in
1143  * bytes, that each pointer within the PtrList points to.
1144  * @param rxCallback @ref IxHssAccChanRxCallback [in] - A client function
1145  * pointer to be called back to handle the actual tx/rx of channelised
1146  * data. If this is not NULL, an ISR will call this function. If this
1147  * pointer is NULL, it implies that the client will use a polling mechanism
1148  * to detect when the tx and rx of channelised data is to occur. The client
1149  * will use hssChanAccStatus for this.
1150  *
1151  * @return
1152  *         - IX_SUCCESS The function executed successfully
1153  *         - IX_FAIL The function did not execute successfully
1154  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1155  *                          parameter error
1156  */
1157
1158 PUBLIC IX_STATUS
1159 ixHssAccChanConnect (IxHssAccHssPort hssPortId,
1160                      unsigned bytesPerTSTrigger,
1161                      UINT8 *rxCircular,
1162                      unsigned numRxBytesPerTS,
1163                      UINT32 *txPtrList,
1164                      unsigned numTxPtrLists,
1165                      unsigned numTxBytesPerBlk,
1166                      IxHssAccChanRxCallback rxCallback);
1167
1168 /**
1169  *
1170  * @ingroup IxHssAccAPI
1171  *
1172  * @fn IX_STATUS ixHssAccChanPortEnable (IxHssAccHssPort hssPortId)
1173  *
1174  * @brief This function is responsible for enabling a channelised service
1175  * for the specified HSS port. It enables the NPE RX flow. The client must
1176  * have already connected to a channelised service before enabling the
1177  * channelised service. No other HssAccChannelised
1178  * interface should be called while this interface is being processed.
1179  *
1180  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1181  * identical ports (0-1).
1182  *
1183  * @return
1184  *         - IX_SUCCESS The function executed successfully
1185  *         - IX_FAIL The function did not execute successfully
1186  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1187  *                          parameter error
1188  */
1189 PUBLIC IX_STATUS
1190 ixHssAccChanPortEnable (IxHssAccHssPort hssPortId);
1191
1192 /**
1193  *
1194  * @ingroup IxHssAccAPI
1195  *
1196  * @fn IX_STATUS ixHssAccChanPortDisable (IxHssAccHssPort hssPortId)
1197  *
1198  * @brief This function is responsible for disabling a channelised service
1199  * for the specified HSS port. It disables the NPE RX flow. The client must
1200  * have already connected to and enabled a channelised service for the
1201  * specified HSS port. This disable interface can be called before a
1202  * disconnect, but is not required to. No other HssAccChannelised
1203  * interface should be called while this interface is being processed.
1204  *
1205  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1206  * identical ports (0-1).
1207  *
1208  * @return
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
1212  *                          parameter error
1213  */
1214 PUBLIC IX_STATUS
1215 ixHssAccChanPortDisable (IxHssAccHssPort hssPortId);
1216
1217 /**
1218  *
1219  * @ingroup IxHssAccAPI
1220  *
1221  * @fn IX_STATUS ixHssAccChanDisconnect (IxHssAccHssPort hssPortId)
1222  *
1223  * @brief This function allows the client to Disconnect from a channelised
1224  * service. If the NPE RX Flow has not been disabled, the disconnect will
1225  * disable it before proceeding with other disconnect functionality.
1226  * No other HssAccChannelised interface should be called while this
1227  * interface is being processed.
1228  *
1229  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1230  * identical ports (0-1).
1231  *
1232  * @return
1233  *         - IX_SUCCESS The function executed successfully
1234  *         - IX_FAIL The function did not execute successfully
1235  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1236  *                          parameter error
1237  */
1238 PUBLIC IX_STATUS
1239 ixHssAccChanDisconnect (IxHssAccHssPort hssPortId);
1240
1241 /**
1242  *
1243  * @ingroup IxHssAccAPI
1244  *
1245  * @fn IX_STATUS ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId,
1246            BOOL *dataRecvd,
1247            unsigned *rxOffset,
1248            unsigned *txOffset,
1249            unsigned *numHssErrs)
1250  *
1251  * @brief This function is called by the client to query whether or not
1252  * channelised data has been received. If there is, hssChanAcc will return
1253  * the details in the output parameters. An enabled connection should
1254  * exist on the specified hssPortId before attempting to call this interface.
1255  * No other HssAccChannelised interface should be called while this
1256  * interface is being processed.
1257  *
1258  * @param hssPortId @ref IxHssAccHssPort [in] - The HSS port Id. There are two
1259  * identical ports (0-1).
1260  * @param *dataRecvd BOOL [out] - This BOOL indicates to the client whether
1261  * or not the access component has read any data for the client. If
1262  * false, the other output parameters will not have been written to.
1263  * @param *rxOffset unsigned [out] - An offset to indicate to the client
1264  * where within the receive buffers the NPE has just written the received
1265  * data to.
1266  * @param *txOffset unsigned [out] - An offset to indicate to the client
1267  * from where within the txPtrList the NPE is currently transmitting from
1268  * @param *numHssErrs unsigned [out] - The total number of HSS port errors
1269  * since initial port configuration
1270  *
1271  *
1272  * @return
1273  *         - IX_SUCCESS The function executed successfully
1274  *         - IX_FAIL The function did not execute successfully
1275  *         - IX_HSSACC_PARAM_ERR The function did not execute successfully due to a
1276  *                          parameter error
1277  */
1278 PUBLIC IX_STATUS
1279 ixHssAccChanStatusQuery (IxHssAccHssPort hssPortId,
1280                          BOOL *dataRecvd,
1281                          unsigned *rxOffset,
1282                          unsigned *txOffset,
1283                          unsigned *numHssErrs);
1284
1285 /**
1286  *
1287  * @ingroup IxHssAccAPI
1288  *
1289  * @fn void ixHssAccShow (void)
1290  *
1291  * @brief This function will display the current state of the IxHssAcc
1292  * component. The output is sent to stdout.
1293  *
1294  * @return void
1295  */
1296 PUBLIC void
1297 ixHssAccShow (void);
1298
1299 /**
1300  *
1301  * @ingroup IxHssAccAPI
1302  *
1303  * @fn void ixHssAccStatsInit (void)
1304  *
1305  * @brief This function will reset the IxHssAcc statistics.
1306  *
1307  * @return void
1308  */
1309 PUBLIC void
1310 ixHssAccStatsInit (void);
1311
1312 #endif /* IXHSSACC_H */
1313
1314 /**
1315  * @} defgroup IxHssAcc
1316  */