[PATCH v2] staging: most: video: document lock fields

[Hussain Sitamouwala]

Fix checkpatch.pl checks:

CHECK: spinlock_t definition without comment
CHECK: struct mutex definition without comment

Document what each lock in struct most_video_dev serializes, based on
how they are used. list_lock serializes changes to pending_mbos and the
mute check in comp_rx_data(). lock is set as vdev->lock and is held by
video_ioctl2() around the ioctl handlers.

No functional change.

Signed-off-by: Hussain Sitamouwala <husainsitamuwala21@xxxxxxxxx>
---
Changes in v2:
 - Replaced the short comments with ones based on an audit of how each
   lock is used, as Dan Carpenter asked.

Audit notes:
 - list_lock: comp_rx_data() takes it to check mute and add to
   pending_mbos. comp_vdev_close() takes it to set mute and empty the
   list, and comp_vdev_read() takes it around list_del().
 - data_ready() and get_top_mbo() read pending_mbos without the lock
   in read() and poll(). Only one client can open the device
   (access_ref), so this looks benign, but I did not change it.
 - mute is cleared in comp_vdev_close() without the lock, after
   most_stop_channel(). I assumed the core delivers no more buffers
   after that call. Please correct me if that is wrong.
 - lock is set as vdev->lock, so video_ioctl2() holds it around the
   ioctl handlers, which covers ctrl_input.

 drivers/staging/most/video/video.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/staging/most/video/video.c b/drivers/staging/most/video/video.c
index 3a0445ff62f4..94f1dc994217 100644
--- a/drivers/staging/most/video/video.c
+++ b/drivers/staging/most/video/video.c
@@ -33,6 +33,10 @@ struct most_video_dev {
 	bool mute;
 
 	struct list_head pending_mbos;
+	/*
+	 * Serializes additions to and removals from pending_mbos, and the
+	 * mute check in comp_rx_data(), which runs in MOST core context.
+	 */
 	spinlock_t list_lock;
 
 	struct v4l2_device v4l2_dev;
@@ -40,6 +44,7 @@ struct most_video_dev {
 	struct video_device *vdev;
 	unsigned int ctrl_input;
 
+	/* Set as vdev->lock: held by video_ioctl2() while it calls the ioctl handlers */
 	struct mutex lock;
 
 	wait_queue_head_t wait_data;
-- 
2.53.0