apps/flash_driver_api/src/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_

#include <stdint.h>

/*******************************************************************************
 * 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(kStatusGroup_FLASH)
#define kStatusGroupGeneric kStatusGroup_Generic
#define kStatusGroupFlashDriver kStatusGroup_FLASH
#define IS_GENERIC_STAUS_CODE_DEFINED 1
#else
#define kStatusGroupGeneric 0
#define kStatusGroupFlashDriver 1
#define IS_GENERIC_STAUS_CODE_DEFINED 0
#endif

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

typedef int32_t status_t;

#if !(IS_GENERIC_STAUS_CODE_DEFINED)
enum _generic_status
{
    kStatus_Success = MAKE_STATUS(kStatusGroupGeneric, 0),
    kStatus_Fail = MAKE_STATUS(kStatusGroupGeneric, 1),
    kStatus_ReadOnly = MAKE_STATUS(kStatusGroupGeneric, 2),
    kStatus_OutOfRange = MAKE_STATUS(kStatusGroupGeneric, 3),
    kStatus_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4)
};
#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,          
    kFLASH_PropertyVersion = 0x20U, 
} 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;

typedef void (*flash_callback_t)(void);

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);

status_t FLASH_PrepareExecuteInRamFunctions(flash_config_t *config);

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);

status_t FLASH_EraseAllUnsecure(flash_config_t *config, uint32_t key);
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);
status_t FLASH_ReadResource(
    flash_config_t *config, uint32_t start, uint32_t *dst, uint32_t lengthInBytes, flash_read_resource_option_t option);

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_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(__cplusplus)
}
#endif

#endif /* _FSL_FLASH_H_ */