AM261x MCU+ SDK: APIs for FLASH

| AM261x MCU+ SDK 26.00.00 |

Data Structures | Functions | Typedefs
APIs for FLASH
APIs for Board Specific Device Drivers

## Introduction

This module contains APIs to program and use the Flash module on the board like XSPI NOR Flash. See Flash for more details.

## Data Structures
struct | Flash_NandConfig
| Flash device config. This will be part of the flash config, so has to be filled by sysconfig or otherwise before invoking Flash_open. More...
struct | Flash_DevConfig
struct | Flash_Params
| Parameters passed during Flash_open() More...
struct | Flash_Fxns
| Driver implementation callbacks. More...
struct | Flash_Attrs
| Flash device attributes, these are filled by SysCfg based on the flash device that is selected. More...
struct | Flash_Config
| Flash driver configuration, these are filled by SysCfg based on the flash device that is selected. More...

## Functions
void | Flash_Params_init (Flash_Params *params)
| Set default parameters in the Flash_Params structure. More...
Flash_Handle | Flash_open (uint32_t instanceId, Flash_Params *params)
| Open flash driver. More...
void | Flash_close (Flash_Handle handle)
| Close flash driver. More...
Flash_Handle | Flash_getHandle (uint32_t instanceId)
| Get handle to flash driver. More...
int32_t | Flash_read (Flash_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| Read data from flash. More...
int32_t | Flash_write (Flash_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| Write to flash. More...
int32_t | Flash_blkPageToOffset (Flash_Handle handle, uint32_t *offset, uint32_t block, uint32_t page)
| Utility API to convert (Block Num, Page Num) to offset in bytes. More...
int32_t | Flash_offsetToBlkPage (Flash_Handle handle, uint32_t offset, uint32_t *block, uint32_t *page)
| Utility API to convert offset in bytes to (Block Num, Page Num) More...
int32_t | Flash_SectorPageToOffset (Flash_Handle handle, uint32_t *offset, uint32_t sector, uint32_t page)
| Utility API to convert (Sector Num, Page Num) to offset in bytes. More...
int32_t | Flash_offsetToSectorPage (Flash_Handle handle, uint32_t offset, uint32_t *sector, uint32_t *page)
| Utility API to convert offset in bytes to (Sector Num, Page Num) More...
int32_t | Flash_eraseBlk (Flash_Handle handle, uint32_t blockNum)
| Erase a block from flash. More...
int32_t | Flash_eraseSector (Flash_Handle handle, uint32_t sectorNum)
| Erase a sector from flash. More...
int32_t | Flash_reset (Flash_Handle handle)
| Do a soft reset of the flash. More...
int32_t | Flash_enableDacMode (Flash_Handle handle)
| Enables DAC mode in flash. More...
int32_t | Flash_disableDacMode (Flash_Handle handle)
| Disable DAC mode in flash. More...
uint32_t | Flash_getPhyTuningOffset (Flash_Handle handle)
| Return flash offset to write PHY tuning data. More...
Flash_Attrs * | Flash_getAttrs (uint32_t instanceId)
| Return flash attributes. More...
int32_t | Flash_phyTune (Flash_Handle handle)
| Tunes the flash controller physical layer parameters. More...

## Typedefs
typedef void * | Flash_Handle
| Handle to the FLash driver returned by Flash_opem() More...
typedef struct Flash_Config_s | Flash_Config
| Forward declaration of Flash_Config. More...
typedef struct Flash_Params_s | Flash_Params
| Forward declaration of Flash_Params. More...

## Flash driver implementation callbacks
typedef int32_t(* | Flash_OpenFxn) (Flash_Config *config, Flash_Params *params)
| Driver implementation to open a specific flash driver. More...
typedef void(* | Flash_CloseFxn) (Flash_Config *config)
| Driver implementation to close a specific flash driver. More...
typedef int32_t(* | Flash_ReadFxn) (Flash_Config *config, uint32_t offset, uint8_t *buf, uint32_t len)
| Driver implementation to read from flash using a specific flash driver. More...
typedef int32_t(* | Flash_WriteFxn) (Flash_Config *config, uint32_t offset, uint8_t *buf, uint32_t len)
| Driver implementation to write to flash using specific flash driver. More...
typedef int32_t(* | Flash_EraseFxn) (Flash_Config *config, uint32_t blockNum)
| Driver implementation to erase a block using a specific flash driver. More...
typedef int32_t(* | Flash_EraseSectorFxn) (Flash_Config *config, uint32_t sectorNum)
| Driver implementation to erase a sector using a specific flash driver. More...
typedef int32_t(* | Flash_ResetFxn) (Flash_Config *config)
| Driver implementation to soft reset the flash. More...
typedef int32_t(* | Flash_EnableDacModeFxn) (Flash_Config *config)
| Driver implementation to enable DAC mode in Flash. More...
typedef int32_t(* | Flash_DisableDacModeFxn) (Flash_Config *config)
| Driver implementation to enable DAC mode in Flash. More...
typedef int32_t(* | Flash_quirksFxn) (Flash_Config *config)
| User implementation of a custom function to handle vendor specific quirks. More...
typedef int32_t(* | Flash_custProtocolFxn) (Flash_Config *config)
| User implementation of a custom function to configure flash to operate in a specific protocol. More...
typedef int32_t(* | Flash_phyTuneFxn) (Flash_Config *confifg)
| Driver implementation to perform phy tune flash. More...

## Typedef Documentation

## ◆ Flash_Handle

typedef void* Flash_Handle

Handle to the FLash driver returned by Flash_opem()

## ◆ Flash_Config

typedef struct Flash_Config_s Flash_Config

Forward declaration of Flash_Config.

## ◆ Flash_Params

typedef struct Flash_Params_s Flash_Params

Forward declaration of Flash_Params.

## ◆ Flash_OpenFxn

typedef int32_t(* Flash_OpenFxn) (Flash_Config *config, Flash_Params *params)

Driver implementation to open a specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device
  params | [in] User controllable parameters when opening the flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_CloseFxn

typedef void(* Flash_CloseFxn) (Flash_Config *config)

Driver implementation to close a specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_ReadFxn

typedef int32_t(* Flash_ReadFxn) (Flash_Config *config, uint32_t offset, uint8_t *buf, uint32_t len)

Driver implementation to read from flash using a specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device
  offset | [in] Offset in the flash from where to start the read
  buf | [in] Buffer into which to read the data into
  len | [in] Length of the data to read, in bytes

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_WriteFxn

typedef int32_t(* Flash_WriteFxn) (Flash_Config *config, uint32_t offset, uint8_t *buf, uint32_t len)

Driver implementation to write to flash using specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device
  offset | [in] Offset in the flash from where to start the write.
  buf | [in] Buffer which has the data to write.
  len | [in] Length of the data to write, in bytes

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_EraseFxn

typedef int32_t(* Flash_EraseFxn) (Flash_Config *config, uint32_t blockNum)

Driver implementation to erase a block using a specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device
  blockNum | [in] Block number to erase.

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_EraseSectorFxn

typedef int32_t(* Flash_EraseSectorFxn) (Flash_Config *config, uint32_t sectorNum)

Driver implementation to erase a sector using a specific flash driver.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device
  sectorNum | [in] Sector number to erase.

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_ResetFxn

typedef int32_t(* Flash_ResetFxn) (Flash_Config *config)

Driver implementation to soft reset the flash.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_EnableDacModeFxn

typedef int32_t(* Flash_EnableDacModeFxn) (Flash_Config *config)

Driver implementation to enable DAC mode in Flash.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_DisableDacModeFxn

typedef int32_t(* Flash_DisableDacModeFxn) (Flash_Config *config)

Driver implementation to enable DAC mode in Flash.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_quirksFxn

typedef int32_t(* Flash_quirksFxn) (Flash_Config *config)

User implementation of a custom function to handle vendor specific quirks.

Typically this callback is hidden from the end application and is implemented when a new type of flash device needs to be implemented.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_custProtocolFxn

typedef int32_t(* Flash_custProtocolFxn) (Flash_Config *config)

User implementation of a custom function to configure flash to operate in a specific protocol.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_phyTuneFxn

typedef int32_t(* Flash_phyTuneFxn) (Flash_Config *confifg)

Driver implementation to perform phy tune flash.

Parameters

  config | [in] Flash configuration for the specific flash device

Returns
  SystemP_SUCCESS on success, else failure

## Function Documentation

## ◆ Flash_Params_init()

void Flash_Params_init | ( | Flash_Params * | params | ) |

Set default parameters in the Flash_Params structure.

Call this API to set defaults and then override the fields as needed before calling Flash_open.

Parameters

  params | [out] Initialized parameters

## ◆ Flash_open()

Flash_Handle Flash_open | ( | uint32_t | instanceId,
|  | Flash_Params * | params
| ) |  |

Open flash driver.

Make sure the SOC peripheral driver is opened before calling this API. Drivers_open function generated by SysCfg opens the underlying SOC peripheral driver, e.g OSPI.

Internally this API also reads the device and manufacture ID and checks if it matches the expected value for the flash device, if there is mismatch then `NULL` is returned.

Global variables `Flash_Config gFlashConfig[]` and `uint32_t gFlashConfigNum` is instantiated by SysCfg to describe the flash configuration based on user selection in SysCfg.

Parameters

  instanceId | [in] Index within `Flash_Config gFlashConfig[]` denoting the flash driver to open
  params | [in] Open parameters

Returns
  Handle to flash driver which should be used in subsequent API call
  NULL in case of failure

## ◆ Flash_close()

void Flash_close | ( | Flash_Handle | handle | ) |

Close flash driver.

Parameters

  handle | [in] Flash driver handle from Flash_open

## ◆ Flash_getHandle()

Flash_Handle Flash_getHandle | ( | uint32_t | instanceId | ) |

Get handle to flash driver.

Parameters

  instanceId | [in] Index within `Flash_Config gFlashConfig[]`

Returns
  Handle to flash driver
  NULL in case of failure

## ◆ Flash_read()

int32_t Flash_read | ( | Flash_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

Read data from flash.

Internally it will use DMA and do the needed cache sync operations as needed.

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [in] Offset in the flash from where to start the read
  buf | [in] Buffer into which to read the data into
  len | [in] Length of the data to read, in bytes

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_write()

int32_t Flash_write | ( | Flash_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

Write to flash.

Make sure the block is erased before writing

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [in] Offset in the flash from where to start the write.
  buf | [in] Buffer which has the data to write.
  len | [in] Length of the data to write, in bytes

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_blkPageToOffset()

int32_t Flash_blkPageToOffset | ( | Flash_Handle | handle,
|  | uint32_t * | offset,
|  | uint32_t | block,
|  | uint32_t | page
| ) |  |

Utility API to convert (Block Num, Page Num) to offset in bytes.

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [out] Offset in the flash, in bytes.
  block | [in] Block number to convert
  page | [in] Page number within the block

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_offsetToBlkPage()

int32_t Flash_offsetToBlkPage | ( | Flash_Handle | handle,
|  | uint32_t | offset,
|  | uint32_t * | block,
|  | uint32_t * | page
| ) |  |

Utility API to convert offset in bytes to (Block Num, Page Num)

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [in] Offset in the flash, in bytes. MUST be page size aligned.
  block | [out] Converted Block number
  page | [out] Converted Page number within the block

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_SectorPageToOffset()

int32_t Flash_SectorPageToOffset | ( | Flash_Handle | handle,
|  | uint32_t * | offset,
|  | uint32_t | sector,
|  | uint32_t | page
| ) |  |

Utility API to convert (Sector Num, Page Num) to offset in bytes.

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [out] Offset in the flash, in bytes.
  sector | [in] Sector number to convert
  page | [in] Page number within the block

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_offsetToSectorPage()

int32_t Flash_offsetToSectorPage | ( | Flash_Handle | handle,
|  | uint32_t | offset,
|  | uint32_t * | sector,
|  | uint32_t * | page
| ) |  |

Utility API to convert offset in bytes to (Sector Num, Page Num)

Parameters

  handle | [in] Flash driver handle from Flash_open
  offset | [in] Offset in the flash, in bytes. MUST be page size aligned.
  sector | [out] Converted sector number
  page | [out] Converted Page number within the block

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_eraseBlk()

int32_t Flash_eraseBlk | ( | Flash_Handle | handle,
|  | uint32_t | blockNum
| ) |  |

Erase a block from flash.

Use the utility API Flash_offsetToBlkPage to convert a offset to block number

Parameters

  handle | [in] Flash driver handle from Flash_open
  blockNum | [in] Block number to erase.

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_eraseSector()

int32_t Flash_eraseSector | ( | Flash_Handle | handle,
|  | uint32_t | sectorNum
| ) |  |

Erase a sector from flash.

Use the utility API Flash_offsetToSectorPage to convert a offset to block number

Parameters

  handle | [in] Flash driver handle from Flash_open
  sectorNum | [in] Sector number to erase.

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_reset()

int32_t Flash_reset | ( | Flash_Handle | handle | ) |

Do a soft reset of the flash.

Parameters

  handle | [in] Flash driver handle from Flash_open

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_enableDacMode()

int32_t Flash_enableDacMode | ( | Flash_Handle | handle | ) |

Enables DAC mode in flash.

Parameters

  handle | [in] Flash driver handle from Flash_open

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_disableDacMode()

int32_t Flash_disableDacMode | ( | Flash_Handle | handle | ) |

Disable DAC mode in flash.

Parameters

  handle | [in] Flash driver handle from Flash_open

Returns
  SystemP_SUCCESS on success, else failure

## ◆ Flash_getPhyTuningOffset()

uint32_t Flash_getPhyTuningOffset | ( | Flash_Handle | handle | ) |

Return flash offset to write PHY tuning data.

Parameters

  handle | [in] Flash driver handle from Flash_open

Returns
  Tuning offset on SUCCESS, else 0xFFFFFFFF if handle is invalid

## ◆ Flash_getAttrs()

Flash_Attrs* Flash_getAttrs | ( | uint32_t | instanceId | ) |

Return flash attributes.

Parameters

  instanceId | [in] Flash instance ID

Returns
  Flash_Attrs, else NULL if instanceId is invalid

## ◆ Flash_phyTune()

int32_t Flash_phyTune | ( | Flash_Handle | handle | ) |

Tunes the flash controller physical layer parameters.

Parameters

  handle | The flash controller handle

Returns
  SystemP_SUCCESS on success, else failure