Message-Id: <20251029-vchiq-destage-v3-3-da8d6c83c2c5@ideasonboard.com>
Date: Wed, 29 Oct 2025 16:00:07 +0530
From: Jai Luthra <jai.luthra@...asonboard.com>
To: Florian Fainelli <florian.fainelli@...adcom.com>, 
 Broadcom internal kernel review list <bcm-kernel-feedback-list@...adcom.com>, 
 Greg Kroah-Hartman <gregkh@...uxfoundation.org>, 
 Ray Jui <rjui@...adcom.com>, Scott Branden <sbranden@...adcom.com>
Cc: linux-rpi-kernel@...ts.infradead.org, 
 linux-arm-kernel@...ts.infradead.org, linux-staging@...ts.linux.dev, 
 linux-kernel@...r.kernel.org, kernel-list@...pberrypi.com, 
 Stefan Wahren <wahrenst@....net>, 
 Dave Stevenson <dave.stevenson@...pberrypi.com>, 
 Laurent Pinchart <laurent.pinchart@...asonboard.com>, 
 Kieran Bingham <kieran.bingham@...asonboard.com>, 
 Phil Elwell <phil@...pberrypi.com>, Umang Jain <uajain@...lia.com>, 
 Jai Luthra <jai.luthra@...asonboard.com>
Subject: [PATCH v3 3/7] staging: vchiq_arm: Improve inline documentation

From: Phil Elwell <phil@...pberrypi.com>

Add more comments to the VCHIQ driver, which provides some
high-level descriptions how things work.

Link: https://github.com/raspberrypi/linux/pull/6801
Signed-off-by: Phil Elwell <phil@...pberrypi.com>
[wahrenst@....net: Rewrite commit log]
Signed-off-by: Stefan Wahren <wahrenst@....net>
Signed-off-by: Jai Luthra <jai.luthra@...asonboard.com>
---
 drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c  |  8 +++++++-
 drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
index c84304dfcdc96742f0f0ef655642a7de69552c3c..a2074069e79e80456a382523b68a6f62116f796c 100644
--- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
+++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
@@ -72,7 +72,13 @@ static const struct vchiq_platform_info bcm2836_info = {
 };
 
 struct vchiq_arm_state {
-	/* Keepalive-related data */
+	/*
+	 * Keepalive-related data
+	 *
+	 * The keepalive mechanism was retro-fitted to VCHIQ to allow active
+	 * services to prevent the system from suspending.
+	 * This feature is not used on Raspberry Pi devices.
+	 */
 	struct task_struct *ka_thread;
 	struct completion ka_evt;
 	atomic_t ka_use_count;
diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
index 9b4e766990a493d6e9d4e0604f2c84f4e7b77804..e3ed50d26c37eb767df43c6cea6b5f0826fada61 100644
--- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
+++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
@@ -171,6 +171,21 @@ struct vchiq_slot_info {
 	short release_count;
 };
 
+/*
+ * VCHIQ is a reliable connection-oriented datagram protocol.
+ *
+ * A VCHIQ service is equivalent to a TCP connection, except:
+ * + FOURCCs are used for the rendezvous, and port numbers are assigned at the
+ *   time the connection is established.
+ * + There is less of a distinction between server and client sockets, the only
+ *   difference being which end makes the first move.
+ * + For a multi-client server, the server creates new "listening" services as
+ *   the existing one becomes connected - there is no need to specify the
+ *   maximum number of clients up front.
+ * + Data transfer is reliable but packetized (messages have defined ends).
+ * + Messages can be either short (capable of fitting in a slot) and in-band,
+ *   or copied between external buffers (bulk transfers).
+ */
 struct vchiq_service {
 	struct vchiq_service_base base;
 	unsigned int handle;
@@ -286,6 +301,23 @@ struct vchiq_shared_state {
 	int debug[DEBUG_MAX];
 };
 
+/*
+ * vchiq_slot_zero describes the memory shared between the ARM host and the
+ * VideoCore VPU. The "master" and "slave" states are owned by the respective
+ * sides but visible to the other; the slots are shared, and the remaining
+ * fields are read-only.
+ *
+ * In the configuration used by this implementation, the memory is allocated
+ * by the host, the VPU is the master (the side which controls the DMA for bulk
+ * transfers), and the host is the slave.
+ *
+ * The ownership of slots changes with use:
+ * + When empty they are owned by the sender.
+ * + When partially filled they are shared with the receiver.
+ * + When completely full they are owned by the receiver.
+ * + When the receiver has finished processing the contents, they are recycled
+ *   back to the sender.
+ */
 struct vchiq_slot_zero {
 	int magic;
 	short version;
@@ -300,6 +332,10 @@ struct vchiq_slot_zero {
 	struct vchiq_slot_info slots[VCHIQ_MAX_SLOTS];
 };
 
+/*
+ * This is the private runtime state used by each side. The same structure was
+ * originally used by both sides, but implementations have since diverged.
+ */
 struct vchiq_state {
 	struct device *dev;
 	int id;
@@ -321,13 +357,27 @@ struct vchiq_state {
 	struct mutex mutex;
 	struct vchiq_instance **instance;
 
-	/* Processes incoming messages */
+	/* Processes all incoming messages which aren't synchronous */
 	struct task_struct *slot_handler_thread;
 
-	/* Processes recycled slots */
+	/*
+	 * Slots which have been fully processed and released by the (peer)
+	 * receiver are added to the receiver queue, which is asynchronously
+	 * processed by the recycle thread.
+	 */
 	struct task_struct *recycle_thread;
 
-	/* Processes synchronous messages */
+	/*
+	 * Processes incoming synchronous messages
+	 *
+	 * The synchronous message channel is shared between all synchronous
+	 * services, and provides a way for urgent messages to bypass
+	 * potentially long queues of asynchronous messages in the normal slots.
+	 *
+	 * There can be only one outstanding synchronous message in
+	 * each direction, and as a precious shared resource synchronous
+	 * services should be used sparingly.
+	 */
 	struct task_struct *sync_thread;
 
 	/* Local implementation of the trigger remote event */

-- 
2.51.0

Powered by blists - more mailing lists