source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxSspAcc.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 22 months ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

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