Overview

This file contains a design example for using the Mailbox hardware and driver XMbox.

This example attempts to send a known message through the mailbox from the processor identified as 0 (XPAR_CPU_ID=0) to the other processor. The message is received by the receiver and the test passes. Since the application is running on two separate processors, the initiator declares success when the message is sent and the receiver declares success when the message is received. There is no feedback to the initiator so a terminal is required for each processor to verify that the test passed for both sides.

The example assumes there are two processors availabile in the system that are expected to inter-communicate.

This example has been tested on ML505 Hardware Evaluation board.

Note

These code fragments will illustrate how the XMbox component can be used to:

Initialize the Mailbox core.
pass data between two processors.

 MODIFICATION HISTORY:

 Ver   Who  Date         Changes



 2.00a hm               Example that sends and receives and uses interrupts
 3.01a sdm  05/06/10    Cleanup for coding guidelines, removed printfs from all
                        the functions except the main function
 4.1   ms   01/23/17 Modified xil_printf statement in main function to
                     ensure that "Successfully ran" and "Failed" strings
                     are available in all examples. This is a fix for
                     CR-965028.
       ms   04/05/17 Added tabspace for return statements in functions for
                     proper documentation while generating doxygen and
                     modified filename tag to include the file in doxygen
                     examples.
 4.6   ht   07/07/23 Added support for system device-tree flow.
 4.9   ht   04/17/25 Update Canonical definition to be inline with xsct flow.
 4.10  vlt  12/14/25 Update Doxygen comments to include SDT flow details.
 4.10  ht   02/17/26 Fix GCC warnings for unused parameter.

#include "xmbox.h"
#include "xstatus.h"
#include "xparameters.h"
#include "xinterrupt_wrap.h"
#include "xil_exception.h"
#include "xil_cache.h"

Macros
#define	MY_CPU_ID XPAR_CPU_ID
	CPU ID definition for multi-processor systems. More...

#define	MSGSIZ 1024
	Size of the buffer for received message. More...

#define	HELLO_SIZE 40
	Size of the Hello Message. More...

#define	TIMEOUT_MAX_COUNT 0x10000000
	Max count to wait for message. More...

#define	MAILBOX_RIT 4
	Mailbox receive interrupt threshold. More...

#define	MAILBOX_SIT 4
	Mailbox send interrupt threshold. More...

#define	printf xil_printf
	A smaller footprint printf. More...

Functions
int	MailboxExample (UINTPTR BaseAddress)
	This function sends a message to and receives a message from the other processor. More...

int	MailboxExample_Send (XMbox *MboxInstancePtr, int CPU_Id, int Blocking)
	This function sends the hello message to the other processor. More...

int	MailboxExample_Receive (XMbox *MboxInstancePtr, int CPU_Id, int Blocking)
	This function receives a message from the other processor verifies it's the expected message. More...

int	MailboxExample_Wait (volatile int Count, char Name, int Threshold)
	This function waits for a particular variable to exceed the threshold value. More...

int	main (void)
	This function is the main function for the mailbox interrupt example. More...

Macro Definition Documentation

#define HELLO_SIZE 40

Size of the Hello Message.

Referenced by MailboxExample_Receive(), and MailboxExample_Send().

#define MAILBOX_RIT 4

Mailbox receive interrupt threshold.

#define MAILBOX_SIT 4

Mailbox send interrupt threshold.

#define MSGSIZ 1024

Size of the buffer for received message.

#define MY_CPU_ID XPAR_CPU_ID

CPU ID definition for multi-processor systems.

Referenced by MailboxExample(), and main().

#define printf xil_printf

A smaller footprint printf.

Referenced by MailboxExample_Receive(), MailboxExample_Send(), MailboxExample_Wait(), and main().

#define TIMEOUT_MAX_COUNT 0x10000000

Max count to wait for message.

Referenced by MailboxExample_Receive(), and MailboxExample_Wait().

Function Documentation

int MailboxExample ( UINTPTR BaseAddress )

This function sends a message to and receives a message from the other processor.

It also uses the interrupt to check whether the other processor has started to send or receive.

Parameters

BaseAddress contains the base address of the device

Returns

XST_SUCCESS if the test passes
XST_FAILURE if the test fails

Note: In XSCT/classic flow, DeviceId is used to look up the device configuration.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::IntrId, XMbox_Config::IntrParent, MailboxExample_Receive(), MailboxExample_Send(), MailboxExample_Wait(), MY_CPU_ID, XMbox_Config::UseFSL, XMbox_CfgInitialize(), and XMbox_LookupConfig().

Referenced by main().

int MailboxExample_Receive	(	XMbox *	MboxInstancePtr,
		int	CPU_Id,
		int	Blocking
	)

This function receives a message from the other processor verifies it's the expected message.

Parameters

MboxInstancePtr	is the instance pointer for the XMbox.
CPU_Id	is the CPU ID for the program that is running on.
Blocking	is set to 1 for the receive to block till the data is received.

Returns

XST_SUCCESS if the receive succeeds
XST_FAILURE if the receive fails

Note: None

References HELLO_SIZE, printf, TIMEOUT_MAX_COUNT, XMbox_Read(), and XMbox_ReadBlocking().

Referenced by MailboxExample().

int MailboxExample_Send	(	XMbox *	MboxInstancePtr,
		int	CPU_Id,
		int	Blocking
	)

This function sends the hello message to the other processor.

Parameters

MboxInstancePtr	is the instance pointer for the XMbox.
CPU_Id	is the CPU ID for the program that is running on.
Blocking	is set to 1 for the send to block till the data is sent.

Returns