mouse: Allow selecting the device to use

Enhance the mouse dump command to support selecting a specific mouse
device by number. This allows testing multiple mouse devices when
available in the system.

Add some documentation while we are here.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <sjg@chromium.org>

cmd/mouse.c

@@ -18,13 +18,21 @@ static int do_mouse_dump(struct cmd_tbl *cmdtp, int flag, int argc,
 	struct udevice *dev;
 	bool running;
 	int count;
+	int mouse_dev = 0;
 	int ret;
 
-	ret = uclass_first_device_err(UCLASS_MOUSE, &dev);
+	/* Parse optional device number */
+	if (argc > 1)
+		mouse_dev = dectoul(argv[1], NULL);
+
+	/* Get the specified mouse device */
+	ret = uclass_get_device(UCLASS_MOUSE, mouse_dev, &dev);
 	if (ret) {
-		printf("Mouse not found (err=%d)\n", ret);
+		printf("Mouse device %d not found (err=%d)\n", mouse_dev, ret);
 		return CMD_RET_FAILURE;
 	}
+
+	printf("Using mouse device %d: %s\n", mouse_dev, dev->name);
 	for (running = true, count = 0; running;) {
 		struct mouse_event evt;
 
@@ -63,7 +71,7 @@ static int do_mouse_dump(struct cmd_tbl *cmdtp, int flag, int argc,
 }
 
 static char mouse_help_text[] =
-	"dump - Dump input from a mouse";
+	"dump [dev] - Dump input from mouse device (default: 0)";
 
 U_BOOT_CMD_WITH_SUBCMDS(mouse, "Mouse input", mouse_help_text,
-	U_BOOT_SUBCMD_MKENT(dump, 1, 1, do_mouse_dump));
+	U_BOOT_SUBCMD_MKENT(dump, 2, 1, do_mouse_dump));

doc/usage/cmd/mouse.rst

@@ -0,0 +1,66 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+.. index::
+   single: mouse (command)
+
+mouse command
+=============
+
+Synopsis
+--------
+
+::
+
+    mouse dump [dev]
+
+The mouse command is used to access mouse input devices.
+
+mouse dump
+----------
+
+Dump input events from a mouse device in real-time. Events are displayed
+until the user presses Ctrl+C to stop.
+
+dev
+    Optional device number (default: 0). Use this to select a specific mouse
+    device when multiple mouse devices are available.
+
+The command displays:
+- Motion events with absolute/relative coordinates and button state
+- Button events (left, right, middle) with press/release state and position
+- Event count when finished
+
+Example
+-------
+
+::
+
+    => mouse dump
+    Using mouse device 0: xhci_pci.p0.usb_hub.p6.usb_mo
+    motion: Xrel=-27, Yrel=84, X=0, Y=84, but=0
+    motion: Xrel=-78, Yrel=87, X=0, Y=171, but=0
+    motion: Xrel=-1, Yrel=87, X=0, Y=258, but=0
+    motion: Xrel=76, Yrel=88, X=76, Y=346, but=0
+    button: button==0, press=1, clicks=1, X=76, Y=346
+    motion: Xrel=76, Yrel=88, X=152, Y=434, but=1
+    motion: Xrel=76, Yrel=88, X=228, Y=522, but=1
+    motion: Xrel=76, Yrel=88, X=304, Y=610, but=1
+    motion: Xrel=76, Yrel=88, X=380, Y=698, but=1
+    button: button==0, press=0, clicks=1, X=380, Y=698
+    motion: Xrel=76, Yrel=88, X=456, Y=786, but=0
+    motion: Xrel=76, Yrel=88, X=532, Y=874, but=0
+    motion: Xrel=50, Yrel=88, X=582, Y=962, but=0
+    motion: Xrel=-1, Yrel=87, X=581, Y=1049, but=0
+    motion: Xrel=76, Yrel=87, X=657, Y=1136, but=0
+    motion: Xrel=-104, Yrel=86, X=553, Y=1222, but=0
+    motion: Xrel=24, Yrel=86, X=577, Y=1308, but=0
+    motion: Xrel=-104, Yrel=85, X=473, Y=1393, but=0
+    18 events received
+
+    => mouse dump 1
+    Mouse device 1 not found (err=-19)
+
+Configuration
+-------------
+
+The mouse command is available when CONFIG_CMD_MOUSE is enabled.

doc/usage/index.rst

@@ -94,6 +94,7 @@ Shell commands
    cmd/mbr
    cmd/md
    cmd/mmc
+   cmd/mouse
    cmd/msr
    cmd/mtest
    cmd/mtrr