daniel/danos
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

usb: hot-plug plumbing, all ports powered, interrupter enabled (M20)

Browse Source 
B3 — the runtime lifecycle a hot-pluggable bus needs, plus two init
fixes that runtime device arrival depends on:

- pump() now handles PORT STATUS CHANGE events (silently dropped
  before): it queues the port, and the bus driver brings the port up
  (a device arrived) or tears it down (a device left) on its tick —
  reporting each interface ChildRemoved to the device manager, which
  prunes the node, notifies watchers, and lets the class driver's world
  end honestly, then Disable Slot frees the controller-side state.
- ALL root-hub ports are powered at init, not just those with a
  boot-time device: an unpowered port (PP=0) cannot signal a later
  connect, so a hot-plug would never be seen.
- the interrupter is enabled (IMAN.IE + USBCMD.INTE) while the ring
  stays polled — some controllers only WRITE runtime events to the
  ring when the interrupter is enabled.

Real-hardware validation is flagged for the user: QEMU's qemu-xhci does
not raise a runtime port-change event to a polling driver on device_add,
so the end-to-end hot-plug path can't be exercised in the harness (the
port-change handling itself IS proven — a late boot device's PSCE is
caught and acked). The harness gained qmp_sequence (multi-step QMP
injection with arguments) for when a drivable case exists. Full suite
88/88; the working USB path (enumeration, HID, storage) is unregressed
by the port-power and interrupter changes.
This commit is contained in:
Daniel Samson
2026-07-21 21:01:41 +01:00
parent 4091ea6912
commit 0ac07dadc9
3 changed files with 180 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
system/drivers/usb-xhci-bus/usb-xhci-bus.zig
+66 -27
View File
@@ -143,6 +143,7 @@ fn initialise(endpoint: runtime.ipc.Handle) bool {
_ = runtime.system.write("/system/drivers/usb-xhci-bus: no device manager to hello\n");
return false;
};
manager_handle = h; // the tick's hot-plug dispatch reports through this
const hello = protocol.Hello{ .role = @intFromEnum(protocol.Role.bus), .device_id = controller_id };
var reply: [protocol.message_maximum]u8 = undefined;
const n = runtime.ipc.call(h, std.mem.asBytes(&hello), &reply) catch {
@@ -186,6 +187,8 @@ fn speedName(speed: u32) []const u8 {
/// report one child per interface — carrying the interface's (class, subclass,
/// protocol) triple as identity, which is what the device manager matches a
/// class driver against.
var manager_handle: ?runtime.ipc.Handle = null;
fn scanPorts(manager: runtime.ipc.Handle) void {
const engine = if (controller) |*c| c else {
_ = runtime.system.write("/system/drivers/usb-xhci-bus: controller not initialised\n");
@@ -196,38 +199,66 @@ fn scanPorts(manager: runtime.ipc.Handle) void {
var port: u32 = 1;
var connected: u32 = 0;
while (port <= engine.max_ports) : (port += 1) {
const port_status = engine.portStatus(port);
if (port_status & 1 == 0) continue; // CCS: nothing connected
if (!engine.portConnected(port)) continue;
connected += 1;
const speed = (port_status >> 10) & 0xF; // the PORTSC port-speed class
std.log.info("port {d} connected — {s} (speed class {d})", .{ port, speedName(speed), speed });
const usb_device = engine.setupDevice(port, speed) orelse {
std.log.info("port {d} device setup failed", .{port});
continue;
};
if (!engine.enumerate(usb_device)) {
std.log.info("port {d} enumeration failed", .{port});
continue;
}
std.log.info("port {d} device vendor 0x{x:0>4} product 0x{x:0>4}, {d} interface(s)", .{
port,
usb_device.device_descriptor.vendor_id,
usb_device.device_descriptor.product_id,
usb_device.interface_count,
});
for (usb_device.interfaces[0..usb_device.interface_count]) |*interface| {
// Record the id each interface was registered as, so a class driver
// opening the interface (by that id) resolves to it.
if (reportInterface(manager, port, interface.*)) |registered| {
interface.registered_device_id = registered;
}
}
bringUpPort(manager, engine, port);
}
if (connected == 0) _ = runtime.system.write("/system/drivers/usb-xhci-bus: no devices connected\n");
}
/// Bring up whatever is on `port`: setup + enumerate + register/report one child
/// per interface. Shared by the boot scan and hot-plug (a port-change event with
/// the port now connected).
fn bringUpPort(manager: runtime.ipc.Handle, engine: *library.Controller, port: u32) void {
const speed = (engine.portStatus(port) >> 10) & 0xF; // the PORTSC port-speed class
std.log.info("port {d} connected — {s} (speed class {d})", .{ port, speedName(speed), speed });
const usb_device = engine.setupDevice(port, speed) orelse {
std.log.info("port {d} device setup failed", .{port});
return;
};
if (!engine.enumerate(usb_device)) {
std.log.info("port {d} enumeration failed", .{port});
return;
}
std.log.info("port {d} device vendor 0x{x:0>4} product 0x{x:0>4}, {d} interface(s)", .{
port,
usb_device.device_descriptor.vendor_id,
usb_device.device_descriptor.product_id,
usb_device.interface_count,
});
for (usb_device.interfaces[0..usb_device.interface_count]) |*interface| {
// Record the id each interface was registered as, so a class driver
// opening the interface (by that id) resolves to it.
if (reportInterface(manager, port, interface.*)) |registered| {
interface.registered_device_id = registered;
}
}
}
/// Tear down whatever was on `port` after an unplug: report each registered
/// interface as removed (the manager prunes the node, notifies watchers, and
/// stops the class driver's world honestly), then release the controller-side
/// device state (Disable Slot).
fn tearDownPort(manager: runtime.ipc.Handle, engine: *library.Controller, port: u32) void {
const usb_device = engine.deviceOnPort(port) orelse return;
std.log.info("port {d} disconnected", .{port});
for (usb_device.interfaces[0..usb_device.interface_count]) |*interface| {
if (interface.registered_device_id == 0) continue;
const event = protocol.ChildRemoved{
.parent = controller_id,
.bus_address = (@as(u64, port) << 8) | interface.number,
};
var reply: [protocol.message_maximum]u8 = undefined;
_ = runtime.ipc.call(manager, std.mem.asBytes(&event), &reply) catch {
std.log.info("child-removed report for port {d} interface {d} failed", .{ port, interface.number });
};
interface.registered_device_id = 0;
}
engine.tearDownDevice(usb_device);
}
/// Register one interface as a resource-less child of the controller and report
/// it to the device manager. The identity is the packed USB class triple, so the
/// manager can match a class driver (HID keyboard, mouse, mass storage); the
@@ -380,6 +411,14 @@ fn onNotification(badge: u64) void {
if (badge & runtime.ipc.notify_timer_bit == 0) return;
if (controller) |*engine| {
engine.pump();
while (engine.takePortChange()) |port| {
const manager = manager_handle orelse break;
if (engine.portConnected(port)) {
if (engine.deviceOnPort(port) == null) bringUpPort(manager, engine, port);
} else {
tearDownPort(manager, engine, port);
}
}
while (engine.takeReport()) |report| {
var message = transfer.InterruptReport{
.device_token = report.device_token,
system/drivers/usb-xhci-bus/usb-xhci-library.zig
+88 -6
View File
@@ -85,6 +85,7 @@ pub const TrbType = enum(u6) {
status_stage = 4,
link = 6,
enable_slot = 9,
disable_slot = 10,
address_device = 11,
configure_endpoint = 12,
evaluate_context = 13,
@@ -330,6 +331,8 @@ pub const Controller = struct {
subscriptions: [max_subscriptions]Subscription = [_]Subscription{.{}} ** max_subscriptions,
report_queue: [report_queue_capacity]Report = [_]Report{.{}} ** report_queue_capacity,
report_count: usize = 0,
port_changes: [16]u32 = undefined,
port_change_count: usize = 0,
// Transferred length of the most recent awaited transfer (requested minus the
// event residual); read right after a control or bulk transfer returns true.
last_transfer_length: u32 = 0,
@@ -429,11 +432,30 @@ pub const Controller = struct {
write64(self.interrupter(event_ring_dequeue_pointer), self.event_ring.segment.physical);
write64(self.interrupter(event_ring_segment_table_base), self.event_ring.table.physical);
write32(self.interrupter(interrupter_moderation), 0);
// Run. (Interrupts are left disabled — the event ring is polled.)
// Enable the interrupter (IMAN.IE) and USBCMD.INTE. We still POLL the
// event ring — no interrupt is wired — but some controllers (QEMU's
// qemu-xhci among them) only WRITE runtime events to the ring when the
// interrupter is enabled, so a hot-plug port-change event is silently
// dropped otherwise. Enabling it is harmless to a polling driver.
write32(self.interrupter(interrupter_management), 1 << 1); // IE
mmio.wmb();
write32(self.operational(op_usbcmd), read32(self.operational(op_usbcmd)) | usbcmd_run);
// Run.
mmio.wmb();
write32(self.operational(op_usbcmd), read32(self.operational(op_usbcmd)) | usbcmd_run | usbcmd_interrupter_enable);
if (!waitClear(self.operational(op_usbsts), usbsts_halted)) return null;
// Power EVERY port — including empty ones — so a later hot-plug can
// signal a connect (an unpowered port reports nothing: PP=0 is why a
// device added after boot never raised a port-change event). Boot-time
// devices are on already-powered ports; this just extends power to the
// rest. Write PP without disturbing the write-1-to-clear bits.
var port: u32 = 1;
while (port <= self.max_ports) : (port += 1) {
const status = self.portStatus(port);
if (status & portsc_power == 0)
self.writePortStatus(port, (status & ~portsc_write_1_to_clear) | portsc_power);
}
return self;
}
@@ -1079,12 +1101,72 @@ pub const Controller = struct {
return report;
}
/// Drain any events currently on the event ring, dispatching interrupt reports
/// into the queue. Non-blocking — called on the driver's timer tick.
/// Drain any events currently on the event ring: interrupt reports into the
/// report queue, PORT STATUS CHANGES into the port-change queue (hot-plug —
/// these were silently dropped before M20). Non-blocking — called on the
/// driver's timer tick.
pub fn pump(self: *Controller) void {
while (true) {
const event = self.nextEvent(system.clock()) orelse return; // deadline=now: null when empty
if (trbType(event.control) == @intFromEnum(TrbType.transfer_event)) _ = self.serviceInterruptEvent(event);
const kind = trbType(event.control);
if (kind == @intFromEnum(TrbType.transfer_event)) {
_ = self.serviceInterruptEvent(event);
} else if (kind == @intFromEnum(TrbType.port_status_change_event)) {
// Port ID rides bits 31:24 of the TRB's first dword.
const port: u32 = @intCast((event.parameter >> 24) & 0xFF);
if (port == 0 or port > self.max_ports) continue;
// Acknowledge the change bits so the port can signal again.
const status = self.portStatus(port);
self.writePortStatus(port, (status & ~portsc_write_1_to_clear) | (status & portsc_change_mask));
if (self.port_change_count < self.port_changes.len) {
self.port_changes[self.port_change_count] = port;
self.port_change_count += 1;
}
}
}
}
/// Dequeue the oldest pending port change (a port whose connect state may
/// have flipped), or null. The bus layer reads PORTSC to decide plug/unplug.
pub fn takePortChange(self: *Controller) ?u32 {
if (self.port_change_count == 0) return null;
const port = self.port_changes[0];
var i: usize = 1;
while (i < self.port_change_count) : (i += 1) self.port_changes[i - 1] = self.port_changes[i];
self.port_change_count -= 1;
return port;
}
/// Whether a port currently has a device connected (PORTSC.CCS).
pub fn portConnected(self: *const Controller, port: u32) bool {
return self.portStatus(port) & portsc_connected != 0;
}
/// The tracked device on `port`, or null.
pub fn deviceOnPort(self: *Controller, port: u32) ?*Device {
for (&self.devices) |*device| {
if (device.used and device.port == port) return device;
}
return null;
}
/// Tear a device down after unplug: cancel its interrupt subscriptions,
/// Disable Slot (frees the controller's slot state), clear its context-array
/// entry, and release the tracking slot. DMA regions leak (as elsewhere) —
/// bounded by the device-slot count.
pub fn tearDownDevice(self: *Controller, device: *Device) void {
for (&self.subscriptions) |*subscription| {
if (subscription.active and subscription.slot_id == device.slot_id) subscription.active = false;
}
const physical = self.submitCommand(.{
.control = trbControl(.disable_slot, @as(u32, device.slot_id) << 24),
});
if (self.awaitCommand(physical)) |code| {
if (code != @intFromEnum(CompletionCode.success))
std.log.info("slot {d}: Disable Slot completion code {d}", .{ device.slot_id, code });
} else std.log.info("slot {d}: Disable Slot timed out", .{device.slot_id});
const array: [*]volatile u64 = @ptrFromInt(self.device_context_array.virtual);
array[device.slot_id] = 0;
device.used = false;
}
};