1.. SPDX-License-Identifier: GPL-2.0 2 3Message Queues 4============== 5Message queue is a simple low-capacity IPC channel between two virtual machines. 6It is intended for sending small control and configuration messages. Each 7message queue is unidirectional and buffered in the hypervisor. A full-duplex 8IPC channel requires a pair of queues. 9 10The size of the queue and the maximum size of the message that can be passed is 11fixed at creation of the message queue. Resource manager is presently the only 12use case for message queues, and creates messages queues between itself and VMs 13with a fixed maximum message size of 240 bytes. Longer messages require a 14further protocol on top of the message queue messages themselves. For instance, 15communication with the resource manager adds a header field for sending longer 16messages which are split into smaller fragments. 17 18The diagram below shows how message queue works. A typical configuration 19involves 2 message queues. Message queue 1 allows VM_A to send messages to VM_B. 20Message queue 2 allows VM_B to send messages to VM_A. 21 221. VM_A sends a message of up to 240 bytes in length. It makes a hypercall 23 with the message to request the hypervisor to add the message to 24 message queue 1's queue. The hypervisor copies memory into the internal 25 message queue buffer; the memory doesn't need to be shared between 26 VM_A and VM_B. 27 282. Gunyah raises the corresponding interrupt for VM_B (Rx vIRQ) when any of 29 these happens: 30 31 a. gunyah_msgq_send() has PUSH flag. This is a typical case when the message 32 queue is being used to implement an RPC-like interface. 33 b. Explicitly with gunyah_msgq_push hypercall from VM_A. 34 c. Message queue has reached a threshold depth. Typically, this threshold 35 depth is the size of the queue (in other words: when queue is full, Rx 36 vIRQ is raised). 37 383. VM_B calls gunyah_msgq_recv() and Gunyah copies message to requested buffer. 39 404. Gunyah raises the corresponding interrupt for VM_A (Tx vIRQ) when the message 41 queue falls below a watermark depth. Typically, this is when the queue is 42 drained. Note the watermark depth and the threshold depth for the Rx vIRQ are 43 independent values. Coincidentally, this signal is conceptually similar to 44 Clear-to-Send. 45 46For VM_B to send a message to VM_A, the process is identical, except that 47hypercalls reference message queue 2's capability ID. The IRQ will be different 48for the second message queue. 49 50:: 51 52 +-------------------+ +-----------------+ +-------------------+ 53 | VM_A | |Gunyah hypervisor| | VM_B | 54 | | | | | | 55 | | | | | | 56 | | Tx | | | | 57 | |-------->| | Rx vIRQ | | 58 |gunyah_msgq_send() | Tx vIRQ |Message queue 1 |-------->|gunyah_msgq_recv() | 59 | |<------- | | | | 60 | | | | | | 61 | | | | | | 62 | | | | Tx | | 63 | | Rx vIRQ | |<--------| | 64 |gunyah_msgq_recv() |<--------|Message queue 2 | Tx vIRQ |gunyah_msgq_send() | 65 | | | |-------->| | 66 | | | | | | 67 | | | | | | 68 +-------------------+ +-----------------+ +---------------+ 69