RTEMS: Flash Device Configuration

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
Flash Device Configuration
Board Support Packages » ARM » Intel Cyclone V » Contributed Code » QSPI Flash Controller Module

## Data Structures
struct | ALT_QSPI_DEV_SIZE_CONFIG_s
struct | ALT_QSPI_TIMING_CONFIG_s
struct | ALT_QSPI_DEV_INST_CONFIG_s

## Typedefs
typedef enum ALT_QSPI_MODE_e | ALT_QSPI_MODE_t
typedef enum ALT_QSPI_CS_MODE_e | ALT_QSPI_CS_MODE_t
typedef enum ALT_QSPI_BAUD_DIV_e | ALT_QSPI_BAUD_DIV_t
typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s | ALT_QSPI_DEV_SIZE_CONFIG_t
typedef enum ALT_QSPI_CLK_PHASE_e | ALT_QSPI_CLK_PHASE_t
typedef enum ALT_QSPI_CLK_POLARITY_e | ALT_QSPI_CLK_POLARITY_t
typedef struct ALT_QSPI_TIMING_CONFIG_s | ALT_QSPI_TIMING_CONFIG_t
typedef struct ALT_QSPI_DEV_INST_CONFIG_s | ALT_QSPI_DEV_INST_CONFIG_t

## Enumerations
enum | ALT_QSPI_MODE_e { ALT_QSPI_MODE_SINGLE = 0 , ALT_QSPI_MODE_DUAL = 1 , ALT_QSPI_MODE_QUAD = 2 }
enum | ALT_QSPI_CS_MODE_e { ALT_QSPI_CS_MODE_SINGLE_SELECT = 0 , ALT_QSPI_CS_MODE_DECODE = 1 }
enum | ALT_QSPI_BAUD_DIV_e { ALT_QSPI_BAUD_DIV_2 = 0x0 , ALT_QSPI_BAUD_DIV_4 = 0x1 , ALT_QSPI_BAUD_DIV_6 = 0x2 , ALT_QSPI_BAUD_DIV_8 = 0x3 , ALT_QSPI_BAUD_DIV_10 = 0x4 , ALT_QSPI_BAUD_DIV_12 = 0x5 , ALT_QSPI_BAUD_DIV_14 = 0x6 , ALT_QSPI_BAUD_DIV_16 = 0x7 , ALT_QSPI_BAUD_DIV_18 = 0x8 , ALT_QSPI_BAUD_DIV_20 = 0x9 , ALT_QSPI_BAUD_DIV_22 = 0xA , ALT_QSPI_BAUD_DIV_24 = 0xB , ALT_QSPI_BAUD_DIV_26 = 0xC , ALT_QSPI_BAUD_DIV_28 = 0xD , ALT_QSPI_BAUD_DIV_30 = 0xE , ALT_QSPI_BAUD_DIV_32 = 0xF }
enum | ALT_QSPI_CLK_PHASE_e { ALT_QSPI_CLK_PHASE_ACTIVE = 0 , ALT_QSPI_CLK_PHASE_INACTIVE = 1 }
enum | ALT_QSPI_CLK_POLARITY_e { ALT_QSPI_CLK_POLARITY_LOW = 0 , ALT_QSPI_CLK_POLARITY_HIGH = 1 }

## Functions
ALT_QSPI_BAUD_DIV_t | alt_qspi_baud_rate_div_get (void)
ALT_STATUS_CODE | alt_qspi_baud_rate_div_set (const ALT_QSPI_BAUD_DIV_t baud_rate_div)
ALT_STATUS_CODE | alt_qspi_chip_select_config_get (uint32_t *cs, ALT_QSPI_CS_MODE_t *cs_mode)
ALT_STATUS_CODE | alt_qspi_chip_select_config_set (const uint32_t cs, const ALT_QSPI_CS_MODE_t cs_mode)
ALT_STATUS_CODE | alt_qspi_mode_bit_disable (void)
ALT_STATUS_CODE | alt_qspi_mode_bit_enable (void)
uint32_t | alt_qspi_mode_bit_config_get (void)
ALT_STATUS_CODE | alt_qspi_mode_bit_config_set (const uint32_t mode_bits)
ALT_STATUS_CODE | alt_qspi_device_size_config_get (ALT_QSPI_DEV_SIZE_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_device_size_config_set (const ALT_QSPI_DEV_SIZE_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_device_read_config_get (ALT_QSPI_DEV_INST_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_device_read_config_set (const ALT_QSPI_DEV_INST_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_device_write_config_get (ALT_QSPI_DEV_INST_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_device_write_config_set (const ALT_QSPI_DEV_INST_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_timing_config_get (ALT_QSPI_TIMING_CONFIG_t *cfg)
ALT_STATUS_CODE | alt_qspi_timing_config_set (const ALT_QSPI_TIMING_CONFIG_t *cfg)

## Detailed Description

The declarations and functions in this group are used to configure the QSPI controller interface to external flash devices.

The following steps describe how to initialize and configure the QSPI controller to operate with a flash device.

- Wait until any pending QSPI operations have completed.
- Disable the QSPI controller using alt_qspi_disable().
- Configure the device for optimal read transaction performance using alt_qspi_device_read_config_set().
- Configure the device for optimal write transaction performance using alt_qspi_device_write_config_set().
- Enable (alt_qspi_mode_bit_disable()) or disable (alt_qspi_mode_bit_disable()) the mode bits per the device requirements. If mode bits are enabled, then configure the mode bit values using alt_qspi_mode_bit_config_set().
- Configure the device size and write protection information using alt_qspi_device_size_config_set().
- Configure the QSPI device delay and timing settings using alt_qspi_device_write_config_set().
- Configure the baud divisor setting to define the required clock frequency to the device using alt_qspi_baud_rate_div_set().
- Enable the QSPI controller using alt_qspi_enable().

## Typedef Documentation

## ◆ ALT_QSPI_BAUD_DIV_t

typedef enum ALT_QSPI_BAUD_DIV_e ALT_QSPI_BAUD_DIV_t

This type enumerates the QSPI controller master baud rate divisor selections.

## ◆ ALT_QSPI_CLK_PHASE_t

typedef enum ALT_QSPI_CLK_PHASE_e ALT_QSPI_CLK_PHASE_t

This type enumerates the QSPI clock phase activity options outside the SPI word.

## ◆ ALT_QSPI_CLK_POLARITY_t

typedef enum ALT_QSPI_CLK_POLARITY_e ALT_QSPI_CLK_POLARITY_t

This type enumerates the QSPI clock polarity options outside the SPI word.

## ◆ ALT_QSPI_CS_MODE_t

typedef enum ALT_QSPI_CS_MODE_e ALT_QSPI_CS_MODE_t

This type enumerates the mode configurations available for driving the ss_n[3:0] device chip selects. The chip selects may be controlled as either in a '1 of 4' or '4 to 16 decode' mode.

## ◆ ALT_QSPI_DEV_INST_CONFIG_t

typedef struct ALT_QSPI_DEV_INST_CONFIG_s ALT_QSPI_DEV_INST_CONFIG_t

Device Instruction Configuration

This type defines a structure for specifying the optimal instruction set configuration to use with a target flash device.

## ◆ ALT_QSPI_DEV_SIZE_CONFIG_t

typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s ALT_QSPI_DEV_SIZE_CONFIG_t

Device Size Configuration

This type defines the structure used to specify flash device size and write protect regions.

## ◆ ALT_QSPI_MODE_t

typedef enum ALT_QSPI_MODE_e ALT_QSPI_MODE_t

This type enumerates the operational modes the QSPI controller can be configured for. It may apply to instruction, address, and/or data width interactions between the QSPI controller and the flash device.

## ◆ ALT_QSPI_TIMING_CONFIG_t

typedef struct ALT_QSPI_TIMING_CONFIG_s ALT_QSPI_TIMING_CONFIG_t

QSPI Controller Timing Configuration

This type defines the structure used to configure timing paramaters used by the QSPI controller to communicate with a target flash device.

All timing values are defined in cycles of the SPI master ref clock.

## Enumeration Type Documentation

## ◆ ALT_QSPI_BAUD_DIV_e

enum ALT_QSPI_BAUD_DIV_e

This type enumerates the QSPI controller master baud rate divisor selections.

Enumerator
ALT_QSPI_BAUD_DIV_2 | Divide by 2
ALT_QSPI_BAUD_DIV_4 | Divide by 4
ALT_QSPI_BAUD_DIV_6 | Divide by 6
ALT_QSPI_BAUD_DIV_8 | Divide by 8
ALT_QSPI_BAUD_DIV_10 | Divide by 10
ALT_QSPI_BAUD_DIV_12 | Divide by 12
ALT_QSPI_BAUD_DIV_14 | Divide by 14
ALT_QSPI_BAUD_DIV_16 | Divide by 16
ALT_QSPI_BAUD_DIV_18 | Divide by 18
ALT_QSPI_BAUD_DIV_20 | Divide by 20
ALT_QSPI_BAUD_DIV_22 | Divide by 22
ALT_QSPI_BAUD_DIV_24 | Divide by 24
ALT_QSPI_BAUD_DIV_26 | Divide by 26
ALT_QSPI_BAUD_DIV_28 | Divide by 28
ALT_QSPI_BAUD_DIV_30 | Divide by 30
ALT_QSPI_BAUD_DIV_32 | Divide by 32

## ◆ ALT_QSPI_CLK_PHASE_e

enum ALT_QSPI_CLK_PHASE_e

This type enumerates the QSPI clock phase activity options outside the SPI word.

Enumerator
ALT_QSPI_CLK_PHASE_ACTIVE | The SPI clock is active outside the word
ALT_QSPI_CLK_PHASE_INACTIVE | The SPI clock is inactive outside the word

## ◆ ALT_QSPI_CLK_POLARITY_e

enum ALT_QSPI_CLK_POLARITY_e

This type enumerates the QSPI clock polarity options outside the SPI word.

Enumerator
ALT_QSPI_CLK_POLARITY_LOW | SPI clock is quiescent low outside the word.
ALT_QSPI_CLK_POLARITY_HIGH | SPI clock is quiescent high outside the word.

## ◆ ALT_QSPI_CS_MODE_e

enum ALT_QSPI_CS_MODE_e

This type enumerates the mode configurations available for driving the ss_n[3:0] device chip selects. The chip selects may be controlled as either in a '1 of 4' or '4 to 16 decode' mode.

Enumerator
ALT_QSPI_CS_MODE_SINGLE_SELECT | Select 1 of 4 chip select ss_n[3:0]
ALT_QSPI_CS_MODE_DECODE | Select external 4 to 16 decode of ss_n[3:0].

## ◆ ALT_QSPI_MODE_e

enum ALT_QSPI_MODE_e

This type enumerates the operational modes the QSPI controller can be configured for. It may apply to instruction, address, and/or data width interactions between the QSPI controller and the flash device.

Enumerator
ALT_QSPI_MODE_SINGLE | Use Standard Single SPI (SIO-SPI) mode (bits always transferred into the device on DQ0 only). Supported by all SPI flash devices.
ALT_QSPI_MODE_DUAL | Use Dual SPI (DIO-SPI) SPI mode where bits are transferred on DQ0 and DQ1.
ALT_QSPI_MODE_QUAD | Use Dual SPI (QIO-SPI) SPI mode where bits are transferred on DQ0, DQ1, DQ3, and DQ3.

## Function Documentation

## ◆ alt_qspi_baud_rate_div_get()

ALT_QSPI_BAUD_DIV_t alt_qspi_baud_rate_div_get | ( | void |  | ) |

Get the current value of the QSPI master baud rate divisor.

Returns
  The value of the QSPI master baud rate divisor.

## ◆ alt_qspi_baud_rate_div_set()

ALT_STATUS_CODE alt_qspi_baud_rate_div_set | ( | const ALT_QSPI_BAUD_DIV_t | baud_rate_div | ) |

Set the current value of the QSPI master baud rate divisor.

Sets the value of the QSPI master baud rate divisor.

Parameters

  baud_rate_div | The master baud rate divisor. Valid range includes even values 2 to 32.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_chip_select_config_get()

ALT_STATUS_CODE alt_qspi_chip_select_config_get | ( | uint32_t * | cs,
|  | ALT_QSPI_CS_MODE_t * | cs_mode
| ) |  |

Get the current QSPI device peripheral chip select output and decode function configuration values.

Parameters

  cs | [out] The chip select line output values.
  cs_mode | [out] The decode mode to use for the chip selects.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_chip_select_config_set()

ALT_STATUS_CODE alt_qspi_chip_select_config_set | ( | const uint32_t | cs,
|  | const ALT_QSPI_CS_MODE_t | cs_mode
| ) |  |

Set the QSPI device peripheral chip select outputs and decode function configuration.

The chip select lines output values operate according to the selected chip select decode mode. If cs_mode is ALT_QSPI_CS_MODE_SINGLE_SELECT then cs[3:0] are output thus:

cs[3:0] | n_ss_out[3:0]
--- | ---
xxx0 | 1110
xx01 | 1101
x011 | 1011
0111 | 0111
1111 | 1111 (no peripheral selected)

Otherwise if cs_mode is ALT_QSPI_CS_MODE_DECODE then cs[3:0] directly drives n_ss_out[3:0].

Parameters

  cs | The chip select line output values.
  cs_mode | The decode mode to use for the chip selects.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_read_config_get()

ALT_STATUS_CODE alt_qspi_device_read_config_get | ( | ALT_QSPI_DEV_INST_CONFIG_t * | cfg | ) |

Get the current QSPI device read instruction configuration.

Parameters

  cfg | [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to contain the returned QSPI controller instruction configuration used when performing read transactions with the device.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_read_config_set()

ALT_STATUS_CODE alt_qspi_device_read_config_set | ( | const ALT_QSPI_DEV_INST_CONFIG_t * | cfg | ) |

Set the QSPI device read instruction configuration.

This API requires that the QSPI controller be idle, as determined by alt_qspi_is_idle().

Parameters

  cfg | Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the desired op code, transfer widths, and dummy cycles for the QSPI controller to use when performing read transactions with the device.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_size_config_get()

ALT_STATUS_CODE alt_qspi_device_size_config_get | ( | ALT_QSPI_DEV_SIZE_CONFIG_t * | cfg | ) |

Get the current flash device size and write protection configuration.

Parameters

  cfg | [out] Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure to contain the returned flash device size and write protection configuration.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_size_config_set()

ALT_STATUS_CODE alt_qspi_device_size_config_set | ( | const ALT_QSPI_DEV_SIZE_CONFIG_t * | cfg | ) |

Set the flash device size and write protection configuration.

Parameters

  cfg | Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the flash device size and write protection configuration.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_write_config_get()

ALT_STATUS_CODE alt_qspi_device_write_config_get | ( | ALT_QSPI_DEV_INST_CONFIG_t * | cfg | ) |

Get the current QSPI device write instruction configuration.

Parameters

  cfg | [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to contain the returned QSPI controller instruction configuration used when performing write transactions with the device.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_device_write_config_set()

ALT_STATUS_CODE alt_qspi_device_write_config_set | ( | const ALT_QSPI_DEV_INST_CONFIG_t * | cfg | ) |

Set the QSPI device write instruction configuration.

This API requires that the QSPI controller be idle, as determined by alt_qspi_is_idle().

Parameters

  cfg | Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the desired op code, transfer widths, and dummy cycles for the QSPI controller to use when performing write transactions with the device.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_mode_bit_config_get()

uint32_t alt_qspi_mode_bit_config_get | ( | void |  | ) |

Get the current value of the Mode Bit Configuration register.

Returns
  The 8 bit value that is sent to the device following the address bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())

## ◆ alt_qspi_mode_bit_config_set()

ALT_STATUS_CODE alt_qspi_mode_bit_config_set | ( | const uint32_t | mode_bits | ) |

Set the value of the Mode Bit Configuration register.

Set the value of the 8 bits that are sent to the device following the address bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())

This API requires that the QSPI controller be idle, as determined by alt_qspi_is_idle().

Parameters

  mode_bits | The 8 bit value sent to the device following the address bytes.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_mode_bit_disable()

ALT_STATUS_CODE alt_qspi_mode_bit_disable | ( | void |  | ) |

Disable the mode bits from being sent after the address bytes.

Prevent the mode bits defined in the Mode Bit Configuration register from being sent following the address bytes.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_mode_bit_enable()

ALT_STATUS_CODE alt_qspi_mode_bit_enable | ( | void |  | ) |

Enable the mode bits to be sent after the address bytes.

Ensure the mode bits defined in the Mode Bit Configuration register to be sent following the address bytes.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_timing_config_get()

ALT_STATUS_CODE alt_qspi_timing_config_get | ( | ALT_QSPI_TIMING_CONFIG_t * | cfg | ) |

Get the QSPI device delay and timing configuration parameters.

This function returns the settings of the chip select delay and timing configurations.

Parameters

  cfg | [out] Pointer to a ALT_QSPI_TIMING_CONFIG_t structure to return the device timing and delay settings.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.

## ◆ alt_qspi_timing_config_set()

ALT_STATUS_CODE alt_qspi_timing_config_set | ( | const ALT_QSPI_TIMING_CONFIG_t * | cfg | ) |

Set the QSPI device delay and timing configuration parameters.

This function allows the user to configure how the chip select is driven after each flash access. This is required as each device may have different timing requirements. As the serial clock frequency is increased, these timing parameters become more important and can be adjusted to meet the requirements of a specific flash device. All timings are defined in cycles of the SPI master ref clock.

This API requires that the QSPI controller be idle, as determined by alt_qspi_is_idle().

Parameters

  cfg | Pointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the desired timing and delay settings.

Return values

  ALT_E_SUCCESS | Indicates successful completion.
  ALT_E_ERROR | Indicates an error occurred.