// -----------------------------------------------------------------------------
/// @file  CachedStorage.h
/// @brief Generic memory cache
// -----------------------------------------------------------------------------
//  Micro-Key bv
//  Industrieweg 28, 9804 TG Noordhorn
//  Postbus 92, 9800 AB Zuidhorn
//  The Netherlands
//  Tel: +31 594 503020
//  Fax: +31 594 505825
//  Email: support@microkey.nl
//  Web: www.microkey.nl
// -----------------------------------------------------------------------------
/// $Revision$
/// $Author$
/// $Date$
//  (c) 2017 Micro-Key bv
// -----------------------------------------------------------------------------

/**
 * CachedStorage implementation
 * \defgroup CachedStorage Package CachedStorage
 * \ingroup HAL
 * @{
 */

#ifndef _CACHEDEEPROM_H_
#define _CACHEDEEPROM_H_

// -----------------------------------------------------------------------------
// Include files
// -----------------------------------------------------------------------------

#include <stdint.h>
#include <stdbool.h>
#include <stdio.h>

#include "stm32f10x.h"

#include "platform.h"

// -----------------------------------------------------------------------------
// Constant and macro definitions
// -----------------------------------------------------------------------------



// -----------------------------------------------------------------------------
// Type definitions.
// -----------------------------------------------------------------------------


struct CachedStorage
{
   bool initialized;
   unsigned int pageNumber;
   size_t cacheSize;
   bool dirty;
   struct MemoryDevice* memoryDevice;
   uint32_t* storage;
   uint32_t* tempBuffer;
};

// -----------------------------------------------------------------------------
// Function declarations
// -----------------------------------------------------------------------------


/** ----------------------------------------------------------------------------
 * CachedStorage_construct
 * Constructor for a new cached storage instance
 * Function makes use of MALLOC
 *
 * @param   self                       The cache instance
 * @param   memoryDevice               The memory device to use on which the
 *                                     cache is located
 * @param   pageNumber                 The pageNumber of the memory section on
 *                                     which the cache is located.
 *                                     This is usually for FLASH or EEPROM
 *                                     devices and required for PAGE-ERASE
 *                                     functionality. Can be set to any random
 *                                     value if PAGE-ERASE is not necessary
 * @param   cacheSize                  The size of the cache.
 *                                     This value is 32bit oriented and
 *                                     NOT BYTE-WISE.
 *                                     The memory allocation will internally
 *                                     re-calculate to bytes
 *
 * @return  ErrorStatus                SUCCESS if constructor was successful
 *                                     ERROR otherwise
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
ErrorStatus CachedStorage_construct(struct CachedStorage* self, struct MemoryDevice* memoryDevice, unsigned int pageNumber, size_t cacheSize);


/** ----------------------------------------------------------------------------
 * CachedStorage_destruct
 * Destructor for a cached storage instance
 * Function makes use of FREE
 *
 * @param   self                       The cache instance to destruct
 *
 * @return  void
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
void CachedStorage_destruct(struct CachedStorage* self);


/** ----------------------------------------------------------------------------
 * CachedStorage_writeWord
 * Function to write a word (32bit) to cache
 *
 * @param   self                       The cache instance
 * @param   offset                     Offset within the cache to put the data
 * @param   value                      The value/data to write
 *
 * @return  void
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
void CachedStorage_writeWord(struct CachedStorage* self, int offset, uint32_t value);


/** ----------------------------------------------------------------------------
 * CachedStorage_writeBlob
 * Function to write a blob (any given format/amount of data) to cache; hence
 * the void pointer.
 * The function verifies cache boundaries using the offset and blob size
 * blobsize is 32bit oriented, NOT BYTE
 *
 * @param   self                       The cache instance
 * @param   offset                     Offset within the cache to put the data
 * @param   blob                       Void pointer to the data to be written
 * @param   blobSize                   sizeof the blob structure. Give in 32bit,
 *                                     NOT IN BYTES
 *
 * @return  void
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
void CachedStorage_writeBlob(struct CachedStorage* self, int offset, const void* blob, size_t blobSize);


/** ----------------------------------------------------------------------------
 * CachedStorage_readWord
 * Function to read a word (32bit) from cache
 *
 * @param   self                       The cache instance
 * @param   offset                     Offset within the cache to put the data
 *
 * @return  uint32_t                   The read data
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
uint32_t CachedStorage_readWord(struct CachedStorage* self, int offset);


/** ----------------------------------------------------------------------------
 * CachedStorage_readBlob
 * Function to read a blob (any given format/amount of data) from cache; hence
 * the void pointer.
 * The function verifies cache boundaries using the offset
 *
 * @param   self                       The cache instance
 * @param   offset                     Offset within the cache to put the data
 *
 * @return  void*                      Void pointer to the blob structure
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
const void* CachedStorage_readBlob(struct CachedStorage* self, int offset);


/** ----------------------------------------------------------------------------
 * CachedStorage_commit
 * Function that puts the data from cache to the memory device.
 * This function will verify that the content of the cache is actually different
 * from the conent of the memory location. If data is equal, not write action
 * will be performed
 * In case of memory that needs PAGE-ERASE prior to write, the erase function
 * will be called automatically.
 *
 * @param   self                       The cache instance
 *
 * @return  void
 *
 * @todo
 * -----------------------------------------------------------------------------
 */
void CachedStorage_commit(struct CachedStorage* self);

#endif

/** @} */