From: Ezequiel García Date: Wed, 22 Feb 2012 21:46:14 +0000 (-0300) Subject: [media] staging: easycap: Clean comment style in easycap_usb_probe() X-Git-Tag: firefly_0821_release~3680^2~275^2~2645 X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=2bc1e212b3f1f783cae9adc5d16aa1a899dc2f82;p=firefly-linux-kernel-4.4.55.git [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 Signed-off-by: Mauro Carvalho Chehab --- diff --git a/drivers/staging/media/easycap/easycap_main.c b/drivers/staging/media/easycap/easycap_main.c index 3d439b790cc6..95f3cc1867db 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;