/*
VirtualPage.h - Flash page management
Original Copyright (c) 2017 Frank Holtz. All right reserved.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* @file VirtualPage.h
* @brief Virtual page management on top of Flash
* The managed pages are organized into VirtualPage.size() sized pages.
* Some Bytes of a Flash page are reserved for a magic number and page management.
*
* @ingroup NVM
* @details Nonvolatile Memory Class
* @{
*/
#pragma once
#include "Flash.h"
#include <Arduino.h>
/**
* @class VirtualPageClass
* @brief Virtual page management on top of Flash
*/
class VirtualPageClass
{
public:
//----------------------------------------------------------------------------
/** Constructor */
VirtualPageClass() {};
//----------------------------------------------------------------------------
/** Initialize Virtual Pages */
void begin() {};
//----------------------------------------------------------------------------
/** Deinitilize Virtual Pages */
void end() {};
//----------------------------------------------------------------------------
/** Reports usable page size in bytes
* @return Number of bytes
*/
uint16_t size() const;
//----------------------------------------------------------------------------
/** Reports usable page size in 32 Bit words
* @return Number of words
*/
uint16_t length() const;
//----------------------------------------------------------------------------
/** Reports the maximum number of allocatable pages
* @return Number of pages
*/
uint16_t page_count() const;
//----------------------------------------------------------------------------
/** Calculates the rate of wear in percent*100.
* Values greater than 10000 indicates exceeding the chip specification.
* This value is only valid for controllers, never erased completely.
* @return calculated level
*/
uint32_t wear_level();
//----------------------------------------------------------------------------
/** Search for a page by given, unique magic number.
* Returns a pointer to (uint32_t *)~0 if there is no page. Don't write
* to this address.
* @param[in] magic A magic number to identify the page.
* @return Pointer to a page
*/
uint32_t *get(uint32_t magic);
//----------------------------------------------------------------------------
/** Returns an address to a blank page or (uint32_t *)~0 if no space
* available. Take care about RADIO, WDT and Interrupt timing! Calculate with
* 0-100ms until a page is available.
* @param[in] magic A magic number to identify the page.
* @return Pointer to a page
*/
uint32_t *allocate(uint32_t magic);
//----------------------------------------------------------------------------
/** Returns an address to a blank page or (uint32_t *)~0 if no space
* available. Take care about RADIO, WDT and Interrupt timing! Calculate with
* 0-100ms until a page is available.
* This function allows using a page multiple times without erasing on some platforms.
* @param[in] magic A magic number to identify the page.
* @param[in] max_writes The number of planned write operations in page lifecycle.
* @return Pointer to a page
*/
uint32_t *allocate(uint32_t magic, uint32_t max_writes);
//----------------------------------------------------------------------------
/** Start releasing a page. You have to allocate a new one and then release the
* old page.
* @param[in] *address A pointer to the page to release
*/
void release_prepare(uint32_t *address);
//----------------------------------------------------------------------------
/** End releasing a page.
* @param[in] *address A pointer to the page to release
*/
void release(uint32_t *address);
//----------------------------------------------------------------------------
/** Returns true if page is in release_prepare state
* @param[in] *address A pointer to a page
* @return Release state
*/
bool release_started(uint32_t *address);
//----------------------------------------------------------------------------
/** Mark a page as a defect page.
*/
void fail(uint32_t *address);
//----------------------------------------------------------------------------
/** Prepare released pages for faster reallocation. Plan with 0-100ms.
*/
void clean_up();
//----------------------------------------------------------------------------
/** Release all pages
*/
void format();
private:
// convert page number 1..max_pages into an address
uint32_t *get_page_address(uint16_t page);
// build a page
void build_page(uint32_t *address, uint32_t magic);
// return number of erase cycles
uint32_t get_page_erase_cycles(uint32_t *address);
};
extern VirtualPageClass VirtualPage; //!< extern VirtualPageClass
/** @} */