Commit 3d2115ea authored by Phil Elwell's avatar Phil Elwell Committed by Greg Kroah-Hartman
Browse files

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: default avatarPhil Elwell <phil@raspberrypi.com>
[wahrenst@gmx.net: Rewrite commit log]
Signed-off-by: default avatarStefan Wahren <wahrenst@gmx.net>
Signed-off-by: default avatarJai Luthra <jai.luthra@ideasonboard.com>
Link: https://patch.msgid.link/20251029-vchiq-destage-v3-3-da8d6c83c2c5@ideasonboard.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent e31d4d64

drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c

+7 −1
Original line number Diff line number Diff line
@@ -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;

drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h

+53 −3
Original line number Diff line number Diff line
@@ -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 */