# TCP3D Driver Functions
[TCP3 Decoder Driver]

## Functions

Tcp3d_Result | Tcp3d_getNumBuf (IN Tcp3d_SizeCfg *cfg, OUT int16_t *nbufs)
Tcp3d_Result | Tcp3d_getBufDesc (IN Tcp3d_SizeCfg *cfg, OUT Tcp3d_MemBuffer bufs[])
Tcp3d_Result | Tcp3d_reset (IN Tcp3d_Instance *tcp3dInst, IN uint32_t codeBlocks)
Tcp3d_Result | Tcp3d_init (IN Tcp3d_MemBuffer bufs[], IN Tcp3d_InitParams *drvInitParams)
Tcp3d_Result | Tcp3d_deInit (IN Tcp3d_Instance *tcp3dInst)
Tcp3d_Result | Tcp3d_enqueueCodeBlock (IN Tcp3d_Instance *tcp3dInst, IN uint32_t blockLength, IN uint32_t *inputConfigPtr, IN int8_t *llrPtr, IN uint32_t llrOffset, IN uint32_t *hdPtr, IN int8_t *sdPtr, IN uint32_t sdOffset, IN uint32_t *statusPtr, IN uint8_t ntfEventFlag)
Tcp3d_Result | Tcp3d_start (IN Tcp3d_Instance *inst, IN uint8_t startMode)
Tcp3d_Result | Tcp3d_status (IN Tcp3d_Instance *inst, INOUT Tcp3d_Sts *drvStatus)
Tcp3d_Result | Tcp3d_control (IN Tcp3d_Instance *inst, IN Tcp3d_Ctrl *drvCtrl)

## Detailed Description

Driver Function definitions

## Function Documentation

Tcp3d_Result Tcp3d_control | ( | IN Tcp3d_Instance * | inst,
|  | IN Tcp3d_Ctrl * | drvCtrl |
| ) |  |  |

Description
This API could be used to change or update the TCP3D driver instance values which are set during the init time. The Tcp3d_CtrlCmd enum structure gives the supported commads.

Note:
  -# This API is not fully scoped and the possible control commands could be extended in future.
  1. We may need to protect the instance value updations, once they are allowed to change in any state.

Parameters:

  `[in]` | *inst | This is the driver instance.
  `[in]` | *drvCtrl | Structure used for keeping the control request command and also for passing any input values along with as required.

Precondition:
  Set appropriate command value before calling the function.

Postcondition:
  Depending on the command the driver behaviour would be changed.

Success - TCP3D_DRV_NO_ERR (valid command) Failure - TCP3D_DRV_FAIL (invalid command)

Tcp3d_Result Tcp3d_deInit | ( | IN Tcp3d_Instance * | tcp3dInst | ) |

Description
TCP3D Driver De-Initialization function which must be called to close the corresponding instance.

This funciton does the following:

1. First this function clears any EDMA specific registers set.

Parameters:

  `[in]` | *tcp3dInst | This is the driver instance.

Precondition:

Postcondition:
  Application can free the resources and memory allocated for this instance after this function.

Success - TCP3D_DRV_NO_ERR Failure - TCP3D_DRV_FAIL

Tcp3d_Result Tcp3d_enqueueCodeBlock | ( | IN Tcp3d_Instance * | tcp3dInst,
|  | IN uint32_t | blockLength,
|  | IN uint32_t * | inputConfigPtr,
|  | IN int8_t * | llrPtr,
|  | IN uint32_t | llrOffset,
|  | IN uint32_t * | hdPtr,
|  | IN int8_t * | sdPtr,
|  | IN uint32_t | sdOffset,
|  | IN uint32_t * | statusPtr,
|  | IN uint8_t | ntfEventFlag |
| ) |  |  |

Description
This is a run-time API for appending the codeblocks to the pseudo PaRAM list as the blocks arrive. This function updates the pseudo PaRAM set entries and chains to the previous block in the corresponding list (PING or PONG).

Enqueuing is done alternately between the two lists until the current list is full. The no room case is indicated with return error TCP3D_DRV_INPUT_LIST_FULL.

On each succeesful enqueue, the corresponding load counter for the path is incremented. This funciton updates some run-time varaibles which keeps track of ping and pong list indexes and counters.

This function primarily does the following:

1. Updates the pseudo PaRAM set with the addresses passed as paramters. Also, updates necessary count and index values within the pseudo PaRAM set which depend on the block size and are not pre-filled during init.
2. Links the optional outputs, if present, to the HD param and sets necessary TCC values.
3. If the ntfEventFlag is set for notification, the NTF Param is linked with the last param from the set.
4. Chaining to the previous block in the corresponding list is done, execept for the first one in the list. This is done by
   - Changing the TCC field of the last param in the previous block to trigger the L2P channel.
   - Updating the link field with the dummy or NTFD depending on whether the previous block has notification or not.
5. Calls the Tcp3d_start() function with auto mode as needed after the application initiated the first start.

This function is executed at the application task thread for queueing the code blocks to the input pseudo PaRAM list. They will be copied to the actual PaRAM area using the L2P channel when the previous block is decoded and outputs are read as specified.

Application need to check the return value to take appropriate action.

1. If no error try enqueuing next block.
2. If LIST FULL error, either wait for some time and try enqueuing or enable EDMA completion interrupts for L2P channels. Upon receiving the interrupt the enqueuing could be tried again.

Since the TCC for L2P channels always point to REVT, enabling L2P channel interrupts would showup as REVT channel call backs.

Parameters:

  `[in]` | *tcp3dInst | This is the driver instance.
  `[in]` | blockLength | Code Block length value which is used for setting some of the PaRAM counts.
  `[in]` | *inputConfigPtr | Pointer to the input config registers prepared for the current code block.
  `[in]` | *llrPtr | Input data pointer where the systematic, parity 1 and parity 2 streams are available.
  `[in]` | llrOffset | Input data offset between the three streams. Used for setting the EDMA trasfer type (A-Sync or AB-Sync) and also to set the source jump index.
  `[in]` | *hdPtr | Pointer to the memory where the decoded hard decision values to be DMAed.
  `[in]` | *statusPtr | Pointer to the memory to DMA the three status register values.

This is a selective parameter which application uses only if the corresponding bit is set in the inputConfigRegs for reading the TCP3D output memory.

If not used, set to NULL to avoid any undesired behaviour from the TCP3 decoder. This will also save the time for programming.

Parameters:

  `[in]` | *sdPtr | Pointer to the memory where the decoded soft decision values to be DMAed.

This is a selective parameter which application uses only if the corresponding bit is set in the inputConfigRegs for reading the TCP3D output memory.

If not used, set to NULL to avoid any undesired behaviour from the TCP3 decoder. This will also save the time for programming.

Parameters:

  `[in]` | sdOffset | Output data offset between the three streams. Not valid for split more, since there will be only one stream.

If not used, set to NULL to avoid any undesired behaviour from the TCP3 decoder.

Parameters:

  `[in]` | ntfEventFlag | Flag for enabling the notification event to be generated at the end of output transfer completion of the code block. When set, the event number provided during the init.

Useful for application to get notification after a specific code block is decoded to start the post-processing.

Precondition:
  This driver API MUST be called only after the Tcp3d_init() function is called.

Postcondition:
  Driver state value could be changed to TCP3D_DRV_STATE_RUNNING from TCP3D_DRV_STATE_PAUSE. This happens only if the startFlag was set by this time.

Success - TCP3D_DRV_NO_ERR Failure - TCP3D_DRV_INPUT_LIST_FULL

Tcp3d_Result Tcp3d_getBufDesc | ( | IN Tcp3d_SizeCfg * | cfg,
|  | OUT Tcp3d_MemBuffer | bufs[] |
| ) |  |  |

Description
TCP3D Driver function for providing the attributes of all the number of buffers requested through the structure of type Tcp3d_MemBuffer provided.

Parameters:

  `[in]` | *cfg | Pointer to the structure of type Tcp3d_SizeCfg which has specific information used for determining the buffer requirements.

TCP3D Driver uses the field maxCodeBlocks for determining the buffer sizes required.

Parameters:

  `[out]` | **bufs | Pointer to the array of Tcp3d_MemBuffer structure of size provided through the Tcp3d_getNumBuf() API.

TCP3D Driver fills all the fileds of the structure except the base which application fills after allocating the memory as per the attributes requested.

Precondition:
  Set the cfg->maxCodeBlocks value before calling this API.

Postcondition:

Returns:
  Status reported as either TCP3D_DRV_NO_ERR or TCP3D_DRV_FAIL.

Tcp3d_Result Tcp3d_getNumBuf | ( | IN Tcp3d_SizeCfg * | cfg,
|  | OUT int16_t * | nbufs |
| ) |  |  |

Description
TCP3D Driver function for providing the number of buffers required.

Parameters:

  `[in]` | *cfg | Pointer to the structure of type Tcp3d_SizeCfg which has specific information used for determining the buffer requirements.

For Example, TCP3D could use one field maxCodeBlocks to determine number of buffers required.

Parameters:

  `[out]` | *nbufs | Pointer of a variable to which TCP3D Driver proveds the number of buffers required.

Precondition:
  Set the cfg->maxCodeBlocks value before calling this API.

Postcondition:

Returns:
  Status reported as either TCP3D_DRV_NO_ERR or TCP3D_DRV_FAIL.

Tcp3d_Result Tcp3d_init | ( | IN Tcp3d_MemBuffer | bufs[],
|  | IN Tcp3d_InitParams * | drvInitParams |
| ) |  |  |

Description
TCP3D Driver Initialization function which must be called only once to initialize the driver instance and other required resources needed for the driver functionality.

This funciton does the following:

1. First this function reads the bufs structure to get the base addresses to set the instance and other strucures. If any base address is NULL, driver exits immediately with error.
2. Initializes all the run-time instance variables to default values.
3. All init-time variables are set either from the drvInitParams input structure or set directly.
4. Copies all the EDMA resource information into the instance.
   - Does some sanity check on the channel numbers associated with REVTs.
   - Enables all the EVENT triggered channels.
   - Pre-fill most of the PaRAM entries for both the physical and linked channels which will be used in run-time in the enqueue funciton.
5. Initializes the pseudo PaRAM buffer with fixed values.
6. All required reset funcitons are called from this function to eliminate the need to call the reset API immediately.
7. Finally before exit, starts the TCP3 Decoder state machine by writing into the control registers from the values provided in the drvInitParams->ctrlParams structure.

Parameters:

  `[in]` | **bufs | Pointer to the array of Tcp3d_MemBuffer structure of size provided through the Tcp3d_getNumBuf() API. This strucure must have all the fields filled by now. The bufs[0]->base value will be used for initializing the driver instance.
  `[in]` | drvInitParams | Driver initialization parameters structure. This structure is used for getting all the required resources for the driver to initialize the instance. Look into the description of the Tcp3d_InitParams structure elements for details.

Precondition:

Postcondition:

Success - TCP3D_DRV_NO_ERR Failure - TCP3D_DRV_INVALID_BUFF Failure - TCP3D_DRV_INVALID_EDMA_CH Failure - TCP3D_DRV_FAIL_EDMA_GET_PARAM_ADDR Failure - TCP3D_DRV_FAIL_EDMA_PARAM_INIT Failure - TCP3D_DRV_FAIL_EDMA_ENABLE_CHANNEL

Tcp3d_Result Tcp3d_reset | ( | IN Tcp3d_Instance * | tcp3dInst,
|  | IN uint32_t | codeBlocks |
| ) |  |  |

Description
TCP3D Driver function called to reset the driver at any time after init and only if both PING & PONG decoders have nothing in the input list for decoding.

This API checks if it is called in a correct state and returns appropriate error message.

This function does the following: 1) Set the instance with the passed values - for example number of blocks for decoding in the current subframe which is needed for boundary checks and to setup the EDMA channels and a new status array pointer where the status register values for each code block are to be DMAed. 2) Initialize all the run-time instance variables to default. 3) Initialize the pseudo PaRAM memory with all the defaults based on mode. 4) Reset the EDMA channels with default values. 5) Change the state to TCP3D_DRV_STATE_INIT.

Parameters:

  `[in]` | *tcp3dInst | This is the driver instance.
  `[in]` | codeBlocks | Number of code blocks to be decoded for the current sub-frame. This value should be equal to the maxCodeBlocks.

For saving cycles, you can set to lower value that should be multiple of 2.

Precondition:
  Allocation of the statusBuf arrary must be big enough to fit all the register trasfers for the given codeBlocks. If the size is small, there will be memory step-over.

Postcondition:

Success - TCP3D_DRV_NO_ERR Failure - TCP3D_DRV_INVALID_STATE Failure - TCP3D_DRV_INVALID_PARAMETER

Tcp3d_Result Tcp3d_start | ( | IN Tcp3d_Instance * | inst,
|  | IN uint8_t | startMode |
| ) |  |  |

Description
This API could be used for starting the driver to start doing EDMA transfers to TCP3 decoder for decoding from the pseudo PaRAM list.

This function updates the load and free counts for both ping and pong lists.

This function is executed at the application task thread for starting either the PING or PONG path execution.

Parameters:

  `[in]` | *inst | This is the driver instance.
  `[in]` | startMode | Flag tells the mode of operation.
  1. If set to TCP3D_DRV_START_AUTO, function checks both the paths (PING & PONG) and start the needed paths.
  2. If set with either TCP3D_DRV_START_PING or TCP3D_DRV_START_PONG, and the corresponding flag (pingStop or pongStop) is set then that path alone is started.

Precondition:
  Application must have atleast one code block enqueued to the pseudo PaRAM list before calling this API so that driver will have something to start the EDMA trasfers and decoding before going to PAUSE state.

This function should be called only after the Tcp3d_init() function is called.

Postcondition:
  Driver state variable is updated, if any paths are started.

Success - TCP3D_DRV_NO_ERR Failure - TCP3D_DRV_FAIL_EDMA_ENABLE_CHANNEL

Tcp3d_Result Tcp3d_status | ( | IN Tcp3d_Instance * | inst,
|  | INOUT Tcp3d_Sts * | drvStatus |
| ) |  |  |

Description
This API could be used for querying the TCP3D driver to get updates or take appropriate actions. The Tcp3d_StsCmd enum structure gives the supported commads.

Note:
  This API is not fully scoped and the possible query commands could be extended in future.

Parameters:

  `[in]` | *inst | This is the driver instance for which status query is made.
  `[in,out]` | *drvStatus | Structure used for keeping the status request command and for keeping the status query output.

Precondition:
  Set appropriate command value before calling the function.

Postcondition:

Success - TCP3D_DRV_NO_ERR (valid command) Failure - TCP3D_DRV_FAIL (invalid command)

Copyright 2012, Texas Instruments Incorporated