| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071 |
- .. SPDX-License-Identifier: GPL-2.0
- Message Queues
- ==============
- Message queue is a simple low-capacity IPC channel between two VMs. It is
- intended for sending small control and configuration messages. Each message
- queue is unidirectional, so a full-duplex IPC channel requires a pair of queues.
- Messages can be up to 240 bytes in length. Longer messages require a further
- protocol on top of the message queue messages themselves. For instance, communication
- with the resource manager adds a header field for sending longer messages via multiple
- message fragments.
- The diagram below shows how message queue works. A typical configuration involves
- 2 message queues. Message queue 1 allows VM_A to send messages to VM_B. Message
- queue 2 allows VM_B to send messages to VM_A.
- 1. VM_A sends a message of up to 240 bytes in length. It raises a hypercall
- with the message to inform the hypervisor to add the message to
- message queue 1's queue. The hypervisor copies memory into the internal
- message queue representation; the memory doesn't need to be shared between
- VM_A and VM_B.
- 2. Gunyah raises the corresponding interrupt for VM_B (Rx vIRQ) when any of
- these happens:
- a. gh_msgq_send() has PUSH flag. Queue is immediately flushed. This is the typical case.
- b. Explicility with gh_msgq_push command from VM_A.
- c. Message queue has reached a threshold depth.
- 3. VM_B calls gh_msgq_recv() and Gunyah copies message to requested buffer.
- 4. Gunyah buffers messages in the queue. If the queue became full when VM_A added a message,
- the return values for gh_msgq_send() include a flag that indicates the queue is full.
- Once VM_B receives the message and, thus, there is space in the queue, Gunyah
- will raise the Tx vIRQ on VM_A to indicate it can continue sending messages.
- For VM_B to send a message to VM_A, the process is identical, except that hypercalls
- reference message queue 2's capability ID. Each message queue has its own independent
- vIRQ: two TX message queues will have two vIRQs (and two capability IDs).
- ::
- +---------------+ +-----------------+ +---------------+
- | VM_A | |Gunyah hypervisor| | VM_B |
- | | | | | |
- | | | | | |
- | | Tx | | | |
- | |-------->| | Rx vIRQ | |
- |gh_msgq_send() | Tx vIRQ |Message queue 1 |-------->|gh_msgq_recv() |
- | |<------- | | | |
- | | | | | |
- | Message Queue | | | | Message Queue |
- | driver | | | | driver |
- | | | | | |
- | | | | | |
- | | | | Tx | |
- | | Rx vIRQ | |<--------| |
- |gh_msgq_recv() |<--------|Message queue 2 | Tx vIRQ |gh_msgq_send() |
- | | | |-------->| |
- | | | | | |
- | | | | | |
- +---------------+ +-----------------+ +---------------+
- Gunyah message queues are exposed as mailboxes. To create the mailbox, create
- a mbox_client and call `gh_msgq_init()`. On receipt of the RX_READY interrupt,
- all messages in the RX message queue are read and pushed via the `rx_callback`
- of the registered mbox_client.
- .. kernel-doc:: drivers/mailbox/gunyah-msgq.c
- :identifiers: gh_msgq_init
|
