atmos/kernel/

audio.rs

// audio.rs - AtmOS PWM Audio Driver & MML Playback Engine
#![allow(dead_code)]

extern crate alloc;
use crate::kernel::audio_stream_fmt::{pwm_range, PcmQueue, PWM_STREAM_CLOCK_HZ};
use crate::os_lib::mml::Note;
use alloc::vec::Vec;
use core::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use spin::Mutex;

const GPIO_BASE: usize = 0x3F20_0000;
const GPFSEL4: *mut u32 = (GPIO_BASE + 0x10) as *mut u32;

const CM_BASE: usize = 0x3F10_1000;
const CM_PWMCTL: *mut u32 = (CM_BASE + 0x10A0) as *mut u32;
const CM_PWMDIV: *mut u32 = (CM_BASE + 0x10A4) as *mut u32;

const PWM_BASE: usize = 0x3F20_C000;
const PWM_CTL: *mut u32 = PWM_BASE as *mut u32;
const PWM_STA: *mut u32 = (PWM_BASE + 0x04) as *mut u32;
const PWM_DMAC: *mut u32 = (PWM_BASE + 0x08) as *mut u32;
const PWM_RNG1: *mut u32 = (PWM_BASE + 0x10) as *mut u32;
const PWM_DAT1: *mut u32 = (PWM_BASE + 0x14) as *mut u32;
const PWM_FIF1: *mut u32 = (PWM_BASE + 0x18) as *mut u32;
const PWM_RNG2: *mut u32 = (PWM_BASE + 0x20) as *mut u32;
const PWM_DAT2: *mut u32 = (PWM_BASE + 0x24) as *mut u32;

// I2S (HDMI Audio Output Destination) Registers
const I2S_BASE: usize = 0x3F20_3000;
const I2S_CS: *mut u32 = I2S_BASE as *mut u32;
const I2S_FIFO: *mut u32 = (I2S_BASE + 0x04) as *mut u32;
const I2S_MODE: *mut u32 = (I2S_BASE + 0x08) as *mut u32;
const I2S_RXC: *mut u32 = (I2S_BASE + 0x0C) as *mut u32;
const I2S_TXC: *mut u32 = (I2S_BASE + 0x10) as *mut u32;
const I2S_DREQ: *mut u32 = (I2S_BASE + 0x14) as *mut u32;

// DMA 3 (for PWM) and DMA 4 (for I2S) Registers
const DMA3_BASE: usize = 0x3F00_7300;
const DMA3_CS: *mut u32 = DMA3_BASE as *mut u32;
const DMA3_CONBLK_AD: *mut u32 = (DMA3_BASE + 0x04) as *mut u32;

const DMA4_BASE: usize = 0x3F00_7400;
const DMA4_CS: *mut u32 = DMA4_BASE as *mut u32;
const DMA4_CONBLK_AD: *mut u32 = (DMA4_BASE + 0x04) as *mut u32;

// PWM CLOCK: 19.2MHz / 16 = 1.2MHz (1,200,000 Hz)
const PWM_CLOCK_FREQ: u32 = 1_200_000;

// 非同期演奏用グローバルステート
static PLAY_QUEUE: Mutex<Vec<Note>> = Mutex::new(Vec::new());
static PLAY_INDEX: Mutex<usize> = Mutex::new(0);
static IS_PLAYING: Mutex<bool> = Mutex::new(false);
static THREAD_STARTED: Mutex<bool> = Mutex::new(false);

// PCMバッファと再生用静的領域
static mut PCM_BUFFER_PWM: [u8; 65536] = [0; 65536];
static mut PCM_BUFFER_I2S: [i16; 65536] = [0; 65536];
static mut DMA_CB_PWM: crate::kernel::dma::DmaControlBlock = crate::kernel::dma::DmaControlBlock {
    ti: 0,
    source_ad: 0,
    dest_ad: 0,
    txfr_len: 0,
    stride: 0,
    nextconbk: 0,
    _reserved: [0; 2],
};
static mut DMA_CB_I2S: crate::kernel::dma::DmaControlBlock = crate::kernel::dma::DmaControlBlock {
    ti: 0,
    source_ad: 0,
    dest_ad: 0,
    txfr_len: 0,
    stride: 0,
    nextconbk: 0,
    _reserved: [0; 2],
};

pub struct Audio;

impl Audio {
    /// PWMおよびGPIO40/45の初期化処理、I2S(HDMI)の初期化、DMAの設定を行います
    pub fn init() {
        unsafe {
            // 1. GPIO40 (PWM0) / GPIO45 (PWM1) のオルタネート機能を ALT0 (100) に設定
            let mut val = core::ptr::read_volatile(GPFSEL4);
            val &= !0b111; // GPIO 40
            val |= 0b100; // ALT0 (PWM0)
            val &= !(0b111 << 15); // GPIO 45
            val |= 0b100 << 15; // ALT0 (PWM1)
            core::ptr::write_volatile(GPFSEL4, val);

            // 2. PWM クロックの初期化
            // 停止させて設定をクリーンにする
            core::ptr::write_volatile(CM_PWMCTL, 0x5A00_0000);
            for _ in 0..1000 {
                core::arch::asm!("nop");
            }

            // 分分周比 16 (19.2MHz / 16 = 1.2MHz)
            core::ptr::write_volatile(CM_PWMDIV, 0x5A00_0000 | (16 << 12));
            for _ in 0..1000 {
                core::arch::asm!("nop");
            }

            // クロックを起動 (ENAB=0x10, SRC=0x01: OSC 19.2MHz)
            core::ptr::write_volatile(CM_PWMCTL, 0x5A00_0010 | 0x01);
            for _ in 0..1000 {
                core::arch::asm!("nop");
            }

            // 3. PWM コントローラの初期化
            // 一度全体をクリア
            core::ptr::write_volatile(PWM_CTL, 0);
            for _ in 0..1000 {
                core::arch::asm!("nop");
            }

            // 周期の初期値を 1024 に
            core::ptr::write_volatile(PWM_RNG1, 1024);
            core::ptr::write_volatile(PWM_RNG2, 1024);

            // 出力データを 0 (Mute) に
            core::ptr::write_volatile(PWM_DAT1, 0);
            core::ptr::write_volatile(PWM_DAT2, 0);

            // Mark-Space Mode で両方のチャンネルを有効化
            core::ptr::write_volatile(PWM_CTL, (1 << 0) | (1 << 1) | (1 << 8) | (1 << 9));

            // 4. I2S (HDMI Audio) の初期化
            // I2Sクロックおよびレジスタの初期設定
            core::ptr::write_volatile(I2S_CS, 0); // Disable I2S first
            core::ptr::write_volatile(I2S_MODE, 0);
            // 16-bit stereo transmit control
            core::ptr::write_volatile(I2S_TXC, (1 << 30) | (1 << 29) | (8 << 16) | (1 << 15)); // CH1EN | CH1WEX | CH1POS
            core::ptr::write_volatile(I2S_DREQ, (8 << 24) | (8 << 8)); // TX DREQ, RX DREQ threshold
            core::ptr::write_volatile(I2S_CS, 1 << 2); // TX Enable

            // 5. DMA 3 / 4 のイネーブル
            // DMAコントロール全体のENABLEレジスタ (0x3F007FF0)
            let dma_en_ptr = 0x3F007FF0 as *mut u32;
            let current_en = core::ptr::read_volatile(dma_en_ptr);
            core::ptr::write_volatile(dma_en_ptr, current_en | (1 << 3) | (1 << 4));
            // Enable DMA 3 and 4
        }

        crate::info!(
            "[AUD] Hardware PWM (Analog) and I2S (HDMI) audio engines initialized successfully."
        );
    }

    /// 常駐再生スレッドを必要なら起動する（プロセス全体で一度だけ spawn される）。
    /// 以前は効果音ごとにスレッドを spawn→終了していたため、ESC 連打などで
    /// 頻繁なスレッド生成・破棄が起き、スタック確保/解放でヒープ破損を招いていた。
    /// Audio::init() は scheduler::init() より前に呼ばれるため、ここで遅延起動する。
    fn ensure_playback_thread() {
        let mut started = THREAD_STARTED.lock();
        if !*started {
            *started = true;
            // 【2026-08-25 バグ修正】`spawn` はヒープ不足で **0 を返す**。
            // `started` を先に立てているので、失敗したまま戻さないと
            // 「再生スレッドは居ないのに起動済み」になり、
            // **以後まったく音が鳴らなくなる**（再試行の機会が二度と来ない）。
            let pid = crate::kernel::scheduler::spawn(
                Self::playback_thread_entry,
                crate::kernel::scheduler::Priority::High,
                "mml_player",
            );
            if pid == 0 {
                crate::warn!("[AUDIO] 再生スレッドを起動できません（ヒープ不足）");
                *started = false;
            }
        }
    }

    /// 指定された周波数 (Hz) で自律発振を開始します (0 の場合は Mute)
    pub fn set_tone(freq: u32) {
        // 連続再生中は PWM を FIFO＋DMA で使っているので触らない。
        if STREAM_ACTIVE.load(Ordering::Acquire) {
            return;
        }
        if freq == 0 {
            Self::mute();
            return;
        }

        let rng = PWM_CLOCK_FREQ / freq;
        let dat = rng / 2; // デューティ比 50%

        unsafe {
            core::ptr::write_volatile(PWM_RNG1, rng);
            core::ptr::write_volatile(PWM_RNG2, rng);
            core::ptr::write_volatile(PWM_DAT1, dat);
            core::ptr::write_volatile(PWM_DAT2, dat);
        }
    }

    /// 音声を消音します
    pub fn mute() {
        if STREAM_ACTIVE.load(Ordering::Acquire) {
            return;
        }
        unsafe {
            core::ptr::write_volatile(PWM_DAT1, 0);
            core::ptr::write_volatile(PWM_DAT2, 0);
        }
    }

    /// MML 文字列をバックグラウンド（ノンブロッキング）で演奏開始します
    pub fn play_mml(mml_str: &str) {
        let notes = crate::os_lib::mml::parse_mml(mml_str);
        if notes.is_empty() {
            return;
        }

        Self::ensure_playback_thread();
        {
            let mut queue = PLAY_QUEUE.lock();
            let mut idx = PLAY_INDEX.lock();
            let mut playing = IS_PLAYING.lock();

            // 常駐再生スレッドにキューを渡すだけ（スレッドは spawn しない）
            *queue = notes;
            *idx = 0;
            *playing = true;
        }
    }

    /// 現在MMLを演奏中かどうかを判定します
    pub fn is_playing() -> bool {
        *IS_PLAYING.lock()
    }

    /// MML演奏を強制停止します
    pub fn stop_mml() {
        let mut queue = PLAY_QUEUE.lock();
        let mut idx = PLAY_INDEX.lock();
        queue.clear();
        *idx = 0;
        Self::mute();
    }

    /// 単音をバックグラウンド（ノンブロッキング）で指定ミリ秒間演奏します
    pub fn play_tone_async(freq: u32, duration_ms: u32) {
        let notes = alloc::vec![Note { freq, duration_ms }];

        Self::ensure_playback_thread();
        {
            let mut queue = PLAY_QUEUE.lock();
            let mut idx = PLAY_INDEX.lock();
            let mut playing = IS_PLAYING.lock();

            // 常駐再生スレッドにキューを渡すだけ（スレッドは spawn しない）
            *queue = notes;
            *idx = 0;
            *playing = true;
        }
    }

    /// 再生スレッドの実行エントリポイント
    fn playback_thread_entry() {
        loop {
            let note_opt = {
                let mut queue = PLAY_QUEUE.lock();
                let mut idx = PLAY_INDEX.lock();
                if *idx < queue.len() {
                    let note = queue[*idx];
                    *idx += 1;
                    Some(note)
                } else {
                    // 全ての音符の再生が終了
                    queue.clear();
                    *idx = 0;
                    let mut playing = IS_PLAYING.lock();
                    *playing = false;
                    None
                }
            };

            if let Some(note) = note_opt {
                if note.freq == 0 {
                    Self::mute();
                } else {
                    Self::set_tone(note.freq);
                }

                // tick 単位 (10ms) に変換
                let ticks = (note.duration_ms / 10) as usize;
                if ticks > 0 {
                    crate::kernel::scheduler::sleep(ticks);
                } else {
                    crate::kernel::scheduler::sleep(1);
                }

                // 同音の連続を綺麗に分離するため、一瞬消音する (10ms)
                Self::mute();
                crate::kernel::scheduler::sleep(1);
            } else {
                // キューが空の間はアイドル待機（スレッドは終了せず常駐し続ける）
                crate::kernel::scheduler::sleep(2);
            }
        }
    }

    /// デコードされた 16-bit PCM ステレオ音声データを、HDMI (I2S) と PWM (イヤホンジャック) に供給してDMA再生します
    pub fn play_pcm_stream(pcm_data: &[i16]) {
        if pcm_data.is_empty() {
            return;
        }

        unsafe {
            // 静的バッファサイズに合わせてコピー（サイズ上限 65536）
            let len = pcm_data.len().min(65536);

            // 1. HDMI (I2S) 用バッファの構築
            core::ptr::copy_nonoverlapping(pcm_data.as_ptr(), PCM_BUFFER_I2S.as_mut_ptr(), len);

            // 2. PWM (アナログ) 用バッファの構築 (16-bit ステレオ -> 8-bit モノラル/ステレオ変換)
            for i in 0..len {
                // -32768..32767 を 0..255 にマッピング
                let sample_8 = (((pcm_data[i] as i32 + 32768) >> 8) & 0xFF) as u8;
                // PWMの出力範囲 (RNG=1024) に合わせてスケーリング (0..255 を 0..1023 へ)
                PCM_BUFFER_PWM[i] = ((sample_8 as u32 * 4).min(1023)) as u8;
            }

            // 3. DMA コントロールブロックの設定 (キャッシュクリーン)
            let pwm_buf_ptr = PCM_BUFFER_PWM.as_ptr() as usize;
            let i2s_buf_ptr = PCM_BUFFER_I2S.as_ptr() as usize;

            crate::kernel::mmu::clean_dcache_range(pwm_buf_ptr, len);
            crate::kernel::mmu::clean_dcache_range(i2s_buf_ptr, len * 2);

            // 4. DMA 3 (PWM) 転送ブロックの構築
            DMA_CB_PWM = crate::kernel::dma::DmaControlBlock {
                ti: (5 << 16) | (1 << 8) | (1 << 4) | (1 << 3), // PERMAP=5 (PWM), SRC_INC, DEST_DREQ, WAIT_RESP
                source_ad: crate::kernel::dma::to_bus_address(pwm_buf_ptr as u32),
                dest_ad: crate::kernel::dma::to_bus_address(PWM_FIF1 as u32),
                txfr_len: len as u32,
                stride: 0,
                nextconbk: 0,
                _reserved: [0; 2],
            };
            crate::kernel::mmu::clean_dcache_range(
                &DMA_CB_PWM as *const _ as usize,
                core::mem::size_of::<crate::kernel::dma::DmaControlBlock>(),
            );

            // 5. DMA 4 (I2S / HDMI) 転送ブロックの構築
            DMA_CB_I2S = crate::kernel::dma::DmaControlBlock {
                ti: (6 << 16) | (1 << 8) | (1 << 4) | (1 << 3), // PERMAP=6 (I2S), SRC_INC, DEST_DREQ, WAIT_RESP
                source_ad: crate::kernel::dma::to_bus_address(i2s_buf_ptr as u32),
                dest_ad: crate::kernel::dma::to_bus_address(I2S_FIFO as u32),
                txfr_len: (len * 2) as u32,
                stride: 0,
                nextconbk: 0,
                _reserved: [0; 2],
            };
            crate::kernel::mmu::clean_dcache_range(
                &DMA_CB_I2S as *const _ as usize,
                core::mem::size_of::<crate::kernel::dma::DmaControlBlock>(),
            );

            if !crate::kernel::dma::is_qemu_env() {
                // 実機の場合: DMAレジスタを設定して転送開始
                // DMA 3 (PWM)
                core::ptr::write_volatile(
                    DMA3_CONBLK_AD,
                    crate::kernel::dma::to_bus_address(&DMA_CB_PWM as *const _ as *const _ as u32),
                );
                core::ptr::write_volatile(DMA3_CS, (1 << 0) | (8 << 16)); // ACTIVE | PRIORITY=8

                // DMA 4 (I2S / HDMI)
                core::ptr::write_volatile(
                    DMA4_CONBLK_AD,
                    crate::kernel::dma::to_bus_address(&DMA_CB_I2S as *const _ as *const _ as u32),
                );
                core::ptr::write_volatile(DMA4_CS, (1 << 0) | (8 << 16)); // ACTIVE | PRIORITY=8
            }
        }
    }
}

#[derive(Clone, Copy, Debug)]
pub enum SeType {
    Apply,  // 設定適用時のきらびやかなチャイム
    Save,   // 保存時の安心なピピッという完了音
    Delete, // 削除時の少し低めのドシュッという音
    Close,  // ウィンドウを閉じる時のフェード音
}

/// システム効果音を再生します。サウンド設定がOFFの場合は完全に静音化されます。
pub fn play_system_se(se: SeType) {
    // グローバルサウンド設定の確認
    if !crate::kernel::config::get_config().enable_sound {
        return;
    }

    let mml = match se {
        SeType::Apply => "T180 L16 O5 C E G",
        SeType::Save => "T240 L16 O5 G O6 C",
        SeType::Delete => "T150 L12 O4 C O3 G",
        SeType::Close => "T240 L16 O5 F D",
    };

    Audio::play_mml(mml);
}

// ============================================================================
// 連続再生（ストリーミング）: PWM の FIFO へ DMA のリング（2 面）で流し続ける
// ============================================================================
//
// 【2026-10-19】MSE（YouTube 等）の AAC を途切れずに鳴らすために新設。従来の
// `play_pcm_stream` は 65536 標本の一括転送で、しかも PWM の周期（約 1.2kHz）・FIFO/DMA の
// 有効化・DMA の TI（DEST_INC と DEST_DREQ の取り違え）・周辺機器のバスアドレス
// （0x3F→0x7E ではなく 0xC0 を OR していた）が誤っており、実際には鳴らなかった。
//
// 構成:
// - PWM のクロック = PLLD 500MHz / 2 = 250MHz、周期 RNG = 250MHz / 標本化周波数
//   （44.1kHz で 5669、約 12.5 ビット相当）。PWM 方式（MSEN=0）、両チャンネルとも FIFO（USEF）。
// - DMA チャンネル 5（ファームウェアが他で使わない範囲）。制御ブロック 2 つを互いに
//   `nextconbk` で指し合い、2 面のバッファを交互に PWM の FIFO へ送り続ける（DREQ 同期）。
// - 補給スレッドが、DMA が今どちらの面を読んでいるか（CONBLK_AD）を見て、読み終えた面を
//   待ち行列（`PcmQueue`）から埋め直す。待ち行列が空なら無音（周期の半分）。
// - QEMU（PWM・DMA を模擬しない）ではレジスタに触れず、補給スレッドが実時間で待ち行列を
//   消費するだけにする（生産側の流れを QEMU で確かめるため）。
//
// 実機での確認が前提（QEMU では音は出ない）。純粋な計算は `audio_stream_fmt.rs`（ホスト試験あり）。

const STREAM_DMA_CH: usize = 5;
const STREAM_DMA_BASE: usize = 0x3F00_7000 + STREAM_DMA_CH * 0x100;
const STREAM_DMA_CS: *mut u32 = STREAM_DMA_BASE as *mut u32;
const STREAM_DMA_CONBLK_AD: *mut u32 = (STREAM_DMA_BASE + 0x04) as *mut u32;
const DMA_ENABLE_REG: *mut u32 = 0x3F00_7FF0 as *mut u32;
/// PWM の FIFO の**バスアドレス**（DMA から見た周辺機器の番地。ARM の 0x3F20C018）。
const PWM_FIF1_BUS: u32 = 0x7E20_C018;
/// BCM2835 Clock Manager レジスタ書き込み保護マジック（データシート上の PASSWD=0x5A）
const CM_MAGIC: u32 = 0x5A00_0000;
/// 1 面あたりのフレーム数（44.1kHz で約 46ms）。
const STREAM_HALF_FRAMES: usize = 2048;
const STREAM_HALF_WORDS: usize = STREAM_HALF_FRAMES * 2;

#[repr(C, align(32))]
struct StreamBuf([u32; STREAM_HALF_WORDS * 2]);
static mut STREAM_BUF: StreamBuf = StreamBuf([0; STREAM_HALF_WORDS * 2]);
static mut STREAM_CBS: [crate::kernel::dma::DmaControlBlock; 2] = [crate::kernel::dma::DmaControlBlock {
    ti: 0,
    source_ad: 0,
    dest_ad: 0,
    txfr_len: 0,
    stride: 0,
    nextconbk: 0,
    _reserved: [0; 2],
}; 2];

static STREAM_QUEUE: Mutex<Option<PcmQueue>> = Mutex::new(None);
static STREAM_ACTIVE: AtomicBool = AtomicBool::new(false);
static STREAM_PAUSED: AtomicBool = AtomicBool::new(false);
static STREAM_RANGE: AtomicU32 = AtomicU32::new(0);
static FEEDER_RUNNING: AtomicBool = AtomicBool::new(false);

/// RAM の番地を DMA から見たバスアドレスへ（キャッシュを通らない 0xC0000000 の別名）。
fn ram_bus(addr: usize) -> u32 {
    (addr as u32) | 0xC000_0000
}

pub struct AudioStream;

impl AudioStream {
    /// 連続再生を始める（既に同じ形式で動いていれば何もしない）。
    pub fn start(sample_rate: u32, channels: u32) {
        if sample_rate == 0 {
            return;
        }
        {
            let mut q = STREAM_QUEUE.lock();
            if let Some(cur) = q.as_ref() {
                if STREAM_ACTIVE.load(Ordering::Acquire) && cur.sample_rate == sample_rate && cur.channels == channels.clamp(1, 2) {
                    return;
                }
            }
            *q = Some(PcmQueue::new(sample_rate, channels));
        }
        let range = pwm_range(PWM_STREAM_CLOCK_HZ, sample_rate);
        STREAM_RANGE.store(range, Ordering::Release);
        STREAM_PAUSED.store(false, Ordering::Release);
        // 鳴っている効果音（MML）を止めてから PWM を連続再生用に切り替える。
        Audio::stop_mml();
        STREAM_ACTIVE.store(true, Ordering::Release);
        if !crate::kernel::dma::is_qemu_env() {
            unsafe { Self::hw_start(range) };
        }
        if !FEEDER_RUNNING.swap(true, Ordering::AcqRel) {
            let pid = crate::kernel::scheduler::spawn(
                Self::feeder_thread,
                crate::kernel::scheduler::Priority::High,
                "audio_feeder",
            );
            if pid == 0 {
                crate::warn!("[AUDIO] 補給スレッドを起動できません（ヒープ不足）。連続再生を止めます");
                FEEDER_RUNNING.store(false, Ordering::Release);
                Self::stop();
                return;
            }
        }
        crate::warn!("[AUDIO] 連続再生開始 {}Hz {}ch range={}", sample_rate, channels, range);
    }

    /// 復号済みの PCM（交互配置）を足す。
    pub fn push(pcm: &[i16]) {
        if let Some(q) = STREAM_QUEUE.lock().as_mut() {
            q.push(pcm);
        }
    }

    /// 溜まっている時間 [ms]（連続再生していなければ 0）。
    pub fn buffered_ms() -> u64 {
        STREAM_QUEUE.lock().as_ref().map(|q| q.buffered_ms()).unwrap_or(0)
    }

    /// 一時停止（無音を流し、待ち行列は保つ）・再開。
    pub fn set_paused(paused: bool) {
        STREAM_PAUSED.store(paused, Ordering::Release);
    }

    /// 待ち行列を捨てる（シーク時）。
    pub fn flush() {
        if let Some(q) = STREAM_QUEUE.lock().as_mut() {
            q.clear();
        }
    }

    pub fn is_active() -> bool {
        STREAM_ACTIVE.load(Ordering::Acquire)
    }

    /// 連続再生を止め、PWM を効果音（単音）用の設定へ戻す。
    pub fn stop() {
        if !STREAM_ACTIVE.swap(false, Ordering::AcqRel) {
            return;
        }
        if !crate::kernel::dma::is_qemu_env() {
            unsafe {
                core::ptr::write_volatile(STREAM_DMA_CS, 1 << 31); // RESET（転送を止める）
                core::ptr::write_volatile(PWM_DMAC, 0);
                core::ptr::write_volatile(PWM_CTL, 0);
                Self::delay();
                Self::restore_tone_mode();
            }
        }
        *STREAM_QUEUE.lock() = None;
        crate::warn!("[AUDIO] 連続再生停止");
    }

    fn delay() {
        for _ in 0..2000 {
            core::hint::spin_loop();
        }
    }

    /// PWM のクロック（PLLD/2）・周期・FIFO・DREQ を設定し、DMA のリングを始める。
    unsafe fn hw_start(range: u32) {
        unsafe {
            // 動いている転送と PWM を止める。
            core::ptr::write_volatile(STREAM_DMA_CS, 1 << 31);
            core::ptr::write_volatile(PWM_DMAC, 0);
            core::ptr::write_volatile(PWM_CTL, 0);
            Self::delay();

            // クロック: 止めて BUSY が落ちるのを待ち、PLLD（SRC=6）/2 で起動。
            let ctl = core::ptr::read_volatile(CM_PWMCTL);
            core::ptr::write_volatile(CM_PWMCTL, CM_MAGIC | (ctl & !0x10));
            let mut guard = 0;
            while core::ptr::read_volatile(CM_PWMCTL) & 0x80 != 0 && guard < 100_000 {
                guard += 1;
                core::hint::spin_loop();
            }
            core::ptr::write_volatile(CM_PWMDIV, CM_MAGIC | (2 << 12));
            core::ptr::write_volatile(CM_PWMCTL, CM_MAGIC | 6);
            core::ptr::write_volatile(CM_PWMCTL, CM_MAGIC | 6 | 0x10);
            Self::delay();

            core::ptr::write_volatile(PWM_RNG1, range);
            core::ptr::write_volatile(PWM_RNG2, range);
            core::ptr::write_volatile(PWM_CTL, 1 << 6); // CLRF1（FIFO を空に）
            Self::delay();
            core::ptr::write_volatile(PWM_STA, 0x1FC); // 誤り表示（BERR・GAPO・RERR・WERR）を消す
            // DMA 要求: ENAB | PANIC=7 | DREQ=7
            core::ptr::write_volatile(PWM_DMAC, (1 << 31) | (7 << 8) | 7);
            // PWEN1 | USEF1 | PWEN2 | USEF2（PWM 方式。FIFO の語は ch1, ch2 の順に交互に使われる）
            core::ptr::write_volatile(PWM_CTL, (1 << 0) | (1 << 5) | (1 << 8) | (1 << 13));

            // 2 面のバッファを埋める（待ち行列が空なら無音）。
            Self::fill_half(0);
            Self::fill_half(1);

            // 制御ブロック 2 つを互いに指し合わせる。
            let cbs = core::ptr::addr_of_mut!(STREAM_CBS) as *mut crate::kernel::dma::DmaControlBlock;
            let buf = core::ptr::addr_of_mut!(STREAM_BUF.0) as *mut u32;
            for i in 0..2usize {
                let next = cbs.add(1 - i) as usize;
                *cbs.add(i) = crate::kernel::dma::DmaControlBlock {
                    // PERMAP=5（PWM）| SRC_INC | DEST_DREQ | WAIT_RESP
                    ti: (5 << 16) | (1 << 8) | (1 << 6) | (1 << 3),
                    source_ad: ram_bus(buf.add(i * STREAM_HALF_WORDS) as usize),
                    dest_ad: PWM_FIF1_BUS,
                    txfr_len: (STREAM_HALF_WORDS * 4) as u32,
                    stride: 0,
                    nextconbk: ram_bus(next),
                    _reserved: [0; 2],
                };
            }
            crate::kernel::mmu::clean_dcache_range(
                cbs as usize,
                2 * core::mem::size_of::<crate::kernel::dma::DmaControlBlock>(),
            );

            let en = core::ptr::read_volatile(DMA_ENABLE_REG);
            core::ptr::write_volatile(DMA_ENABLE_REG, en | (1 << STREAM_DMA_CH));
            core::ptr::write_volatile(STREAM_DMA_CONBLK_AD, ram_bus(cbs as usize));
            // ACTIVE | PRIORITY=8 | PANIC_PRIORITY=8
            core::ptr::write_volatile(STREAM_DMA_CS, (1 << 0) | (8 << 16) | (8 << 20));
        }
    }

    /// 面 `half`（0/1）を待ち行列から埋め、DMA から見えるようにキャッシュを書き出す。
    unsafe fn fill_half(half: usize) {
        let range = STREAM_RANGE.load(Ordering::Acquire);
        let buf = unsafe { core::ptr::addr_of_mut!(STREAM_BUF.0) as *mut u32 };
        let words = unsafe { core::slice::from_raw_parts_mut(buf.add(half * STREAM_HALF_WORDS), STREAM_HALF_WORDS) };
        if STREAM_PAUSED.load(Ordering::Acquire) {
            words.fill(range / 2);
        } else {
            match STREAM_QUEUE.lock().as_mut() {
                Some(q) => {
                    q.fill_words(words, range);
                }
                None => words.fill(range / 2),
            }
        }
        crate::kernel::mmu::clean_dcache_range(words.as_ptr() as usize, STREAM_HALF_WORDS * 4);
    }

    /// 補給スレッド: DMA が読み終えた面を埋め直す（QEMU では実時間で消費するだけ）。
    fn feeder_thread() {
        let qemu = crate::kernel::dma::is_qemu_env();
        let cb1_bus = unsafe { ram_bus((core::ptr::addr_of!(STREAM_CBS) as *const crate::kernel::dma::DmaControlBlock).add(1) as usize) };
        let mut last_half = 0usize;
        let mut last_ms = crate::kernel::timer::get_system_time_ms();
        while STREAM_ACTIVE.load(Ordering::Acquire) {
            if qemu {
                let now = crate::kernel::timer::get_system_time_ms();
                let dt = now.wrapping_sub(last_ms);
                last_ms = now;
                if !STREAM_PAUSED.load(Ordering::Acquire) {
                    if let Some(q) = STREAM_QUEUE.lock().as_mut() {
                        let frames = (q.sample_rate as u64 * dt / 1000) as usize;
                        q.drain_frames(frames);
                    }
                }
            } else {
                let cur = unsafe { core::ptr::read_volatile(STREAM_DMA_CONBLK_AD) };
                let half = if cur == cb1_bus { 1 } else { 0 };
                if half != last_half {
                    // DMA が次の面へ移った → 読み終えた面を埋め直す。
                    unsafe { Self::fill_half(last_half) };
                    last_half = half;
                }
            }
            crate::kernel::scheduler::sleep(1);
        }
        FEEDER_RUNNING.store(false, Ordering::Release);
        crate::kernel::scheduler::exit();
    }

    /// PWM を `init()` と同じ効果音（単音）用の設定へ戻す（OSC 19.2MHz / 16、M/S 方式）。
    unsafe fn restore_tone_mode() {
        unsafe {
            core::ptr::write_volatile(CM_PWMCTL, CM_MAGIC);
            Self::delay();
            core::ptr::write_volatile(CM_PWMDIV, CM_MAGIC | (16 << 12));
            Self::delay();
            core::ptr::write_volatile(CM_PWMCTL, CM_MAGIC | 0x10 | 0x01);
            Self::delay();
            core::ptr::write_volatile(PWM_RNG1, 1024);
            core::ptr::write_volatile(PWM_RNG2, 1024);
            core::ptr::write_volatile(PWM_DAT1, 0);
            core::ptr::write_volatile(PWM_DAT2, 0);
            core::ptr::write_volatile(PWM_CTL, (1 << 0) | (1 << 1) | (1 << 8) | (1 << 9));
        }
    }
}