Doug / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit 626f090c5cbbe557379978c7a9525011ad7fbbf6

Authored by Yacine Belkadi
Committed by Greg Kroah-Hartman
1 parent 6b0a1cf732
Exists in smarc-imx_3.14.28_1.0.0_ga and in 1 other branch imx_3.14.28_1.0.0_ga

usb: fix some scripts/kernel-doc warnings 

When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:

Warning(drivers/usb/core/usb.c:76): No description found for return value of
'usb_find_alt_setting'

Fix them by:
- adding some missing descriptions of return values
- using "Return" sections for those descriptions

Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Showing 10 changed files with 173 additions and 87 deletions Side-by-side Diff

drivers/usb/core/buffer.c
Diff comments   View file @ 626f090
... ... @@ -43,10 +43,11 @@
43 43 *
44 44 * Call this as part of initializing a host controller that uses the dma
45 45 * memory allocators. It initializes some pools of dma-coherent memory that
46   - * will be shared by all drivers using that controller, or returns a negative
47   - * errno value on error.
  46 + * will be shared by all drivers using that controller.
48 47 *
49 48 * Call hcd_buffer_destroy() to clean up after using those pools.
  49 + *
  50 + * Return: 0 if successful. A negative errno value otherwise.
50 51 */
51 52 int hcd_buffer_create(struct usb_hcd *hcd)
52 53 {
drivers/usb/core/driver.c
Diff comments   View file @ 626f090
... ... @@ -117,6 +117,8 @@
117 117 * @count: input size
118 118 *
119 119 * Removes a dynamic usb device ID from this driver.
  120 + *
  121 + * Return: @count on success. A negative error code otherwise.
120 122 */
121 123 static ssize_t
122 124 store_remove_id(struct device_driver *driver, const char *buf, size_t count)
... ... @@ -457,6 +459,8 @@
457 459 * Callers must own the device lock, so driver probe() entries don't need
458 460 * extra locking, but other call contexts may need to explicitly claim that
459 461 * lock.
  462 + *
  463 + * Return: 0 on success.
460 464 */
461 465 int usb_driver_claim_interface(struct usb_driver *driver,
462 466 struct usb_interface *iface, void *priv)
... ... @@ -658,6 +662,8 @@
658 662 * These device tables are exported with MODULE_DEVICE_TABLE, through
659 663 * modutils, to support the driver loading functionality of USB hotplugging.
660 664 *
  665 + * Return: The first matching usb_device_id, or %NULL.
  666 + *
661 667 * What Matches:
662 668 *
663 669 * The "match_flags" element in a usb_device_id controls which
... ... @@ -823,7 +829,8 @@
823 829 * Registers a USB device driver with the USB core. The list of
824 830 * unattached devices will be rescanned whenever a new driver is
825 831 * added, allowing the new driver to attach to any recognized devices.
826   - * Returns a negative error code on failure and 0 on success.
  832 + *
  833 + * Return: A negative error code on failure and 0 on success.
827 834 */
828 835 int usb_register_device_driver(struct usb_device_driver *new_udriver,
829 836 struct module *owner)
830 837  
... ... @@ -879,8 +886,9 @@
879 886 * Registers a USB interface driver with the USB core. The list of
880 887 * unattached interfaces will be rescanned whenever a new driver is
881 888 * added, allowing the new driver to attach to any recognized interfaces.
882   - * Returns a negative error code on failure and 0 on success.
883 889 *
  890 + * Return: A negative error code on failure and 0 on success.
  891 + *
884 892 * NOTE: if you want your driver to use the USB major number, you must call
885 893 * usb_register_dev() to enable that functionality. This function no longer
886 894 * takes care of that.
... ... @@ -1213,6 +1221,8 @@
1213 1221 * unpredictable times.
1214 1222 *
1215 1223 * This routine can run only in process context.
  1224 + *
  1225 + * Return: 0 if the suspend succeeded.
1216 1226 */
1217 1227 static int usb_suspend_both(struct usb_device *udev, pm_message_t msg)
1218 1228 {
... ... @@ -1294,6 +1304,8 @@
1294 1304 * unpredictable times.
1295 1305 *
1296 1306 * This routine can run only in process context.
  1307 + *
  1308 + * Return: 0 on success.
1297 1309 */
1298 1310 static int usb_resume_both(struct usb_device *udev, pm_message_t msg)
1299 1311 {
... ... @@ -1491,6 +1503,8 @@
1491 1503 * The caller must hold @udev's device lock.
1492 1504 *
1493 1505 * This routine can run only in process context.
  1506 + *
  1507 + * Return: 0 on success. A negative error code otherwise.
1494 1508 */
1495 1509 int usb_autoresume_device(struct usb_device *udev)
1496 1510 {
... ... @@ -1600,6 +1614,8 @@
1600 1614 * However if the autoresume fails then the counter is re-decremented.
1601 1615 *
1602 1616 * This routine can run only in process context.
  1617 + *
  1618 + * Return: 0 on success.
1603 1619 */
1604 1620 int usb_autopm_get_interface(struct usb_interface *intf)
1605 1621 {
... ... @@ -1633,6 +1649,8 @@
1633 1649 * resumed.
1634 1650 *
1635 1651 * This routine can run in atomic context.
  1652 + *
  1653 + * Return: 0 on success. A negative error code otherwise.
1636 1654 */
1637 1655 int usb_autopm_get_interface_async(struct usb_interface *intf)
1638 1656 {
drivers/usb/core/file.c
Diff comments   View file @ 626f090
... ... @@ -153,7 +153,7 @@
153 153 * usb_deregister_dev() must be called when the driver is done with
154 154 * the minor numbers given out by this function.
155 155 *
156   - * Returns -EINVAL if something bad happens with trying to register a
  156 + * Return: -EINVAL if something bad happens with trying to register a
157 157 * device, and 0 on success.
158 158 */
159 159 int usb_register_dev(struct usb_interface *intf,
drivers/usb/core/hcd-pci.c
Diff comments   View file @ 626f090
... ... @@ -171,6 +171,8 @@
171 171 * through the hotplug entry's driver_data.
172 172 *
173 173 * Store this function in the HCD's struct pci_driver as probe().
  174 + *
  175 + * Return: 0 if successful.
174 176 */
175 177 int usb_hcd_pci_probe(struct pci_dev *dev, const struct pci_device_id *id)
176 178 {
drivers/usb/core/hcd.c
Diff comments   View file @ 626f090
... ... @@ -378,9 +378,10 @@
378 378 * @buf: Buffer for USB string descriptor (header + UTF-16LE)
379 379 * @len: Length (in bytes; may be odd) of descriptor buffer.
380 380 *
381   - * The return value is the number of bytes filled in: 2 + 2*strlen(s) or
382   - * buflen, whichever is less.
  381 + * Return: The number of bytes filled in: 2 + 2*strlen(s) or @len,
  382 + * whichever is less.
383 383 *
  384 + * Note:
384 385 * USB String descriptors can contain at most 126 characters; input
385 386 * strings longer than that are truncated.
386 387 */
... ... @@ -416,7 +417,8 @@
416 417 *
417 418 * Produces either a manufacturer, product or serial number string for the
418 419 * virtual root hub device.
419   - * Returns the number of bytes filled in: the length of the descriptor or
  420 + *
  421 + * Return: The number of bytes filled in: the length of the descriptor or
420 422 * of the provided buffer, whichever is less.
421 423 */
422 424 static unsigned
... ... @@ -938,6 +940,8 @@
938 940 *
939 941 * Assigns a bus number, and links the controller into usbcore data
940 942 * structures so that it can be seen by scanning the bus list.
  943 + *
  944 + * Return: 0 if successful. A negative error code otherwise.
941 945 */
942 946 static int usb_register_bus(struct usb_bus *bus)
943 947 {
... ... @@ -1002,6 +1006,8 @@
1002 1006 * the device properly in the device tree and then calls usb_new_device()
1003 1007 * to register the usb device. It also assigns the root hub's USB address
1004 1008 * (always 1).
  1009 + *
  1010 + * Return: 0 if successful. A negative error code otherwise.
1005 1011 */
1006 1012 static int register_root_hub(struct usb_hcd *hcd)
1007 1013 {
... ... @@ -1108,7 +1114,9 @@
1108 1114 * @isoc: true for isochronous transactions, false for interrupt ones
1109 1115 * @bytecount: how many bytes in the transaction.
1110 1116 *
1111   - * Returns approximate bus time in nanoseconds for a periodic transaction.
  1117 + * Return: Approximate bus time in nanoseconds for a periodic transaction.
  1118 + *
  1119 + * Note:
1112 1120 * See USB 2.0 spec section 5.11.3; only periodic transfers need to be
1113 1121 * scheduled in software, this function is only used for such scheduling.
1114 1122 */
... ... @@ -1166,7 +1174,7 @@
1166 1174 * be disabled. The actions carried out here are required for URB
1167 1175 * submission, as well as for endpoint shutdown and for usb_kill_urb.
1168 1176 *
1169   - * Returns 0 for no error, otherwise a negative error code (in which case
  1177 + * Return: 0 for no error, otherwise a negative error code (in which case
1170 1178 * the enqueue() method must fail). If no error occurs but enqueue() fails
1171 1179 * anyway, it must call usb_hcd_unlink_urb_from_ep() before releasing
1172 1180 * the private spinlock and returning.
... ... @@ -1221,7 +1229,7 @@
1221 1229 * be disabled. The actions carried out here are required for making
1222 1230 * sure than an unlink is valid.
1223 1231 *
1224   - * Returns 0 for no error, otherwise a negative error code (in which case
  1232 + * Return: 0 for no error, otherwise a negative error code (in which case
1225 1233 * the dequeue() method must fail). The possible error codes are:
1226 1234 *
1227 1235 * -EIDRM: @urb was not submitted or has already completed.
... ... @@ -1784,7 +1792,7 @@
1784 1792 * pass in the current alternate interface setting in cur_alt,
1785 1793 * and pass in the new alternate interface setting in new_alt.
1786 1794 *
1787   - * Returns an error if the requested bandwidth change exceeds the
  1795 + * Return: An error if the requested bandwidth change exceeds the
1788 1796 * bus bandwidth or host controller internal resources.
1789 1797 */
1790 1798 int usb_hcd_alloc_bandwidth(struct usb_device *udev,
1791 1799  
... ... @@ -1954,9 +1962,12 @@
1954 1962 * @num_streams: number of streams to allocate.
1955 1963 * @mem_flags: flags hcd should use to allocate memory.
1956 1964 *
1957   - * Sets up a group of bulk endpoints to have num_streams stream IDs available.
  1965 + * Sets up a group of bulk endpoints to have @num_streams stream IDs available.
1958 1966 * Drivers may queue multiple transfers to different stream IDs, which may
1959 1967 * complete in a different order than they were queued.
  1968 + *
  1969 + * Return: On success, the number of allocated streams. On failure, a negative
  1970 + * error code.
1960 1971 */
1961 1972 int usb_alloc_streams(struct usb_interface *interface,
1962 1973 struct usb_host_endpoint **eps, unsigned int num_eps,
... ... @@ -2201,6 +2212,8 @@
2201 2212 * khubd identifying and possibly configuring the device.
2202 2213 * This is needed by OTG controller drivers, where it helps meet
2203 2214 * HNP protocol timing requirements for starting a port reset.
  2215 + *
  2216 + * Return: 0 if successful.
2204 2217 */
2205 2218 int usb_bus_start_enum(struct usb_bus *bus, unsigned port_num)
2206 2219 {
... ... @@ -2235,6 +2248,8 @@
2235 2248 *
2236 2249 * If the controller isn't HALTed, calls the driver's irq handler.
2237 2250 * Checks whether the controller is now dead.
  2251 + *
  2252 + * Return: %IRQ_HANDLED if the IRQ was handled. %IRQ_NONE otherwise.
2238 2253 */
2239 2254 irqreturn_t usb_hcd_irq (int irq, void *__hcd)
2240 2255 {
... ... @@ -2320,7 +2335,8 @@
2320 2335 * HC driver's private data. Initialize the generic members of the
2321 2336 * hcd structure.
2322 2337 *
2323   - * If memory is unavailable, returns NULL.
  2338 + * Return: On success, a pointer to the created and initialized HCD structure.
  2339 + * On failure (e.g. if memory is unavailable), %NULL.
2324 2340 */
2325 2341 struct usb_hcd *usb_create_shared_hcd(const struct hc_driver *driver,
2326 2342 struct device *dev, const char *bus_name,
... ... @@ -2384,7 +2400,8 @@
2384 2400 * HC driver's private data. Initialize the generic members of the
2385 2401 * hcd structure.
2386 2402 *
2387   - * If memory is unavailable, returns NULL.
  2403 + * Return: On success, a pointer to the created and initialized HCD
  2404 + * structure. On failure (e.g. if memory is unavailable), %NULL.
2388 2405 */
2389 2406 struct usb_hcd *usb_create_hcd(const struct hc_driver *driver,
2390 2407 struct device *dev, const char *bus_name)
drivers/usb/core/hub.c
Diff comments   View file @ 626f090
... ... @@ -734,6 +734,8 @@
734 734 *
735 735 * call this function to control port's power via setting or
736 736 * clearing the port's PORT_POWER feature.
  737 + *
  738 + * Return: 0 if successful. A negative error code otherwise.
737 739 */
738 740 int usb_hub_set_port_power(struct usb_device *hdev, struct usb_hub *hub,
739 741 int port1, bool set)
... ... @@ -762,6 +764,8 @@
762 764 *
763 765 * It may not be possible for that hub to handle additional full (or low)
764 766 * speed transactions until that state is fully cleared out.
  767 + *
  768 + * Return: 0 if successful. A negative error code otherwise.
765 769 */
766 770 int usb_hub_clear_tt_buffer(struct urb *urb)
767 771 {
... ... @@ -964,6 +968,8 @@
964 968 * see that the device has been disconnected. When the device is
965 969 * physically unplugged and something is plugged in, the events will
966 970 * be received and processed normally.
  971 + *
  972 + * Return: 0 if successful. A negative error code otherwise.
967 973 */
968 974 int usb_remove_device(struct usb_device *udev)
969 975 {
... ... @@ -2115,6 +2121,8 @@
2115 2121 * @udev: newly addressed device (in ADDRESS state)
2116 2122 *
2117 2123 * Finish enumeration for On-The-Go devices
  2124 + *
  2125 + * Return: 0 if successful. A negative error code otherwise.
2118 2126 */
2119 2127 static int usb_enumerate_device_otg(struct usb_device *udev)
2120 2128 {
... ... @@ -2197,6 +2205,8 @@
2197 2205 * If the device is WUSB and not authorized, we don't attempt to read
2198 2206 * the string descriptors, as they will be errored out by the device
2199 2207 * until it has been authorized.
  2208 + *
  2209 + * Return: 0 if successful. A negative error code otherwise.
2200 2210 */
2201 2211 static int usb_enumerate_device(struct usb_device *udev)
2202 2212 {
2203 2213  
... ... @@ -2277,13 +2287,14 @@
2277 2287 * udev has already been installed, but udev is not yet visible through
2278 2288 * sysfs or other filesystem code.
2279 2289 *
2280   - * It will return if the device is configured properly or not. Zero if
2281   - * the interface was registered with the driver core; else a negative
2282   - * errno value.
2283   - *
2284 2290 * This call is synchronous, and may not be used in an interrupt context.
2285 2291 *
2286 2292 * Only the hub driver or root-hub registrar should ever call this.
  2293 + *
  2294 + * Return: Whether the device is configured properly or not. Zero if the
  2295 + * interface was registered with the driver core; else a negative errno
  2296 + * value.
  2297 + *
2287 2298 */
2288 2299 int usb_new_device(struct usb_device *udev)
2289 2300 {
... ... @@ -2391,6 +2402,8 @@
2391 2402 *
2392 2403 * We share a lock (that we have) with device_del(), so we need to
2393 2404 * defer its call.
  2405 + *
  2406 + * Return: 0.
2394 2407 */
2395 2408 int usb_deauthorize_device(struct usb_device *usb_dev)
2396 2409 {
2397 2410  
... ... @@ -5025,10 +5038,11 @@
5025 5038 * re-connected. All drivers will be unbound, and the device will be
5026 5039 * re-enumerated and probed all over again.
5027 5040 *
5028   - * Returns 0 if the reset succeeded, -ENODEV if the device has been
  5041 + * Return: 0 if the reset succeeded, -ENODEV if the device has been
5029 5042 * flagged for logical disconnection, or some other negative error code
5030 5043 * if the reset wasn't even attempted.
5031 5044 *
  5045 + * Note:
5032 5046 * The caller must own the device lock. For example, it's safe to use
5033 5047 * this from a driver probe() routine after downloading new firmware.
5034 5048 * For calls that might not occur during probe(), drivers should lock
5035 5049  
... ... @@ -5184,8 +5198,9 @@
5184 5198 * method), performs the port reset, and then lets the drivers know that
5185 5199 * the reset is over (using their post_reset method).
5186 5200 *
5187   - * Return value is the same as for usb_reset_and_verify_device().
  5201 + * Return: The same as for usb_reset_and_verify_device().
5188 5202 *
  5203 + * Note:
5189 5204 * The caller must own the device lock. For example, it's safe to use
5190 5205 * this from a driver probe() routine after downloading new firmware.
5191 5206 * For calls that might not occur during probe(), drivers should lock
... ... @@ -5323,7 +5338,7 @@
5323 5338 * USB drivers call this function to get hub's child device
5324 5339 * pointer.
5325 5340 *
5326   - * Return NULL if input param is invalid and
  5341 + * Return: %NULL if input param is invalid and
5327 5342 * child's usb_device pointer if non-NULL.
5328 5343 */
5329 5344 struct usb_device *usb_hub_find_child(struct usb_device *hdev,
... ... @@ -5357,8 +5372,8 @@
5357 5372 * @hdev: USB device belonging to the usb hub
5358 5373 * @port1: port num of the port
5359 5374 *
5360   - * Return connect type of the port and if input params are
5361   - * invalid, return USB_PORT_CONNECT_TYPE_UNKNOWN.
  5375 + * Return: The connect type of the port if successful. Or
  5376 + * USB_PORT_CONNECT_TYPE_UNKNOWN if input params are invalid.
5362 5377 */
5363 5378 enum usb_port_connect_type
5364 5379 usb_get_hub_port_connect_type(struct usb_device *hdev, int port1)
... ... @@ -5418,8 +5433,8 @@
5418 5433 * @hdev: USB device belonging to the usb hub
5419 5434 * @port1: port num of the port
5420 5435 *
5421   - * Return port's acpi handle if successful, NULL if params are
5422   - * invaild.
  5436 + * Return: Port's acpi handle if successful, %NULL if params are
  5437 + * invalid.
5423 5438 */
5424 5439 acpi_handle usb_get_hub_port_acpi_handle(struct usb_device *hdev,
5425 5440 int port1)
drivers/usb/core/message.c
Diff comments   View file @ 626f090
... ... @@ -119,15 +119,15 @@
119 119 * This function sends a simple control message to a specified endpoint and
120 120 * waits for the message to complete, or timeout.
121 121 *
122   - * If successful, it returns the number of bytes transferred, otherwise a
123   - * negative error number.
124   - *
125 122 * Don't use this function from within an interrupt context, like a bottom half
126 123 * handler. If you need an asynchronous message, or need to send a message
127 124 * from within interrupt context, use usb_submit_urb().
128 125 * If a thread in your driver uses this call, make sure your disconnect()
129 126 * method can wait for it to complete. Since you don't have a handle on the
130 127 * URB used, you can't cancel the request.
  128 + *
  129 + * Return: If successful, the number of bytes transferred. Otherwise, a negative
  130 + * error number.
131 131 */
132 132 int usb_control_msg(struct usb_device *dev, unsigned int pipe, __u8 request,
133 133 __u8 requesttype, __u16 value, __u16 index, void *data,
134 134  
... ... @@ -170,15 +170,16 @@
170 170 * This function sends a simple interrupt message to a specified endpoint and
171 171 * waits for the message to complete, or timeout.
172 172 *
173   - * If successful, it returns 0, otherwise a negative error number. The number
174   - * of actual bytes transferred will be stored in the actual_length paramater.
175   - *
176 173 * Don't use this function from within an interrupt context, like a bottom half
177 174 * handler. If you need an asynchronous message, or need to send a message
178 175 * from within interrupt context, use usb_submit_urb() If a thread in your
179 176 * driver uses this call, make sure your disconnect() method can wait for it to
180 177 * complete. Since you don't have a handle on the URB used, you can't cancel
181 178 * the request.
  179 + *
  180 + * Return:
  181 + * If successful, 0. Otherwise a negative error number. The number of actual
  182 + * bytes transferred will be stored in the @actual_length paramater.
182 183 */
183 184 int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
184 185 void *data, int len, int *actual_length, int timeout)
... ... @@ -203,9 +204,6 @@
203 204 * This function sends a simple bulk message to a specified endpoint
204 205 * and waits for the message to complete, or timeout.
205 206 *
206   - * If successful, it returns 0, otherwise a negative error number. The number
207   - * of actual bytes transferred will be stored in the actual_length paramater.
208   - *
209 207 * Don't use this function from within an interrupt context, like a bottom half
210 208 * handler. If you need an asynchronous message, or need to send a message
211 209 * from within interrupt context, use usb_submit_urb() If a thread in your
... ... @@ -217,6 +215,11 @@
217 215 * users are forced to abuse this routine by using it to submit URBs for
218 216 * interrupt endpoints. We will take the liberty of creating an interrupt URB
219 217 * (with the default interval) if the target is an interrupt endpoint.
  218 + *
  219 + * Return:
  220 + * If successful, 0. Otherwise a negative error number. The number of actual
  221 + * bytes transferred will be stored in the @actual_length paramater.
  222 + *
220 223 */
221 224 int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
222 225 void *data, int len, int *actual_length, int timeout)
... ... @@ -341,9 +344,9 @@
341 344 * send every byte identified in the list.
342 345 * @mem_flags: SLAB_* flags affecting memory allocations in this call
343 346 *
344   - * Returns zero for success, else a negative errno value. This initializes a
345   - * scatter/gather request, allocating resources such as I/O mappings and urb
346   - * memory (except maybe memory used by USB controller drivers).
  347 + * This initializes a scatter/gather request, allocating resources such as
  348 + * I/O mappings and urb memory (except maybe memory used by USB controller
  349 + * drivers).
347 350 *
348 351 * The request must be issued using usb_sg_wait(), which waits for the I/O to
349 352 * complete (or to be canceled) and then cleans up all resources allocated by
... ... @@ -351,6 +354,8 @@
351 354 *
352 355 * The request may be canceled with usb_sg_cancel(), either before or after
353 356 * usb_sg_wait() is called.
  357 + *
  358 + * Return: Zero for success, else a negative errno value.
354 359 */
355 360 int usb_sg_init(struct usb_sg_request *io, struct usb_device *dev,
356 361 unsigned pipe, unsigned period, struct scatterlist *sg,
... ... @@ -623,7 +628,7 @@
623 628 *
624 629 * This call is synchronous, and may not be used in an interrupt context.
625 630 *
626   - * Returns the number of bytes received on success, or else the status code
  631 + * Return: The number of bytes received on success, or else the status code
627 632 * returned by the underlying usb_control_msg() call.
628 633 */
629 634 int usb_get_descriptor(struct usb_device *dev, unsigned char type,
... ... @@ -671,7 +676,7 @@
671 676 *
672 677 * This call is synchronous, and may not be used in an interrupt context.
673 678 *
674   - * Returns the number of bytes received on success, or else the status code
  679 + * Return: The number of bytes received on success, or else the status code
675 680 * returned by the underlying usb_control_msg() call.
676 681 */
677 682 static int usb_get_string(struct usb_device *dev, unsigned short langid,
... ... @@ -805,7 +810,7 @@
805 810 *
806 811 * This call is synchronous, and may not be used in an interrupt context.
807 812 *
808   - * Returns length of the string (>= 0) or usb_control_msg status (< 0).
  813 + * Return: length of the string (>= 0) or usb_control_msg status (< 0).
809 814 */
810 815 int usb_string(struct usb_device *dev, int index, char *buf, size_t size)
811 816 {
... ... @@ -853,8 +858,8 @@
853 858 * @udev: the device whose string descriptor is being read
854 859 * @index: the descriptor index
855 860 *
856   - * Returns a pointer to a kmalloc'ed buffer containing the descriptor string,
857   - * or NULL if the index is 0 or the string could not be read.
  861 + * Return: A pointer to a kmalloc'ed buffer containing the descriptor string,
  862 + * or %NULL if the index is 0 or the string could not be read.
858 863 */
859 864 char *usb_cache_string(struct usb_device *udev, int index)
860 865 {
... ... @@ -894,7 +899,7 @@
894 899 *
895 900 * This call is synchronous, and may not be used in an interrupt context.
896 901 *
897   - * Returns the number of bytes received on success, or else the status code
  902 + * Return: The number of bytes received on success, or else the status code
898 903 * returned by the underlying usb_control_msg() call.
899 904 */
900 905 int usb_get_device_descriptor(struct usb_device *dev, unsigned int size)
... ... @@ -980,7 +985,7 @@
980 985 *
981 986 * This call is synchronous, and may not be used in an interrupt context.
982 987 *
983   - * Returns zero on success, or else the status code returned by the
  988 + * Return: Zero on success, or else the status code returned by the
984 989 * underlying usb_control_msg() call.
985 990 */
986 991 int usb_clear_halt(struct usb_device *dev, int pipe)
... ... @@ -1277,7 +1282,7 @@
1277 1282 * endpoints in that interface; all such urbs must first be completed
1278 1283 * (perhaps forced by unlinking).
1279 1284 *
1280   - * Returns zero on success, or else the status code returned by the
  1285 + * Return: Zero on success, or else the status code returned by the
1281 1286 * underlying usb_control_msg() call.
1282 1287 */
1283 1288 int usb_set_interface(struct usb_device *dev, int interface, int alternate)
... ... @@ -1431,7 +1436,7 @@
1431 1436 *
1432 1437 * The caller must own the device lock.
1433 1438 *
1434   - * Returns zero on success, else a negative error code.
  1439 + * Return: Zero on success, else a negative error code.
1435 1440 */
1436 1441 int usb_reset_configuration(struct usb_device *dev)
1437 1442 {
... ... @@ -1973,7 +1978,7 @@
1973 1978 * routine gets around the normal restrictions by using a work thread to
1974 1979 * submit the change-config request.
1975 1980 *
1976   - * Returns 0 if the request was successfully queued, error code otherwise.
  1981 + * Return: 0 if the request was successfully queued, error code otherwise.
1977 1982 * The caller has no way to know whether the queued request will eventually
1978 1983 * succeed.
1979 1984 */
drivers/usb/core/urb.c
Diff comments   View file @ 626f090
... ... @@ -55,12 +55,12 @@
55 55 * Creates an urb for the USB driver to use, initializes a few internal
56 56 * structures, incrementes the usage counter, and returns a pointer to it.
57 57 *
58   - * If no memory is available, NULL is returned.
59   - *
60 58 * If the driver want to use this urb for interrupt, control, or bulk
61 59 * endpoints, pass '0' as the number of iso packets.
62 60 *
63 61 * The driver must call usb_free_urb() when it is finished with the urb.
  62 + *
  63 + * Return: A pointer to the new urb, or %NULL if no memory is available.
64 64 */
65 65 struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags)
66 66 {
... ... @@ -103,7 +103,7 @@
103 103 * host controller driver. This allows proper reference counting to happen
104 104 * for urbs.
105 105 *
106   - * A pointer to the urb with the incremented reference counter is returned.
  106 + * Return: A pointer to the urb with the incremented reference counter.
107 107 */
108 108 struct urb *usb_get_urb(struct urb *urb)
109 109 {
... ... @@ -200,13 +200,12 @@
200 200 * the particular kind of transfer, although they will not initialize
201 201 * any transfer flags.
202 202 *
203   - * Successful submissions return 0; otherwise this routine returns a
204   - * negative error number. If the submission is successful, the complete()
205   - * callback from the URB will be called exactly once, when the USB core and
206   - * Host Controller Driver (HCD) are finished with the URB. When the completion
207   - * function is called, control of the URB is returned to the device
208   - * driver which issued the request. The completion handler may then
209   - * immediately free or reuse that URB.
  203 + * If the submission is successful, the complete() callback from the URB
  204 + * will be called exactly once, when the USB core and Host Controller Driver
  205 + * (HCD) are finished with the URB. When the completion function is called,
  206 + * control of the URB is returned to the device driver which issued the
  207 + * request. The completion handler may then immediately free or reuse that
  208 + * URB.
210 209 *
211 210 * With few exceptions, USB device drivers should never access URB fields
212 211 * provided by usbcore or the HCD until its complete() is called.
... ... @@ -241,6 +240,9 @@
241 240 * that are standardized in the USB 2.0 specification. For bulk
242 241 * endpoints, a synchronous usb_bulk_msg() call is available.
243 242 *
  243 + * Return:
  244 + * 0 on successful submissions. A negative error number otherwise.
  245 + *
244 246 * Request Queuing:
245 247 *
246 248 * URBs may be submitted to endpoints before previous ones complete, to
... ... @@ -572,6 +574,9 @@
572 574 * particular, when a driver calls this routine, it must insure that the
573 575 * completion handler cannot deallocate the URB.
574 576 *
  577 + * Return: -EINPROGRESS on success. See description for other values on
  578 + * failure.
  579 + *
575 580 * Unlinking and Endpoint Queues:
576 581 *
577 582 * [The behaviors and guarantees described below do not apply to virtual
... ... @@ -846,6 +851,8 @@
846 851 *
847 852 * Call this is you want to be sure all an anchor's
848 853 * URBs have finished
  854 + *
  855 + * Return: Non-zero if the anchor became unused. Zero on timeout.
849 856 */
850 857 int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
851 858 unsigned int timeout)
852 859  
... ... @@ -859,8 +866,11 @@
859 866 * usb_get_from_anchor - get an anchor's oldest urb
860 867 * @anchor: the anchor whose urb you want
861 868 *
862   - * this will take the oldest urb from an anchor,
  869 + * This will take the oldest urb from an anchor,
863 870 * unanchor and return it
  871 + *
  872 + * Return: The oldest urb from @anchor, or %NULL if @anchor has no
  873 + * urbs associated with it.
864 874 */
865 875 struct urb *usb_get_from_anchor(struct usb_anchor *anchor)
866 876 {
... ... @@ -909,7 +919,7 @@
909 919 * usb_anchor_empty - is an anchor empty
910 920 * @anchor: the anchor you want to query
911 921 *
912   - * returns 1 if the anchor has no urbs associated with it
  922 + * Return: 1 if the anchor has no urbs associated with it.
913 923 */
914 924 int usb_anchor_empty(struct usb_anchor *anchor)
915 925 {
drivers/usb/core/usb.c
Diff comments   View file @ 626f090
... ... @@ -68,6 +68,8 @@
68 68 * @alt_num: alternate interface setting number to search for.
69 69 *
70 70 * Search the configuration's interface cache for the given alt setting.
  71 + *
  72 + * Return: The alternate setting, if found. %NULL otherwise.
71 73 */
72 74 struct usb_host_interface *usb_find_alt_setting(
73 75 struct usb_host_config *config,
... ... @@ -103,8 +105,7 @@
103 105 * @ifnum: the desired interface
104 106 *
105 107 * This walks the device descriptor for the currently active configuration
106   - * and returns a pointer to the interface with that particular interface
107   - * number, or null.
  108 + * to find the interface object with the particular interface number.
108 109 *
109 110 * Note that configuration descriptors are not required to assign interface
110 111 * numbers sequentially, so that it would be incorrect to assume that
... ... @@ -115,6 +116,9 @@
115 116 *
116 117 * Don't call this function unless you are bound to one of the interfaces
117 118 * on this device or you have locked the device!
  119 + *
  120 + * Return: A pointer to the interface that has @ifnum as interface number,
  121 + * if found. %NULL otherwise.
118 122 */
119 123 struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
120 124 unsigned ifnum)
... ... @@ -139,8 +143,7 @@
139 143 * @altnum: the desired alternate setting number
140 144 *
141 145 * This searches the altsetting array of the specified interface for
142   - * an entry with the correct bAlternateSetting value and returns a pointer
143   - * to that entry, or null.
  146 + * an entry with the correct bAlternateSetting value.
144 147 *
145 148 * Note that altsettings need not be stored sequentially by number, so
146 149 * it would be incorrect to assume that the first altsetting entry in
... ... @@ -149,6 +152,9 @@
149 152 *
150 153 * Don't call this function unless you are bound to the intf interface
151 154 * or you have locked the device!
  155 + *
  156 + * Return: A pointer to the entry of the altsetting array of @intf that
  157 + * has @altnum as the alternate setting number. %NULL if not found.
152 158 */
153 159 struct usb_host_interface *usb_altnum_to_altsetting(
154 160 const struct usb_interface *intf,
... ... @@ -191,6 +197,8 @@
191 197 * This walks the bus device list and returns a pointer to the interface
192 198 * with the matching minor and driver. Note, this only works for devices
193 199 * that share the USB major number.
  200 + *
  201 + * Return: A pointer to the interface with the matching major and @minor.
194 202 */
195 203 struct usb_interface *usb_find_interface(struct usb_driver *drv, int minor)
196 204 {
... ... @@ -390,6 +398,9 @@
390 398 * controllers) should ever call this.
391 399 *
392 400 * This call may not be used in a non-sleeping context.
  401 + *
  402 + * Return: On success, a pointer to the allocated usb device. %NULL on
  403 + * failure.
393 404 */
394 405 struct usb_device *usb_alloc_dev(struct usb_device *parent,
395 406 struct usb_bus *bus, unsigned port1)
... ... @@ -501,7 +512,7 @@
501 512 * their probe() methods, when they bind to an interface, and release
502 513 * them by calling usb_put_dev(), in their disconnect() methods.
503 514 *
504   - * A pointer to the device with the incremented reference counter is returned.
  515 + * Return: A pointer to the device with the incremented reference counter.
505 516 */
506 517 struct usb_device *usb_get_dev(struct usb_device *dev)
507 518 {
... ... @@ -535,8 +546,7 @@
535 546 * their probe() methods, when they bind to an interface, and release
536 547 * them by calling usb_put_intf(), in their disconnect() methods.
537 548 *
538   - * A pointer to the interface with the incremented reference counter is
539   - * returned.
  549 + * Return: A pointer to the interface with the incremented reference counter.
540 550 */
541 551 struct usb_interface *usb_get_intf(struct usb_interface *intf)
542 552 {
... ... @@ -589,7 +599,7 @@
589 599 * disconnect; in some drivers (such as usb-storage) the disconnect()
590 600 * or suspend() method will block waiting for a device reset to complete.
591 601 *
592   - * Returns a negative error code for failure, otherwise 0.
  602 + * Return: A negative error code for failure, otherwise 0.
593 603 */
594 604 int usb_lock_device_for_reset(struct usb_device *udev,
595 605 const struct usb_interface *iface)
596 606  
... ... @@ -628,14 +638,15 @@
628 638 * usb_get_current_frame_number - return current bus frame number
629 639 * @dev: the device whose bus is being queried
630 640 *
631   - * Returns the current frame number for the USB host controller
632   - * used with the given USB device. This can be used when scheduling
  641 + * Return: The current frame number for the USB host controller used
  642 + * with the given USB device. This can be used when scheduling
633 643 * isochronous requests.
634 644 *
635   - * Note that different kinds of host controller have different
636   - * "scheduling horizons". While one type might support scheduling only
637   - * 32 frames into the future, others could support scheduling up to
638   - * 1024 frames into the future.
  645 + * Note: Different kinds of host controller have different "scheduling
  646 + * horizons". While one type might support scheduling only 32 frames
  647 + * into the future, others could support scheduling up to 1024 frames
  648 + * into the future.
  649 + *
639 650 */
640 651 int usb_get_current_frame_number(struct usb_device *dev)
641 652 {
642 653  
... ... @@ -685,11 +696,12 @@
685 696 * @mem_flags: affect whether allocation may block
686 697 * @dma: used to return DMA address of buffer
687 698 *
688   - * Return value is either null (indicating no buffer could be allocated), or
689   - * the cpu-space pointer to a buffer that may be used to perform DMA to the
  699 + * Return: Either null (indicating no buffer could be allocated), or the
  700 + * cpu-space pointer to a buffer that may be used to perform DMA to the
690 701 * specified device. Such cpu-space buffers are returned along with the DMA
691 702 * address (through the pointer provided).
692 703 *
  704 + * Note:
693 705 * These buffers are used with URB_NO_xxx_DMA_MAP set in urb->transfer_flags
694 706 * to avoid behaviors like using "DMA bounce buffers", or thrashing IOMMU
695 707 * hardware during URB completion/resubmit. The implementation varies between
696 708  
... ... @@ -735,17 +747,18 @@
735 747 * usb_buffer_map - create DMA mapping(s) for an urb
736 748 * @urb: urb whose transfer_buffer/setup_packet will be mapped
737 749 *
738   - * Return value is either null (indicating no buffer could be mapped), or
739   - * the parameter. URB_NO_TRANSFER_DMA_MAP is
740   - * added to urb->transfer_flags if the operation succeeds. If the device
741   - * is connected to this system through a non-DMA controller, this operation
742   - * always succeeds.
  750 + * URB_NO_TRANSFER_DMA_MAP is added to urb->transfer_flags if the operation
  751 + * succeeds. If the device is connected to this system through a non-DMA
  752 + * controller, this operation always succeeds.
743 753 *
744 754 * This call would normally be used for an urb which is reused, perhaps
745 755 * as the target of a large periodic transfer, with usb_buffer_dmasync()
746 756 * calls to synchronize memory and dma state.
747 757 *
748 758 * Reverse the effect of this call with usb_buffer_unmap().
  759 + *
  760 + * Return: Either %NULL (indicating no buffer could be mapped), or @urb.
  761 + *
749 762 */
750 763 #if 0
751 764 struct urb *usb_buffer_map(struct urb *urb)
752 765  
... ... @@ -850,9 +863,10 @@
850 863 * @sg: the scatterlist to map
851 864 * @nents: the number of entries in the scatterlist
852 865 *
853   - * Return value is either < 0 (indicating no buffers could be mapped), or
854   - * the number of DMA mapping array entries in the scatterlist.
  866 + * Return: Either < 0 (indicating no buffers could be mapped), or the
  867 + * number of DMA mapping array entries in the scatterlist.
855 868 *
  869 + * Note:
856 870 * The caller is responsible for placing the resulting DMA addresses from
857 871 * the scatterlist into URB transfer buffer pointers, and for setting the
858 872 * URB_NO_TRANSFER_DMA_MAP transfer flag in each of those URBs.
... ... @@ -708,7 +708,10 @@
708 708 * usb_interface_claimed - returns true iff an interface is claimed
709 709 * @iface: the interface being checked
710 710 *
711   - * Returns true (nonzero) iff the interface is claimed, else false (zero).
  711 + * Return: %true (nonzero) iff the interface is claimed, else %false
  712 + * (zero).
  713 + *
  714 + * Note:
712 715 * Callers must own the driver model's usb bus readlock. So driver
713 716 * probe() entries don't need extra locking, but other call contexts
714 717 * may need to explicitly claim that lock.
715 718  
... ... @@ -745,8 +748,9 @@
745 748 * @buf: where to put the string
746 749 * @size: how big is "buf"?
747 750 *
748   - * Returns length of the string (> 0) or negative if size was too small.
  751 + * Return: Length of the string (> 0) or negative if size was too small.
749 752 *
  753 + * Note:
750 754 * This identifier is intended to be "stable", reflecting physical paths in
751 755 * hardware such as physical bus addresses for host controllers or ports on
752 756 * USB hubs. That makes it stay the same until systems are physically
... ... @@ -1578,7 +1582,7 @@
1578 1582 * usb_urb_dir_in - check if an URB describes an IN transfer
1579 1583 * @urb: URB to be checked
1580 1584 *
1581   - * Returns 1 if @urb describes an IN transfer (device-to-host),
  1585 + * Return: 1 if @urb describes an IN transfer (device-to-host),
1582 1586 * otherwise 0.
1583 1587 */
1584 1588 static inline int usb_urb_dir_in(struct urb *urb)
... ... @@ -1590,7 +1594,7 @@
1590 1594 * usb_urb_dir_out - check if an URB describes an OUT transfer
1591 1595 * @urb: URB to be checked
1592 1596 *
1593   - * Returns 1 if @urb describes an OUT transfer (host-to-device),
  1597 + * Return: 1 if @urb describes an OUT transfer (host-to-device),
1594 1598 * otherwise 0.
1595 1599 */
1596 1600 static inline int usb_urb_dir_out(struct urb *urb)