Embedded Peripherals IP User Guide

ID 683130
Date 10/18/2021
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) Core 26. On-Chip Memory II (RAM or ROM) 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. Intel FPGA HPS GMII to TSE 1000BASE-X/SGMII PCS Bridge Core 52. Intel FPGA HPS EMAC to Multi-rate PHY GMII Adapter Core 53. Intel FPGA MSI to GIC Generator Core

13.4.1.2. Driver Implementation

An opened Mailbox instance will register a sender/receiver interrupt service routine (ISR), if interrupts are supported with sender/receiver callbacks. When a Mailbox interrupt is disabled, an ISR will not register and polling mode will need to be used. You must close the Mailbox driver when it is unused.

Table 112.  Mailbox APIs
Function Name Description
altera_avalon_mailbox_send Send message to Mailbox
altera_avalon_mailbox_status Query current state of Mailbox
altera_avalon_mailbox_retrieve_poll Read from Mailbox pointer register to retrieve messages
altera_avalon_mailbox_open Claims a handle to a Mailbox, enabling all the other functions to access the Mailbox core
altera_avalon_mailbox_close Close the handle to a Mailbox
Table 113.  altera_avalon_mailbox_open
Prototype: altera_avalon_mailbox_dev* altera_avalon_mailbox_open (const char* name, altera_mailbox_tx_cb tx_callback, altera_mailbox_rx_cb rx_callback)
Include: <altera_avalon_mailbox_simple.h>
Parameters:

Name — The Mailbox device name to open.

tx_callback – User to provide callback function to notify when a sending message is completed.

rx_callback – User to provide callback function to notify when a receive a message.
Returns: Pointer to mailbox
Description:

altera_avalon_mailbox_open() find and register the Mailbox device pointer. This function also registers the interrupt handler and user callback function for a interrupt enabled Mailbox.

Table 114.  altera_avalon_mailbox_close
Prototype: void altera_avalon_mailbox_close (altera_avalon_mailbox_dev* dev);
Include: <altera_avalon_mailbox_simple.h>
Parameters: dev—The Mailbox to close.
Returns: Null
Description: alt_avalon_mailbox_close() closes the mailbox de-registering interrupt handler and callback functions and masking Mailbox interrupt.
Table 115.  altera_avalon_mailbox_send
Prototype: int altera_avalon_mailbox_send (altera_avalon_mailbox_dev* dev, void* message, int timeout, EventType event)
Include: <altera_avalon_mailbox_simple.h>
Parameters:

*message – Pointer to message command and pointer structure.

Timeout – Specifies number of loops before sending a message. Give a ‘0’ value to wait until the message is transferred.

EventType – set ‘POLL’ or ‘ISR’.

Returns: Return 0 on success and 1 for fail.
Description:

altera_avalon_mailbox_send () sends a message to the mailbox. This is a blocking function when the sender interrupt is disabled.

This function is in non-blocking when interrupt is enabled.

Table 116.  altera_avalon_mailbox_retrieve_poll
Prototype: int altera_avalon_mailbox_retrieve_poll (altera_avalon_mailbox_dev* dev,alt_u32* msg_ptr, alt_u32 timeout)
Include: <altera_avalon_mailbox_simple.h>
Parameters:

dev - The Mailbox device to read message from.

timeout – Specifies number loops before sending a message. Give a ‘0’ value to wait until a message is retrieved.

msg_ptr – A pointer to an array of two Dwords which are for the command and message pointer. This pointer will be populated with a receive message if successful or NULL if error.
Returns: Return pointer to message and command. Return ‘NULL’ in messages if timeout. This is a blocking function.
Description:

altera_avalon_mailbox_retrieve_poll () reads a message pointer and command to Mailbox structure from the Mailbox and notifies through callback.

Table 117.  altera_avalon_mailbox_status
Prototype: alt_u32 altera_avalon_mailbox_status (altera_avalon_mailbox_dev* dev)
Include: <altera_avalon_mailbox_simple.h>
Parameters:

dev -The Mailbox device to read status from

Returns:

For a receiving Mailbox:

- 0 for no message pending

- 1 for message pending

For a sending Mailbox:

- 0 for Mailbox empty (ready to send)

- 1 for Mailbox full (not ready to send)

Description:

Indicates to sender Mailbox it is full or empty for transfer.

Indicates to receiver Mailbox has a message pending or not.

Device structure


// Callback routine type definition
typedef void(*altera_mailbox_rx_cb)(void *message);
typedefvoid (*altera_mailbox_tx_cb)(void *message,int status);

typedef enum mbox_type { MBOX_TX = 0,MBOX_RX } MboxType;
typedef enum event_type { ISR = 0, POLL } EventType;

typedef struct altera_avalon_mailbox_dev
{    
	alt_dev                 dev;                  
	/* Device linke-list entry */
    
	alt_u32                 base;                 
	/* Base address of Mailbox */
    
	alt_u32                 mailbox_irq;          
	/* Mailbox IRQ */
    
	alt_u32                 mailbox_intr_ctrl_id; 
	/* Mailbox IRQ ID */  
  
	altera_mailbox_tx_cb    tx_cb;                
	/* Callback routine pointer */ 
   
	altera_mailbox_rx_cb    rx_cb;                
	/* Callback routine pointer */   
 
	MboxType                mbox_type;            
	/* Mailbox direction */  
  
	alt_u32*                mbox_msg;             
	/* a pointer to message array to be received or sent */
    
	alt_u8                  lock;                 
	/* Token to indicate mbox_msg already taken */ 
   
	ALT_SEM                 (write_lock)          
	/* Semaphore used to control access to the write in multi-threaded mode */
} 
altera_avalon_mailbox_dev;