Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
staging: vchiq_arm: Improve inline documentation
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@raspberrypi.com>
[wahrenst@gmx.net: Rewrite commit log]
Signed-off-by: Stefan Wahren <wahrenst@gmx.net>
Signed-off-by: Jai Luthra <jai.luthra@ideasonboard.com>
Link: https://patch.msgid.link/20251029-vchiq-destage-v3-3-da8d6c83c2c5@ideasonboard.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Phil Elwell
and committed by
Greg Kroah-Hartman
3d2115ea
e31d4d64
+60
-4
+7
-1
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
+7
-1
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
···
72
72
};
73
73
74
74
struct vchiq_arm_state {
75
-
/* Keepalive-related data */
75
+
/*
76
+
* Keepalive-related data
77
+
*
78
+
* The keepalive mechanism was retro-fitted to VCHIQ to allow active
79
+
* services to prevent the system from suspending.
80
+
* This feature is not used on Raspberry Pi devices.
81
+
*/
76
82
struct task_struct *ka_thread;
77
83
struct completion ka_evt;
78
84
atomic_t ka_use_count;
+53
-3
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
+53
-3
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
···
171
171
short release_count;
172
172
};
173
173
174
+
/*
175
+
* VCHIQ is a reliable connection-oriented datagram protocol.
176
+
*
177
+
* A VCHIQ service is equivalent to a TCP connection, except:
178
+
* + FOURCCs are used for the rendezvous, and port numbers are assigned at the
179
+
* time the connection is established.
180
+
* + There is less of a distinction between server and client sockets, the only
181
+
* difference being which end makes the first move.
182
+
* + For a multi-client server, the server creates new "listening" services as
183
+
* the existing one becomes connected - there is no need to specify the
184
+
* maximum number of clients up front.
185
+
* + Data transfer is reliable but packetized (messages have defined ends).
186
+
* + Messages can be either short (capable of fitting in a slot) and in-band,
187
+
* or copied between external buffers (bulk transfers).
188
+
*/
174
189
struct vchiq_service {
175
190
struct vchiq_service_base base;
176
191
unsigned int handle;
···
301
286
int debug[DEBUG_MAX];
302
287
};
303
288
289
+
/*
290
+
* vchiq_slot_zero describes the memory shared between the ARM host and the
291
+
* VideoCore VPU. The "master" and "slave" states are owned by the respective
292
+
* sides but visible to the other; the slots are shared, and the remaining
293
+
* fields are read-only.
294
+
*
295
+
* In the configuration used by this implementation, the memory is allocated
296
+
* by the host, the VPU is the master (the side which controls the DMA for bulk
297
+
* transfers), and the host is the slave.
298
+
*
299
+
* The ownership of slots changes with use:
300
+
* + When empty they are owned by the sender.
301
+
* + When partially filled they are shared with the receiver.
302
+
* + When completely full they are owned by the receiver.
303
+
* + When the receiver has finished processing the contents, they are recycled
304
+
* back to the sender.
305
+
*/
304
306
struct vchiq_slot_zero {
305
307
int magic;
306
308
short version;
···
332
300
struct vchiq_slot_info slots[VCHIQ_MAX_SLOTS];
333
301
};
334
302
303
+
/*
304
+
* This is the private runtime state used by each side. The same structure was
305
+
* originally used by both sides, but implementations have since diverged.
306
+
*/
335
307
struct vchiq_state {
336
308
struct device *dev;
337
309
int id;
···
357
321
struct mutex mutex;
358
322
struct vchiq_instance **instance;
359
323
360
-
/* Processes incoming messages */
324
+
/* Processes all incoming messages which aren't synchronous */
361
325
struct task_struct *slot_handler_thread;
362
326
363
-
/* Processes recycled slots */
327
+
/*
328
+
* Slots which have been fully processed and released by the (peer)
329
+
* receiver are added to the receiver queue, which is asynchronously
330
+
* processed by the recycle thread.
331
+
*/
364
332
struct task_struct *recycle_thread;
365
333
366
-
/* Processes synchronous messages */
334
+
/*
335
+
* Processes incoming synchronous messages
336
+
*
337
+
* The synchronous message channel is shared between all synchronous
338
+
* services, and provides a way for urgent messages to bypass
339
+
* potentially long queues of asynchronous messages in the normal slots.
340
+
*
341
+
* There can be only one outstanding synchronous message in
342
+
* each direction, and as a precious shared resource synchronous
343
+
* services should be used sparingly.
344
+
*/
367
345
struct task_struct *sync_thread;
368
346
369
347
/* Local implementation of the trigger remote event */