github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-24 15:12:13 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

staging: vchiq_arm: Improve inline documentation

Browse Source 
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>
This commit is contained in:
Phil Elwell 2025-10-29 16:00:07 +05:30 committed by Greg Kroah-Hartman
parent e31d4d6470
commit 3d2115ea5d
2 changed files with 60 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
View File

@ -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;

56
drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
View File

@ -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 */