Embedded Peripherals IP User Guide

ID 683130
Date 10/18/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
1. Introduction 2. Avalon® -ST Multi-Channel Shared Memory FIFO Core 3. Avalon® -ST Single-Clock and Dual-Clock FIFO Cores 4. Avalon® -ST Serial Peripheral Interface Core 5. SPI Core 6. SPI Agent/JTAG to Avalon® Host Bridge Cores 7. Intel eSPI Agent Core 8. eSPI to LPC Bridge Core 9. Ethernet MDIO Core 10. Intel FPGA 16550 Compatible UART Core 11. UART Core 12. JTAG UART Core 13. Intel FPGA Avalon® Mailbox Core 14. Intel FPGA Avalon® Mutex Core 15. Intel FPGA Avalon® I2C (Host) Core 16. Intel FPGA I2C Agent to Avalon® -MM Host Bridge Core 17. Intel FPGA Avalon® Compact Flash Core 18. EPCS/EPCQA Serial Flash Controller Core 19. Intel FPGA Serial Flash Controller Core 20. Intel FPGA Serial Flash Controller II Core 21. Intel FPGA Generic QUAD SPI Controller Core 22. Intel FPGA Generic QUAD SPI Controller II Core 23. Interval Timer Core 24. Intel FPGA Avalon FIFO Memory Core 25. On-Chip Memory (RAM and ROM) Intel FPGA IP 26. On-Chip Memory II (RAM or ROM) Intel FPGA IP 27. Optrex 16207 LCD Controller Core 28. PIO Core 29. PLL Cores 30. DMA Controller Core 31. Modular Scatter-Gather DMA Core 32. Scatter-Gather DMA Controller Core 33. SDRAM Controller Core 34. Tri-State SDRAM Core 35. Video Sync Generator and Pixel Converter Cores 36. Intel FPGA Interrupt Latency Counter Core 37. Performance Counter Unit Core 38. Vectored Interrupt Controller Core 39. Avalon® -ST Data Pattern Generator and Checker Cores 40. Avalon® -ST Test Pattern Generator and Checker Cores 41. System ID Peripheral Core 42. Avalon® Packets to Transactions Converter Core 43. Avalon® -ST Multiplexer and Demultiplexer Cores 44. Avalon® -ST Bytes to Packets and Packets to Bytes Converter Cores 45. Avalon® -ST Delay Core 46. Avalon® -ST Round Robin Scheduler Core 47. Avalon® -ST Splitter Core 48. Avalon® -MM DDR Memory Half Rate Bridge Core 49. Intel FPGA GMII to RGMII Converter Core 50. Intel FPGA MII to RMII Converter Core 51. HPS GMII to TSE 1000BASE-X/SGMII PCS Bridge Core Intel® FPGA IP 52. Intel FPGA HPS EMAC to Multi-rate PHY GMII Adapter Core 53. Intel FPGA MSI to GIC Generator Core 54. Cache Coherency Translator Intel® FPGA IP 55. Lightweight UART Core

15.8. Intel FPGA Avalon® I2C (Host) Core API

Table 135.  alt_avalon_i2c_open
Prototype ALT_AVALON_I2C_DEV_t* alt_avalon_i2c_open(const char* name)
Include <altera_avalon_i2c.h>
Parameters
  • name - Character pointer to name of I2C peripheral as registered with the HAL.

For example: To open an I2C controller named as i2c_0 in Platform Designer, use /dev/i2c_0.

Returns
  • NULL - The return value is NULL on failure.
  • non-NULL - Success, returns ptr to I2C device instance.
Description

Retrieve a pointer to the I2C block instance. Search the list of registered I2C instances for one with the supplied name.

Table 136.  alt_avalon_i2c_register_optional_irq_handler
Prototype void alt_avalon_i2c_register_optional_irq_handler(ALT_AVALON_I2C_DEV_t *i2c_dev, IRQ_DATA_t * irq_data)
Include <altera_avalon_i2c.h>
Parameters
  • i2c_dev – Pointer to I2C device (instance) structure.
  • irq data – A structure used for interrupt handler data.
Returns -
Description Associate the optionally provided user interrupt callback routine with the I2C handler. This is a simple IRQ callback which allows I2C transaction functions to immediately return while the optional callback handles receiving or transmitting the data to the device and completing the transaction. This optional callback uses a IRQ_DATA_t structure for IRQ data.

You can use the function alt_avalon_i2c_interrupt_transaction_status to check for IRQ transaction complete, or for a transaction error. These optionally provided interrupt routines are functional, but are provided mainly for the purpose as working examples of using interrupts with the Avalon® I2C (Host) Core.

You may want to develop a more detailed irq callback routine tailored for specific device hardware. In that case, you shall register the user callback with the alt_avalon_i2c_register_callback function.

Using this optionally provided user callback routine enables use of the following functions:
  • alt_avalon_i2c_master_receive_using_interrupts
  • alt_avalon_i2c_master_transmit_using_interrupts
Table 137.  alt_avalon_i2c_register_callback
Prototype void alt_avalon_i2c_register_callback (ALT_AVALON_I2C_DEV_t *i2c_dev, alt_avalon_i2c_callback callback, alt_u32 control, void *context)
Include <altera_avalon_i2c.h>
Parameters
  • dev - Pointer to I2C device (instance) structure.
  • callback - Pointer to callback routine to execute at interrupt level.
  • control - For masking the source interruption and setting configuration.
  • context - Callback context.
Returns -
Description

Associate a user-specific routine with the I2C interrupt handler. If a callback is registered, all enabled ISR's causes the callback to be executed.

The callback runs as part of the interrupt service routine.

An optional user callback routine is provided in this code and, if used, enables use of the following functions:
  • alt_avalon_i2c_master_receive_using_interrupts
  • alt_avalon_i2c_master_transmit_using_interrupts
To register the optionally provided user callback use the alt_avalon_i2c_register_optional_irq_handler function.
Table 138.  alt_avalon_i2c_master_tx
Prototype alt_avalon_i2c_master_tx (ALT_AVALON_I2C_DEV_t *i2c_dev, alt_u8 * buffer, const alt_u32 size, const alt_u8 use_interrupts)
Include <altera_avalon_i2c.h>
Parameters
  • dev - Pointer to I2C device (instance) structure.
  • buffer - The data buffer to transmit the I2C data.
  • size - The size of the data buffer to write to the I2C bus.
  • use_interrupts - The optional user interrupt handler callback is used to handle sending the data.
Returns ALT_AVALON_I2C_SUCCESS indicates successful status. Otherwise, one of the ALT_AVALON_I2C_* status codes is returned. All failing return values are < 0.
Description

This function transmits START followed by the I2C command byte(s). Then write requests are sent to fulfill the write request. The final transaction will issue a STOP.

This API is not suitable for being called in an interrupt context as it may wait for certain controller states before completing. The target address must have been set before using this function. If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, or ALT_AVALON_I2C_BUSY occurs, then the command is retried.

If the use_interrupts parameter is 1, then as soon as all cmd bytes have been written to the command fifo this function will return. The interrupt handler will then handle waiting for the device to send the rx data and will then complete the I2C transaction. To use this option the provided optional user interrupt handler callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler function.

Table 139.  alt_avalon_i2c_master_rx
Prototype alt_avalon_i2c_master_rx (ALT_AVALON_I2C_DEV_t *i2c_dev, alt_u8 * buffer, const alt_u32 size, const alt_u8 use_interrupts)
Include <altera_avalon_i2c.h>
Parameters
  • dev - Pointer to I2C device (instance) structure.
  • buffer - The data buffer to receive the I2C data.
  • size - The size of the data buffer to write to the I2C bus.
  • use_interrupts - The optional user interrupt handler callback is used to handle receiving the data.
Returns ALT_AVALON_I2C_SUCCESS indicates successful status. Otherwise, one of the ALT_AVALON_I2C_* status codes is returned. All failing return values are < 0.
Description

This function transmits START followed by the I2C command byte(s). Then read requests are sent to fulfill the read request. The final transaction will issue a STOP.

This API is not suitable for being called in an interrupt context as it may wait for certain controller states before completing.

The target address must have been set before using this function.

If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, ALT_AVALON_I2C_BUSY occurs, the command will be retried. ALT_AVALON_I2C_NACK_ERR will occur when the agent device is not yet ready to accept more data. If the use_interrupts parameter is 1, then as soon as all cmd bytes have been written to the command fifo, this function will return. The interrupt handler will then handle waiting for the device to send the rx data and will then complete the I2C transaction. To use this option the provided optional user interrupt handler callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler function.
Table 140.  alt_avalon_i2c_master_tx_rx
Prototype alt_avalon_i2c_master_tx_rx (ALT_AVALON_I2C_DEV_t *i2c_dev, const alt_u8 * txbuffer, const alt_u32 txsize, alt_u8 * rxbuffer, const alt_u32 rxsize, const alt_u8 use_interrupts)
Include <altera_avalon_i2c.h>
Parameters
  • dev - Pointer to I2C device (instance) structure.
  • txdata - Send data buffer.
  • txsize - Size of the send data buffer to write to the I2C bus.
  • rxdata - Receive data buffer.
  • rxsize - Size of the receive data buffer.
  • use_interrupts - The optional user interrupt handler callback is used to handle sending and receiving the data.
Returns ALT_AVALON_I2C_SUCCESS indicates successful status. Otherwise, one of the ALT_AVALON_I2C_* status codes is returned. All failing return values are < 0.
Description

This function transmits START followed by the I2C command byte(s). Then write requests are sent to fulfill the write request. After a RESTART is issued and read requests are sent until the read request is fulfilled. The final transaction will issue a STOP.

This API is not suitable for being called in an interrupt context as it may wait for certain controller states before completing. The target address must have been set before using this function. If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, or ALT_AVALON_I2C_BUSY, occurs, then the command is retried.

ALT_AVALON_I2C_NACK_ERR occurs when the agent device is not yet ready to accept or send more data. This command allows easy access of a device requiring an internal register address to be set before doing a read, for example an EEPROM device.

Example: If an EEPROM requires a 2 byte address to be sent before doing a memory read, the tx buffer contains the 2 byte address and the txsize is set to 2. Then the rxbuffer recieves the rxsize number of bytes to read from the EEPROM as follows:
To Read 0x10 bytes from EEPROM at I2C address 0x51 into buffer:
buffer[0]=2;buffer[1]=0; //set eeprom address 0x200
alt_avalon_i2c_master_tx_rx(i2c_ptr,buffer,2,buffer,0x10,0);

The tx and rx buffer can be the same buffer if desired.

If the use_interrupts parameter is 1, then as soon as all cmd bytes have been written to the command fifo this function will return. The interrupt handler will then handle waiting for the device to send the rx data and will then complete the I2C transaction. To use this option the provided optional user interrupt handler callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler function.
Table 141.  alt_avalon_i2c_interrupt_transaction_status
Prototype This API is not suitable for being called in analt_avalon_i2c_interrupt_transaction_status (ALT_AVALON_I2C_DEV_t *i2c_dev)
Include <altera_avalon_i2c.h>
Parameters dev - A pointer to the I2C controller device block instance.
Returns

ALT_AVALON_I2C_SUCCESS indicates interrupt transaction is successfully completed. Another transaction can now be started.

ALT_AVALON_I2C_BUSY indicates the interrupt transaction is still busy.

ALT_AVALON_NACK_ERROR indicates the device did not ack. This is most likely because the device is busy with the previous transaction. The transaction must be retried.

Otherwise, one of the other ALT_AVALON_I2C_* status codes is returned. The transaction must be retried.

All failing return values are < 0.
Description When an interrupt transaction has been initiated using the alt_avalon_i2c_master_tx, alt_avalon_i2c_master_rx, or alt_avalon_i2c_master_tx_rx function with the interrupt option set, or if using the alt_avalon_i2c_master_transmit_using_interrupts or alt_avalon_i2c_master_receive_using_interrupts functions, then this function can be used to check the status of that transaction. The only way to ensure error free back to back transactions is to use this function after every interrupt transaction to ensure the transaction had no errors and is complete, before starting the next transaction. Also, if an error is returned from this function, then you must retry the I2C transaction. One reason an error may be returned is if the device is busy, which is likely to occur occasionally if you are doing back to back transactions.