AI Engine I/O Transaction - 2024.1 English

AI Engine System Software Driver Reference Manual (UG1642)

Document ID
Release Date
2024.1 English

In the case of Linux runtime, if every I/O write goes to Linux kernel, there is a lot of userspace to kernel space and memory copying overhead to complete operations for a group of tiles. I/O transactions reduce the overhead by caching the I/O write commands in the userspace until you send the whole transaction to the kernel space. The AI Engine driver maintains transactions and their buffers per thread. You can also export transactions from its own thread and use the exported transaction later. The following diagram shows the flows of transactions.

Figure 1. I/O with Transaction Mode
Figure 2. I/O Transaction Auto Flush

When the read/poll operation is called, by default the AI Engine driver auto flushes the commands in the transaction buffer of the thread. Start transaction has a flag argument to allow you to set the AI Engine driver to not auto flush but error out if read and poll operations are called after start transaction is called.

Figure 3. Export I/O Transaction

The transaction of a thread can be exported for you to use later.

Figure 4. Linux AI Engine Partition Kernel Driver

In the case of Linux, whenever the transaction buffer allocation happens, it registers the memory to the AI Engine partition kernel driver to pin the buffer. When the transaction is submitted, the Linux kernel can directly use the buffer instead of copying from userspace to kernel space. When the buffer is freed, the AI Engine driver unregisters the buffer from kernel drive to unpin it.

The number of transactions that are successfully executed with I/O backends is not returned because the I/O backend prints which I/O failed and you do not have the details to know which I/O is for which operation. Thus, printing which I/O failed from the backend is sufficient for debugging.

The I/O writes and mask writes are buffered in the transaction buffer after you call to start transaction. The transaction buffers are sent to I/O backend to execute when you call submit transaction, or when there is read I/O required for the operation. If you call export transaction, the I/O commands saved in the I/O transaction buffer are saved into the user defined buffer. You can resubmit the I/O transactions. The I/O transaction can fail due to the following reasons:

  • Access invalid address, which is a driver bug
  • Access gated tiles, which is a driver bug
  • Failed to allocate more memory for transaction buffer if the existing transaction memory is not large enough.

For the previously mentioned reasons, the AI Engine driver returns different error codes. It returns XAIE_ERR for the first two failures and returns no memory for the last reason.