Fix for SDOCM00112751. Changed instance validity
[keystone-rtos/tcp3d-lld.git] / tcp3d_drv.h
1 /**\r
2  *   @file  tcp3d_drv.h\r
3  *\r
4  *   @brief\r
5  *      Header file for the TCP3 Decoder Driver. The file exposes the data\r
6  *      structures and exported API which are available for use by the driver\r
7  *      users.\r
8  *\r
9  *  \par\r
10  *  NOTE:\r
11  *      (C) Copyright 2011, 2014 Texas Instruments, Inc.\r
12  * \r
13  *  Redistribution and use in source and binary forms, with or without \r
14  *  modification, are permitted provided that the following conditions \r
15  *  are met:\r
16  *\r
17  *    Redistributions of source code must retain the above copyright \r
18  *    notice, this list of conditions and the following disclaimer.\r
19  *\r
20  *    Redistributions in binary form must reproduce the above copyright\r
21  *    notice, this list of conditions and the following disclaimer in the \r
22  *    documentation and/or other materials provided with the   \r
23  *    distribution.\r
24  *\r
25  *    Neither the name of Texas Instruments Incorporated nor the names of\r
26  *    its contributors may be used to endorse or promote products derived\r
27  *    from this software without specific prior written permission.\r
28  *\r
29  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
30  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
31  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
32  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
33  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
34  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
36  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
37  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
38  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
39  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
40  *\r
41 */\r
42 \r
43 /** @defgroup TCP3D_DRV_API TCP3 Decoder Driver\r
44  *\r
45  * @section Introduction\r
46  *\r
47  * @subsection xxx Overview\r
48  *  The TCP3 decoder driver provides a well defined standard interface\r
49  *  which allows application developers to send code blocks for decoding and\r
50  *  receive hard decision and status via EDMA3 transfers. \r
51  */\r
52 \r
53 #ifndef _TCP3D_DRV_H_\r
54 #define _TCP3D_DRV_H_\r
55 \r
56 /**\r
57 @defgroup TCP3D_DRV_SYMBOL  TCP3D Driver Symbols Defined\r
58 @ingroup TCP3D_DRV_API\r
59 */\r
60 /**\r
61 @defgroup TCP3D_DRV_FUNCTION  TCP3D Driver Functions\r
62 @ingroup TCP3D_DRV_API\r
63 */\r
64 /**\r
65 @defgroup TCP3D_DRV_UTIL_FUNCTION  TCP3D Driver Utility Functions\r
66 @ingroup TCP3D_DRV_API\r
67 */\r
68 /**\r
69 @defgroup TCP3D_DRV_DATASTRUCT  TCP3D Driver Data Structures\r
70 @ingroup TCP3D_DRV_API\r
71 */\r
72 /**\r
73 @defgroup TCP3D_OSAL_API  TCP3D Driver OSAL Functions\r
74 @ingroup TCP3D_DRV_API\r
75 */\r
76 \r
77 /**\r
78  *  Driver Includes\r
79  */\r
80 /* Types include */\r
81 #include <tcp3d_drv_types.h>\r
82 \r
83 /* EDMA3 LLD Driver include */\r
84 #include <ti/sdo/edma3/drv/edma3_drv.h>\r
85 \r
86 /* CSL includes */\r
87 #include <ti/csl/cslr_tpcc.h>\r
88 #include <ti/csl/cslr_tcp3d_cfg.h>\r
89 #include <ti/csl/cslr_tcp3d_dma.h>\r
90 \r
91 /* Version include */\r
92 #include "tcp3dver.h"\r
93 \r
94 /* ========================================================================= */\r
95 /** @addtogroup TCP3D_DRV_SYMBOL\r
96  @{ */\r
97 \r
98 /**\r
99  *  @brief Used for indexing the Status Channel.\r
100  */\r
101 #define TCP3D_DRV_MAX_NUM_INSTANCES     (CSL_TCP3D_PER_CNT)\r
102 \r
103 /**\r
104  *  @brief  This is the TCP3D Driver maximum channels required per each PING\r
105  *          and PONG paths. Channel Index values are defined to get references\r
106  *          to the pingCh[] or pongCh[] arrays in the driver instance.\r
107  */\r
108 #define TCP3D_DRV_MAX_CH_PER_PATH       (2u)\r
109 \r
110 /**\r
111  *  @brief Used for indexing the Status Channel.\r
112  */\r
113 #define TCP3D_DRV_CH_IDX_REVT           (0u)\r
114 \r
115 /**\r
116  *  @brief Used for indexing the L2 to PaRAM Channel.\r
117  */\r
118 #define TCP3D_DRV_CH_IDX_L2P            (1u)\r
119 \r
120 /**\r
121  *  @brief  Maximum Link channels required per code block for swapping from\r
122  *          pseudo PaRAM memory during run-time.\r
123  */\r
124 #define TCP3D_DRV_LINK_CB               (5u)\r
125 \r
126 /**\r
127  *  @brief  Number of Link channels used for control/reload operations.\r
128  */\r
129 #define TCP3D_DRV_LINK_CTRL             (6u)\r
130 \r
131 /**\r
132  *  @brief  Number of Link channels used for notification use.\r
133  */\r
134 #define TCP3D_DRV_LINK_NOTIFY           (2u)\r
135 \r
136 /**\r
137  *  @brief  This is the TCP3D Driver maximum link channels required for both\r
138  *          PING and PONG paths.\r
139  */\r
140 #define TCP3D_DRV_MAX_LINK_CH           (((TCP3D_DRV_LINK_CB) + \\r
141                                           (TCP3D_DRV_LINK_CTRL) + \\r
142                                           (TCP3D_DRV_LINK_NOTIFY)) << 1) \r
143 \r
144 /**\r
145  * @brief   This define gives the number of buffers required for TCP3D Driver.\r
146  */\r
147 #define TCP3D_DRV_NUM_BUF               (2u)\r
148 \r
149 /**\r
150  * @brief   This is used for getting the instance buffer index.\r
151  */\r
152 #define TCP3D_DRV_INST_BUFN             (0u)\r
153 \r
154 /**\r
155  * @brief   This is used for getting the pseudo param buffer index.\r
156  */\r
157 #define TCP3D_DRV_PSEUDO_PARAM_BUFN     (1u)\r
158 \r
159 /**\r
160  *  @brief  This is the start flag for PING.\r
161  */\r
162 #define TCP3D_DRV_START_PING            (1u)\r
163 \r
164 /**\r
165  *  @brief  This is the start flag for PONG.\r
166  */\r
167 #define TCP3D_DRV_START_PONG            (2u)\r
168 \r
169 /**\r
170  *  @brief  This is the start flag for AUTO.\r
171  */\r
172 #define TCP3D_DRV_START_AUTO            (3u)\r
173 \r
174 /**\r
175 @}\r
176 */\r
177 \r
178 /* ========================================================================= */\r
179 \r
180 /* ========================================================================= */\r
181 /** @addtogroup TCP3D_DRV_DATASTRUCT\r
182  @{ */\r
183 \r
184 /**\r
185  *  @brief Memory Buffer class definitions.\r
186  */\r
187 typedef enum Tcp3d_BufClass\r
188 {\r
189     Tcp3d_BufClass_EXTERNAL = 0,    /**< generic (bulk) external memory */\r
190     Tcp3d_BufClass_INTERNAL,        /**< generic (bulk) internal memory */\r
191     Tcp3d_BufClass_L2RAM,           /**< Local L2 Memory */\r
192     Tcp3d_BufClass_L2SRAM,          /**< Shared L2 Memory (on another core) */\r
193     Tcp3d_BufClass_MSMC             /**< Shared Memory */\r
194 } Tcp3d_BufClass;\r
195 \r
196 /**\r
197  *  @brief Driver return values to application.\r
198  */\r
199 typedef enum Tcp3d_Result\r
200 {\r
201     TCP3D_DRV_NO_ERR,                   /**< No Error, Success */\r
202     TCP3D_DRV_FAIL,                     /**< General Error */\r
203     TCP3D_DRV_INPUT_LIST_FULL,          /**< Enqueue error message */\r
204     TCP3D_DRV_INVALID_INSTANCE_NUMBER,  /**< Unsupported Instance number */\r
205     TCP3D_DRV_INVALID_PARAMETER,        /**< Parameter value is not correct */\r
206     TCP3D_DRV_INVALID_STATE,            /**< API called in invalid state */\r
207     TCP3D_DRV_INVALID_BUFF,             /**< Invalid buffer pointer */\r
208     TCP3D_DRV_INVALID_EDMA_CH,          /**< Invalid EDMA channel */\r
209     TCP3D_DRV_FAIL_EDMA_PARAM_INIT,     /**< EDMA PaRAM initialization failed */\r
210     TCP3D_DRV_FAIL_EDMA_ENABLE_CHANNEL, /**< EDMA enable channel failed */\r
211     TCP3D_DRV_FAIL_EDMA_GET_PARAM_ADDR  /**< EDMA get PaRAM address failed */\r
212 } Tcp3d_Result;\r
213 \r
214 /**\r
215  *  @brief Driver state indication\r
216  */\r
217 typedef enum Tcp3d_State\r
218 {\r
219     /** This is the driver init state which is used to set in the state\r
220      * variables either at the end of initialization or after the reset. */\r
221     TCP3D_DRV_STATE_INIT = 0,\r
222     \r
223     /** This state indicates the driver is running in a steady state. This is\r
224      * used when ever the driver start is done. In this state, the code blocks\r
225      * are DMAed from input list to TCP3D for execution continuously. */\r
226     TCP3D_DRV_STATE_RUNNING,\r
227     \r
228     /** This state indicates the driver is halted from steady state execution.\r
229      * It could happen if chain to the next code block is not available when\r
230      * the time previous block was DMAed for execution or there are no more\r
231      * code blocks for decoding. If there are more blocks for decoding, restart\r
232      * is required for the driver to complete all decoding. */\r
233     TCP3D_DRV_STATE_PAUSE\r
234 } Tcp3d_State;\r
235 \r
236 /**\r
237  *  @brief  Driver Control Commands.\r
238  */\r
239 typedef enum Tcp3d_CtrlCmd\r
240 {\r
241     /** Used for enabling or disbling the interrupt generation by REVT channels.\r
242      * This is done using the EDMA CC IER or IERH register. */\r
243     TCP3D_DRV_SET_REVT_INT,        \r
244 \r
245     /** Used for clearing the pending interrupts generated by REVT channels\r
246      * in the EDMA CC IPR or IPRH register. */\r
247     TCP3D_DRV_CLR_REVT_INT,\r
248 \r
249     /** Used for enabling or disbling the interrupt generation by L2P channels.\r
250      * This is done by setting the corresponding PaRAM OPT field bit. \r
251      * \b Note that this will result in REVT Channel ISR as the TCC value on the\r
252      * L2P channel PaRAM is set with REVT channel number for chaining use. */\r
253     TCP3D_DRV_SET_L2P_INT,\r
254     \r
255     /** Set interrupt for PING Pause channel (depricated) */\r
256     TCP3D_DRV_SET_PING_PAUSE_INT,\r
257     \r
258     /** Set interrupt for PONG Pause channel (depricated) */\r
259     TCP3D_DRV_SET_PONG_PAUSE_INT,\r
260     \r
261     /** Set interrupt for PING L2P channel (depricated) */\r
262     TCP3D_DRV_SET_PING_L2P_INT,\r
263     \r
264     /** Set interrupt for PONG L2P channel (depricated) */\r
265     TCP3D_DRV_SET_PONG_L2P_INT\r
266 } Tcp3d_CtrlCmd;\r
267 \r
268 /**\r
269  *  @brief Driver Status query Commands\r
270  */\r
271 typedef enum Tcp3d_StsCmd\r
272 {\r
273     TCP3D_DRV_GET_STATE,            /**< Get driver state information */\r
274     TCP3D_DRV_GET_PING_OUT_IDX,     /**< To compute the PING output index in\r
275                                             the pseudo PaRAM list */\r
276     TCP3D_DRV_GET_PONG_OUT_IDX,     /**< To compute the PONG output index in\r
277                                             the pseudo PaRAM list */\r
278     TCP3D_DRV_GET_MIN_OUT_IDX       /**< To compute minimum output index in\r
279                                             the pseudo PaRAM list, used in the\r
280                                             wrap-around case */\r
281 } Tcp3d_StsCmd;\r
282 \r
283 /**\r
284 @}\r
285 */\r
286 /* ========================================================================= */\r
287 \r
288 /* ========================================================================= */\r
289 /** @addtogroup TCP3D_DRV_DATASTRUCT\r
290  @{ */\r
291 \r
292 /**\r
293  *  @brief Parameters which determine buffer sizes.\r
294  *\r
295  * These are configured and passed with getNumBuf() & getBufDesc() funcitons\r
296  * to get the buffer requirement of the TCP3.\r
297  */\r
298 typedef struct Tcp3d_SizeCfg\r
299 {\r
300     uint32_t      maxCodeBlocks;  /**< Maximum code blocks for which driver will\r
301                                     be configured */\r
302     uint32_t      mode;           /**< TCP3 Decode mode for which the driver\r
303                                     instance will be used */\r
304 } Tcp3d_SizeCfg;\r
305 \r
306 /**\r
307  *  @brief Memory Buffer Structure.\r
308  *\r
309  * This structure is used to request and/or supply the \r
310  * dynamic memory to the components.\r
311  */\r
312 typedef struct Tcp3d_MemBuffer\r
313 {\r
314 \r
315   Tcp3d_BufClass  mclass;    /**< Memory class. It is used to describe kind of \r
316                        memory that is requested or returned. For \r
317                        example: external, internal, or similar. One \r
318                        should use MEM_CLASS_xxx constants. On RETURN, \r
319                        class may be changed if original memory class \r
320                        is exhausted. */\r
321   uint16_t log2align; /**< Alignment information (>= 0). If zero, no \r
322                        alignment is required nor provided. Otherwise, \r
323                        memory buffer is aligned on appropriate power \r
324                        of 2 (e.g. if log2align=3, buffer is aligned \r
325                        modulo-8). */\r
326   uint32_t size;      /**< Number of 8 bit words that are requested or supplied. \r
327                        Word length depends on the platform, and \r
328                        corresponds to the shortest element that can be \r
329                        addressed by the CPU. Word storage length in bits \r
330                        is defined in types.h as TYP_TWORD_SIZE. The \r
331                        maximum size depends on the platform. */\r
332   uint16_t  volat;    /**< TRUE: Memory buffer must be restored before and \r
333                        saved after it is used.\r
334                        FALSE: Save/restore are not necessary.\r
335                        On RETURN, volatile flag may be changed if \r
336                        original request could not be satisfied. */\r
337   void  *base;     /**< Base address of the requested buffer. */\r
338 } Tcp3d_MemBuffer;\r
339 \r
340 /**\r
341  * @brief   The TCP3 decoder initialization parameters structure holds all the\r
342  *          information concerning the user channel. These values are used to\r
343  *          generate the control configuration register values for the TCP3D.\r
344  * \r
345  *          Valid values for each field are provided in the brackets in the\r
346  *          comments following the field name.\r
347  */ \r
348 typedef struct Tcp3d_CtrlParams\r
349 {\r
350     /* Mode Control Register parameters */\r
351     uint8_t       mode;           /**< TCP3D mode (0 - 3) */\r
352     uint16_t        doubleBuf;      /**< Enable/disable the double buffer (0,1) */\r
353     uint16_t        intTable;       /**< Enable/disable the Interleaver Table\r
354                                         Generation (0,1) */\r
355     uint16_t        errIgnore;      /**< Enable/disable error detection to stop\r
356                                         TCP3D from running (0,1) */\r
357     uint16_t        autoTrig;       /**< Enable/disable auto trigger mode (0,1) */\r
358     uint8_t       lteCrcSel;      /**< LTE CRC initial value selection (0,1) */\r
359 \r
360     /* Endian Control Register parameters */\r
361     uint8_t       endInt;         /**< Interleaver Table Endian mode (0,1) */\r
362     uint8_t       endInData;      /**< Input systematic and parity data Endian\r
363                                         mode (0,1) */\r
364 \r
365     /* Emulation Control Register parameters */\r
366     uint8_t       emuFreeRun;     /**< Emulation suspend signal (0,1) */   \r
367     uint8_t       emuSoftStop;    /**< Emulation Soft or Hard Stop (0,1) */\r
368     uint8_t       emuRtSel;       /**< Maximum number of iterations (0,1) */\r
369 \r
370     /* Process 0 Execution Register parameters */\r
371     uint8_t       exeP0cmd;       /**< Process 0 execution command (0,1,4,5,6,7)*/\r
372 \r
373     /* Process 1 Execution Register parameters */\r
374     uint8_t       exeP1cmd;       /**< Process 1 execution command (0,1,4,5,6,7)*/\r
375 \r
376 } Tcp3d_CtrlParams;\r
377 \r
378 /**\r
379  * @brief   The TCP3D runtime parameters structure holds all the information\r
380  *          that could be changed per code block. These values are used to\r
381  *          generate the appropriate input configuration register values for\r
382  *          the TCP3D.\r
383  * \r
384  *          Valid values for each field are provided in the brackets in the\r
385  *          comments following the field name.\r
386  */ \r
387 typedef struct Tcp3d_InCfgParams\r
388 {\r
389     /* IC0 */\r
390     uint8_t       numsw0;         /**< number of SW0s (0 - 62) */\r
391     uint16_t      blockLen;       /**< code Block Length (39 - 8191) */\r
392 \r
393     /* IC1 */\r
394     uint8_t       sw0LenSel;      /**< SW0 Length Selection value (0 - 5) */\r
395     uint8_t       sw2LenSel;      /**< SW2 Length Selection value (0,1,2) */\r
396     uint8_t       sw1Len;         /**< SW1 Length (9 - 127) */\r
397 \r
398     /* IC2 */\r
399     uint8_t       intLoadSel;     /**< Interleaver Table load or generate\r
400                                         selection (0,1) */\r
401     uint16_t        maxStar;        /**< Enable/disable Max Star (0,1) */\r
402     uint16_t        outStsRead;     /**< Enable/disable Output Status registers\r
403                                         read via EDMA3 (0,1) */\r
404     uint8_t       outOrderSel;    /**< Output bit order swapping within 32-bit\r
405                                         word (0,1) */\r
406     uint16_t        extScale;       /**< Enable/disable Extrinsic scaling (0,1) */\r
407     uint16_t        softOutRead;    /**< Enable/disable Soft outputs read\r
408                                         via EDMA3 (0,1) */\r
409     uint8_t       softOutOrderSel;/**< Soft output byte order (0,1)\r
410                                         used only in BIG ENDIAN mode */\r
411     uint8_t       softOutFrmtSel; /**< Soft output bit format (0,1) */\r
412     uint8_t       minIter;        /**< Minumun iterations (0 - 15) */\r
413     uint8_t       maxIter;        /**< Maximum iterations (0 - 15) */\r
414     uint8_t       snrVal;         /**< SNR threshold value in dB used as stopping\r
415                                         criteria (0 - 20) */\r
416     uint16_t        snrReport;      /**< Enable/disable SNR reporting (0,1) */\r
417     uint8_t       stopSel;        /**< Stopping criteria selection (0 - 3) */\r
418     uint8_t       crcIterSel;     /**< LTE CRC consecutive matches for\r
419                                         stopping (0 - 3 ) */\r
420     uint8_t       crcPolySel;     /**< LTE CRC polynomial selection (0,1) */\r
421 \r
422     /* IC3 */\r
423     uint8_t       maxStarThres;   /**< Max Star Threshold value (0 - 63) */\r
424     uint8_t       maxStarValue;   /**< Max Star Value (0 - 63) */\r
425 \r
426     /* IC4-IC7 */\r
427     int8_t        betaMap0[8];    /**< Beta state values for MAP0 decoder */\r
428     int8_t        betaMap1[8];    /**< Beta state values for MAP1 decoder */\r
429 \r
430     /* IC8-IC11 */\r
431     uint8_t       extrScale[16];  /**< Extrinsic scale values */\r
432 \r
433     /* IC12-IC14 */\r
434     uint16_t      itgParam[5];    /**< Interleaver Table Generation init params */\r
435 \r
436 } Tcp3d_InCfgParams;\r
437 \r
438 /**\r
439  * @brief Structure to store TCP3 decoder specific values to identify its\r
440  *          instance configuration information. This is created to facilitate\r
441  *          the application to choose TCP3 decoder (either TCP3D_0 or TCP3D_1)\r
442  *          for which the driver will be configured.\r
443  * \r
444  *      This structure could be used for both PING and PONG specific values.\r
445  */\r
446 typedef struct Tcp3d_Config\r
447 {\r
448     uint32_t      inCfgStart; /**< input configuration registers start address */\r
449     uint32_t      llrStart;   /**< input data (LLR) start address */\r
450     uint32_t      interStart; /**< inter leaver start address */\r
451     uint32_t      hdStart;    /**< output hard decision start address */\r
452     uint32_t      sdStart;    /**< output soft decision start address */\r
453     uint32_t      stsStart;   /**< output status registers start address */\r
454     uint32_t      revtCh;     /**< Channel number associated with REVT */\r
455 }Tcp3d_Config;\r
456 \r
457 /**\r
458  * @brief TCP3D Driver instance structure\r
459  */\r
460 typedef struct Tcp3d_Instance\r
461 {\r
462     /** TCP3D Peripheral instance number */\r
463     uint8_t                 instNum;\r
464 \r
465     /** Variable to keep the driver state */\r
466     volatile Tcp3d_State    state;\r
467 \r
468     /** Driver operating Mode for the given instance */\r
469     uint8_t                 mode;\r
470     \r
471     /** Double Buffer mode enable/disable */\r
472     uint16_t                doubleBuffer;\r
473 \r
474     /** If true, PING path is stopped */\r
475     volatile uint8_t        pingStop;\r
476     \r
477     /** If true, PONG path is stopped */\r
478     volatile uint8_t        pongStop;\r
479 \r
480     /** TCP3D driver start mode flag. Set to NULL during init to disable the \r
481      * auto start function call from enqueue funciton until application\r
482      * initiates.\r
483      */\r
484     uint8_t                 startFlag;\r
485 \r
486     /** CPU/DSP core ID on which this instance of driver is running */\r
487     uint8_t                 coreId;\r
488 \r
489     /** Gives the number of free entries available in the input ping list for\r
490      * enqueue. This flag is decremented when a code block is enqueued into\r
491      * the ping list. It's value is updated in the start funciton. */\r
492     int32_t                 pingFreeCnt;\r
493 \r
494     /** Gives the number of free entries available in the input pong list for\r
495      * enqueue. This flag is decremented when a code block is enqueued into\r
496      * the pong list. It's value is updated in the start funciton. */\r
497     int32_t                 pongFreeCnt;\r
498 \r
499     /** Gives the Maximum number of code blocks that can be enqueued using the\r
500      * driver. This value is set during the init. */\r
501     uint32_t                maxCodeBlocks;\r
502 \r
503     /** Gives the next code block index for enqueue into the input list. */\r
504     uint32_t                nextCodeBlockIndex;\r
505     \r
506     /** Pointer to the pseudo PaRAM buffer array base. */\r
507     EDMA3_DRV_PaRAMRegs     *pseudoParamBufPtr;\r
508 \r
509     /** CP_INTC0 input event number used for the output notification. Driver\r
510      * uses this value to write (using EDMA) into the STATUS_SET_INDEX_REG\r
511      * during run-time to cause system event/interrupt. */\r
512     uint32_t                notificationEventNum;\r
513 \r
514     /**\r
515      *  CP_INTC0 register overlay base address.\r
516      *  This is expected of type CSL_CPINTC_RegsOvly.\r
517      */\r
518     void                    *cpIntc0RegsBase;\r
519 \r
520     /* EDMA Variables */\r
521     EDMA3_DRV_Handle        edmaHnd;        /**< EDMA3 LLD Driver Handle */\r
522     uint32_t                edmaRegionId;   /**< EDMA shadow region number*/\r
523     uint32_t                pingCh[TCP3D_DRV_MAX_CH_PER_PATH];\r
524                                             /**< Ping channels stored here */\r
525     uint32_t                pongCh[TCP3D_DRV_MAX_CH_PER_PATH];\r
526                                             /**< Pong channels stored here */\r
527     uint32_t                pingChParamAddr[TCP3D_DRV_MAX_CH_PER_PATH];\r
528                                             /**< Physical PaRAM addresses of the \r
529                                                 Ping channels */\r
530     uint32_t                pongChParamAddr[TCP3D_DRV_MAX_CH_PER_PATH];\r
531                                             /**< Physical PaRAM addresses of the \r
532                                                 Pong channels */\r
533     uint32_t                pingLinkCh[TCP3D_DRV_MAX_LINK_CH>>1];\r
534                                             /**< Link channels for Ping path */\r
535     uint32_t                pongLinkCh[TCP3D_DRV_MAX_LINK_CH>>1];\r
536                                             /**< Link channels for Pong path */\r
537     uint32_t                pingLinkChParamAddr[TCP3D_DRV_MAX_LINK_CH>>1];\r
538                                             /**< Link channel PaRAM address for\r
539                                              Ping path */\r
540     uint32_t                pongLinkChParamAddr[TCP3D_DRV_MAX_LINK_CH>>1];\r
541                                             /**< Link channel PaRAM address for\r
542                                                     Pong path */\r
543 \r
544     /** bit masks used for controlling interrupt generation by EDMA CC */\r
545     uint32_t                l2pChMaskPing;  /**< L2P Channel Mask for PING */\r
546     uint32_t                l2pChMaskPong;  /**< L2P Channel Mask for PONG */\r
547     uint32_t                pauseChMaskPing;  /**< REVT Channel Mask for PING */\r
548     uint32_t                pauseChMaskPong;  /**< REVT Channel Mask for PING */\r
549 \r
550     /** EDMA shadow registers base address used during run-time */\r
551     CSL_TPCC_ShadowRegs     *tpccShadowRegs;\r
552     /** Register address of TPCC_IECR used for clearing (diable) the IER bits */\r
553     uint32_t                *intEnClrReg[2];\r
554     /** Register address of TPCC_IESR used for setting (enable) the IER bits */\r
555     uint32_t                *intEnSetReg[2];\r
556     /** Register address of TPCC_ICR used for clearing the pending IPR bits */\r
557     uint32_t                *clrIntPendReg[2];\r
558     /** Register address of TPCC_IPR used for checking pending interrupts */\r
559     uint32_t                *intPendReg[2];\r
560 \r
561     /* Internal Variables (most of the names are self explanatory) */\r
562     uint8_t                 constantOne;/**< variable set to 1 at init time and\r
563                                         used by PAUSE channels */\r
564     Tcp3d_State             pauseState; /**< variable set to TCP3D_DRV_STATE_PAUSE\r
565                                         and used by PAUSE channels */\r
566     uint32_t                resetHdOpt[2];\r
567     uint32_t                resetHdLink[2];\r
568     uint32_t                resetStsOpt[2];\r
569     uint32_t                resetStsLink[2];\r
570     uint32_t                resetSdOpt[2];\r
571     uint32_t                resetSdLink[2];\r
572     EDMA3_DRV_PaRAMRegs     *startPrmPtr;\r
573     EDMA3_DRV_PaRAMRegs     *pingPtrL2p;\r
574     EDMA3_DRV_PaRAMRegs     *pongPtrL2p;\r
575     EDMA3_DRV_PaRAMRegs     revtPrm[2];\r
576     EDMA3_DRV_PaRAMRegs     l2pPrm[2];\r
577     EDMA3_DRV_PaRAMRegs     *lastParam[2];\r
578     EDMA3_DRV_PaRAMRegs     *endListParam[2];\r
579     uint32_t                prevNtfFlag[2];\r
580     uint32_t                maxPingCbIdx;\r
581     uint32_t                maxPongCbIdx;\r
582     uint32_t                maxPingCbCnt;\r
583     uint32_t                maxPongCbCnt;\r
584     uint32_t                nextPingInIdx;\r
585     uint32_t                nextPongInIdx;\r
586     uint32_t                prevPingOutIdx;\r
587     uint32_t                prevPongOutIdx;\r
588     int32_t                 pingLoadCnt;\r
589     int32_t                 pongLoadCnt;\r
590     volatile uint32_t       pingLastOutFlag;\r
591     volatile uint32_t       pongLastOutFlag;\r
592     uint8_t                 pingWrapCheck;    \r
593     uint8_t                 pongWrapCheck;    \r
594 \r
595     /* Debug Flags */\r
596     volatile uint32_t       pingStartCntr;\r
597     volatile uint32_t       pongStartCntr;\r
598     volatile uint32_t       pingPauseEnCntr;\r
599     volatile uint32_t       pingL2pEnCntr;\r
600     volatile uint32_t       pingIntr;\r
601     volatile uint32_t       pongIntr;\r
602 \r
603 } Tcp3d_Instance;\r
604 \r
605 /**\r
606  * @brief   TCP3D Driver Initialization parameters structure\r
607  */\r
608 typedef struct Tcp3d_InitParams\r
609 {\r
610     /** \r
611      * TCP3D Peripheral instance number to setup. Possible values are\r
612      *          CSL_TCP3D_0 or CSL_TCP3D_1.\r
613      */\r
614     uint8_t                   instNum;\r
615 \r
616     /**\r
617      *  Maximum code blocks for which the driver resources will be \r
618      *          configured. This value is required to configure some parameters.\r
619      */\r
620     uint32_t                  maxCodeBlocks;\r
621 \r
622     /**\r
623      *  Core Index value [0,1,2,3]. Used for traslating local L2\r
624      *          addresses into global addresses used in the EDMA transfers.\r
625      */\r
626     uint8_t                   coreID;\r
627 \r
628     /**\r
629      *  Control parameters for TCP3 decoder. All the elements in this\r
630      *          structure must be filled with the required values with which\r
631      *          the driver is intended to run.\r
632      * \r
633      *          They are used to set the MODE, ENDIAN and EXECUTE control\r
634      *          registers and also to control the driver code based on the\r
635      *          configuration information like mode & double buffer.\r
636      */\r
637     Tcp3d_CtrlParams        ctrlParams;\r
638 \r
639     /**\r
640      *  TCP3 decoder configuration registers start address. This is used\r
641      *          only in the init function to start the TCP3 decoder state\r
642      *          machine by writing into the control registers with the correct\r
643      *          configuration values.\r
644      */\r
645     CSL_Tcp3d_cfgRegs       *tcp3dCfgRegs;\r
646 \r
647     /**\r
648      *  Start addresses of PING (P0) memory area of TCP3 Decoder and\r
649      *          the assiciated REVT channel number will be provided here.  \r
650      *          This structure values must be filled with appropriate addresses \r
651      *          depending on the decoder instance.\r
652      */\r
653     Tcp3d_Config            pingConfig;\r
654 \r
655     /**\r
656      *  Start addresses of PONG (P1) memory area of TCP3 Decoderand\r
657      *          the assiciated REVT channel number will be provided here.\r
658      *          This structure values must be filled with appropriate addresses \r
659      *          depending on the decoder instance.\r
660      */\r
661     Tcp3d_Config            pongConfig;\r
662 \r
663     /**\r
664      *  EDMA3 LLD Driver handle used in the driver to call EDMA LLD\r
665      *          driver funcitons.\r
666      */\r
667     EDMA3_DRV_Handle        edmaHnd;\r
668 \r
669     /**\r
670      *  EDMA3 shadow region ID through which all the resources are\r
671      *          allocated.\r
672      */\r
673     uint32_t                  edmaRegionId;\r
674 \r
675     /**\r
676      *  Ping Channels Array. First channel must be "0" since it is tied \r
677      *          to the event (REVT0) generated from TCP3D and used for reading\r
678      *          outputs from the decoder memory. Total physical channels \r
679      *          required is given by the define TCP3D_DRV_MAX_CH_PER_PATH.\r
680      * \r
681      *          This arrary could be accesssed with the index values provided\r
682      *          as define names starting with TCP3D_DRV_CH_IDX. This is useful\r
683      *          for the application when it needs to setup a callback with\r
684      *          specific Channel (TCC).\r
685      */\r
686     uint32_t                  pingCh[TCP3D_DRV_MAX_CH_PER_PATH];\r
687 \r
688     /**\r
689      *  Pong Channels Array. First channel must be "1" since it is tied \r
690      *          to the event (REVT1) generated from TCP3D and used for reading\r
691      *          outputs from the decoder memory.\r
692      *\r
693      *          Total physical channels required is given by the define \r
694      *          TCP3D_DRV_MAX_CH_PER_PATH.\r
695      *   \r
696      *          This arrary could be accesssed with the index values provided\r
697      *          as define names starting with TCP3D_DRV_CH_IDX. This is useful\r
698      *          for the application when it needs to setup a callback with\r
699      *          specific Channel (TCC).\r
700      */\r
701     uint32_t                  pongCh[TCP3D_DRV_MAX_CH_PER_PATH];\r
702 \r
703     /**\r
704      *  Link Channels Array.\r
705      * \r
706      *          Total physical channels required is given by the define\r
707      *          TCP3D_DRV_MAX_LINK_CH.\r
708      * \r
709      * @note    It is required that all these link channels be consecutive in\r
710      *          their PaRAM memory. \r
711      */\r
712     uint32_t                  linkCh[TCP3D_DRV_MAX_LINK_CH];\r
713 \r
714     /**\r
715      *  CP_INTC0 input event used for the output notification.\r
716      */\r
717     uint32_t                  notificationEventNum;\r
718 \r
719     /**\r
720      *  CP_INTC0 register overlay base address.\r
721      *  This is expected of type CSL_CPINTC_RegsOvly.\r
722      */\r
723     void                    *cpIntc0RegsBase;\r
724 \r
725     /**\r
726      *  EDMA3 Channel Controller shadow register base address of the region\r
727      *  (edmaRegionId) from where the resources were allocated.\r
728      *  This is expected of type CSL_TPCC_ShadowRegs.\r
729      */\r
730     CSL_TPCC_ShadowRegs     *edma3ShadowRegsBase;\r
731 \r
732 } Tcp3d_InitParams;\r
733 \r
734 /**\r
735  * @brief   TCP3D Driver Status structure.\r
736  */ \r
737 typedef struct Tcp3d_Sts\r
738 {\r
739     Tcp3d_StsCmd    cmd;        /**< Command flag for Status query */\r
740     Tcp3d_State     state;      /**< to keep the Driver state value */\r
741     uint32_t          prmOutIdx;  /**< to keep the queried input pseudo PaRAM\r
742                                     index value */\r
743 } Tcp3d_Sts;\r
744 \r
745 /**\r
746  * @brief   TCP3D Driver Control structure.\r
747  */ \r
748 typedef struct Tcp3d_Ctrl\r
749 {\r
750     Tcp3d_CtrlCmd   cmd;            /**< Command flag for control operation */\r
751     uint32_t          intrFlag;       /**< interrupt flag to enable or disable\r
752                                         1 - for enable\r
753                                         0 - for disable */\r
754 } Tcp3d_Ctrl;\r
755 \r
756 /**\r
757 @}\r
758 */\r
759 /* ========================================================================= */\r
760 \r
761 /* ========================================================================= */\r
762 /**\r
763  * Driver Function definitions\r
764  */\r
765 /** @addtogroup TCP3D_DRV_FUNCTION\r
766  @{ */\r
767 \r
768 /**\r
769  *  @b  Description\r
770  *  @n  \r
771  *              TCP3D Driver function for providing the number of buffers\r
772  *              required.\r
773  * \r
774  *  \param[in]      *cfg\r
775  *              Pointer to the structure of type Tcp3d_SizeCfg which has\r
776  *              specific information used for determining the buffer\r
777  *              requirements.\r
778  *\r
779  *              For Example, TCP3D could use one field maxCodeBlocks to\r
780  *              determine number of buffers required.\r
781  * \r
782  *  \param[out]     *nbufs\r
783  *              Pointer of a variable to which TCP3D Driver proveds the number\r
784  *              of buffers required.\r
785  * \r
786  *  \pre        Set the cfg->maxCodeBlocks value before calling this API.\r
787  *\r
788  *  \post       \r
789  *\r
790  *  \return     Status reported as either TCP3D_DRV_NO_ERR or TCP3D_DRV_FAIL.\r
791  *\r
792  */\r
793 Tcp3d_Result Tcp3d_getNumBuf (IN Tcp3d_SizeCfg  *cfg,\r
794                               OUT int16_t         *nbufs);\r
795 \r
796 /**\r
797  *  @b  Description\r
798  *  @n  \r
799  *              TCP3D Driver function for providing the attributes of all the\r
800  *              number of buffers requested through the structure of type\r
801  *              Tcp3d_MemBuffer provided.\r
802  * \r
803  *  \param[in]      *cfg\r
804  *              Pointer to the structure of type Tcp3d_SizeCfg which has\r
805  *              specific information used for determining the buffer\r
806  *              requirements.\r
807  *\r
808  *              TCP3D Driver uses the field maxCodeBlocks for determining\r
809  *              the buffer sizes required.\r
810  * \r
811  *  \param[out]     **bufs\r
812  *              Pointer to the array of Tcp3d_MemBuffer structure of size\r
813  *              provided through the Tcp3d_getNumBuf() API.\r
814  *\r
815  *              TCP3D Driver fills all the fileds of the structure except the\r
816  *              base which application fills after allocating the memory as per\r
817  *              the attributes requested.\r
818  * \r
819  *  \pre        Set the cfg->maxCodeBlocks value before calling this API.\r
820  *\r
821  *  \post       \r
822  *\r
823  *  \return     Status reported as either TCP3D_DRV_NO_ERR or TCP3D_DRV_FAIL.\r
824  *\r
825  */\r
826 Tcp3d_Result Tcp3d_getBufDesc ( IN  Tcp3d_SizeCfg       *cfg,\r
827                                 OUT Tcp3d_MemBuffer     bufs[]);\r
828 \r
829 /**\r
830  *  @b  Description\r
831  *  @n  \r
832  *              TCP3D Driver function called to reset the driver at any time\r
833  *              after init and only if both PING & PONG decoders have nothing\r
834  *              in the input list for decoding.\r
835  * \r
836  *              This API checks if it is called in a correct state and returns\r
837  *              appropriate error message.\r
838  *\r
839  *              This function does the following:\r
840  *              1) Set the instance with the passed values - for example number\r
841  *                  of blocks for decoding in the current subframe which is\r
842  *                  needed for boundary checks and to setup the EDMA channels\r
843  *                  and a new status array pointer where the status register\r
844  *                  values for each code block are to be DMAed.\r
845  *              2) Initialize all the run-time instance variables to default.\r
846  *              3) Initialize the pseudo PaRAM memory with all the defaults\r
847  *                  based on mode.\r
848  *              4) Reset the EDMA channels with default values.\r
849  *              5) Change the state to TCP3D_DRV_STATE_INIT.\r
850  * \r
851  *  \param[in]      *tcp3dInst\r
852  *              This is the driver instance.\r
853  * \r
854  *  \param[in]     codeBlocks\r
855  *              Number of code blocks to be decoded for the current sub-frame.\r
856  *              This value should be equal to the maxCodeBlocks.\r
857  *\r
858  *              For saving cycles, you can set to lower value that should be\r
859  *              multiple of 2.\r
860  *\r
861  *  \pre        Allocation of the statusBuf arrary must be big enough to fit\r
862  *              all the register trasfers for the given codeBlocks. If the size\r
863  *              is small, there will be memory step-over.\r
864  *\r
865  *  \post       \r
866  *\r
867  *  \retVal     Success - TCP3D_DRV_NO_ERR \r
868  *  \retVal     Failure - TCP3D_DRV_INVALID_STATE\r
869  *  \retVal     Failure - TCP3D_DRV_INVALID_PARAMETER\r
870  *\r
871  */\r
872 Tcp3d_Result Tcp3d_reset (  IN Tcp3d_Instance  *tcp3dInst,\r
873                             IN uint32_t          codeBlocks);\r
874 \r
875 /**\r
876  *  @b  Description\r
877  *  @n  \r
878  *              TCP3D Driver Initialization function which must be called only\r
879  *              once to initialize the driver instance and other required\r
880  *              resources needed for the driver functionality.\r
881  * \r
882  *              This funciton does the following:\r
883  *              -# First this function reads the bufs structure to get the base\r
884  *                  addresses to set the instance and other strucures. If any\r
885  *                  base address is NULL, driver exits immediately with error.\r
886  *              -# Initializes all the run-time instance variables to default\r
887  *                  values.\r
888  *              -# All init-time variables are set either from the drvInitParams\r
889  *                  input structure or set directly.\r
890  *              -# Copies all the EDMA resource information into the instance.\r
891  *                  - Does some sanity check on the channel numbers associated\r
892  *                      with REVTs. \r
893  *                  - Enables all the EVENT triggered channels.\r
894  *                  - Pre-fill most of the PaRAM entries for both the physical\r
895  *                      and linked channels which will be used in run-time in\r
896  *                      the enqueue funciton.\r
897  *              -# Initializes the pseudo PaRAM buffer with fixed values.\r
898  *              -# All required reset funcitons are called from this function\r
899  *                  to eliminate the need to call the reset API immediately.\r
900  *              -# Finally before exit, starts the TCP3 Decoder state machine by\r
901  *                  writing into the control registers from the values provided\r
902  *                  in the drvInitParams->ctrlParams structure.\r
903  * \r
904  *  \param[in]      **bufs\r
905  *              Pointer to the array of Tcp3d_MemBuffer structure of size\r
906  *              provided through the Tcp3d_getNumBuf() API. This strucure must\r
907  *              have all the fields filled by now. The bufs[0]->base value will\r
908  *              be used for initializing the driver instance.\r
909  *\r
910  *  \param[in]      drvInitParams\r
911  *              Driver initialization parameters structure. This structure is\r
912  *              used for getting all the required resources for the driver to\r
913  *              initialize the instance. Look into the description of the \r
914  *              Tcp3d_InitParams structure elements for details. \r
915  * \r
916  *  \pre          \r
917  *\r
918  *  \post       \r
919  *\r
920  *  \retVal     Success -   TCP3D_DRV_NO_ERR \r
921  *  \retVal     Failure -   TCP3D_DRV_INVALID_BUFF\r
922  *  \retVal     Failure -   TCP3D_DRV_INVALID_EDMA_CH \r
923  *  \retVal     Failure -   TCP3D_DRV_FAIL_EDMA_GET_PARAM_ADDR\r
924  *  \retVal     Failure -   TCP3D_DRV_FAIL_EDMA_PARAM_INIT\r
925  *  \retVal     Failure -   TCP3D_DRV_FAIL_EDMA_ENABLE_CHANNEL\r
926  *\r
927  */\r
928 Tcp3d_Result Tcp3d_init(IN  Tcp3d_MemBuffer     bufs[],\r
929                         IN  Tcp3d_InitParams    *drvInitParams);\r
930 \r
931 /**\r
932  *  @b  Description\r
933  *  @n  \r
934  *              TCP3D Driver De-Initialization function which must be called\r
935  *              to close the corresponding instance.\r
936  * \r
937  *              This funciton does the following:\r
938  *              -# First this function clears any EDMA specific registers set.\r
939  * \r
940  *  \param [in]     *tcp3dInst\r
941  *              This is the driver instance.\r
942  *\r
943  *  \pre          \r
944  *\r
945  *  \post       Application can free the resources and memory allocated for this\r
946  *              instance after this function.\r
947  *\r
948  *  \retVal     Success -   TCP3D_DRV_NO_ERR \r
949  *  \retVal     Failure -   TCP3D_DRV_FAIL\r
950  *\r
951  */\r
952 Tcp3d_Result Tcp3d_deInit(IN  Tcp3d_Instance  *tcp3dInst);\r
953 \r
954 /**\r
955  *  @b  Description\r
956  *  @n  \r
957  *              This is a run-time API for appending the codeblocks to the\r
958  *              pseudo PaRAM list as the blocks arrive. This function updates\r
959  *              the pseudo PaRAM set entries and chains to the previous block\r
960  *              in the corresponding list (PING or PONG).\r
961  * \r
962  *              Enqueuing is done alternately between the two lists until the\r
963  *              current list is full. The no room case is indicated with return\r
964  *              error TCP3D_DRV_INPUT_LIST_FULL.\r
965  * \r
966  *              On each succeesful enqueue, the corresponding load counter for\r
967  *              the path is incremented. This funciton updates some run-time\r
968  *              varaibles which keeps track of ping and pong list indexes\r
969  *              and counters.\r
970  * \r
971  *              This function primarily does the following:\r
972  *              -# Updates the pseudo PaRAM set with the addresses passed as \r
973  *                  paramters. Also, updates necessary count and index values\r
974  *                  within the pseudo PaRAM set which depend on the block size\r
975  *                  and are not pre-filled during init.\r
976  *              -# Links the optional outputs, if present, to the HD param and\r
977  *                  sets necessary TCC values.\r
978  *              -# If the ntfEventFlag is set for notification, the NTF Param is\r
979  *                  linked with the last param from the set.\r
980  *              -# Chaining to the previous block in the corresponding list is\r
981  *                  done, execept for the first one in the list. This is done by\r
982  *                  - Changing the TCC field of the last param in the previous\r
983  *                      block to trigger the L2P channel.\r
984  *                  - Updating the link field with the dummy or NTFD depending\r
985  *                      on whether the previous block has notification or not.\r
986  *              -# Calls the Tcp3d_start() function with auto mode as needed\r
987  *                  after the application initiated the first start.\r
988  *\r
989  *              This function is executed at the application task thread for\r
990  *              queueing the code blocks to the input pseudo PaRAM list. They\r
991  *              will be copied to the actual PaRAM area using the L2P channel\r
992  *              when the previous block is decoded and outputs are read as\r
993  *              specified.\r
994  * \r
995  *              Application need to check the return value to take appropriate\r
996  *              action.\r
997  *              -# If no error try enqueuing next block.\r
998  *              -# If LIST FULL error, either wait for some time and try\r
999  *                  enqueuing or enable EDMA completion interrupts for L2P\r
1000  *                  channels. Upon receiving the interrupt the enqueuing could\r
1001  *                  be tried again.\r
1002  * \r
1003  *              Since the TCC for L2P channels always point to REVT, enabling\r
1004  *              L2P channel interrupts would showup as REVT channel call backs.\r
1005  *\r
1006  *  \param [in]     *tcp3dInst\r
1007  *              This is the driver instance.\r
1008  *\r
1009  *  \param [in]     blockLength\r
1010  *              Code Block length value which is used for setting some of the\r
1011  *              PaRAM counts.\r
1012  *\r
1013  *  \param [in]     *inputConfigPtr\r
1014  *              Pointer to the input config registers prepared for the current\r
1015  *              code block.\r
1016  *\r
1017  *  \param [in]     *llrPtr\r
1018  *              Input data pointer where the systematic, parity 1 and parity 2\r
1019  *              streams are available.\r
1020  *\r
1021  *  \param [in]     llrOffset\r
1022  *              Input data offset between the three streams. Used for setting\r
1023  *              the EDMA trasfer type (A-Sync or AB-Sync) and also to set the\r
1024  *              source jump index.\r
1025  *\r
1026  *  \param [in]     *hdPtr\r
1027  *              Pointer to the memory where the decoded hard decision values to\r
1028  *              be DMAed.\r
1029  *\r
1030  *  \param [in]     *statusPtr\r
1031  *              Pointer to the memory to DMA the three status register values.\r
1032  *              \r
1033  *              This is a selective parameter which application uses only if the\r
1034  *              corresponding bit is set in the inputConfigRegs for reading the\r
1035  *              TCP3D output memory.\r
1036  * \r
1037  *              If not used, set to @b NULL to avoid any undesired behaviour\r
1038  *              from the TCP3 decoder. This will also save the time for\r
1039  *              programming.\r
1040  *\r
1041  *  \param [in]     *sdPtr\r
1042  *              Pointer to the memory where the decoded soft decision values to\r
1043  *              be DMAed.\r
1044  * \r
1045  *              This is a selective parameter which application uses only if the\r
1046  *              corresponding bit is set in the inputConfigRegs for reading the\r
1047  *              TCP3D output memory.\r
1048  * \r
1049  *              If not used, set to @b NULL to avoid any undesired behaviour\r
1050  *              from the TCP3 decoder. This will also save the time for\r
1051  *              programming.\r
1052  *\r
1053  *  \param [in]     sdOffset\r
1054  *              Output data offset between the three streams. Not valid for\r
1055  *              split more, since there will be only one stream.\r
1056  * \r
1057  *              If not used, set to @b NULL to avoid any undesired behaviour\r
1058  *              from the TCP3 decoder.\r
1059  *\r
1060  *  \param [in]     ntfEventFlag\r
1061  *              Flag for enabling the notification event to be generated at\r
1062  *              the end of output transfer completion of the code block. When\r
1063  *              set, the event number provided during the init.\r
1064  *  \r
1065  *              Useful for application to get notification after a specific\r
1066  *              code block is decoded to start the post-processing.\r
1067  *\r
1068  *  \pre        This driver API MUST be called only after the Tcp3d_init()\r
1069  *              function is called.\r
1070  *\r
1071  *  \post       Driver state value could be changed to TCP3D_DRV_STATE_RUNNING\r
1072  *              from TCP3D_DRV_STATE_PAUSE. This happens only if the startFlag\r
1073  *              was set by this time.\r
1074  *\r
1075  *  \retVal     Success -   TCP3D_DRV_NO_ERR\r
1076  *  \retVal     Failure -   TCP3D_DRV_INPUT_LIST_FULL\r
1077  */\r
1078 Tcp3d_Result Tcp3d_enqueueCodeBlock(IN  Tcp3d_Instance  *tcp3dInst,\r
1079                                     IN  uint32_t          blockLength,\r
1080                                     IN  uint32_t          *inputConfigPtr,\r
1081                                     IN  int8_t            *llrPtr,\r
1082                                     IN  uint32_t          llrOffset,\r
1083                                     IN  uint32_t          *hdPtr,\r
1084                                     IN  int8_t            *sdPtr,\r
1085                                     IN  uint32_t          sdOffset,\r
1086                                     IN  uint32_t          *statusPtr,\r
1087                                     IN  uint8_t           ntfEventFlag);\r
1088 \r
1089 /**\r
1090  *  @b  Description\r
1091  *  @n  \r
1092  *              This API could be used for starting the driver to start doing\r
1093  *              EDMA transfers to TCP3 decoder for decoding from the pseudo\r
1094  *              PaRAM list.\r
1095  * \r
1096  *              This function updates the load and free counts for both ping\r
1097  *              and pong lists.\r
1098  *\r
1099  *              This function is executed at the application task thread for\r
1100  *              starting either the PING or PONG path execution.\r
1101  * \r
1102  *  \param [in]     *inst\r
1103  *              This is the driver instance. \r
1104  *\r
1105  *  \param [in]     startMode\r
1106  *              Flag tells the mode of operation.\r
1107  *          -# If set to TCP3D_DRV_START_AUTO, function checks both the paths\r
1108  *              (PING & PONG) and start the needed paths.\r
1109  *          -# If set with either TCP3D_DRV_START_PING or TCP3D_DRV_START_PONG,\r
1110  *              and the corresponding flag (pingStop or pongStop) is set then\r
1111  *              that path alone is started.\r
1112  *\r
1113  *  \pre        Application must have atleast one code block enqueued to the \r
1114  *              pseudo PaRAM list before calling this API so that driver will\r
1115  *              have something to start the EDMA trasfers and decoding before\r
1116  *              going to PAUSE state.\r
1117  * \r
1118  *              This function should be called only after the Tcp3d_init()\r
1119  *              function is called.\r
1120  *\r
1121  *  \post       Driver state variable is updated, if any paths are started.\r
1122  *\r
1123  *  \retVal     Success -   TCP3D_DRV_NO_ERR\r
1124  *  \retVal     Failure -   TCP3D_DRV_FAIL_EDMA_ENABLE_CHANNEL\r
1125  *\r
1126  */\r
1127 Tcp3d_Result Tcp3d_start (  IN  Tcp3d_Instance  *inst,\r
1128                             IN  uint8_t           startMode);\r
1129 \r
1130 /**\r
1131  *  @b  Description\r
1132  *  @n  \r
1133  *              This API could be used for querying the TCP3D driver to get\r
1134  *              updates or take appropriate actions. The Tcp3d_StsCmd enum\r
1135  *              structure gives the supported commads.\r
1136  * \r
1137  *  \note       This API is not fully scoped and the possible query commands\r
1138  *              could be extended in future.\r
1139  * \r
1140  *  \param[in]      *inst\r
1141  *              This is the driver instance for which status query is made.\r
1142  *\r
1143  *  \param[in,out]  *drvStatus\r
1144  *              Structure used for keeping the status request command and \r
1145  *              for keeping the status query output.\r
1146  *\r
1147  *  \pre        Set appropriate command value before calling the function.\r
1148  * \r
1149  *  \post       \r
1150  *\r
1151  *  \retVal     Success -   TCP3D_DRV_NO_ERR (valid command)\r
1152  *  \retVal     Failure -   TCP3D_DRV_FAIL (invalid command)\r
1153  *\r
1154  */\r
1155 Tcp3d_Result Tcp3d_status ( IN    Tcp3d_Instance    *inst,\r
1156                             INOUT Tcp3d_Sts         *drvStatus );\r
1157 \r
1158 /**\r
1159  *  @b  Description\r
1160  *  @n  \r
1161  *              This API could be used to change or update the TCP3D driver\r
1162  *              instance values which are set during the init time. The\r
1163  *              Tcp3d_CtrlCmd enum structure gives the supported commads.\r
1164  *  \r
1165  *  \note       -# This API is not fully scoped and the possible control\r
1166  *              commands could be extended in future.\r
1167  *              -# We may need to protect the instance value updations, once\r
1168  *              they are allowed to change in any state.\r
1169  * \r
1170  *  \param[in]      *inst\r
1171  *              This is the driver instance.\r
1172  *\r
1173  *  \param[in]      *drvCtrl\r
1174  *              Structure used for keeping the control request command and\r
1175  *              also for passing any input values along with as required. \r
1176  *\r
1177  *  \pre        Set appropriate command value before calling the function.\r
1178  * \r
1179  *  \post       Depending on the command the driver behaviour would be changed. \r
1180  *\r
1181  *  \retVal     Success -   TCP3D_DRV_NO_ERR (valid command)\r
1182  *  \retVal     Failure -   TCP3D_DRV_FAIL (invalid command)\r
1183  *\r
1184  */\r
1185 Tcp3d_Result Tcp3d_control (IN Tcp3d_Instance   *inst,\r
1186                             IN Tcp3d_Ctrl       *drvCtrl );\r
1187 \r
1188 /**\r
1189 @}\r
1190 */\r
1191 /* ========================================================================= */\r
1192 \r
1193 /* ========================================================================= */\r
1194 /**\r
1195  * Utility Function definitions\r
1196  *  - Register Preparation Function definitions\r
1197  *  - Any other functions\r
1198  */\r
1199 \r
1200 /** @addtogroup TCP3D_DRV_UTIL_FUNCTION\r
1201  @{ */\r
1202 \r
1203 /**\r
1204  *  @b  Description\r
1205  *  @n  \r
1206  *              TCP3D Driver function for preparing the common control registers\r
1207  *              from the input structure parameters using the CSL_FINS macro.\r
1208  * \r
1209  *              The outputs could be used to write into the actual TCP3 decoder\r
1210  *              memory registers directly or DMAed to bring the TCP3 decoder\r
1211  *              state machine to WAIT for inputs state.\r
1212  * \r
1213  *  \param[in]      *ctrl\r
1214  *              Pointer to structure of type Tcp3d_CtrlParams for providing\r
1215  *              the input parameters for the control variables.\r
1216  *\r
1217  *  \param[out]     *modeReg\r
1218  *              Pointer to the mode register variable to put the prepared value. \r
1219  * \r
1220  *  \param[out]     *endReg\r
1221  *              Pointer to the endian register variable for placing the\r
1222  *              prepared value. \r
1223  * \r
1224  *  \param[out]     *exeRegP0\r
1225  *              Pointer to the process 0 execution register variable for\r
1226  *              placing the prepared value. \r
1227  * \r
1228  *  \param[out]     *exeRegP1\r
1229  *              Pointer to the process 1 execution register variable for\r
1230  *              placing the prepared value.\r
1231  * \r
1232  *  \pre        All the parameters in the input ctrl structure must be set\r
1233  *              before calling this API. Read the Tcp3d_CtrlParams structure\r
1234  *              description to see if some parameters are reserved for future\r
1235  *              use in which case they need not be set.  \r
1236  *\r
1237  *  \post       \r
1238  *\r
1239  *  \return     \r
1240  * \r
1241  */\r
1242 void Tcp3d_prepControlRegs( IN  Tcp3d_CtrlParams    *ctrl,\r
1243                                 OUT uint32_t              *modeReg,\r
1244                                 OUT uint32_t              *endReg,\r
1245                                 OUT uint32_t              *exeRegP0,\r
1246                                 OUT uint32_t              *exeRegP1);\r
1247 \r
1248 /**\r
1249  *  @b  Description\r
1250  *  @n  \r
1251  *              This is a utility function provided as part of TCP3D Driver for\r
1252  *              preparing a fixed set of input config registers that would be\r
1253  *              fixed for a typical configuration and will not vary from \r
1254  *              code block to code block.\r
1255  * \r
1256  *              This function is used for preparing IC2, IC3, IC8-IC11 registers\r
1257  *              only of 15 registers (IC0-IC14) using CSL_FINS macro.\r
1258  * \r
1259  *              The output outICRegs could be used as template IC registers\r
1260  *              array when preparing the input config registers for code blocks.\r
1261  * \r
1262  *  \param[in]      *inCfgParams\r
1263  *              Pointer to structure of input parameters of type\r
1264  *              Tcp3d_InCfgParams for preparing IC0-IC14 (15 registers).\r
1265  *\r
1266  *  \param[out]     *outICRegs\r
1267  *              Pointer to the array for holding the 15 registers memory.\r
1268  *              @b Note that only the relavent registers are updated.  \r
1269  * \r
1270  *  \pre        Parameters required for preparing fixed registers (IC2, IC3,\r
1271  *              IC8-IC11) must be set in the input parameters structure\r
1272  *              before calling this API.\r
1273  * \r
1274  *              Read the Tcp3d_InCfgParams structure description to see details\r
1275  *              on which parameters are needed.\r
1276  *\r
1277  *  \post       \r
1278  *\r
1279  *  \return     \r
1280  * \r
1281  */\r
1282 void Tcp3d_prepFixedConfigRegs ( \r
1283                             IN  Tcp3d_InCfgParams * const RESTRICT inCfgParams,\r
1284                             OUT uint32_t            * const RESTRICT outICRegs);\r
1285 \r
1286 /**\r
1287  *  @b  Description\r
1288  *  @n  \r
1289  *              This is a utility function provided as part of TCP3D Driver for\r
1290  *              preparing the input config registers that will be used for\r
1291  *              sending to TCP3 decoder IP memory before sending the LLR data.\r
1292  * \r
1293  *              This function is used for preparing all the 15 input config\r
1294  *              registers (IC0-IC14) using CSL_FINS macro.\r
1295  * \r
1296  *              This function along with Tcp3d_prepFixedConfigRegs provides\r
1297  *              an otimization knowing that some of the registers will not\r
1298  *              change for each block in general. The last two paramaters are\r
1299  *              provided to use this feature. Once the fixed register fields\r
1300  *              are known, Tcp3d_prepFixedConfigRegs funciton could be\r
1301  *              called for preparing the fixed registers and get the tempICRegs\r
1302  *              array ready in advance sometime during init time. This array\r
1303  *              could be supplied with the Tcp3d_prepConfigRegs API along\r
1304  *              with a flag to copy the fixed registers from the array instead\r
1305  *              of preparing.\r
1306  * \r
1307  *  \param[in]      mode\r
1308  *              Mode of the TCP3D IP block used for determing what to fill in to\r
1309  *              IC12, IC13, IC14 registers (Initial ITG Param values).\r
1310  *              These registers must be prepared only for LTE and WIMAX case,\r
1311  *              otherwise set to ZERO always.\r
1312  * \r
1313  *  \param[in]      *inCfgParams\r
1314  *              Pointer to structure of input parameters of type\r
1315  *              Tcp3d_InCfgParams for preparing IC0-IC14 (15 registers).\r
1316  *\r
1317  *  \param[out]     *outICRegs\r
1318  *              Pointer to the memory array for holding the fully prepared\r
1319  *              registers, ready to be copied to TCP3 decoder IP memory.\r
1320  * \r
1321  *  \param[in]      *tempICRegs\r
1322  *              Template memory array pointer with fixed registers prepared.\r
1323  *              This array should have been prepared one time by calling the\r
1324  *              Tcp3d_prepFixedConfigRegs function well in advance.\r
1325  *              Part of this array will be used only if the copyFixedReg flag\r
1326  *              parameter is set to non-zero value. \r
1327  * \r
1328  *  \param[in]      copyFixedReg\r
1329  *              Flag to tell whether to use the tempICRegs array to copy the\r
1330  *              fixed input config registers or to prepare all of them in this\r
1331  *              function.\r
1332  * \r
1333  *  \pre        All the parameters in the input structure param must be set\r
1334  *              before calling this API.\r
1335  *\r
1336  *              You can avoid setting some of the register parameters, if you\r
1337  *              use the optimization trick as described in the description. In\r
1338  *              that case, the fixed register parameterss need not be set.\r
1339  *\r
1340  *              Read the Tcp3d_InCfgParams structure description to see details\r
1341  *              on which parameters are needed.\r
1342  *\r
1343  *  \post       \r
1344  *\r
1345  *  \return     \r
1346  * \r
1347  *  \ref        Tcp3d_prepFixedConfigRegs\r
1348  *\r
1349  */\r
1350 void Tcp3d_prepConfigRegs (\r
1351                             IN  uint8_t                              mode,\r
1352                             IN  Tcp3d_InCfgParams * const RESTRICT inCfgParams,\r
1353                             OUT uint32_t            * const RESTRICT outICRegs,\r
1354                             IN  uint32_t            * const RESTRICT tempICRegs,\r
1355                             IN  uint8_t                              copyFixedReg);\r
1356 \r
1357 /**\r
1358  *  @b  Description\r
1359  *  @n  \r
1360  *              This is a utility function is provided as part of TCP3D Driver\r
1361  *              for preparing the specific input config registers which depend\r
1362  *              on the block size.\r
1363  * \r
1364  *              This function can be used for preparing IC0, IC1, IC12-IC14\r
1365  *              registers only out of 15 registers (IC0-IC14) using \r
1366  *              CSL_FINS macro.\r
1367  *\r
1368  *              This function is called per code block.\r
1369  * \r
1370  *  \param[in]      mode\r
1371  *              Driver mode of operation.\r
1372  *\r
1373  *  \param[out]     *outICRegs\r
1374  *              Pointer to the array for holding the 15 registers memory.\r
1375  *              @b Note that only the relavent registers are updated.  \r
1376  * \r
1377  *  \param[in]      numsw0\r
1378  *              Number of SW0 used in the decoder.\r
1379  *\r
1380  *  \param[in]      blockLen\r
1381  *              Block length value as required to be populated in the registers.\r
1382  *\r
1383  *  \param[in]      sw0LenSel\r
1384  *              The value of this parameter depends on the actual SW0 length\r
1385  *              used and the possible values are described below.\r
1386  *                  0 \96 16 bits\r
1387  *                  1 \96 32 bits\r
1388  *                  2 \96 48 bits\r
1389  *                  3 \96 64 bits\r
1390  *                  4 \96 96 bits\r
1391  *                  5 \96 128 bits\r
1392  *\r
1393  *  \param[in]      sw1Len\r
1394  *              The value of this parameter depends on the actual SW1 length\r
1395  *              used and the possible values are described below.\r
1396  *                  9 \96 10 bits\r
1397  *                  10 \96 11 bits\r
1398  *                  11 \96 12 bits\r
1399  *                  ...\r
1400  *                  127 \96 128 bits\r
1401  *\r
1402  *  \param[in]      sw2LenSel\r
1403  *              The value of this parameter depends on the actual SW1 length\r
1404  *              used and the possible values are described below.\r
1405  *                  0 \96 SW2 is not present\r
1406  *                  1 \96 SW2 length is same as SW1\r
1407  *                  2 \96 SW2 length is less by 2 bits from SW1\r
1408  *\r
1409  *  \param[in]      *itgParam\r
1410  *              Interleaver Table Generation init params.\r
1411  *\r
1412  *  \pre        Input Parameters required for this function must be computed\r
1413  *              as per the guildelines given in the user guide for preparing\r
1414  *              these specific registers (IC0, IC1, IC12-IC14).\r
1415  * \r
1416  *  \Note       The following rules must be followed when programming sliding\r
1417  *              window values, otherwise expect unpredictable results.\r
1418  *          1.  SW0 length >= SW1 length; If num_sw0 > 0\r
1419  *          2.  SW1 length >= 10\r
1420  *          3.  If (SW0 length - SW1 length  < 4 and SW1 length != SW2 length )\r
1421  *                  then SW2 length must = 0 (off)\r
1422  *          4.  K <= N * 128 * SW0 Nominal length\r
1423  * \r
1424  *          where K = block Length and N = Number of MAP decoders\r
1425  *                                      ( 2 - LTE/WiMAX mode )\r
1426  *                                      ( 1 - WCDMA mode )\r
1427  *\r
1428  *  \post       \r
1429  *\r
1430  *  \return     \r
1431  * \r
1432  */\r
1433 void Tcp3d_prepBlockSizeDepConfigRegs ( IN  uint8_t                   mode,\r
1434                                         OUT uint32_t * const RESTRICT outICRegs,\r
1435                                         IN  uint8_t                   numsw0,\r
1436                                         IN  uint16_t                  blockLen,\r
1437                                         IN  uint8_t                   sw0LenSel,\r
1438                                         IN  uint8_t                   sw2LenSel,\r
1439                                         IN  uint8_t                   sw1Len,\r
1440                                         IN  uint16_t * const RESTRICT itgParam);\r
1441 \r
1442 /**\r
1443  *  @b  Description\r
1444  *  @n  \r
1445  *              This is a utility function is provided as part of TCP3D Driver\r
1446  *              for preparing the beta state value dependent input config\r
1447  *              registers only.\r
1448  * \r
1449  *              This function can be used for preparing IC4-IC7 registers only\r
1450  *              out of 15 registers (IC0-IC14) using CSL_FINS macro.\r
1451  * \r
1452  *  \param[in]      mode\r
1453  *              Driver mode of operation.\r
1454  *\r
1455  *  \param[out]     *outICRegs\r
1456  *              Pointer to the array for holding the 15 registers memory.\r
1457  *              @b Note that only the relavent registers are updated.  \r
1458  * \r
1459  *  \param[in]      *betaMap0\r
1460  *              Beta state values for MAP0 decoder.\r
1461  * \r
1462  *  \param[in]      *betaMap1\r
1463  *              Beta state values for MAP1 decoder.\r
1464  * \r
1465  *  \pre        Input Parameters required for this function must be computed\r
1466  *              as per the guildelines given in the user guide for preparing\r
1467  *              these specific registers (IC4-IC7).\r
1468  * \r
1469  *  \post       \r
1470  *\r
1471  *  \return     \r
1472  * \r
1473  */\r
1474 void Tcp3d_prepBetaStateConfigRegs( IN  uint8_t                   mode,\r
1475                                     OUT uint32_t * const RESTRICT outICRegs,\r
1476                                     IN  int8_t   * const RESTRICT betaMap0,\r
1477                                     IN  int8_t   * const RESTRICT betaMap1);\r
1478 \r
1479 /** \r
1480  *  @b  Description\r
1481  *  @n  \r
1482  *              Calculates initial beta state values using the tail bits that\r
1483  *              could be used in preparing the TCP3D input configuration\r
1484  *              registers.\r
1485  *           \r
1486  *  \param[in]  tailBits\r
1487  *              Tail Bits buffer of size 12. The tail bits are expected to be\r
1488  *              in the order Xt1[0],Pt1[0],Xt1[1],Pt1[1],Xt1[2],Pt1[2],Xt2[0],\r
1489  *              Pt2[0],Xt2[1],Pt2[1],Xt2[2],Pt2[2].\r
1490  *\r
1491  *  \param[in]  signChange\r
1492  *              For sign inversion information.\r
1493  *                  1 - the sign of the outputs changed\r
1494  *                  0 - the output sign is unchanged.\r
1495  *  \r
1496  *  \param[out] Kt\r
1497  *              Number of trellis stages used to calculate initial beta states.\r
1498  *              This values is computed using the formula [3 - (Kext-K)],\r
1499  *              where K is the code block length.\r
1500  *  \r
1501  *  \param[out] beta0Ptr\r
1502  *              Initial beta state values for the MAP0 decoder computed from\r
1503  *              the tail bits. The buffer size is 8.\r
1504  *\r
1505  *  \param[out] beta1Ptr\r
1506  *              Initial beta state values for the MAP1 decoder computed from\r
1507  *              the tail bits. The buffer size is 8.\r
1508  *\r
1509  *  \return\r
1510  */\r
1511 void Tcp3d_betaStates(  IN  int8_t    * const RESTRICT tailBits,\r
1512                         IN  int32_t   signChange,\r
1513                         IN  int32_t   Kt,\r
1514                         OUT int8_t    * const RESTRICT beta0Ptr,\r
1515                         OUT int8_t    * const RESTRICT beta1Ptr);\r
1516 \r
1517 /**\r
1518  *  @b Description\r
1519  *  @n  \r
1520  *      The function is used to get the version information of the TCP3D Driver.\r
1521  *\r
1522  *  @retval\r
1523  *      Version Information.\r
1524  */\r
1525 uint32_t Tcp3d_getVersion (void);\r
1526 \r
1527 /**\r
1528  *  @b Description\r
1529  *  @n  \r
1530  *      The function is used to get the version string for the TCP3D Driver.\r
1531  *\r
1532  *  @retval\r
1533  *      Version String.\r
1534  */\r
1535 const char* Tcp3d_getVersionStr (void);\r
1536 \r
1537 /**\r
1538 @}\r
1539 */\r
1540 /* ========================================================================= */\r
1541 \r
1542 #endif /* _TCP3D_DRV_H_ */\r