staging: vchiq_arm: Add the requested explanations

Replace the TODO items with explanations largely derived by reading the
code.

Signed-off-by: Phil Elwell <[email protected]>

Author: pelwell

drivers/staging/vc04_services/Documentation/vchiq-cdev

@@ -6,40 +6,82 @@ Description:
 		The ioctl interface for the VCHIQ character device.
 		Following actions are supported:
 
-		/* TODO: Please explain each IOCTL in short */
-
 		* VCHIQ_IOC_CONNECT:
+		  Establish/confirm the link to the VPU peer.
 
 		* VCHIQ_IOC_SHUTDOWN:
+		  Close the link to the VPU peer, removing all services.
 
 		* VCHIQ_IOC_CREATE_SERVICE:
+		  Create a VCHIQ service with the given FOURCC, registering a
+		  callback. If is_open is true, attempt to connect to the same
+		  FOURCC on the peer. If successful, populates the handle field
+		  in the parameter structure, otherwise returns an error.
 
 		* VCHIQ_IOC_REMOVE_SERVICE:
+		  Close and remove the service indicated by the provided
+		  handle.
 
 		* VCHIQ_IOC_QUEUE_MESSAGE:
+		  Adds the given in-band message for the indicated server to
+		  the queue.
 
 		* VCHIQ_IOC_QUEUE_BULK_TRANSMIT:
+		  Adds the given out-of-band bulk message for the indicated
+		  service to the bulk queue.
 
 		* VCHIQ_IOC_QUEUE_BULK_RECEIVE:
+		  Adds the given out-of-band bulk buffer for data from the
+		  indicated service to the bulk queue.
 
 		* VCHIQ_IOC_AWAIT_COMPLETION:
+		  The in-kernel API allows direct callbacks to client code.
+		  Userspace clients rely on the equivalent of an RPC, with the
+		  parameters for each callback marshalled into structures
+		  called completions. This method blocks waiting for
+		  completions to process.
 
 		* VCHIQ_IOC_DEQUEUE_MESSAGE:
+		  Copy the next message for the indicated service, releasing
+		  the space that was occupied. Optionally blocks if no message
+		  is waiting.
 
 		* VCHIQ_IOC_GET_CLIENT_ID:
+		  Retrieve an identifier for the client. This is intended to
+		  allow instances of multiple services to be grouped. For
+		  services provided by Linux the client ID is the pid. VPU
+		  services have a client ID of 1.
 
 		* VCHIQ_IOC_GET_CONFIG:
+		  Returns various properties of the VCHIQ configuration, such
+		  as the maximum message size and version numbers.
 
 		* VCHIQ_IOC_CLOSE_SERVICE:
+		  Cause a service to disconnect from the peer, returning it to
+		  the closed/listening state, i.e. REMOVE_SERVICE but without
+		  destroying the service.
 
 		* VCHIQ_IOC_USE_SERVICE:
-
 		* VCHIQ_IOC_RELEASE_SERVICE:
+		  Use to mark the start and end of activity on a service. An
+		  active service is intended to prevent the system from
+		  suspending. N.B. Raspberry Pi devices that run VCHIQ do not
+		  implement suspend/resume.
 
 		* VCHIQ_IOC_SET_SERVICE_OPTION:
+		  Sets a number of per-service options: AUTOCLOSE, SLOT_QUOTA,
+		  MESSAGE_QUOTA, SYNCHRONOUS mode and TRACE.
 
 		* VCHIQ_IOC_DUMP_PHYS_MEM:
+		  No longer implemented.
 
 		* VCHIQ_IOC_LIB_VERSION:
+		  Notify the kernel of the version of the userspace VCHIQ
+		  library being used. Currently used to determine if the
+		  CLOSE_DELIVERED ioctl is used, and therefore whether to
+		  wait for the extra handshake on a close.
 
 		* VCHIQ_IOC_CLOSE_DELIVERED:
+		  Signal that the userspace code has finished processing the
+		  close. This additional handshake avoids a race on service
+		  closure.

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

@@ -82,9 +82,12 @@ static const struct vchiq_platform_info bcm2711_info = {
 };
 
 struct vchiq_arm_state {
-	/* Keepalive-related data */
-	/* TODO: Please elaborate the purpose of this thread
-	 * What needs to be kept alive?
+	/*
+	 * 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;

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

@@ -174,7 +174,21 @@ struct vchiq_slot_info {
 	short release_count;
 };
 
-/* TODO: Please explain the meaning of "service" in the context of VCHIQ */
+/*
+ * 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 packetised (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;
@@ -291,8 +305,21 @@ struct vchiq_shared_state {
 };
 
 /*
- * TODO: Mark all structs which are shared with the VideoCore and must not
- * be modified (ABI)
+ * 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 owmership 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;
@@ -308,6 +335,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;
@@ -329,18 +360,27 @@ struct vchiq_state {
 	struct mutex mutex;
 	struct vchiq_instance **instance;
 
-	/* Processes incoming messages */
-	/* TODO: This is the only thread which handles incoming messages
-	 *       or just asynchronous messages ?
-	 */
+	/* This thread processes all incoming messages which aren't synchronous */
 	struct task_struct *slot_handler_thread;
 
-	/* Processes recycled slots */
-	/* TODO: Please elaborate more ... (purpose) */
+	/*
+	 * 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 */
-	/* TODO: Please elaborate more ... (direction, purpose) */
+	/*
+	 * Processes incoming synchronous messagses
+	 *
+	 * 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 */