From owner-p4-projects@FreeBSD.ORG Tue Feb 19 18:22:22 2008 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 8C16316A468; Tue, 19 Feb 2008 18:22:22 +0000 (UTC) Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 49A3716A419 for ; Tue, 19 Feb 2008 18:22:22 +0000 (UTC) (envelope-from hselasky@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id 37A6013C4CC for ; Tue, 19 Feb 2008 18:22:22 +0000 (UTC) (envelope-from hselasky@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.1/8.14.1) with ESMTP id m1JIMM6I085205 for ; Tue, 19 Feb 2008 18:22:22 GMT (envelope-from hselasky@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.1/8.14.1/Submit) id m1JIMLIO085202 for perforce@freebsd.org; Tue, 19 Feb 2008 18:22:21 GMT (envelope-from hselasky@FreeBSD.org) Date: Tue, 19 Feb 2008 18:22:21 GMT Message-Id: <200802191822.m1JIMLIO085202@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to hselasky@FreeBSD.org using -f From: Hans Petter Selasky To: Perforce Change Reviews Cc: Subject: PERFORCE change 135732 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 Feb 2008 18:22:23 -0000 http://perforce.freebsd.org/chv.cgi?CH=135732 Change 135732 by hselasky@hselasky_laptop001 on 2008/02/19 18:21:43 Add more documentation to "usb_requests.c". Affected files ... .. //depot/projects/usb/src/sys/dev/usb/usb_requests.c#19 edit Differences ... ==== //depot/projects/usb/src/sys/dev/usb/usb_requests.c#19 (text+ko) ==== @@ -62,6 +62,14 @@ /*------------------------------------------------------------------------* * usbreq_reset_port + * + * This function will instruct an USB HUB to perform a reset sequence + * on the specified port number. + * + * Returns: + * 0: Success. The USB device should now be at address zero. + * Else: Failure. No USB device is present and the USB port should be + * disabled. *------------------------------------------------------------------------*/ usbd_status_t usbreq_reset_port(struct usbd_device *udev, struct mtx *mtx, uint8_t port) @@ -149,6 +157,21 @@ /*------------------------------------------------------------------------* * usbreq_get_desc + * + * This function can be used to retrieve USB descriptors. It contains + * some additional logic like zeroing of missing descriptor bytes and + * retrying an USB descriptor in case of failure. The "min_len" + * argument specifies the minimum descriptor length. The "max_len" + * argument specifies the maximum descriptor length. If the real + * descriptor length is less than the minimum length the missing + * byte(s) will be zeroed. The length field, first byte, of the USB + * descriptor will get overwritten in case it indicates a length that + * is too big. Also the type field, second byte, of the USB descriptor + * will get forced to the correct type. + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_desc(struct usbd_device *udev, struct mtx *mtx, void *desc, @@ -228,6 +251,10 @@ * using the first language ID. The maximum length "len" includes * the terminating zero. The "len" argument should be twice as * big pluss 2 bytes, compared with the actual maximum string length ! + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_string_any(struct usbd_device *udev, struct mtx *mtx, char *buf, @@ -308,6 +335,10 @@ * * If you don't know the language ID, consider using * "usbreq_get_string_any()". + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_string_desc(struct usbd_device *udev, struct mtx *mtx, void *sdesc, @@ -320,6 +351,10 @@ /*------------------------------------------------------------------------* * usbreq_get_config_desc + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_config_desc(struct usbd_device *udev, struct mtx *mtx, usb_config_descriptor_t *d, @@ -343,6 +378,14 @@ /*------------------------------------------------------------------------* * usbreq_get_config_desc_full + * + * This function gets the complete USB configuration descriptor, + * limited by the specified "size" which is usually equal to the + * "wTotalLength" field stored in the USB configuration descriptor. + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_config_desc_full(struct usbd_device *udev, struct mtx *mtx, void *d, @@ -355,6 +398,10 @@ /*------------------------------------------------------------------------* * usbreq_get_device_desc + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_device_desc(struct usbd_device *udev, struct mtx *mtx, @@ -367,6 +414,10 @@ /*------------------------------------------------------------------------* * usbreq_get_alt_interface_no + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_alt_interface_no(struct usbd_device *udev, struct mtx *mtx, @@ -389,6 +440,10 @@ /*------------------------------------------------------------------------* * usbreq_set_alt_interface_no + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_alt_interface_no(struct usbd_device *udev, struct mtx *mtx, @@ -412,6 +467,10 @@ /*------------------------------------------------------------------------* * usbreq_get_device_status + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_device_status(struct usbd_device *udev, struct mtx *mtx, @@ -429,6 +488,10 @@ /*------------------------------------------------------------------------* * usbreq_get_hub_descriptor + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_hub_descriptor(struct usbd_device *udev, struct mtx *mtx, @@ -446,6 +509,10 @@ /*------------------------------------------------------------------------* * usbreq_get_hub_status + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_hub_status(struct usbd_device *udev, struct mtx *mtx, @@ -463,6 +530,13 @@ /*------------------------------------------------------------------------* * usbreq_set_address + * + * This function is used to set the address for an USB device. After + * port reset the USB device will respond at address zero. + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_address(struct usbd_device *udev, struct mtx *mtx, uint16_t addr) @@ -484,6 +558,10 @@ /*------------------------------------------------------------------------* * usbreq_get_port_status + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_port_status(struct usbd_device *udev, struct mtx *mtx, @@ -502,6 +580,10 @@ /*------------------------------------------------------------------------* * usbreq_clear_hub_feature + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_clear_hub_feature(struct usbd_device *udev, struct mtx *mtx, @@ -519,6 +601,10 @@ /*------------------------------------------------------------------------* * usbreq_set_hub_feature + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_hub_feature(struct usbd_device *udev, struct mtx *mtx, @@ -536,6 +622,10 @@ /*------------------------------------------------------------------------* * usbreq_clear_port_feature + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_clear_port_feature(struct usbd_device *udev, struct mtx *mtx, @@ -554,6 +644,10 @@ /*------------------------------------------------------------------------* * usbreq_set_port_feature + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_port_feature(struct usbd_device *udev, struct mtx *mtx, @@ -572,6 +666,10 @@ /*------------------------------------------------------------------------* * usbreq_set_protocol + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_protocol(struct usbd_device *udev, struct mtx *mtx, @@ -597,6 +695,10 @@ /*------------------------------------------------------------------------* * usbreq_set_report + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_report(struct usbd_device *udev, struct mtx *mtx, void *data, uint16_t len, @@ -621,6 +723,10 @@ /*------------------------------------------------------------------------* * usbreq_get_report + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_report(struct usbd_device *udev, struct mtx *mtx, void *data, @@ -645,6 +751,10 @@ /*------------------------------------------------------------------------* * usbreq_set_idle + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_idle(struct usbd_device *udev, struct mtx *mtx, @@ -669,6 +779,10 @@ /*------------------------------------------------------------------------* * usbreq_get_report_descriptor + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_report_descriptor(struct usbd_device *udev, struct mtx *mtx, @@ -691,6 +805,14 @@ /*------------------------------------------------------------------------* * usbreq_set_config + * + * This function is used to select the current configuration number in + * both USB device side mode and USB host side mode. When setting the + * configuration the function of the interfaces can change. + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_set_config(struct usbd_device *udev, struct mtx *mtx, uint8_t conf) @@ -721,6 +843,10 @@ /*------------------------------------------------------------------------* * usbreq_get_config + * + * Returns: + * 0: Success + * Else: Failure *------------------------------------------------------------------------*/ usbd_status_t usbreq_get_config(struct usbd_device *udev, struct mtx *mtx, uint8_t *pconf)