*
 * Description:   
 *
 *    This procedure is called to program the protection register on
 *    the flash device at the specified location with the specified data
 *    value.  See the flash device datasheet for specific details on this
 *    command.
 *
 * Parameters:
 *
 *    IN      location - the protection register location on the flash
 *                       device to be programmed.
 *
 *    IN      value    - the data item to be programmed.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_ProgramProtection ( UINT32 location, 
                                     TMPL_FDATA value,
                                     UINT8 returnSR );



/****************************************************************************
 *
 * TMPL_ProgramSuspend
 *
 * Description:   
 *
 *    This procedure is called to issue the program suspend command to
 *    the flash device.  See the flash device datasheet for specific details 
 *    on this command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number on the device.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    When this function is called the device is currently in the program
 *    mode for the block identified.
 *
 ***************************************************************************/
TMPL_Status TMPL_ProgramSuspend ( UINT16 blocknum,
                                  UINT8 returnSR );


/****************************************************************************
 *
 * TMPL_Query
 *
 * Description:   
 *
 *    This procedure is called to issue the query command to
 *    the flash device.  See the flash device datasheet for specific details 
 *    on this command.
 *
 * Parameters:
 *
 *    OUT      *query - pointer to query structure
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_Query( struct TMPL_QueryData *query );


/****************************************************************************
 *
 * TMPL_ReadBlockStatus
 *
 * Description:   
 *
 *    This procedure is called to read the status for the specified block
 *    from the flash device.  See the flash device datasheet for specific 
 *    details on this command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number on the device.
 *
 *    OUT     blockstat- the status of the block as: unlocked, locked, 
 *                       or locked down.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum 
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_ReadBlockStatus ( UINT16    blocknum, 
                                   TMPL_FDATA_PTR blockstat );


/****************************************************************************
 *
 * TMPL_ReadDeviceID
 *
 * Description:   
 *
 *    This procedure is called to read the status for the specified block
 *    from the flash device.  See the flash device datasheet for specific 
 *    details on this command.
 *
 * Parameters:
 *
 *    OUT     mcode    - the manufacturer code.
 *
 *    OUT     deviceid - the device id.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_ReadDeviceID ( UINT16_PTR mcode, 
                                UINT16_PTR deviceid ); 


/****************************************************************************
 *
 * TMPL_ReadF
 *
 * Description:   
 *
 *    This procedure is called to read a single data item directly from the 
 *    specified device address.  This function is used internally by the
 *    flash template api.  Clients that need to read data from the flash
 *    device should use the TMPL_ReadFlash command.  See the flash device 
 *    datasheet for specific details on reading flash data.
 *
 * Parameters:
 *
 *    IN      address  - the flash address to be read from.
 *
 *    OUT     value    - the flash data read from the device.
 *
 * Returns:   
 *
 *    NONE
 *
 * Assumptions:
 *
 *    The flash device is in the READ_ARRAY mode when this function is
 *    called.
 *
 ***************************************************************************/
void TMPL_ReadF( UINT32 address, 
                 TMPL_FDATA_PTR value );


/****************************************************************************
 *
 * TMPL_ReadFlash
 *
 * Description:   
 *
 *    This procedure is called to read one or more data items from 
 *    the flash device at the specified starting address.  See the flash 
 *    device datasheet for specific details on reading flash data.
 *
 * Parameters:
 *
 *    IN      address  - the starting device address.
 *
 *    OUT     buffer   - the buffer to contain the data items read.
 *
 *    IN      numbytes - the number of data items to read.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_ReadFlash ( UINT32    address, 
                             UINT8_PTR buffer, 
                             UINT32    numbytes,
                             UINT8 returnSR );


/****************************************************************************
 *
 * TMPL_ReadProtection
 *
 * Description:   
 *
 *    This procedure is called to read the protection register value on
 *    the flash device from the specified location.  See the flash device 
 *    datasheet for specific details on this command.
 *
 * Parameters:
 *
 *    IN      location - the protection register location on the flash
 *                       device to be read from. 
 *
 *    OUT     value    - the data item read from the register.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_ReadProtection ( UINT32    location, 
                                  TMPL_FDATA_PTR value );


/****************************************************************************
 *
 * TMPL_ReadStatus
 *
 * Description:   
 *
 *    This procedure is called to read the status register value from
 *    the flash device.  See the flash device datasheet for specific details
 *    on this command.
 *
 * Parameters:
 *
 *    NONE
 *
 * Returns:   
 *
 *    TMPL_FDATA - the status register value read from the device.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_FDATA TMPL_ReadStatus ( void );


/****************************************************************************
 *
 * TMPL_Resume
 *
 * Description:   
 *
 *    This procedure is called to issue the resume command to the flash
 *    device for the specified block. See the flash device datasheet for
 *    specific details on this command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number to resume.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    The block indicated was previously program suspended or erase 
 *    suspended.
 *
 ***************************************************************************/
TMPL_Status TMPL_Resume ( UINT16 blocknum,
                          UINT8 returnSR );


/****************************************************************************
 *
 * TMPL_SecExtendedQuery
 *
 * Description:   
 *
 *    This procedure is called to retrieve the secondary extended query
 *    data from the flash device.  See the flash device datasheet for
 *    specific details on this command.
 *
 * Parameters:
 *
 *    OUT      *secextquery - pointer to secondary extended query structure
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_SecExtendedQuery( struct TMPL_SecExtQueryData *secextquery );


/****************************************************************************
 *
 * TMPL_UnlockBlock
 *
 * Description:   
 *
 *    This procedure is called to unlock the specified block on the flash
 *    device.  See the flash device datasheet for specific details on this 
 *    command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number to unlock.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    The block indicated was previously locked.
 *
 ***************************************************************************/
TMPL_Status TMPL_UnlockBlock ( UINT16 blocknum,
                               UINT8 returnSR );


/****************************************************************************
 *
 * TMPL_WaitUntilReady
 *
 * Description:   
 *
 *    This procedure is called to wait until the flash device status 
 *    indicates a ready state or times out.  See the flash device datasheet
 *    for specific details on reading status data.
 *
 * Parameters:
 *
 *    IN      timeout  - timeout value specified as number of times
 *                       to read the status register before giving up.
 *
 * Returns:   
 *
 *    UINT8 - boolean flag indicating whether the ready state was
 *            reached before the timeout number of reads 
 *            occured.
 *
 * Assumptions:
 *
 *    NONE.
 *
 ***************************************************************************/
UINT8 TMPL_WaitUntilReady( UINT32 timeout );


/****************************************************************************
 *
 * TMPL_WriteF
 *
 * Description:   
 *
 *    This procedure is called to write a single data item directly to the 
 *    specified device address.  This function is used internally by the
 *    flash template api.  Clients that need to write data to the flash
 *    device should use the TMPL_ProgramFlash or TMPL_ProgramFlashBuffered
 *    command.  See the flash device datasheet for specific details on
 *    writing flash data.
 *
 * Parameters:
 *
 *    IN      address  - the flash address to be written to.
 *
 *    IN      value    - the flash data to write to the device.
 *
 * Returns:   
 *
 *    NONE
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
void TMPL_WriteF( UINT32 address, 
                  TMPL_FDATA value );

#endif  /* __TEMPLATE_H */