source: svn/newcon3bcm2_21bu/magnum/syslib/vbilib/bvbilib_dccreorder.c

/***************************************************************************
 *     Copyright (c) 2007, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: bvbilib_dccreorder.c $
 * $brcm_Revision: Hydra_Software_Devel/4 $
 * $brcm_Date: 5/29/07 2:32p $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: /magnum/syslib/vbilib/bvbilib_dccreorder.c $
 * 
 * Hydra_Software_Devel/4   5/29/07 2:32p darnstein
 * PR31097: Bug fix: I forgot to advance a queue pointer.
 * 
 * Hydra_Software_Devel/3   5/29/07 1:11p darnstein
 * PR31097: Implement the _Count function. Fix some ordinary typing
 * errors. Add another paramter check to the _Open function.
 * 
 * Hydra_Software_Devel/2   5/25/07 6:09p darnstein
 * PR31097: ready for testing now.
 * 
 * Hydra_Software_Devel/1   5/25/07 1:51p darnstein
 * PR31097: just a placeholder for now.
 * 
 ***************************************************************************/

#include "bvbilib_dccreorder.h"
#include "bkni.h"

BDBG_MODULE(BVBIlib);

/***************************************************************************
* Private data structures
***************************************************************************/

/* This is an entry in one of the queues of closed caption data */
typedef struct
{
    uint8_t datumL;
    uint8_t datumH;
}
P_CCdata;

/* This is a queue of closed caption data */
typedef struct
{
        unsigned int size;
        unsigned int readN;
        unsigned int writeN;
        P_CCdata* array;
}
P_Queue;

/* This is the complete state of the module */
typedef struct
{
        uint32_t ulBlackMagic;
        P_Queue topQ;
        P_Queue botQ;
        unsigned int threshold;
        BAVC_Polarity last_rtn_polarity;
}
BVBIlib_P_DCCReorder_Handle;

/***************************************************************************
* Forward declarations of static (private) functions
***************************************************************************/

/* This is also defined in bvbilib_priv.h. I decided to keep these files
 * independent of each other.
 */
#define BVBILIB_P_GENERIC_GET_CONTEXT(handle, context, structname) \
do { \
        if(!(handle) || \
           (((structname*)(handle))->ulBlackMagic != \
           sizeof(structname))) \
        { \
                BDBG_ERR(("Corrupted context handle\n")); \
                (context) = NULL; \
        } \
        else \
        { \
                (context) = (structname*)(handle); \
        } \
} while (0)

#define P_GET_CONTEXT(handle, context) \
        BVBILIB_P_GENERIC_GET_CONTEXT(handle, context, BVBIlib_P_DCCReorder_Handle)

#ifndef MAX
        #define MAX(a,b) (((a) > (b)) ? (a) : (b))
#endif

static BERR_Code P_Put (P_Queue* queue, uint8_t datumL, uint8_t datumH);
static BERR_Code P_Get (P_Queue* queue, uint8_t* pDatumL, uint8_t* pDatumH);
static unsigned int P_Count (P_Queue* queue);

/***************************************************************************
* Implementation of "BVBIlib_" API functions
***************************************************************************/

/***************************************************************************
 *
 */
BERR_Code BVBIlib_DCCReorder_Open (
    BVBIlib_DCCReorder_Handle* pHandle, 
    unsigned int histSize,             
    unsigned int threshold             
)
{
        BVBIlib_P_DCCReorder_Handle *prHandle;
        unsigned int vtest;
        unsigned int count = 0;

        BDBG_ENTER(BVBIlib_DCCReorder_Open);

        if (!pHandle) 
        {
                BDBG_ERR(("Invalid parameter\n"));
                BDBG_LEAVE(BVBIlib_DCCReorder_Open);
                return BERR_TRACE(BERR_INVALID_PARAMETER);
        }

        /* Verify that the size parameter is nonzero, and a power of two. */
        if (histSize == 0)
        {
                BDBG_ERR(("Invalid parameter\n"));
                BDBG_LEAVE(BVBIlib_DCCReorder_Open);
                return BERR_TRACE(BERR_INVALID_PARAMETER);
        }
        vtest = histSize;
        while (vtest > 1)
        {
                ++count;
                vtest >>= 1;
        }
        vtest = 1 << count;
        if (vtest != histSize)
        {
                BDBG_ERR(("Invalid parameter\n"));
                BDBG_LEAVE(BVBIlib_DCCReorder_Open);
                return BERR_TRACE(BERR_INVALID_PARAMETER);
        }

        /* Don't allow a large threshold */
        if (threshold > histSize)
        {
                BDBG_ERR(("Invalid parameter\n"));
                BDBG_LEAVE(BVBIlib_DCCReorder_Open);
                return BERR_TRACE(BERR_INVALID_PARAMETER);
        }

        /* Alloc the main context. */
        prHandle = 
                (BVBIlib_P_DCCReorder_Handle*)(BKNI_Malloc(
                        sizeof(BVBIlib_P_DCCReorder_Handle)));

        if(!prHandle)
        {
                return BERR_TRACE(BERR_OUT_OF_SYSTEM_MEMORY);
        }

        /* Clear out the context and set defaults. */
        BKNI_Memset((void*)prHandle, 0x0, sizeof(BVBIlib_P_DCCReorder_Handle));

        /* Allocate queues */
        prHandle->topQ.array = (P_CCdata*)BKNI_Malloc (
                histSize * sizeof(P_CCdata));
        if (!prHandle->topQ.array)
        {
                BKNI_Free ((void*)prHandle);
                return BERR_TRACE(BERR_OUT_OF_SYSTEM_MEMORY);
        }
        prHandle->botQ.array = (P_CCdata*)BKNI_Malloc (
                histSize * sizeof(P_CCdata));
        if (!prHandle->botQ.array)
        {
                BKNI_Free ((void*)(prHandle->topQ.array));
                BKNI_Free ((void*)prHandle);
                return BERR_TRACE(BERR_OUT_OF_SYSTEM_MEMORY);
        }

        /* Store user's settings */
        prHandle->topQ.size = histSize;
        prHandle->botQ.size = histSize;
        prHandle->threshold = threshold;

        /* Initialize empty queues of closed caption data */
        prHandle->topQ.readN  = 0;
        prHandle->topQ.writeN = 0;
        prHandle->botQ.readN  = 0;
        prHandle->botQ.writeN = 0;

        /* The module has returned no CC data yet */
        prHandle->last_rtn_polarity = BAVC_Polarity_eFrame;    /* undefined */

        /* Initialize magic number to the size of the struct */
        prHandle->ulBlackMagic = sizeof(BVBIlib_P_DCCReorder_Handle);

        /* All done. now return the new fresh context to user. */
        *pHandle = (BVBIlib_DCCReorder_Handle)prHandle;

        BDBG_LEAVE(BVBIlib_DCCReorder_Open);
        return BERR_SUCCESS;
}


/***************************************************************************
 *
 */
void BVBIlib_DCCReorder_Close (BVBIlib_DCCReorder_Handle handle)
{
        BVBIlib_P_DCCReorder_Handle *prHandle;

        BDBG_ENTER(BVBIlib_DCCReorder_Close);

        /* check parameters */
        P_GET_CONTEXT(handle, prHandle);
        BDBG_ASSERT (prHandle != NULL);

        /* The handle is about to become invalid */
        prHandle->ulBlackMagic = 0;

        /* Release context in system memory */
        BKNI_Free ((void*)(prHandle->topQ.array));
        BKNI_Free ((void*)(prHandle->botQ.array));
        BKNI_Free((void*)prHandle);

        BDBG_LEAVE(BVBIlib_DCCReorder_Close);
}


/***************************************************************************
 *
 */
BERR_Code BVBIlib_DCCReorder_Put (
    BVBIlib_DCCReorder_Handle handle,
    uint8_t datumL,                 
    uint8_t datumH,
    BAVC_Polarity polarity
)
{
        BVBIlib_P_DCCReorder_Handle *prHandle;
        P_Queue* queue;
        BERR_Code eStatus;

        BDBG_ENTER (BVBIlib_DCCReorder_Put);

        /* check parameters */
        P_GET_CONTEXT(handle, prHandle);
        if (prHandle == NULL)
        {
                return BERR_TRACE (BERR_INVALID_PARAMETER);
        }

        /* Choose a queue to operate on */
        switch (polarity)
        {
        case BAVC_Polarity_eTopField:
                queue = &(prHandle->topQ);
                break;
        case BAVC_Polarity_eBotField:
                queue = &(prHandle->botQ);
                break;
        default:
                queue = 0x0;
                return BERR_TRACE (BERR_INVALID_PARAMETER);
                break;
        }

        /* Store the data if there is room */
        eStatus = P_Put (queue, datumL, datumH);

        BDBG_LEAVE (BVBIlib_DCCReorder_Put);
        return eStatus;
}


/***************************************************************************
 *
 */
BERR_Code BVBIlib_DCCReorder_Get (
    BVBIlib_DCCReorder_Handle handle, 
    uint8_t* pDatumL,                   
    uint8_t* pDatumH,                   
    BAVC_Polarity* pPolarity            
)
{
        BVBIlib_P_DCCReorder_Handle *prHandle;
        P_Queue* queue;
        uint8_t datumL = 0x0;
        uint8_t datumH = 0x0;
        BAVC_Polarity polarity = BAVC_Polarity_eFrame;
        BERR_Code eStatus = BERR_OUT_OF_SYSTEM_MEMORY;

        BDBG_ENTER (BVBIlib_DCCReorder_Get);

        /* check parameters */
        P_GET_CONTEXT(handle, prHandle);
        if (prHandle == NULL)
        {
                return BERR_TRACE (BERR_INVALID_PARAMETER);
        }

        /* 
         * This is the core algorithm of the entire BVBIlib_dccreorder module. See
         * description of this function in bvbilib_dccreorder.h for details.
         */

        /* Special case: no data returned yet. Any polarity data will do. */
        if (prHandle->last_rtn_polarity == BAVC_Polarity_eFrame)
        {
                if ((eStatus = P_Get (&prHandle->topQ, &datumL, &datumH)) == 
                        BERR_SUCCESS)
                {
                        prHandle->last_rtn_polarity = BAVC_Polarity_eTopField;
                        polarity                    = BAVC_Polarity_eTopField;
                }
                else
                {
                        if ((eStatus = P_Get (&prHandle->botQ, &datumL, &datumH)) ==
                                BERR_SUCCESS)
                        {
                                prHandle->last_rtn_polarity = BAVC_Polarity_eBotField;
                                polarity                    = BAVC_Polarity_eBotField;
                        }
                }
        }

        /* Next, try to maintain alternating polarity. */
        if (eStatus != BERR_SUCCESS)
        {
                if (prHandle->last_rtn_polarity == BAVC_Polarity_eTopField)
                {
                        queue = &prHandle->botQ;
                        polarity = BAVC_Polarity_eBotField;
                }
                else
                {
                        queue = &prHandle->topQ;
                        polarity = BAVC_Polarity_eTopField;
                }
                eStatus = P_Get (queue, &datumL, &datumH);
                if (eStatus == BERR_SUCCESS)
                {
                        prHandle->last_rtn_polarity = polarity;
                }
        }

        /* Next, check for a too-full top queue. */
        if (eStatus != BERR_SUCCESS)
        {
                if (P_Count (&prHandle->topQ) + prHandle->threshold > 
                        prHandle->topQ.size)
                {
                        eStatus = P_Get (&prHandle->topQ, &datumL, &datumH);
                        if (eStatus == BERR_SUCCESS)
                        {
                                prHandle->last_rtn_polarity = BAVC_Polarity_eTopField;
                                polarity                    = BAVC_Polarity_eTopField;
                        }
                }
        }

        /* Finally, check for a too-full bottom queue. */
        if (eStatus != BERR_SUCCESS)
        {
                if (P_Count (&prHandle->botQ) + prHandle->threshold > 
                        prHandle->botQ.size)
                {
                        eStatus = P_Get (&prHandle->botQ, &datumL, &datumH);
                        if (eStatus == BERR_SUCCESS)
                        {
                                prHandle->last_rtn_polarity = BAVC_Polarity_eBotField;
                                polarity                    = BAVC_Polarity_eBotField;
                        }
                }
        }

        /* Return what we got */
        if (eStatus == BERR_SUCCESS)
        {
                *pDatumL   = datumL;
                *pDatumH   = datumH;
                *pPolarity = polarity;
        }

        BDBG_LEAVE (BVBIlib_DCCReorder_Get);
        return eStatus;
}


/***************************************************************************
 *
 */
BERR_Code BVBIlib_DCCReorder_Count (
    BVBIlib_DCCReorder_Handle* handle, 
    unsigned int* count                
)
{
        BVBIlib_P_DCCReorder_Handle *prHandle;

        BDBG_ENTER (BVBIlib_DCCReorder_Count);

        /* check parameters */
        P_GET_CONTEXT(handle, prHandle);
        if (prHandle == NULL)
        {
                return BERR_TRACE (BERR_INVALID_PARAMETER);
        }

        *count = MAX (P_Count (&prHandle->topQ), P_Count (&prHandle->botQ));

        BDBG_LEAVE (BVBIlib_DCCReorder_Count);
        return BERR_SUCCESS;
}

/***************************************************************************
* Implementation of private (static) functions
***************************************************************************/

/*
 * Rules for the queues:
 * --------------------
 *
 *  The queue size must be a power of two.
 *
 *  A queue is empty when readN == writeN
 *
 *  A queue is full when readN != writeN AND (readN == writeN (modulo size))
 *
 *  Increment one counter on every read and write. No other counter
 *  modification is allowed.
 */

/***************************************************************************
 *
 */
static BERR_Code P_Put (P_Queue* queue, uint8_t datumL, uint8_t datumH)
{
        unsigned int index;
        P_CCdata* ccdata;

        /* Check for queue full condition */
        if (queue->readN != queue->writeN)
        {
                if (((queue->writeN - queue->readN) % queue->size) == 0)
                {
                        return BERR_OUT_OF_SYSTEM_MEMORY;
                }
        }

        /* Queue not full, work it. */
        index = (queue->writeN) % (queue->size);
        ccdata = &queue->array[index];
        ccdata->datumL = datumL;
        ccdata->datumH = datumH;

        /* Advance the queue */
        ++(queue->writeN);

        /* Success */
        return BERR_SUCCESS;
}

/***************************************************************************
 *
 */
static BERR_Code P_Get (P_Queue* queue, uint8_t* pDatumL, uint8_t* pDatumH)
{
        unsigned int index;
        P_CCdata* ccdata;

        /* Check for queue empty condition */
        if (queue->readN == queue->writeN)
        {
                return BERR_OUT_OF_SYSTEM_MEMORY;
        }

        /* Queue not empty, work it. */
        index = (queue->readN) % (queue->size);
        ccdata = &queue->array[index];
        *pDatumL = ccdata->datumL;
        *pDatumH = ccdata->datumH;

        /* Advance the queue */
        ++(queue->readN);

        /* Success */
        return BERR_SUCCESS;
}

/***************************************************************************
 *
 */
static unsigned int P_Count (P_Queue* queue)
{
        unsigned int count = 0;

        if (queue->writeN < queue->readN)
        {
                count = queue->size;
        }

        count += queue->writeN;
        count -= queue->readN;

        return count;
}