drivers/net/npe/include/IxSspAcc.h

   1 /**
   2  * @file IxSspAcc.h
   3  *
   4  * @brief  Header file for the IXP400 SSP Serial Port Access (IxSspAcc)
   5  *
   6  * @version $Revision: 0.1 $
   7  *
   8  * @par
   9  * IXP400 SW Release version 2.0
  10  *
  11  * -- Copyright Notice --
  12  *
  13  * @par
  14  * Copyright 2001-2005, Intel Corporation.
  15  * All rights reserved.
  16  *
  17  * @par
  18  * SPDX-License-Identifier:     BSD-3-Clause
  19  * @par
  20  * -- End of Copyright Notice --
  21  */
  22
  23 /**
  24  * @defgroup IxSspAcc IXP400 SSP Serial Port Access (IxSspAcc) API
  25  *
  26  * @brief IXP400 SSP Serial Port Access Public API
  27  *
  28  * @{
  29  */
  30 #ifndef IXSSPACC_H
  31 #define IXSSPACC_H
  32
  33 #ifdef __ixp46X
  34
  35 #include "IxOsal.h"
  36
  37 /*
  38  * Section for enum
  39  */
  40 /**
  41  * @ingroup IxSspAcc
  42  *
  43  * @enum IxSspAccDataSize
  44  *
  45  * @brief The data sizes in bits that are supported by the protocol
  46  */
  47 typedef enum
  48 {
  49         DATA_SIZE_TOO_SMALL = 0x2,
  50         DATA_SIZE_4 = 0x3,
  51         DATA_SIZE_5,
  52         DATA_SIZE_6,
  53         DATA_SIZE_7,
  54         DATA_SIZE_8,
  55         DATA_SIZE_9,
  56         DATA_SIZE_10,
  57         DATA_SIZE_11,
  58         DATA_SIZE_12,
  59         DATA_SIZE_13,
  60         DATA_SIZE_14,
  61         DATA_SIZE_15,
  62         DATA_SIZE_16,
  63         DATA_SIZE_TOO_BIG
  64 } IxSspAccDataSize;
  65
  66 /**
  67  * @ingroup IxSspAcc
  68  *
  69  * @enum IxSspAccPortStatus
  70  *
  71  * @brief The status of the SSP port to be set to enable/disable
  72  */
  73 typedef enum
  74 {
  75         SSP_PORT_DISABLE = 0x0,
  76         SSP_PORT_ENABLE,
  77         INVALID_SSP_PORT_STATUS
  78 } IxSspAccPortStatus;
  79
  80 /**
  81  * @ingroup IxSspAcc
  82  *
  83  * @enum IxSspAccFrameFormat
  84  *
  85  * @brief The frame format that is to be used - SPI, SSP, or Microwire
  86  */
  87 typedef enum
  88 {
  89         SPI_FORMAT = 0x0,
  90         SSP_FORMAT,
  91         MICROWIRE_FORMAT,
  92         INVALID_FORMAT
  93 } IxSspAccFrameFormat;
  94
  95 /**
  96  * @ingroup IxSspAcc
  97  *
  98  * @enum IxSspAccClkSource
  99  *
 100  * @brief The source to produce the SSP serial clock
 101  */
 102 typedef enum
 103 {
 104         ON_CHIP_CLK = 0x0,
 105         EXTERNAL_CLK,
 106         INVALID_CLK_SOURCE
 107 } IxSspAccClkSource;
 108
 109 /**
 110  * @ingroup IxSspAcc
 111  *
 112  * @enum IxSspAccSpiSclkPhase
 113  *
 114  * @brief The SPI SCLK Phase:
 115  * 0 - SCLK is inactive one cycle at the start of a frame and 1/2 cycle at the
 116  *              end of a frame.
 117  * 1 - SCLK is inactive 1/2 cycle at the start of a frame and one cycle at the
 118  *              end of a frame.
 119  */
 120 typedef enum
 121 {
 122         START_ONE_END_HALF = 0x0,
 123         START_HALF_END_ONE,
 124         INVALID_SPI_PHASE
 125 } IxSspAccSpiSclkPhase;
 126
 127 /**
 128  * @ingroup IxSspAcc
 129  *
 130  * @enum IxSspAccSpiSclkPolarity
 131  *
 132  * @brief The SPI SCLK Polarity can be set to either low or high.
 133  */
 134 typedef enum
 135 {
 136         SPI_POLARITY_LOW = 0x0,
 137         SPI_POLARITY_HIGH,
 138         INVALID_SPI_POLARITY
 139 } IxSspAccSpiSclkPolarity;
 140
 141 /**
 142  * @ingroup IxSspAcc
 143  *
 144  * @enum IxSspAccMicrowireCtlWord
 145  *
 146  * @brief The Microwire control word can be either 8 or 16 bit.
 147  */
 148 typedef enum
 149 {
 150         MICROWIRE_8_BIT = 0x0,
 151         MICROWIRE_16_BIT,
 152         INVALID_MICROWIRE_CTL_WORD
 153 } IxSspAccMicrowireCtlWord;
 154
 155 /**
 156  * @ingroup IxSspAcc
 157  *
 158  * @enum IxSspAccFifoThreshold
 159  *
 160  * @brief The threshold in frames (each frame is defined by IxSspAccDataSize)
 161  *                      that can be set for the FIFO to trigger a threshold exceed when
 162  *                      checking with the ExceedThresholdCheck functions or an interrupt
 163  *                      when it is enabled.
 164  */
 165 typedef enum
 166 {
 167         FIFO_TSHLD_1 =  0x0,
 168         FIFO_TSHLD_2,
 169         FIFO_TSHLD_3,
 170         FIFO_TSHLD_4,
 171         FIFO_TSHLD_5,
 172         FIFO_TSHLD_6,
 173         FIFO_TSHLD_7,
 174         FIFO_TSHLD_8,
 175         FIFO_TSHLD_9,
 176         FIFO_TSHLD_10,
 177         FIFO_TSHLD_11,
 178         FIFO_TSHLD_12,
 179         FIFO_TSHLD_13,
 180         FIFO_TSHLD_14,
 181         FIFO_TSHLD_15,
 182         FIFO_TSHLD_16,
 183         INVALID_FIFO_TSHLD
 184 } IxSspAccFifoThreshold;
 185
 186 /**
 187  * @ingroup IxSspAcc
 188  *
 189  * @enum IX_SSP_STATUS
 190  *
 191  * @brief The statuses that can be returned in a SSP Serial Port Access
 192  */
 193 typedef enum
 194 {
 195         IX_SSP_SUCCESS = IX_SUCCESS, /**< Success status */
 196         IX_SSP_FAIL, /**< Fail status */
 197         IX_SSP_RX_FIFO_OVERRUN_HANDLER_MISSING, /**<
 198                                                 Rx FIFO Overrun handler is NULL. */
 199         IX_SSP_RX_FIFO_HANDLER_MISSING, /**<
 200                                         Rx FIFO threshold hit or above handler is NULL
 201                                         */
 202         IX_SSP_TX_FIFO_HANDLER_MISSING, /**<
 203                                         Tx FIFO threshold hit or below handler is NULL
 204                                         */
 205         IX_SSP_FIFO_NOT_EMPTY_FOR_SETTING_CTL_CMD, /**<
 206                                         Tx FIFO not empty and therefore microwire
 207                                         control command size setting is not allowed.    */
 208         IX_SSP_INVALID_FRAME_FORMAT_ENUM_VALUE, /**<
 209                                         frame format selected is invalid. */
 210         IX_SSP_INVALID_DATA_SIZE_ENUM_VALUE, /**<
 211                                         data size selected is invalid. */
 212         IX_SSP_INVALID_CLOCK_SOURCE_ENUM_VALUE, /**<
 213                                         source clock selected is invalid. */
 214         IX_SSP_INVALID_TX_FIFO_THRESHOLD_ENUM_VALUE, /**<
 215                                         Tx FIFO threshold selected is invalid. */
 216         IX_SSP_INVALID_RX_FIFO_THRESHOLD_ENUM_VALUE, /**<
 217                                         Rx FIFO threshold selected is invalid. */
 218         IX_SSP_INVALID_SPI_PHASE_ENUM_VALUE, /**<
 219                                         SPI phase selected is invalid. */
 220         IX_SSP_INVALID_SPI_POLARITY_ENUM_VALUE, /**<
 221                                         SPI polarity selected is invalid. */
 222         IX_SSP_INVALID_MICROWIRE_CTL_CMD_ENUM_VALUE, /**<
 223                                         Microwire control command selected is invalid
 224                                         */
 225         IX_SSP_INT_UNBIND_FAIL, /**< Interrupt unbind fail to unbind SSP
 226                         interrupt */
 227         IX_SSP_INT_BIND_FAIL, /**< Interrupt bind fail during init */
 228         IX_SSP_RX_FIFO_NOT_EMPTY, /**<
 229                                         Rx FIFO not empty while trying to change data
 230                                         size. */
 231         IX_SSP_TX_FIFO_NOT_EMPTY, /**<
 232                                         Rx FIFO not empty while trying to change data
 233                                         size or microwire control command size. */
 234         IX_SSP_POLL_MODE_BLOCKING, /**<
 235                                         poll mode selected blocks interrupt mode from
 236                                         being selected. */
 237         IX_SSP_TX_FIFO_HIT_BELOW_THRESHOLD, /**<
 238                                         Tx FIFO level hit or below threshold. */
 239         IX_SSP_TX_FIFO_EXCEED_THRESHOLD, /**<
 240                                         Tx FIFO level exceeded threshold. */
 241         IX_SSP_RX_FIFO_HIT_ABOVE_THRESHOLD, /**<
 242                                         Rx FIFO level hit or exceeded threshold. */
 243         IX_SSP_RX_FIFO_BELOW_THRESHOLD, /**<
 244                                         Rx FIFO level below threshold. */
 245         IX_SSP_BUSY, /**< SSP is busy. */
 246         IX_SSP_IDLE, /**< SSP is idle. */
 247         IX_SSP_OVERRUN_OCCURRED, /**<
 248                                         SSP has experienced an overrun. */
 249         IX_SSP_NO_OVERRUN, /**<
 250                                         SSP did not experience an overrun. */
 251         IX_SSP_NOT_SUPORTED, /**< hardware does not support SSP */
 252         IX_SSP_NOT_INIT, /**< SSP Access not intialized */
 253         IX_SSP_NULL_POINTER /**< parameter passed in is NULL */
 254 } IX_SSP_STATUS;
 255
 256 /**
 257  * @ingroup IxSspAcc
 258  *
 259  * @brief SSP Rx FIFO Overrun handler
 260  *
 261  * This function is called for the client to handle Rx FIFO Overrun that occurs
 262  * in the SSP hardware
 263  */
 264 typedef void (*RxFIFOOverrunHandler)(void);
 265
 266 /**
 267  * @ingroup IxSspAcc
 268  *
 269  * @brief SSP Rx FIFO Threshold hit or above handler
 270  *
 271  * This function is called for the client to handle Rx FIFO threshold hit or
 272  * or above that occurs in the SSP hardware
 273  */
 274 typedef void (*RxFIFOThresholdHandler)(void);
 275
 276 /**
 277  * @ingroup IxSspAcc
 278  *
 279  * @brief SSP Tx FIFO Threshold hit or below handler
 280  *
 281  * This function is called for the client to handle Tx FIFO threshold hit or
 282  * or below that occurs in the SSP hardware
 283  */
 284 typedef void (*TxFIFOThresholdHandler)(void);
 285
 286
 287 /*
 288  * Section for struct
 289  */
 290 /**
 291  * @ingroup IxSspAcc
 292  *
 293  * @brief contains all the variables required to initialize the SSP serial port
 294  *              hardware.
 295  *
 296  * Structure to be filled and used for calling initialization
 297  */
 298 typedef struct
 299 {
 300         IxSspAccFrameFormat FrameFormatSelected;/**<Select between SPI, SSP and
 301                                                                                                 Microwire. */
 302         IxSspAccDataSize DataSizeSelected;              /**<Select between 4 and 16. */
 303         IxSspAccClkSource ClkSourceSelected;    /**<Select clock source to be
 304                                                                                                 on-chip or external. */
 305         IxSspAccFifoThreshold TxFIFOThresholdSelected;
 306                                                                                         /**<Select Tx FIFO threshold
 307                                                                                                 between 1 to 16. */
 308         IxSspAccFifoThreshold RxFIFOThresholdSelected;
 309                                                                                         /**<Select Rx FIFO threshold
 310                                                                                                 between 1 to 16. */
 311         BOOL RxFIFOIntrEnable;                                  /**<Enable/disable Rx FIFO
 312                                                                                                 threshold interrupt. Disabling
 313                                                                                                 this interrupt will require
 314                                                                                                 the use of the polling function
 315                                                                                                 RxFIFOExceedThresholdCheck. */
 316         BOOL TxFIFOIntrEnable;                                  /**<Enable/disable Tx FIFO
 317                                                                                                 threshold interrupt. Disabling
 318                                                                                                 this interrupt will require
 319                                                                                                 the use of the polling function
 320                                                                                                 TxFIFOExceedThresholdCheck. */
 321         RxFIFOThresholdHandler RxFIFOThsldHdlr; /**<Pointer to function to handle
 322                                                                                                 a Rx FIFO interrupt. */
 323         TxFIFOThresholdHandler TxFIFOThsldHdlr; /**<Pointer to function to handle
 324                                                                                                 a Tx FIFO interrupt. */
 325         RxFIFOOverrunHandler RxFIFOOverrunHdlr; /**<Pointer to function to handle
 326                                                                                                 a Rx FIFO overrun interrupt. */
 327         BOOL LoopbackEnable;                                    /**<Select operation mode to be
 328                                                                                                 normal or loopback mode. */
 329         IxSspAccSpiSclkPhase SpiSclkPhaseSelected;
 330                                                                                         /**<Select SPI SCLK phase to start
 331                                                                                                 with one inactive cycle and end
 332                                                                                                 with 1/2 inactive cycle or
 333                                                                                                 start with 1/2 inactive cycle
 334                                                                                                 and end with one inactive
 335                                                                                                 cycle. (Only used in
 336                                                                                                 SPI format). */
 337         IxSspAccSpiSclkPolarity SpiSclkPolaritySelected;
 338                                                                                         /**<Select SPI SCLK idle state
 339                                                                                                 to be low or high. (Only used in
 340                                                                                                 SPI format). */
 341         IxSspAccMicrowireCtlWord MicrowireCtlWordSelected;
 342                                                                                         /**<Select Microwire control
 343                                                                                                 format to be 8 or 16-bit. (Only
 344                                                                                                 used in Microwire format). */
 345         UINT8 SerialClkRateSelected;                    /**<Select between 0 (1.8432Mbps)
 346                                                                                                 and 255 (7.2Kbps). The
 347                                                                                                 formula used is Bit rate =
 348                                                                                                 3.6864x10^6 /
 349                                                                                                 (2 x (SerialClkRateSelect + 1))
 350                                                                                                 */
 351 } IxSspInitVars;
 352
 353 /**
 354  * @ingroup IxSspAcc
 355  *
 356  * @brief contains counters of the SSP statistics
 357  *
 358  * Structure contains all values of counters and associated overflows.
 359  */
 360 typedef struct
 361 {
 362         UINT32 ixSspRcvCounter;         /**<Total frames received. */
 363         UINT32 ixSspXmitCounter;        /**<Total frames transmitted. */
 364         UINT32 ixSspOverflowCounter;/**<Total occurrences of overflow. */
 365 } IxSspAccStatsCounters;
 366
 367
 368 /*
 369  * Section for prototypes interface functions
 370  */
 371
 372 /**
 373  * @ingroup IxSspAcc
 374  *
 375  * @fn ixSspAccInit (
 376         IxSspInitVars *initVarsSelected);
 377  *
 378  * @brief Initializes the SSP Access module.
 379  *
 380  * @param "IxSspAccInitVars [in] *initVarsSelected" - struct containing required
 381  *                      variables for initialization
 382  *
 383  * Global Data  :
 384  *              - None.
 385  *
 386  * This API will initialize the SSP Serial Port hardware to the user specified
 387  * configuration. Then it will enable the SSP Serial Port.
 388  * *NOTE*: Once interrupt or polling mode is selected, the mode cannot be
 389  * changed via the interrupt enable/disable function but the init needs to be
 390  * called again to change it.
 391  *
 392  * @return
 393  *      - IX_SSP_SUCCESS - Successfully initialize and enable the SSP
 394  *                                                                      serial port.
 395  *              - IX_SSP_RX_FIFO_HANDLER_MISSING - interrupt mode is selected but RX FIFO
 396  *                                                                      handler pointer is NULL
 397  *              - IX_SSP_TX_FIFO_HANDLER_MISSING - interrupt mode is selected but TX FIFO
 398  *                                                                      handler pointer is NULL
 399  *              - IX_SSP_RX_FIFO_OVERRUN_HANDLER_MISSING - interrupt mode is selected but
 400  *                                                                      RX FIFO Overrun handler pointer is NULL
 401  *              - IX_SSP_RX_FIFO_NOT_EMPTY - Rx FIFO not empty, data size change is not
 402  *                                              allowed.
 403  *              - IX_SSP_TX_FIFO_NOT_EMPTY - Tx FIFO not empty, data size change is not
 404  *                                              allowed.
 405  *              - IX_SSP_INVALID_FRAME_FORMAT_ENUM_VALUE - frame format selected is invalid
 406  *              - IX_SSP_INVALID_DATA_SIZE_ENUM_VALUE - data size selected is invalid
 407  *              - IX_SSP_INVALID_CLOCK_SOURCE_ENUM_VALUE - clock source selected is invalid
 408  *              - IX_SSP_INVALID_TX_FIFO_THRESHOLD_ENUM_VALUE - Tx FIFO threshold level
 409  *                                                                      selected is invalid
 410  *              - IX_SSP_INVALID_RX_FIFO_THRESHOLD_ENUM_VALUE - Rx FIFO threshold level
 411  *                                                                      selected is invalid
 412  *              - IX_SSP_INVALID_SPI_PHASE_ENUM_VALUE - SPI phase selected is invalid
 413  *              - IX_SSP_INVALID_SPI_POLARITY_ENUM_VALUE - SPI polarity selected is invalid
 414  *              - IX_SSP_INVALID_MICROWIRE_CTL_CMD_ENUM_VALUE - microwire control command
 415  *                                                                      size is invalid
 416  *      - IX_SSP_INT_UNBIND_FAIL - interrupt handler failed to unbind SSP interrupt
 417  *              - IX_SSP_INT_BIND_FAIL - interrupt handler failed to bind to SSP interrupt
 418  *                                                                      hardware trigger
 419  *      - IX_SSP_NOT_SUPORTED - hardware does not support SSP
 420  *      - IX_SSP_NULL_POINTER - parameter passed in is NULL
 421  *
 422  * @li   Reentrant    : yes
 423  * @li   ISR Callable : yes
 424  *
 425  */
 426 PUBLIC IX_SSP_STATUS
 427 ixSspAccInit (IxSspInitVars *initVarsSelected);
 428
 429 /**
 430  * @ingroup IxSspAcc
 431  *
 432  * @fn ixSspAccUninit (
 433         void)
 434  *
 435  * @brief Un-initializes the SSP Serial Port Access component
 436  *
 437  * @param - None
 438  *
 439  * Global Data  :
 440  *              - None.
 441  *
 442  * This API will disable the SSP Serial Port hardware. The client can call the
 443  * init function again if they wish to enable the SSP.
 444  *
 445  * @return
 446  *      - IX_SSP_SUCCESS - successfully uninit SSP component
 447  *      - IX_SSP_INT_UNBIND_FAIL - interrupt handler failed to unbind SSP interrupt
 448  *
 449  * @li   Reentrant    : yes
 450  * @li   ISR Callable : yes
 451  *
 452  */
 453 PUBLIC IX_SSP_STATUS
 454 ixSspAccUninit (void);
 455
 456 /**
 457  * @ingroup IxSspAcc
 458  *
 459  * @fn ixSspAccFIFODataSubmit (
 460         UINT16 *data,
 461         UINT32 amtOfData)
 462  *
 463  * @brief Inserts data into the SSP Serial Port's FIFO
 464  *
 465  * @param       "UINT16 [in] *data" - pointer to the location to transmit the data
 466  *                              from
 467  *                      "UINT32 [in] amtOfData" - number of data to be transmitted.
 468  *
 469  * Global Data  :
 470  *              - None.
 471  *
 472  * This API will insert the amount of data specified by "amtOfData" from buffer
 473  * pointed to by "data" into the FIFO to be transmitted by the hardware.
 474  *
 475  * @return
 476  *      - IX_SSP_SUCCESS - Data inserted successfully into FIFO
 477  *              - IX_SSP_FAIL - FIFO insufficient space
 478  *              - IX_SSP_NULL_POINTER - data pointer passed by client is NULL
 479  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 480  *
 481  * @li   Reentrant    : yes
 482  * @li   ISR Callable : yes
 483  *
 484  */
 485 PUBLIC IX_SSP_STATUS
 486 ixSspAccFIFODataSubmit (
 487         UINT16* data,
 488         UINT32 amtOfData);
 489
 490 /**
 491  * @ingroup IxSspAcc
 492  *
 493  * @fn ixSspAccFIFODataReceive (
 494         UINT16 *data,
 495         UINT32 amtOfData)
 496  *
 497  * @brief Extract data from the SSP Serial Port's FIFO
 498  *
 499  * @param       "UINT16 [in] *data" - pointer to the location to receive the data into
 500  *                      "UINT32 [in] amtOfData" - number of data to be received.
 501  *
 502  * Global Data  :
 503  *              - None.
 504  *
 505  * This API will extract the amount of data specified by "amtOfData" from the
 506  * FIFO already received by the hardware into the buffer pointed to by "data".
 507  *
 508  * @return
 509  *      - IX_SSP_SUCCESS - Data extracted successfully from FIFO
 510  *              - IX_SSP_FAIL - FIFO has no data
 511  *              - IX_SSP_NULL_POINTER - data pointer passed by client is NULL
 512  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 513  *
 514  * @li   Reentrant    : yes
 515  * @li   ISR Callable : yes
 516  *
 517  */
 518 PUBLIC IX_SSP_STATUS
 519 ixSspAccFIFODataReceive (
 520         UINT16* data,
 521         UINT32 amtOfData);
 522
 523
 524 /**
 525  * Polling Functions
 526  */
 527
 528 /**
 529  * @ingroup IxSspAcc
 530  *
 531  * @fn ixSspAccTxFIFOHitOrBelowThresholdCheck (
 532                 void)
 533  *
 534  * @brief Check if the Tx FIFO threshold has been hit or fallen below.
 535  *
 536  * @param - None
 537  *
 538  * Global Data  :
 539  *              - None.
 540  *
 541  * This API will return whether the Tx FIFO threshold has been exceeded or not
 542  *
 543  * @return
 544  *      - IX_SSP_TX_FIFO_HIT_BELOW_THRESHOLD - Tx FIFO level hit or below threshold .
 545  *              - IX_SSP_TX_FIFO_EXCEED_THRESHOLD - Tx FIFO level exceeded threshold.
 546  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 547  *
 548  * @li   Reentrant    : yes
 549  * @li   ISR Callable : yes
 550  *
 551  */
 552 PUBLIC IX_SSP_STATUS
 553 ixSspAccTxFIFOHitOrBelowThresholdCheck (
 554         void);
 555
 556 /**
 557  * @ingroup IxSspAcc
 558  *
 559  * @fn ixSspAccRxFIFOHitOrAboveThresholdCheck (
 560                 void)
 561  *
 562  * @brief Check if the Rx FIFO threshold has been hit or exceeded.
 563  *
 564  * @param - None
 565  *
 566  * Global Data  :
 567  *              - None.
 568  *
 569  * This API will return whether the Rx FIFO level is below threshold or not
 570  *
 571  * @return
 572  *      - IX_SSP_RX_FIFO_HIT_ABOVE_THRESHOLD - Rx FIFO level hit or exceeded threshold
 573  *              - IX_SSP_RX_FIFO_BELOW_THRESHOLD - Rx FIFO level below threshold
 574  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 575  *
 576  * @li   Reentrant    : yes
 577  * @li   ISR Callable : yes
 578  *
 579  */
 580 PUBLIC IX_SSP_STATUS
 581 ixSspAccRxFIFOHitOrAboveThresholdCheck (
 582         void);
 583
 584
 585 /**
 586  * Configuration functions
 587  *
 588  * NOTE: These configurations are not required to be called once init is called
 589  * unless configurations need to be changed on the fly.
 590  */
 591
 592 /**
 593  * @ingroup IxSspAcc
 594  *
 595  * @fn ixSspAccSSPPortStatusSet (
 596         IxSspAccPortStatus portStatusSelected)
 597  *
 598  * @brief Enables/disables the SSP Serial Port hardware.
 599  *
 600  * @param "IxSspAccPortStatus [in] portStatusSelected" - Set the SSP port to
 601  *                      enable or disable
 602  *
 603  * Global Data  :
 604  *              - None.
 605  *
 606  * This API will enable/disable the SSP Serial Port hardware.
 607  * NOTE: This function is called by init to enable the SSP after setting up the
 608  * configurations and by uninit to disable the SSP.
 609  *
 610  * @return
 611  *      - IX_SSP_SUCCESS - Port status set with valid enum value
 612  *              - IX_SSP_FAIL - invalid enum value
 613  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 614  *
 615  * @li   Reentrant    : yes
 616  * @li   ISR Callable : yes
 617  *
 618  */
 619 PUBLIC IX_SSP_STATUS
 620 ixSspAccSSPPortStatusSet (
 621         IxSspAccPortStatus portStatusSelected);
 622
 623 /**
 624  * @ingroup IxSspAcc
 625  *
 626  * @fn ixSspAccFrameFormatSelect (
 627         IxSspAccFrameFormat frameFormatSelected)
 628  *
 629  * @brief Sets the frame format for the SSP Serial Port hardware
 630  *
 631  * @param "IxSspAccFrameFormat [in] frameFormatSelected" - The frame format of
 632  *                      SPI, SSP or Microwire can be selected as the format
 633  *
 634  * Global Data  :
 635  *              - None.
 636  *
 637  * This API will set the format for the transfers via user input.
 638  * *NOTE*: The SSP hardware will be disabled to clear the FIFOs. Then its
 639  * previous state (enabled/disabled) restored after changing the format.
 640  *
 641  * @return
 642  *      - IX_SSP_SUCCESS - frame format set with valid enum value
 643  *              - IX_SSP_INVALID_FRAME_FORMAT_ENUM_VALUE - invalid frame format value
 644  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 645  *
 646  * @li   Reentrant    : yes
 647  * @li   ISR Callable : yes
 648  *
 649  */
 650 PUBLIC IX_SSP_STATUS
 651 ixSspAccFrameFormatSelect (
 652         IxSspAccFrameFormat frameFormatSelected);
 653
 654 /**
 655  * @ingroup IxSspAcc
 656  *
 657  * @fn ixSspAccDataSizeSelect (
 658         IxSspAccDataSize dataSizeSelected)
 659  *
 660  * @brief Sets the data size for transfers
 661  *
 662  * @param "IxSspAccDataSize [in] dataSizeSelected" - The data size between 4
 663  *                      and 16 that can be selected for data transfers
 664  *
 665  * Global Data  :
 666  *              - None.
 667  *
 668  * This API will set the data size for the transfers via user input. It will
 669  * disallow the change of the data size if either of the Rx/Tx FIFO is not
 670  * empty to prevent data loss.
 671  * *NOTE*: The SSP port will be disabled if the FIFOs are found to be empty and
 672  *                      if between the check and disabling of the SSP (which clears the
 673  *                      FIFOs) data is received into the FIFO, it might be lost.
 674  * *NOTE*: The FIFOs can be cleared by disabling the SSP Port if necessary to
 675  *                      force the data size change.
 676  *
 677  * @return
 678  *      - IX_SSP_SUCCESS - data size set with valid enum value
 679  *              - IX_SSP_RX_FIFO_NOT_EMPTY - Rx FIFO not empty, data size change is not
 680  *                                                      allowed.
 681  *              - IX_SSP_TX_FIFO_NOT_EMPTY - Tx FIFO not empty, data size change is not
 682  *                                                      allowed.
 683  *              - IX_SSP_INVALID_DATA_SIZE_ENUM_VALUE - invalid enum value
 684  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 685  *
 686  * @li   Reentrant    : yes
 687  * @li   ISR Callable : yes
 688  *
 689  */
 690 PUBLIC IX_SSP_STATUS
 691 ixSspAccDataSizeSelect (
 692         IxSspAccDataSize dataSizeSelected);
 693
 694 /**
 695  * @ingroup IxSspAcc
 696  *
 697  * @fn ixSspAccClockSourceSelect(
 698         IxSspAccClkSource clkSourceSelected)
 699  *
 700  * @brief Sets the clock source of the SSP Serial Port hardware
 701  *
 702  * @param "IxSspAccClkSource [in] clkSourceSelected" - The clock source from
 703  *                      either external source on on-chip can be selected as the source
 704  *
 705  * Global Data  :
 706  *              - None.
 707  *
 708  * This API will set the clock source for the transfers via user input.
 709  *
 710  * @return
 711  *      - IX_SSP_SUCCESS - clock source set with valid enum value
 712  *              - IX_SSP_INVALID_CLOCK_SOURCE_ENUM_VALUE - invalid enum value
 713  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 714  *
 715  * @li   Reentrant    : yes
 716  * @li   ISR Callable : yes
 717  *
 718  */
 719 PUBLIC IX_SSP_STATUS
 720 ixSspAccClockSourceSelect (
 721         IxSspAccClkSource clkSourceSelected);
 722
 723 /**
 724  * @ingroup IxSspAcc
 725  *
 726  * @fn ixSspAccSerialClockRateConfigure (
 727         UINT8 serialClockRateSelected)
 728  *
 729  * @brief Sets the on-chip Serial Clock Rate of the SSP Serial Port hardware.
 730  *
 731  * @param "UINT8 [in] serialClockRateSelected" - The serial clock rate that can
 732  *                      be set is between 7.2Kbps and 1.8432Mbps. The formula used is
 733  *                      Bit rate = 3.6864x10^6 / (2 x (SerialClockRateSelected + 1))
 734  *
 735  * Global Data  :
 736  *              - None.
 737  *
 738  * This API will set the serial clock rate for the transfers via user input.
 739  *
 740  * @return
 741  *      - IX_SSP_SUCCESS - Serial clock rate configured successfully
 742  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 743  *
 744  * @li   Reentrant    : yes
 745  * @li   ISR Callable : yes
 746  *
 747  */
 748 PUBLIC IX_SSP_STATUS
 749 ixSspAccSerialClockRateConfigure (
 750         UINT8 serialClockRateSelected);
 751
 752 /**
 753  * @ingroup IxSspAcc
 754  *
 755  * @fn ixSspAccRxFIFOIntEnable (
 756         RxFIFOThresholdHandler rxFIFOIntrHandler)
 757  *
 758  * @brief Enables service request interrupt whenever the Rx FIFO hits its
 759  *              threshold
 760  *
 761  * @param "void [in] *rxFIFOIntrHandler(UINT32)" - function pointer to the
 762  *                              interrupt handler for the Rx FIFO exceeded.
 763  *
 764  * Global Data  :
 765  *              - None.
 766  *
 767  * This API will enable the service request interrupt for the Rx FIFO
 768  *
 769  * @return
 770  *      - IX_SSP_SUCCESS - Rx FIFO level interrupt enabled successfully
 771  *              - IX_SSP_RX_FIFO_HANDLER_MISSING - missing handler for Rx FIFO level interrupt
 772  *              - IX_SSP_POLL_MODE_BLOCKING - poll mode is selected at init, interrupt not
 773  *                              allowed to be enabled. Use init to enable interrupt mode.
 774  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 775  *
 776  * @li   Reentrant    : yes
 777  * @li   ISR Callable : yes
 778  *
 779  */
 780 PUBLIC IX_SSP_STATUS
 781 ixSspAccRxFIFOIntEnable (
 782         RxFIFOThresholdHandler rxFIFOIntrHandler);
 783
 784 /**
 785  * @ingroup IxSspAcc
 786  *
 787  * @fn ixSspAccRxFIFOIntDisable (
 788         void)
 789  *
 790  * @brief Disables service request interrupt of the Rx FIFO.
 791  *
 792  * @param - None
 793  *
 794  * Global Data  :
 795  *              - None.
 796  *
 797  * This API will disable the service request interrupt of the Rx FIFO.
 798  *
 799  * @return
 800  *              - IX_SSP_SUCCESS - Rx FIFO Interrupt disabled successfully
 801  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 802  *
 803  * @li   Reentrant    : yes
 804  * @li   ISR Callable : yes
 805  *
 806  */
 807 PUBLIC IX_SSP_STATUS
 808 ixSspAccRxFIFOIntDisable (
 809         void);
 810
 811 /**
 812  * @ingroup IxSspAcc
 813  *
 814  * @fn ixSspAccTxFIFOIntEnable (
 815         TxFIFOThresholdHandler txFIFOIntrHandler)
 816  *
 817  * @brief Enables service request interrupt of the Tx FIFO.
 818  *
 819  * @param "void [in] *txFIFOIntrHandler(UINT32)" - function pointer to the
 820  *                              interrupt handler for the Tx FIFO exceeded.
 821  *
 822  * Global Data  :
 823  *              - None.
 824  *
 825  * This API will enable the service request interrupt of the Tx FIFO.
 826  *
 827  * @return
 828  *      - IX_SSP_SUCCESS - Tx FIFO level interrupt enabled successfully
 829  *              - IX_SSP_TX_FIFO_HANDLER_MISSING - missing handler for Tx FIFO level interrupt
 830  *              - IX_SSP_POLL_MODE_BLOCKING - poll mode is selected at init, interrupt not
 831  *                              allowed to be enabled. Use init to enable interrupt mode.
 832  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 833  *
 834  * @li   Reentrant    : yes
 835  * @li   ISR Callable : yes
 836  *
 837  */
 838 PUBLIC IX_SSP_STATUS
 839 ixSspAccTxFIFOIntEnable (
 840         TxFIFOThresholdHandler txFIFOIntrHandler);
 841
 842 /**
 843  * @ingroup IxSspAcc
 844  *
 845  * @fn ixSspAccTxFIFOIntDisable (
 846         void)
 847  *
 848  * @brief Disables service request interrupt of the Tx FIFO
 849  *
 850  * @param - None
 851  *
 852  * Global Data  :
 853  *              - None.
 854  *
 855  * This API will disable the service request interrupt of the Tx FIFO
 856  *
 857  * @return
 858  *              - IX_SSP_SUCCESS - Tx FIFO Interrupt disabled successfuly.
 859  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 860  *
 861  * @li   Reentrant    : yes
 862  * @li   ISR Callable : yes
 863  *
 864  */
 865 PUBLIC IX_SSP_STATUS
 866 ixSspAccTxFIFOIntDisable (
 867         void);
 868
 869 /**
 870  * @ingroup IxSspAcc
 871  *
 872  * @fn ixSspAccLoopbackEnable (
 873         BOOL loopbackEnable)
 874  *
 875  * @brief Enables/disables the loopback mode
 876  *
 877  * @param "BOOL [in] loopbackEnable" - true to enable and false to disable.
 878  *
 879  * Global Data  :
 880  *              - None.
 881  *
 882  * This API will set the mode of operation to either loopback or normal mode
 883  * according to the user input.
 884  *
 885  * @return
 886  *              - IX_SSP_SUCCESS - Loopback enabled successfully
 887  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 888  *
 889  * @li   Reentrant    : yes
 890  * @li   ISR Callable : yes
 891  *
 892  */
 893 PUBLIC IX_SSP_STATUS
 894 ixSspAccLoopbackEnable (
 895         BOOL loopbackEnable);
 896
 897 /**
 898  * @ingroup IxSspAcc
 899  *
 900  * @fn ixSspAccSpiSclkPolaritySet (
 901         IxSspAccSpiSclkPolarity spiSclkPolaritySelected)
 902  *
 903  * @brief Sets the SPI SCLK Polarity to Low or High
 904  *
 905  * @param - "IxSspAccSpiSclkPolarity [in] spiSclkPolaritySelected" - SPI SCLK
 906  *                              polarity that can be selected to either high or low
 907  *
 908  * Global Data  :
 909  *              - None.
 910  *
 911  * This API is only used for the SPI frame format and will set the SPI SCLK polarity
 912  * to either low or high
 913  *
 914  * @return
 915  *      - IX_SSP_SUCCESS - SPI Sclk polarity set with valid enum value
 916  *              - IX_SSP_INVALID_SPI_POLARITY_ENUM_VALUE - invalid SPI polarity value
 917  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 918  *
 919  * @li   Reentrant    : yes
 920  * @li   ISR Callable : yes
 921  *
 922  */
 923 PUBLIC IX_SSP_STATUS
 924 ixSspAccSpiSclkPolaritySet (
 925         IxSspAccSpiSclkPolarity spiSclkPolaritySelected);
 926
 927 /**
 928  * @ingroup IxSspAcc
 929  *
 930  * @fn ixSspAccSpiSclkPhaseSet (
 931         IxSspAccSpiSclkPhase spiSclkPhaseSelected)
 932  *
 933  * @brief Sets the SPI SCLK Phase
 934  *
 935  * @param "IxSspAccSpiSclkPhase [in] spiSclkPhaseSelected" - Phase of either
 936  *                      the SCLK is inactive one cycle at the start of a frame and 1/2
 937  *                      cycle at the end of a frame, OR
 938  *                      the SCLK is inactive 1/2 cycle at the start of a frame and one
 939  *                      cycle at the end of a frame.
 940  *
 941  * Global Data  :
 942  *              - IX_SSP_SUCCESS - SPI Sclk phase set with valid enum value
 943  *              - IX_SSP_INVALID_SPI_PHASE_ENUM_VALUE - invalid SPI phase value
 944  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 945  *
 946  * This API is only used for the SPI frame format and will set the SPI SCLK
 947  * phase according to user input.
 948  *
 949  * @return
 950  *      - None
 951  *
 952  * @li   Reentrant    : yes
 953  * @li   ISR Callable : yes
 954  *
 955  */
 956 PUBLIC IX_SSP_STATUS
 957 ixSspAccSpiSclkPhaseSet (
 958         IxSspAccSpiSclkPhase spiSclkPhaseSelected);
 959
 960 /**
 961  * @ingroup IxSspAcc
 962  *
 963  * @fn ixSspAccMicrowireControlWordSet (
 964         IxSspAccMicrowireCtlWord microwireCtlWordSelected)
 965  *
 966  * @brief Sets the Microwire control word to 8 or 16 bit format
 967  *
 968  * @param "IxSspAccMicrowireCtlWord [in] microwireCtlWordSelected" - Microwire
 969  *                      control word format can be either 8 or 16 bit format
 970  *
 971  * Global Data  :
 972  *              - None.
 973  *
 974  * This API is only used for the Microwire frame format and will set the
 975  * control word to 8 or 16 bit format
 976  *
 977  * @return
 978  *      - IX_SSP_SUCCESS - Microwire Control Word set with valid enum value
 979  *              - IX_SSP_TX_FIFO_NOT_EMPTY - Tx FIFO not empty, data size change is not
 980  *                                                      allowed.
 981  *              - IX_SSP_INVALID_MICROWIRE_CTL_CMD_ENUM_VALUE - invalid enum value
 982  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
 983  *
 984  * @li   Reentrant    : yes
 985  * @li   ISR Callable : yes
 986  *
 987  */
 988 PUBLIC IX_SSP_STATUS
 989 ixSspAccMicrowireControlWordSet (
 990         IxSspAccMicrowireCtlWord microwireCtlWordSelected);
 991
 992 /**
 993  * @ingroup IxSspAcc
 994  *
 995  * @fn ixSspAccTxFIFOThresholdSet (
 996         IxSspAccFifoThreshold txFIFOThresholdSelected)
 997  *
 998  * @brief Sets the Tx FIFO Threshold.
 999  *
1000  * @param "IxSspAccFifoThreshold [in] txFIFOThresholdSelected" - Threshold that
1001  *              is set for a Tx FIFO service request to be triggered
1002  *
1003  * Global Data  :
1004  *              - None.
1005  *
1006  * This API will set the threshold for a Tx FIFO threshold to be triggered
1007  *
1008  * @return
1009  *      - IX_SSP_SUCCESS - Tx FIFO Threshold set with valid enum value
1010  *              - IX_SSP_INVALID_TX_FIFO_THRESHOLD_ENUM_VALUE - invalid enum value
1011  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
1012  *
1013  * @li   Reentrant    : yes
1014  * @li   ISR Callable : yes
1015  *
1016  */
1017 PUBLIC IX_SSP_STATUS
1018 ixSspAccTxFIFOThresholdSet (
1019         IxSspAccFifoThreshold txFIFOThresholdSelected);
1020
1021 /**
1022  * @ingroup IxSspAcc
1023  *
1024  * @fn ixSspAccRxFIFOThresholdSet (
1025         IxSspAccFifoThreshold rxFIFOThresholdSelected)
1026  *
1027  * @brief Sets the Rx FIFO Threshold.
1028  *
1029  * @param "IxSspAccFifoThreshold [in] rxFIFOThresholdSelected" - Threshold that
1030  *              is set for a Tx FIFO service request to be triggered
1031  *
1032  * Global Data  :
1033  *              - None.
1034  *
1035  * This API will will set the threshold for a Rx FIFO threshold to be triggered
1036  *
1037  * @return
1038  *      - IX_SSP_SUCCESS - Rx FIFO Threshold set with valid enum value
1039  *              - IX_SSP_INVALID_RX_FIFO_THRESHOLD_ENUM_VALUE - invalid enum value
1040  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
1041  *
1042  * @li   Reentrant    : yes
1043  * @li   ISR Callable : yes
1044  *
1045  */
1046 PUBLIC IX_SSP_STATUS
1047 ixSspAccRxFIFOThresholdSet (
1048         IxSspAccFifoThreshold rxFIFOThresholdSelected);
1049
1050
1051 /**
1052  * Debug functions
1053  */
1054
1055 /**
1056  * @ingroup IxSspAcc
1057  *
1058  * @fn ixSspAccStatsGet (
1059         IxSspAccStatsCounters *sspStats)
1060  *
1061  * @brief Returns the SSP Statistics through the pointer passed in
1062  *
1063  * @param "IxSspAccStatsCounters [in] *sspStats" - SSP statistics counter will
1064  *                      be read and written to the location pointed by this pointer.
1065  *
1066  * Global Data  :
1067  *              - None.
1068  *
1069  * This API will return the statistics counters of the SSP transfers.
1070  *
1071  * @return
1072  *      - IX_SSP_SUCCESS - Stats obtained into the pointer provided successfully
1073  *              - IX_SSP_FAIL - client provided pointer is NULL
1074  *
1075  * @li   Reentrant    : yes
1076  * @li   ISR Callable : yes
1077  *
1078  */
1079 PUBLIC IX_SSP_STATUS
1080 ixSspAccStatsGet (
1081         IxSspAccStatsCounters *sspStats);
1082
1083 /**
1084  * @ingroup IxSspAcc
1085  *
1086  * @fn ixSspAccStatsReset (
1087         void)
1088  *
1089  * @brief Resets the SSP Statistics
1090  *
1091  * @param - None
1092  *
1093  * Global Data  :
1094  *              - None.
1095  *
1096  * This API will reset the SSP statistics counters.
1097  *
1098  * @return
1099  *      - None
1100  *
1101  * @li   Reentrant    : yes
1102  * @li   ISR Callable : yes
1103  *
1104  */
1105 PUBLIC void
1106 ixSspAccStatsReset (
1107         void);
1108
1109 /**
1110  * @ingroup IxSspAcc
1111  *
1112  * @fn ixSspAccShow (
1113                 void)
1114  *
1115  * @brief Display SSP status registers and statistics counters.
1116  *
1117  * @param - None
1118  *
1119  * Global Data  :
1120  *              - None.
1121  *
1122  * This API will display the status registers of the SSP and the statistics
1123  * counters.
1124  *
1125  * @return
1126  *              - IX_SSP_SUCCESS - SSP show called successfully.
1127  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
1128  *
1129  * @li   Reentrant    : yes
1130  * @li   ISR Callable : yes
1131  *
1132  */
1133 PUBLIC IX_SSP_STATUS
1134 ixSspAccShow (
1135         void);
1136
1137 /**
1138  * @ingroup IxSspAcc
1139  *
1140  * @fn ixSspAccSSPBusyCheck (
1141                 void)
1142  *
1143  * @brief Determine the state of the SSP serial port hardware.
1144  *
1145  * @param - None
1146  *
1147  * Global Data  :
1148  *              - None.
1149  *
1150  * This API will return the state of the SSP serial port hardware - busy or
1151  * idle
1152  *
1153  * @return
1154  *      - IX_SSP_BUSY - SSP is busy
1155  *              - IX_SSP_IDLE - SSP is idle.
1156  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
1157  *
1158  * @li   Reentrant    : yes
1159  * @li   ISR Callable : yes
1160  *
1161  */
1162 PUBLIC IX_SSP_STATUS
1163 ixSspAccSSPBusyCheck (
1164         void);
1165
1166 /**
1167  * @ingroup IxSspAcc
1168  *
1169  * @fn ixSspAccTxFIFOLevelGet (
1170                 void)
1171  *
1172  * @brief Obtain the Tx FIFO's level
1173  *
1174  * @param - None
1175  *
1176  * Global Data  :
1177  *              - None.
1178  *
1179  * This API will return the level of the Tx FIFO
1180  *
1181  * @return
1182  *      - 0..16; 0 can also mean SSP not initialized and will need to be init.
1183  *
1184  * @li   Reentrant    : yes
1185  * @li   ISR Callable : yes
1186  *
1187  */
1188 PUBLIC UINT8
1189 ixSspAccTxFIFOLevelGet (
1190         void);
1191
1192 /**
1193  * @ingroup IxSspAcc
1194  *
1195  * @fn ixSspAccRxFIFOLevelGet (
1196                 void)
1197  *
1198  * @brief Obtain the Rx FIFO's level
1199  *
1200  * @param - None
1201  *
1202  * Global Data  :
1203  *              - None.
1204  *
1205  * This API will return the level of the Rx FIFO
1206  *
1207  * @return
1208  *      - 0..16; 0 can also mean SSP not initialized and will need to be init.
1209  *
1210  * @li   Reentrant    : yes
1211  * @li   ISR Callable : yes
1212  *
1213  */
1214 PUBLIC UINT8
1215 ixSspAccRxFIFOLevelGet (
1216         void);
1217
1218 /**
1219  * @ingroup IxSspAcc
1220  *
1221  * @fn ixSspAccRxFIFOOverrunCheck (
1222                 void)
1223  *
1224  * @brief Check if the Rx FIFO has overrun its FIFOs
1225  *
1226  * @param - None
1227  *
1228  * Global Data  :
1229  *              - None.
1230  *
1231  * This API will return whether the Rx FIFO has overrun its 16 FIFOs
1232  *
1233  * @return
1234  *      - IX_SSP_OVERRUN_OCCURRED - Rx FIFO overrun occurred
1235  *              - IX_SSP_NO_OVERRUN - Rx FIFO did not overrun
1236  *              - IX_SSP_NOT_INIT - SSP not initialized. SSP init needs to be called.
1237  *
1238  * @li   Reentrant    : yes
1239  * @li   ISR Callable : yes
1240  *
1241  */
1242 PUBLIC IX_SSP_STATUS
1243 ixSspAccRxFIFOOverrunCheck (
1244         void);
1245
1246 #endif /* __ixp46X */
1247 #endif /* IXSSPACC_H */