Altera Embedded Peripherals IP - Manual (Page 266)

The mailbox software programming model has the following characteristics and assumes there are
multiple processors accessing a single mailbox core and a shared memory:
• Each mailbox message is one 32-bit word.
• There is a predefined address range in shared memory dedicated to storing messages. The size of this
address range imposes a maximum limit on the number of messages pending.
• The mailbox software implements a message FIFO between processors. Only one processor can write
to the mailbox at a time, and only one processor can read from the mailbox at a time, ensuring
message integrity.
• The software on both the sending and receiving processors must agree on a protocol for interpreting
mailbox messages. Typically, processors treat the message as a pointer to a structure in shared
memory.
• The sending processor can post messages in succession, up to the limit imposed by the size of the
message address range.
• When messages exist in the mailbox, the receiving processor can read messages. The receiving
processor can block until a message appears, or it can poll the mailbox for new messages.
• Reading the message removes the message from the mailbox.
Software Files
Altera provides the following software files accompanying the mailbox core hardware:
•
altera_avalon_mailbox_regs.h —Defines the core’s register map, providing symbolic constants to access
the low-level hardware.
• altera_avalon_mailbox.h —Defines data structures and functions to access the mailbox core hardware.
• altera_avalon_mailbox.c —Contains the implementations of the functions to access the mailbox core.
Programming with the Mailbox Core
This section describes the software constructs for manipulating the mailbox core hardware.
The file
altera_avalon_mailbox.h declares a structure
alt_mailbox_dev
that represents an instance of a
mailbox device. It also declares functions for accessing the mailbox hardware structure, listed in the
Mailbox API Functions table. For a complete description of each function, refer to the MailboxAPI
section.
Table 27-2: Mailbox API Functions
Function Name Description
altera_avalon_mailbox_close()
Closes the handle to a mailbox.
altera_avalon_mailbox_get()
Returns a message if one is present, but does not block
waiting for a message.
altera_avalon_mailbox_open()
Claims a handle to a mailbox, enabling all the other
functions to access the mailbox core.
altera_avalon_mailbox_pend()
Blocks waiting for a message to be in the mailbox.
altera_avalon_mailbox_post()
Posts a message to the mailbox.
The example below demonstrates writing to and reading from a mailbox. For this example, assume that
the hardware system has two processors communicating via mailboxes. The system includes two mailbox
cores, which provide two-way communication between the processors.
UG-01085
2014.24.07
Software Files 27-3
Mailbox Core Altera Corporation
Send Feedback