Commit 365038f2 authored by Chunfeng Yun's avatar Chunfeng Yun Committed by Greg Kroah-Hartman
Browse files

usb: common: move function's kerneldoc next to its definition 



Following a general rule, add the kerneldoc for a function next
to it's definition, but not next to its declaration in a header
file.

Suggested-by: default avatarAlan Stern <stern@rowland.harvard.edu>
Suggested-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: default avatarChunfeng Yun <chunfeng.yun@mediatek.com>
Link: https://lore.kernel.org/r/c4d2e010ae2bf67cdfa0b55e6d1deb9339d9d3dc.1615170625.git.chunfeng.yun@mediatek.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent f18b6edb

drivers/usb/common/common.c

+35 −0
Original line number Diff line number Diff line
@@ -25,6 +25,12 @@ static const char *const ep_type_names[] = { 
	[USB_ENDPOINT_XFER_INT] = "intr",

};



/**

 * usb_ep_type_string() - Returns human readable-name of the endpoint type.

 * @ep_type: The endpoint type to return human-readable name for.  If it's not

 *   any of the types: USB_ENDPOINT_XFER_{CONTROL, ISOC, BULK, INT},

 *   usually got by usb_endpoint_type(), the string 'unknown' will be returned.

 */

const char *usb_ep_type_string(int ep_type)

{

	if (ep_type < 0 || ep_type >= ARRAY_SIZE(ep_type_names))
@@ -76,6 +82,12 @@ static const char *const ssp_rate[] = { 
	[USB_SSP_GEN_2x2] = "super-speed-plus-gen2x2",

};



/**

 * usb_speed_string() - Returns human readable-name of the speed.

 * @speed: The speed to return human-readable name for.  If it's not

 *   any of the speeds defined in usb_device_speed enum, string for

 *   USB_SPEED_UNKNOWN will be returned.

 */

const char *usb_speed_string(enum usb_device_speed speed)

{

	if (speed < 0 || speed >= ARRAY_SIZE(speed_names))
@@ -84,6 +96,14 @@ const char *usb_speed_string(enum usb_device_speed speed) 
}

EXPORT_SYMBOL_GPL(usb_speed_string);



/**

 * usb_get_maximum_speed - Get maximum requested speed for a given USB

 * controller.

 * @dev: Pointer to the given USB controller device

 *

 * The function gets the maximum speed string from property "maximum-speed",

 * and returns the corresponding enum usb_device_speed.

 */

enum usb_device_speed usb_get_maximum_speed(struct device *dev)

{

	const char *maximum_speed;
@@ -102,6 +122,15 @@ enum usb_device_speed usb_get_maximum_speed(struct device *dev) 
}

EXPORT_SYMBOL_GPL(usb_get_maximum_speed);



/**

 * usb_get_maximum_ssp_rate - Get the signaling rate generation and lane count

 *	of a SuperSpeed Plus capable device.

 * @dev: Pointer to the given USB controller device

 *

 * If the string from "maximum-speed" property is super-speed-plus-genXxY where

 * 'X' is the generation number and 'Y' is the number of lanes, then this

 * function returns the corresponding enum usb_ssp_rate.

 */

enum usb_ssp_rate usb_get_maximum_ssp_rate(struct device *dev)

{

	const char *maximum_speed;
@@ -116,6 +145,12 @@ enum usb_ssp_rate usb_get_maximum_ssp_rate(struct device *dev) 
}

EXPORT_SYMBOL_GPL(usb_get_maximum_ssp_rate);



/**

 * usb_state_string - Returns human readable name for the state.

 * @state: The state to return a human-readable name for. If it's not

 *	any of the states devices in usb_device_state_string enum,

 *	the string UNKNOWN will be returned.

 */

const char *usb_state_string(enum usb_device_state state)

{

	static const char *const names[] = {

drivers/usb/common/debug.c

+20 −2
Original line number Diff line number Diff line
@@ -207,8 +207,26 @@ static void usb_decode_set_isoch_delay(__u8 wValue, char *str, size_t size) 
	snprintf(str, size, "Set Isochronous Delay(Delay = %d ns)", wValue);

}



/*

 * usb_decode_ctrl - returns a string representation of ctrl request

/**

 * usb_decode_ctrl - Returns human readable representation of control request.

 * @str: buffer to return a human-readable representation of control request.

 *       This buffer should have about 200 bytes.

 * @size: size of str buffer.

 * @bRequestType: matches the USB bmRequestType field

 * @bRequest: matches the USB bRequest field

 * @wValue: matches the USB wValue field (CPU byte order)

 * @wIndex: matches the USB wIndex field (CPU byte order)

 * @wLength: matches the USB wLength field (CPU byte order)

 *

 * Function returns decoded, formatted and human-readable description of

 * control request packet.

 *

 * The usage scenario for this is for tracepoints, so function as a return

 * use the same value as in parameters. This approach allows to use this

 * function in TP_printk

 *

 * Important: wValue, wIndex, wLength parameters before invoking this function

 * should be processed by le16_to_cpu macro.

 */

const char *usb_decode_ctrl(char *str, size_t size, __u8 bRequestType,

			    __u8 bRequest, __u16 wValue, __u16 wIndex,

include/linux/usb/ch9.h

+0 −61
Original line number Diff line number Diff line
@@ -45,76 +45,15 @@ enum usb_ssp_rate { 
	USB_SSP_GEN_2x2,

};



/**

 * usb_ep_type_string() - Returns human readable-name of the endpoint type.

 * @ep_type: The endpoint type to return human-readable name for.  If it's not

 *   any of the types: USB_ENDPOINT_XFER_{CONTROL, ISOC, BULK, INT},

 *   usually got by usb_endpoint_type(), the string 'unknown' will be returned.

 */

extern const char *usb_ep_type_string(int ep_type);



/**

 * usb_speed_string() - Returns human readable-name of the speed.

 * @speed: The speed to return human-readable name for.  If it's not

 *   any of the speeds defined in usb_device_speed enum, string for

 *   USB_SPEED_UNKNOWN will be returned.

 */

extern const char *usb_speed_string(enum usb_device_speed speed);



/**

 * usb_get_maximum_speed - Get maximum requested speed for a given USB

 * controller.

 * @dev: Pointer to the given USB controller device

 *

 * The function gets the maximum speed string from property "maximum-speed",

 * and returns the corresponding enum usb_device_speed.

 */

extern enum usb_device_speed usb_get_maximum_speed(struct device *dev);



/**

 * usb_get_maximum_ssp_rate - Get the signaling rate generation and lane count

 *	of a SuperSpeed Plus capable device.

 * @dev: Pointer to the given USB controller device

 *

 * If the string from "maximum-speed" property is super-speed-plus-genXxY where

 * 'X' is the generation number and 'Y' is the number of lanes, then this

 * function returns the corresponding enum usb_ssp_rate.

 */

extern enum usb_ssp_rate usb_get_maximum_ssp_rate(struct device *dev);



/**

 * usb_state_string - Returns human readable name for the state.

 * @state: The state to return a human-readable name for. If it's not

 *	any of the states devices in usb_device_state_string enum,

 *	the string UNKNOWN will be returned.

 */

extern const char *usb_state_string(enum usb_device_state state);



unsigned int usb_decode_interval(const struct usb_endpoint_descriptor *epd,

				 enum usb_device_speed speed);



#ifdef CONFIG_TRACING

/**

 * usb_decode_ctrl - Returns human readable representation of control request.

 * @str: buffer to return a human-readable representation of control request.

 *       This buffer should have about 200 bytes.

 * @size: size of str buffer.

 * @bRequestType: matches the USB bmRequestType field

 * @bRequest: matches the USB bRequest field

 * @wValue: matches the USB wValue field (CPU byte order)

 * @wIndex: matches the USB wIndex field (CPU byte order)

 * @wLength: matches the USB wLength field (CPU byte order)

 *

 * Function returns decoded, formatted and human-readable description of

 * control request packet.

 *

 * The usage scenario for this is for tracepoints, so function as a return

 * use the same value as in parameters. This approach allows to use this

 * function in TP_printk

 *

 * Important: wValue, wIndex, wLength parameters before invoking this function

 * should be processed by le16_to_cpu macro.

 */

extern const char *usb_decode_ctrl(char *str, size_t size, __u8 bRequestType,

				   __u8 bRequest, __u16 wValue, __u16 wIndex,

				   __u16 wLength);