1.. SPDX-License-Identifier: GPL-2.0 2 3Message Queues 4============== 5Message queue is a simple low-capacity IPC channel between two VMs. It is 6intended for sending small control and configuration messages. Each message 7queue is unidirectional, so a full-duplex IPC channel requires a pair of queues. 8 9Messages can be up to 240 bytes in length. Longer messages require a further 10protocol on top of the message queue messages themselves. For instance, communication 11with the resource manager adds a header field for sending longer messages via multiple 12message fragments. 13 14The diagram below shows how message queue works. A typical configuration involves 152 message queues. Message queue 1 allows VM_A to send messages to VM_B. Message 16queue 2 allows VM_B to send messages to VM_A. 17 181. VM_A sends a message of up to 240 bytes in length. It raises a hypercall 19 with the message to inform the hypervisor to add the message to 20 message queue 1's queue. The hypervisor copies memory into the internal 21 message queue representation; the memory doesn't need to be shared between 22 VM_A and VM_B. 23 242. Gunyah raises the corresponding interrupt for VM_B (Rx vIRQ) when any of 25 these happens: 26 27 a. gh_msgq_send() has PUSH flag. Queue is immediately flushed. This is the typical case. 28 b. Explicility with gh_msgq_push command from VM_A. 29 c. Message queue has reached a threshold depth. 30 313. VM_B calls gh_msgq_recv() and Gunyah copies message to requested buffer. 32 334. Gunyah buffers messages in the queue. If the queue became full when VM_A added a message, 34 the return values for gh_msgq_send() include a flag that indicates the queue is full. 35 Once VM_B receives the message and, thus, there is space in the queue, Gunyah 36 will raise the Tx vIRQ on VM_A to indicate it can continue sending messages. 37 38For VM_B to send a message to VM_A, the process is identical, except that hypercalls 39reference message queue 2's capability ID. Each message queue has its own independent 40vIRQ: two TX message queues will have two vIRQs (and two capability IDs). 41 42:: 43 44 +---------------+ +-----------------+ +---------------+ 45 | VM_A | |Gunyah hypervisor| | VM_B | 46 | | | | | | 47 | | | | | | 48 | | Tx | | | | 49 | |-------->| | Rx vIRQ | | 50 |gh_msgq_send() | Tx vIRQ |Message queue 1 |-------->|gh_msgq_recv() | 51 | |<------- | | | | 52 | | | | | | 53 | Message Queue | | | | Message Queue | 54 | driver | | | | driver | 55 | | | | | | 56 | | | | | | 57 | | | | Tx | | 58 | | Rx vIRQ | |<--------| | 59 |gh_msgq_recv() |<--------|Message queue 2 | Tx vIRQ |gh_msgq_send() | 60 | | | |-------->| | 61 | | | | | | 62 | | | | | | 63 +---------------+ +-----------------+ +---------------+ 64 65Gunyah message queues are exposed as mailboxes. To create the mailbox, create 66a mbox_client and call `gh_msgq_init()`. On receipt of the RX_READY interrupt, 67all messages in the RX message queue are read and pushed via the `rx_callback` 68of the registered mbox_client. 69 70.. kernel-doc:: drivers/mailbox/gunyah-msgq.c 71 :identifiers: gh_msgq_init 72