feat(usb): gadget: f_hid: add wakeup_on_write support (#57)

* usb: gadget: f_hid: add wakeup_on_write support

Add an opt-in wakeup_on_write configfs attribute to the HID function
driver.  When enabled, each write to /dev/hidgN calls
usb_gadget_wakeup() before queuing the USB request, allowing HID input
to wake a suspended host.

The configuration descriptor must also advertise remote wakeup capability
(bmAttributes bit 5) for the host to arm the feature during enumeration.

This is useful for KVM-over-IP devices that need to wake a sleeping host
machine by sending keyboard or mouse input.

Tested on JetKVM v2 (RV1106 SoC, DWC3 v3.30a) waking a Windows 11 host
from S3 sleep via Intel xHCI USB 3.1 controller.  Host wakes in ~4
seconds from HID keystroke.

Closes: jetkvm/kvm#120
Closes: jetkvm/kvm#674

* fix: guard func.config dereference in f_hidg_write

Move the hidg->func.config->cdev dereference inside the
wakeup_on_write guard block and add a NULL check on func.config
before accessing cdev. This prevents a potential NULL pointer
dereference if f_hidg_write races with unbind, where func.config
can be NULL before the spinlock is acquired.

The cdev variable was only used for the wakeup call, so scoping
it to the guard block is safe.

Author: jlian

sysdrv/source/kernel/drivers/usb/gadget/function/f_hid.c

@@ -54,6 +54,8 @@ struct f_hidg {
 	 *              will be used to receive reports.
 	 */
 	bool				use_out_ep;
+	/* attempt to wake the host when writing a report */
+	bool				wakeup_on_write;
 
 	/* recv report */
 	spinlock_t			read_spinlock;
@@ -434,6 +436,19 @@ static ssize_t f_hidg_write(struct file *file, const char __user *buffer,
 	unsigned long flags;
 	ssize_t status = -ENOMEM;
 
+	/*
+	 * Try to wake the host if it suspended the bus.  The wakeup request
+	 * is only honoured when the host has negotiated remote-wakeup during
+	 * enumeration (indicated by the bmAttributes remote-wakeup bit in the
+	 * configuration descriptor).  If the UDC or the host does not support
+	 * wakeup the call simply returns an error we can safely ignore.
+	 */
+	if (hidg->wakeup_on_write && hidg->func.config) {
+		struct usb_composite_dev *cdev = hidg->func.config->cdev;
+		if (cdev && cdev->gadget)
+			usb_gadget_wakeup(cdev->gadget);
+	}
+
 	spin_lock_irqsave(&hidg->write_spinlock, flags);
 
 	if (!hidg->req) {
@@ -1097,6 +1112,7 @@ CONFIGFS_ATTR(f_hid_opts_, name)
 F_HID_OPT(subclass, 8, 255);
 F_HID_OPT(protocol, 8, 255);
 F_HID_OPT(no_out_endpoint, 8, 1);
+F_HID_OPT(wakeup_on_write, 8, 1);
 F_HID_OPT(report_length, 16, 65535);
 
 static ssize_t f_hid_opts_report_desc_show(struct config_item *item, char *page)
@@ -1157,6 +1173,7 @@ static struct configfs_attribute *hid_attrs[] = {
 	&f_hid_opts_attr_subclass,
 	&f_hid_opts_attr_protocol,
 	&f_hid_opts_attr_no_out_endpoint,
+	&f_hid_opts_attr_wakeup_on_write,
 	&f_hid_opts_attr_report_length,
 	&f_hid_opts_attr_report_desc,
 	&f_hid_opts_attr_dev,
@@ -1297,6 +1314,7 @@ static struct usb_function *hidg_alloc(struct usb_function_instance *fi)
 		}
 	}
 	hidg->use_out_ep = !opts->no_out_endpoint;
+	hidg->wakeup_on_write = opts->wakeup_on_write;
 
 	mutex_unlock(&opts->lock);
 

sysdrv/source/kernel/drivers/usb/gadget/function/u_hid.h

@@ -21,6 +21,7 @@ struct f_hid_opts {
 	unsigned char			subclass;
 	unsigned char			protocol;
 	unsigned char			no_out_endpoint;
+	unsigned char			wakeup_on_write;
 	unsigned short			report_length;
 	unsigned short			report_desc_length;
 	unsigned char			*report_desc;