/*******************************************************************************
 * Copyright 2004-2005 - Software Design Solutions, Inc.  All rights reserved.
 *
 * Portions of this work have been provided under license with Texas 
 * Instruments Inc.
 * 
 * $RCSfile: FBTCBurn.h,v $
 * $Revision: 1.9 $
 * 
 * Description: Defines the FlashBurn Target Component commands
 * 
 ******************************************************************************/


#ifndef _FBTCBURN_H
#define _FBTCBURN_H
 
#include "type.h"
#include "TargetConfig.h"


/** 
 * Type for the index used to reference flash memory as one large flat
 * address space. The flash index is zero-based.
 * All targets use a 32 bit index. 
 */
typedef u32 FLASH_IMAGE_INDEX_TYPE;

 
/** 
 * Set the flash memory base address, permitting the host to override the flash
 * base address given as FLBASE in TargetConfig.h
 *
 * @param [in] addr - New base address for flash programming
 *
 * @pre  - InitFlash() has been run
 * @post - The flash memory base address is updated
 */
void SetFlashBase(FLASH_DATA_TYPE *addr);


/**
 * Get the current flash memory base address.
 * 
 * @return - The current flash memory base address
 *
 * @pre  - InitFlash() has been run
 */
FLASH_DATA_TYPE *GetFlashBase(void);


/**
 * Set the flash memory size, permitting the host to override the flash size
 * given as FLSIZEBYTES
 * 
 * @param [in] size - The new flash memory size, in bytes
 *
 * @pre  - InitFlash() has been run
 * @post - The flash memory size is updated
 */
void SetFlashSize(FLASH_IMAGE_INDEX_TYPE size);


/** 
 * Get the current flash memory size
 * 
 * @return - The current flash memory size, in bytes
 *
 * @pre  - InitFlash() has been run
 */
FLASH_IMAGE_INDEX_TYPE GetFlashSize(void);


/** 
 * Initialize the state of flash programming
 *
 * @post - Flash programming is ready to begin at the flash base address
 */
void InitFlash(void);


/** 
 * Burn data into flash memory the given index
 *
 * @param [in] index  - Zero based index into flash memory to begin burning
 * @param [in] data   - Data to burn to flash, from the command message
 * @param [in] nBytes - Number of bytes to burn
 *
 * @pre  - InitFlash() has been run
 * @post - Flash at the current flash memory pointer is burned
 */
void BurnFlash(FLASH_IMAGE_INDEX_TYPE index, MSG_DATA_TYPE *data, u32 nBytes);


/**
 * Get the contents of a flash location
 *
 * @param [in] index - Zero-based index into flash memory
 *
 * @return - The contents of flash memory at the location
 */
FLASH_DATA_TYPE GetFlashVal(FLASH_IMAGE_INDEX_TYPE index);


/**
 * Given a buffer of flash indices, 32 bits each, translate them
 * to a buffer of flash addresses.  Targets with paged memory may
 * encode the page number in the upper bits.
 *
 * @param [in] count - Count of indexes in the buffer
 *
 * @return Flash addresses corresponding to the indices
 *
 * @pre  - InitFlash() has been run
 */
void GetFlashAddresses(u16 count);


/**
 * Sends a block of flash bytes to host
 *
 * @param [in] cmd    - Command to send back to the host
 * @param [in] index  - Zero based index into flash memory
 * @param [in] nBytes - Count of bytes to send
 *
 * @pre  - InitFlash() has been run
 * @post - Flash contents have been sent to the host
 */
void SendFlashBufToHost(u16 cmd, FLASH_IMAGE_INDEX_TYPE index, u32 nBytes);


/**
 * Erase all of flash memory
 *
 * @pre  - InitFlash() has been run
 * @post - All of flash is erased
 */
void EraseFlash(void);


/**
 * Erase an individual flash memory sector.  The definition of a flash
 * sector is implementation dependent
 *
 * @param [in] sector - Sector number to be erased - numbering is target 
 * dependent
 *
 * @pre  - InitFlash() has been run
 * @post - The given flash sector has been erased
 */
void EraseFlashSector(unsigned long sector);


/**
 * Check the flash erase status - return when the erasure is completed
 * 
 * @pre  - InitFlash() has been run
 * @post - When the function returns, flash erasure is complete
 */
void CheckFlashErase(void);


/*
 * Checksum Processing
 * A simple modulo-16 additive cksum which adds the carry bit back into the 
 * accumulator.
 */

/**
 * Initialize the checksum value
 *
 * @param [in] val - Initial value for the checksum
 *
 * @pre  - InitFlash() has been run
 * @post - The checksum is initialized
 */
void CKSSet(u16 val);


/** 
 * Returns the current checksum value
 *
 * @return - The currently computed checksum value
 * 
 * @pre  - InitFlash() has been run
 */
u16 CKSGet(void);


/** 
 * Compute a checksum of a buffer
 *
 * @param [in] index  - Zero based index into flash to start computing the 
 * checksum
 * @param [in] nBytes - Length of flash to use for the checksum, in bytes
 * 
 * @return - The value of the checksum
 *
 * @pre  - InitFlash() has been run
 * @post - Accumulated checksum is updated
 */
u16 CKSAccumBuf(FLASH_IMAGE_INDEX_TYPE index, u32 nBytes);

#endif