AM261x MCU+ SDK: Generic NOR Flash API for single pin mode

| AM261x MCU+ SDK 26.00.00 |

Functions
Generic NOR Flash API for single pin mode
APIs for SOC Specific Device Drivers » APIs for OSPI LLD

## Introduction

These APIs try to communicate with whichever flash is connected the OSPI peripheral in 1-1-1 mode. This can be used in bringing up new flashes and mostly used for debug and diagnostic purposes

## Functions
int32_t | OSPI_lld_norFlashInit1s1s1s (OSPILLD_Handle handle)
| This function initializes the NOR flash to work in 1-1-1 mode. More...
void | OSPI_lld_norFlashSetCmds (uint8_t rdCmd, uint8_t wrCmd, uint8_t eraseCmd)
| This function sets up internal bookkeeping variables for read, write and erase commands. This API has to be called immediately before OSPI_lld_norFlashInit1s1s1s. More...
int32_t | OSPI_lld_norFlashReadId (OSPILLD_Handle handle, uint32_t *manufacturerId, uint32_t *deviceId)
| This function tries to read the JEDEC ID from the NOR flash connected to the OSPI peripheral. More...
int32_t | OSPI_lld_norFlashWrite (OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| This function writes data to the flash at a specified offset. More...
int32_t | OSPI_lld_norFlashRead (OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| This function reads data from the flash from a specified offset in DAC mode. More...
int32_t | OSPI_lld_norFlashReadIndirect (OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| This function reads data from the flash from a specified offset in INDAC mode. More...
int32_t | OSPI_lld_norFlashReadSfdp (OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len)
| This function reads SFDP table from the flash from a specified offset. More...
int32_t | OSPI_lld_norFlashErase (OSPILLD_Handle handle, uint32_t address)
| This function erases 1 block of data starting from a provided address. More...
int32_t | OSPI_lld_configResetPin (OSPILLD_Handle handle, uint32_t config)
| This function configures reset functionality. More...
int32_t | OSPI_lld_configBaudrate (OSPILLD_Handle handle, uint32_t baud)
| Configures baud divider. More...
int32_t | OSPI_lld_readBaudRateDivFromReg (OSPILLD_Handle handle, uint32_t *baudDiv)
| Return value of baudrate that is programmed in IP register. More...
int32_t | OSPI_lld_getBaudRateDivFromObj (OSPILLD_Handle handle, uint32_t *baudDiv)
| Return value of baudrate that is saved in OSPI Object. More...
int32_t | OSPI_lld_setResetPinStatus (OSPILLD_Handle hOspi, uint32_t pinStatus)
| This function activates the RESET pin feature. More...
int32_t | OSPI_dmaOpen (OSPILLD_Handle hOspi)
| API to open an OSPI DMA channel. More...
int32_t | OSPI_dmaClose (OSPILLD_Handle handle)
| API to close an OSPI DMA channel. More...
int32_t | OSPI_dmaCopy (OSPILLD_Handle handle, void *dst, void *src, uint32_t length, uint32_t timeout)
| API to do a DMA Copy using appropriate DMA Channel opened. More...
int32_t | OSPI_isDmaInterruptEnabled (OSPILLD_Handle handle)
| API to get the DMA Interrupt status. More...
int32_t | OSPI_lld_phyValidateTuningPoint (OSPILLD_Handle hOspi, uint32_t flashOffset)
| Validates a tuning point for the OSPI physical interface. More...
uint32_t | OSPI_lld_isValidateOtpEnable (OSPILLD_Handle hOspi)
| Checks if OTP validation is enabled for the OSPI controller. More...
int32_t | OSPI_lld_setFrequency (OSPILLD_Handle hOspi, uint64_t inputClkFreq)
| Sets the operating frequency for the OSPI peripheral. More...
int32_t | OSPI_lld_setDelays (OSPILLD_Handle hOspi, uint32_t inputClkFreq)
| Sets timing delays for the OSPI interface based on input clock frequency. More...
int32_t | OSPI_lld_setBaudRateDiv (OSPILLD_Handle hOspi, uint32_t baudRateDiv)
| Sets the baud rate divider for OSPI communication. More...
int32_t | OSPI_lld_disableDdrRdCmds (OSPILLD_Handle hOspi)
| This function resets DDR bit in INSTR_RD register for RD commands. More...
int32_t | OSPI_lld_set1sProtocol (OSPILLD_Handle hOspi)
| Resets the OSPI controller to operate in 1S-1S-1S mode. More...

## Function Documentation

## ◆ OSPI_lld_norFlashInit1s1s1s()

int32_t OSPI_lld_norFlashInit1s1s1s | ( | OSPILLD_Handle | handle | ) |

This function initializes the NOR flash to work in 1-1-1 mode.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashSetCmds()

void OSPI_lld_norFlashSetCmds | ( | uint8_t | rdCmd,
|  | uint8_t | wrCmd,
|  | uint8_t | eraseCmd
| ) |  |

This function sets up internal bookkeeping variables for read, write and erase commands. This API has to be called immediately before OSPI_lld_norFlashInit1s1s1s.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  rdCmd | Command to be used in single mode read
  wrCmd | Command to be used in single mode write/page program
  eraseCmd | Command to be used to erase (block or sector)

## ◆ OSPI_lld_norFlashReadId()

int32_t OSPI_lld_norFlashReadId | ( | OSPILLD_Handle | handle,
|  | uint32_t * | manufacturerId,
|  | uint32_t * | deviceId
| ) |  |

This function tries to read the JEDEC ID from the NOR flash connected to the OSPI peripheral.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  manufacturerId | Pointer to a uint32_t variable. This will be filled with the manufacturer ID on success
  deviceId | Pointer to a uint32_t variable. This will be filled with the device ID on success

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashWrite()

int32_t OSPI_lld_norFlashWrite | ( | OSPILLD_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

This function writes data to the flash at a specified offset.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  offset | Offset at which the data is to be written
  buf | Buffer which has the data to be written to the flash
  len | Number of bytes to be written to the flash

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashRead()

int32_t OSPI_lld_norFlashRead | ( | OSPILLD_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

This function reads data from the flash from a specified offset in DAC mode.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  offset | Offset at which the data is to be read from
  buf | Buffer to which data will be written into
  len | Number of bytes to be read from the flash

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashReadIndirect()

int32_t OSPI_lld_norFlashReadIndirect | ( | OSPILLD_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

This function reads data from the flash from a specified offset in INDAC mode.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  offset | Offset at which the data is to be read from
  buf | Buffer to which data will be written into
  len | Number of bytes to be read from the flash

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashReadSfdp()

int32_t OSPI_lld_norFlashReadSfdp | ( | OSPILLD_Handle | handle,
|  | uint32_t | offset,
|  | uint8_t * | buf,
|  | uint32_t | len
| ) |  |

This function reads SFDP table from the flash from a specified offset.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  offset | Offset at which the data is to be read from
  buf | Buffer to which data will be written into
  len | Number of bytes to be read from the flash

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_norFlashErase()

int32_t OSPI_lld_norFlashErase | ( | OSPILLD_Handle | handle,
|  | uint32_t | address
| ) |  |

This function erases 1 block of data starting from a provided address.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_open()
  address | Address of the data block to be erased. This address should be block aligned.

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_configResetPin()

int32_t OSPI_lld_configResetPin | ( | OSPILLD_Handle | handle,
|  | uint32_t | config
| ) |  |

This function configures reset functionality.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPI_Handle returned from an OSPI_open()
  config | reset config

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_configBaudrate()

int32_t OSPI_lld_configBaudrate | ( | OSPILLD_Handle | handle,
|  | uint32_t | baud
| ) |  |

Configures baud divider.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPI_Handle returned from an OSPI_open()
  baud | baudrate from 2 to 32 and divisible by 2

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_readBaudRateDivFromReg()

int32_t OSPI_lld_readBaudRateDivFromReg | ( | OSPILLD_Handle | handle,
|  | uint32_t * | baudDiv
| ) |  |

Return value of baudrate that is programmed in IP register.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPI_Handle returned from an OSPI_open()
  baudDiv | pointer to memory into which baudrate will be written

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_getBaudRateDivFromObj()

int32_t OSPI_lld_getBaudRateDivFromObj | ( | OSPILLD_Handle | handle,
|  | uint32_t * | baudDiv
| ) |  |

Return value of baudrate that is saved in OSPI Object.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  handle | An OSPILLD_Handle returned from an OSPI_init()
  baudDiv | pointer to memory into which baudrate will be written

Returns
  OSPI_SYSTEM_SUCCESS on success, OSPI_SYSTEM_FAILURE otherwise

## ◆ OSPI_lld_setResetPinStatus()

int32_t OSPI_lld_setResetPinStatus | ( | OSPILLD_Handle | hOspi,
|  | uint32_t | pinStatus
| ) |  |

This function activates the RESET pin feature.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  hOspi | An OSPILLD_Handle returned from an OSPI_open()
  pinStatus | pinStatus - HIGH/LOW

Returns
  SystemP_SUCCESS on success, SystemP_FAILURE otherwise

## ◆ OSPI_dmaOpen()

int32_t OSPI_dmaOpen | ( | OSPILLD_Handle | hOspi | ) |

API to open an OSPI DMA channel.

This API will open a DMA Channel using the appropriate DMA driver callbacks and the registered via Sysconfig

Parameters

  hOspi | An OSPILLD_Handle returned from an OSPI_open()

Returns
  SystemP_SUCCESS on success, else failure

## ◆ OSPI_dmaClose()

int32_t OSPI_dmaClose | ( | OSPILLD_Handle | handle | ) |

API to close an OSPI DMA channel.

This API will open a DMA Channel using the appropriate DMA driver callbacks registered via Sysconfig

Parameters

  handle | [in] An OSPILLD_Handle returned from an OSPI_open()

Returns
  SystemP_SUCCESS on success, else failure

## ◆ OSPI_dmaCopy()

int32_t OSPI_dmaCopy | ( | OSPILLD_Handle | handle,
|  | void * | dst,
|  | void * | src,
|  | uint32_t | length,
|  | uint32_t | timeout
| ) |  |

API to do a DMA Copy using appropriate DMA Channel opened.

This API will open a DMA Channel using the appropriate DMA driver callbacks registered via Sysconfig

Parameters

  handle | [in] An OSPILLD_Handle returned from an OSPI_open()
  dst | [in] Destination address to which the data is to be copied
  src | [in] Source address from which the data is to be copied
  length | [in] Data length
  timeout | [in] Timeout for the transaction

Returns
  SystemP_SUCCESS on success, else failure

## ◆ OSPI_isDmaInterruptEnabled()

int32_t OSPI_isDmaInterruptEnabled | ( | OSPILLD_Handle | handle | ) |

API to get the DMA Interrupt status.

This API will retrieve the interrrupt status of the DMA Channel

Parameters

  handle | [in] An OSPILLD_Handle returned from an OSPI_open()

Returns
  SystemP_SUCCESS on success, else failure

## ◆ OSPI_lld_phyValidateTuningPoint()

int32_t OSPI_lld_phyValidateTuningPoint | ( | OSPILLD_Handle | hOspi,
|  | uint32_t | flashOffset
| ) |  |

Validates a tuning point for the OSPI physical interface.

This function verifies if the current OSPI physical interface configuration (tuning point) is valid by performing a read operation at the specified flash offset.

Parameters

  hOspi | OSPI LLD handle
  flashOffset | Flash memory offset to use for the validation read operation

Returns
  SystemP_SUCCESS on success, SystemP_FAILURE otherwise

## ◆ OSPI_lld_isValidateOtpEnable()

uint32_t OSPI_lld_isValidateOtpEnable | ( | OSPILLD_Handle | hOspi | ) |

Checks if OTP validation is enabled for the OSPI controller.

This function determines whether the OTP (One-Time Programmable) validation feature is currently enabled in the OSPI controller.

Parameters

  hOspi | Handle to the OSPI controller instance

Returns
  uint32_t Returns 1 if OTP validation is enabled, 0 otherwise

## ◆ OSPI_lld_setFrequency()

int32_t OSPI_lld_setFrequency | ( | OSPILLD_Handle | hOspi,
|  | uint64_t | inputClkFreq
| ) |  |

Sets the operating frequency for the OSPI peripheral.

This function configures the OSPI controller to operate at the specified frequency based on the input clock frequency provided.

Parameters

  hOspi | OSPI LLD handle
  inputClkFreq | Input clock frequency in Hz

Returns
  SystemP_SUCCESS on success, error code on failure

## ◆ OSPI_lld_setDelays()

int32_t OSPI_lld_setDelays | ( | OSPILLD_Handle | hOspi,
|  | uint32_t | inputClkFreq
| ) |  |

Sets timing delays for the OSPI interface based on input clock frequency.

This function configures the appropriate timing delays for the OSPI interface to ensure reliable communication with external memory devices. The delays are calculated based on the provided input clock frequency.

Parameters

  hOspi | OSPI LLD handle
  inputClkFreq | Input clock frequency in Hz

Returns
  SystemP_SUCCESS on success, error code on failure

## ◆ OSPI_lld_setBaudRateDiv()

int32_t OSPI_lld_setBaudRateDiv | ( | OSPILLD_Handle | hOspi,
|  | uint32_t | baudRateDiv
| ) |  |

Sets the baud rate divider for OSPI communication.

This function configures the baud rate divider to control the OSPI clock frequency. The actual OSPI clock frequency is determined by dividing the input clock frequency by the specified baud rate divider.

Parameters

  hOspi | OSPI LLD handle
  baudRateDiv | Baud rate divider value

Returns
  SystemP_SUCCESS on success, error code on failure

## ◆ OSPI_lld_disableDdrRdCmds()

int32_t OSPI_lld_disableDdrRdCmds | ( | OSPILLD_Handle | hOspi | ) |

This function resets DDR bit in INSTR_RD register for RD commands.

Precondition
  OSPI controller has been opened using OSPI_open()

Parameters

  hOspi | An OSPILLD_Handle returned from an OSPI_open()

Returns
  OSPI_SYSTEM_SUCCESS if DDR successfully disabled, else error on failure

## ◆ OSPI_lld_set1sProtocol()

int32_t OSPI_lld_set1sProtocol | ( | OSPILLD_Handle | hOspi | ) |

Resets the OSPI controller to operate in 1S-1S-1S mode.

This function reverts the OSPI controller configuration from advanced modes (such as 8D-8D-8D DDR mode) back to the basic single-lane mode (1S-1S-1S). It unsets all registers that were configured for high-performance modes, allowing the controller to operate in the standard SPI mode.

Parameters

  hOspi | An OSPILLD_Handle returned from an OSPI_open()

Returns
  SystemP_SUCCESS on success, else failure