src/drivers/flash/fsl_flash.h

/*
 * Copyright (c) 2013-2016, Freescale Semiconductor, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o 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.
 *
 * o Neither the name of Freescale Semiconductor, Inc. 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.
 */

#ifndef _FSL_FLASH_H_
#define _FSL_FLASH_H_

#if (defined(BL_TARGET_FLASH) || defined(BL_TARGET_ROM) || defined(BL_TARGET_RAM))
#include <assert.h>
#include <string.h>
#include "fsl_device_registers.h"
#include "bootloader_common.h"
#else
#include "fsl_common.h"
#endif

/*******************************************************************************
 * Definitions
 ******************************************************************************/

#if !defined(MAKE_VERSION)
#define MAKE_VERSION(major, minor, bugfix) (((major) << 16) | ((minor) << 8) | (bugfix))
#endif

#define FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(2, 1, 0)) 
enum _flash_driver_version_constants
{
    kFLASH_DriverVersionName = 'F', 
    kFLASH_DriverVersionMajor = 2,  
    kFLASH_DriverVersionMinor = 1,  
    kFLASH_DriverVersionBugfix = 0  
};
#if !defined(FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT)
#define FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT 1 
#endif

#define FLASH_SSD_IS_FLEXNVM_ENABLED (FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT && FSL_FEATURE_FLASH_HAS_FLEX_NVM)

#if !defined(FLASH_DRIVER_IS_FLASH_RESIDENT)
#if (!defined(BL_TARGET_ROM) && !defined(BL_TARGET_RAM))
#define FLASH_DRIVER_IS_FLASH_RESIDENT 1 
#else
#define FLASH_DRIVER_IS_FLASH_RESIDENT 0 
#endif
#endif

#if !defined(FLASH_DRIVER_IS_EXPORTED)
#if (defined(BL_TARGET_ROM) || defined(BL_TARGET_FLASH))
#define FLASH_DRIVER_IS_EXPORTED 1 
#else
#define FLASH_DRIVER_IS_EXPORTED 0 
#endif
#endif

#if defined(kStatusGroup_FlashDriver)
#define kStatusGroupGeneric kStatusGroup_Generic
#define kStatusGroupFlashDriver kStatusGroup_FlashDriver
#elif defined(kStatusGroup_FLASH)
#define kStatusGroupGeneric kStatusGroup_Generic
#define kStatusGroupFlashDriver kStatusGroup_FLASH
#else
#define kStatusGroupGeneric 0
#define kStatusGroupFlashDriver 1
#endif

#if !defined(MAKE_STATUS)
#define MAKE_STATUS(group, code) ((((group)*100) + (code)))
#endif

enum _flash_status
{
    kStatus_FLASH_Success = MAKE_STATUS(kStatusGroupGeneric, 0),         
    kStatus_FLASH_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4), 
    kStatus_FLASH_SizeError = MAKE_STATUS(kStatusGroupFlashDriver, 0),   
    kStatus_FLASH_AlignmentError =
        MAKE_STATUS(kStatusGroupFlashDriver, 1), 
    kStatus_FLASH_AddressError = MAKE_STATUS(kStatusGroupFlashDriver, 2), 
    kStatus_FLASH_AccessError =
        MAKE_STATUS(kStatusGroupFlashDriver, 3), 
    kStatus_FLASH_ProtectionViolation = MAKE_STATUS(
        kStatusGroupFlashDriver, 4), 
    kStatus_FLASH_CommandFailure =
        MAKE_STATUS(kStatusGroupFlashDriver, 5), 
    kStatus_FLASH_UnknownProperty = MAKE_STATUS(kStatusGroupFlashDriver, 6),   
    kStatus_FLASH_EraseKeyError = MAKE_STATUS(kStatusGroupFlashDriver, 7),     
    kStatus_FLASH_RegionExecuteOnly = MAKE_STATUS(kStatusGroupFlashDriver, 8), 
    kStatus_FLASH_ExecuteInRamFunctionNotReady =
        MAKE_STATUS(kStatusGroupFlashDriver, 9), 
    kStatus_FLASH_PartitionStatusUpdateFailure =
        MAKE_STATUS(kStatusGroupFlashDriver, 10), 
    kStatus_FLASH_SetFlexramAsEepromError =
        MAKE_STATUS(kStatusGroupFlashDriver, 11), 
    kStatus_FLASH_RecoverFlexramAsRamError =
        MAKE_STATUS(kStatusGroupFlashDriver, 12), 
    kStatus_FLASH_SetFlexramAsRamError = MAKE_STATUS(kStatusGroupFlashDriver, 13), 
    kStatus_FLASH_RecoverFlexramAsEepromError =
        MAKE_STATUS(kStatusGroupFlashDriver, 14), 
    kStatus_FLASH_CommandNotSupported = MAKE_STATUS(kStatusGroupFlashDriver, 15), 
    kStatus_FLASH_SwapSystemNotInUninitialized =
        MAKE_STATUS(kStatusGroupFlashDriver, 16), 
    kStatus_FLASH_SwapIndicatorAddressError =
        MAKE_STATUS(kStatusGroupFlashDriver, 17), 
};
#if !defined(FOUR_CHAR_CODE)
#define FOUR_CHAR_CODE(a, b, c, d) (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a)))
#endif

enum _flash_driver_api_keys
{
    kFLASH_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') 
};
typedef enum _flash_margin_value
{
    kFLASH_MarginValueNormal,  
    kFLASH_MarginValueUser,    
    kFLASH_MarginValueFactory, 
    kFLASH_MarginValueInvalid  
} flash_margin_value_t;

typedef enum _flash_security_state
{
    kFLASH_SecurityStateNotSecure,       
    kFLASH_SecurityStateBackdoorEnabled, 
    kFLASH_SecurityStateBackdoorDisabled 
} flash_security_state_t;

typedef enum _flash_protection_state
{
    kFLASH_ProtectionStateUnprotected, 
    kFLASH_ProtectionStateProtected,   
    kFLASH_ProtectionStateMixed        
} flash_protection_state_t;

typedef enum _flash_execute_only_access_state
{
    kFLASH_AccessStateUnLimited,   
    kFLASH_AccessStateExecuteOnly, 
    kFLASH_AccessStateMixed        
} flash_execute_only_access_state_t;

typedef enum _flash_property_tag
{
    kFLASH_PropertyPflashSectorSize = 0x00U,         
    kFLASH_PropertyPflashTotalSize = 0x01U,          
    kFLASH_PropertyPflashBlockSize = 0x02U,          
    kFLASH_PropertyPflashBlockCount = 0x03U,         
    kFLASH_PropertyPflashBlockBaseAddr = 0x04U,      
    kFLASH_PropertyPflashFacSupport = 0x05U,         
    kFLASH_PropertyPflashAccessSegmentSize = 0x06U,  
    kFLASH_PropertyPflashAccessSegmentCount = 0x07U, 
    kFLASH_PropertyFlexRamBlockBaseAddr = 0x08U,     
    kFLASH_PropertyFlexRamTotalSize = 0x09U,         
    kFLASH_PropertyDflashSectorSize = 0x10U,         
    kFLASH_PropertyDflashTotalSize = 0x11U,          
    kFLASH_PropertyDflashBlockSize = 0x12U,          
    kFLASH_PropertyDflashBlockCount = 0x13U,         
    kFLASH_PropertyDflashBlockBaseAddr = 0x14U,      
    kFLASH_PropertyEepromTotalSize = 0x15U
} flash_property_tag_t;

enum _flash_execute_in_ram_function_constants
{
    kFLASH_ExecuteInRamFunctionMaxSize = 64U, 
    kFLASH_ExecuteInRamFunctionTotalNum = 2U  
};

typedef struct _flash_execute_in_ram_function_config
{
    uint32_t activeFunctionCount;    
    uint8_t *flashRunCommand;        
    uint8_t *flashCacheClearCommand; 
} flash_execute_in_ram_function_config_t;

typedef enum _flash_read_resource_option
{
    kFLASH_ResourceOptionFlashIfr =
        0x00U, 
    kFLASH_ResourceOptionVersionId = 0x01U 
} flash_read_resource_option_t;

enum _flash_read_resource_range
{
#if (FSL_FEATURE_FLASH_IS_FTFE == 1)
    kFLASH_ResourceRangePflashIfrSizeInBytes = 1024U,  
    kFLASH_ResourceRangeVersionIdSizeInBytes = 8U,     
    kFLASH_ResourceRangeVersionIdStart = 0x08U,        
    kFLASH_ResourceRangeVersionIdEnd = 0x0FU,          
    kFLASH_ResourceRangePflashSwapIfrStart = 0x40000U, 
    kFLASH_ResourceRangePflashSwapIfrEnd =
        (kFLASH_ResourceRangePflashSwapIfrStart + 0x3FFU), 
#else                                                      /* FSL_FEATURE_FLASH_IS_FTFL == 1 or FSL_FEATURE_FLASH_IS_FTFA = =1 */
    kFLASH_ResourceRangePflashIfrSizeInBytes = 256U,  
    kFLASH_ResourceRangeVersionIdSizeInBytes = 8U,    
    kFLASH_ResourceRangeVersionIdStart = 0x00U,       
    kFLASH_ResourceRangeVersionIdEnd = 0x07U,         
#if 0x20000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE)
    kFLASH_ResourceRangePflashSwapIfrStart = 0x8000U, 
#elif 0x40000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE)
    kFLASH_ResourceRangePflashSwapIfrStart = 0x10000U, 
#elif 0x80000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE)
    kFLASH_ResourceRangePflashSwapIfrStart = 0x20000U, 
#else
    kFLASH_ResourceRangePflashSwapIfrStart = 0,
#endif
    kFLASH_ResourceRangePflashSwapIfrEnd =
        (kFLASH_ResourceRangePflashSwapIfrStart + 0xFFU), 
#endif
    kFLASH_ResourceRangeDflashIfrStart = 0x800000U, 
    kFLASH_ResourceRangeDflashIfrEnd = 0x8003FFU,   
};

typedef enum _flash_flexram_function_option
{
    kFLASH_FlexramFunctionOptionAvailableAsRam = 0xFFU,    
    kFLASH_FlexramFunctionOptionAvailableForEeprom = 0x00U 
} flash_flexram_function_option_t;

enum _flash_acceleration_ram_property
{
    kFLASH_AccelerationRamSize = 0x400U
};

typedef enum _flash_swap_function_option
{
    kFLASH_SwapFunctionOptionEnable = 0x00U, 
    kFLASH_SwapFunctionOptionDisable = 0x01U 
} flash_swap_function_option_t;

typedef enum _flash_swap_control_option
{
    kFLASH_SwapControlOptionIntializeSystem = 0x01U,    
    kFLASH_SwapControlOptionSetInUpdateState = 0x02U,   
    kFLASH_SwapControlOptionSetInCompleteState = 0x04U, 
    kFLASH_SwapControlOptionReportStatus = 0x08U,       
    kFLASH_SwapControlOptionDisableSystem = 0x10U       
} flash_swap_control_option_t;

typedef enum _flash_swap_state
{
    kFLASH_SwapStateUninitialized = 0x00U, 
    kFLASH_SwapStateReady = 0x01U,         
    kFLASH_SwapStateUpdate = 0x02U,        
    kFLASH_SwapStateUpdateErased = 0x03U,  
    kFLASH_SwapStateComplete = 0x04U,      
    kFLASH_SwapStateDisabled = 0x05U       
} flash_swap_state_t;

typedef enum _flash_swap_block_status
{
    kFLASH_SwapBlockStatusLowerHalfProgramBlocksAtZero =
        0x00U, 
    kFLASH_SwapBlockStatusUpperHalfProgramBlocksAtZero =
        0x01U, 
} flash_swap_block_status_t;

typedef struct _flash_swap_state_config
{
    flash_swap_state_t flashSwapState;                
    flash_swap_block_status_t currentSwapBlockStatus; 
    flash_swap_block_status_t nextSwapBlockStatus;    
} flash_swap_state_config_t;

typedef struct _flash_swap_ifr_field_config
{
    uint16_t swapIndicatorAddress; 
    uint16_t swapEnableWord;       
    uint8_t reserved0[4];          
#if (FSL_FEATURE_FLASH_IS_FTFE == 1)
    uint8_t reserved1[2];     
    uint16_t swapDisableWord; 
    uint8_t reserved2[4];     
#endif
} flash_swap_ifr_field_config_t;

typedef union _flash_swap_ifr_field_data
{
    uint32_t flashSwapIfrData[2];                    
    flash_swap_ifr_field_config_t flashSwapIfrField; 
} flash_swap_ifr_field_data_t;

typedef enum _flash_partition_flexram_load_option
{
    kFLASH_PartitionFlexramLoadOptionLoadedWithValidEepromData =
        0x00U, 
    kFLASH_PartitionFlexramLoadOptionNotLoaded = 0x01U 
} flash_partition_flexram_load_option_t;

typedef void (*flash_callback_t)(void);

typedef struct _flash_operation_config
{
    uint32_t convertedAddress;           
    uint32_t activeSectorSize;           
    uint32_t activeBlockSize;            
    uint32_t blockWriteUnitSize;         
    uint32_t sectorCmdAddressAligment;   
    uint32_t sectionCmdAddressAligment;  
    uint32_t resourceCmdAddressAligment; 
    uint32_t checkCmdAddressAligment;    
} flash_operation_config_t;

typedef struct _flash_config
{
    uint32_t PFlashBlockBase;                
    uint32_t PFlashTotalSize;                
    uint32_t PFlashBlockCount;               
    uint32_t PFlashSectorSize;               
    flash_callback_t PFlashCallback;         
    uint32_t PFlashAccessSegmentSize;        
    uint32_t PFlashAccessSegmentCount;       
    uint32_t *flashExecuteInRamFunctionInfo; 
    uint32_t FlexRAMBlockBase;               
    uint32_t FlexRAMTotalSize;               
    uint32_t DFlashBlockBase; 
    uint32_t DFlashTotalSize; 
    uint32_t EEpromTotalSize; 
} flash_config_t;

/*******************************************************************************
 * API
 ******************************************************************************/

#if defined(__cplusplus)
extern "C" {
#endif

status_t FLASH_Init(flash_config_t *config);

status_t FLASH_SetCallback(flash_config_t *config, flash_callback_t callback);

#if FLASH_DRIVER_IS_FLASH_RESIDENT
status_t FLASH_PrepareExecuteInRamFunctions(flash_config_t *config);
#endif

status_t FLASH_EraseAll(flash_config_t *config, uint32_t key);

status_t FLASH_Erase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key);

#if defined(FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD) && FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD
status_t FLASH_EraseAllUnsecure(flash_config_t *config, uint32_t key);
#endif

status_t FLASH_EraseAllExecuteOnlySegments(flash_config_t *config, uint32_t key);

status_t FLASH_Program(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes);

status_t FLASH_ProgramOnce(flash_config_t *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes);

#if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD
status_t FLASH_ProgramSection(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes);
#endif

#if FLASH_SSD_IS_FLEXNVM_ENABLED
status_t FLASH_EepromWrite(flash_config_t *config, uint32_t start, uint8_t *src, uint32_t lengthInBytes);
#endif

#if defined(FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD) && FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD
status_t FLASH_ReadResource(
    flash_config_t *config, uint32_t start, uint32_t *dst, uint32_t lengthInBytes, flash_read_resource_option_t option);
#endif

status_t FLASH_ReadOnce(flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes);

status_t FLASH_GetSecurityState(flash_config_t *config, flash_security_state_t *state);

status_t FLASH_SecurityBypass(flash_config_t *config, const uint8_t *backdoorKey);

status_t FLASH_VerifyEraseAll(flash_config_t *config, flash_margin_value_t margin);

status_t FLASH_VerifyErase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_margin_value_t margin);

status_t FLASH_VerifyProgram(flash_config_t *config,
                             uint32_t start,
                             uint32_t lengthInBytes,
                             const uint32_t *expectedData,
                             flash_margin_value_t margin,
                             uint32_t *failedAddress,
                             uint32_t *failedData);

status_t FLASH_VerifyEraseAllExecuteOnlySegments(flash_config_t *config, flash_margin_value_t margin);

status_t FLASH_IsProtected(flash_config_t *config,
                           uint32_t start,
                           uint32_t lengthInBytes,
                           flash_protection_state_t *protection_state);

status_t FLASH_IsExecuteOnly(flash_config_t *config,
                             uint32_t start,
                             uint32_t lengthInBytes,
                             flash_execute_only_access_state_t *access_state);

status_t FLASH_GetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value);

#if defined(FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD) && FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD
status_t FLASH_SetFlexramFunction(flash_config_t *config, flash_flexram_function_option_t option);
#endif

#if defined(FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD) && FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD
status_t FLASH_SwapControl(flash_config_t *config,
                           uint32_t address,
                           flash_swap_control_option_t option,
                           flash_swap_state_config_t *returnInfo);
#endif

#if defined(FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP) && FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP
status_t FLASH_Swap(flash_config_t *config, uint32_t address, flash_swap_function_option_t option);
#endif

#if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD
status_t FLASH_ProgramPartition(flash_config_t *config,
                                flash_partition_flexram_load_option_t option,
                                uint32_t eepromDataSizeCode,
                                uint32_t flexnvmPartitionCode);
#endif

status_t FLASH_PflashSetProtection(flash_config_t *config, uint32_t protectStatus);

status_t FLASH_PflashGetProtection(flash_config_t *config, uint32_t *protectStatus);

#if FLASH_SSD_IS_FLEXNVM_ENABLED
status_t FLASH_DflashSetProtection(flash_config_t *config, uint8_t protectStatus);
#endif

#if FLASH_SSD_IS_FLEXNVM_ENABLED
status_t FLASH_DflashGetProtection(flash_config_t *config, uint8_t *protectStatus);
#endif

#if FLASH_SSD_IS_FLEXNVM_ENABLED
status_t FLASH_EepromSetProtection(flash_config_t *config, uint8_t protectStatus);
#endif

#if FLASH_SSD_IS_FLEXNVM_ENABLED
status_t FLASH_EepromGetProtection(flash_config_t *config, uint8_t *protectStatus);
#endif

#if defined(__cplusplus)
}
#endif

#endif /* _FSL_FLASH_H_ */