SPI_Memory_Base.h

Go to the documentation of this file.

//------------------------------------------------------------------------------
//! @file       SPI_Memory_Base.h
//! @brief      SPI connected memory base class header file.
//! @attention  No special attention requered.
//! @copyright  (C) 2015-2020 ANVILEX LLC
//!             $HeadURL: https://192.168.3.4:8443/svn/P004_07/ConOpSys/Engine/SPI_Memory_Base.h $
//!             $Revision: 2339 $
//!             $Date: 2021-01-08 14:06:54 +0500 (Fr, 08 Jan 2021) $
//!             $Author: minch $
//------------------------------------------------------------------------------
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// 1. Redistributions of source code must retain the above copyright notice,
//    this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.
//
// 3. Neither the name of ANVILEX nor the names of its contributors may be
//    used to endorse or promote products derived from this software without
//    specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//
//------------------------------------------------------------------------------
 
#pragma once
 
//------------------------------------------------------------------------------
// Include files
//------------------------------------------------------------------------------
 
#include "SPI_Master_Base.h"
#include "Protocol_Base.h"
 
//------------------------------------------------------------------------------
// Class definitions
//------------------------------------------------------------------------------
 
//! @brief SPI memory base class
class TSPI_Memory_Base
{
 
  //----------------------------------------------------------------------------
  // Public defines, methods and variables
  //----------------------------------------------------------------------------
 
  public:
 
    //--------------------------------------------------------------------------
    // Public defines
    //--------------------------------------------------------------------------
  
    //! @brief Chip descriptior structure
    typedef struct
    {
 
      //! @brief Chip capacity in bytes
      U32 u32_Chip_Size;
 
      //! @brief Size of block in bytes
      U32 u32_Block_Size;
 
      //! @brief Size of page in bytes
      U16 u16_Page_Size;
 
      //! @brief Count of the blocks per chip
      U16 u16_Blocks_Per_Chip_Count;
 
      //! @brief Count of the pages per block
      U16 u16_Pages_Per_Block_Count;
 
      //! @brief Count of the pages per chip
      U32 u32_Pages_Per_Chip_Count;
 
      //! @brief Chip supported flag
      BOOL bool_Supported;
 
    } TMemory_Chip_Descriptor;
 
    //--------------------------------------------------------------------------
    // Public methods
    //--------------------------------------------------------------------------
    
    //!-------------------------------------------------------------------------
    //! @brief     Base class constructor method.
    //! @note      None
    //! \par       Override
    //!            Not allowed
    //! @attention Don't call this method directly.
    //--------------------------------------------------------------------------
 
    TSPI_Memory_Base();
 
    //!-------------------------------------------------------------------------
    //! @brief     Base class constructor method.
    //! @note      None
    //! \par       Override
    //!            Not allowed
    //! @attention Don't call this method directly.
    //--------------------------------------------------------------------------
 
    virtual ~TSPI_Memory_Base();
 
    //!-------------------------------------------------------------------------
    //! @brief     SPI memory base object initialisation method.
    //! @note      None
    //! @return    None
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    VOID Init();
 
    //!-------------------------------------------------------------------------
    //! @brief     SPI memory base object finalisation method.
    //! @note      None
    //! @return    None
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    VOID Done();
 
    //!-------------------------------------------------------------------------
    //! @brief     Start operation of SPI memory base driver.
    //! @note      This method start operation of memory driver and underlayed SPI hardware driver.
    //! @return    None
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual VOID Start();
 
    //!-------------------------------------------------------------------------
    //! @brief     Stop operation of SPI memory base driver.
    //! @note      This method stop operation of memory driver and underlayed SPI hardware driver.
    //! @return    None
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual VOID Stop();
 
    //!-------------------------------------------------------------------------
    //! @brief     Assign SPI master hardware driver.
    //! @note      None
    //! @param     [in] *object_New_SPI_Master - Pointer to the SPI master hardware driver
    //! @return    None
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    VOID Assign_SPI_Master( TSPI_Master_Base *object_New_SPI_Master );
 
    //!-------------------------------------------------------------------------
    //! @brief     Unassign SPI master hardware driver.
    //! @note      None
    //! @return    None
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    VOID Unassign_SPI_Master();
 
    //!-------------------------------------------------------------------------
    //! @brief     Read data from memory into the buffer method.
    //! @note      None
    //! @param     [in] u32_Linear_Address - Linear address in memory
    //! @param     [in] u32_Size - Amount byte to read
    //! @param     [out] *u8_Data_Buffer - Pointer to the data buffer
    //! @return    BOOL - Read operation status
    //! @retval    false - Read operation failed
    //! @retval    true - Read operation succeeded
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Read_Buffer( U32 u32_Linear_Address, U32 u32_Size, U8 *u8_Data_Buffer ) = 0;
 
    //!-------------------------------------------------------------------------
    //! @brief     Write data from buffer into memory method.
    //! @note      None
    //! @param     [in] u32_Linear_Address - Linear address in memory
    //! @param     [in] u32_Size - Amount byte to write
    //! @param     [in] *u8_Data_Buffer - Pointer to the data buffer
    //! @return    BOOL - Write operation status
    //! @retval    false - Write operation failed
    //! @retval    true - Write operation succeeded
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Write_Buffer( U32 u32_Linear_Address, U32 u32_Size, U8 *u8_Data_Buffer ) = 0;
 
    //!-------------------------------------------------------------------------
    //! @brief     Verify data in memory and memory method.
    //! @note      None
    //! @param     [in] u32_Linear_Address - Linear address in memory
    //! @param     [in] u32_Size - Amount byte to verify
    //! @param     [in] *u8_Data_Buffer - Pointer to the data buffer
    //! @return    BOOL - Verification operation status
    //! @retval    false - Verification operation failed, data in buffer and memory not equal
    //! @retval    true - Verification operation succeeded, data in buffer and memory equal
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Verify_Buffer( U32 u32_Linear_Address, U32 u32_Size, U8 *u8_Data_Buffer );
 
    //!-------------------------------------------------------------------------
    //! @brief     Erase chip method.
    //! @note      This method can done full erase the memory, or erase only not damage blocks
    //! @param     [in] bool_Force_Bad_Block_Erase - Option to select an erase type
    //! @return    BOOL - Erasing status
    //! @retval    false - Erase falled
    //! @retval    true - Erase successfully done
    //! \par       Override
    //!            Optional
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Erase_Chip( BOOL bool_Force_Bad_Block_Erase );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get linear address of the block by specified block index.
    //! @note      None
    //! @param     [in] u16_Block_Index - Block index
    //! @param     [out] *u32_Linear_Address - Linear address of the block
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Block_Address( U16 u16_Block_Index, U32 *u32_Linear_Address );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get linear address of the page by specified block index and relative page index.
    //! @note      None
    //! @param     [in] u16_Block_Index - Block index
    //! @param     [in] u16_Relative_Page_Index - Page relative index within block
    //! @param     [out] *u32_Linear_Address - Linear address of the block
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Page_Address( U16 u16_Block_Index, U16 u16_Relative_Page_Index, U32 *u32_Linear_Address );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get capacity of attached SPI memory.
    //! @note      None
    //! @return    U32 - Capacity of attached SPI memory
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    U32 Get_Capacity(); //!< DEPRICATED: Get capacity of attached SPI memory
 
    //!-------------------------------------------------------------------------
    //! @brief     Return SPI avaliability.
    //! @note      None
    //! @return    TRIL - SPI avaliability
    //! \par       Override
    //!            Not requered
    //! @attention DEPRICATED: Return SPI avaliability
    //--------------------------------------------------------------------------
 
    TRIL Is_Available();
 
    //!-------------------------------------------------------------------------
    //! @brief     Method sends default driver information over specified communication channel.
    //! @note      None
    //! @param     [in] *object_Protocol - Pointer to the connunication channel
    //! @return    None
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual VOID Send_Information( TProtocol_Base *object_Protocol );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get page index from lenear address.
    //! @note      None
    //! @param     [in] u32_Linear_Address - Linear address
    //! @param     [out] *u32_Page_Index - Page index
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Page_Index( U32 u32_Linear_Address, U32 *u32_Page_Index );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get page index from block index and page relative index.
    //! @note      None
    //! @param     [in] u16_Block_Index - Block index
    //! @param     [in] u16_Page_Relative_Index - Page relative index
    //! @param     [out] *u32_Page_Index - Page index
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Page_Index( U16 u16_Block_Index, U16 u16_Page_Relative_Index, U32 *u32_Page_Index );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get block index by page index.
    //! @note      None
    //! @param     [in] u32_Page_Index - Page number of the chip
    //! @param     [out] *u16_Block_Index - Block index
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Block_Index_By_Page( U32 u32_Page_Index, U16 *u16_Block_Index );
 
    //!-------------------------------------------------------------------------
    //! @brief     Get page index of the block.
    //! @note      None
    //! @param     [in] u16_Block_Index - Block index
    //! @param     [out] *u32_Page_Index - Page number of the chip
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Page_Index( U16 u16_Block_Index, U32 *u32_Page_Index );
 
    //!-------------------------------------------------------------------------
    //! @brief     Return page size in bytes.
    //! @note      None
    //! @param     [out] *u16_Page_Size - Page size in bytes
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, page size can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Page_Size( U16 *u16_Page_Size );
 
    //!-------------------------------------------------------------------------
    //! @brief     Return pages number into block.
    //! @note      None
    //! @param     [out] *u16_Pages_Per_Block - Page into block
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, block size can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Pages_Per_Block_Count( U16 *u16_Pages_Per_Block );
 
    //!-------------------------------------------------------------------------
    //! @brief     Return total amount of the blocks.
    //! @note      None
    //! @param     [out] *u16_Block_Count - Total block count
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, total block count can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Block_Count( U16 *u16_Block_Count );
 
    //!-------------------------------------------------------------------------
    //! @brief     Return total amount of the pages.
    //! @note      None
    //! @param     [out] *u32_Pages_Per_Chip - Total pages count
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, total block count can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Pages_Per_Chip_Count( U32 *u32_Pages_Per_Chip );
 
  //----------------------------------------------------------------------------
  // Protected defines, methods and variables
  //----------------------------------------------------------------------------
 
  protected:
 
    //--------------------------------------------------------------------------
    // Protected methods
    //--------------------------------------------------------------------------
  
    //!-------------------------------------------------------------------------
    //! @brief     Return total chip capacity in bytes.
    //! @note      None
    //! @param     [out] *u32_Chip_Size - Total chip size in bytes
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, total chip size can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Chip_Size( U32 *u32_Chip_Size );
 
    //!-------------------------------------------------------------------------
    //! @brief     Return block size in bytes.
    //! @note      None
    //! @param     [out] *u32_Block_Size - Block size in bytes
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed, block size can not be retrieved
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Get_Block_Size( U32 *u32_Block_Size );
 
    //!-------------------------------------------------------------------------
    //! @brief     Extract page relative address from lenear address.
    //! @note      None
    //! @param     [in] u32_Linear_Address - Linear address
    //! @param     [out] *u16_Relative_Address - Relative address from beggining of the page
    //! @return    BOOL - Operation status
    //! @retval    false - Operation failed
    //! @retval    true - Operation succeeded
    //! \par       Override
    //!            Not requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Extract_Page_Relative_Address( U32 u32_Linear_Address, U16 *u16_Relative_Address );
 
    //!-------------------------------------------------------------------------
    //! @brief     This method check that block index is valid
    //! @note      None
    //! @param     [in] u16_Block_Index - Block index
    //! @return    BOOL - Operation status
    //! @retval    false - Verification succeeded
    //! @retval    true - Operation failed, verification failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Is_Block_Index_In_Range( U16 u16_Block_Index );
 
    //!-------------------------------------------------------------------------
    //! @brief     This method check that page index is valid
    //! @note      None
    //! @param     [in] u32_Page_Index - Page index
    //! @return    BOOL - Operation status
    //! @retval    false - Verification succeeded
    //! @retval    true - Operation failed, verification failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Is_Page_Index_In_Range( U32 u32_Page_Index );
 
    //--------------------------------------------------------------------------
    // Protected variables
    //--------------------------------------------------------------------------
    
    //! @brief Pointer to the SPI master object
    TSPI_Master_Base *object_SPI_Master = (TSPI_Master_Base*)NULL;
 
    //! @brief Pointer to the chip descriptor structure
    TMemory_Chip_Descriptor *struct_Memory_Chip_Descriptor = (TMemory_Chip_Descriptor*)NULL;
 
    //! @brief Memory chip availablility status
    TRIL tril_Available = (TRIL)unset;
 
    //! @brief Manufacturer ID availablility status
    BOOL bool_Manufacturer_ID_Available = (BOOL)false;
 
    //! @brief Device ID availablility status
    BOOL bool_Device_ID_Available = (BOOL)false;
 
    //! @brief Serial number availablility status
    BOOL bool_Serial_Number_Available = (BOOL)false;
 
    //! @brief Depricated: Capacity of SPI memory in bytes
    U32 u32_Capacity = (U32)0;
 
  //----------------------------------------------------------------------------
  // Private defines, methods and variables
  //----------------------------------------------------------------------------
 
  private:
 
    //--------------------------------------------------------------------------
    // Private methods
    //--------------------------------------------------------------------------
  
    //!-------------------------------------------------------------------------
    //! @brief     Enable write operation into memory.
    //! @note      None
    //! @return    BOOL - Operation status
    //! @retval    false - Operation succeeded
    //! @retval    true - Operation failed
    //! \par       Override
    //!            Optional
    //! @attention Override this method if memory support enabling and disabling write protection function.
    //--------------------------------------------------------------------------
 
    virtual BOOL Write_Enable();
 
    //!-------------------------------------------------------------------------
    //! @brief     Disable write operation into memory.
    //! @note      None
    //! @return    BOOL - Operation status
    //! @retval    false - Operation succeeded
    //! @retval    true - Operation failed
    //! \par       Override
    //!            Optional
    //! @attention Override this method if memory support enabling and disabling write protection function.
    //--------------------------------------------------------------------------
 
    virtual BOOL Write_Disable();
 
    //!-------------------------------------------------------------------------
    //! @brief     Read memory device status register method.
    //! @note      None
    //! @param     [out] *u8_StatusRegister - Pointer to status register value
    //! @return    BOOL - Read operation status
    //! @retval    false - Read operation succeeded
    //! @retval    true - Read operation failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Read_Status_Register( U8 *u8_StatusRegister );
 
    //!-------------------------------------------------------------------------
    //! @brief     Write memory device status register method.
    //! @note      None
    //! @param     [in] u8_StatusRegister - Status register value to write
    //! @return    BOOL - Write operation status
    //! @retval    false - Write operation succeeded
    //! @retval    true - Write operation failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Write_Status_Register( U8 u8_StatusRegister );
 
    //!-------------------------------------------------------------------------
    //! @brief     Read byte from memory.
    //! @note      None
    //! @param     [in] u32_Address - Linear address
    //! @param     [out] *u8_Data - Pointer to byte value
    //! @return    BOOL - Read operation status
    //! @retval    false - Read operation succeeded
    //! @retval    true - Read operation failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Read_Memory( U32 u32_Address, U8 *u8_Data );
 
    //!-------------------------------------------------------------------------
    //! @brief     Write byte into memory.
    //! @note      None
    //! @param     [in] u32_Address - Linear address
    //! @param     [in] u8_Data - Data byte value to write
    //! @return    BOOL - Write operation status
    //! @retval    false - Write operation succeeded
    //! @retval    true - Write operation failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Write_Memory( U32 u32_Address, U8 u8_Data );
 
    //!-------------------------------------------------------------------------
    //! @brief     Read memory device identification information pure virtual method.
    //! @note      None
    //! @return    None
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    virtual BOOL Read_Identification() = 0;
 
    //!-------------------------------------------------------------------------
    //! @brief     This method check that relative index is valid
    //! @note      None
    //! @param     [in] u16_Page_Relative_Index - Relative index
    //! @return    BOOL - Operation status
    //! @retval    false - Verification succeeded
    //! @retval    true - Operation failed, verification failed
    //! \par       Override
    //!            Requered
    //! @attention None
    //--------------------------------------------------------------------------
 
    BOOL Is_Page_Relative_Index_In_Range( U16 u16_Page_Relative_Index );
 
};
 
//------------------------------------------------------------------------------
// End of file
//------------------------------------------------------------------------------