source: svn/newcon3bcm2_21bu/magnum/syslib/pvrlib/bpvrlib_feed.h

/***************************************************************************

 *     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: bpvrlib_feed.h $

 * $brcm_Revision: Hydra_Software_Devel/4 $

 * $brcm_Date: 12/13/10 6:59p $

 *

 * Module Description:

 *

 * PVR library, playback feeder module

 * Revision History:

 *

 * $brcm_Log: /magnum/syslib/pvrlib/bpvrlib_feed.h $

 * 

 * Hydra_Software_Devel/4   12/13/10 6:59p vsilyaev

 * SW7425-39: Added support for MUX input

 * 

 * Hydra_Software_Devel/3   4/16/08 6:57p mward

 * PR39994: Use BXPT_Playback_GetIntId() instead of channelNum.

 * 

 * Hydra_Software_Devel/2   8/2/07 5:36p vsilyaev

 * PR 33751: Improved documentation of bpvrlib_feed module

 * 

 * Hydra_Software_Devel/1   8/2/07 4:18p vsilyaev

 * PR 33751:

 * 

 *      

 ***************************************************************************/

#ifndef BPVRLIB_FEED_H__

#define BPVRLIB_FEED_H__

#include "bxpt_playback.h"

#include "bavc_xpt.h"



#ifdef __cplusplus

extern "C" {

#endif



/************************************************************************

The BPVRlib_Feed is replacement for BPVRlib_Play. And goal of this

replacement is to improve performance, it's done in several ways: 

        o reduce code complexity by removing unused functionality

        o support for batch operations (send multiple blocks at the time), thus spreading cost of function call across multiple data chunks 

        o effective use of cached memory to reduce latency of CPU to hardware communications.





Purpose of BPVRlib_Feed library is to send data from the memory using the playback block into the transport hardware.



BPVRlib_Feed library provides scalable API that could be used in wide range of application 

        o data from circular FIFO 

        o data from network buffers 

        o synchronous transfer from the user's memory 

        o data from the stream parsers library 

        o good use of resources at hand (MIPS cache, scatter/gather nature of playback hardware) 

        o Asynchronous/non-blocking execution



*************************************************************************/





/* type of BPVRlib_Feed instance */

typedef struct BPVRlib_Feed  *BPVRlib_Feed_Handle;



/*

Summary:

The settings needed for creating instance of BPVRlib_Feed 

*/

typedef struct BPVRlib_Feed_Settings {

        BXPT_Handle xptHandle;              /* XPT handle */

        BXPT_Playback_Handle xptPlayHandle; /* XPT playback handle */

        BMEM_Heap_Handle heap;              /* Mem heap handle */

        BINT_Handle intHandle;              /* Int handle */

        bool useExtndedDesc;                    /* enable use of extended (8 word) descriprots if HW supports it,  this allows use of the BPVRlib_Feed_AddExtendedOffsetEntries API */

        size_t numDesc;                   /* number of descriptors to use  */

        void *applicationCnxt;             /* application specific context */

        int applicationNumber;           /* application specific number passed into the callback */

        void (*descAvaliable_isr)(void *applicationCnxt, int applicationNumber); /* function that is called when new descriptor becomes avaliable, e.g.  when BPVRlib_Feed_AddEntries/BPVRlib_Feed_OffsetAddEntries could be called and it will consume some data */

} BPVRlib_Feed_Settings;



/*

Summary:

        status of BPVRlib_Feed instance

See also:

    BPVRlib_Feed_GetStatus

*/

typedef struct BPVRlib_Feed_Status {

        unsigned freeDesc;     /* number of avaliable descriptors, call to BPVRlib_Feed_AddEntries/BPVRlib_Feed_OffsetAddEntries will consume at least that many entries */

} BPVRlib_Feed_Status;



/*

Summary:

This structure describes single transfer unit for the feeder 

Description:

    This structure is used to describe transfer unit in terms of CPU virtual address

See also:

   o BPVRlib_Feed_OffsetEntry

   o BPVRlib_Feed_AddEntries

*/

typedef struct BPVRlib_Feed_Entry {

        void *addr; /* memory address such BMEM_Heap_ConvertAddressToOffset could be uses convert address to the device offset, for example an address returned by BMEM_Alloc */

        size_t len; /* length of memory block */

} BPVRlib_Feed_Entry;



/*

Summary:

        This structure describes single transfer unit for the feeder 

Description:

    This structure is used to describe transfer unit it terms of physicall device addresses (also known as device offset)

See also:

   o BPVRlib_Feed_Entry

   o BPVRlib_Feed_AddOffsetEntries

*/

typedef struct BPVRlib_Feed_OffsetEntry {

        uint32_t    offset; /* device offset of the memory region */

        size_t len; /* length of memory block */

} BPVRlib_Feed_OffsetEntry;



/*

Summary:

        This structure describes extended single transfer unit for the feeder 

Description:

    This structure is used to describe transfer unit it terms of physicall device addresses (also known as device offset)

See also:

   o BPVRlib_Feed_AddExtendedOffsetEntries

*/

typedef struct BPVRlib_Feed_ExtendedOffsetEntry {

    BPVRlib_Feed_OffsetEntry baseEntry;

    BAVC_TsMux_DescConfig flags;  

} BPVRlib_Feed_ExtendedOffsetEntry;



/*

Summary:

        fills-out configuration structure with default values */

void BPVRlib_Feed_GetDefaultSettings(

                BPVRlib_Feed_Settings *settings /* pointer to the configuration structure */

                );

/*

Summary:

        opens new instancne of BPVRlib_Feed_ feeder 

*/

BERR_Code BPVRlib_Feed_Open(

                BPVRlib_Feed_Handle *feed,  /* out pointer to the instance of BPVRlib_Feed */

                const BPVRlib_Feed_Settings *settings /* pointer to the configuration structure */

                );



/*

Summary:

        releases all resources allocated for the feeder

*/

void BPVRlib_Feed_Close(

                BPVRlib_Feed_Handle feed /* instance of BPVRlib_Feed */

                );



/*

Summary:

   Addes new data to the feeder.

Description:

  This function is used to add new data to the feeder.

  Pointer to BPVRlib_Feed_Entry need to be valid only during duration of the function call . 

*/

BERR_Code BPVRlib_Feed_AddEntries(

                BPVRlib_Feed_Handle feed, /* instance of BPVRlib_Feed */

                BMEM_Heap_Handle heap,  /* instance of BMEM_Heap_Handle that used to convert entries[i].addr to the device offset */

                const BPVRlib_Feed_Entry *entries, /* pointer to array of BPVRlib_Feed_Entry */ 

                size_t count,           /* number of elements in the array */ 

                size_t *nconsumed   /* out pointer to return number of consumed elements */

                );



/*

Summary:

   Addes new data to the feeder.

Description:

  This function is used to add new data to the feeder.

  Pointer to BPVRlib_Feed_Entry need to be valid only during duration of the function call. 

  This function shall be used if address can't be converted by using BMEM_Heap_Handle or user want's to

  remove overhead of calling BMEM_Heap_ConvertAddressToOffset for each address

*/

BERR_Code BPVRlib_Feed_AddOffsetEntries(

                BPVRlib_Feed_Handle feed, /* instance of BPVRlib_Feed */

                const BPVRlib_Feed_OffsetEntry *entries, /* pointer to array of BPVRlib_Feed_OffsetEntry */ 

                size_t count, /* number of elements in the array */ 

                size_t *nconsumed/* out pointer to return number of consumed elements */

                );



/*

Summary:

   Addes new data to the feeder.

Description:

  This function is used to add new data to the feeder.

  Pointer to BPVRlib_Feed_ExtendedOffsetEntry need to be valid only during duration of the function call. 

  This function shall be used if address can't be converted by using BMEM_Heap_Handle or user want's to

  remove overhead of calling BMEM_Heap_ConvertAddressToOffset for each address.

See also:

   o BPVRlib_Feed_AddOffsetEntries

   o BPVRlib_Feed_Settings

*/

BERR_Code BPVRlib_Feed_AddExtendedOffsetEntries(

                BPVRlib_Feed_Handle feed, /* instance of BPVRlib_Feed */

                const BPVRlib_Feed_ExtendedOffsetEntry *entries, /* pointer to array of BPVRlib_Feed_ExtendedOffsetEntries */ 

                size_t count, /* number of elements in the array */ 

                size_t *nconsumed/* out pointer to return number of consumed elements */

                );



/*

Summary:

   This function is used to monitor progress of transaction 

Description:

   This function returns number of completed entries since last call to BPVRlib_Feed_GetCompleted. Often 

   application would use this number recycle memory.

*/

BERR_Code BPVRlib_Feed_GetCompleted(

                BPVRlib_Feed_Handle feed, /* instance of BPVRlib_Feed */

                size_t *ncompleted      /* out pointer to return number of completed elements */

                );

/*

Summary:

        This function activates data feeding

*/

BERR_Code BPVRlib_Feed_Start(

                BPVRlib_Feed_Handle feed /* instance of BPVRlib_Feed */

                );



/*

Summary:

        This function deactivates data feeding.

Description:

        The BPVRlib_Feed_Stop function stops data feeding, all unsent entries are discarded.

*/

void BPVRlib_Feed_Stop(

                BPVRlib_Feed_Handle feed /* instance of BPVRlib_Feed */

                );

/*

Summary:

   This function returms statos of BPVRlib_Feed module

*/

void BPVRlib_Feed_GetStatus(

                BPVRlib_Feed_Handle feed, /* instance of BPVRlib_Feed */

                BPVRlib_Feed_Status *status /* out pointer to the  BPVRlib_Feed_Status structure */

                );

#ifdef __cplusplus

}

#endif



#endif /* BPVRLIB_FEED_H__ */