Using the Mailbox - 2022.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2022.1 English

The main advantage of auto-restarting kernels is that they run semi-autonomously operating as data-driven kernels without the need for frequent interaction with the host application and for software control. But auto-restarting kernels also offer semi-synchronization through the mailbox, which is the ability to exchange data with the host application in an asynchronous, non-blocking, and safe way. For software controlled kernels, the kernel follows the C-semantics of call and return. The input arguments are read at the start of kernel execution, and the output arguments are written at the end of each kernel execution. However, in the auto-restart kernel, the kernel is managed in hardware, offering many of the performance advantages of a Free-Running Kernel, so that once started by the host code it is automatically restarted until explicitly stopped. The host code can also query the status of the kernel to determine when it actually has finished executing after being instructed to do so. The host application and auto-restarting kernel use the following communications protocol:

  • For passing argument values from the host to the kernel, the mailbox implements a set of double-buffered s_axilite mapped registers to ensure non-blocking communication and consistent passing of inputs by the host code and passing of outputs by the kernel.
  • Whenever the host code writes to an input argument, it changes the host-side copy. The kernel running in hardware does not see that change. After the host code requests a mailbox write, the next time the kernel automatically restarts the copy of the registers that are seen by the kernel is consistently updated. Hence the host code can write any number of arguments in any order, and the kernel does not see these updates until the host code requests a mailbox write, and the kernel restarts.
    Tip: If some arguments are arrays mapped to s_axilite register files, then the entire array must be written between successive mailbox writes because it is implemented as a ping-pong buffer.
  • The same process occurs on the output side when the kernel writes to the kernel side register and requests a mailbox read. The next time the kernel is done, the values of the s_axilite mapped output arguments are updated, and the host code can read them as needed.

Hence the host application has the following criteria:

  • Not in charge of providing input data at every execution of the kernel and collecting output data at its finish, as it would be in the case of software controlled kernels.
  • Involved in occasionally setting and updating some kernel input parameters (for example, routing tables, etc.) and checking the status of the kernel computation. This semi-synchronization operation is typically done without a fixed communication rate between the host and kernel.
  • When the host application has a new set of parameters to send to the hardware kernel, it does so without caring where the hardware kernel is in its computation. When the host application needs to check the status of the hardware kernel, it does so without caring where exactly the hardware is in its computation. It is satisfied only that the parameter update and status check is performed consistently for the hardware.