psx_fmv/

mdec.rs

// SPDX-License-Identifier: GPL-2.0-or-later
//! MDEC driver: table upload, decode command, DMA0 in, DMA1 out.
//!
//! [`Mdec`] owns the two DMA channels that feed and drain the decoder; every
//! step that starts one is a method on it.
//!
//! Decode protocol, as commercial players drive it:
//!
//! 1. [`Mdec::reset`] once, then [`Mdec::load_tables`] (quantization + IDCT
//!    tables). Neither assumes the MDEC reacts at once: see "Reset latency"
//!    below.
//! 2. Per frame, [`Mdec::decode_start`] writes the decode command (output depth +
//!    run-length word count) to MDEC0 and kicks DMA0 with the whole
//!    run-length buffer. It does not wait: the MDEC throttles DMA0 as its
//!    output FIFO fills.
//! 3. [`Mdec::read_column`] pulls one 16-pixel-wide column of decoded
//!    macroblocks over DMA1 (macroblocks come out in the order the
//!    bitstream stores them: top to bottom, then left to right), which the
//!    caller uploads to VRAM.
//! 4. [`Mdec::decode_finish`] confirms DMA0 drained.
//!
//! Every wait is bounded (`psx_io::dma::wait_done`), and every kick aborts
//! the channel first, per the SDK rule for silicon DMA wedges.
//!
//! # Reset latency
//!
//! On a PAL SCPH-9002 the MDEC does not finish a reset within the next bus
//! access: the status read straight after writing the reset still shows the
//! state from before it (0x6401_0000: busy, data-in full), where the
//! SuperStation One FPGA and PSoXide already read the documented reset state.
//! Writing the DMA-request enable right behind the reset, as this driver used
//! to, left the table upload waiting on DMA0 forever on that console while
//! both of the others played the movie. So [`Mdec::reset`] waits for the reset to
//! settle before enabling requests, and [`Mdec::load_tables`] checks that the MDEC
//! actually raised its data-in request (status bit 28) after each command,
//! re-writing the enable if it did not, and falls back to CPU writes when
//! DMA0 still will not take the table.

use psx_hw::mdec::{self as hw, MDEC0, MDEC1};
use psx_io::dma::{self, Channel};
use psx_io::periph::MdecDma;

use crate::rle::{self, RleLengthError};

/// DMA block size the MDEC channels use, in words.
pub const DMA_BLOCK_WORDS: usize = crate::rle::BLOCK_WORDS;

/// Spin budget for one table upload or column transfer.
pub const DMA_SPINS: u32 = 400_000;

// CHCR: to device / from device, block sync, start.
const CHCR_IN: u32 =
    psx_hw::dma::CHCR_TO_DEVICE | psx_hw::dma::CHCR_SYNC_BLOCK | psx_hw::dma::CHCR_START;
const CHCR_OUT: u32 = psx_hw::dma::CHCR_SYNC_BLOCK | psx_hw::dma::CHCR_START;

/// Standard intra quantization matrix (row-major), DC entry 2.
const QUANT_ROW_MAJOR: [u8; 64] = [
    2, 16, 19, 22, 26, 27, 29, 34, //
    16, 16, 22, 24, 27, 29, 34, 37, //
    19, 22, 26, 27, 29, 34, 34, 38, //
    22, 22, 26, 27, 29, 34, 37, 40, //
    22, 26, 27, 29, 32, 35, 40, 48, //
    26, 27, 29, 32, 35, 40, 48, 58, //
    26, 27, 29, 34, 38, 46, 56, 69, //
    27, 29, 35, 38, 46, 56, 69, 83,
];

/// Zigzag position `i` to its row-major index.
const ZIGZAG_TO_ROW_MAJOR: [u8; 64] = [
    0, 1, 8, 16, 9, 2, 3, 10, 17, 24, 32, 25, 18, 11, 4, 5, //
    12, 19, 26, 33, 40, 48, 41, 34, 27, 20, 13, 6, 7, 14, 21, 28, //
    35, 42, 49, 56, 57, 50, 43, 36, 29, 22, 15, 23, 30, 37, 44, 51, //
    58, 59, 52, 45, 38, 31, 39, 46, 53, 60, 61, 54, 47, 55, 62, 63,
];

/// Luma then chroma table, zigzag order, as the 32 words command 2 takes.
pub static QUANT_WORDS: [u32; 32] = build_quant();

const fn build_quant() -> [u32; 32] {
    let mut bytes = [0u8; 128];
    let mut i = 0;
    while i < 64 {
        let q = QUANT_ROW_MAJOR[ZIGZAG_TO_ROW_MAJOR[i] as usize];
        bytes[i] = q;
        bytes[64 + i] = q;
        i += 1;
    }
    let mut words = [0u32; 32];
    let mut w = 0;
    while w < 32 {
        words[w] = u32::from_le_bytes([
            bytes[4 * w],
            bytes[4 * w + 1],
            bytes[4 * w + 2],
            bytes[4 * w + 3],
        ]);
        w += 1;
    }
    words
}

/// The IDCT matrix for MDEC command 3, generated from the DCT basis in
/// [`crate::idct`].
pub static SCALE_WORDS: [u32; 32] = crate::idct::MATRIX_WORDS;

// Register constants moved to psx-hw; these forward until games repin.

/// Spin budget for one status wait (reset settle, request, FIFO room).
/// The console settles a reset in tens of cycles; this is a few ms.
pub const SETTLE_SPINS: u32 = 20_000;
/// Status reads to spend after a reset looks settled. A reset from an idle
/// MDEC can read idle before it has finished, so waiting for busy to drop
/// is not enough on its own. Each read is an MMIO access, several cycles,
/// so this is a few hundred cycles against the tens a reset takes.
const RESET_TAIL_READS: u32 = 64;
/// Enable writes to try before giving up on the data-in request.
const ENABLE_ATTEMPTS: u8 = 4;

/// Raw MDEC1 status word.
#[inline(always)]
pub fn status() -> u32 {
    // SAFETY: MDEC status register read.
    unsafe { psx_io::read_u32(MDEC1) }
}

/// Wait until `status() & mask == want`. `false` on timeout.
fn wait_status(mask: u32, want: u32, spins: u32) -> bool {
    let mut n = 0;
    while status() & mask != want {
        if n >= spins {
            return false;
        }
        n += 1;
    }
    true
}

/// Send `blocks` 32-word blocks from `words` to the MDEC over DMA0 without
/// waiting.
///
/// # Safety
/// `blocks` must not be 0 (the controller reads 0 as 65,536 blocks), and
/// `blocks * 32` words at `words` must stay alive and unmodified until DMA0
/// completes.
unsafe fn dma_in(words: *const u32, blocks: u16) {
    debug_assert!(blocks != 0, "a zero block count is 65,536 blocks");
    dma::abort(Channel::MdecIn);
    // SAFETY: the channel was just aborted, so it is idle; the caller keeps
    // the `blocks * 32` words at `words` alive and unmodified until DMA0
    // completes, and `blocks` is not 0.
    unsafe {
        dma::start(
            Channel::MdecIn,
            dma::Transfer {
                address: words as u32,
                size: dma::size_blocks(DMA_BLOCK_WORDS as u16, blocks),
                control: CHCR_IN,
            },
        )
    };
}

/// How [`Mdec::load_tables`] got the tables in.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Tables {
    /// Enable writes, summed over both commands, before the MDEC raised its
    /// data-in request: 2 when every first write held. 0 means it never
    /// asked for data, so DMA0 decodes will not run either.
    pub enable_writes: u8,
    /// Tables that went in over the CPU because the MDEC never asked for
    /// DMA0 data or DMA0 wedged part way (0, 1 or 2).
    pub cpu_uploads: u8,
}

impl Tables {
    /// The MDEC asked for data on both commands, so DMA0 feeds it.
    pub fn is_dma_ready(&self) -> bool {
        self.enable_writes != 0 && self.cpu_uploads == 0
    }
}

/// The MDEC's driver: it owns the two DMA channels that feed and drain it, so
/// every decode step that starts one is a method here and the borrow checker
/// sees a second decoder.
///
/// A decode frame is: [`reset`](Self::reset) and
/// [`load_tables`](Self::load_tables) once, then per frame
/// [`decode`](Self::decode) with a closure that pulls the output columns.
///
/// The status register stays a free function ([`status`]): reading it
/// cannot disturb a transfer, so it needs no owner.
#[derive(Debug)]
#[repr(transparent)]
pub struct Mdec(MdecDma);

impl Mdec {
    /// Take the MDEC's DMA channels. Touches no register: call
    /// [`reset`](Self::reset) next.
    pub const fn new(dma: MdecDma) -> Self {
        Self(dma)
    }

    /// Give the DMA token back.
    #[inline(always)]
    pub fn release(self) -> MdecDma {
        self.0
    }

    /// Reset the MDEC, wait for the reset to finish, then enable its DMA
    /// requests on both channels. `false` if the MDEC stayed busy after the
    /// reset (the enable is still written).
    pub fn reset(&mut self) -> bool {
        dma::abort(Channel::MdecIn);
        dma::abort(Channel::MdecOut);
        dma::enable_channel(Channel::MdecIn);
        dma::enable_channel(Channel::MdecOut);
        // SAFETY: MDEC control register write.
        unsafe { psx_io::write_u32(MDEC1, hw::CONTROL_RESET) };
        let settled = wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS);
        let mut n = 0;
        while n < RESET_TAIL_READS {
            let _ = status();
            n += 1;
        }
        // SAFETY: MDEC control register write.
        unsafe { psx_io::write_u32(MDEC1, hw::CONTROL_ENABLE_DMA) };
        settled
    }

    /// Write `command`, then feed its 32 parameter words: over DMA0 when the
    /// MDEC asks for data, else over the CPU. Returns (enable writes before the
    /// request rose, 0 if never; went over the CPU), or `None` if the MDEC
    /// would not take the words at all.
    fn upload(&mut self, command: u32, words: &[u32; 32]) -> Option<(u8, bool)> {
        if !wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS) {
            return None;
        }
        // SAFETY: MDEC command write.
        unsafe { psx_io::write_u32(MDEC0, command) };
        let mut writes = 0u8;
        let mut asked = wait_status(hw::STATUS_IN_REQUEST, hw::STATUS_IN_REQUEST, SETTLE_SPINS);
        while !asked && writes + 1 < ENABLE_ATTEMPTS {
            // The enable can be lost to a reset that had not finished.
            // SAFETY: MDEC control register write, no reset bit.
            unsafe { psx_io::write_u32(MDEC1, hw::CONTROL_ENABLE_DMA) };
            writes += 1;
            asked = wait_status(hw::STATUS_IN_REQUEST, hw::STATUS_IN_REQUEST, SETTLE_SPINS);
        }
        let enable_writes = if asked { writes + 1 } else { 0 };
        if asked {
            // SAFETY: `words` is a borrowed table; the transfer is waited out.
            unsafe { dma_in(words.as_ptr(), 1) };
            if dma::wait_done(Channel::MdecIn, DMA_SPINS) {
                return Some((enable_writes, false));
            }
            // Part of the table went in: start the command over.
            dma::abort(Channel::MdecIn);
            self.reset();
            if !wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS) {
                return None;
            }
            // SAFETY: MDEC command write.
            unsafe { psx_io::write_u32(MDEC0, command) };
        }
        for &word in words {
            if !wait_status(hw::STATUS_IN_FULL, 0, SETTLE_SPINS) {
                return None;
            }
            // SAFETY: MDEC parameter write.
            unsafe { psx_io::write_u32(MDEC0, word) };
        }
        Some((enable_writes, true))
    }

    /// Upload the standard quantization tables and the IDCT basis. `None` if
    /// the MDEC would take them neither over DMA0 nor over the CPU.
    pub fn load_tables(&mut self) -> Option<Tables> {
        let (quant_writes, quant_cpu) = self.upload(hw::COMMAND_SET_QUANT, &QUANT_WORDS)?;
        let (scale_writes, scale_cpu) = self.upload(hw::COMMAND_SET_SCALE, &SCALE_WORDS)?;
        if !wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS) {
            return None;
        }
        Some(Tables {
            enable_writes: if quant_writes == 0 || scale_writes == 0 {
                0
            } else {
                quant_writes + scale_writes
            },
            cpu_uploads: quant_cpu as u8 + scale_cpu as u8,
        })
    }

    /// Upload both tables over CPU writes to MDEC0 only, after
    /// [`reset`](Self::reset). No DMA involved: the control path for a console
    /// whose DMA0 will not feed the MDEC. `false` if the input FIFO never made
    /// room.
    pub fn load_tables_cpu(&mut self) -> bool {
        for (command, words) in [
            (hw::COMMAND_SET_QUANT, &QUANT_WORDS),
            (hw::COMMAND_SET_SCALE, &SCALE_WORDS),
        ] {
            if !wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS) {
                return false;
            }
            self.write_command(command);
            for &word in words {
                if !wait_status(hw::STATUS_IN_FULL, 0, SETTLE_SPINS) {
                    return false;
                }
                self.write_command(word);
            }
        }
        wait_status(hw::STATUS_BUSY, 0, SETTLE_SPINS)
    }

    /// Write one word to MDEC0: a command, or a parameter the CPU feeds itself.
    #[inline(always)]
    pub fn write_command(&mut self, word: u32) {
        // SAFETY: MDEC command/parameter write.
        unsafe { psx_io::write_u32(MDEC0, word) }
    }

    /// Read one word of decoded output from MDEC0 (the CPU path; DMA1 is the
    /// usual one). Garbage when the output FIFO is empty.
    #[inline(always)]
    pub fn read_data(&mut self) -> u32 {
        // SAFETY: MDEC data read.
        unsafe { psx_io::read_u32(MDEC0) }
    }

    /// Start decoding `words` 32-bit words of run-length data (a multiple of 32,
    /// as [`crate::bitstream::decode_frame`] returns). `mode` is
    /// [`psx_hw::mdec::DECODE_15BPP`] or [`psx_hw::mdec::DECODE_24BPP`],
    /// optionally with [`psx_hw::mdec::DECODE_STP`].
    ///
    /// [`decode`](Self::decode) is the safe form: it holds the borrow of `rle`
    /// until DMA0 is done with it.
    ///
    /// # Errors
    /// [`RleLengthError`] when `words` is 0, not a multiple of 32, longer than
    /// the decode command can announce ([`crate::rle::MAX_WORDS`]) or longer
    /// than `rle`. Nothing is written to the MDEC then and no DMA starts.
    ///
    /// # Safety
    /// On `Ok`, DMA0 keeps reading `rle` after this returns. The caller must
    /// keep `rle` alive and unmodified until [`decode_finish`](Self::decode_finish)
    /// returns, and must call it before the storage is reused or freed.
    pub unsafe fn decode_start(
        &mut self,
        rle: &[u32],
        words: usize,
        mode: u32,
    ) -> Result<(), RleLengthError> {
        if words > rle.len() {
            return Err(RleLengthError::PastBuffer);
        }
        let blocks = rle::dma_block_count(words)?;
        // SAFETY: MMIO write to MDEC0, then a DMA0 kick of `blocks` (not 0)
        // 32-word blocks, exactly the first `words` words of `rle` (checked
        // above), which the caller keeps alive until `decode_finish`.
        unsafe {
            psx_io::write_u32(MDEC0, mode | words as u32);
            dma_in(rle.as_ptr(), blocks);
        }
        Ok(())
    }

    /// Decode all of `rle` (a multiple of 32 words, as
    /// [`crate::bitstream::decode_frame`] returns) with DMA0 feeding the MDEC,
    /// the safe form of [`decode_start`](Self::decode_start).
    ///
    /// `columns` runs while DMA0 feeds the MDEC and pulls the output, normally
    /// with [`read_column`](Self::read_column) once per column; it gets the
    /// driver back for that. Returns its result and
    /// [`decode_finish`](Self::decode_finish)'s: `false` there means DMA0 was
    /// still busy and has been aborted.
    ///
    /// # Errors
    /// [`RleLengthError`] when `rle` is empty, not a whole number of 32-word
    /// blocks or longer than [`crate::rle::MAX_WORDS`]; `columns` does not run.
    pub fn decode<R>(
        &mut self,
        rle: &[u32],
        mode: u32,
        columns: impl FnOnce(&mut Self) -> R,
    ) -> Result<(R, bool), RleLengthError> {
        // Finishes the decode on every exit, an unwinding `columns` included.
        struct Finish<'a> {
            mdec: &'a mut Mdec,
            done: bool,
        }
        impl Drop for Finish<'_> {
            fn drop(&mut self) {
                if !self.done {
                    self.mdec.decode_finish();
                }
            }
        }
        // SAFETY: `rle` stays borrowed until this function returns. On `Err`
        // no DMA started; on `Ok` every return path runs decode_finish first
        // (directly, or via `Finish` when unwinding), which returns only once
        // DMA0 is done or aborted.
        unsafe { self.decode_start(rle, rle.len(), mode)? };
        let mut finish = Finish {
            mdec: self,
            done: false,
        };
        let out = columns(finish.mdec);
        finish.done = true;
        Ok((out, finish.mdec.decode_finish()))
    }

    /// Start pulling the next `words` words (a multiple of 32) of decoded
    /// pixels over DMA1 into `dst` and return at once;
    /// [`column_done`](Self::column_done) says when they are in. The MDEC
    /// decodes only while DMA1 drains its output, so a player that overlaps
    /// work with the decode kicks the next column as soon as the last one
    /// lands.
    ///
    /// Only whole 32-word blocks move. Returns `false`, having started
    /// nothing, when that is no block at all or more than one transfer can
    /// count: the controller reads a zero block count as 65,536 blocks, which
    /// would run far past `dst`.
    ///
    /// # Safety
    /// `dst` must point at `words` writable words that stay alive and
    /// untouched until [`column_done`](Self::column_done) returns `true` or
    /// DMA1 is aborted ([`abort_decode`](Self::abort_decode)).
    pub unsafe fn read_column_start(&mut self, dst: *mut u32, words: usize) -> bool {
        let Ok(blocks) = u16::try_from(words / DMA_BLOCK_WORDS) else {
            return false;
        };
        if blocks == 0 {
            return false;
        }
        dma::abort(Channel::MdecOut);
        // SAFETY: the channel was just aborted, so it is idle. The transfer
        // writes `blocks * DMA_BLOCK_WORDS` = `words` words at `dst`, which
        // the caller keeps writable and untouched until it completes or is
        // aborted.
        unsafe {
            dma::start(
                Channel::MdecOut,
                dma::Transfer {
                    address: dst as u32,
                    size: dma::size_blocks(DMA_BLOCK_WORDS as u16, blocks),
                    control: CHCR_OUT,
                },
            )
        };
        true
    }

    /// True once the column [`read_column_start`](Self::read_column_start)
    /// asked for has arrived.
    #[inline]
    pub fn column_done(&self) -> bool {
        !dma::is_busy(Channel::MdecOut)
    }

    /// Stop both MDEC DMA channels, e.g. when a decode has taken too long. A
    /// column or run-length buffer a transfer was using is free again once
    /// this returns.
    pub fn abort_decode(&mut self) {
        dma::abort(Channel::MdecOut);
        dma::abort(Channel::MdecIn);
    }

    /// Pull the next `dst.len()` words (a multiple of 32) of decoded pixels
    /// over DMA1 and wait for them. For 15bpp one 16-pixel-wide column of
    /// height `h` is `8 * h` words. `false` if DMA1 wedged.
    pub fn read_column(&mut self, dst: &mut [u32]) -> bool {
        // SAFETY: `dst` is borrowed exclusively until this function returns;
        // the wait below, or the abort on a wedge, ends the transfer before
        // then.
        if !unsafe { self.read_column_start(dst.as_mut_ptr(), dst.len()) } {
            return false;
        }
        dma::wait_or_abort(Channel::MdecOut, DMA_SPINS)
    }

    /// Confirm DMA0 finished feeding the frame. `false` (after aborting the
    /// channel) if it is still busy, e.g. the frame held more data than was
    /// read back.
    pub fn decode_finish(&mut self) -> bool {
        dma::wait_or_abort(Channel::MdecIn, DMA_SPINS)
    }
}

/// A driver for a deprecated forwarder that never took the token.
fn steal_mdec() -> Mdec {
    // SAFETY: a token is a logic guard, not a memory-safety one (see
    // `psx_io::periph`), and the old free functions never took one.
    Mdec::new(unsafe { MdecDma::steal() })
}

/// Reset the MDEC and enable its DMA requests.
#[deprecated(note = "use `Mdec::reset` with the `MdecDma` token")]
pub fn reset() -> bool {
    steal_mdec().reset()
}

/// Upload the standard quantization tables and the IDCT basis.
#[deprecated(note = "use `Mdec::load_tables` with the `MdecDma` token")]
pub fn load_tables() -> Option<Tables> {
    steal_mdec().load_tables()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_driver_is_its_token_and_gives_it_back() {
        assert_eq!(core::mem::size_of::<Mdec>(), 0);
        // SAFETY: a test-local token on the host; `new` touches no register.
        let mdec = Mdec::new(unsafe { MdecDma::steal() });
        let _token: MdecDma = mdec.release();
    }

    #[test]
    fn a_decode_that_cannot_be_described_never_runs_its_columns() {
        // SAFETY: a test-local token on the host; both calls are refused
        // before any register is touched.
        let mut mdec = Mdec::new(unsafe { MdecDma::steal() });
        let mut ran = false;
        // Empty, and one word short of a block: refused before any write.
        for rle in [&[][..], &[0u32; 31][..]] {
            let result = mdec.decode(rle, hw::DECODE_15BPP, |_| ran = true);
            assert!(result.is_err());
        }
        assert!(!ran);
    }

    #[test]
    fn a_column_slice_the_channel_cannot_describe_is_refused_before_it_starts() {
        // SAFETY: a test-local token on the host; both are refused first.
        let mut mdec = Mdec::new(unsafe { MdecDma::steal() });
        assert!(!mdec.read_column(&mut []));
        assert!(!mdec.read_column(&mut [0u32; 31]));
    }
}