0. 目的与范围

本规范约束 PSRAM 器件在嵌入式固件中的软件行为：命令序列、延迟配置、刷新窗口管理、低功耗状态切换、XIP 映射与异常恢复。凡本文与器件 datasheet 冲突，以 datasheet 为准。

• 统一命令序列：读（03h/0Bh/6Bh/EBh）、写（02h/38h）、复位（66h→99h）、模式配置，各自固化为一套标准流程。
• 统一延迟判据：所有读都必须按接口频率配置 dummy / initial latency，频率变了延迟就要重配，不能写死。
• 统一刷新窗口：任何单笔事务的 CS# 低电平时间不得超过 tCEM（典型 4 µs），长事务必须分片，保证内部自刷新有窗口。
• 统一低功耗语义：明确 Active / Standby / Deep Sleep / DPD 四态的进入命令、退出代价与数据保持性，尤其 DPD 唤醒后须重初始化。

一句话结论：PSRAM 是「带内部刷新的 SRAM」 —— 所有写都是立即完成的（没有 WREN、没有忙标志、没有擦除）；所有读都要先熬过一段延迟（dummy / initial latency）才能拿到数据； 而它最容易被忽略的死穴是 CS# 不能一直拉低——超过 tCEM 会阻断内部刷新，高温下数据悄悄丢失；把 NOR 的 wait_busy() 搬过来会死等；把 PSRAM 当真正 SRAM 用会掉数据。

文档使用说明

• 本文是《PSRAM 电路设计指南》的软件配套篇：硬件篇解决「怎么接、怎么供电、怎么走线」，本文解决「驱动怎么写、延迟怎么配、刷新窗口怎么留、低功耗怎么切」。
• 命令码、寄存器位、时序值以典型 Quad SPI / OPI PSRAM 命令集与《PSRAM 电路设计指南》给出，作为 XTX PSRAM 驱动开发的基线框架；具体器件（型号、MID、模式寄存器命令字、延迟/突发位定义）必须对照对应 datasheet 核实后填入。
• 文中 C 代码为协议骨架伪代码，演示流程与判断条件，非特定平台可直接编译的完整实现；spi_transfer()、now_us() 等为平台相关底层。

1 · 器件定位与存储组织

PSRAM 不是「能字节写的 Flash」，也不是「完全不用管的 SRAM」。它是 DRAM 内核 + 片内自刷新控制器，对外呈现 SRAM 式线性寻址。软件设计的第一件事，是把「线性地址空间」和「刷新窗口」这两个概念刻进脑子里。

1.1 器件定位与关键参数

数据取自《PSRAM 电路设计指南》第 1~2 章器件参数与第 5 章刷新/延迟；具体数值以目标器件 datasheet 为准。

1.2 地址空间与线性映射

PSRAM 内部是单一连续的线性地址空间，没有「页/块/扇区」层级，也没有「cache 寄存器」中间缓冲。软件寻址时只需要一个地址计数器，从 0x000000 到 容量-1，读写都按字节（或按总线位宽的字）推进：

1.3 接口模式：SPI / Quad / OPI / HyperBus

1.4 与 SPI NOR / SDRAM 的关键差异（移植必读）

2 · 术语与缩写

本章统一术语口径，避免「延迟/突发/刷新窗口」在文档与代码里指的不是同一件事。

2.1 结构与命令术语

2.2 本文书写约定

• 命令码用小写十六进制带后缀 h 书写（如 0xEB），与 datasheet 保持一致；本文统一用 0x 前缀。
• 寄存器位写作 CR0[2] 形式，方括号内为 bit 位序（bit0 为最低位）。
• 时序符号沿用 datasheet：tCEM（CS# 低上限）、tCPH（CS# 高下限）、tVSL（上电稳定）、tRST（复位恢复）。「典型值 / 最大值」成对给出时，软件分片与超时一律按最大值（最严）预算。
• 延迟符号：Latency / Dummy 表示读前空周期数，数值随接口与频率变化，必须参数化。
• 代码示例为 C 伪代码，省略 SPI/QSPI/OPI 传输底层实现，只表达命令序列、延迟与分片判据。

3 · 驱动架构与初始化

PSRAM 的驱动比 NOR 少两层（没有坏块、没有 ECC 判读），但多一层刷新窗口管理和一层延迟配置。这两层放错位置，后面所有优化都是白做。

3.1 分层职责

3.2 上电初始化流程

上电后器件处于SPI 单线默认模式，延迟取默认值，且数据未定义（上电瞬间 RAM 内容随机）。初始化必须按下列顺序执行：

/* 上电初始化：返回 0 表示成功 */
int psram_init(void)
{
    uint8_t id[3];

    delay_ms(3);                    /* 上电稳定余量 ≥1 ms；器件 tPU 典型 150~500 µs */
    psram_reset();                  /* 66h -> 99h，复位到已知态 */

    if (psram_read_id(id) != 0)     return -E_NODEV;   /* 9Fh */
    if (id[0] != XTX_MID)          return -E_NODEV;   /* 厂商 ID 不匹配 */

    /* 进入目标接口模式（以 datasheet 命令字为准） */
    psram_enter_quad_mode();        /* 典型 0x35；OPI 则发 OPI 切换命令 */

    /* 配置模式/配置寄存器：突发长度、驱动强度、延迟、刷新范围 */
    psram_wr_mode_reg(PSR_MREG_ALL);

    /* OPI/HyperBus 需读训练；SPI/Quad 跳过 */
    if (iface_is_high_speed())
        psram_read_training();

    /* 自检：写已知 pattern 再读回比对 */
    if (psram_self_test() != 0)     return -E_SELFTEST;
    return 0;
}

3.3 器件识别：ID 与配置寄存器

1. 9Fh 读 ID（厂商 + 容量/接口）：拿到 MID 判定厂商，容量码决定地址位宽与最大地址。这是最快的筛选路径，用于初始化早期排除「没焊上 / 型号不对」。
2. 读配置/模式寄存器（CR0/CR1 或 MR）：回读当前突发长度、延迟、驱动强度、刷新范围，确认器件实际配置与驱动期望一致；不一致则写配置对齐。
3. 自检回读：在一段已知地址写固定 pattern（如 0xAA/0x55 交替），再读回比对。校验不过说明接口模式/延迟/采样配置错，应降级频率重试而非继续初始化。

4 · 配置寄存器与模式寄存器体系

PSRAM 没有 NOR 式「状态寄存器 + 配置寄存器」的标准划分，但高速型号（OPI/HyperBus）普遍通过配置寄存器（CR0/CR1）或模式寄存器（MR）来控制延迟、突发、驱动强度与刷新。理解这些寄存器，就理解了整颗器件的可调行为。

4.1 寄存器总览

4.2 模式寄存器（进入 Quad / OPI）

接口模式切换是 PSRAM 初始化最关键的一步，常见两种机制：

4.3 延迟 / 突发配置位

4.4 驱动强度与刷新配置位

调整驱动强度是信号完整性手段而非性能手段：高速读出错时，先训练延迟链，再决定是否加驱动或降频。

4.5 配置写入准则

/* 配置寄存器写：读-改-写-校验（以目标寄存器地址/命令为准） */
int psram_wr_cfg(uint8_t reg, uint8_t mask, uint8_t val)
{
    uint8_t cur = psram_rd_cfg(reg);   /* ① 读原值 */
    uint8_t next = (cur & ~mask) | (val & mask);   /* ② 只改目标位 */
    if (next == cur) return 0;         /* 无需写 */

    psram_wr_cfg_raw(reg, next);        /* 下发 */
    if (psram_rd_cfg(reg) != next)      /* ③ 回读校验 */
        return -E_VERIFY;
    return 0;
}