//! /system/drivers/usb-xhci-bus — the xHCI (USB 3) host-controller bus driver.
//! The device manager spawns **one instance per controller** it discovers (a
//! machine can carry several), passing the controller's device-tree id as
//! argv[1]; this instance claims that device and no other, so multiple
//! instances never fight over hardware.
//!
//! M18.1 (this increment): a harness service and the first conforming driver of
//! the device-manager protocol — claim the controller, `hello` the manager
//! (role, version, assignment) inside its deadline, then serve. Controller
//! bring-up (map the MMIO window, reset, port scan) and tree reports
//! (`child_added` for each connected port) land in M18.2.

const std = @import("std");
const runtime = @import("runtime");
const protocol = runtime.device_manager_protocol;
const device = runtime.device;

/// Format one whole log line and emit it in a single `debug_write`, so
/// concurrent instances (one per controller) can never interleave mid-line.
fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
    var line: [128]u8 = undefined;
    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
}

var controller_id: u64 = protocol.no_device;

/// Claim the assigned controller, find its register window, and hello the
/// manager. Any failure returns false: the process exits cleanly, which the
/// manager reads as "meant to stop" — a missing assignment is not a crash loop.
fn initialise(endpoint: runtime.ipc.Handle) bool {
    _ = endpoint;
    if (!device.claim(controller_id)) {
        writeLine("usb-xhci-bus: unable to claim controller device {d}\n", .{controller_id});
        return false;
    }

    // Fetch our own descriptor back for the controller's resources.
    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
        _ = runtime.system.write("usb-xhci-bus: out of memory\n");
        return false;
    };
    const total = device.enumerate(buffer);
    const descriptor = for (buffer[0..@min(total, buffer.len)]) |d| {
        if (d.id == controller_id) break d;
    } else {
        writeLine("usb-xhci-bus: device {d} not in the device tree\n", .{controller_id});
        return false;
    };

    // The controller's operational registers live behind BAR0, enumerated as
    // the device's first memory resource.
    const register_window = for (descriptor.resources[0..@intCast(descriptor.resource_count)]) |resource| {
        if (resource.kind == @intFromEnum(device.ResourceKind.memory)) break resource;
    } else {
        writeLine("usb-xhci-bus: controller device {d} has no MMIO window\n", .{controller_id});
        return false;
    };
    writeLine("usb-xhci-bus: claimed controller device {d} (registers at 0x{x}, {d} bytes)\n", .{
        controller_id,
        register_window.start,
        register_window.len,
    });

    // The handshake: role, protocol version, assignment — inside the manager's
    // deadline (the lookup retries cover the manager still registering).
    var manager: ?runtime.ipc.Handle = null;
    var tries: u32 = 0;
    while (manager == null and tries < 100) : (tries += 1) {
        manager = runtime.ipc.lookup(.device_manager);
        if (manager == null) runtime.system.sleep(20);
    }
    const h = manager orelse {
        _ = runtime.system.write("usb-xhci-bus: no device manager to hello\n");
        return false;
    };
    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 {
        _ = runtime.system.write("usb-xhci-bus: hello call failed\n");
        return false;
    };
    if (n < protocol.reply_size or std.mem.bytesToValue(protocol.HelloReply, reply[0..protocol.reply_size]).status != 0) {
        _ = runtime.system.write("usb-xhci-bus: hello refused\n");
        return false;
    }
    _ = runtime.system.write("usb-xhci-bus: hello acknowledged\n");
    return true;
}

/// No bus protocol to serve yet — transfer requests arrive with the USB track.
fn onMessage(message: []const u8, reply: []u8, sender: u32) usize {
    _ = message;
    _ = reply;
    _ = sender;
    return 0;
}

pub fn main(init: runtime.process.Init) void {
    const argument = init.arguments.get(1) orelse {
        _ = runtime.system.write("usb-xhci-bus: missing controller device id (argv[1])\n");
        return;
    };
    controller_id = std.fmt.parseInt(u64, argument, 10) catch {
        writeLine("usb-xhci-bus: malformed controller device id '{s}'\n", .{argument});
        return;
    };
    runtime.service.run(protocol.message_maximum, .{
        .init = initialise,
        .on_message = onMessage,
    });
}

pub const panic = runtime.panic;
comptime {
    _ = &runtime.start._start; // pull the runtime entry shim into the image
}