[hid:for-5.13/thrustmaster 1/1] drivers/hid/hid-thrustmaster.c:62: warning: wrong kernel-doc identifier on line:

[kernel test robot <lkp@intel.com>]

[-- Attachment #1: Type: text/plain, Size: 10711 bytes --]

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git for-5.13/thrustmaster
head:   c49c33637802a2c6957a78119eb8be3b055dd9e9
commit: c49c33637802a2c6957a78119eb8be3b055dd9e9 [1/1] HID: support for initialization of some Thrustmaster wheels
config: arm64-randconfig-r033-20210318 (attached as .config)
compiler: clang version 13.0.0 (https://github.com/llvm/llvm-project fcc1ce00931751ac02498986feb37744e9ace8de)
reproduce (this is a W=1 build):
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # install arm64 cross compiling tool for clang build
        # apt-get install binutils-aarch64-linux-gnu
        # https://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git/commit/?id=c49c33637802a2c6957a78119eb8be3b055dd9e9
        git remote add hid https://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
        git fetch --no-tags hid for-5.13/thrustmaster
        git checkout c49c33637802a2c6957a78119eb8be3b055dd9e9
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross ARCH=arm64 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

   drivers/hid/hid-thrustmaster.c:23: warning: Incorrect use of kernel-doc format:  * These interrupts are used to prevent a nasty crash when initializing the
   drivers/hid/hid-thrustmaster.c:26: warning: cannot understand function prototype: 'const u8 setup_0[] = '
   drivers/hid/hid-thrustmaster.c:49: warning: cannot understand function prototype: 'struct tm_wheel_info '
>> drivers/hid/hid-thrustmaster.c:62: warning: wrong kernel-doc identifier on line:
    * Known wheels.
   drivers/hid/hid-thrustmaster.c:84: warning: cannot understand function prototype: 'struct __packed tm_wheel_response '
   drivers/hid/hid-thrustmaster.c:143: warning: wrong kernel-doc identifier on line:
    * On some setups initializing the T300RS crashes the kernel,
   drivers/hid/hid-thrustmaster.c:202: warning: Function parameter or member 'urb' not described in 'thrustmaster_model_handler'
>> drivers/hid/hid-thrustmaster.c:202: warning: expecting prototype for Called by the USB subsystem when the wheel responses to our request(). Prototype was for thrustmaster_model_handler() instead
   drivers/hid/hid-thrustmaster.c:265: warning: wrong kernel-doc identifier on line:
    * Function called by HID when a hid Thrustmaster FFB wheel is connected to the host.


vim +62 drivers/hid/hid-thrustmaster.c

    21	
    22	/**
  > 23	 * These interrupts are used to prevent a nasty crash when initializing the
    24	 * T300RS. Used in thrustmaster_interrupts().
    25	 */
    26	static const u8 setup_0[] = { 0x42, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
    27	static const u8 setup_1[] = { 0x0a, 0x04, 0x90, 0x03, 0x00, 0x00, 0x00, 0x00 };
    28	static const u8 setup_2[] = { 0x0a, 0x04, 0x00, 0x0c, 0x00, 0x00, 0x00, 0x00 };
    29	static const u8 setup_3[] = { 0x0a, 0x04, 0x12, 0x10, 0x00, 0x00, 0x00, 0x00 };
    30	static const u8 setup_4[] = { 0x0a, 0x04, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00 };
    31	static const u8 *const setup_arr[] = { setup_0, setup_1, setup_2, setup_3, setup_4 };
    32	static const unsigned int setup_arr_sizes[] = {
    33		ARRAY_SIZE(setup_0),
    34		ARRAY_SIZE(setup_1),
    35		ARRAY_SIZE(setup_2),
    36		ARRAY_SIZE(setup_3),
    37		ARRAY_SIZE(setup_4)
    38	};
    39	/**
    40	 * This struct contains for each type of
    41	 * Thrustmaster wheel
    42	 *
    43	 * Note: The values are stored in the CPU
    44	 * endianness, the USB protocols always use
    45	 * little endian; the macro cpu_to_le[BIT]()
    46	 * must be used when preparing USB packets
    47	 * and vice-versa
    48	 */
    49	struct tm_wheel_info {
    50		uint16_t wheel_type;
    51	
    52		/**
    53		 * See when the USB control out packet is prepared...
    54		 * @TODO The TMX seems to require multiple control codes to switch.
    55		 */
    56		uint16_t switch_value;
    57	
    58		char const *const wheel_name;
    59	};
    60	
    61	/**
  > 62	 * Known wheels.
    63	 * Note: TMX does not work as it requires 2 control packets
    64	 */
    65	static const struct tm_wheel_info tm_wheels_infos[] = {
    66		{0x0306, 0x0006, "Thrustmaster T150RS"},
    67		{0x0206, 0x0005, "Thrustmaster T300RS"},
    68		{0x0204, 0x0005, "Thrustmaster T300 Ferrari Alcantara Edition"},
    69		{0x0002, 0x0002, "Thrustmaster T500RS"}
    70		//{0x0407, 0x0001, "Thrustmaster TMX"}
    71	};
    72	
    73	static const uint8_t tm_wheels_infos_length = 4;
    74	
    75	/**
    76	 * This structs contains (in little endian) the response data
    77	 * of the wheel to the request 73
    78	 *
    79	 * A sufficient research to understand what each field does is not
    80	 * beign conducted yet. The position and meaning of fields are a
    81	 * just a very optimistic guess based on instinct....
    82	 */
    83	struct __packed tm_wheel_response
    84	{
    85		/**
    86		 * Seems to be the type of packet
    87		 * - 0x0049 if is data.a (15 bytes)
    88		 * - 0x0047 if is data.b (7 bytes)
    89		 */
    90		uint16_t type;
    91	
    92		union {
    93			struct __packed {
    94				uint16_t field0;
    95				uint16_t field1;
    96				/**
    97				 * Seems to be the model code of the wheel
    98				 * Read table thrustmaster_wheels to values
    99				 */
   100				uint16_t model;
   101	
   102				uint16_t field2;
   103				uint16_t field3;
   104				uint16_t field4;
   105				uint16_t field5;
   106			} a;
   107			struct __packed {
   108				uint16_t field0;
   109				uint16_t field1;
   110				uint16_t model;
   111			} b;
   112		} data;
   113	};
   114	
   115	struct tm_wheel {
   116		struct usb_device *usb_dev;
   117		struct urb *urb;
   118	
   119		struct usb_ctrlrequest *model_request;
   120		struct tm_wheel_response *response;
   121	
   122		struct usb_ctrlrequest *change_request;
   123	};
   124	
   125	/** The control packet to send to wheel */
   126	static const struct usb_ctrlrequest model_request = {
   127		.bRequestType = 0xc1,
   128		.bRequest = 73,
   129		.wValue = 0,
   130		.wIndex = 0,
   131		.wLength = cpu_to_le16(0x0010)
   132	};
   133	
   134	static const struct usb_ctrlrequest change_request = {
   135		.bRequestType = 0x41,
   136		.bRequest = 83,
   137		.wValue = 0, // Will be filled by the driver
   138		.wIndex = 0,
   139		.wLength = 0
   140	};
   141	
   142	/**
   143	 * On some setups initializing the T300RS crashes the kernel,
   144	 * these interrupts fix that particular issue. So far they haven't caused any
   145	 * adverse effects in other wheels.
   146	 */
   147	static void thrustmaster_interrupts(struct hid_device *hdev)
   148	{
   149		int ret, trans, i, b_ep;
   150		u8 *send_buf = kmalloc(256, GFP_KERNEL);
   151		struct usb_host_endpoint *ep;
   152		struct device *dev = &hdev->dev;
   153		struct usb_interface *usbif = to_usb_interface(dev->parent);
   154		struct usb_device *usbdev = interface_to_usbdev(usbif);
   155	
   156		if (!send_buf) {
   157			hid_err(hdev, "failed allocating send buffer\n");
   158			return;
   159		}
   160	
   161		ep = &usbif->cur_altsetting->endpoint[1];
   162		b_ep = ep->desc.bEndpointAddress;
   163	
   164		for (i = 0; i < ARRAY_SIZE(setup_arr); ++i) {
   165			memcpy(send_buf, setup_arr[i], setup_arr_sizes[i]);
   166	
   167			ret = usb_interrupt_msg(usbdev,
   168				usb_sndintpipe(usbdev, b_ep),
   169				send_buf,
   170				setup_arr_sizes[i],
   171				&trans,
   172				USB_CTRL_SET_TIMEOUT);
   173	
   174			if (ret) {
   175				hid_err(hdev, "setup data couldn't be sent\n");
   176				return;
   177			}
   178		}
   179	
   180		kfree(send_buf);
   181	}
   182	
   183	static void thrustmaster_change_handler(struct urb *urb)
   184	{
   185		struct hid_device *hdev = urb->context;
   186	
   187		// The wheel seems to kill himself before answering the host and therefore is violating the USB protocol...
   188		if (urb->status == 0 || urb->status == -EPROTO || urb->status == -EPIPE)
   189			hid_info(hdev, "Success?! The wheel should have been initialized!\n");
   190		else
   191			hid_warn(hdev, "URB to change wheel mode seems to have failed with error %d\n", urb->status);
   192	}
   193	
   194	/**
   195	 * Called by the USB subsystem when the wheel responses to our request
   196	 * to get [what it seems to be] the wheel's model.
   197	 *
   198	 * If the model id is recognized then we send an opportune USB CONTROL REQUEST
   199	 * to switch the wheel to its full capabilities
   200	 */
   201	static void thrustmaster_model_handler(struct urb *urb)
 > 202	{
   203		struct hid_device *hdev = urb->context;
   204		struct tm_wheel *tm_wheel = hid_get_drvdata(hdev);
   205		uint16_t model = 0;
   206		int i, ret;
   207		const struct tm_wheel_info *twi = 0;
   208	
   209		if (urb->status) {
   210			hid_err(hdev, "URB to get model id failed with error %d\n", urb->status);
   211			return;
   212		}
   213	
   214		if (tm_wheel->response->type == cpu_to_le16(0x49))
   215			model = le16_to_cpu(tm_wheel->response->data.a.model);
   216		else if (tm_wheel->response->type == cpu_to_le16(0x47))
   217			model = le16_to_cpu(tm_wheel->response->data.b.model);
   218		else {
   219			hid_err(hdev, "Unknown packet type 0x%x, unable to proceed further with wheel init\n", tm_wheel->response->type);
   220			return;
   221		}
   222	
   223		for (i = 0; i < tm_wheels_infos_length && !twi; i++)
   224			if (tm_wheels_infos[i].wheel_type == model)
   225				twi = tm_wheels_infos + i;
   226	
   227		if (twi)
   228			hid_info(hdev, "Wheel with model id 0x%x is a %s\n", model, twi->wheel_name);
   229		else {
   230			hid_err(hdev, "Unknown wheel's model id 0x%x, unable to proceed further with wheel init\n", model);
   231			return;
   232		}
   233	
   234		tm_wheel->change_request->wValue = cpu_to_le16(twi->switch_value);
   235		usb_fill_control_urb(
   236			tm_wheel->urb,
   237			tm_wheel->usb_dev,
   238			usb_sndctrlpipe(tm_wheel->usb_dev, 0),
   239			(char *)tm_wheel->change_request,
   240			0, 0, // We do not expect any response from the wheel
   241			thrustmaster_change_handler,
   242			hdev
   243		);
   244	
   245		ret = usb_submit_urb(tm_wheel->urb, GFP_ATOMIC);
   246		if (ret)
   247			hid_err(hdev, "Error %d while submitting the change URB. I am unable to initialize this wheel...\n", ret);
   248	}
   249	

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 30553 bytes --]