atmos/kernel/

usb.rs

// usb.rs - Minimal DWC2 (Synopsys OTG) USB Host Controller & USB HID Stack
#![allow(dead_code)]
#![allow(static_mut_refs)]

use crate::kernel::net;
use crate::kernel::reclock::RecoverableMutex;

// パニック回復対応ロック（NET_LOCK と同じ理由）。
static USB_LOCK: RecoverableMutex<()> = RecoverableMutex::new(());

/// パニック回復: コア `cid` が USB_LOCK を保持していれば強制解放する。
pub fn force_release_locks(cid: i16) {
    unsafe {
        USB_LOCK.force_release_if_core(cid);
    }
}

// BCM2837 DWC2 USB Base MMIO Address
const USB_BASE: usize = 0x3F98_0000;

// Global Registers
const GOTGCTL: *mut u32 = USB_BASE as *mut u32;
const GOTGINT: *mut u32 = (USB_BASE + 0x004) as *mut u32;
const GAHBCFG: *mut u32 = (USB_BASE + 0x008) as *mut u32;
const GUSBCFG: *mut u32 = (USB_BASE + 0x00C) as *mut u32;
const GRSTCTL: *mut u32 = (USB_BASE + 0x010) as *mut u32;
const GINTSTS: *mut u32 = (USB_BASE + 0x014) as *mut u32;
const GINTMSK: *mut u32 = (USB_BASE + 0x018) as *mut u32;
// 診断用: コア ID / ハードウェア構成（PHY 種別など）
const GSNPSID: *mut u32 = (USB_BASE + 0x040) as *mut u32;
const GHWCFG2: *mut u32 = (USB_BASE + 0x048) as *mut u32;
const GRXSTSR: *mut u32 = (USB_BASE + 0x01C) as *mut u32;
const GRXFSIZ: *mut u32 = (USB_BASE + 0x024) as *mut u32;
const GNPTXFSIZ: *mut u32 = (USB_BASE + 0x028) as *mut u32;
const GNPTXSTS: *mut u32 = (USB_BASE + 0x02C) as *mut u32;
const HPTXFSIZ: *mut u32 = (USB_BASE + 0x100) as *mut u32;

// Host Global Registers
const HCFG: *mut u32 = (USB_BASE + 0x400) as *mut u32;
const HFIR: *mut u32 = (USB_BASE + 0x404) as *mut u32;
const HFNUM: *mut u32 = (USB_BASE + 0x408) as *mut u32;
const HAINT: *mut u32 = (USB_BASE + 0x414) as *mut u32;
const HAINTMSK: *mut u32 = (USB_BASE + 0x418) as *mut u32;
const HPRT0: *mut u32 = (USB_BASE + 0x440) as *mut u32;
// Power and Clock Gating Control。0 を書いて PHY クロックのゲートを解除する（BCM2837 必須）。
const PCGCCTL: *mut u32 = (USB_BASE + 0xE00) as *mut u32;

// Host Channel Registers
const HC_BASE: usize = USB_BASE + 0x500;
fn hc_char(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20) as *mut u32
}
// HCSPLT (Split Control, offset +0x04)。非スプリット転送では 0 にクリアする。
// これを書かないと、ファームウェア残留の SplitEna によりチャネルがスプリット転送を試み、
// ルート機器（ハブ配下でない）相手では永遠に完了せず HCINT=0 でスタックする。
fn hc_splt(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20 + 0x04) as *mut u32
}
fn hc_int(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20 + 0x08) as *mut u32
}
fn hc_intmsk(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20 + 0x0C) as *mut u32
}
fn hc_tsiz(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20 + 0x10) as *mut u32
}
fn hc_dma(n: usize) -> *mut u32 {
    (HC_BASE + n * 0x20 + 0x14) as *mut u32
}

// USB Request Setup Packet structure
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct UsbSetupPacket {
    pub request_type: u8,
    pub request: u8,
    pub value: u16,
    pub index: u16,
    pub length: u16,
}

// RNDIS packet message header structure (44 bytes)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct RndisPacketMsg {
    pub message_type: u32,              // 0x00000001 (RNDIS_PACKET_MSG)
    pub message_length: u32,            // Total message length in bytes (44 + payload)
    pub data_offset: u32, // Offset from the start of data_offset field (8 bytes from structure start) to payload (36)
    pub data_length: u32, // Size of payload in bytes
    pub oob_data_offset: u32, // 0
    pub oob_data_length: u32, // 0
    pub num_oob_data_elements: u32, // 0
    pub packet_information_offset: u32, // 0
    pub packet_information_length: u32, // 0
    pub device_vc_handle: u32, // 0
    pub reserved: u32,    // 0
}

// DMA用バッファ（メモリのアライメントに注意）
#[repr(C, align(64))]
struct DmaBuffer {
    data: [u8; 2048],
}

static mut DMA_BUF: DmaBuffer = DmaBuffer { data: [0; 2048] };
static mut SETUP_BUF: DmaBuffer = DmaBuffer { data: [0; 2048] };
/// Ethernet bulk IN 専用 DMA バッファ。
/// RX は「張りっぱなし」(async) 運用のため、TX/HID と共用すると保留中の DMA 書き込みと衝突する。
static mut RX_DMA_BUF: DmaBuffer = DmaBuffer { data: [0; 2048] };
static mut ETH_RX_BUF: [u8; 2048] = [0; 2048];
static mut ETH_RX_LEN: usize = 0;

const MAX_HID_DEVICES: usize = 4;
const HUB_DESCRIPTOR_TYPE: u16 = 0x2900;
const HUB_FEATURE_PORT_RESET: u16 = 4;
const HUB_FEATURE_PORT_POWER: u16 = 8;
const HUB_FEATURE_C_PORT_CONNECTION: u16 = 16;
const HUB_FEATURE_C_PORT_RESET: u16 = 20;

#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum UsbDeviceKind {
    None,
    Hub,
    Keyboard,
    Mouse,
    Tablet,
    CdcEthernet,
}

#[derive(Copy, Clone)]
struct UsbHidDevice {
    address: u8,
    ep0_mps: u16,
    hid_ep: u8,
    hid_ep_size: u16,
    interface_number: u8,
    kind: UsbDeviceKind,
    key_prev_state: [u8; 6],
    shift_pressed: bool,
    ctrl_pressed: bool,
    alt_pressed: bool,
    gui_pressed: bool,
    /// Interrupt IN 転送の DATA toggle (0=DATA0, 2=DATA1)
    data_toggle: u32,
}

impl UsbHidDevice {
    const fn empty() -> Self {
        Self {
            address: 0,
            ep0_mps: 8,
            hid_ep: 0,
            hid_ep_size: 8,
            interface_number: 0,
            kind: UsbDeviceKind::None,
            key_prev_state: [0; 6],
            shift_pressed: false,
            ctrl_pressed: false,
            alt_pressed: false,
            gui_pressed: false,
            data_toggle: 0,
        }
    }
}

pub struct EnumeratedDevice {
    pub kind: UsbDeviceKind,
    pub address: u8,
    pub interface_number: u8,
    pub ep0_mps: u16,
    pub hid_ep: u8,
    pub hid_ep_size: u16,
    pub port_count: u8,
    pub bulk_in_ep: u8,
    pub bulk_out_ep: u8,
    pub bulk_ep_size: u16,
    pub data_interface_number: u8,
    pub data_alt_setting: u8,
    /// 構成記述子の bConfigurationValue（SET_CONFIGURATION で使用）
    pub config_value: u8,
    pub is_rndis: bool,
    pub i_mac_address: u8,
    pub mac_address: Option<[u8; 6]>,
}

impl EnumeratedDevice {
    pub fn empty() -> Self {
        Self {
            kind: UsbDeviceKind::None,
            address: 0,
            interface_number: 0,
            ep0_mps: 8,
            hid_ep: 0,
            hid_ep_size: 0,
            port_count: 0,
            bulk_in_ep: 0,
            bulk_out_ep: 0,
            bulk_ep_size: 64,
            data_interface_number: 0,
            data_alt_setting: 0,
            config_value: 1,
            is_rndis: false,
            i_mac_address: 0,
            mac_address: None,
        }
    }
}

// デバイスの状態追跡
static mut DEV_SPEED: u32 = 0; // 1: High, 2: Full, 3: Low
static mut DEV_ADDR: u8 = 0;
static mut EP0_MPS: u16 = 8; // コントロールエンドポイント0の最大パケットサイズ
static mut HID_EP_SIZE: u16 = 8; // HIDインタラプトエンドポイントの最大パケットサイズ
#[repr(align(64))]
struct Align64<T>(T);

static mut HID_DEVICES: Align64<[UsbHidDevice; MAX_HID_DEVICES]> = Align64([UsbHidDevice::empty(); MAX_HID_DEVICES]);
static mut HID_DEVICE_COUNT: Align64<usize> = Align64(0);
static mut HUB_ADDR: u8 = 0;
static mut HUB_EP0_MPS: u16 = 8;
static mut ETH_BULK_OUT_TOGGLE: u32 = 0;
static mut ETH_BULK_IN_TOGGLE: u32 = 0;
static mut HUB_PORT_COUNT: u8 = 0;
static mut NEXT_DEVICE_ADDR: u8 = 1;

static mut CURRENT_HUB_PORT: u8 = 0;
static mut CURRENT_HUB_PORT_SPEED: u32 = 0; // 0: FS, 1: LS, 2: HS
static mut DEV_SPEEDS: [u8; 16] = [0; 16]; // 各デバイスアドレス (0..16) の速度を記録する (0: FS, 1: LS, 2: HS)
// 各デバイスの親ハブ情報。実機 RPi3B+ の LAN7515 はハブが2段構成のため、
// スプリット転送の宛先 (直近の HS ハブのアドレスとポート) をデバイスごとに記録する。
static mut DEV_HUB_ADDRS: [u8; 16] = [0; 16]; // 0 = ルート直結 (ハブ経由でない)
static mut DEV_HUB_PORTS: [u8; 16] = [0; 16];

// 簡易ディレイ
fn delay_ms(ms: u32) {
    // ARM ジェネリックタイマ (cntpct_el0) を使った実時間ウェイト。
    // 旧実装は NOP ループ (ms*50000) で CPU クロック依存だったため、実機 RPi3B+ (1.4GHz) では
    // ウェイトが極端に短くなり、USB リセット/安定待ちが不足して列挙失敗やコントローラ停止を招いていた。
    let start = crate::kernel::timer::get_system_time_us();
    let target = ms as u64 * 1000;
    while crate::kernel::timer::get_system_time_us().wrapping_sub(start) < target {
        unsafe {
            core::arch::asm!("nop");
        }
    }
}

/// 指定レジスタの mask ビットがすべてセットされるまで実時間で待つ。
/// timeout_ms 以内に成立すれば true、タイムアウトなら false（uspi の WaitForBit 相当）。
/// 反復回数ベースの待ちは CPU クロック依存で実機 1.4GHz では早期に尽きるため使わない。
unsafe fn wait_bit_set(reg: *mut u32, mask: u32, timeout_ms: u32) -> bool {
    let start = crate::kernel::timer::get_system_time_us();
    let limit = timeout_ms as u64 * 1000;
    loop {
        if core::ptr::read_volatile(reg) & mask == mask {
            return true;
        }
        if crate::kernel::timer::get_system_time_us().wrapping_sub(start) > limit {
            return false;
        }
    }
}

/// 指定レジスタの mask ビットがすべてクリアされるまで実時間で待つ。
unsafe fn wait_bit_clear(reg: *mut u32, mask: u32, timeout_ms: u32) -> bool {
    let start = crate::kernel::timer::get_system_time_us();
    let limit = timeout_ms as u64 * 1000;
    loop {
        if core::ptr::read_volatile(reg) & mask == 0 {
            return true;
        }
        if crate::kernel::timer::get_system_time_us().wrapping_sub(start) > limit {
            return false;
        }
    }
}

/// HPRT0 レジスタを安全に読み取る。
/// HPRT0 には W1C (Write-1-to-Clear) ビットが含まれており、read-modify-write で
/// これらのビットを不用意に書き戻すとポートが無効化される。
/// bit1=PrtConnDet, bit2=PrtEna, bit3=PrtEnChng, bit5=PrtOvrCurrChng
unsafe fn read_hprt0_safe() -> u32 {
    let val = core::ptr::read_volatile(HPRT0);
    val & !(0b0010_1110) // W1C ビット (1,2,3,5) をマスク
}

/// DWC2 USBホストコントローラの初期化とデバイス検出
pub fn init() {
    // 一切の変更やソフトリセットを行う前に、初期レジスタのダンプを出力する
    unsafe {
        let initial_gusbcfg = core::ptr::read_volatile(GUSBCFG);
        let initial_hprt0 = core::ptr::read_volatile(HPRT0);
        let initial_hcfg = core::ptr::read_volatile(HCFG);
        let initial_pcgcctl = core::ptr::read_volatile(PCGCCTL);
        crate::warn!("[USB][DIAG] Initial state: GUSBCFG=0x{:08X} HPRT0=0x{:08X} HCFG=0x{:08X} PCGCCTL=0x{:08X}",
            initial_gusbcfg, initial_hprt0, initial_hcfg, initial_pcgcctl);
    }

    // uspi 同様、初期化の最初に USB ホストコントローラの電源を投入する。
    match crate::kernel::mailbox::power_on_usb() {
        Ok(()) => {}
        Err(e) => crate::warn!("[USB] Mailbox USB power ON: FAILED ({})", e),
    }
    delay_ms(500);

    unsafe {
        reset_device_state();

        // ================= InitCore (GUSBCFG 設定後のソフトリセットシーケンス) =================
        // リセット前に確実に PHY クロックのゲートを解除しておく
        core::ptr::write_volatile(PCGCCTL, 0);
        delay_ms(10);

        let mut usbcfg = core::ptr::read_volatile(GUSBCFG);

        // 1. ULPI_EXT_VBUS_DRV / TERM_SEL_DL_PULSE をクリア
        usbcfg &= !(1 << 20); // ULPI_EXT_VBUS_DRV
        usbcfg &= !(1 << 22); // TERM_SEL_DL_PULSE

        // 2. UTMI+ (ULPI_UTMI_SELクリア) & PHYIF=8bit (PHYIFクリア)
        usbcfg &= !(1 << 4); // ULPI_UTMI_SEL -> UTMI+
        usbcfg &= !(1 << 3); // PHYIF -> 8bit

        // 3. HS PHY が UTMI+（BCM2837）なので ULPI_FSLS / ULPI_CLK_SUS_M をクリア
        usbcfg &= !(1 << 17); // ULPI_FSLS
        usbcfg &= !(1 << 19); // ULPI_CLK_SUS_M

        // 4. ホストモード強制
        usbcfg |= 1 << 29; // ForceHstMode
        usbcfg &= !(1 << 30); // clear ForceDevMode

        // 5. USBTrdTim / TOutCal はファーム既定(5 / 0)のまま触らない。
        //    Circle の実機 golden 値 USBCFG=0x20001400 が TrdTim=5・TOutCal=0 であり、
        //    それで HS チャープが成功している。TrdTim=9/TOutCal=7 は HS を阻害したため撤去。

        // 6. HNP / SRP 無効化
        usbcfg &= !(1 << 9); // HNP_CAPABLE
        usbcfg &= !(1 << 8); // SRP_CAPABLE

        core::ptr::write_volatile(GUSBCFG, usbcfg);
        delay_ms(10);

        // 7. HCFG: FSLSPClkSel = 30/60MHz (0) をリセット前に設定（リセットでステートマシンに同期させる）
        let mut hcfg = core::ptr::read_volatile(HCFG);
        hcfg &= !0x3; // FSLSPClkSel = 0
        core::ptr::write_volatile(HCFG, hcfg);
        delay_ms(10);

        // コアソフトリセット: GUSBCFG で設定した PHY 幅・ホストモードをステートマシンに反映させる
        let ahb_idle_before = wait_bit_set(GRSTCTL, 1 << 31, 100); // AHB Idle
        core::ptr::write_volatile(GRSTCTL, 1 << 0); // CSFTRST
        let csftrst_cleared = wait_bit_clear(GRSTCTL, 1 << 0, 100); // CSFTRST 自己クリア待ち
        let ahb_idle_after = wait_bit_set(GRSTCTL, 1 << 31, 100);
        crate::warn!(
            "[USB] srst: ahb_idle={}/{} csftrst_clr={} GRSTCTL=0x{:08X}",
            ahb_idle_before,
            ahb_idle_after,
            csftrst_cleared,
            core::ptr::read_volatile(GRSTCTL)
        );
        delay_ms(100);

        // リセット後、速やかに PHY クロックのゲートを解除する
        core::ptr::write_volatile(PCGCCTL, 0);
        delay_ms(10);

        // リセット直後のレジスタ値を診断ログで出力
        let post_reset_usbcfg = core::ptr::read_volatile(GUSBCFG);
        let post_reset_hcfg = core::ptr::read_volatile(HCFG);
        crate::warn!(
            "[USB][DIAG] Post-reset: GUSBCFG=0x{:08X} HCFG=0x{:08X}",
            post_reset_usbcfg,
            post_reset_hcfg
        );

        // ソフトリセットによって初期値に戻ってしまった GUSBCFG / HCFG を再度適用する。
        // PHY構成関連ビット（ULPI_UTMI_SEL, PHYIF, ULPI_FSLS, ULPI_CLK_SUS_M, ULPI_EXT_VBUS_DRV, TERM_SEL_DL_PULSE, HNP/SRP）には触れず、
        // リセットでクリアされる ForceHstMode, USBTrdTim, TOutCal のみを最小限に上書き設定する。
        let mut usbcfg = post_reset_usbcfg;
        usbcfg |= 1 << 29; // ForceHstMode
        usbcfg &= !(1 << 30); // clear ForceDevMode
                              // TrdTim / TOutCal はファーム既定のまま（Circle golden = TrdTim=5/TOutCal=0）。触らない。
        core::ptr::write_volatile(GUSBCFG, usbcfg);
        delay_ms(10);

        let mut hcfg = core::ptr::read_volatile(HCFG);
        // すでに FSLSPClkSel が 0 でなければ設定する
        if (hcfg & 0x3) != 0 {
            hcfg &= !0x3; // FSLSPClkSel = 0
            core::ptr::write_volatile(HCFG, hcfg);
            delay_ms(10);
        }

        // ホストモードへの遷移確認 (GINTSTS.CurMod が 1 になるのを待つ)
        let mut curmod_ok = false;
        for _ in 0..100 {
            let gintsts = core::ptr::read_volatile(GINTSTS);
            if (gintsts & 1) != 0 {
                // CurMod (Bit 0) が 1 (Host)
                curmod_ok = true;
                break;
            }
            delay_ms(5);
        }
        if !curmod_ok {
            crate::warn!(
                "[USB]   WARNING: Host Mode transition timed out (GINTSTS=0x{:08X})",
                core::ptr::read_volatile(GINTSTS)
            );
        }

        // GAHBCFG: DMAEnable | WAIT_AXI_WRITES、MAX_AXI_BURST(bits2:1) クリア
        let mut ahbcfg = core::ptr::read_volatile(GAHBCFG);
        ahbcfg |= 1 << 5; // DMAEnable
        ahbcfg |= 1 << 4; // WAIT_AXI_WRITES
        ahbcfg &= !(3 << 1); // MAX_AXI_BURST = 0
                             // GlobalInt(bit0): CPU への IRQ 線アサートを制御するビット。DMA モードでは必要
        ahbcfg |= 1 << 0; // GlobalInt enable
        core::ptr::write_volatile(GAHBCFG, ahbcfg);
        crate::warn!(
            "[USB] GAHBCFG=0x{:08X} GINTMSK=0x{:08X}",
            core::ptr::read_volatile(GAHBCFG),
            (1u32 << 3) | (1 << 24) | (1 << 25) | (1 << 29)
        );

        // 割り込みマスク: ホストチャネル割り込みをアンマスク（uspi EnableHostInterrupts 相当）。
        core::ptr::write_volatile(GINTSTS, 0xFFFF_FFFF); // pending クリア
                                                         // Circle golden GINTMSK=0x23000008: SOF(3) | PrtInt(24) | HChInt(25) | DisconnInt(29)
        core::ptr::write_volatile(GINTMSK, (1 << 3) | (1 << 24) | (1 << 25) | (1 << 29));

        // ================= InitHost (uspi 忠実移植) =================
        // PHY クロックのゲートを解除（PCGCCTL=0）
        crate::info!("[USB]   InitHost: restart PHY clock (PCGCCTL=0)...");
        core::ptr::write_volatile(PCGCCTL, 0);

        // HCFG: FSLSPClkSel = 30/60MHz (0)。FslsOnly は立てない（Circle golden HCFG=0x0）。
        let mut hcfg = core::ptr::read_volatile(HCFG);
        hcfg &= !0x3; // FSLSPClkSel = 30/60MHz (UTMI PHY 用)
        core::ptr::write_volatile(HCFG, hcfg);
        crate::warn!(
            "[USB] HCFG=0x{:08X} FIFO RX/NP/P=1024/1024/1024",
            core::ptr::read_volatile(HCFG)
        );

        // FIFO サイズ: Circle 実機 golden に一致させる。
        // RXSIZ=1024, NPTXSIZ=depth1024|start1024(=0x04000400), HPTXSIZ=depth1024|start2048(=0x04000800)。
        core::ptr::write_volatile(GRXFSIZ, 1024);
        core::ptr::write_volatile(GNPTXFSIZ, 1024 | (1024 << 16));
        core::ptr::write_volatile(HPTXFSIZ, (1024 + 1024) | (1024 << 16));

        // FIFO フラッシュ（全 TX → RX、実時間ベースで完了待ち）
        core::ptr::write_volatile(GRSTCTL, (0x10 << 6) | (1 << 5)); // TxFFlsh (all)
        let txflush = wait_bit_clear(GRSTCTL, 1 << 5, 100);
        core::ptr::write_volatile(GRSTCTL, 1 << 4); // RxFFlsh
        let rxflush = wait_bit_clear(GRSTCTL, 1 << 4, 100);
        if !txflush || !rxflush {
            crate::warn!("[USB] FIFO flush TIMEOUT: tx={} rx={}", txflush, rxflush);
        }

        // ポート電源 ON
        let hprt = read_hprt0_safe();
        if (hprt & (1 << 12)) == 0 {
            core::ptr::write_volatile(HPRT0, hprt | (1 << 12)); // PrtPwr
        }
        delay_ms(500);

        // ================= EnableRootPort =================
        crate::warn!("[USB] Waiting for device connection...");
        let mut t = 20;
        loop {
            let v = core::ptr::read_volatile(HPRT0);
            if (v & 1) != 0 {
                crate::warn!("[USB] Device detected! HPRT0=0x{:08X}", v);
                break;
            }
            delay_ms(100);
            t -= 1;
            if t == 0 {
                crate::warn!("[USB] WARNING: No USB device detected.");
                return;
            }
        }
        delay_ms(1000); // USB 2.0 spec

        const RESET_RETRIES: u32 = 8;
        let mut enabled = false;
        let mut hprt_final = 0u32;
        let mut last_reset_try = 0u32;
        for reset_try in 0..RESET_RETRIES {
            let v = read_hprt0_safe();
            core::ptr::write_volatile(HPRT0, v | (1 << 12) | (1 << 8)); // PrtPwr | PrtRst
            delay_ms(100);
            let v = read_hprt0_safe();
            core::ptr::write_volatile(HPRT0, (v | (1 << 12)) & !(1 << 8)); // PrtPwr | clear PrtRst
            delay_ms(200);

            hprt_final = core::ptr::read_volatile(HPRT0);
            enabled = (hprt_final & (1 << 2)) != 0; // PrtEna
            last_reset_try = reset_try;

            if !enabled {
                delay_ms(50);
                continue;
            }

            DEV_SPEED = (hprt_final >> 17) & 0x3; // PrtSpd
            if DEV_SPEED == 0 {
                break;
            } // High Speed 達成
            delay_ms(50);
        }
        crate::warn!(
            "[USB] reset×{}: HPRT0=0x{:08X} PrtSpd={} ({})",
            last_reset_try + 1,
            hprt_final,
            DEV_SPEED,
            match DEV_SPEED {
                0 => "HS",
                1 => "FS",
                2 => "LS",
                _ => "?",
            }
        );

        if enabled {
            DEV_SPEED = (hprt_final >> 17) & 0x3; // PrtSpd (Port Speed)
                                                  // 実機デバッグ: DWC2 の構成とホストクロック状態をダンプする。
            {
                let snpsid = core::ptr::read_volatile(GSNPSID);
                let hwcfg2 = core::ptr::read_volatile(GHWCFG2);
                let hfir = core::ptr::read_volatile(HFIR);
                let hfnum1 = core::ptr::read_volatile(HFNUM) & 0x3FFF;
                delay_ms(2);
                let hfnum2 = core::ptr::read_volatile(HFNUM) & 0x3FFF;
                crate::warn!(
                    "[USB][DIAG] SNPSID=0x{:08X} HWCFG2=0x{:08X} GUSBCFG=0x{:08X} HCFG=0x{:08X}",
                    snpsid,
                    hwcfg2,
                    core::ptr::read_volatile(GUSBCFG),
                    core::ptr::read_volatile(HCFG)
                );
                crate::warn!(
                    "[USB][DIAG] HFIR=0x{:08X} frame:{}->{} ({})",
                    hfir,
                    hfnum1,
                    hfnum2,
                    if hfnum2 != hfnum1 {
                        "SOF OK"
                    } else {
                        "SOF STUCK!"
                    }
                );
            }

            // コントローラ側のホスト速度設定を設定値に同期 (実機クロック消失防止のためコメントアウト)
            // let mut hcfg = core::ptr::read_volatile(HCFG);
            // hcfg &= !0x3; // FSLSPclkSel
            // BCM2837 DWC2 FSLSPclkSel: 0=30/60MHz(HS), 1=48MHz(FS), 2=6MHz(LS)
            // if DEV_SPEED == 2 {
            //     hcfg |= 2; // 6MHz for Low Speed
            // } else {
            //     hcfg |= 1; // 48MHz for Full/High Speed
            // }
            // core::ptr::write_volatile(HCFG, hcfg);

            // ポートのW1C変化ビット (PrtConnDet=1, PrtEnChng=3, PrtOvrCurrChng=5) をクリアして
            // 保留中のポート割り込み(GINTSTS bit24 PrtInt)を落とす。PrtEna(bit2)は read_hprt0_safe で
            // マスク済みなので触らない（書き戻すとポートが無効化されるため）。
            // 保留ポート割り込みがチャネルのスケジューリングを阻むことがあるため、列挙前に必ず落とす。
            {
                let v = read_hprt0_safe();
                core::ptr::write_volatile(HPRT0, v | (1 << 1) | (1 << 3) | (1 << 5));
                let after = core::ptr::read_volatile(GINTSTS);
                crate::warn!(
                    "[USB][DIAG] W1C cleared. HPRT0=0x{:08X} GINTSTS=0x{:08X}",
                    core::ptr::read_volatile(HPRT0),
                    after
                );
            }

            // 8. デバイスの列挙（Enumeration）の実行
            enumerate_root_device();
        } else {
            crate::warn!(
                "[USB]   ERROR: Port did not enable after reset (500ms timeout). HPRT0=0x{:08X}",
                hprt_final
            );
        }
    }
}

unsafe fn reset_device_state() {
    DEV_ADDR = 0;
    EP0_MPS = 8;
    HID_EP_SIZE = 8;
    HID_DEVICE_COUNT.0 = 0;
    HUB_ADDR = 0;
    HUB_EP0_MPS = 8;
    HUB_PORT_COUNT = 0;
    NEXT_DEVICE_ADDR = 1;
    CURRENT_HUB_PORT = 0;
    CURRENT_HUB_PORT_SPEED = 0;
    DEV_SPEEDS = [0; 16];
    DEV_HUB_ADDRS = [0; 16];
    DEV_HUB_PORTS = [0; 16];
    for idx in 0..MAX_HID_DEVICES {
        HID_DEVICES.0[idx] = UsbHidDevice::empty();
    }
}

/// スプリット転送の宛先 (Transaction Translator を持つ直近の HS ハブ) を解決する。
/// USB のトポロジ規則上、非 HS (FS/LS) で動作しているハブは TT を持たないため、
/// その配下のデバイスへのスプリット転送は、そのハブではなくさらに上流の直近の
/// HS ハブを宛先にしなければならない。中間ハブを辿って HS ハブに到達するまで遡る。
unsafe fn resolve_split_target(hub_addr_in: u8, port_in: u8) -> (u8, u8) {
    let mut hub_addr = hub_addr_in;
    let mut port = port_in;
    // hub_addr == 0 はルートハブ (常に HS) を意味するのでそのまま返す。
    // 暴走防止のため最大16段まで遡る。
    for _ in 0..16 {
        if hub_addr == 0 || DEV_SPEEDS[hub_addr as usize] == 2 {
            break;
        }
        let parent_addr = DEV_HUB_ADDRS[hub_addr as usize];
        let parent_port = DEV_HUB_PORTS[hub_addr as usize];
        if parent_addr == 0 && parent_port == 0 {
            // これ以上遡る情報がない (異常系)。現状の hub_addr/port をそのまま使う。
            break;
        }
        hub_addr = parent_addr;
        port = parent_port;
    }
    (hub_addr, port)
}

unsafe fn select_control_target(address: u8, ep0_mps: u16) {
    DEV_ADDR = address;
    EP0_MPS = ep0_mps;
}

unsafe fn register_hid_device(device: EnumeratedDevice) {
    if HID_DEVICE_COUNT.0 >= MAX_HID_DEVICES {
        crate::debug!(
            "  WARNING: HID device table is full. Skipping address {}.",
            device.address
        );
        return;
    }

    HID_DEVICES.0[HID_DEVICE_COUNT.0] = UsbHidDevice {
        address: device.address,
        ep0_mps: device.ep0_mps,
        hid_ep: device.hid_ep,
        hid_ep_size: device.hid_ep_size,
        interface_number: device.interface_number,
        kind: device.kind,
        key_prev_state: [0; 6],
        shift_pressed: false,
        ctrl_pressed: false,
        alt_pressed: false,
        gui_pressed: false,
        data_toggle: 0,
    };
    HID_DEVICE_COUNT.0 += 1;

    // キャッシュを物理メモリへ書き出し (Core 0 -> Core 1)
    let count_addr = &HID_DEVICE_COUNT.0 as *const usize as usize;
    crate::kernel::mmu::clean_dcache_range(count_addr, core::mem::size_of_val(&HID_DEVICE_COUNT.0));
    let devices_addr = HID_DEVICES.0.as_ptr() as usize;
    crate::kernel::mmu::clean_dcache_range(devices_addr, core::mem::size_of_val(&HID_DEVICES.0));
    core::arch::asm!("dsb sy", "isb", options(nostack));

    let kind = match device.kind {
        UsbDeviceKind::Keyboard => "keyboard",
        UsbDeviceKind::Mouse => "mouse",
        UsbDeviceKind::Tablet => "tablet",
        _ => "unknown",
    };
    crate::warn!(
        "[USB] Registered USB HID {} at address {} (EP {}, MPS {}).",
        kind,
        device.address,
        device.hid_ep,
        device.hid_ep_size
    );
}

unsafe fn parse_config_descriptor(total_len: u16, device_class: u8) -> EnumeratedDevice {
    let mut result = EnumeratedDevice::empty();
    // bConfigurationValue (構成記述子 offset 5) を保存。
    // QEMU usb-net は config 1=RNDIS / config 2=CDC-ECM のため、ハードコードの 1 を
    // SET_CONFIGURATION すると RNDIS 構成が活性化され、INITIALIZE 未実施の RNDIS
    // ゲートにより bulk IN が永久 NAK（=受信不能）になっていた。
    if total_len >= 9 {
        result.config_value = DMA_BUF.data[5];
    }
    let mut current_kind = if device_class == 0x09 {
        UsbDeviceKind::Hub
    } else {
        UsbDeviceKind::None
    };
    let mut current_interface = 0u8;
    let mut current_alt = 0u8;
    // current_alt_setting moved to inner loop
    let mut current_if_class = 0u8;
    let mut cdc_control_if = 0u8;
    let mut cdc_data_if = 0u8;
    let mut cdc_bulk_in = 0u8;
    let mut cdc_bulk_out = 0u8;
    let mut cdc_bulk_mps = 0u16;
    let mut cdc_data_alt_setting = 0u8;
    let mut cdc_detected = false;
    let mut cdc_is_rndis = false;
    let mut i = 0usize;

    if current_kind == UsbDeviceKind::Hub {
        result.kind = UsbDeviceKind::Hub;
    }

    while i < total_len as usize {
        let desc_len = DMA_BUF.data[i] as usize;
        if desc_len < 2 {
            break;
        }

        let desc_type = DMA_BUF.data[i + 1];
        if desc_type == 0x04 {
            current_interface = DMA_BUF.data[i + 2];
            let current_alt_setting = DMA_BUF.data[i + 3];
            current_alt = current_alt_setting;
            let if_class = DMA_BUF.data[i + 5];
            let if_subclass = DMA_BUF.data[i + 6];
            let if_protocol = DMA_BUF.data[i + 7];
            let is_cdc_control = (if_class == 0x02 && matches!(if_subclass, 0x00 | 0x02 | 0x06))
                || (if_class == 0xE0 && if_subclass == 0x01 && if_protocol == 0x03);
            current_if_class = if_class;

            if is_cdc_control {
                cdc_detected = true;
                cdc_control_if = current_interface;
                // RNDIS 判定: class 0xE0 (Wireless/RNDIS) に加え、
                // class 02/subclass 02/protocol 0xFF (ACM 形式の RNDIS。QEMU usb-net が使用) も RNDIS。
                // これを CDC-ECM と誤認すると RNDIS INITIALIZE が送られず、
                // デバイスの rndis_state が DATA_INITIALIZED にならないため受信が永久 NAK になる。
                cdc_is_rndis = if_class == 0xE0
                    || (if_class == 0x02 && if_subclass == 0x02 && if_protocol == 0xFF);
            }
            if if_class == 0x0A {
                cdc_data_if = current_interface;
                cdc_data_alt_setting = current_alt_setting;
            }

            current_kind = match if_class {
                0x09 => UsbDeviceKind::Hub,
                0x03 if if_protocol == 1 => UsbDeviceKind::Keyboard,
                0x03 if if_protocol == 2 => UsbDeviceKind::Mouse,
                0x03 if if_protocol == 0 => UsbDeviceKind::Tablet, // USB Tablet often uses protocol 0 (None)
                0x02 if matches!(if_subclass, 0x00 | 0x02 | 0x06) => UsbDeviceKind::CdcEthernet,
                0xE0 if if_subclass == 0x01 && if_protocol == 0x03 => UsbDeviceKind::CdcEthernet,
                _ => UsbDeviceKind::None,
            };

            if result.kind == UsbDeviceKind::None && current_kind != UsbDeviceKind::None {
                result.kind = current_kind;
                result.interface_number = current_interface;
                if current_kind == UsbDeviceKind::Hub {
                    break;
                }
            }
        } else if desc_type == 0x05
            && (current_kind == UsbDeviceKind::Keyboard
                || current_kind == UsbDeviceKind::Mouse
                || current_kind == UsbDeviceKind::Tablet)
        {
            let ep_addr = DMA_BUF.data[i + 2];
            let ep_attr = DMA_BUF.data[i + 3];
            let raw_ep_size = ((DMA_BUF.data[i + 5] as u16) << 8 | (DMA_BUF.data[i + 4] as u16)) & 0x07FF;
            let ep_size = raw_ep_size.min(64); // HIDデバイスのパケットサイズは最大64バイト
            if (ep_addr & 0x80) != 0 && (ep_attr & 0x3) == 0x3 {
                result.kind = current_kind;
                result.interface_number = current_interface;
                result.hid_ep = ep_addr & 0x0F;
                result.hid_ep_size = ep_size;
                break;
            }
        } else if desc_type == 0x05 && cdc_detected && current_if_class == 0x0A {
            let ep_addr = DMA_BUF.data[i + 2];
            let ep_attr = DMA_BUF.data[i + 3];
            let raw_ep_size = ((DMA_BUF.data[i + 5] as u16) << 8 | (DMA_BUF.data[i + 4] as u16)) & 0x07FF;
            let ep_size = raw_ep_size.min(1024);
            if (ep_attr & 0x3) == 0x2 {
                if (ep_addr & 0x80) != 0 {
                    cdc_bulk_in = ep_addr & 0x0F;
                    cdc_bulk_mps = ep_size;
                } else {
                    cdc_bulk_out = ep_addr & 0x0F;
                    cdc_bulk_mps = ep_size;
                }
                // バルクデータ EP が含まれる alt 設定を採用する。
                // CDC-ECM のデータ IF は alt 0=EP無し / alt 1=EP有り のため、
                // EP が見つかった alt を SET_INTERFACE 対象にしないと RX が有効化されない。
                cdc_data_alt_setting = current_alt;
            }
        } else if desc_type == 0x24 && DMA_BUF.data[i + 2] == 0x0F {
            // CDC Ethernet Networking Functional Descriptor
            if desc_len >= 4 {
                result.i_mac_address = DMA_BUF.data[i + 3];
            }
        }

        i += desc_len;
    }

    if cdc_detected && cdc_bulk_in != 0 && cdc_bulk_out != 0 {
        result.kind = UsbDeviceKind::CdcEthernet;
        result.interface_number = cdc_control_if;
        result.data_interface_number = cdc_data_if;
        result.data_alt_setting = cdc_data_alt_setting;
        result.bulk_in_ep = cdc_bulk_in;
        result.bulk_out_ep = cdc_bulk_out;
        result.bulk_ep_size = cdc_bulk_mps;
        result.is_rndis = cdc_is_rndis;
    }

    result
}

unsafe fn hub_get_port_count() -> Option<u8> {
    select_control_target(HUB_ADDR, HUB_EP0_MPS);
    let req = UsbSetupPacket {
        request_type: 0xA0,
        request: 0x06,
        value: HUB_DESCRIPTOR_TYPE,
        index: 0,
        length: 9,
    };
    let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
    if usb_control_transfer(req, buf_phys, 9, true).is_err() {
        return None;
    }
    Some(DMA_BUF.data[2])
}

unsafe fn hub_set_port_feature(port: u8, feature: u16) -> bool {
    select_control_target(HUB_ADDR, HUB_EP0_MPS);
    let req = UsbSetupPacket {
        request_type: 0x23,
        request: 0x03,
        value: feature,
        index: port as u16,
        length: 0,
    };
    usb_control_transfer(req, 0, 0, false).is_ok()
}

unsafe fn hub_clear_port_feature(port: u8, feature: u16) -> bool {
    select_control_target(HUB_ADDR, HUB_EP0_MPS);
    let req = UsbSetupPacket {
        request_type: 0x23,
        request: 0x01,
        value: feature,
        index: port as u16,
        length: 0,
    };
    usb_control_transfer(req, 0, 0, false).is_ok()
}

unsafe fn hub_get_port_status(port: u8) -> Option<u32> {
    select_control_target(HUB_ADDR, HUB_EP0_MPS);
    let req = UsbSetupPacket {
        request_type: 0xA3,
        request: 0x00,
        value: 0,
        index: port as u16,
        length: 4,
    };
    let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
    if usb_control_transfer(req, buf_phys, 4, true).is_err() {
        return None;
    }

    let status = DMA_BUF.data[0] as u32
        | ((DMA_BUF.data[1] as u32) << 8)
        | ((DMA_BUF.data[2] as u32) << 16)
        | ((DMA_BUF.data[3] as u32) << 24);
    Some(status)
}

unsafe fn hub_reset_port(port: u8) -> bool {
    let _ = hub_clear_port_feature(port, HUB_FEATURE_C_PORT_CONNECTION);
    let _ = hub_clear_port_feature(port, HUB_FEATURE_C_PORT_RESET);

    if !hub_set_port_feature(port, HUB_FEATURE_PORT_RESET) {
        return false;
    }
    delay_ms(100);
    let _ = hub_clear_port_feature(port, HUB_FEATURE_C_PORT_RESET);
    delay_ms(50);

    for _ in 0..10 {
        if let Some(status) = hub_get_port_status(port) {
            if (status & 0x0003) == 0x0003 {
                return true;
            }
        }
        delay_ms(20);
    }

    false
}

unsafe fn enumerate_default_address_device(
    new_address: u8,
    label: &str,
) -> Option<EnumeratedDevice> {
    crate::info!("[USB] {}: starting enumeration on default address.", label);

    select_control_target(0, 64);
    HID_EP_SIZE = 8;

    let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
    let req = UsbSetupPacket {
        request_type: 0x80,
        request: 0x06,
        value: 0x0100,
        index: 0,
        length: 8,
    };
    if usb_control_transfer(req, buf_phys, 8, true).is_err() {
        crate::warn!(
            "[USB] {}: failed to read first device descriptor bytes.",
            label
        );
        return None;
    }

    let ep0_mps = DMA_BUF.data[7] as u16;
    crate::warn!(
        "[USB] {}: max packet size = {} (parent hub_addr={} port={} speed={})",
        label,
        ep0_mps,
        unsafe { HUB_ADDR },
        unsafe { CURRENT_HUB_PORT },
        unsafe { CURRENT_HUB_PORT_SPEED }
    );
    select_control_target(0, ep0_mps);

    let set_addr_req = UsbSetupPacket {
        request_type: 0x00,
        request: 0x05,
        value: new_address as u16,
        index: 0,
        length: 0,
    };
    if usb_control_transfer(set_addr_req, 0, 0, false).is_err() {
        crate::info!("[USB] {}: failed to set address {}.", label, new_address);
        return None;
    }

    delay_ms(20);
    unsafe {
        DEV_SPEEDS[new_address as usize] = CURRENT_HUB_PORT_SPEED as u8;
        // この時点の HUB_ADDR / CURRENT_HUB_PORT は列挙中の直接の親ハブを指す
        // (ルート直結の場合はともに 0)。直接の親を記録しておく (TT解決の連鎖に使う)。
        DEV_HUB_ADDRS[new_address as usize] = HUB_ADDR;
        DEV_HUB_PORTS[new_address as usize] = CURRENT_HUB_PORT;
    }
    select_control_target(new_address, ep0_mps);

    let req_full = UsbSetupPacket {
        request_type: 0x80,
        request: 0x06,
        value: 0x0100,
        index: 0,
        length: 18,
    };
    if usb_control_transfer(req_full, buf_phys, 18, true).is_err() {
        crate::info!("[USB] {}: failed to read full device descriptor.", label);
        return None;
    }

    let vid = (DMA_BUF.data[9] as u16) << 8 | (DMA_BUF.data[8] as u16);
    let pid = (DMA_BUF.data[11] as u16) << 8 | (DMA_BUF.data[10] as u16);
    let class = DMA_BUF.data[4];
    let subclass = DMA_BUF.data[5];
    let protocol = DMA_BUF.data[6];
    crate::info!(
        "[USB] {}: VID=0x{:04X} PID=0x{:04X} CLASS=0x{:02X} SUB=0x{:02X} PROTO=0x{:02X}",
        label,
        vid,
        pid,
        class,
        subclass,
        protocol
    );

    let config_req = UsbSetupPacket {
        request_type: 0x80,
        request: 0x06,
        value: 0x0200,
        index: 0,
        length: 9,
    };
    if usb_control_transfer(config_req, buf_phys, 9, true).is_err() {
        crate::info!(
            "[USB] {}: failed to read configuration descriptor header.",
            label
        );
        return None;
    }

    let total_len = (DMA_BUF.data[3] as u16) << 8 | (DMA_BUF.data[2] as u16);
    let req_config_all = UsbSetupPacket {
        request_type: 0x80,
        request: 0x06,
        value: 0x0200,
        index: 0,
        length: total_len,
    };
    if usb_control_transfer(req_config_all, buf_phys, total_len as u32, true).is_err() {
        crate::info!(
            "[USB] {}: failed to read full configuration descriptor.",
            label
        );
        return None;
    }

    let mut result = parse_config_descriptor(total_len, class);

    // String Descriptor (MAC)
    let mut mac_opt: Option<[u8; 6]> = None;
    if result.i_mac_address != 0 {
        let req_str = UsbSetupPacket {
            request_type: 0x80,
            request: 0x06,
            value: 0x0300 | (result.i_mac_address as u16),
            index: 0x0409, // English
            length: 255,
        };
        if usb_control_transfer(req_str, buf_phys, 255, true).is_ok() {
            let str_len = DMA_BUF.data[0] as usize;
            if str_len >= 26 && DMA_BUF.data[1] == 0x03 {
                let mut mac = [0u8; 6];
                let mut valid = true;
                for j in 0..6 {
                    let hi_char = DMA_BUF.data[2 + j * 4] as char;
                    let lo_char = DMA_BUF.data[2 + j * 4 + 2] as char;
                    let hi = hi_char.to_digit(16);
                    let lo = lo_char.to_digit(16);
                    if let (Some(h), Some(l)) = (hi, lo) {
                        mac[j] = ((h << 4) | l) as u8;
                    } else {
                        valid = false;
                        break;
                    }
                }
                if valid {
                    mac_opt = Some(mac);
                }
            }
        }
    }

    result.address = new_address;
    result.ep0_mps = ep0_mps;
    result.mac_address = mac_opt;

    let set_config_req = UsbSetupPacket {
        request_type: 0x00,
        request: 0x09,
        value: result.config_value.max(1) as u16, // 記述子の bConfigurationValue を使用
        index: 0,
        length: 0,
    };
    if usb_control_transfer(set_config_req, 0, 0, false).is_err() {
        crate::debug!("[USB] {}: failed to activate configuration.", label);
        return None;
    }
    delay_ms(20);

    match result.kind {
        UsbDeviceKind::Hub => {
            HUB_ADDR = new_address;
            HUB_EP0_MPS = ep0_mps;
            if let Some(port_count) = hub_get_port_count() {
                result.port_count = port_count;
                crate::debug!(
                    "[USB] {}: identified as USB hub with {} port(s).",
                    label,
                    port_count
                );
            } else {
                crate::debug!("[USB] {}: failed to read hub descriptor.", label);
                return None;
            }
        }
        UsbDeviceKind::Keyboard | UsbDeviceKind::Mouse | UsbDeviceKind::Tablet => {
            let set_protocol_req = UsbSetupPacket {
                request_type: 0x21,
                request: 0x0B,
                value: 0,
                index: result.interface_number as u16,
                length: 0,
            };
            let _ = usb_control_transfer(set_protocol_req, 0, 0, false);
            let kind_str = match result.kind {
                UsbDeviceKind::Keyboard => "keyboard",
                UsbDeviceKind::Mouse => "mouse",
                UsbDeviceKind::Tablet => "tablet",
                _ => "unknown",
            };
            crate::debug!(
                "[USB] {}: identified as USB HID {} on interface {} endpoint {}.",
                label,
                kind_str,
                result.interface_number,
                result.hid_ep
            );
        }
        UsbDeviceKind::CdcEthernet => {
            if result.data_alt_setting != 0 {
                let set_interface_req = UsbSetupPacket {
                    request_type: 0x01,
                    request: 0x0B, // SET_INTERFACE
                    value: result.data_alt_setting as u16,
                    index: result.data_interface_number as u16,
                    length: 0,
                };
                if usb_control_transfer(set_interface_req, 0, 0, false).is_err() {
                    crate::debug!("[USB] {}: failed to set CDC-ECM data alternate setting.", label);
                    return None;
                }
            }

            if !result.is_rndis {
                let set_packet_filter_req = UsbSetupPacket {
                    request_type: 0x21,
                    request: 0x43,
                    value: 0x000F, // Promiscuous, AllMulticast, Directed, Broadcast
                    index: result.interface_number as u16,
                    length: 0,
                };
                if usb_control_transfer(set_packet_filter_req, 0, 0, false).is_err() {
                    crate::debug!("[USB] {}: CDC-ECM packet filter set failed.", label);
                }
            } else {
                let init_req = UsbSetupPacket {
                    request_type: 0x21,
                    request: 0x00, // SEND_ENCAPSULATED_COMMAND
                    value: 0,
                    index: result.interface_number as u16,
                    length: 24,
                };
                let mut init_msg = [0u32; 6];
                init_msg[0] = 0x00000002; // REMOTE_NDIS_INITIALIZE_MSG
                init_msg[1] = 24;
                init_msg[2] = 1;
                init_msg[3] = 1;
                init_msg[4] = 1;
                init_msg[5] = 1580; // MaxTransferSize

                let init_ptr = &init_msg as *const u32 as *const u8;
                let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
                unsafe {
                    core::ptr::copy_nonoverlapping(init_ptr, DMA_BUF.data.as_mut_ptr(), 24);
                }

                let init_ok = usb_control_transfer(init_req, buf_phys, 24, false).is_ok();
                crate::info!("[USB] RNDIS DIAG: INITIALIZE_MSG sent ok={}", init_ok);

                // wait and get response
                delay_ms(10);
                let get_resp_req = UsbSetupPacket {
                    request_type: 0xA1,
                    request: 0x01, // GET_ENCAPSULATED_RESPONSE
                    value: 0,
                    index: result.interface_number as u16,
                    length: 1024,
                };
                let resp_ok = usb_control_transfer(get_resp_req, buf_phys, 1024, true).is_ok();
                crate::info!("[USB] RNDIS DIAG: GET_RESPONSE ok={} head={:02x} {:02x} {:02x} {:02x} | {:02x} {:02x} {:02x} {:02x}",
                    resp_ok,
                    DMA_BUF.data[0], DMA_BUF.data[1], DMA_BUF.data[2], DMA_BUF.data[3],
                    DMA_BUF.data[16], DMA_BUF.data[17], DMA_BUF.data[18], DMA_BUF.data[19]);

                let _set_req = UsbSetupPacket {
                    request_type: 0x21,
                    request: 0x00,
                    value: 0,
                    index: result.interface_number as u16,
                    length: 32,
                };
                let mut set_msg = [0u32; 8];
                set_msg[0] = 0x00000005; // REMOTE_NDIS_SET_MSG
                set_msg[1] = 32;
                set_msg[2] = 2;
                set_msg[3] = 0x0001010E; // OID_GEN_CURRENT_PACKET_FILTER
                set_msg[6] = 0; // DeviceVcHandle
                set_msg[7] = 0x0000000F; // Filter: Directed, Multicast, AllMulticast, Broadcast

                let set_req = UsbSetupPacket {
                    request_type: 0x21,
                    request: 0x00, // SEND_ENCAPSULATED_COMMAND
                    value: 0,
                    index: result.interface_number as u16,
                    length: 32,
                };
                unsafe {
                    core::ptr::copy_nonoverlapping(
                        set_msg.as_ptr() as *const u8,
                        DMA_BUF.data.as_mut_ptr(),
                        32,
                    );
                }
                let set_ok = usb_control_transfer(set_req, buf_phys, 32, false).is_ok();
                crate::info!("[USB] RNDIS DIAG: SET_PACKET_FILTER sent ok={}", set_ok);
                if set_ok {
                    delay_ms(10);
                    let read_req = UsbSetupPacket {
                        request_type: 0xA1,
                        request: 0x01,
                        value: 0,
                        index: result.interface_number as u16,
                        length: 64,
                    };
                    let r_ok = usb_control_transfer(read_req, buf_phys, 64, true).is_ok();
                    crate::info!(
                        "RNDIS DIAG: SET_RESPONSE ok={} status={:02x}{:02x}{:02x}{:02x}",
                        r_ok,
                        DMA_BUF.data[15],
                        DMA_BUF.data[14],
                        DMA_BUF.data[13],
                        DMA_BUF.data[12]
                    );
                }
            }

            crate::debug!(
                "{}: identified as USB Ethernet {} (ctrl if {}, data if {} alt {}, bulk in {}, bulk out {}, mps {}).",
                label,
                if result.is_rndis { "RNDIS" } else { "CDC-ECM" },
                result.interface_number,
                result.data_interface_number,
                result.data_alt_setting,
                result.bulk_in_ep,
                result.bulk_out_ep,
                result.bulk_ep_size
            );
            let default_mac = [0x02, 0x00, 0xA1, 0xCE, 0x00, 0x01];
            let mac = result.mac_address.unwrap_or(default_mac);
            net::register_usb_ethernet(
                result.address,
                result.bulk_in_ep,
                result.bulk_out_ep,
                result.bulk_ep_size,
                result.is_rndis,
                mac,
            );
        }
        UsbDeviceKind::None => {
            crate::debug!("[USB] {}: unsupported USB device.", label);
            return None;
        }
    }

    Some(result)
}

unsafe fn enumerate_hub_children(depth: u8) {
    // 実機 RPi3B+ の LAN7515 はハブ2段構成のため再帰列挙する。暴走防止に深さ制限。
    if depth >= 4 {
        crate::warn!("[USB] Hub nesting too deep ({}). Skipping.", depth);
        return;
    }
    crate::info!("[USB] Starting USB hub child enumeration (depth {})...", depth);

    // このハブ自身の識別情報を退避 (子ハブの再帰列挙でグローバルが書き替わるため)
    let my_hub_addr = HUB_ADDR;
    let my_hub_mps = HUB_EP0_MPS;
    let my_port_count = HUB_PORT_COUNT;

    for port in 1..=my_port_count {
        let _ = hub_set_port_feature(port, HUB_FEATURE_PORT_POWER);
    }
    crate::info!("[USB] Waiting 1000ms for USB hub ports to settle...");
    delay_ms(1000); // 100msから1000msに延長。vmnet-sharedの初期化遅延対策

    for port in 1..=my_port_count {
        let status = match hub_get_port_status(port) {
            Some(status) => status,
            None => {
                crate::debug!("[USB] Hub port {}: failed to read status.", port);
                continue;
            }
        };

        if (status & 0x0001) == 0 {
            continue;
        }

        crate::warn!(
            "[USB]   Hub port {}: device connected. status=0x{:08X} speed={}",
            port,
            status,
            CURRENT_HUB_PORT_SPEED
        );
        if !hub_reset_port(port) {
            crate::warn!("[USB]   Hub port {}: reset failed.", port);
            continue;
        }

        // リセット後の回復ウェイト
        delay_ms(100);

        // リセット後の最新ステータスと速度を再取得して更新する
        let status_post = match hub_get_port_status(port) {
            Some(s) => s,
            None => {
                crate::warn!("[USB]   Hub port {}: failed to read status post-reset.", port);
                continue;
            }
        };
        unsafe {
            CURRENT_HUB_PORT_SPEED = (status_post >> 9) & 0x3;
        }
        crate::warn!(
            "[USB]   Hub port {}: reset success. status=0x{:08X} speed={}",
            port,
            status_post,
            unsafe { CURRENT_HUB_PORT_SPEED }
        );

        let child_addr = NEXT_DEVICE_ADDR + 1;
        let label_buf = [
            b'H',
            b'u',
            b'b',
            b' ',
            b'P',
            b'o',
            b'r',
            b't',
            b' ',
            b'0' + port,
        ];
        let label = unsafe { core::str::from_utf8_unchecked(&label_buf) };

        // 親ハブ情報の保存
        unsafe {
            CURRENT_HUB_PORT = port;
        }

        // アドレスは列挙の成否にかかわらず事前に消費する。
        // enumerate_default_address_device が SET_ADDRESS まで進んで失敗した場合、
        // デバイスは child_addr に居座ったままになる。次のデバイスが同じ child_addr を
        // 使うとバス上でアドレス衝突が起き、CSPLIT NAK 地獄になる。
        NEXT_DEVICE_ADDR = child_addr;

        if let Some(child) = enumerate_default_address_device(child_addr, label) {
            match child.kind {
                UsbDeviceKind::Keyboard | UsbDeviceKind::Mouse | UsbDeviceKind::Tablet => {
                    register_hid_device(child)
                }
                UsbDeviceKind::CdcEthernet => {
                    crate::debug!("[USB] Hub port {}: USB Ethernet configured.", port)
                }
                UsbDeviceKind::Hub => {
                    // ネストハブ: enumerate_default_address_device が HUB_ADDR / HUB_EP0_MPS
                    // を子ハブに更新済み。ポート数を設定して子ハブ配下を再帰列挙する。
                    crate::warn!(
                        "[USB]   Hub port {}: nested hub (addr {}, {} ports). Enumerating children...",
                        port,
                        child.address,
                        child.port_count
                    );
                    HUB_PORT_COUNT = child.port_count;
                    enumerate_hub_children(depth + 1);
                    // 自分 (親ハブ) の識別情報へ復元して残りのポートの列挙を続ける
                    HUB_ADDR = my_hub_addr;
                    HUB_EP0_MPS = my_hub_mps;
                    HUB_PORT_COUNT = my_port_count;
                }
                UsbDeviceKind::None => {}
            }
        } else {
            crate::warn!(
                "[USB]   Hub port {}: enumeration failed (addr {} consumed).",
                port,
                child_addr
            );
        }

        // 親ハブ情報のクリア
        unsafe {
            CURRENT_HUB_PORT = 0;
            CURRENT_HUB_PORT_SPEED = 0;
        }

        let _ = hub_clear_port_feature(port, HUB_FEATURE_C_PORT_CONNECTION);
        let _ = hub_clear_port_feature(port, HUB_FEATURE_C_PORT_RESET);
    }

    crate::warn!(
        "[USB] Hub child enumeration completed. {} HID device(s) ready.",
        HID_DEVICE_COUNT.0
    );
}

unsafe fn enumerate_root_device() {
    crate::info!("[USB] Starting USB Device Enumeration...");

    if let Some(root) = enumerate_default_address_device(1, "Root Device") {
        NEXT_DEVICE_ADDR = 1;
        match root.kind {
            UsbDeviceKind::Hub => {
                HUB_PORT_COUNT = root.port_count;
                enumerate_hub_children(0);
            }
            UsbDeviceKind::Keyboard | UsbDeviceKind::Mouse | UsbDeviceKind::Tablet => {
                register_hid_device(root);
                crate::debug!("[USB] USB root HID enumeration completed.");
            }
            UsbDeviceKind::CdcEthernet => {
                crate::debug!("[USB] USB root Ethernet enumeration completed.");
            }
            UsbDeviceKind::None => {}
        }
    }
}

unsafe fn handle_mouse_packet() {
    let btn = DMA_BUF.data[0];
    let dx = DMA_BUF.data[1];
    let dy = (-(DMA_BUF.data[2] as i8)) as u8;

    let mut ps2_btn = 0x08;
    if (btn & 0x01) != 0 {
        ps2_btn |= 0x01;
    }
    if (btn & 0x02) != 0 {
        ps2_btn |= 0x02;
    }
    if (btn & 0x04) != 0 {
        ps2_btn |= 0x04;
    }
    if (dx as i8) < 0 {
        ps2_btn |= 0x10;
    }
    if (dy as i8) < 0 {
        ps2_btn |= 0x20;
    }

    let _ = crate::kernel::interrupt::MOUSE_FIFO.lock().push(0xFE);
    let _ = crate::kernel::interrupt::MOUSE_FIFO
        .lock()
        .push(ps2_btn as u32);
    let _ = crate::kernel::interrupt::MOUSE_FIFO.lock().push(dx as u32);
    let _ = crate::kernel::interrupt::MOUSE_FIFO.lock().push(dy as u32);
}

unsafe fn handle_tablet_packet(len: usize) {
    if len < 5 {
        return;
    }

    let btn = DMA_BUF.data[0];
    let abs_x = (DMA_BUF.data[1] as u16) | ((DMA_BUF.data[2] as u16) << 8);
    let abs_y = (DMA_BUF.data[3] as u16) | ((DMA_BUF.data[4] as u16) << 8);

    // 絶対座標イベントのシグネチャ: 0xFC
    // この後、btn, abs_x, abs_y, wheel を連続して送る
    let wheel = if len >= 6 { DMA_BUF.data[5] as i8 } else { 0 };
    let _ = crate::kernel::interrupt::MOUSE_FIFO.lock().push(0xFC);
    let _ = crate::kernel::interrupt::MOUSE_FIFO.lock().push(btn as u32);
    let _ = crate::kernel::interrupt::MOUSE_FIFO
        .lock()
        .push(abs_x as u32);
    let _ = crate::kernel::interrupt::MOUSE_FIFO
        .lock()
        .push(abs_y as u32);
    let _ = crate::kernel::interrupt::MOUSE_FIFO
        .lock()
        .push(wheel as u32);
}

unsafe fn handle_keyboard_packet(device: &mut UsbHidDevice) {
    let modifier = DMA_BUF.data[0];
    let shift_pressed = (modifier & 0x22) != 0;
    let ctrl_pressed = (modifier & 0x11) != 0; // LCtrl (0x01) | RCtrl (0x10)
    let alt_pressed = (modifier & 0x44) != 0; // LAlt (0x04) | RAlt (0x40)
    let gui_pressed = (modifier & 0x88) != 0; // LGui (0x08) | RGui (0x80)

    if shift_pressed != device.shift_pressed {
        device.shift_pressed = shift_pressed;
        let code = 0x2A;
        let p = if shift_pressed { code } else { code | 0x80 };
        let _ = crate::kernel::interrupt::KBD_FIFO.lock().push(p as u32);
    }

    if ctrl_pressed != device.ctrl_pressed {
        device.ctrl_pressed = ctrl_pressed;
        let code = 0x1D; // LCtrl scan code
        let p = if ctrl_pressed { code } else { code | 0x80 };
        let _ = crate::kernel::interrupt::KBD_FIFO.lock().push(p as u32);
    }

    if alt_pressed != device.alt_pressed {
        device.alt_pressed = alt_pressed;
        let code = 0x38; // LAlt scan code
        let p = if alt_pressed { code } else { code | 0x80 };
        let _ = crate::kernel::interrupt::KBD_FIFO.lock().push(p as u32);
    }

    if gui_pressed != device.gui_pressed {
        device.gui_pressed = gui_pressed;
        let code = 0x5B; // LGui scan code
        let p = if gui_pressed { code } else { code | 0x80 };
        let _ = crate::kernel::interrupt::KBD_FIFO.lock().push(p as u32);
    }

    for key_idx in 0..6 {
        let key = DMA_BUF.data[2 + key_idx];
        if key == 0 {
            continue;
        }

        let mut is_new = true;
        for prev_idx in 0..6 {
            if device.key_prev_state[prev_idx] == key {
                is_new = false;
                break;
            }
        }

        if is_new {
            if let Some(ps2_code) = hid_to_ps2(key) {
                let _ = crate::kernel::interrupt::KBD_FIFO
                    .lock()
                    .push(ps2_code as u32);
            }
        }
    }

    for prev_idx in 0..6 {
        let prev_key = device.key_prev_state[prev_idx];
        if prev_key == 0 {
            continue;
        }

        let mut is_released = true;
        for key_idx in 0..6 {
            if DMA_BUF.data[2 + key_idx] == prev_key {
                is_released = false;
                break;
            }
        }

        if is_released {
            if let Some(ps2_code) = hid_to_ps2(prev_key) {
                let _ = crate::kernel::interrupt::KBD_FIFO
                    .lock()
                    .push((ps2_code | 0x80) as u32);
            }
        }
    }

    for idx in 0..6 {
        device.key_prev_state[idx] = DMA_BUF.data[2 + idx];
    }
}

/// ホストチャネルを使った1つのUSB転送（トランザクション）の発行
/// ch: チャネル番号, ep: エンドポイント, dev_addr: デバイスアドレス, pid: PID(0=DATA0, 2=DATA1, 3=SETUP), dir_in: 転送方向(true=IN, false=OUT), len: 転送サイズ
unsafe fn usb_transfer(
    ch: usize,
    ep: u8,
    dev_addr: u8,
    ep_type: u8,
    pid: u32,
    dir_in: bool,
    buffer_phys: u32,
    len: u32,
    mps: u16,
    timeout_val: u32,
) -> Result<u32, ()> {
    // キャッシュ一貫性の確保 (DMA Buffer)
    if !dir_in || pid == 3 {
        if len > 0 {
            crate::kernel::mmu::clean_dcache_range(buffer_phys as usize, len as usize);
        } else if pid == 3 {
            crate::kernel::mmu::clean_dcache_range(buffer_phys as usize, 8); // SETUPは常に8バイト
        }
    } else if dir_in && len > 0 {
        crate::kernel::mmu::invalidate_dcache_range(buffer_phys as usize, len as usize);
    }

    // スプリット転送が必要か判定:
    // ルートがHSで、対象デバイスがハブ経由かつ HS (2) ではない場合。
    // 親ハブはデバイスごとに DEV_HUB_ADDRS で追跡する (ネストハブ対応)。
    let is_split = unsafe {
        DEV_SPEED == 0 && (
            (dev_addr == 0 && HUB_ADDR > 0 && CURRENT_HUB_PORT > 0 && CURRENT_HUB_PORT_SPEED != 2) ||
            (dev_addr > 0 && DEV_HUB_ADDRS[dev_addr as usize] > 0 && DEV_SPEEDS[dev_addr as usize] != 2)
        )
    };

    if !is_split {
        // 0. HCSPLT をクリア（非スプリット転送）。
        core::ptr::write_volatile(hc_splt(ch), 0);

        // 1. チャネル割り込みのクリア + マスク設定
        core::ptr::write_volatile(hc_int(ch), 0x7FF);
        core::ptr::write_volatile(hc_intmsk(ch), 0x7FF);
        core::ptr::write_volatile(HAINTMSK, 0xFFFF);

        // 2. 転送サイズとPID、パケット数の設定
        let packet_count = if len == 0 {
            1
        } else {
            len.div_ceil(mps as u32)
        };
        let mut tsiz = len & 0x7FFFF;
        tsiz |= packet_count << 19;
        tsiz |= pid << 29; // PID (0: DATA0, 2: DATA1, 3: SETUP)
        core::ptr::write_volatile(hc_tsiz(ch), tsiz);

        // 3. DMAアドレスを設定
        let bus_addr = buffer_phys | 0xC0000000;
        core::ptr::write_volatile(hc_dma(ch), bus_addr);

        // 4. チャネル特性の設定 ＆ 転送開始
        let mut hcchar = mps as u32 & 0x7FF; // MaxPacketSize (Bits 10:0)
        hcchar |= (ep as u32 & 0xF) << 11; // EPNum (Bits 14:11)
        if dir_in {
            hcchar |= 1 << 15; // EPDir = IN (Bit 15)
        }
        if DEV_SPEED == 2 {
            hcchar |= 1 << 17; // LSPDev = Low-Speed (Bit 17)
        }
        hcchar |= (ep_type as u32 & 0x3) << 18; // EPType (Bits 19:18)
        hcchar |= 1 << 20; // MULTI_CNT = 1
        hcchar |= (dev_addr as u32 & 0x7F) << 22; // DevAddr (Bits 28:22)
        // OddFrame (bit29): Circle reads HFNUM and sets this even for bulk.
        // Real BCM2837 DWC2 requires it for correct frame scheduling.
        if (core::ptr::read_volatile(HFNUM) & 1) != 0 {
            hcchar |= 1 << 29; // OddFrame
        }
        hcchar |= 1 << 31; // ChEna = Channel Enable (Bit 31)

        core::ptr::write_volatile(hc_char(ch), hcchar);

        // メモリバリア
        core::arch::asm!("dsb sy", "isb", options(nostack));

        // 5. ポーリングで待機
        let start_time = crate::kernel::timer::get_system_time_us();
        let timeout_us = timeout_val as u64;
        loop {
            core::arch::asm!("dsb sy", options(nostack));
            let hctrans = core::ptr::read_volatile(hc_char(ch));
            if (hctrans & (1 << 31)) == 0 {
                core::arch::asm!("dsb sy", options(nostack));
                let interrupts = core::ptr::read_volatile(hc_int(ch));
                if interrupts == 0 {
                    // DWC2 on real HW (Pi 4) may clear ChEna slightly before setting HCINT.
                    // If no interrupt reason is posted yet, check timeout and break out if needed.
                    if crate::kernel::timer::get_system_time_us().wrapping_sub(start_time) > timeout_us {
                        crate::warn!("[USB] ch{} TIMEOUT while waiting for HCINT to populate", ch);
                        return Err(());
                    }
                    continue;
                }
                if (interrupts & (1 << 0)) != 0 {
                    // XferCompl
                    let actual_size = len - (core::ptr::read_volatile(hc_tsiz(ch)) & 0x7FFFF);
                    if dir_in && actual_size > 0 {
                        crate::kernel::mmu::invalidate_dcache_range(
                            buffer_phys as usize,
                            actual_size as usize,
                        );
                    }
                    return Ok(actual_size);
                }
                if (interrupts & (1 << 1)) != 0 {
                    // ChHltd
                    let ints2 = core::ptr::read_volatile(hc_int(ch));
                    if (ints2 & (1 << 0)) != 0 {
                        let actual_size = len - (core::ptr::read_volatile(hc_tsiz(ch)) & 0x7FFFF);
                        if dir_in && actual_size > 0 {
                            crate::kernel::mmu::invalidate_dcache_range(
                                buffer_phys as usize,
                                actual_size as usize,
                            );
                        }
                        return Ok(actual_size);
                    }
                    if (ints2 & (1 << 4)) == 0 {
                        // STALL (bit 3) は正常なプロトコル拒否応答であり、警告ログを出さず debug! にします
                        if (ints2 & (1 << 3)) != 0 {
                            crate::debug!(
                                "[USB]     Transfer STALL (hc_int=0x{:03X} is_split={} dir_in={} ep={} len={} dev_addr={})",
                                ints2,
                                is_split,
                                dir_in as u8,
                                ep,
                                len,
                                dev_addr
                            );
                        } else {
                            crate::warn!(
                                "[USB]     Transfer failed: Channel Halted (hc_int=0x{:03X} is_split={} dir_in={} ep={} len={} dev_addr={})",
                                ints2,
                                is_split,
                                dir_in as u8,
                                ep,
                                len,
                                dev_addr
                            );
                        }
                    }
                    return Err(());
                }
                if (interrupts & (1 << 2)) != 0 {
                    // AHBErr (bit2) - AHB DMA read/write error
                    crate::warn!("[USB] ch{} AHB Error (hcint=0x{:03X})", ch, interrupts);
                    return Err(());
                }
                if (interrupts & (1 << 3)) != 0 {
                    // STALL (bit3) - device returned STALL
                    crate::warn!("[USB] ch{} STALL (hcint=0x{:03X})", ch, interrupts);
                    return Err(());
                }
                if (interrupts & (1 << 4)) != 0 {
                    // NAK
                    return Err(());
                }
                // ChEna cleared but no recognized completion/error bits.
                // Log at warn for real-HW diagnostics (HCINT=0 case).
                crate::warn!(
                    "[USB] ch{} unexpected halt: hcint=0x{:03X} dir_in={} ep={} len={}",
                    ch, interrupts, dir_in as u8, ep, len
                );
                return Err(());
            }

            if crate::kernel::timer::get_system_time_us().wrapping_sub(start_time) > timeout_us {
                // Request channel halt (Circle: always wait for ChHltd after ChDis)
                let mut char_val = core::ptr::read_volatile(hc_char(ch));
                char_val |= 1 << 30; // ChDis
                char_val |= 1 << 31; // ChEna (required to let ChDis take effect)
                core::ptr::write_volatile(hc_char(ch), char_val);
                // Wait up to 1ms for channel to actually halt before returning,
                // so next transfer on same channel starts clean.
                let halt_start = crate::kernel::timer::get_system_time_us();
                loop {
                    core::arch::asm!("dsb sy", options(nostack));
                    if (core::ptr::read_volatile(hc_char(ch)) & (1 << 31)) == 0 {
                        break;
                    }
                    if crate::kernel::timer::get_system_time_us().wrapping_sub(halt_start)
                        > 1_000
                    {
                        break;
                    }
                }
                let final_hcint = core::ptr::read_volatile(hc_int(ch));
                let final_hcchar = core::ptr::read_volatile(hc_char(ch));
                let chdis_ok = (final_hcchar & (1 << 31)) == 0;
                let final_gnptxsts = core::ptr::read_volatile(GNPTXSTS);
                let final_gintsts = core::ptr::read_volatile(GINTSTS);
                crate::warn!(
                    "[USB] ch{} TIMEOUT: hcint=0x{:03X} hcchar=0x{:08X} chdis_ok={} gnptx=0x{:08X} gintsts=0x{:08X}",
                    ch, final_hcint, final_hcchar, chdis_ok, final_gnptxsts, final_gintsts
                );
                return Err(());
            }
        }
    } else {
        // --- スプリット転送 ---
        // 宛先は必ず TT を持つ直近の HS ハブでなければならない。デバイスごとに記録した
        // 直接の親ハブから、非 HS ハブを飛ばして直近の HS ハブまで辿る (resolve_split_target)。
        let (hub_addr, port_addr) = unsafe {
            let (direct_hub_addr, direct_port) = if dev_addr > 0 {
                (
                    DEV_HUB_ADDRS[dev_addr as usize],
                    DEV_HUB_PORTS[dev_addr as usize],
                )
            } else {
                (HUB_ADDR, CURRENT_HUB_PORT)
            };
            resolve_split_target(direct_hub_addr, direct_port)
        };

        let is_periodic = ep_type == 3;
        let mut sched = if is_periodic {
            frame_sched::FrameScheduler::new_periodic()
        } else {
            frame_sched::FrameScheduler::new_non_periodic()
        };

        sched.start_split();

        let start_time = crate::kernel::timer::get_system_time_us();
        // スプリット転送時はハブの下流応答待ちによる NYET リトライが多発するため、
        // タイムアウトを最小 1,000,000us (1秒) に引き上げるが、
        // Periodic (Interrupt) ポーリングでアイドル時に毎回1秒ブロックしないよう短く切る。
        let timeout_us = if is_periodic {
            (timeout_val as u64).min(5_000) // 5ms で打ち切り
        } else {
            (timeout_val as u64).max(1_000_000)
        };

        loop {
            if crate::kernel::timer::get_system_time_us().wrapping_sub(start_time) > timeout_us {
                let mut char_val = core::ptr::read_volatile(hc_char(ch));
                char_val |= 1 << 30; // ChDis
                char_val |= 1 << 31; // ChEna
                core::ptr::write_volatile(hc_char(ch), char_val);
                let halt_start = crate::kernel::timer::get_system_time_us();
                loop {
                    core::arch::asm!("dsb sy", options(nostack));
                    if (core::ptr::read_volatile(hc_char(ch)) & (1 << 31)) == 0 {
                        break;
                    }
                    if crate::kernel::timer::get_system_time_us().wrapping_sub(halt_start)
                        > 1_000
                    {
                        break;
                    }
                }
                if !is_periodic {
                    crate::warn!(
                        "[USB] ch{} split TIMEOUT: hcint=0x{:03X} dir_in={} ep={} dev_addr={} hub_addr={} port={} state={:?} nak_restarts={}",
                        ch,
                        core::ptr::read_volatile(hc_int(ch)),
                        dir_in as u8,
                        ep,
                        dev_addr,
                        hub_addr,
                        port_addr,
                        sched.state,
                        sched.nak_restarts
                    );
                    return Err(());
                } else {
                    let hcint = core::ptr::read_volatile(hc_int(ch));
                    if (hcint & 0x050) == 0 { // NAK (0x010) と NYET (0x040) 以外ならバスエラー等なので警告
                        crate::warn!("[USB] ch{} Periodic split TIMEOUT with error: hcint=0x{:03X} state={:?}", ch, hcint, sched.state);
                    }
                    return Ok(0); // 割り込み転送のタイムアウトは「データなし(NAK)」と同義
                }
            }

            let is_csplit = sched.complete_split();

            // 1. HCSPLT の設定
            let mut splt = 1 << 31; // SPLTENA
            if is_csplit {
                splt |= 1 << 16; // COMPSPLT
            }
            splt |= 3 << 14; // XACTPOS = All
            splt |= ((hub_addr as u32) & 0x7F) << 7;
            splt |= (port_addr as u32) & 0x7F;
            core::ptr::write_volatile(hc_splt(ch), splt);

            // 2. 割り込みクリア
            core::ptr::write_volatile(hc_int(ch), 0x7FF);
            core::ptr::write_volatile(hc_intmsk(ch), 0x7FF);
            core::ptr::write_volatile(HAINTMSK, 0xFFFF);

            // 3. 転送サイズとDMAアドレスの設定
            let packet_count = if len == 0 {
                1
            } else {
                len.div_ceil(mps as u32)
            };
            let mut tsiz = len & 0x7FFFF;
            tsiz |= packet_count << 19;
            tsiz |= pid << 29;
            core::ptr::write_volatile(hc_tsiz(ch), tsiz);

            let bus_addr = buffer_phys | 0xC0000000;
            core::ptr::write_volatile(hc_dma(ch), bus_addr);

            // 4. フレーム待機 (マイクロフレーム同期)
            sched.wait_for_frame();

            // 5. チャネル特性の設定と開始
            let mut hcchar = mps as u32 & 0x7FF;
            hcchar |= (ep as u32 & 0xF) << 11;
            if dir_in {
                hcchar |= 1 << 15;
            }
            // スプリット転送時は AXI バス上の通信は常にハブの速度(HS)となるため、
            // LSPDev (bit 17) は設定してはなりません (常に0)。
            hcchar |= (ep_type as u32 & 0x3) << 18;
            if sched.is_odd_frame() {
                hcchar |= 1 << 29; // OddFrame
            }
            hcchar |= 1 << 20; // MULTI_CNT = 1
            hcchar |= (dev_addr as u32 & 0x7F) << 22;
            hcchar |= 1 << 31; // ChEna

            core::ptr::write_volatile(hc_char(ch), hcchar);

            // メモリバリア
            core::arch::asm!("dsb sy", "isb", options(nostack));

            // 6. ポーリング完了待ち (スプリット1回分)
            let trans_start = crate::kernel::timer::get_system_time_us();
            let mut interrupts = 0;
            loop {
                core::arch::asm!("dsb sy", options(nostack));
                let hctrans = core::ptr::read_volatile(hc_char(ch));
                if (hctrans & (1 << 31)) == 0 {
                    interrupts = core::ptr::read_volatile(hc_int(ch));
                    if interrupts != 0 {
                        break;
                    }
                }
                if crate::kernel::timer::get_system_time_us().wrapping_sub(trans_start) > 50000 {
                    break; // 50ms タイムアウト
                }
            }

            // スケジューラに状態通知
            sched.transaction_complete(interrupts);

            if sched.is_complete() {
                let actual_size = len - (core::ptr::read_volatile(hc_tsiz(ch)) & 0x7FFFF);
                if dir_in && actual_size > 0 {
                    crate::kernel::mmu::invalidate_dcache_range(
                        buffer_phys as usize,
                        actual_size as usize,
                    );
                }
                return Ok(actual_size);
            }

            if sched.is_failed() {
                if !is_periodic {
                    crate::warn!(
                        "[USB] ch{} split transaction failed: status=0x{:03X} state={:?} ep={} dev_addr={} hub_addr={} port={} mps={} dir_in={} nak_restarts={}",
                        ch,
                        interrupts,
                        sched.state,
                        ep,
                        dev_addr,
                        hub_addr,
                        port_addr,
                        mps,
                        dir_in as u8,
                        sched.nak_restarts
                    );
                    return Err(());
                } else {
                    if (interrupts & 0x050) == 0 {
                        crate::warn!("[USB] ch{} Periodic split failed with error: hcint=0x{:03X} state={:?}", ch, interrupts, sched.state);
                    }
                    return Ok(0); // データなしとして扱う
                }
            }

            // Periodic転送の場合、遅延を入れるとマイクロフレーム同期が崩れてTTにデータを破棄されるため待機しない
            if !is_periodic {
                delay_ms(1);
            }
        }
    }
}

/// USBコントロール転送の実行 (SETUP, DATA, STATUSの3ステージ)
unsafe fn usb_control_transfer(
    request: UsbSetupPacket,
    data_buf_phys: u32,
    data_len: u32,
    dir_in: bool,
) -> Result<u32, ()> {
    // Packed構造体のフィールドアライメント問題を避けるため、一旦ローカル変数にコピー
    let req_type = request.request_type;
    let req_code = request.request;
    let req_value = request.value;
    let req_index = request.index;
    let req_length = request.length;

    // 1. SETUPバッファの構築
    let setup_ptr = &request as *const UsbSetupPacket as *const u8;
    for i in 0..8 {
        SETUP_BUF.data[i] = core::ptr::read(setup_ptr.add(i));
    }

    // コントロール転送は SETUP/DATA/STATUS が一体のトランザクション。DATA ステージ
    // だけを再試行しても、デバイス側の EP0 状態機械が SETUP 待ちに戻っている場合は
    // 永遠に NAK され続ける (実機のハブ配下 FS デバイスで観測)。そのため DATA 失敗時
    // は SETUP からやり直す (SETUP は EP0 状態を無条件にリセットする)。
    let mut outer = 3;
    let mut actual_len;
    'transfer: loop {
        // 2. SETUPステージ
        // ch=0, ep=0, dev_addr=DEV_ADDR, pid=3(SETUP), dir=OUT
        let mut retry = 3;
        while retry > 0 {
            let setup_phys = &SETUP_BUF as *const DmaBuffer as u32;
            if usb_transfer(0, 0, DEV_ADDR, 0, 3, false, setup_phys, 8, EP0_MPS, 200000).is_ok() {
                break;
            }
            retry -= 1;
            delay_ms(5);
        }
        if retry == 0 {
            crate::warn!(
                "[USB] SETUP stage failed: req_type=0x{:02X} req=0x{:02X} val=0x{:04X} idx=0x{:04X} len={} dev_addr={}",
                req_type,
                req_code,
                req_value,
                req_index,
                req_length,
                DEV_ADDR
            );
            return Err(());
        }

        // 3. DATAステージ (データがある場合のみ)
        actual_len = 0;
        if data_len > 0 {
            let mut retry = 7;
            let mut success = false;
            while retry > 0 {
                // コントロール転送のデータステージは常に DATA1 から開始
                if usb_transfer(
                    0,
                    0,
                    DEV_ADDR,
                    0,
                    2,
                    dir_in,
                    data_buf_phys,
                    data_len,
                    EP0_MPS,
                    200000,
                )
                .is_ok()
                {
                    if dir_in {
                        actual_len = data_len;
                    }
                    success = true;
                    break;
                }
                retry -= 1;
                delay_ms(5);
            }
            if !success {
                outer -= 1;
                if outer == 0 {
                    crate::warn!(
                        "[USB] DATA stage failed: req_type=0x{:02X} req=0x{:02X} val=0x{:04X} idx=0x{:04X} len={} dev_addr={}",
                        req_type,
                        req_code,
                        req_value,
                        req_index,
                        req_length,
                        DEV_ADDR
                    );
                    return Err(());
                }
                crate::warn!(
                    "[USB] DATA stage failed; restarting control transfer from SETUP (remaining {})",
                    outer
                );
                delay_ms(10);
                continue 'transfer;
            }
        }
        break 'transfer;
    }

    // 4. STATUSステージ (応答)
    // 送信ならIN、受信ならOUTで0バイトのステータス確認パケットを送受信
    // ステータスステージのPIDは常に DATA1
    let status_phys = &SETUP_BUF as *const DmaBuffer as u32; // 空バッファを指定
    let mut retry = 100; // QEMU/実機での状態遷移中NAKを考慮し5から100に大幅拡張 (最大500ms)
    let mut success = false;
    while retry > 0 {
        if usb_transfer(
            0,
            0,
            DEV_ADDR,
            0,
            2,
            !dir_in,
            status_phys,
            0,
            EP0_MPS,
            200000,
        )
        .is_ok()
        {
            success = true;
            break;
        }
        retry -= 1;
        delay_ms(5);
    }
    if !success {
        crate::warn!(
            "[USB] STATUS stage failed: req_type=0x{:02X} req=0x{:02X} val=0x{:04X} idx=0x{:04X} len={} dev_addr={}",
            req_type,
            req_code,
            req_value,
            req_index,
            req_length,
            DEV_ADDR
        );
        return Err(());
    }

    Ok(actual_len)
}

static mut POLL_DIVIDER: u32 = 0;

/// 定期的にUSBデバイスをポーリングし、入力パケットを INPUT_FIFO に転送します
/// この関数は main.rs のループ内で毎フレーム実行されます
pub fn poll() {
    unsafe {
        let _lock = USB_LOCK.lock();
        HID_POLL_CALLS.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
        // 【2026-08-05】ここにあった `poll_usb_ethernet_data_plane()` を外した。
        //
        // ## 外す前の実測（3.7MB JPEG 取得中、fetch=4244tick=42.4秒）
        //
        // ```text
        // hid_eth_us=18641424  ← Core 1 がここで 18.6 秒（全体の 44%）
        // eth_us=2724875       ← Core 2 の専用スレッドは 2.7 秒だけ
        // hid_us=0             ← HID 転送そのものは無視できる
        // ```
        //
        // Ethernet 収穫は 2 コアから同じ `USB_LOCK` の下で行われており、
        // **本来 HID 担当の Core 1 が受信の 87% を担っていた**。
        // しかも Core 1 は収穫中ずっとロックを握るので、
        // 専用スレッド（Core 2）の `try_lock` が 41% 失敗し、
        // そのたびに受信の番が 100ms 飛んでいた。
        //
        // ## 一本化を試したが**明確に悪化したので戻した**
        //
        // 「Core 1 から外し、Core 2 の間隔を `yield_now` まで詰める」を試した結果、
        // 3.7MB の画像が **200 秒待っても完了しなくなった**
        // （それまでは 42 秒。1 ブート内の取得数も 13 → 10 に減った）。
        //
        // Core 2 には画像取得ワーカー等も載るため、`net_service_thread` が
        // `yield_now` で譲ると受信の番が安定して回ってこない。
        // 一方 Core 1 の `poll()` はスリープ無しの専用ループで、
        // **結果的にこれが最も安定した受信ドライバになっている**。
        // 見た目の役割分担（HID 担当）と実際の役割が食い違っているが、
        // 動いている構造を崩してはいけない。
        //
        // 受信を速くするなら、担当を移すのではなく
        // **1 フレームあたり 1.4ms かかっている中身**を削ること。
        let t_eth1 = crate::kernel::timer::get_system_time_us();
        poll_usb_ethernet_data_plane();
        HID_ETH_US.fetch_add(
            crate::kernel::timer::get_system_time_us().wrapping_sub(t_eth1) as u32,
            core::sync::atomic::Ordering::Relaxed,
        );
        // 【2026-08-05 計測】ここから下の HID 転送が
        // `USB_LOCK` をどれだけ握り続けるかを測る。
        // Core 2 の受信は try_lock なので、ここが長いと 41% の取りこぼしになる。
        let t_hid = crate::kernel::timer::get_system_time_us();

        // キャッシュの無効化 (Core 1 が物理メモリから最新値をロードするように強制)
        let count_addr = &HID_DEVICE_COUNT.0 as *const usize as usize;
        crate::kernel::mmu::invalidate_dcache_range(count_addr, core::mem::size_of_val(&HID_DEVICE_COUNT.0));
        let devices_addr = HID_DEVICES.0.as_ptr() as usize;
        crate::kernel::mmu::invalidate_dcache_range(devices_addr, core::mem::size_of_val(&HID_DEVICES.0));
        core::arch::asm!("dsb sy", "isb", options(nostack));

        if HID_DEVICE_COUNT.0 == 0 {
            return; // デバイスが未初期化の場合は何もしない
        }

        // チャネル1を割り当てて、インタラプト転送を実行
        let buf_phys = &DMA_BUF as *const DmaBuffer as u32;

        for idx in 0..HID_DEVICE_COUNT.0 {
            let device = &mut HID_DEVICES.0[idx];
            if device.address == 0 || device.hid_ep == 0 {
                continue;
            }

            // DATA toggle 管理: USB仕様では Interrupt IN は DATA0/DATA1 を交互に送る必要がある。
            // QEMUではトグルを無視しても動作するが、実機ではNAK/STALLの原因となる。
            let pid = device.data_toggle;
            let res = usb_transfer(
                1,
                device.hid_ep,
                device.address,
                3,
                pid,
                true,
                buf_phys,
                device.hid_ep_size as u32,
                device.hid_ep_size,
                200000,
            );

            if let Ok(len) = res {
                let recv_len = len as usize;
                if recv_len == 0 {
                    // NAK（データなし）: トグルは進めない
                    continue;
                }
                // 受信成功: トグルを反転 (DATA0=0 <-> DATA1=2)
                device.data_toggle = if pid == 0 { 2 } else { 0 };

                match device.kind {
                    UsbDeviceKind::Mouse => handle_mouse_packet(),
                    UsbDeviceKind::Tablet => handle_tablet_packet(len as usize),
                    UsbDeviceKind::Keyboard => handle_keyboard_packet(device),
                    _ => {}
                }
            }
        }
        HID_POLL_US.fetch_add(
            crate::kernel::timer::get_system_time_us().wrapping_sub(t_hid) as u32,
            core::sync::atomic::Ordering::Relaxed,
        );
    }
}

/// 【2026-08-05 診断】Core 1 の `poll()` が回った回数。
pub static HID_POLL_CALLS: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);
/// そのうち HID 転送に費やしたマイクロ秒の累計（`USB_LOCK` を握ったまま）。
pub static HID_POLL_US: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);
/// Core 1 の `poll()` が Ethernet 収穫に費やしたマイクロ秒の累計。
pub static HID_ETH_US: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);

// 【2026-08-05】収穫 1 回の内訳計装は目的を果たしたので撤去した（L-4）。
// 得られた事実（3.7MB 取得中、約 14000 フレーム）:
//   sec_frame_us  … フレーム処理。開始時 832µs/枚 → 修正後 75〜165µs/枚
//   sec_arm_us    … 再アーム 約 1.2 秒
//   sec_inv_us    … dcache 無効化 約 0.1 秒（軽い）
//   rndis_extra   … 1 転送に 2 個目以降のメッセージ = **0 件**
// 計装自体が `get_system_time_us`（除算を含む）をフレームごとに
// 2 回呼ぶため、熱経路に残してはいけない（U-5）。
pub static mut POLL_THREAD_ACTIVE: bool = false;

/// # 実測（2026-08-05、sugi-lab.net の 3.7MB JPEG 取得中）
///
/// ```text
/// fetch=4631tick  eth_calls=311  eth_ticks=282  eth_lockmiss=219
/// ```
///
/// - **この関数の内側で使っている時間は取得時間の 6%**（282/4631）。
///   受信処理そのものは重くない。
/// - 呼び出しが成立したのは 46 秒間で 311 回（≒150ms に 1 回）。
///   `net_service_thread` の `sleep(10)`（100ms）より疎い。
/// - 差の原因は `USB_LOCK` で、**試行 530 回中 219 回（41%）が
///   ロックを取れずに諦めている**（Core 1 の HID ポーリングと競合）。
///
/// つまり律速は「受信処理の重さ」でも「眠る間隔」でもなく、
/// **ロック競合で受信の番が回ってこないこと**。
///
/// 計算量: 1 回の呼び出しは **O(F)**（F は回収フレーム数、上限 8）。
pub fn poll_ethernet_data_plane_only() {
    // [修正] マルチコア環境でのデータ競合（USBレジスタやDMA_BUFへの複数コア同時アクセス）を防ぐため、
    // USBポーリングスレッドが稼働している Core 2 以外からの直接ポーリングを禁止する。
    // Core 2 以外は yield_now() で待機していれば、Core 2 が裏で受信パケットを処理してキューに積んでくれる。
    //
    // 【2026-07-25 補足】この関数名から`usb_poll_thread`（Core 1、HID専用）が
    // 呼んでいるように誤解しやすいが、実際にこの関数を毎ループ呼んでいるのは
    // `net_service_thread`（`main.rs`の`spawn_on_core(net_service_thread, ..., 2)`
    // によりCore 2固定）である。`core_id() != 2`のガードはこの`net_service_thread`
    // と正しく整合しており、意図通り動作している（spec/TODO.md 2026-07-24/25の
    // 調査で一度「バグ候補」として疑い、検証の上「問題なし」と確定済み）。
    if crate::kernel::scheduler::core_id() != 2 {
        return;
    }
    unsafe {
        // 【2026-07-30】DWC2 の共有レジスタ・DMA バッファ・`RX_IN_FLIGHT` 等の
        // `static mut` は Core 1（HID: `poll()`）と Core 2（本経路）の両方から
        // 触られる。`poll()` 側は `USB_LOCK` を取っていたが**こちらは取っておらず**、
        // 排他なしで同じレジスタを同時操作していた。
        // 受信が不安定になる典型なので同じロックで保護する。
        //
        // ただし**ブロックする `lock()` は使わない**。実測で、ネットワーク側が
        // ロックを保持し続けると Core 1 の `poll()`（HID/GUI）が待たされ、
        // 画面が「Loading Secure Page...」のまま更新されなくなった。
        // ネットワーク取得は 5/5 成功しているのに描画が止まる、という
        // 分かりにくい回帰になる。
        // 取得できなければこの回は諦める（次のポーリングで再試行される）。
        // 【2026-08-05】以前は 1 回 `try_lock` して駄目なら即 `return` していた。
        //
        // 呼び元（`net_service_thread`）は戻ると 100ms 眠るので、
        // **取りこぼし 1 回につき受信の番が 100ms 飛ぶ**。
        // 実測ではこれが試行の 41%（530 回中 219 回）に達していた。
        //
        // ## 粘って取りに行く案は**効果を示せなかったので入れていない**
        //
        // 「8 回まで `yield_now` しながら `try_lock` を繰り返す」を試すと、
        // 取りこぼしは 210 → 5 まで減った。ところが取得時間は改善せず、
        // 別の回では取りこぼしが 119 に戻り取得も遅くなった。
        //
        // ```text
        // 変更前: fetch = 3685 / 3746 / 4273 / 4296 / 4631 tick（平均 4126）
        // 変更後: fetch = 3598 / 4244 / 5879 tick（平均 4574）
        // ```
        //
        // 取りこぼしを潰しても速くならないのは、受信の 87% を
        // Core 1 の `poll()` が担っており、こちらの寄与が元々小さいから。
        // 根拠の無い複雑さは入れない。
        let Some(_lock) = USB_LOCK.try_lock() else {
            ETH_POLL_LOCK_MISS.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
            return;
        };
        // 【2026-08-05 計測】取得の律速がこの関数の内側かどうかを決める。
        // 内側の実時間が取得時間に比べて小さければ、律速は「呼ばれる回数」側。
        // 目的: 受信律速の特定。破棄条件: 特定でき次第削除。
        // tick（10ms 刻み）では 1 回数 ms の処理を測れない。
        // 毎回 0 と数えられて合計しても出てこないため、
        // CNTPCT 由来のマイクロ秒（`get_system_time_us`）で測る。
        let t0 = crate::kernel::timer::get_system_time_us();
        ETH_POLL_CALLS.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
        poll_usb_ethernet_data_plane();
        ETH_POLL_US.fetch_add(
            crate::kernel::timer::get_system_time_us().wrapping_sub(t0) as u32,
            core::sync::atomic::Ordering::Relaxed,
        );
    }
}

/// 【2026-07-29診断】USB Ethernet が受信したフレーム総数。
/// 「1 回目は成功するが 2 回目以降が失敗する」件で、
/// フレームがそもそも届いていないのかを切り分けるために数える。
/// 転送中のままポーリングした回数。上限を超えたら強制再アームする。
static mut RX_IN_FLIGHT_POLLS: u32 = 0;

/// 【2026-08-05 診断】`poll_ethernet_data_plane_only` が実際に働いた回数。
pub static ETH_POLL_CALLS: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);
/// その内側で費やしたマイクロ秒の累計。取得時間と比べて律速の在り処を決める。
pub static ETH_POLL_US: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);
/// `USB_LOCK` が取れずに諦めた回数。HID 側と競っているかを見る。
pub static ETH_POLL_LOCK_MISS: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);

/// 【2026-08-05 診断】USB 送信（イーサネットフレーム）の成否。
///
/// `送信再送` が 36 回の送信に対し 44〜48 回と多い。
/// 受信側（破棄 0.2%）・順序外バッファ・再送閾値のどれも原因でなく、
/// 送信キューも一度も溢れていない（`nic tx queue FULL` 0 件）。
/// 残るのは**USB へ実際に出せているか**。ここが最後の未計測区間。
/// 破棄条件: 送信ロストの原因が特定でき次第削除。
pub static TX_USB_OK: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);
pub static TX_USB_FAIL: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);

pub static RX_FRAME_COUNT: core::sync::atomic::AtomicU32 =
    core::sync::atomic::AtomicU32::new(0);

unsafe fn poll_usb_ethernet_data_plane() {
    let st = net::status();
    if !st.usb_eth_present
        || st.usb_eth_addr == 0
        || st.usb_eth_bulk_in == 0
        || st.usb_eth_bulk_out == 0
    {
        return;
    }

    let mut tx_buf = [0u8; 1536];
    let max_chunk = 1536; // USBコントローラが自動でMPS分割するので、ソフトウェア側で細切れにせずパケット全体を渡す
    while let Some(chunk_len) = net::nic_take_tx_ipv4_chunk(max_chunk, &mut tx_buf) {
        if chunk_len == 0 {
            break;
        }

        if st.usb_eth_is_rndis {
            let header_len = 44;
            let total_len = header_len + chunk_len;
            let rndis_header = RndisPacketMsg {
                message_type: 0x00000001, // RNDIS_PACKET_MSG
                message_length: total_len as u32,
                data_offset: 36, // Relative offset from the start of data_offset field (36 + 8 = 44 bytes offset from start)
                data_length: chunk_len as u32,
                oob_data_offset: 0,
                oob_data_length: 0,
                num_oob_data_elements: 0,
                packet_information_offset: 0,
                packet_information_length: 0,
                device_vc_handle: 0,
                reserved: 0,
            };

            let header_ptr = &rndis_header as *const RndisPacketMsg as *const u8;
            core::ptr::copy_nonoverlapping(header_ptr, DMA_BUF.data.as_mut_ptr(), header_len);
            core::ptr::copy_nonoverlapping(
                tx_buf.as_ptr(),
                DMA_BUF.data.as_mut_ptr().add(header_len),
                chunk_len,
            );

            let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
            let pid = crate::kernel::usb_toggle::pid_from_toggle(ETH_BULK_OUT_TOGGLE);
            match usb_transfer(
                2,
                st.usb_eth_bulk_out,
                st.usb_eth_addr,
                2,
                pid,
                false,
                buf_phys,
                total_len as u32,
                st.usb_eth_mps,
                500_000,
            ) {
                Ok(_) => {
                    crate::debug!("[USB] NET: USB OUT sent {} bytes (RNDIS)", total_len);
                }
                Err(_) => {
                    crate::warn!("[USB] NET: USB OUT FAILED (RNDIS)!");
                    break;
                }
            }
            // 【2026-07-29】トグル計算は検証済みモジュールへ一本化
            // （`kernel/usb_toggle.rs`、単体試験 14 件）。
            // ここへ到達するのは転送成功時のみ（失敗時は上の `Err` で break）。
            // トグルがずれるとデバイスはパケットを重複とみなして黙って捨てるため、
            // インライン計算のままだと壊れても気付けない。
            if let Some(pc) = crate::kernel::usb_toggle::packet_count(total_len, st.usb_eth_mps as u32) {
                ETH_BULK_OUT_TOGGLE = crate::kernel::usb_toggle::advance_by_packets(
                    ETH_BULK_OUT_TOGGLE,
                    pc,
                    crate::kernel::usb_toggle::TxnResult::Acked,
                );
            }
        } else {
            DMA_BUF.data[..chunk_len].copy_from_slice(&tx_buf[..chunk_len]);
            let buf_phys = &DMA_BUF as *const DmaBuffer as u32;
            let pid = crate::kernel::usb_toggle::pid_from_toggle(ETH_BULK_OUT_TOGGLE);
            match usb_transfer(
                2,
                st.usb_eth_bulk_out,
                st.usb_eth_addr,
                2,
                pid,
                false,
                buf_phys,
                chunk_len as u32,
                st.usb_eth_mps,
                500_000,
            ) {
                Ok(_) => {
                    crate::debug!("[USB] NET: USB OUT sent {} bytes (CDC-ECM)", chunk_len);
                }
                Err(_) => {
                    crate::warn!("[USB] NET: USB OUT FAILED (CDC-ECM)!");
                    break;
                }
            }
            // CDC-ECM 側も同様に検証済みモジュールへ一本化（`kernel/usb_toggle.rs`）。
            // 到達するのは転送成功時のみ（失敗時は上の `Err` で break）。
            if let Some(pc) = crate::kernel::usb_toggle::packet_count(chunk_len, st.usb_eth_mps as u32) {
                ETH_BULK_OUT_TOGGLE = crate::kernel::usb_toggle::advance_by_packets(
                    ETH_BULK_OUT_TOGGLE,
                    pc,
                    crate::kernel::usb_toggle::TxnResult::Acked,
                );
            }
        }
    }

    // --- 受信 (bulk IN): 「張りっぱなし」非同期方式 ---
    // QEMU DWC2 モデルは bulk NAK 時にチャネルを停止せず (ChEna 維持)、
    // 内部タイマ (4kHz) とデバイス wakeup で自動再試行し、データ到着時に
    // XferCompl|ChHltd で完了する。従来の「スピン待ち→タイムアウトで強制 ChDis」は
    // この保留パケットを毎回キャンセルしてしまい、受信が永久に成立しなかった。
    // よって IN は一度発行したら放置し、後続の poll で完了だけを収穫する。
    const RX_LEN: u32 = 1600;
    static mut RX_IN_FLIGHT: bool = false;
    /// 【2026-07-26診断】XferCompl 以外でチャネルが停止した回数。
    static mut RX_ABNORMAL_HALTS: u32 = 0;

    // 1 ポールで最大 8 フレームまで収穫する。
    // デバイス(QEMU usb-net)は 1 フレームしか持てないため、収穫→即再装填を繰り返すと
    // 連続データ時はチャネル再装填の同期完了で次々と取り込める。
    // 【2026-07-30】1 回のポーリングで回収するフレーム数。
    // 64 へ増やし間隔も詰めたところ実機で全滅したため 8 に戻した
    // （`kernel/usb_rx_state.rs` の試験と `spec/l1_l2_usb.md` を参照）。
    //
    // 【2026-08-05】画像取得の律速がここだと実測で確定した。
    //
    // 3.7MB の JPEG は取得 3685 tick に対しデコード 1092 tick
    // （`[IMGPERF]`）。取得側が 3 倍以上重い。
    // ポーリング間隔 100ms × 1 回 8 フレーム × 1500 バイト
    //   = 120KB/s
    // で、実効 100KB/s とほぼ一致する。**この 2 つの値が上限そのもの**。
    //
    // 2026-07-30 の全滅は間隔（100→20ms）と回収数（8→64）を
    // **同時に**変えた結果で、どちらが原因かは分かっていない。
    // 当時の注記自身が「片方ずつ変えて測ること」と書いている。
    //
    // 回収数だけを 8 → 32 にして測った結果（間隔は 100ms のまま）:
    //
    // ```
    // 8:  fetch=3685tick  13/13 成功
    // 32: fetch=8329tick  13/13 成功   ← 2.3 倍**遅い**
    // ```
    //
    // 成功率は落ちないが確実に遅くなる。
    // QEMU の usb-net はデバイス側が 1 フレームしか持てないため、
    // 予算を増やしても待つ回数が増えるだけで、
    // その間 `USB_LOCK` を握り続けて他を止めているとみられる。
    // **8 のままが正しい。**
    let mut harvest_budget = 8u32;
    loop {
        if RX_IN_FLIGHT {
            let hcchar_v = core::ptr::read_volatile(hc_char(3));
            let ints = core::ptr::read_volatile(hc_int(3));
            // 【2026-07-29】判断は純粋モジュールへ委譲（`kernel/usb_rx_state.rs`、
            // 単体試験 10 件）。以前はここで CHENA が立っている限り無条件に
            // `return` しており、CHENA が落ちない状態に陥ると**受信が永久に停止**
            // していた（実測: 1 回目の 14 フレーム以降まったく増えない）。
            // DNS タイムアウト・TCP 接続タイムアウト・受信打ち切りは
            // すべてこの単一症状の現れだった。
            let action = crate::kernel::usb_rx_state::decide(
                true,
                hcchar_v,
                ints,
                RX_IN_FLIGHT_POLLS,
            );
            if action == crate::kernel::usb_rx_state::RxAction::WaitInFlight {
                RX_IN_FLIGHT_POLLS = RX_IN_FLIGHT_POLLS.saturating_add(1);
                return;
            }
            // NAK は「今はデータが無い」という正常応答。異常扱いも待機もせず、
            // 割り込みをクリアして即座に再アームへ進む（下の再アーム処理へ落とす）。
            if action == crate::kernel::usb_rx_state::RxAction::Rearm {
                // 【2026-08-05】ここで `hc_int` をクリアしていたが、
                // この後どの経路を通っても必ず下の再アーム処理へ落ち、
                // そこで**同じクリアをもう一度**行っている。
                // NAK は「今はデータが無い」という正常応答なので
                // この経路は頻繁に通り、MMIO 書き込みが 1 回まるごと無駄だった。
                RX_IN_FLIGHT_POLLS = 0;
                RX_IN_FLIGHT = false;
            }
            if RX_IN_FLIGHT_POLLS >= crate::kernel::usb_rx_state::MAX_IN_FLIGHT_POLLS {
                crate::warn!(
                    "[USB][RX] channel stuck enabled for {} polls; forcing re-arm (HCCHAR=0x{:08x} HCINT=0x{:08x})",
                    RX_IN_FLIGHT_POLLS,
                    hcchar_v,
                    ints
                );
            }
            RX_IN_FLIGHT_POLLS = 0;
            RX_IN_FLIGHT = false;
            if (ints & (1 << 0)) != 0 {
                // XferCompl
                // 【2026-08-05】ここは `hc_tsiz(3)` を 2 回読んでいた
                // （残バイト数と、下の Data Toggle 引き継ぎ用 PID）。
                // MMIO は QEMU では 1 回ごとにトラップするため、
                // 収穫したフレームの数だけ無駄な往復が発生していた
                // （実測でフレームは 1 ブートあたり 13000 以上）。
                // 同じレジスタなので 1 回読んで使い回す。
                let tsiz = core::ptr::read_volatile(hc_tsiz(3));
                let remaining = tsiz & 0x7FFFF;
                let recv_len = (RX_LEN - remaining) as usize;

                // ハードウェアが管理する Data Toggle を読み出して次回の IN トークンへ
                // 引き継ぐ。
                //
                // 【2026-07-26 重大バグ修正】この更新は以前 `if recv_len > 0` の
                // **内側**にあった。USB のバルク転送では、デバイスが転送の区切りとして
                // **ゼロ長パケット(ZLP)** を返すことがあり、その場合 XferCompl は立つが
                // `recv_len == 0` になる。すると Data Toggle が更新されないまま次の IN
                // トークンを**古い PID** で発行してしまう。デバイス側は既にトグルを
                // 進めているため PID が不一致となり、以後こちらの IN はすべて噛み合わず
                // **受信が恒久的に停止する**。
                // これは本セッションで繰り返し観測した「送信は成功するのに、ある回数を
                // 境に SYN-ACK も DNS 応答も一切届かなくなる（接続の通し番号 ordinal が
                // 進むほど失敗する）」という症状を説明しうる。
                // 完了した転送では長さに関わらず必ずトグルを引き継ぐ。
                let next_pid = (tsiz >> 29) & 3;
                // PID → トグルの変換も検証済みモジュールへ（`usb_toggle.rs`）。
                ETH_BULK_IN_TOGGLE = crate::kernel::usb_toggle::toggle_from_pid(next_pid);

                if recv_len > 0 {
                    crate::kernel::mmu::invalidate_dcache_range(
                        (&RX_DMA_BUF as *const DmaBuffer) as usize,
                        recv_len,
                    );

                    if st.usb_eth_is_rndis {
                        if recv_len >= 44 {
                            let msg = core::ptr::read_unaligned(
                                RX_DMA_BUF.data.as_ptr() as *const RndisPacketMsg
                            );
                            // 【2026-07-29】範囲計算は検証済みモジュールへ一本化
                            // （`kernel/usb_rndis.rs`、単体試験 12 件）。
                            // DataOffset は offset 8 からの相対値で、`+8` を忘れる誤りや
                            // 加算オーバーフロー、短すぎるフレームの素通しを型で防ぐ。
                            let range = crate::kernel::usb_rndis::rndis_frame_range(
                                recv_len,
                                msg.message_type,
                                msg.data_offset,
                                msg.data_length,
                            );
                            if let Ok((abs_offset, frame_end)) = range {
                                // 【2026-08-05 計測済み】1 転送に 2 個目以降の RNDIS
                                // メッセージが入っていた回数を数えたところ **0 件**だった
                                // （13968 フレーム中）。QEMU の usb-net はバッチ送信しない。
                                // → 先頭 1 個しか見ていなくても**取りこぼしは無い**。
                                // → `RX_LEN` を増やして 1 転送に複数詰める案も効果が無い。
                                let data_len = frame_end - abs_offset;
                                if true {
                                    let eth_frame =
                                        &RX_DMA_BUF.data[abs_offset..abs_offset + data_len];
                                    if eth_frame.len() >= 14 {
                                        crate::debug!(
                                            "[USB] NET: USB IN received {} bytes (RNDIS)",
                                            eth_frame.len()
                                        );
                                        RX_FRAME_COUNT.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
                                        let _ = net::ingest_nic_ethernet_frame(eth_frame);
                                    }
                                }
                            }
                        }
                    } else if recv_len >= 14 {
                        crate::debug!("[USB] NET: USB IN received {} bytes (CDC-ECM)", recv_len);
                        // 【2026-07-29診断】連続取得で 2 回目以降が失敗する件。
                        // そもそもフレームが届いているのかを数える。
                        RX_FRAME_COUNT.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
                        let _ = net::ingest_nic_ethernet_frame(&RX_DMA_BUF.data[..recv_len]);
                    }
                }
            }
            // XferCompl 以外（STALL / XactErr / DataToggleErr 等）で停止した場合。
            //
            // 【2026-07-26診断】現状はここで何もせず、**同じ Data Toggle のまま**
            // 次の IN を再発行している。もし停止要因が Data Toggle Error(DTERR,
            // bit10) や Transaction Error(XactErr, bit7) であれば、同じ条件で再試行
            // し続けることになり **受信が恒久的に停止する**。本セッションで繰り返し
            // 観測している「送信は成功し続けるのに、ある時点から SYN-ACK も DNS 応答も
            // 一切届かなくなる」症状と整合する。まず実際にどのビットで停止して
            // いるのかを計測する（憶測で回復処理を入れる前に事実を取る）。
            // NAK は正常応答なので異常カウンタを回さない（実測で 21504 回
            // 誤記録していた）。判定は `usb_rx_state::decide` に一本化済み。
            else if action != crate::kernel::usb_rx_state::RxAction::Rearm {
                RX_ABNORMAL_HALTS = RX_ABNORMAL_HALTS.saturating_add(1);
                if RX_ABNORMAL_HALTS <= 8 || RX_ABNORMAL_HALTS.is_multiple_of(64) {
                    crate::warn!(
                        "[USB][DIAG] RX halted without XferCompl: HCINT=0x{:08x} (STALL={} XactErr={} DTERR={} BblErr={} FrmOvrun={}) count={}",
                        ints,
                        (ints >> 3) & 1,
                        (ints >> 7) & 1,
                        (ints >> 10) & 1,
                        (ints >> 8) & 1,
                        (ints >> 9) & 1,
                        RX_ABNORMAL_HALTS
                    );
                }
            }
        }

        if !RX_IN_FLIGHT {
            // 新しい IN 転送をノンブロッキングで発行（完了は待たない）
            let buf_phys = &RX_DMA_BUF as *const DmaBuffer as u32;
            crate::kernel::mmu::invalidate_dcache_range(buf_phys as usize, RX_LEN as usize);
            let pid = crate::kernel::usb_toggle::pid_from_toggle(ETH_BULK_IN_TOGGLE);
            core::ptr::write_volatile(hc_int(3), 0x7FF); // 割り込みクリア
            let mps = st.usb_eth_mps as u32;
            let packet_count = RX_LEN.div_ceil(mps);
            let mut tsiz = RX_LEN & 0x7FFFF;
            tsiz |= packet_count << 19;
            tsiz |= pid << 29;
            core::ptr::write_volatile(hc_tsiz(3), tsiz);
            core::ptr::write_volatile(hc_dma(3), buf_phys);
            let mut hcchar_v = mps & 0x7FF;
            hcchar_v |= ((st.usb_eth_bulk_in as u32) & 0xF) << 11;
            hcchar_v |= 1 << 15; // EPDir = IN
            hcchar_v |= 2 << 18; // EPType = Bulk
            hcchar_v |= 3 << 20; // MC/EC
            hcchar_v |= ((st.usb_eth_addr as u32) & 0x7F) << 22;
            hcchar_v |= 1 << 31; // ChEna
            core::ptr::write_volatile(hc_char(3), hcchar_v);
            RX_IN_FLIGHT = true;
        }

        harvest_budget -= 1;
        if harvest_budget == 0 {
            break;
        }
    } // loop
}

/// USB HID スキャンコードから PS/2 Set 1 スキャンコードへのマッピング
fn hid_to_ps2(hid_code: u8) -> Option<u8> {
    let ps2 = match hid_code {
        0x1E => 0x02, // 1
        0x1F => 0x03, // 2
        0x20 => 0x04, // 3
        0x21 => 0x05, // 4
        0x22 => 0x06, // 5
        0x23 => 0x07, // 6
        0x24 => 0x08, // 7
        0x25 => 0x09, // 8
        0x26 => 0x0A, // 9
        0x27 => 0x0B, // 0
        0x2D => 0x0C, // -
        0x2E => 0x0D, // = / ^
        0x2A => 0x0E, // Backspace
        0x2B => 0x0F, // Tab
        0x04 => 0x1E, // A
        0x05 => 0x30, // B
        0x06 => 0x2E, // C
        0x07 => 0x20, // D
        0x08 => 0x12, // E
        0x09 => 0x21, // F
        0x0A => 0x22, // G
        0x0B => 0x23, // H
        0x0C => 0x17, // I
        0x0D => 0x24, // J
        0x0E => 0x25, // K
        0x0F => 0x26, // L
        0x10 => 0x32, // M
        0x11 => 0x31, // N
        0x12 => 0x18, // O
        0x13 => 0x19, // P
        0x14 => 0x10, // Q
        0x15 => 0x13, // R
        0x16 => 0x1F, // S
        0x17 => 0x14, // T
        0x18 => 0x16, // U
        0x19 => 0x2F, // V
        0x1A => 0x11, // W
        0x1B => 0x2D, // X
        0x1C => 0x15, // Y
        0x1D => 0x2C, // Z
        0x2F => 0x1A, // [ / @
        0x30 => 0x1B, // ] / [
        0x2C => 0x39, // Space
        0x28 => 0x1C, // Enter
        0x33 => 0x27, // ; / +
        0x34 => 0x28, // ' / :
        0x35 => 0x29, // ` / Hankaku-Zenkaku
        0x31 => 0x2B, // \ / ]
        0x36 => 0x33, // ,
        0x37 => 0x34, // .
        0x38 => 0x35, // /
        0x64 => 0x73, // Non-US \ / |
        0x87 => 0x73, // JIS Ro
        0x88 => 0x70, // JIS Katakana/Hiragana
        0x89 => 0x7D, // JIS Yen
        0x8A => 0x79, // JIS Henkan
        0x8B => 0x7B, // JIS Muhenkan
        0x90 => 0x79, // Mac Kana (Lang1) -> Map to Henkan (0x79)
        0x91 => 0x7B, // Mac Eisu (Lang2) -> Map to Muhenkan (0x7B)
        0x52 => 0x48, // Up Arrow
        0x51 => 0x50, // Down Arrow
        0x50 => 0x4B, // Left Arrow
        0x4F => 0x4D, // Right Arrow
        0x4C => 0x53, // Delete Forward
        0x4A => 0x47, // Home
        0x4D => 0x4F, // End
        0x4B => 0x49, // Page Up
        0x4E => 0x51, // Page Down
        0x29 => 0x01, // Esc
        0x3A => 0x3B, // F1
        0x3B => 0x3C, // F2
        0x3C => 0x3D, // F3
        0x3D => 0x3E, // F4
        0x3E => 0x3F, // F5
        0x3F => 0x40, // F6
        0x40 => 0x41, // F7
        0x41 => 0x42, // F8
        0x42 => 0x43, // F9
        0x43 => 0x44, // F10
        0x44 => 0x57, // F11
        0x45 => 0x58, // F12
        _ => return None,
    };
    Some(ps2)
}

// =====================================================================================
// DWC2 スプリットトランザクション用フレームスケジューラ
// =====================================================================================
//
// HS ホスト(DWC2)が HS ハブ(RPi3B+ 内蔵 LAN9514)の背後にぶら下がる FS/LS デバイス
// （実機のキーボード/マウス）と通信するには、Start-Split / Complete-Split の2段階
// トランザクションを正しい (マイクロ)フレームに配置し、NYET/NAK 時に決められた
// ポリシーで再試行する必要がある。その時間規律を司るのがフレームスケジューラ。
//
// アルゴリズムは uspi (rsta2/uspi, GPLv3) の dwhciframesched{nsplit,nper,per}.c を
// 「参照」し、USB 2.0 spec §11.18 のスプリットスケジューリング規則に基づいて
// 自前 Rust で機能等価に再実装したもの（逐語移植・コードコピーではない）。
//
// 設計: 非ブロッキングのフレーム駆動ステートマシン。状態遷移ロジック（バグの出やすい
// 部分）は純粋関数なので frame_sched::selftest() で QEMU/ホスト検証できる。
// wait_for_frame だけが実 HFNUM レジスタを参照する（実機タイミング依存）。
pub mod frame_sched {
    // チャネル割り込みステータスビット（HCINT と共通）
    const INT_XFER_COMPLETE: u32 = 1 << 0;
    const INT_NAK: u32 = 1 << 4;
    const INT_ACK: u32 = 1 << 5;
    const INT_NYET: u32 = 1 << 6;
    const INT_XACT_ERR: u32 = 1 << 7;

    /// CSPLIT NAK による SSPLIT やり直しの上限。complete_split() がサイクル毎に
    /// tries をリセットするため、これがないと外側のタイムアウト (1秒) まで
    /// リトライし続けてしまう。上限到達で失敗を返し、上位層 (コントロール転送の
    /// SETUP からのやり直し) に回復を委ねる。
    const MAX_NAK_RESTARTS: u32 = 64;

    const UFRAME_US: u64 = 125; // 1 マイクロフレーム = 125us
    const MAX_FRAME_NUMBER: u32 = 0x3FFF;
    const NPER_FRAME_UNSET: u32 = MAX_FRAME_NUMBER + 1; // NoSplit 用センチネル
    const PER_FRAME_UNSET: u32 = 8; // Periodic 用センチネル（マイクロフレーム 0..7 の範囲外）

    /// HFNUM レジスタからフレーム番号フィールド (下位16bit) を読む。
    #[inline]
    fn frame_number() -> u32 {
        unsafe { core::ptr::read_volatile(super::HFNUM) & 0xFFFF }
    }

    /// 実時間マイクロ秒ウェイト（cntpct_el0 ベース、割り込み非依存）。
    fn udelay(us: u64) {
        let start = crate::kernel::timer::get_system_time_us();
        while crate::kernel::timer::get_system_time_us().wrapping_sub(start) < us {
            unsafe { core::arch::asm!("nop") };
        }
    }

    #[derive(Clone, Copy, PartialEq, Eq, Debug)]
    pub enum State {
        StartSplit,
        StartSplitComplete,
        CompleteSplit,
        CompleteRetry,
        CompleteSplitComplete,
        CompleteSplitFailed,
        Unknown,
    }

    #[derive(Clone, Copy, PartialEq, Eq)]
    enum Kind {
        /// 非スプリット（HS デバイス直結。SSPLIT/CSPLIT を使わない）
        NoSplit { is_periodic: bool },
        /// スプリット・非ピリオディック（FS/LS の control/bulk）
        NonPeriodic,
        /// スプリット・ピリオディック（FS/LS の interrupt/iso）
        Periodic,
    }

    /// 1 トランザクション分のフレームスケジューラ状態。
    pub struct FrameScheduler {
        kind: Kind,
        pub state: State,
        tries: i32,
        next_frame: u32,
        /// CSPLIT が NAK を受けて SSPLIT からやり直した回数（診断用）。
        pub nak_restarts: u32,
        /// XactErr (バス転送エラー) の残りリトライ回数。tries と違い NAK 再開で
        /// リセットされない、サイクル全体を通した予算。
        xacterr_budget: i32,
    }

    impl FrameScheduler {
        pub fn new_no_split(is_periodic: bool) -> Self {
            Self {
                kind: Kind::NoSplit { is_periodic },
                state: State::Unknown,
                tries: 0,
                next_frame: NPER_FRAME_UNSET,
                nak_restarts: 0,
                xacterr_budget: 3,
            }
        }
        pub fn new_non_periodic() -> Self {
            Self {
                kind: Kind::NonPeriodic,
                state: State::Unknown,
                tries: 0,
                next_frame: NPER_FRAME_UNSET,
                nak_restarts: 0,
                xacterr_budget: 3,
            }
        }
        pub fn new_periodic() -> Self {
            Self {
                kind: Kind::Periodic,
                state: State::Unknown,
                tries: 0,
                next_frame: PER_FRAME_UNSET,
                nak_restarts: 0,
                xacterr_budget: 3,
            }
        }

        /// この転送がスプリットを使うか（NoSplit なら false）。
        pub fn is_split(&self) -> bool {
            !matches!(self.kind, Kind::NoSplit { .. })
        }
        /// スプリットサイクルが成功完了したか。
        pub fn is_complete(&self) -> bool {
            self.state == State::CompleteSplitComplete
        }
        /// スプリットサイクルが失敗終了したか。
        pub fn is_failed(&self) -> bool {
            self.state == State::CompleteSplitFailed
        }

        /// 新しい Start-Split サイクルを開始する。
        pub fn start_split(&mut self) {
            match self.kind {
                Kind::NoSplit { .. } => {} // 非スプリットでは呼ばれない（呼ばれても無害）
                Kind::NonPeriodic => {
                    self.state = State::StartSplit;
                }
                Kind::Periodic => {
                    self.state = State::StartSplit;
                    self.next_frame = PER_FRAME_UNSET;
                }
            }
        }

        /// Complete-Split を今発行すべきか返す。false なら CSPLIT は出さない（完了/失敗 or 待機）。
        pub fn complete_split(&mut self) -> bool {
            match self.kind {
                Kind::NoSplit { .. } => false,
                Kind::NonPeriodic => match self.state {
                    State::StartSplitComplete => {
                        // USB 2.0 spec §11.18.2.2:
                        // SSPLIT ACK 後、最初の CSPLIT を発行するまでに FS デバイスが
                        // ダウンストリームバスでトランザクションを完了するのを待つ。
                        // FS: ~1bit time × 8bit × max_packet + ターンアラウンド。
                        // 安全マージンを含め 3 マイクロフレーム (375μs) 待機する。
                        // この wait がないと TT が「まだ完了していない」として NAK を返す。
                        udelay(3 * UFRAME_US);
                        self.state = State::CompleteSplit;
                        self.tries = 3;
                        true
                    }
                    State::CompleteSplit | State::CompleteRetry => {
                        udelay(5 * UFRAME_US);
                        true
                    }
                    _ => false, // CompleteSplitComplete / Failed / その他
                },
                Kind::Periodic => match self.state {
                    State::StartSplitComplete => {
                        self.state = State::CompleteSplit;
                        self.tries = if self.next_frame != 5 { 3 } else { 2 };
                        self.next_frame = (self.next_frame + 2) & 7;
                        true
                    }
                    State::CompleteRetry => {
                        self.next_frame = (self.next_frame + 1) & 7;
                        true
                    }
                    _ => false,
                },
            }
        }

        /// 直前トランザクションのチャネル割り込みステータスを与えて状態を進める。
        pub fn transaction_complete(&mut self, status: u32) {
            match self.kind {
                Kind::NoSplit { .. } => {}
                Kind::NonPeriodic => match self.state {
                    State::StartSplit => self.state = State::StartSplitComplete,
                    State::CompleteSplit | State::CompleteRetry => {
                        if status & INT_XFER_COMPLETE != 0 {
                            self.state = State::CompleteSplitComplete;
                        } else if status & (INT_NYET | INT_ACK) != 0 {
                            if status & INT_NYET != 0 {
                                self.state = State::CompleteRetry;
                            } else {
                                if self.tries == 0 {
                                    self.state = State::CompleteSplitFailed;
                                } else {
                                    self.tries -= 1;
                                    self.state = State::CompleteRetry;
                                }
                            }
                        } else if status & INT_NAK != 0 {
                            // USB 2.0 spec §11.18: Complete-Split が NAK を受けたら、
                            // それは「ハブが完了トランザクションを保持していない」ことを意味する。
                            // CSPLIT を単純に再送するのではなく、Start-Split からサイクル全体を
                            // やり直さなければならない。(Linux dwc2 ドライバも同様に
                            // complete_split フラグをクリアして SSPLIT からリトライする)
                            if self.tries == 0 || self.nak_restarts >= MAX_NAK_RESTARTS {
                                udelay(5 * UFRAME_US);
                                self.state = State::CompleteSplitFailed;
                            } else {
                                self.tries -= 1;
                                self.state = State::StartSplit;
                                self.nak_restarts += 1;
                            }
                        } else {
                            // XactErr 等のバス転送エラー。実機の TT 経由通信では単発の
                            // バスエラーが起こり得るため、Linux dwc2 ドライバ同様に
                            // 数回は SSPLIT からやり直す。予算 (xacterr_budget) を
                            // 使い切ったら諦める。
                            if self.xacterr_budget <= 0 {
                                self.state = State::CompleteSplitFailed;
                            } else {
                                self.xacterr_budget -= 1;
                                self.state = State::StartSplit;
                                self.nak_restarts += 1;
                            }
                        }
                    }
                    _ => {}
                },
                Kind::Periodic => match self.state {
                    State::StartSplit => self.state = State::StartSplitComplete,
                    State::CompleteSplit | State::CompleteRetry => {
                        if status & INT_XFER_COMPLETE != 0 {
                            self.state = State::CompleteSplitComplete;
                        } else if status & (INT_NYET | INT_ACK) != 0 {
                            if status & INT_NYET != 0 {
                                self.state = State::CompleteRetry;
                            } else {
                                if self.tries == 0 {
                                    self.state = State::CompleteSplitFailed;
                                    udelay(8 * UFRAME_US);
                                } else {
                                    self.tries -= 1;
                                    self.state = State::CompleteRetry;
                                }
                            }
                        } else if status & INT_NAK != 0 {
                            udelay(5 * UFRAME_US);
                            self.state = State::CompleteSplitFailed;
                        } else {
                            self.state = State::CompleteSplitFailed;
                        }
                    }
                    _ => {}
                },
            }
        }

        /// Start-Split を発行する正しいフレームまで待つ（実 HFNUM 参照）。
        pub fn wait_for_frame(&mut self) {
            match self.kind {
                Kind::NoSplit { is_periodic } => {
                    self.next_frame = (frame_number() + 1) & MAX_FRAME_NUMBER;
                    if !is_periodic {
                        while (frame_number() & MAX_FRAME_NUMBER) != self.next_frame {
                            unsafe {
                                core::arch::asm!("dsb sy", "isb", options(nostack));
                            }
                        }
                    }
                }
                Kind::NonPeriodic => {} // 任意フレームで SSPLIT 可
                Kind::Periodic => {
                    if self.next_frame == PER_FRAME_UNSET {
                        self.next_frame = (frame_number() + 1) & 7;
                        if self.next_frame == 6 {
                            self.next_frame += 1; // 6 は避ける（→7）
                        }
                    }
                    while (frame_number() & 7) != self.next_frame {
                        unsafe {
                            core::arch::asm!("dsb sy", "isb", options(nostack));
                        }
                    }
                }
            }
        }

        /// HCCHAR の Odd-Frame ビットに設定すべき値。
        pub fn is_odd_frame(&self) -> bool {
            match self.kind {
                Kind::NoSplit { .. } | Kind::Periodic => self.next_frame & 1 != 0,
                Kind::NonPeriodic => false,
            }
        }
    }

    /// 状態遷移ロジックのセルフテスト（実機タイミング非依存の純粋部分のみ）。
    /// main.rs のブート時セルフテスト群から呼ばれ "USBSCHED_SELFTEST: PASS x/y" を出す。
    pub fn selftest() -> (usize, usize) {
        let mut pass = 0usize;
        let mut total = 0usize;
        macro_rules! check {
            ($cond:expr) => {{
                total += 1;
                if $cond {
                    pass += 1;
                }
            }};
        }

        // --- NonPeriodic: 正常系 (SSPLIT ACK → CSPLIT → XFER_COMPLETE) ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            check!(s.is_split());
            s.start_split();
            s.transaction_complete(INT_ACK); // SSPLIT が ACK
            check!(s.complete_split()); // → CSPLIT を発行
            s.transaction_complete(INT_XFER_COMPLETE); // CSPLIT 完了
            check!(s.is_complete());
            check!(!s.complete_split()); // もう CSPLIT は出さない
            check!(!s.is_failed());
        }

        // --- NonPeriodic: NYET では tries を消費せずリトライを継続すること ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            s.start_split();
            s.transaction_complete(INT_ACK);
            check!(s.complete_split()); // tries=3, CompleteSplit
            // NYET を 10 回与えてもリトライが継続し、失敗しない
            for _ in 0..10 {
                s.transaction_complete(INT_NYET);
                check!(s.complete_split());
                check!(!s.is_failed());
                check!(!s.is_complete());
            }
        }

        // --- NonPeriodic: CSPLIT が NAK を受けたら SSPLIT からやり直すこと ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            s.start_split();
            s.transaction_complete(INT_ACK); // SSPLIT ACK → StartSplitComplete
            check!(s.complete_split()); // → CompleteSplit (tries=3), CSPLIT 発行
            s.transaction_complete(INT_NAK); // CSPLIT が NAK → SSPLIT からやり直し
            check!(!s.is_failed());
            check!(!s.complete_split()); // state=StartSplit なので CSPLIT は出さない (SSPLIT を送る)
            s.transaction_complete(INT_ACK); // 2回目の SSPLIT が ACK
            check!(s.complete_split()); // → 再度 CSPLIT
            s.transaction_complete(INT_XFER_COMPLETE);
            check!(s.is_complete());
        }

        // --- NonPeriodic: NAK やり直しは有限回 (MAX_NAK_RESTARTS) で打ち切られること ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            s.start_split();
            let mut iters = 0u32;
            loop {
                s.transaction_complete(INT_ACK); // SSPLIT ACK
                if !s.complete_split() {
                    break; // 失敗確定なら CSPLIT を出さない
                }
                s.transaction_complete(INT_NAK); // CSPLIT が NAK
                if s.is_failed() {
                    break;
                }
                iters += 1;
                if iters > 1000 {
                    break; // 無限ループ防止 (テスト自体の失敗を意味する)
                }
            }
            check!(s.is_failed());
            check!((10..=MAX_NAK_RESTARTS + 1).contains(&iters));
        }

        // --- NonPeriodic: XactErr は予算内なら SSPLIT からやり直し、成功できること ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            s.start_split();
            s.transaction_complete(INT_ACK);
            check!(s.complete_split()); // → CompleteSplit, CSPLIT 発行
            s.transaction_complete(INT_XACT_ERR); // バスエラー → SSPLIT からやり直し
            check!(!s.is_failed());
            check!(!s.complete_split()); // state=StartSplit → SSPLIT を送る
            s.transaction_complete(INT_ACK);
            check!(s.complete_split());
            s.transaction_complete(INT_XFER_COMPLETE);
            check!(s.is_complete());
        }

        // --- NonPeriodic: XactErr が予算(3回)を使い切ったら失敗すること ---
        {
            let mut s = FrameScheduler::new_non_periodic();
            s.start_split();
            s.transaction_complete(INT_ACK);
            for _ in 0..4 {
                check!(!s.is_failed());
                check!(s.complete_split());
                s.transaction_complete(INT_XACT_ERR);
                s.transaction_complete(INT_ACK); // 次サイクルの SSPLIT ACK (StartSplit→StartSplitComplete)
            }
            check!(s.is_failed());
        }

        // --- Periodic: 正常系 ---
        {
            let mut s = FrameScheduler::new_periodic();
            check!(s.is_split());
            s.start_split();
            s.transaction_complete(INT_ACK); // SSPLIT ACK
            check!(s.complete_split()); // → CSPLIT
            s.transaction_complete(INT_XFER_COMPLETE);
            check!(s.is_complete());
        }

        // --- Periodic: NAK は即失敗 ---
        {
            let mut s = FrameScheduler::new_periodic();
            s.start_split();
            s.transaction_complete(INT_ACK);
            check!(s.complete_split());
            s.transaction_complete(INT_NAK); // NAK → 即失敗
            check!(s.is_failed());
        }

        // --- NoSplit: スプリットを使わない ---
        {
            let s = FrameScheduler::new_no_split(false);
            check!(!s.is_split());
        }

        (pass, total)
    }
}