# TCP3D Driver Utility Functions
[TCP3 Decoder Driver]

## Functions

void | Tcp3d_prepControlRegs (IN Tcp3d_CtrlParams *ctrl, OUT uint32_t *modeReg, OUT uint32_t *endReg, OUT uint32_t *exeRegP0, OUT uint32_t *exeRegP1)
void | Tcp3d_prepFixedConfigRegs (IN Tcp3d_InCfgParams *const RESTRICT inCfgParams, OUT uint32_t *const RESTRICT outICRegs)
void | Tcp3d_prepConfigRegs (IN uint8_t mode, IN Tcp3d_InCfgParams *const RESTRICT inCfgParams, OUT uint32_t *const RESTRICT outICRegs, IN uint32_t *const RESTRICT tempICRegs, IN uint8_t copyFixedReg)
void | Tcp3d_prepBlockSizeDepConfigRegs (IN uint8_t mode, OUT uint32_t *const RESTRICT outICRegs, IN uint8_t numsw0, IN uint16_t blockLen, IN uint8_t sw0LenSel, IN uint8_t sw2LenSel, IN uint8_t sw1Len, IN uint16_t *const RESTRICT itgParam)
void | Tcp3d_prepBetaStateConfigRegs (IN uint8_t mode, OUT uint32_t *const RESTRICT outICRegs, IN int8_t *const RESTRICT betaMap0, IN int8_t *const RESTRICT betaMap1)
void | Tcp3d_betaStates (IN int8_t *const RESTRICT tailBits, IN int32_t signChange, IN int32_t Kt, OUT int8_t *const RESTRICT beta0Ptr, OUT int8_t *const RESTRICT beta1Ptr)
uint32_t | Tcp3d_getVersion (void)
const char * | Tcp3d_getVersionStr (void)

## Detailed Description

Utility Function definitions

- Register Preparation Function definitions
- Any other functions

## Function Documentation

void Tcp3d_betaStates | ( | IN int8_t *const RESTRICT | tailBits,
|  | IN int32_t | signChange,
|  | IN int32_t | Kt,
|  | OUT int8_t *const RESTRICT | beta0Ptr,
|  | OUT int8_t *const RESTRICT | beta1Ptr |
| ) |  |  |

Description
Calculates initial beta state values using the tail bits that could be used in preparing the TCP3D input configuration registers.

Parameters:

  `[in]` | tailBits | Tail Bits buffer of size 12. The tail bits are expected to be in the order Xt1[0],Pt1[0],Xt1[1],Pt1[1],Xt1[2],Pt1[2],Xt2[0], Pt2[0],Xt2[1],Pt2[1],Xt2[2],Pt2[2].
  `[in]` | signChange | For sign inversion information. 1 - the sign of the outputs changed 0 - the output sign is unchanged.
  `[out]` | Kt | Number of trellis stages used to calculate initial beta states. This values is computed using the formula [3 - (Kext-K)], where K is the code block length.
  `[out]` | beta0Ptr | Initial beta state values for the MAP0 decoder computed from the tail bits. The buffer size is 8.
  `[out]` | beta1Ptr | Initial beta state values for the MAP1 decoder computed from the tail bits. The buffer size is 8.

Returns:

uint32_t Tcp3d_getVersion | ( | void |  | ) |

Description
The function is used to get the version information of the TCP3D Driver.

Return values:

  | Version | Information.

const char* Tcp3d_getVersionStr | ( | void |  | ) |

Description
The function is used to get the version string for the TCP3D Driver.

Return values:

  | Version | String.

void Tcp3d_prepBetaStateConfigRegs | ( | IN uint8_t | mode,
|  | OUT uint32_t *const RESTRICT | outICRegs,
|  | IN int8_t *const RESTRICT | betaMap0,
|  | IN int8_t *const RESTRICT | betaMap1 |
| ) |  |  |

Description
This is a utility function is provided as part of TCP3D Driver for preparing the beta state value dependent input config registers only.

This function can be used for preparing IC4-IC7 registers only out of 15 registers (IC0-IC14) using CSL_FINS macro.

Parameters:

  `[in]` | mode | Driver mode of operation.
  `[out]` | *outICRegs | Pointer to the array for holding the 15 registers memory. Note that only the relavent registers are updated.
  `[in]` | *betaMap0 | Beta state values for MAP0 decoder.
  `[in]` | *betaMap1 | Beta state values for MAP1 decoder.

Precondition:
  Input Parameters required for this function must be computed as per the guildelines given in the user guide for preparing these specific registers (IC4-IC7).

Postcondition:

Returns:

void Tcp3d_prepBlockSizeDepConfigRegs | ( | IN uint8_t | mode,
|  | OUT uint32_t *const RESTRICT | outICRegs,
|  | IN uint8_t | numsw0,
|  | IN uint16_t | blockLen,
|  | IN uint8_t | sw0LenSel,
|  | IN uint8_t | sw2LenSel,
|  | IN uint8_t | sw1Len,
|  | IN uint16_t *const RESTRICT | itgParam |
| ) |  |  |

Description
This is a utility function is provided as part of TCP3D Driver for preparing the specific input config registers which depend on the block size.

This function can be used for preparing IC0, IC1, IC12-IC14 registers only out of 15 registers (IC0-IC14) using CSL_FINS macro.

This function is called per code block.

Parameters:

  `[in]` | mode | Driver mode of operation.
  `[out]` | *outICRegs | Pointer to the array for holding the 15 registers memory. Note that only the relavent registers are updated.
  `[in]` | numsw0 | Number of SW0 used in the decoder.
  `[in]` | blockLen | Block length value as required to be populated in the registers.
  `[in]` | sw0LenSel | The value of this parameter depends on the actual SW0 length used and the possible values are described below. 0 – 16 bits 1 – 32 bits 2 – 48 bits 3 – 64 bits 4 – 96 bits 5 – 128 bits
  `[in]` | sw1Len | The value of this parameter depends on the actual SW1 length used and the possible values are described below. 9 – 10 bits 10 – 11 bits 11 – 12 bits ... 127 – 128 bits
  `[in]` | sw2LenSel | The value of this parameter depends on the actual SW1 length used and the possible values are described below. 0 – SW2 is not present 1 – SW2 length is same as SW1 2 – SW2 length is less by 2 bits from SW1
  `[in]` | *itgParam | Interleaver Table Generation init params.

Precondition:
  Input Parameters required for this function must be computed as per the guildelines given in the user guide for preparing these specific registers (IC0, IC1, IC12-IC14).

The following rules must be followed when programming sliding window values, otherwise expect unpredictable results. 1. SW0 length >= SW1 length; If num_sw0 > 0 2. SW1 length >= 10 3. If (SW0 length - SW1 length < 4 and SW1 length != SW2 length ) then SW2 length must = 0 (off) 4. K <= N * 128 * SW0 Nominal length

where K = block Length and N = Number of MAP decoders ( 2 - LTE/WiMAX mode ) ( 1 - WCDMA mode )

Postcondition:

Returns:

void Tcp3d_prepConfigRegs | ( | IN uint8_t | mode,
|  | IN Tcp3d_InCfgParams *const RESTRICT | inCfgParams,
|  | OUT uint32_t *const RESTRICT | outICRegs,
|  | IN uint32_t *const RESTRICT | tempICRegs,
|  | IN uint8_t | copyFixedReg |
| ) |  |  |

Description
This is a utility function provided as part of TCP3D Driver for preparing the input config registers that will be used for sending to TCP3 decoder IP memory before sending the LLR data.

This function is used for preparing all the 15 input config registers (IC0-IC14) using CSL_FINS macro.

This function along with Tcp3d_prepFixedConfigRegs provides an otimization knowing that some of the registers will not change for each block in general. The last two paramaters are provided to use this feature. Once the fixed register fields are known, Tcp3d_prepFixedConfigRegs funciton could be called for preparing the fixed registers and get the tempICRegs array ready in advance sometime during init time. This array could be supplied with the Tcp3d_prepConfigRegs API along with a flag to copy the fixed registers from the array instead of preparing.

Parameters:

  `[in]` | mode | Mode of the TCP3D IP block used for determing what to fill in to IC12, IC13, IC14 registers (Initial ITG Param values). These registers must be prepared only for LTE and WIMAX case, otherwise set to ZERO always.
  `[in]` | *inCfgParams | Pointer to structure of input parameters of type Tcp3d_InCfgParams for preparing IC0-IC14 (15 registers).
  `[out]` | *outICRegs | Pointer to the memory array for holding the fully prepared registers, ready to be copied to TCP3 decoder IP memory.
  `[in]` | *tempICRegs | Template memory array pointer with fixed registers prepared. This array should have been prepared one time by calling the Tcp3d_prepFixedConfigRegs function well in advance. Part of this array will be used only if the copyFixedReg flag parameter is set to non-zero value.
  `[in]` | copyFixedReg | Flag to tell whether to use the tempICRegs array to copy the fixed input config registers or to prepare all of them in this function.

Precondition:
  All the parameters in the input structure param must be set before calling this API.

You can avoid setting some of the register parameters, if you use the optimization trick as described in the description. In that case, the fixed register parameterss need not be set.

Read the Tcp3d_InCfgParams structure description to see details on which parameters are needed.

Postcondition:

Returns:

Tcp3d_prepFixedConfigRegs

void Tcp3d_prepControlRegs | ( | IN Tcp3d_CtrlParams * | ctrl,
|  | OUT uint32_t * | modeReg,
|  | OUT uint32_t * | endReg,
|  | OUT uint32_t * | exeRegP0,
|  | OUT uint32_t * | exeRegP1 |
| ) |  |  |

Description
TCP3D Driver function for preparing the common control registers from the input structure parameters using the CSL_FINS macro.

The outputs could be used to write into the actual TCP3 decoder memory registers directly or DMAed to bring the TCP3 decoder state machine to WAIT for inputs state.

Parameters:

  `[in]` | *ctrl | Pointer to structure of type Tcp3d_CtrlParams for providing the input parameters for the control variables.
  `[out]` | *modeReg | Pointer to the mode register variable to put the prepared value.
  `[out]` | *endReg | Pointer to the endian register variable for placing the prepared value.
  `[out]` | *exeRegP0 | Pointer to the process 0 execution register variable for placing the prepared value.
  `[out]` | *exeRegP1 | Pointer to the process 1 execution register variable for placing the prepared value.

Precondition:
  All the parameters in the input ctrl structure must be set before calling this API. Read the Tcp3d_CtrlParams structure description to see if some parameters are reserved for future use in which case they need not be set.

Postcondition:

Returns:

void Tcp3d_prepFixedConfigRegs | ( | IN Tcp3d_InCfgParams *const RESTRICT | inCfgParams,
|  | OUT uint32_t *const RESTRICT | outICRegs |
| ) |  |  |

Description
This is a utility function provided as part of TCP3D Driver for preparing a fixed set of input config registers that would be fixed for a typical configuration and will not vary from code block to code block.

This function is used for preparing IC2, IC3, IC8-IC11 registers only of 15 registers (IC0-IC14) using CSL_FINS macro.

The output outICRegs could be used as template IC registers array when preparing the input config registers for code blocks.

Parameters:

  `[in]` | *inCfgParams | Pointer to structure of input parameters of type Tcp3d_InCfgParams for preparing IC0-IC14 (15 registers).
  `[out]` | *outICRegs | Pointer to the array for holding the 15 registers memory. Note that only the relavent registers are updated.

Precondition:
  Parameters required for preparing fixed registers (IC2, IC3, IC8-IC11) must be set in the input parameters structure before calling this API.

Read the Tcp3d_InCfgParams structure description to see details on which parameters are needed.

Postcondition:

Returns:

Copyright 2012, Texas Instruments Incorporated