source: svn/trunk/newcon3bcm2_21bu/dta/src/app/image_recv.h @ 2

/***************************************************************************
 *     Copyright (c) 2003-2008, 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: $
 * $brcm_Revision: $
 * $brcm_Date: $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/
#if !defined(__IMAGE_RECV_H__)
#define __IMAGE_RECV_H__

#include "bsettop_types.h"

/***************************************************************************
Summary:
 Error codes returned by image functions
Description:
 Error codes that are returned by image... functions. Caller must test
these error codes and update status accordingly.
***************************************************************************/
#define berr_no_dsmcc_pid 41
#define berr_no_code_image_file 42
#define berr_download_failure 43
#define berr_no_memory 44
#define berr_verification_falure 45
#define berr_loading 46
#define berr_same_version 47

/***************************************************************************
Summary:
 Structure describing received software image in memory.
Description:
 Structure is placed at the head of received image.
 size - size of the image.
 header - space for boot header structure;
 data - content of the software image. The actual array has at least as many
 bytes as the size of the image. The remaining bytes follow the first element
 of the array - data[1], data[2]...
***************************************************************************/
struct image_t {
    size_t size;
    unsigned int header[4];
    char data[1];
};

/***************************************************************************
Summary:
 Structure describing current download status.
Description:
 Structure is used to obtain status for display in diagnostic screen
 block_count - total block count according to DII
 block_received - number of blocks that was already received.
 module_version - module version from DII
 module_info_length - lenght of module name from DII
 module_info_bytes - pointer to constant string containing module name.
***************************************************************************/
struct image_status_t {
    uint32_t blocks_count;
    uint32_t blocks_received;
    uint32_t module_version;
    uint32_t module_info_length;
    uint8_t * module_info_bytes;
};

/***************************************************************************
Summary: 
  Initialize image download.
Description:
  Initialize image download and prepare for receiving image. This function 
should be called before calling any other function. There is no corresponding
close function.
Input:
  None
Output:
  None
Returns:
  b_ok in case call was successful, error code otherwise.
SeeAlso:
None
***************************************************************************/
bresult image_init(void);

/***************************************************************************
Summary:
  Receive image from the dsmcc carousel
Description:
  Receive image from the dsmcc carousel. The function first receives dii,
parses it, then receives first module described in dii. The result is stored
in memory block described by image_t structure and allocated inside of the
function. After caller is done with the image it must call free(image) in
order to avoid memory leak. Since image is large memory leak will be 
significant. Function does not do any tuning so tuning should be done before
calling this function.
Input:
  band - input band on which to receive data.
  pid - pid which contains dsm-cc data.
  image - pointer to pointer to the image structure.
  name_lengh - lenght of name from CVT
  name - pointer to the name from CVT
Output:
  image - if function is successful this pointer will be initialize with
pointer to the image_t structure containing received image. If function
fails content of this pointer is not defined. After application is done with
data the this pointer should be freed by calling free.
Returns:
  b_ok if function is successful error code otherwise.
SeeAlso:
  image_init
***************************************************************************/
bresult image_receive(bband_t band, uint16_t pid, struct image_t ** image, uint8_t name_length, uint8_t * name);

/***************************************************************************
Summary:
  Write image to flash
Description:
  Function chooses which location to use for storing image based on image
version and running image version. Then function authenticates image and 
if authentication successful, writes image to flash.
Input:
  image - pointer to the image structure.
Output:
  None
Returns:
  b_ok if function is successful error code otherwise.
SeeAlso:
  image_init, image_receive
***************************************************************************/
bresult image_write(struct image_t * image);

/***************************************************************************
Summary:
  Retrieve current download status.
Description:
  Retrieve current download status from download module.
Input:
  status - poitner to the stcuture that will be filled with status
           information.
Output:
  None
Returns:
  None
SeeAlso:
  image_init, image_receive
***************************************************************************/
void image_get_status(struct image_status_t * status);


/***************************************************************************
Summary:
 Retrieve flash write status.
Description:
 New HD DTA OSI requires to draw the percentage of CDL. 
Output:
 berased : specify whether flash erase is done or not 
 wpct : percentage of flash program
Return:
 None
***************************************************************************/
void image_get_wstate(bool *berased, int *wpct);

/***************************************************************************
Summary:
 Return application header for specified bank
Input:
 bank - 0 for Bank A, 1 for Bank B
Output:
 bact - specifiy specified bank image is active or not
Returns:
 pointer to the application header for the specified bank. 
 If there's no image on that bank, return NULL
***************************************************************************/
void *image_get_header(int bank, bool *bact);
#endif