source: svn/trunk/newcon3bcm2_21bu/magnum/commonutils/img/bimg.h @ 2

/***************************************************************************
 *     Copyright (c) 2005, 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: bimg.h $
 * $brcm_Revision: Hydra_Software_Devel/1 $
 * $brcm_Date: 2/24/05 6:46p $
 *
 * Module Description: throttled playback
 *
 * Revision History:
 *
 * $brcm_Log: /magnum/commonutils/img/bimg.h $
 * 
 * Hydra_Software_Devel/1   2/24/05 6:46p vsilyaev
 * PR 14226: Interface to access firmware type of data images
 * 
 *
 ***************************************************************/
#ifndef BIMG_H__
#define BIMG_H__

/*================== Module Overview =====================================
This modules defines interface to access firware image files.

User of the interface (low level software, aka Porting Interface module) is responsible: 
        o to pair 'open' with 'close' call 
        o do not nest calls to 'open' 
        o test return codes from 'open' and 'next' calls, each error considered to be fatal 
        o do not use interface in the _isr context 

Provider of the image loader interface is resposible: 
        o open,next and close calls shall take bounded time to execute 
        o 'next' method should either read requested number of bytes from the media or return an error 
  
========================================================================*/

/***************************************************************************
Summary:
        This method is used to open image interface and allow further access to the image

Input:
        context - conext of the image interface
    image_id - system specific ID for the specific image

Output:
        image - context for the opened image

Returns:
    BERR_SUCCESS - if function succeded
        error code - if function has failed
        

***************************************************************************/
typedef BERR_Code (*BIMG_Method_Open)(
        void *context,  /* context of the image interface */
        void **image,  /* [out] pointer to the image context */
        unsigned image_id /* ID of the image */
);

/***************************************************************************
Summary:
        This method is used to access to the image data

Input:
        image - conext of previously opened image
        chunk - number of microcode block
    length - size of the microcode block

Output:
        data - pointer to the images data

Returns:
    BERR_SUCCESS - if function succeded and data points to the memory with exact 'length' bytes of data
        error code - if function has failed

***************************************************************************/
typedef BERR_Code (*BIMG_Method_Next)(
        void *image,  /* image context information, one returned by the 'open' call */
        unsigned chunk,  /* number of chunk, starts from 0, shall increment with each call */
        const void **data,  /*  [out] returns pointer to next piece of data, contents of this pointer is valid until succeding call to the 'next' function */
        uint16_t length /* number of bytes to read from the image,  length shall be less than 64K */
); 

/***************************************************************************
Summary:
        This method is used to close image context

Input:
        image - conext of previously opened image

Returns:
    <none>

***************************************************************************/
typedef void (*BIMG_Method_Close)(
        void *image /* image context */
);

/***************************************************************************
Summary:
        This interface is used to access firmware images

***************************************************************************/
typedef struct BIMG_Interface {
        BIMG_Method_Open open; /* open method */
        BIMG_Method_Next next; /* 'next' method */
        BIMG_Method_Close close; /* close method */
} BIMG_Interface;

#endif /* BIMG_H__ */