Altera HWLIB  16.0
The Altera HW Manager API Reference Manual
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups
Flash Device Configuration

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.

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
 

ENUMS

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)
 

Data Structure Documentation

struct ALT_QSPI_DEV_SIZE_CONFIG_s

Device Size Configuration

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

Data Fields
uint32_t block_size Number of bytes per device block. The number is specified as a power of 2. That is 0 = 1 byte, 1 = 2 bytes, ... 16 = 65535 bytes, etc.
uint32_t page_size Number of bytes per device page. This is required by the controller for performing flash writes up to and across page boundaries.
uint32_t addr_size Number of bytes used for the flash address. The value is n + 1 based. That is 0 = 1 byte, 1 = 2 bytes, 2 = 3 bytes, 3 = 4 bytes.
uint32_t lower_wrprot_block The block number that defines the lower block in the range of blocks that is protected from writing. This field is ignored it write protection is disabled.
uint32_t upper_wrprot_block The block number that defines the upper block in the range of blocks that is protected from writing. This field is ignored it write protection is disabled.
bool wrprot_enable The write region enable value. A value of true enables write protection on the region specified by the lower_wrprot_block and upper_wrprot_block range.
struct ALT_QSPI_TIMING_CONFIG_s

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.

Data Fields
ALT_QSPI_CLK_PHASE_t clk_phase Selects whether the clock is in an active or inactive phase outside the SPI word.
ALT_QSPI_CLK_POLARITY_t clk_pol Selects whether the clock is quiescent low or high outside the SPI word.
uint32_t cs_da Chip Select De-Assert. Added delay in master reference clocks for the length that the master mode chip select outputs are de-asserted between transactions. If CSDA = X, then the chip select de-assert time will be: 1 sclk_out + 1 ref_clk + X ref_clks.
uint32_t cs_dads Chip Select De-Assert Different Slaves. Delay in master reference clocks between one chip select being de-activated and the activation of another. This is used to ensure a quiet period between the selection of two different slaves. CSDADS is only relevant when switching between 2 different external flash devices. If CSDADS = X, then the delay will be: 1 sclk_out + 3 ref_clks + X ref_clks.
uint32_t cs_eot Chip Select End Of Transfer. Delay in master reference clocks between last bit of current transaction and de-asserting the device chip select (n_ss_out). By default (when CSEOT=0), the chip select will be de-asserted on the last falling edge of sclk_out at the completion of the current transaction. If CSEOT = X, then chip selected will de-assert X ref_clks after the last falling edge of sclk_out.
uint32_t cs_sot Chip Select Start Of Transfer. Delay in master reference clocks between setting n_ss_out low and first bit transfer. By default (CSSOT=0), chip select will be asserted half a SCLK period before the first rising edge of sclk_out. If CSSOT = X, chip select will be asserted half an sclk_out period before the first rising edge of sclk_out + X ref_clks.
uint32_t rd_datacap The additional number of read data capture cycles (ref_clk) that should be applied to the internal read data capture circuit. The large clock-to-out delay of the flash memory together with trace delays as well as other device delays may impose a maximum flash clock frequency which is less than the flash memory device itself can operate at. To compensate, software should set this register to a value that guarantees robust data captures.
struct ALT_QSPI_DEV_INST_CONFIG_s

Device Instruction Configuration

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

Data Fields
uint32_t op_code The read or write op code to use for the device transaction.
ALT_QSPI_MODE_t inst_type Instruction mode type for the controller to use with the device. The instruction type applies to all instructions (reads and writes) issued from either the Direct Access Controller or the Indirect Acces Controller.
ALT_QSPI_MODE_t addr_xfer_type Address transfer mode type. The value of this field is ignored if the inst_type data member is set to anything other than ALT_QSPI_MODE_SINGLE. In that case, the addr_xfer_type assumes the same mode as the inst_type.
ALT_QSPI_MODE_t data_xfer_type Data transfer mode type. The value of this field is ignored if the inst_type data member is set to anything other than ALT_QSPI_MODE_SINGLE. In that case, the data_xfer_type assumes the same mode as the inst_type.
uint32_t dummy_cycles Number of dummy clock cycles required by device for a read or write instruction.

Typedef Documentation

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.

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.

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

Device Size Configuration

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

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

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

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.

Device Instruction Configuration

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

Enumeration Type Documentation

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.

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].

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

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

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.

Function Documentation

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_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_divThe master baud rate divisor. Valid range includes even values 2 to 32.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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
csThe chip select line output values.
cs_modeThe decode mode to use for the chip selects.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_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_bitsThe 8 bit value sent to the device following the address bytes.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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
cfgPointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the flash device size and write protection configuration.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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
cfgPointer 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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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
cfgPointer 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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
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
cfgPointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the desired timing and delay settings.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.