/*
 * Copyright 2010 Trident Microsystems (Far East) Ltd. All rights reserved.
 * All prior copyright rights in this work and the accompanying software
 * products transferred to Trident Microsystems (Far East) Ltd. by written
 * agreement.
 */
/*****************************************************************************/
/* Copyright (c) 2010 NXP B.V.  All rights are reserved.                     */
/*                                                                           */
/* Redistribution and use in source and binary forms, with or without        */
/* modification, are permitted provided that the following conditions        */
/* are met:                                                                  */
/*                                                                           */
/* Redistributions of source code must retain the above copyright            */
/* notice, this list of conditions and the following disclaimer.             */
/*                                                                           */
/* Redistributions in binary form must reproduce the above copyright         */
/* notice, this list of conditions and the following disclaimer in the       */
/* documentation and/or other materials provided with the distribution.      */
/*                                                                           */
/* Neither the name of NXP nor the names of its                              */
/* contributors may be used to endorse or promote products derived from      */
/* this software without specific prior written permission.                  */
/*                                                                           */
/* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       */
/* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT         */
/* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR     */
/* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT      */
/* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,     */
/* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT          */
/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,     */
/* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     */
/* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       */
/* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE         */
/* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH          */
/* DAMAGE.                                                                   */
/*                                                                           */
/*****************************************************************************/
/**
    @file   phStbKBufMgr.h
    @brief  Kernel Buffer Manager component

    Top level API for the Kernel Buffer Manager.

    Set your editor for 4 space indentation.
*//*

Rev Date        Author      Comments
--------------------------------------------------------------------------------
10  20070820    barnish     added sbm source buffers
11  20070831    awest       added DMXSW_SPDIF buffer
12  20070830    barnish     add new 64K Audio In buffer type
13  20070925    batelaan    add phStbNetDev packet pool
14  20071018    barnish     remove dependency on wmv switch
14.1.1 20071122 barnish     remove AIO buffers and add ALIN
16  20071123    barnish     rename audio buffers
15  20071106    burningh    improve documentation
15.1.1 20071127 iwillis     Renamed and reordered some buffers
17  20071128    barnish     merge
18  20080118    Farzad      Optimise for alignment
19  20080122    steel       add spts buffers
20  20080205    neill       add support for HD to SD downscale
21  20080207    batelaan    Update file copyright/license text
22  20080215    myers       move msvd fw lower in the map and introduce
                            new entries for AVS framstores
23  20080509    griffiths   Add extra buffer for auxiliary demuxer
24  20080619    griffiths   Add extra buffer for alternate directfb allocation
25  20080805    laird       Add a debug buffer region.
26  20080912    batelaan    Re-arrange and update documentation
27  20081014    neill       Add video input buffer
28  20081104    batelaan    Add phStbKBufMgr_LookupBuffer and phStbKBufMgr_BufferStats
29  20090120    batelaan    Update file copyright/license text
--------------------------------------------------------------------------------
    For consistency and standardisation retain the Section Separators.
*/

#ifndef PHSTBKBUFMGR_H
#define PHSTBKBUFMGR_H

/**************************************************************
* INCLUDE FILES                                               *
***************************************************************/

#include <tmNxTypes.h>

#ifdef __cplusplus
extern "C"
{
#endif

/**************************************************************
* EXPORTED MACROS                                             *
***************************************************************/

/** No free buffer available, or
    no buffer exists with the specified address. */
#define PH_STBKBUFMGR_ERR_BUFFER_NOT_AVAILABLE 0x100

/** The provided out parameter was bad. */
#define PH_STBKBUFMGR_ERR_BAD_OUT_PARAM        0x200

/** The requested number of buffers was too high. */
#define PH_STBKBUFMGR_ERR_NUM_BUFFERS_TOO_HIGH 0x300

/** The memory required to allocate all the buffers wasn't available. */
#define PH_STBKBUFMGR_ERR_OUT_OF_MEMORY        0x400

/** The buffer type is out of range. */
#define PH_STBKBUFMGR_ERR_BAD_BUFFER_TYPE 0x500

/** The requested buffer index is out of range. */
#define PH_STBKBUFMGR_ERR_BAD_BUFFER_INDEX 0x600

/** The requested buffer is not allocated. */
#define PH_STBKBUFMGR_ERR_NOT_ALLOCATED 0x700

/**************************************************************
* EXPORTED TYPEDEFS                                           *
***************************************************************/

/** Enumeration of available buffer types.
 * The order is important. See comments in the list of enums.
 */
typedef enum phStbKBufMgr_Buffer
{
    phStbKBufMgr_Buffer_VIDEO_ES,       /**< Video elementary stream SBM */
    phStbKBufMgr_Buffer_AUDIO_ES,       /**< Audio input buffers */
    phStbKBufMgr_Buffer_VSPTS,          /**< VMSP SPTS buffer */
    phStbKBufMgr_Buffer_VSECT,          /**< VMSP Section filter buffer */
    phStbKBufMgr_Buffer_VFILT,          /**< VMSP filter buffer */
    phStbKBufMgr_Buffer_FSY,            /**< Frame store Y buffers */
    phStbKBufMgr_Buffer_FSUV,           /**< Frame store UV buffers */
    phStbKBufMgr_Buffer_FSY_Stop,       /**< Frame store Y buffer for decoder stop */
    phStbKBufMgr_Buffer_FSUV_Stop,      /**< Frame store UV buffer for decoder stop */
    phStbKBufMgr_Buffer_FW,             /**< Firmware for MSVD.
     @note
     The buffer types above phStbKBufMgr_Buffer_FW must be allocated
     physically above phStbKBufMgr_Buffer_FW since the TM CPU
     firmware is mapped to TM address 0.
     The buffer types below phStbKBufMgr_Buffer_FW may be allocated anywhere. */

    phStbKBufMgr_Buffer_DOWNSCALE_Y,    /**< Downscale Y buffers */
    phStbKBufMgr_Buffer_DOWNSCALE_UV,   /**< Downscale UV buffers */
    phStbKBufMgr_Buffer_AUDIO_OUT,      /**< Audio post processor output */
    phStbKBufMgr_Buffer_VSYS,           /**< VMSP System buffer */
    phStbKBufMgr_Buffer_AUDIO,          /**< Audio SBM & MS lin buffers */
    phStbKBufMgr_Buffer_NETDEV,         /**< 64k phStbNetDev interprocessor packet pool */
    phStbKBufMgr_Buffer_DMXSW,          /**< Software Demux */
    phStbKBufMgr_Buffer_SBMSource,      /**< SBM Source input buffers */
    phStbKBufMgr_Buffer_DMXSW_VID,      /**< Software Demux VIDEO*/
    phStbKBufMgr_Buffer_DMXSW_AUD,      /**< Software Demux Audio*/
    phStbKBufMgr_Buffer_DMXSW_AUD2,     /**< Software Demux AUDIO2*/
    phStbKBufMgr_Buffer_VIDEO_PES_HDR,  /**< Video PES header SBM */
    phStbKBufMgr_Buffer_VPTS,           /**< Video PTS timestamp SBM */
    phStbKBufMgr_Buffer_UD,             /**< User Data SBM */
    phStbKBufMgr_Buffer_AHeader,        /**< Audio PES header SBM */
    phStbKBufMgr_Buffer_APTS,           /**< Audio PTS timestamp SBM */
    phStbKBufMgr_Buffer_AUX_MUX,        /**< Auxiliary demultiplexor buffer */
    phStbKBufMgr_Buffer_ALT_DIRECTFB,   /**< Alternate directFB buffer */
    phStbKBufMgr_Buffer_VID_INPUT,      /**< Video input buffer */
    phStbKBufMgr_Buffer_DEBUG_REGION,   /**< A region that can be used for debug storage.*/

    /** Indicates number of buffer types that need physical memory allocation.
        The buffer type enums below are for buffers that share space with the buffers
        that are allocated. */
    phStbKBufMgr_Buffer_AllocatedGuard,

    phStbKBufMgr_Buffer_FSY_AVS = phStbKBufMgr_Buffer_AllocatedGuard,
                                        /**< Frame store Y buffers for AVS */
    phStbKBufMgr_Buffer_FSUV_AVS,       /**< Frame store UV buffers for AVS */
    phStbKBufMgr_Buffer_Number          /**< Number of buffer types */
} phStbKBufMgr_Buffer_t;

/**************************************************************
* EXPORTED DATA                                               *
***************************************************************/

/**************************************************************
* EXPORTED FUNCTION PROTOTYPES                                *
***************************************************************/

/** Allocate a buffer.

    @param  buf       @b IN   Type of buffer required
    @param  pBufAddr  @b OUT  Storage for address of buffer
    @param  pSize     @b OUT  Storage for size of buffer

    @retval TM_OK  Success
    @retval PH_STBKBUFMGR_ERR_BAD_BUFFER_TYPE Wrong buffer type
    @retval PH_STBKBUFMGR_ERR_BUFFER_NOT_AVAILABLE No free buffer available.
*/
tmErrorCode_t phStbKBufMgr_GetBuffer(
    phStbKBufMgr_Buffer_t buf,
    uint32_t *pBufAddr,
    uint32_t *pSize);


/** Release an allocated buffer.

    @param  buf       @b IN   Type of buffer released
    @param  bufAddr   @b IN   address of buffer

    @retval TM_OK  Success
    @retval PH_STBKBUFMGR_ERR_BAD_BUFFER_TYPE Wrong buffer type
    @retval PH_STBKBUFMGR_ERR_BUFFER_NOT_AVAILABLE No buffer exists with the specified address

    @note There is no check that the buffer to be released is currently allocated.
*/
tmErrorCode_t phStbKBufMgr_ReleaseBuffer(
	phStbKBufMgr_Buffer_t buf,
	uint32_t bufAddr);

/** Takes the passed in buffer and swaps it with the stop buffer slot
*/
tmErrorCode_t phStbKBufMgr_SwapStopBuffer(
	phStbKBufMgr_Buffer_t buf,
	phStbKBufMgr_Buffer_t stop_buf,
	uint32_t bufAddr);

/** Lookup the address and size of an allocated buffer.

    @param  buf       @b IN   Type of buffer
    @param  bufferIndex @b IN Index of buffer instance
    @param  pBufAddr  @b OUT  Storage for address of buffer, or NULL if not interested
    @param  pSize     @b OUT  Storage for size of buffer, or NULL if not interested

    @retval TM_OK  Success
    @retval PH_STBKBUFMGR_ERR_BAD_BUFFER_TYPE Wrong buffer type
    @retval PH_STBKBUFMGR_ERR_BAD_BUFFER_INDEX bufferIndex out of range
    @retval PH_STBKBUFMGR_ERR_NOT_ALLOCATED Buffer is not allocated.
*/
tmErrorCode_t phStbKBufMgr_LookupBuffer(
    phStbKBufMgr_Buffer_t buf,
    uint32_t bufferIndex,
    uint32_t *pBufAddr,
    uint32_t *pSize);


/** Get size and availability statistics for a given buffer type.

    @param  buf        @b IN   Type of buffer
    @param  pSiz       @b OUT  Storage for size of buffer, or NULL if not interested.
    @param  pNumTotal  @b OUT  Storage for total number of buffers, or NULL if not interested.
    @param  pNumFree   @b OUT  Storage for number of buffers currently free, or NULL if not interested.
    @retval TM_OK  Success
    @retval PH_STBKBUFMGR_ERR_BAD_BUFFER_TYPE Wrong buffer type
*/
tmErrorCode_t phStbKBufMgr_BufferStats(
    phStbKBufMgr_Buffer_t buf,
    uint32_t *pSize,
    uint32_t *pNumTotal,
    uint32_t *pNumFree);

#ifdef __cplusplus
}
#endif

#endif /* Do not add any thing below this line */

