[Qemu-devel] Question on ioeventfd behavior

[Markus Armbruster]

Unlike much of QEMU, memory.h actually has useful contracts, much
appreciated.  Here's the one in question:

/**
 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
 *                            is written to a location.
 *
 * Marks a word in an IO region (initialized with memory_region_init_io())
 * as a trigger for an eventfd event.  The I/O callback will not be called.
 * The caller must be prepared to handle failure (that is, take the required
 * action if the callback _is_ called).
 *
 * @mr: the memory region being updated.
 * @addr: the address within @mr that is to be monitored
 * @size: the size of the access to trigger the eventfd
 * @match_data: whether to match against @data, instead of just @addr
 * @data: the data to match against the guest write
 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
 **/
void memory_region_add_eventfd(MemoryRegion *mr,
                               hwaddr addr,
                               unsigned size,
                               bool match_data,
                               uint64_t data,
                               EventNotifier *e);

ivshmem uses it to implement its Doorbell register efficiently:

    memory_region_add_eventfd(&s->ivshmem_mmio,
                              DOORBELL,
                              4,
                              true,
                              (posn << 16) | i,
                              &s->peers[posn].eventfds[i]);

This runs for every (posn, i) pair in use.  The contract makes perfectly
clear what happens when the value written matches and everything works:
the matching s->peers[posn].eventfds[i] gets notified.

What exactly does "The caller must be prepared to handle failure" mean?
What are the failure modes?

Does "value written doesn't match" count as failure in the sense of this
clause?  Rephrasing my question: what happens when the guest writes a
value to the Doorbell register that does not match any of the values
registered with memory_region_add_eventfd()?  Is the I/O callback
called exactly as if ioeventfd was not in use?