[media] staging: easycap: Clean comment style in easycap_usb_probe()

Some of these comments may still need to be reviewed.
This patch only cleans the comment style.

Signed-off-by: Ezequiel Garcia <elezegarcia@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 79 insertions, 164 deletions

diff --git a/drivers/staging/media/easycap/easycap_main.c b/drivers/staging/media/easycap/easycap_main.c
index 3d439b790cc..95f3cc1867d 100644
--- a/drivers/staging/media/easycap/easycap_main.c
+++ b/drivers/staging/media/easycap/easycap_main.c
@@ -2849,13 +2849,11 @@ static const struct v4l2_file_operations v4l2_fops = {
         .poll           = easycap_poll,
         .mmap           = easycap_mmap,
 };
-/*****************************************************************************/
-/*---------------------------------------------------------------------------*/
+
 /*
- *  WHEN THE EasyCAP IS PHYSICALLY PLUGGED IN, THIS FUNCTION IS CALLED THREE
- *  TIMES, ONCE FOR EACH OF THE THREE INTERFACES.  BEWARE.
+ * When the device is plugged, this function is called three times,
+ * one for each interface.
  */
-/*---------------------------------------------------------------------------*/
 static int easycap_usb_probe(struct usb_interface *intf,
                             const struct usb_device_id *id)
 {
@@ -2884,7 +2882,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
 
         usbdev = interface_to_usbdev(intf);
 
-/*---------------------------------------------------------------------------*/
         alt = usb_altnum_to_altsetting(intf, 0);
         if (!alt) {
                 SAY("ERROR: usb_host_interface not found\n");
@@ -2896,11 +2893,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 SAY("ERROR: intf_descriptor is NULL\n");
                 return -EFAULT;
         }
-/*---------------------------------------------------------------------------*/
-/*
- *  GET PROPERTIES OF PROBED INTERFACE
- */
-/*---------------------------------------------------------------------------*/
+
+        /* Get properties of probed interface */
         bInterfaceNumber = interface->bInterfaceNumber;
         bInterfaceClass = interface->bInterfaceClass;
         bInterfaceSubClass = interface->bInterfaceSubClass;
@@ -2912,28 +2906,23 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 (long int)(intf->cur_altsetting - intf->altsetting));
         JOT(4, "intf[%i]: bInterfaceClass=0x%02X bInterfaceSubClass=0x%02X\n",
                         bInterfaceNumber, bInterfaceClass, bInterfaceSubClass);
-/*---------------------------------------------------------------------------*/
-/*
- *  A NEW struct easycap IS ALWAYS ALLOCATED WHEN INTERFACE 0 IS PROBED.
- *  IT IS NOT POSSIBLE HERE TO FREE ANY EXISTING struct easycap.  THIS
- *  SHOULD HAVE BEEN DONE BY easycap_delete() WHEN THE EasyCAP WAS
- *  PHYSICALLY UNPLUGGED.
- *
- *  THE POINTER peasycap TO THE struct easycap IS REMEMBERED WHEN
- *  INTERFACES 1 AND 2 ARE PROBED.
-*/
-/*---------------------------------------------------------------------------*/
+
+        /*
+         * A new struct easycap is always allocated when interface 0 is probed.
+         * It is not possible here to free any existing struct easycap.
+         * This should have been done by easycap_delete() when the device was
+         * physically unplugged.
+         * The allocated struct easycap is saved for later usage when
+         * interfaces 1 and 2 are probed.
+         */
         if (0 == bInterfaceNumber) {
                 peasycap = kzalloc(sizeof(struct easycap), GFP_KERNEL);
                 if (!peasycap) {
                         SAY("ERROR: Could not allocate peasycap\n");
                         return -ENOMEM;
                 }
-/*---------------------------------------------------------------------------*/
-/*
- *  PERFORM URGENT INTIALIZATIONS ...
-*/
-/*---------------------------------------------------------------------------*/
+
+                /* Perform urgent initializations */
                 peasycap->minor = -1;
                 kref_init(&peasycap->kref);
                 JOM(8, "intf[%i]: after kref_init(..._video) "
@@ -2976,11 +2965,7 @@ static int easycap_usb_probe(struct usb_interface *intf,
 
                 peasycap->allocation_video_struct = sizeof(struct easycap);
 
-/*---------------------------------------------------------------------------*/
-/*
- *  ... AND FURTHER INITIALIZE THE STRUCTURE
-*/
-/*---------------------------------------------------------------------------*/
+                /* and further initialize the structure */
                 peasycap->pusb_device = usbdev;
                 peasycap->pusb_interface = intf;
 
@@ -3002,11 +2987,7 @@ static int easycap_usb_probe(struct usb_interface *intf,
 
                 peasycap->frame_buffer_many = FRAME_BUFFER_MANY;
 
-/*---------------------------------------------------------------------------*/
-/*
- *  DYNAMICALLY FILL IN THE AVAILABLE FORMATS ...
- */
-/*---------------------------------------------------------------------------*/
+                /* Dynamically fill in the available formats */
                 rc = easycap_video_fillin_formats();
                 if (0 > rc) {
                         SAM("ERROR: fillin_formats() rc = %i\n", rc);
@@ -3014,10 +2995,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 }
                 JOM(4, "%i formats available\n", rc);
 
-                /*  ... AND POPULATE easycap.inputset[] */
-
+                /* Populate easycap.inputset[] */
                 inputset = peasycap->inputset;
-
                 fmtidx = peasycap->ntsc ? NTSC_M : PAL_BGHIN;
                 m = 0;
                 mask = 0;
@@ -3030,7 +3009,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                                 mask = easycap_standard[i].mask;
                         }
                 }
-
                 if (1 != m) {
                         SAM("ERROR: "
                             "inputset->standard_offset unpopulated, %i=m\n", m);
@@ -3089,14 +3067,13 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 JOM(4, "populated inputset[]\n");
                 JOM(4, "finished initialization\n");
         } else {
-/*---------------------------------------------------------------------------*/
-/*
- *                                 FIXME
- *
- *  IDENTIFY THE APPROPRIATE POINTER peasycap FOR INTERFACES 1 AND 2.
- *  THE ADDRESS OF peasycap->pusb_device IS RELUCTANTLY USED FOR THIS PURPOSE.
- */
-/*---------------------------------------------------------------------------*/
+
+                /*
+                 * FIXME: Identify the appropriate pointer
+                 * peasycap for interfaces 1 and 2.
+                 * The address of peasycap->pusb_device
+                 * is reluctantly used for this purpose.
+                 */
                 for (ndong = 0; ndong < DONGLE_MANY; ndong++) {
                         if (usbdev == easycapdc60_dongle[ndong].peasycap->
                                                                         pusb_device) {
@@ -3117,7 +3094,7 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         return -ENODEV;
                 }
         }
-/*---------------------------------------------------------------------------*/
+
         if ((USB_CLASS_VIDEO == bInterfaceClass) ||
             (USB_CLASS_VENDOR_SPEC == bInterfaceClass)) {
                 if (-1 == peasycap->video_interface) {
@@ -3149,14 +3126,12 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         }
                 }
         }
-/*---------------------------------------------------------------------------*/
-/*
- *  INVESTIGATE ALL ALTSETTINGS.
- *  DONE IN DETAIL BECAUSE USB DEVICE 05e1:0408 HAS DISPARATE INCARNATIONS.
- */
-/*---------------------------------------------------------------------------*/
-        isokalt = 0;
 
+        /*
+         * Investigate all altsettings. This is done in detail
+         * because USB device 05e1:0408 has disparate incarnations.
+         */
+        isokalt = 0;
         for (i = 0; i < intf->num_altsetting; i++) {
                 alt = usb_altnum_to_altsetting(intf, i);
                 if (!alt) {
@@ -3172,7 +3147,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 if (0 == interface->bNumEndpoints)
                         JOM(4, "intf[%i]alt[%i] has no endpoints\n",
                                                 bInterfaceNumber, i);
-/*---------------------------------------------------------------------------*/
                 for (j = 0; j < interface->bNumEndpoints; j++) {
                         ep = &alt->endpoint[j].desc;
                         if (!ep) {
@@ -3312,19 +3286,12 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         }
                 }
         }
-/*---------------------------------------------------------------------------*/
-/*
- *  PERFORM INITIALIZATION OF THE PROBED INTERFACE
- */
-/*---------------------------------------------------------------------------*/
+
+        /* Perform initialization of the probed interface */
         JOM(4, "initialization begins for interface %i\n",
                 interface->bInterfaceNumber);
         switch (bInterfaceNumber) {
-/*---------------------------------------------------------------------------*/
-/*
- *  INTERFACE 0 IS THE VIDEO INTERFACE
- */
-/*---------------------------------------------------------------------------*/
+        /* 0: Video interface */
         case 0: {
                 if (!peasycap) {
                         SAM("MISTAKE: peasycap is NULL\n");
@@ -3337,11 +3304,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 peasycap->video_altsetting_on = okalt[isokalt - 1];
                 JOM(4, "%i=video_altsetting_on <====\n",
                                         peasycap->video_altsetting_on);
-/*---------------------------------------------------------------------------*/
-/*
- *  DECIDE THE VIDEO STREAMING PARAMETERS
- */
-/*---------------------------------------------------------------------------*/
+
+                /* Decide video streaming parameters */
                 peasycap->video_endpointnumber = okepn[isokalt - 1];
                 JOM(4, "%i=video_endpointnumber\n", peasycap->video_endpointnumber);
                 maxpacketsize = okmps[isokalt - 1];
@@ -3373,7 +3337,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         SAM("MISTAKE: peasycap->video_isoc_buffer_size too big\n");
                         return -EFAULT;
                 }
-/*---------------------------------------------------------------------------*/
                 if (-1 == peasycap->video_interface) {
                         SAM("MISTAKE:  video_interface is unset\n");
                         return -EFAULT;
@@ -3398,14 +3361,13 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         SAM("MISTAKE:  video_isoc_buffer_size is unset\n");
                         return -EFAULT;
                 }
-/*---------------------------------------------------------------------------*/
-/*
- *  ALLOCATE MEMORY FOR VIDEO BUFFERS.  LISTS MUST BE INITIALIZED FIRST.
- */
-/*---------------------------------------------------------------------------*/
+
+                /*
+                 * Allocate memory for video buffers.
+                 * Lists must be initialized first.
+                 */
                 INIT_LIST_HEAD(&(peasycap->urb_video_head));
                 peasycap->purb_video_head = &(peasycap->urb_video_head);
-/*---------------------------------------------------------------------------*/
                 JOM(4, "allocating %i frame buffers of size %li\n",
                                 FRAME_BUFFER_MANY, (long int)FRAME_BUFFER_SIZE);
                 JOM(4, ".... each scattered over %li pages\n",
@@ -3436,7 +3398,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 peasycap->frame_read = 0;
                 JOM(4, "allocation of frame buffers done:  %i pages\n", k *
                                                                         m);
-/*---------------------------------------------------------------------------*/
                 JOM(4, "allocating %i field buffers of size %li\n",
                                 FIELD_BUFFER_MANY, (long int)FIELD_BUFFER_SIZE);
                 JOM(4, ".... each scattered over %li pages\n",
@@ -3468,7 +3429,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 peasycap->field_read = 0;
                 JOM(4, "allocation of field buffers done:  %i pages\n", k *
                                                                         m);
-/*---------------------------------------------------------------------------*/
                 JOM(4, "allocating %i isoc video buffers of size %i\n",
                                                 VIDEO_ISOC_BUFFER_MANY,
                                                 peasycap->video_isoc_buffer_size);
@@ -3492,11 +3452,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 }
                 JOM(4, "allocation of isoc video buffers done: %i pages\n",
                                                 k * (0x01 << VIDEO_ISOC_ORDER));
-/*---------------------------------------------------------------------------*/
-/*
- *  ALLOCATE AND INITIALIZE MULTIPLE struct urb ...
- */
-/*---------------------------------------------------------------------------*/
+
+                /* Allocate and initialize multiple struct usb */
                 JOM(4, "allocating %i struct urb.\n", VIDEO_ISOC_BUFFER_MANY);
                 JOM(4, "using %i=peasycap->video_isoc_framesperdesc\n",
                                                 peasycap->video_isoc_framesperdesc);
@@ -3515,7 +3472,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         }
 
                         peasycap->allocation_video_urb += 1;
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
                         pdata_urb = kzalloc(sizeof(struct data_urb), GFP_KERNEL);
                         if (!pdata_urb) {
                                 SAM("ERROR: Could not allocate struct data_urb.\n");
@@ -3530,11 +3486,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         pdata_urb->length = 0;
                         list_add_tail(&(pdata_urb->list_head),
                                                         peasycap->purb_video_head);
-/*---------------------------------------------------------------------------*/
-/*
- *  ... AND INITIALIZE THEM
- */
-/*---------------------------------------------------------------------------*/
+
+                        /* Initialize allocated urbs */
                         if (!k) {
                                 JOM(4, "initializing video urbs thus:\n");
                                 JOM(4, "  purb->interval = 1;\n");
@@ -3582,20 +3535,17 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         }
                 }
                 JOM(4, "allocation of %i struct urb done.\n", k);
-/*--------------------------------------------------------------------------*/
-/*
- *  SAVE POINTER peasycap IN THIS INTERFACE.
- */
-/*--------------------------------------------------------------------------*/
+
+                /* Save pointer peasycap in this interface */
                 usb_set_intfdata(intf, peasycap);
-/*---------------------------------------------------------------------------*/
-/*
- *  IT IS ESSENTIAL TO INITIALIZE THE HARDWARE BEFORE, RATHER THAN AFTER,
- *  THE DEVICE IS REGISTERED, BECAUSE SOME VERSIONS OF THE videodev MODULE
- *  CALL easycap_open() IMMEDIATELY AFTER REGISTRATION, CAUSING A CLASH.
- *  BEWARE.
-*/
-/*---------------------------------------------------------------------------*/
+
+                /*
+                 * It is essential to initialize the hardware before,
+                 * rather than after, the device is registered,
+                 * because some versions of the videodev module
+                 * call easycap_open() immediately after registration,
+                 * causing a clash.
+                 */
                 peasycap->ntsc = easycap_ntsc;
                 JOM(8, "defaulting initially to %s\n",
                         easycap_ntsc ? "NTSC" : "PAL");
@@ -3604,27 +3554,20 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         SAM("ERROR: reset() rc = %i\n", rc);
                         return -EFAULT;
                 }
-/*--------------------------------------------------------------------------*/
-/*
- *  THE VIDEO DEVICE CAN BE REGISTERED NOW, AS IT IS READY.
- */
-/*--------------------------------------------------------------------------*/
+
+                /* The video device can now be registered */
                 if (v4l2_device_register(&intf->dev, &peasycap->v4l2_device)) {
                         SAM("v4l2_device_register() failed\n");
                         return -ENODEV;
                 }
                 JOM(4, "registered device instance: %s\n",
                         peasycap->v4l2_device.name);
-/*---------------------------------------------------------------------------*/
-/*
- *                                 FIXME
- *
- *
- *  THIS IS BELIEVED TO BE HARMLESS, BUT MAY WELL BE UNNECESSARY OR WRONG:
-*/
-/*---------------------------------------------------------------------------*/
+
+                /*
+                 * FIXME: This is believed to be harmless,
+                 * but may well be unnecessary or wrong.
+                 */
                 peasycap->video_device.v4l2_dev = NULL;
-/*---------------------------------------------------------------------------*/
 
 
                 strcpy(&peasycap->video_device.name[0], "easycapdc60");
@@ -3648,28 +3591,19 @@ static int easycap_usb_probe(struct usb_interface *intf,
 
                 break;
         }
-/*--------------------------------------------------------------------------*/
-/*
- *  INTERFACE 1 IS THE AUDIO CONTROL INTERFACE
- *  INTERFACE 2 IS THE AUDIO STREAMING INTERFACE
- */
-/*--------------------------------------------------------------------------*/
+        /* 1: Audio control */
         case 1: {
                 if (!peasycap) {
                         SAM("MISTAKE: peasycap is NULL\n");
                         return -EFAULT;
                 }
-/*--------------------------------------------------------------------------*/
-/*
- *  SAVE POINTER peasycap IN INTERFACE 1
- */
-/*--------------------------------------------------------------------------*/
+                /* Save pointer peasycap in this interface */
                 usb_set_intfdata(intf, peasycap);
                 JOM(4, "no initialization required for interface %i\n",
                                         interface->bInterfaceNumber);
                 break;
         }
-/*--------------------------------------------------------------------------*/
+        /* 2: Audio streaming */
         case 2: {
                 if (!peasycap) {
                         SAM("MISTAKE: peasycap is NULL\n");
@@ -3769,15 +3703,14 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         SAM("MISTAKE:  audio_isoc_buffer_size is unset\n");
                         return -EFAULT;
                 }
-/*---------------------------------------------------------------------------*/
-/*
- *  ALLOCATE MEMORY FOR AUDIO BUFFERS.  LISTS MUST BE INITIALIZED FIRST.
- */
-/*---------------------------------------------------------------------------*/
+
+                /*
+                 * Allocate memory for audio buffers.
+                 * Lists must be initialized first.
+                 */
                 INIT_LIST_HEAD(&(peasycap->urb_audio_head));
                 peasycap->purb_audio_head = &(peasycap->urb_audio_head);
 
-/*---------------------------------------------------------------------------*/
                 JOM(4, "allocating %i isoc audio buffers of size %i\n",
                         AUDIO_ISOC_BUFFER_MANY,
                         peasycap->audio_isoc_buffer_size);
@@ -3800,11 +3733,8 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         peasycap->audio_isoc_buffer[k].kount = k;
                 }
                 JOM(4, "allocation of isoc audio buffers done.\n");
-/*---------------------------------------------------------------------------*/
-/*
- *  ALLOCATE AND INITIALIZE MULTIPLE struct urb ...
- */
-/*---------------------------------------------------------------------------*/
+
+                /* Allocate and initialize urbs */
                 JOM(4, "allocating %i struct urb.\n", AUDIO_ISOC_BUFFER_MANY);
                 JOM(4, "using %i=peasycap->audio_isoc_framesperdesc\n",
                                         peasycap->audio_isoc_framesperdesc);
@@ -3822,7 +3752,6 @@ static int easycap_usb_probe(struct usb_interface *intf,
                                 return -ENOMEM;
                         }
                         peasycap->allocation_audio_urb += 1 ;
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
                         pdata_urb = kzalloc(sizeof(struct data_urb), GFP_KERNEL);
                         if (!pdata_urb) {
                                 usb_free_urb(purb);
@@ -3837,11 +3766,7 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         pdata_urb->length = 0;
                         list_add_tail(&(pdata_urb->list_head),
                                                         peasycap->purb_audio_head);
-/*---------------------------------------------------------------------------*/
-/*
- *  ... AND INITIALIZE THEM
- */
-/*---------------------------------------------------------------------------*/
+
                         if (!k) {
                                 JOM(4, "initializing audio urbs thus:\n");
                                 JOM(4, "  purb->interval = 1;\n");
@@ -3889,17 +3814,11 @@ static int easycap_usb_probe(struct usb_interface *intf,
                         }
                 }
                 JOM(4, "allocation of %i struct urb done.\n", k);
-/*---------------------------------------------------------------------------*/
-/*
- *  SAVE POINTER peasycap IN THIS INTERFACE.
- */
-/*---------------------------------------------------------------------------*/
+
+                /* Save pointer peasycap in this interface */
                 usb_set_intfdata(intf, peasycap);
-/*---------------------------------------------------------------------------*/
-/*
- *  THE AUDIO DEVICE CAN BE REGISTERED NOW, AS IT IS READY.
- */
-/*---------------------------------------------------------------------------*/
+
+                /* The audio device can now be registered */
                 JOM(4, "initializing ALSA card\n");
 
                 rc = easycap_alsa_probe(peasycap);
@@ -3915,11 +3834,7 @@ static int easycap_usb_probe(struct usb_interface *intf,
                 peasycap->registered_audio++;
                 break;
         }
-/*---------------------------------------------------------------------------*/
-/*
- *  INTERFACES OTHER THAN 0, 1 AND 2 ARE UNEXPECTED
- */
-/*---------------------------------------------------------------------------*/
+        /* Interfaces other than 0,1,2 are unexpected */
         default:
                 JOM(4, "ERROR: unexpected interface %i\n", bInterfaceNumber);
                 return -EINVAL;