Add a usbdevfs fd with the synchronous ioctls

[jotpalch]

NOTE: piece C of the USB layer described in #319, on top of #334 and #351. It adds the usbdevfs descriptor and the synchronous half of its ioctl surface. Transfers that need the asynchronous engine (SUBMITURB, REAPURB, DISCARDURB) are the next piece and are not here; this one answers ENOTTY for them and reports no URB capability bits, which is what makes that honest.

Summary

A guest that opens /dev/bus/usb/BBB/DDD gets a descriptor whose file contract and ioctl surface follow drivers/usb/core/devio.c: the permission answers, the write family, the file position, the argument validation the kernel does before it touches the wire, and the synchronous operations mapped onto IOUSBDeviceInterface650 and IOUSBInterfaceInterface800. CLAIMINTERFACE, RELEASEINTERFACE, SETINTERFACE, SETCONFIGURATION, CONTROL, BULK, CLEAR_HALT, RESETEP, RESET, GETDRIVER, DISCONNECT_CLAIM, IOCTL, CONNECTINFO, GET_SPEED and GET_CAPABILITIES are implemented.

Driver arbitration is per object and dynamic, not per device

The one design point worth stating up front, because it changed after measurement. macOS arbitration is not a property of a device class that can be decided in advance. A device-level open succeeds whenever the bound driver holds no exclusive device open, and an interface-level open succeeds unless that specific driver currently holds that specific interface. So the layer attempts the open and maps the IOKit result rather than refusing by class.

Measured on an attached ESP32-S3 (303a:1001), with a native IOKit probe run at the same moment as the guest call:

nothing holding /dev/cu.usbmodem1101:
  USBInterfaceOpen(interface 1, bound to AppleUSBACMData) = 0x00000000
  CLAIMINTERFACE 1                                        = 0
the tty held:
  USBInterfaceOpen(interface 1)                           = kIOReturnExclusiveAccess
  CLAIMINTERFACE 1                                        = -EBUSY
interface 0 (CDC control, AppleUSBACMControl)             = -EBUSY either way
interface 2 (vendor class, no matching driver)            = 0 either way

An earlier revision refused interface 1 outright because a driver was bound to it, which refused work macOS allows. A tool that talks to a board over the vendor interface while the CDC tty stays available to the rest of the system is the case this serves.

What the argument validation follows

Each of these is a devio.c line rather than a guess, and each has an assertion in the new lane.

• Every ioctl on an O_RDONLY descriptor is EPERM (devio.c:2605), which is FMODE_WRITE and not a permission check on the node.
• check_ctrlrecip runs before the wLength cap (devio.c:1176-1181), and findintfep before the transfer-length checks (devio.c:1289-1298), so an absent endpoint outranks a malformed length rather than the other way round.
• The reserved-bit test on an endpoint address (devio.c:860) lives in the one lookup all four endpoint ioctls share.
• The interface-number bound is 64, not 32: claimintf refuses ifnum >= 8 * sizeof(ps->ifclaimed) and ifclaimed is an unsigned long (devio.c:75, :785). Between 32 and 64 an interface is merely absent, which is a question about the device, so the claimed mask is a uint64_t.
• DISCONNECT_CLAIM answers EINVAL for an interface the device does not have (devio.c:2467-2469), the opposite of claimintf's ENOENT.
• USBDEVFS_IOCTL with CONNECT on an interface that already has a driver is EBUSY (devio.c:2357-2361); only a free one reaches device_attach.

Deviations, recorded rather than implied

These are printed by the lane as XFAIL rows carrying both values, so they stay visible in its own output rather than living only in a commit message.

• RESET: Linux re-enumerates the port. IOKit's equivalent is USBDeviceReEnumerate, which is an unplug that tears down the user client, so this clears the claimed pipes' stalls and returns 0 instead.
• Once a device is gone, Linux answers ENODEV for every ioctl. This still serves GET_SPEED, CONNECTINFO, GET_CAPABILITIES and read() from the model captured at open, because noticing the departure needs an IOKit termination notification on a run loop, which is the next piece's machinery.
• GETDRIVER reports the IOKit class (AppleUSBACMControl) where Linux reports the driver name (cdc_acm), and DISCONNECT_CLAIM's name filters compare against it. A guest asking to detach cdc_acm by name will not match.
• A short bulk OUT reports EIO: WritePipeTO returns no length, so the byte count Linux would report is not available.
• The side table holds 32 descriptors per process and reports ENOMEM past that, where Linux has no such limit.

Tests

tests/test-usbdev-ioctl.c is a new lane, 54 assertions, that needs no hardware: it runs against ELFUSE_USB_FIXTURE, whose devices are modeled but have no IOKit service behind them, which is exactly the shape of a device the model knows and the machine cannot reach. It covers the half of usbdevfs decided before the wire. Run without the fixture it prints its unmet precondition and exits rather than reporting assertions that failed for the wrong reason.

The half that needs a device, a real claim and a real transfer and arbitration against a bound host driver, is verified on the attached board and is not pretended to be covered by the lane.

Evidence

make check BAREMETAL_CROSS=aarch64-elf-   All 98 tests passed, exit 0
test-usbdev-ioctl                          54 passed, 0 failed
test-usb-sysfs                            138 passed, 0 failed
test-usb-sysfs-matrix                     288 passed, 0 failed
test-epoll, test-fcntl-flags, test-dir-fd-budget   OK

---

Summary by cubic

Implements the synchronous usbdevfs portion described in #319. Writable opens of /dev/bus/usb/BBB/DDD previously returned EACCES; they now create a typed fd that serves the descriptor blob and maps synchronous ioctls to IOKit, while async URBs remain ENOTTY with no capability bits. Wire access resolves lazily, so modeled devices can open without a matching host service and report ENODEV only when an operation needs hardware.

Behavior

• Supports interface claims, alternate settings, configuration, control and bulk transfers, pipe stalls, driver queries, disconnect/attach, speed, and connection information.
• Attempts interface arbitration through IOKit, returning EBUSY only while the interface is held.
• Preserves Linux ioctl and write-family permission gates, validation order, endpoint checks, interface bounds, and errno mappings.
• Enforces the shared 16 MB usbfs_memory_mb allowance across in-flight transfers, refunding on every exit path.
• Serves read, pread, readv, and lseek from a per-open descriptor position and reports fstat as USB char device 189:minor.
• Refuses dup() and fork inheritance; O_PATH continues using the existing path-only fd.

Tests and known gaps

• Adds a hardware-free 92-assertion ioctl lane plus fault runs for allocation, out-of-range interface numbers, and fd-publication races.
• Board checks cover claim arbitration, transfers, stalls, timeouts, driver reporting, and validation edge cases.
• XFAILs record missing disconnect detection, serialized ioctls per fd, IOKit class names in GETDRIVER, non-reenumerating RESET, short bulk OUT as EIO, the 32-fd side-table limit, and cross-fd disconnect behavior.

^{Written for commit dfdd55c. Summary will update on new commits.}

[jserv]

mine = !u->dead is the only claim test, so this can retire an entry that is no longer the one this open created. If the guest closes guest_fd right after the publish at 1318, usbdev_fd_cleanup tears this entry down and usbdev_unref frees the slot (used = false); a sibling usbdev_open_path can then take that slot and bind its own live fd before 1334 runs. This call marks that entry dead, frees its blob and closes its pipe_wr, and the new fd answers EBADF on every read and ioctl. Same failure the generation tiebreak in usbdev_fd_cleanup exists to avoid.

Pass guest_fd and gen in, and claim only when u->used && !u->dead && u->guest_fd == guest_fd && u->generation == gen.

[jotpalch]

Confirmed and reproduced. With the claim narrowed back to !u->dead and ELFUSE_USBDEV_RETIRE_DELAY_US widening the window, the sibling fd that was never closed answers errno 9 on both pread and GET_SPEED, two assertions failing; with the tuple restored it passes. This lands squarely on our own answer to C10: we added the generation recheck to close the pre-bind window, but the retire helper it calls claimed the slot on "not dead" alone, so in the post-bind window it marked the sibling's live entry dead, freed its blob and closed its pipe. That is the same failure usbdev_fd_cleanup's generation tiebreak already existed to avoid, reintroduced on the other side of the same bind, so the earlier fix was incomplete in one direction and actively harmful in the other. usbdev_retire_unpublished now takes guest_fd and gen and claims u->used && !u->dead && u->guest_fd == guest_fd && u->generation == gen, with all four fields read under usbdev_table_lock so they are read as one value. The window is driven by a new hook in the shape the file already uses, and test-usbdev-faults runs it.

[jserv]

fd_alloc_from() takes an out_gen captured inside the allocating fd_lock section, which is the proof this path re-derives by hand at 1315. Re-reading after the slot is publishable means that if the guest closes guest_fd and any thread reopens the same number as another FD_USBDEV fd in the window, gen is the other allocation's stamp: the guard at 1334 compares equal, no retire happens, and both entries then match guest_fd == fd && generation == snap.generation in usbdev_acquire, which returns whichever sits lower. The orphan keeps its slot, blob and pipe write end for the life of the process, which is the leak this comment says was closed.

fd_alloc_from(0, FD_USBDEV, pipefd[0], usbdev_fd_cleanup, &gen) removes the window and one fd_lock trip.

[jotpalch]

Confirmed and fixed exactly as you describe: fd_alloc_from(0, FD_USBDEV, pipefd[0], usbdev_fd_cleanup, &gen), with the later fd_current_generation read and its fd_lock trip deleted. fd_alloc_from's own comment already documents this contract for dup, so the re-derivation was working against an API that exists to prevent it. This is our own C10 answer again, and the history is the point: before that round the re-read fed only the publish, and the comment above it called the staleness an accepted race. Adding the recheck made it load-bearing without revisiting where the value came from, so in the pre-bind window the generation could be a reopening thread's stamp, both entries held the identical {guest_fd, generation}, the guard compared equal and retired nothing, and usbdev_acquire, which matches on that same pair, answered from whichever sat lower. Reproduced by moving the re-derivation back inside the widened window: the fd read back the idVendor of the other bus and the table went from 32 slots to 31. One correction to a claim I made last round, rather than leave it for you to find: the shipped ELFUSE_USBDEV_PUBLISH_DELAY_US does not expose this by itself, because the pre-fix code took the re-read ahead of the hook, so that lane passes against the old code. The evidence is the mutation, and what closes the window now is that there is no second read left to race.

[jserv]

do_vfs_ioctl handles FIONBIO and FIOASYNC for every file before f_op->unlocked_ioctl runs, so Linux answers them on a usbdevfs fd. This early return sends them into usbdev_ioctl, whose default arm is ENOTTY and whose FMODE_WRITE gate fires first on an O_RDONLY fd: ioctl(fd, FIONBIO, &one) returns 0 and sets O_NONBLOCK on Linux, ENOTTY here (EPERM read-only), while fcntl(fd, F_SETFL, O_NONBLOCK) on the same fd still succeeds. Two entry points onto one flag disagree.

FIOCLEX and FIONCLEX are already tested above this branch; these two belong there.

[jotpalch]

Confirmed against a container. On both a char device and a plain file, in all four access modes, Linux answers FIONBIO(1) = 0 and sets O_NONBLOCK, FIOASYNC(1) = ENOTTY, and FIOASYNC(0) = 0. Ours sent both into usbdev_ioctl, so FIONBIO came back EPERM on a read-only fd and ENOTTY on a writable one while fcntl(F_SETFL, O_NONBLOCK) on the same descriptor succeeded and F_GETFL reported the flag, which is the disagreement you name. Both are now answered beside FIOCLEX and FIONCLEX, where do_vfs_ioctl answers them before it calls f_op->unlocked_ioctl (fs/ioctl.c:818-822), so no other fd type's path changes. FIONBIO edits only the guest flag word and always reports 0, as ioctl_fionbio does (fs/ioctl.c:342-363), and the readiness pipe behind the fd stays nonblocking whatever the guest asks. FIOASYNC is not an unconditional 0: ioctl_fioasync consults f_op->fasync only when the request would change the FASYNC state and usbdev_file_operations declares none (devio.c:2846-2856), so asking for the state the fd already has is 0 and asking to change it is ENOTTY. 12 assertions fail with the arm removed.

[jserv]

usbfs_memory_mb is a global in-flight allowance charged by usbfs_increase_memory_usage and refunded on completion, not a per-call size cap. Two consequences: bt.len == USBDEV_BULK_MAX passes here, where Linux charges len + sizeof(struct urb) against the same 16 MB and returns ENOMEM; and nothing accumulates across fds, so a guest holding all 32 side-table slots can keep 32 concurrent 16 MB buffers live in the host.

An atomic byte counter charged here and refunded after the transfer gets both.

[jotpalch]

Confirmed. usbfs_memory_mb is one module-global allowance, charged len + sizeof(struct urb) at devio.c:1308 and given back by usbfs_decrease_memory_usage (devio.c:145-178), not a per-call size cap. An atomic counter now carries the total, charged before the buffer is allocated and refunded on every exit from there down, which is why the OUT path's guest_read failure joins the single exit instead of returning from the middle. A transfer of exactly the allowance is now ENOMEM, one just under it goes through twice, and it survives a faulting transfer; each of those three assertions fails under its own mutation, the dropped tail refund and the dropped EFAULT refund included. Two things I did not fix, rather than claim: the per-URB charge is a named constant and not an assertion about sizeof(struct urb), which is kernel-internal and config-dependent and which I cannot measure here, so the INT_MAX - sizeof(struct urb) EINVAL boundary is still spelled INT32_MAX and a narrow band of lengths answers ENOMEM where Linux answers EINVAL, both rejections. And the across-fd accumulation is measured but not asserted: the loopback model retires a transfer before a second can overlap it, and refusing 32 concurrent 16 MB requests would not demonstrate it either, since the per-request boundary already refuses every one of them on its own.

[jserv]

This tests the literal value O_RDONLY, but Linux derives the gate from OPEN_FMODE(flags) = (flags + 1) & O_ACCMODE, which gives access mode 3 neither FMODE_READ nor FMODE_WRITE. open("/dev/bus/usb/001/001", 3) succeeds (0666 node, ACC_MODE(3) is read plus write) and the fd passes this gate, so every ioctl is accepted where Linux answers EPERM. Same shape for the read gates at 1347 and 1385.

Deriving the two capability bits once from (accmode + 1) & 3 covers all four.

[jotpalch]

Confirmed, including the reachability. ACC_MODE(3) is "\006", read plus write, so open(node, 3) succeeds on this 0666 node, while OPEN_FMODE(3) is (3 + 1) & O_ACCMODE = 0 and gives neither FMODE_READ nor FMODE_WRITE (fs.h:3630, :3631). Measured in a container on a char device and on a plain file: the open succeeds and read, pread and write are all EBADF. The two capability bits now come from one derivation, and five gates read it rather than four: read, pread, the write refusal, the ioctl gate, and a new read refusal for io.c's empty-vector arm, which carried the same defect and was not in your list. 7 assertions fail with the literal test restored. One more of this shape that the four did not reach, since you asked the general question: the async stage's poll remap decided writability with (flags & O_ACCMODE) != O_RDONLY, where usbdev_poll gates EPOLLOUT|EPOLLWRNORM on FMODE_WRITE (devio.c:2837). It now reads the same derivation. No guest can observe that one today, because reaching POLLOUT needs a reapable completion and SUBMITURB on such an fd is already EPERM, so it is a consistency fix and I have not added an assertion that would have passed with the literal test too.

[jserv]

Thank @jotpalch for contributing!