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