PUYA ESMC — 外部 QSPI Flash 读写（轮询）ESMC_ReadWrite_Polling

Tue, 08 Sep 2026 14:52:21 +0800

ESMC — 外部 QSPI Flash 读写（轮询）ESMC_ReadWrite_Polling

固件库: PY32F403_Firmware V1.4.5
芯片: PY32F403（Cortex-M4）⭐ F403 特色外设
源文件: PY32F403-STK/Example/ESMC/ESMC_ReadWrite_Polling/Src/main.c
核心外设: ESMC（驱动板载 P25Q64 QSPI NOR Flash）

1. 功能简介（大白话）

ESMC 是 F403 用来驱动外部串行 Flash 的专用控制器，本例用它操作板载的 P25Q64（8MB 的 QSPI NOR Flash），把 4096 字节测试数据写进去再读出来比对：

准备 4096 字节测试数据（0,1,2,...,255 循环）；
ESMC 初始化（时钟分频、单线指令、关闭双 Flash）；
写使能 → 等 BUSY 清零；
扇区擦除（4KB）；
开启 QE 位（Quad Enable，让四根数据线生效）；
四线页编程（按 256 字节/页写入）；
四线快读 回读；
校验一致则点亮绿灯，否则熄灭进入错误循环。

相当于给 MCU 「外挂了一块 8MB 硬盘」，且用的是四线 QSPI，比前面 SPI 例程的单线 Flash 快得多。这是 F403 相对基础系列多出来的招牌能力。

2. 硬件准备

物品	说明
PY32F403-STK 开发板	板载 P25Q64 QSPI Flash + 绿色 LED
USB 线	供电 + 下载

ESMC 与 P25Q64 的引脚连接（STK 板载已接好，AF10）：

P25Q64	信号	MCU 引脚
CLK	时钟	PB10
SS0 / CS	片选	PA2
IO0（SI）	数据0	PB1
IO1（SO）	数据1	PB0
IO2（WP）	数据2	PA7
IO3（HOLD）	数据3	PA6

无需串口，结果用 LED 表示：亮 = 成功，不亮/灭 = 失败。

3. 完整代码（带中文注释）

#include "main.h"
#define BUFFERSIZE 4096

ESMC_HandleTypeDef hesmc;
ESMC_InitTypeDef    ESMC_initTypeDef;
uint8_t aRxBuffer[BUFFERSIZE];
uint8_t aTxBuffer[BUFFERSIZE];
uint8_t flashStatus;

/* 函数声明 */
static void APP_EsmcInit(void);
static void APP_WriteEnable(void);
static void APP_EraseSector(uint32_t address);
static void APP_PageProgram(uint8_t *pdata, uint32_t addr, uint32_t Nbytes);
static void APP_DataRead(uint8_t *pData, uint32_t address, uint32_t nBytes);
static HAL_StatusTypeDef APP_DataCheck(uint8_t *pSrc, uint8_t *pDst, uint32_t length);
static void APP_SetFlashStatus(uint8_t status, uint8_t comm);
static uint8_t APP_GetFlashStatus(uint8_t comm);

int main(void)
{
  uint32_t i = 0, cnt = 0, progAddr = 0;
  uint8_t *pData = NULL;
  uint32_t address = 0;

  HAL_Init();
  BSP_LED_Init(LED_GREEN);

  /* 准备测试数据 0,1,2,...,255 循环 */
  for (i = 0; i < BUFFERSIZE; i++) aTxBuffer[i] = i % 256;

  APP_EsmcInit();          /* 1. ESMC 初始化 */

  APP_WriteEnable();        /* 2. 写使能 */
  while (APP_GetFlashStatus(0x05) & 0x01) {}   /* 等 BUSY 清 */

  APP_EraseSector(address); /* 3. 扇区擦除（4KB）*/
  while (APP_GetFlashStatus(P25Q64_READ_STATUS_REG_CMD) & 0x01) {}

  /* 4. 开启 QE 位（状态寄存器1 的 bit1）*/
  flashStatus = APP_GetFlashStatus(P25Q64_READ_STATUS_REG_1_CMD);
  flashStatus |= 0x02;
  APP_WriteEnable();
  while (APP_GetFlashStatus(0x05) & 0x01) {}
  APP_SetFlashStatus(flashStatus, P25Q64_WRITE_STATUS_REG_1_CMD);
  while (APP_GetFlashStatus(P25Q64_READ_STATUS_REG_CMD) & 0x01) {}

  /* 5. 分页编程（每页 256 字节）*/
  cnt = BUFFERSIZE; progAddr = address; pData = aTxBuffer;
  while (cnt / P25Q64_PAGE_SIZE > 0)
  {
    APP_PageProgram(pData, progAddr, P25Q64_PAGE_SIZE);
    while (APP_GetFlashStatus(P25Q64_READ_STATUS_REG_CMD) & 0x01) {}
    cnt      -= P25Q64_PAGE_SIZE;
    progAddr += P25Q64_PAGE_SIZE;
    pData    += P25Q64_PAGE_SIZE;
  }
  if (cnt > 0) {
    APP_PageProgram(pData, progAddr, cnt);
    while (APP_GetFlashStatus(P25Q64_READ_STATUS_REG_CMD) & 0x01) {}
  }

  /* 6. 读回并校验 */
  APP_DataRead(aRxBuffer, address, BUFFERSIZE);
  if (HAL_OK != APP_DataCheck(aRxBuffer, aTxBuffer, BUFFERSIZE))
  {
    BSP_LED_Off(LED_GREEN);
    APP_ErrorHandler();
  }
  BSP_LED_On(LED_GREEN);   /* 成功亮灯 */
  while (1) {}
}

/* ---------- ESMC 初始化 ---------- */
static void APP_EsmcInit(void)
{
  __HAL_RCC_ESMC_CLK_ENABLE();
  hesmc.Instance = ESMC;
  ESMC_initTypeDef.ClockPrescaler = 0x8;             /* 时钟分频（决定 QSPI 速率）*/
  ESMC_initTypeDef.ClockMode      = ESMC_CLOCK_MODE_0; /* CPOL=0, CPHA=0 */
  ESMC_initTypeDef.DualFlash      = ESMC_DUALFLASH_DISABLE;
  hesmc.Init = ESMC_initTypeDef;
  HAL_ESMC_Init(&hesmc);
}

/* ---------- 读状态寄存器 ---------- */
static uint8_t APP_GetFlashStatus(uint8_t command)
{
  ESMC_CommandTypeDef cmdStc = {0};
  uint8_t status;
  cmdStc.TransferFormat    = ESMC_TRANSFER_FORMAT_SINGLE;
  cmdStc.InstructionMode   = ESMC_INSTRUCTION_SINGLE_LINE;
  cmdStc.Instruction       = command;                /* 如 0x05 读状态 */
  cmdStc.AddressMode       = ESMC_ADDRESS_NONE;
  cmdStc.DummyCycles       = 0x0;
  cmdStc.DdrMode           = ESMC_DDR_DISABLE;
  cmdStc.DataMode          = ESMC_DATA_READ;
  cmdStc.NbData            = 1;
  cmdStc.CSPinSel          = ESMC_SELECT_PIN_CS0;     /* 选 CS0(PA2) */
  HAL_ESMC_Command(&hesmc, &cmdStc, 0x0000FFFF);
  HAL_ESMC_Receive(&hesmc, &status, 0x0000FFFF);
  return status;
}

/* ---------- 写状态寄存器 ---------- */
static void APP_SetFlashStatus(uint8_t status, uint8_t command)
{
  ESMC_CommandTypeDef cmdStc = {0};
  cmdStc.TransferFormat  = ESMC_TRANSFER_FORMAT_SINGLE;
  cmdStc.InstructionMode = ESMC_INSTRUCTION_SINGLE_LINE;
  cmdStc.Instruction     = command;                  /* 如 0x31 写状态1 */
  cmdStc.AddressMode     = ESMC_ADDRESS_NONE;
  cmdStc.DataMode        = ESMC_DATA_WRITE;
  cmdStc.NbData          = 1;
  cmdStc.CSPinSel        = ESMC_SELECT_PIN_CS0;
  HAL_ESMC_Command(&hesmc, &cmdStc, 0x0000FFFF);
  HAL_ESMC_Transmit(&hesmc, &status, 0x0000FFFF);
}

/* ---------- 写使能（06h）---------- */
static void APP_WriteEnable(void)
{
  ESMC_CommandTypeDef commandStc = {0};
  commandStc.TransferFormat  = ESMC_TRANSFER_FORMAT_SINGLE;
  commandStc.InstructionMode = ESMC_INSTRUCTION_SINGLE_LINE;
  commandStc.Instruction     = P25Q64_WRITE_ENABLE_CMD; /* 0x06 */
  commandStc.AddressMode     = ESMC_ADDRESS_NONE;
  commandStc.DataMode        = ESMC_DATA_NONE;
  commandStc.CSPinSel        = ESMC_SELECT_PIN_CS0;
  HAL_ESMC_Command(&hesmc, &commandStc, 0x0000FFFF);
}

/* ---------- 扇区擦除（20h，4KB）---------- */
static void APP_EraseSector(uint32_t address)
{
  ESMC_CommandTypeDef cmdStc = {0};
  APP_WriteEnable();
  cmdStc.TransferFormat  = ESMC_TRANSFER_FORMAT_SINGLE;
  cmdStc.InstructionMode = ESMC_INSTRUCTION_SINGLE_LINE;
  cmdStc.Instruction     = P25Q64_SECTOR_ERASE_4K_CMD; /* 0x20 */
  cmdStc.AddressMode     = ESMC_ADDRESS_SINGLE_LINE;
  cmdStc.AddressSize     = ESMC_ADDRESS_24_BITS;
  cmdStc.Address         = address;
  cmdStc.DataMode        = ESMC_DATA_NONE;
  cmdStc.CSPinSel        = ESMC_SELECT_PIN_CS0;
  HAL_ESMC_Command(&hesmc, &cmdStc, 0x0000FFFF);
}

/* ---------- 四线页编程（32h）---------- */
static void APP_PageProgram(uint8_t *pData, uint32_t addr, uint32_t nBytes)
{
  ESMC_CommandTypeDef cmdStc = {0};
  APP_WriteEnable();
  cmdStc.TransferFormat  = ESMC_TRANSFER_FORMAT_QUAD;   /* 四线传输数据 */
  cmdStc.InstructionMode = ESMC_INSTRUCTION_SINGLE_LINE;/* 指令仍单线 */
  cmdStc.Instruction     = P25Q64_QUAD_INPUT_PAGE_PROG_CMD; /* 0x32 */
  cmdStc.AddressMode     = ESMC_ADDRESS_SINGLE_LINE;
  cmdStc.AddressSize     = ESMC_ADDRESS_24_BITS;
  cmdStc.Address         = addr;
  cmdStc.DummyCycles     = 0x0;
  cmdStc.DataMode        = ESMC_DATA_WRITE;
  cmdStc.NbData          = nBytes;
  cmdStc.CSPinSel        = ESMC_SELECT_PIN_CS0;
  HAL_ESMC_Command(&hesmc, &cmdStc, 0x0000FFFF);
  HAL_ESMC_Transmit(&hesmc, pData, 0x0000FFFF);
}

/* ---------- 四线快读（6Bh）---------- */
static void APP_DataRead(uint8_t *pData, uint32_t address, uint32_t nBytes)
{
  ESMC_CommandTypeDef cmdStc = {0};
  cmdStc.TransferFormat  = ESMC_TRANSFER_FORMAT_QUAD;   /* 四线读数据 */
  cmdStc.InstructionMode = ESMC_INSTRUCTION_SINGLE_LINE;
  cmdStc.Instruction     = P25Q64_1I4O_FAST_READ_CMD;  /* 0x6B：指令单线，数据四线 */
  cmdStc.AddressMode     = ESMC_ADDRESS_SINGLE_LINE;
  cmdStc.AddressSize     = ESMC_ADDRESS_24_BITS;
  cmdStc.Address         = address;
  cmdStc.DummyCycles     = DUMMY_CLOCK_CYCLES_READ;     /* 8 个哑周期 */
  cmdStc.DataMode        = ESMC_DATA_READ;
  cmdStc.NbData          = nBytes;
  cmdStc.CSPinSel        = ESMC_SELECT_PIN_CS0;
  HAL_ESMC_Command(&hesmc, &cmdStc, 0x00FFFFFF);
  HAL_ESMC_Receive(&hesmc, pData, 0x00FFFFFF);
}

/* ---------- 数据比对 ---------- */
static HAL_StatusTypeDef APP_DataCheck(uint8_t *pSrc, uint8_t *pDst, uint32_t length)
{
  for (uint32_t i = 0; i < length; i++)
    if (pSrc[i] != pDst[i]) return HAL_ERROR;
  return HAL_OK;
}

void APP_ErrorHandler(void) { while (1) {} }

附：MSP 里的引脚配置（HAL_ESMC_Init 自动调用）

void HAL_ESMC_MspInit(ESMC_HandleTypeDef *hesmc)
{
  __HAL_RCC_ESMC_CLK_ENABLE();
  __HAL_RCC_GPIOA_CLK_ENABLE();
  __HAL_RCC_GPIOB_CLK_ENABLE();
  __HAL_RCC_GPIOC_CLK_ENABLE();

  GPIO_InitTypeDef GPIO_InitStructure = {0};
  GPIO_InitStructure.Mode      = GPIO_MODE_AF_PP;
  GPIO_InitStructure.Alternate = GPIO_AF10_ESMC;       /* 全部 AF10 */
  GPIO_InitStructure.Speed     = GPIO_SPEED_FREQ_VERY_HIGH;

  /* CLK=PB10, IO0=PB1, IO1=PB0 */
  GPIO_InitStructure.Pin = GPIO_PIN_10; GPIO_InitStructure.Pull = GPIO_NOPULL;
  HAL_GPIO_Init(GPIOB, &GPIO_InitStructure);
  GPIO_InitStructure.Pin = GPIO_PIN_1;  HAL_GPIO_Init(GPIOB, &GPIO_InitStructure);
  GPIO_InitStructure.Pin = GPIO_PIN_0;  HAL_GPIO_Init(GPIOB, &GPIO_InitStructure);
  /* IO2=PA7, IO3=PA6, SS0=PA2（上拉）*/
  GPIO_InitStructure.Pin = GPIO_PIN_7; GPIO_InitStructure.Pull = GPIO_PULLUP;
  HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);
  GPIO_InitStructure.Pin = GPIO_PIN_6; HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);
  GPIO_InitStructure.Pin = GPIO_PIN_2; HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);
}

4. 代码分段讲解

4.1 ESMC 的「命令描述符」模型

ESMC 把一次 Flash 访问拆成两步：

HAL_ESMC_Command()：用 ESMC_CommandTypeDef 描述本次操作——指令码、指令线数、是否带地址、地址位数、数据方向（读/写）、数据线数（单/双/四）、数据长度、CS 引脚；
HAL_ESMC_Transmit / Receive：按描述真正搬数据。

这种「描述符 + 传输」模型非常灵活，一套 API 通吃各种 QSPI 器件，不用手写位时序。

4.2 单线指令 + 四线数据

注意一个关键设计：指令阶段几乎都用单线（INSTRUCTION_SINGLE_LINE，成本低兼容好），而数据阶段才用四线（TRANSFER_FORMAT_QUAD）。例如：

写：0x32（QUAD_INPUT_PAGE_PROG）指令单线发，后面数据四线写；
读：0x6B（1I4O_FAST_READ）指令单线发，读回数据四线收，中间插 8 个哑周期（Dummy）。

4.3 四线为什么必须开 QE？

四线要用 IO2/IO3 两根线，但这两根线默认是 WP/HOLD 功能。必须在**状态寄存器 1 的 bit1（QE 位）**置 1，Flash 才把它们切换成数据线。本例在擦除后专门读-改-写状态寄存器开启 QE——没开 QE 就四线读写会失败。

4.4 写使能与 BUSY 轮询（铁律）

任何擦/写前必须发 Write Enable（0x06）；操作期间状态寄存器 BUSY 位=1，代码用 while (GetFlashStatus & 0x01) 轮询等到清零，才能下一步。这是所有 SPI/QSPI NOR Flash 的通用约定。

4.5 页编程与跨页

P25Q64 每页 256 字节，一次最多写一页。本例 4096 字节用 while (cnt / 256 > 0) 循环分 16 页写，余数单独补一页。且每次写前地址所在扇区必须已擦除（4KB 扇区擦除已覆盖这 4096 字节）。

4.6 时钟分频

ClockPrescaler = 0x8 决定 QSPI 接口时钟频率（由 ESMC 输入时钟分频而来）。想提速可减小分频，但要保证在 Flash 手册允许范围内。

5. 实验现象

烧录运行后：绿色 LED 常亮 = 擦→写→读→校验全部成功；
若失败（如型号不匹配、QE 未开、接线错）：LED 不亮或熄灭，卡在 APP_ErrorHandler。

6. 常见问题

现象	原因	解决
LED 不亮（校验失败）	Flash 型号不是 P25Q64	指令宏 `P25Q64_*` 与芯片匹配；换型号需改指令/页大小
四线读写失败	QE 位没成功开启	检查 `APP_SetFlashStatus` 流程，确认状态1 bit1=1
写不进去	没 WriteEnable / 没擦除	写前使能且目标区已擦除（全 0xFF）
BUSY 一直为 1	操作未完成/异常	检查指令与 CS 引脚选择（CS0=PA2）
速率上不去	分频太大	减小 `ClockPrescaler`，勿超 Flash 上限
大块数据慢	轮询阻塞	参考 `ESMC_ReadWrite_DMA`、`ESMC_ReadWriteQuad_IT`

7. 小结

ESMC 是 F403 特色外设，用「命令描述符 + 传输」统一驱动 QSPI/Octo 串行存储器；
QSPI Flash 写流程铁律：写使能 → 等 BUSY → 擦除 → 写使能 → 页编程 → 等 BUSY → 读 → 校验；
指令通常单线发，开 QE 后数据用四线搬，速度翻数倍；
引脚全部 AF10：CLK=PB10、CS=PA2、IO0~3=PB1/PB0/PA7/PA6；
本例擦 4KB、分 16 页写 4096 字节、四线读回，LED 亮即成功。

8. 拓展应用（学了能做什么项目）

字库/图片/UI 资源库：把字模、位图存外部 Flash，内部 Flash 只放代码；
数据记录仪：日志、采样缓存写外部 Flash，断电不丢；
固件 OTA：新固件先存外部 Flash，校验后切换启动；
内存映射 XIP：参考 ESMC_MemoryMapping，把外部 Flash 映射成地址空间直接执行代码，突破内部容量；
双 Flash 并行：参考 ESMC_ReadWrite_TwoFlash_Polling，翻倍带宽；
大块资源搬运：参考 ESMC_ReadWrite_DMA，用 DMA 把音频/视频资源送到 LCD/Codec。

返回：ESMC 总览

P25Q64 on CLing