source: svn/newcon3bcm2_21bu/BSEAV/api/include/bsettop_recpump.h

/***************************************************************************
 *     Copyright (c) 2004-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: bsettop_recpump.h $
 * $brcm_Revision: 8 $
 * $brcm_Date: 11/9/07 9:25a $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: /BSEAV/api/include/bsettop_recpump.h $
 * 
 * 8   11/9/07 9:25a vsilyaev
 * PR 34612: Added packet_size configuration
 * 
 * 7   12/4/06 5:21p jrubio
 * PR25213: PR25927 Add new recpump_immediate_stop that completely stops
 * 
 * 
 * 
 * 
 * PR25213: PR25927 Add new recpump_immediate_stop that completely stops
 * * all recpump from calling client callbacks
 * 
 * 6   12/1/06 4:22p jrubio
 * PR25213: PR25927 Add new recpump_immediate_stop that completely stops
 * all recpump from calling client callbacks
 * 
 * 5   7/12/06 3:18p ahulse
 * PR16324: get playback / record time via call to bplayback_get_status /
 * brecord_get_status
 * 
 * 4   6/6/06 7:19p ahulse
 * PR20917: Add MCARD 3DES decryption, using XPT TS_DMA/PB Engines, to
 * BCM7038 SW
 * 
 * 3   6/9/05 3:24p erickson
 * PR15513: all pass record is now audio pid 0 or 0x1fff. large warnings
 * now printed.
 * 
 * 2   5/4/05 4:59p erickson
 * PR14576: added num_descriptors and extended comments
 * 
 * 1   2/7/05 7:06p dlwin
 * Merge down for release 2005_REFSW_MERGETOMAIN:
 * 
 * Irvine_BSEAVSW_Devel/6   11/23/04 8:12p vsilyaev
 * PR 13351: Refactoring playback API.
 * 
 * Irvine_BSEAVSW_Devel/5   6/29/04 11:29a erickson
 * PR11135: updated deprecation notices for settop api
 * 
 * Irvine_BSEAVSW_Devel/4   6/24/04 10:27a erickson
 * PR11135: converted to generic bsettop_callback for playpump and recpump
 *
 * Irvine_BSEAVSW_Devel/3   6/17/04 9:37a erickson
 * PR11135: recpump callback enabled
 *
 * Irvine_BSEAVSW_Devel/2   6/10/04 8:08a erickson
 * PR11135: brecpump implemented and brecord converted to use recpump
 *
 * Irvine_BSEAVSW_Devel/1   6/8/04 7:40a erickson
 * PR11135: added iniital playpump impl for 97038
 *
 *******************************************************************************/
#ifndef BSETTOP_RECPUMP_H__
#define BSETTOP_RECPUMP_H__

#ifdef __cplusplus
extern "C" {
#endif

/*=****************************************
brecpump is a low-level PVR api for recording.
It does not perform any file i/o and does not maintain any threads,
but uses asynchronous callbacks to send data out to the application.

The brecord api is built on top of brecpump. It performs file i/o
and threading.
*******************************************/

/**
Summary:
Handle for brecpump api.
**/
typedef struct brecpump *brecpump_t;

/**
Summary:
Parameters that must be passed into brecpump_open.
**/
typedef struct brecpump_open_params {
        struct {
                size_t buffer_size; /* size in bytes of the record buffer */
                unsigned alignment; /* alignment for the block. units of 2^alignment. Therefore a value of 2 will be 
                        4 byte aligned, 3 will be 8 byte aligned, etc. only used for data, not scode. */
                unsigned num_descriptors; /* buffer_size/num_descriptors determines the size of the blocks that
                        you will receive from recpump. */
                void * buf;     /* pass in ptr to buffer to be used instead of using own */
        } data, scode;
} brecpump_open_params;

/**
Summary:
Returns default configuration parameters for the record pump 
**/
void brecpump_get_open_params(
                bobject_t id, 
                brecpump_open_params *open_params /* [out] */
                );

/**
Summary:
Open a recpump source.
**/
brecpump_t brecpump_open(
                bobject_t id, 
                const brecpump_open_params *open_params /* optional parameters for the record pump */
                );

/**
Summary:
Close the recpump.
Description:
It should already be stopped.
**/
void brecpump_close(brecpump_t recpump);

/**
Summary:
Parameters that must be passed into brecpump_start.
**/
typedef struct brecpump_params {
        bencryption_params encryption; /* PVR encryption parameters to be applied to
                                                                the recorded data. */
        bool timestamp_enabled; /* If true, then a 4 byte timestamp is prepended to every
                                                                transport packet. bplayback_params.timestamp_enabled
                                                                must match. */
        void *callback_context; /* Context pointer which is returned in the callback functions. */
        bsettop_callback data_write_callback; /* Callback function that will be called for
                                                                MPEG data. You should call brecpump_data_get_buffer
                                                                but the actual file write and brecpump_data_write_complete
                                                                call should not be made from this callback. */
        bsettop_callback index_write_callback; /* Optional callback function that will be called
                                                                for SCT (start code table) data. You can set this to be
                                                                NULL if you don't want index data produced. */
        bsettop_callback overflow;      /* Called whenever a buffer overflow is detected.
                                                                Recorded data will be corrupt. This is used for system
                                                                debug only. In a production system this should never
                                                                happen, and if it does, you should just keep on recording. */

        size_t packet_size;         /* the size of the blocks that you will receive from recpump would be multiplier of packet_size, please also see 
                                    brecpump_open_params  for buffer_size and num_descriptors */
} brecpump_params;

/**
Summary:
Initialize the recpump parameters to defaults.

Description:
You will need to set at the very least the data_write_callback.
**/
void brecpump_params_init(
        brecpump_params *params, /* [out] */
        brecpump_t recpump
        );

/**
Summary:
Start recording a stream.

Description:
To perform an "all pass" record of an entire transport stream, create a stream with video[0].pid and 
audio[0].pid of 0. This is only supported on magnum-based platforms and has possibly undesired 
effects on all records, so only use this as a test mode.
**/
bresult brecpump_start(
        brecpump_t recpump,
        bstream_t stream,
        const brecpump_params *params
        );

/**
Summary:
Stop the recording and wait for the recording process to finalize.
The recpump handle can be safely closed after brecpump_stop returns.
**/
bresult brecpump_stop(
        brecpump_t recpump
        );


/**
Summary:
 Please call before you call brecpump_stop if you have
stopped abnormally. This will ensure that when you stop
you will not receive any more call backs and data
**/
void brecpump_immediate_stop(
        brecpump_t recpump
        );

/**
Summary:
Get next portion of MPEG data from the record buffer that needs to be consumed from transport.

Description:
This returns the same type of information as the write_callback.
Note that after receiving the callback, if you call brecpump_data_get_buffer again,
there may be more data that becomes available.
**/
bresult brecpump_data_get_buffer(
        brecpump_t recpump,
        const void **buffer, /* [out] memory which contains data to be written */
        size_t *buffer_size /* [out] total amount of data to be written */
        );

/**
Summary:
Get next portion of SCT index data from the record buffer that needs to be consumed.
Description:
This returns the same type of information as the write_callback.
Note that after receiving the callback, if you call brecpump_index_get_buffer again,
there may be more data that becomes available.
**/
bresult brecpump_index_get_buffer(
        brecpump_t recpump,
        const void **buffer, /* [out] memory which contains data to be written */
        size_t *buffer_size /* [out] total amount of data to be written */
        );

/**
Summary:
Report back how much MPEG data was consumed (usually by writing to disk).

Description:
If the write fails, the user has the option of calling brecpump_write_complete
or stopping pvr altogether. There is no way and no point in information brecpump
that a write has failed.
**/
bresult brecpump_data_write_complete(
        brecpump_t recpump,
        size_t amount_written
        );

/**
Summary:
Report back how much index data was consumed (usually by writing to disk).

Description:
If the write fails, the user has the option of calling brecpump_write_complete
or stopping pvr altogether. There is no way and no point in information brecpump
that a write has failed.
**/
bresult brecpump_index_write_complete(
        brecpump_t recpump,
        size_t amount_written
        );

/**
Summary:
Status returned by brecord_get_status.
**/
typedef struct brecpump_status {
        unsigned long mpeg_bytes_recorded;      /* Number of bytes of mpeg stream data recorded */
        unsigned long mpeg_fifo_depth;  /* Current depth in bytes of the mpeg record buffer */
        unsigned long mpeg_fifo_size;   /* Current size in bytes of the mpeg record buffer */
        bool has_index; /* If true, then you are recording an index and the following fields
                                                are valid. */
        unsigned long index_bytes_recorded;     /* Number of bytes of index data recorded */
        unsigned long index_fifo_depth; /* Current depth in bytes of the index record buffer */
        unsigned long index_fifo_size;  /* Current size in bytes of the index record buffer */
        unsigned long last_timestamp;   /* timestamp of last frame recorded. Not used by recpump, */
                                        /* but included for use in brecord_status -time in mSec */
} brecpump_status;

/**
Summary:
Get current status of the recording.
**/
void brecpump_get_status(
        brecpump_t recpump,
        brecpump_status *status /* [out] current status information */
        );

#ifdef __cplusplus
}
#endif

#endif /* BSETTOP_RECPUMP_H__ */