AM263Px MCU+ SDK: APIs for FLSOPSKD

| AM263Px MCU+ SDK 26.00.00 |

Data Structures | Functions | Macros
APIs for FLSOPSKD
APIs for SOC Specific Device Drivers

## Introduction

This module contains APIs for FLSOPSKD. FLSOPSKD stands for **FL**ash **OP**erations Scheduler (SKD)

FLSOPSKD is name given to 8051 controller that sits close to external flash controller (OSPI Controller) and monitors the traffic on the data bus. When there is no traffic on the OSPI data bus, 8051 will place the flash command on the bus.

## Data Structures
struct | FLSOPSKD_Params
struct | FLSOPSKD_Handle

## Functions
uint32_t | FLSOPSKD_usrGetTicks ()
| User defined getTicks function. More...
int32_t | FLSOPSKD_Params_init (FLSOPSKD_Params *pParams)
| Init all params. More...
int32_t | FLSOPSKD_init (FLSOPSKD_Handle *pHandle, FLSOPSKD_Params *pParams)
| Init the FLSOPSKD IP and driver. More...
int32_t | FLSOPSKD_write (FLSOPSKD_Handle *pHandle, uint32_t destAddr, uint8_t *pSrcBuffer, uint32_t bytesToWrite)
| Sends write scheduling request to hardware IP. More...
int32_t | FLSOPSKD_erase (FLSOPSKD_Handle *pHandle, uint32_t eraseOffsetInBytes)
| Send erase scheduling request. More...
int32_t | FLSOPSKD_getFwVersion (FLSOPSKD_Handle *pHandle, volatile uint32_t *pVersion)
| Get Firmware version. More...
int32_t | FLSOPSKD_busyPoll (FLSOPSKD_Handle *pHandle)
| Wait till controller is busy. More...
int32_t | FLSOPSKD_perfGetDowntime (FLSOPSKD_Handle *pHandle, uint32_t *memLoc)
| Get XIP downtime of last operation. More...
int32_t | FLSOPSKD_perfGetPollCounts (FLSOPSKD_Handle *pHandle, uint32_t *memLoc)
| Get Busy poll status count. More...
int32_t | FLSOPSKD_deinit (FLSOPSKD_Handle *pHandle)
| Deinit Handle. More...

## Macros
#define | FLSOPSKD_EXPECTED_FW_VERSION (0x10000U)
| The version number that this driver expects from the firmware running in 8051. More...

## Macro Definition Documentation

## ◆ FLSOPSKD_EXPECTED_FW_VERSION

#define FLSOPSKD_EXPECTED_FW_VERSION (0x10000U)

The version number that this driver expects from the firmware running in 8051.

It is good practice to get the firmware version from 8051 and check if it is equal to this macro.

## Function Documentation

## ◆ FLSOPSKD_usrGetTicks()

uint32_t FLSOPSKD_usrGetTicks | ( |  | ) |

User defined getTicks function.

User should define this function in their applicaiton.

Returns
  system ticks

## ◆ FLSOPSKD_Params_init()

int32_t FLSOPSKD_Params_init | ( | FLSOPSKD_Params * | pParams | ) |

Init all params.

Use this function to initilize the parameters. if FLSOPSKD_Params.pageSizeInBytes is 0 then this function sets it to 256. if FLSOPSKD_Params.eraseSizeInBytes is 0 then this function sets it to 4096. if FLSOPSKD_Params.eraseOpCode is 0 then this function sets it to 0x21. if FLSOPSKD_Params.eraseExOpCode is 0 then this function sets it to 0x21. FLSOPSKD_Params.pollTimeout is set to 1000.

Parameters

  pParams | pointer to FLSOPSKD_Params struct

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_init()

int32_t FLSOPSKD_init | ( | FLSOPSKD_Handle * | pHandle,
|  | FLSOPSKD_Params * | pParams
| ) |  |

Init the FLSOPSKD IP and driver.

FLSOPSKD IP is initilized by following procedure:

1. Put 8051 in reset state
2. Enable and initilize 8051 memory
   1. This step consist of enabling R5F access to 8051 code and data access.
   2. wait for memory to finish initilization
3. Load 8051 firmware in the 8051 code/data memory.
4. Disable R5F access to 8051 memories to avoid unintentional modification of 8051 firmware.
5. Enable required interrupts in the IP and R5F.
6. Lift 8051 from reset

Most of the flash paramter are taken from the OSPI IP. However, some other parameter of external flash are not save in the OSPI IP and those needs to be save in the RAM. eraseOpCode and eraseExOpCode are such flash parameters and all of these parameters are in pParams.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  pParams | pointer to FLSOPSKD_Params Object.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_write()

int32_t FLSOPSKD_write | ( | FLSOPSKD_Handle * | pHandle,
|  | uint32_t | destAddr,
|  | uint8_t * | pSrcBuffer,
|  | uint32_t | bytesToWrite
| ) |  |

Sends write scheduling request to hardware IP.

This function will schedule a write command to the flash and sends that command as soon as the OSPI Bus is free. After M8051 sends the write command, it also polls for the completion of write. Completion of write is logically determined by the `m8051 done` interrupt which is set only after the WIP bit of the external flash is not active.

SOC memory-map maps flash to some address space, for example, 0x60000000 and suppose application wants to write to 0x60000000 + 1MB = 0x60100000. In this case, destAddr should be 0x100000 and not 0x60100000.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  destAddr | [in] Flash address to which to write this buffer
  pSrcBuffer | [in] pointer to source buffer
  bytesToWrite | [in] size of the buffer to write

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_erase()

int32_t FLSOPSKD_erase | ( | FLSOPSKD_Handle * | pHandle,
|  | uint32_t | eraseOffsetInBytes
| ) |  |

Send erase scheduling request.

This function schedules erase command and sends it to the flash as soon as the OSPI lines are free. This function also polls by sending the status check commands and if polling is enabled then will only return when the flash WIP bit is not active.

The command which is sent to the external flash requries a field called address. This field specifies the sector/block which is to be erased. Depending on flash, its value can be constraint. Value of that field is sent via eraseOffsetInBytes argument.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  eraseOffsetInBytes | [in] block offset in bytes.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_getFwVersion()

int32_t FLSOPSKD_getFwVersion | ( | FLSOPSKD_Handle * | pHandle,
|  | volatile uint32_t * | pVersion
| ) |  |

Get Firmware version.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  pVersion | [out] pointer to memory to save version info.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_busyPoll()

int32_t FLSOPSKD_busyPoll | ( | FLSOPSKD_Handle * | pHandle | ) |

Wait till controller is busy.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_perfGetDowntime()

int32_t FLSOPSKD_perfGetDowntime | ( | FLSOPSKD_Handle * | pHandle,
|  | uint32_t * | memLoc
| ) |  |

Get XIP downtime of last operation.

Each Flash operation cause some downtime of XIP. After operation is complete, the FLSOPSKD firmware returns the worst case XIP downtime that application can expect out of the last operation. This function returns the XIP downtime.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  memLoc | [out] pointer to location to write the downtime.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_perfGetPollCounts()

int32_t FLSOPSKD_perfGetPollCounts | ( | FLSOPSKD_Handle * | pHandle,
|  | uint32_t * | memLoc
| ) |  |

Get Busy poll status count.

After sending any erase or write operation, FLSOPSKD operation also sends status operation. After the operation is complete, the number of status polls sent is returned.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.
  memLoc | [out] pointer to location to write polls count.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS

## ◆ FLSOPSKD_deinit()

int32_t FLSOPSKD_deinit | ( | FLSOPSKD_Handle * | pHandle | ) |

Deinit Handle.

Parameters

  pHandle | [in] pointer to FLSOPSKD_Handle instance.

Returns
  SystemP_FAILURE
  SystemP_SUCCESS