必须配对设置Memory-Mapped Mode寄存器：启用XIP需在QSPI_InitTypeDef中设MemoryMappedMode为ENABLE，并严格对齐FifoThreshold、SampleShifting、FlashSize等参数，如W25Q80DV的FlashSize须填0x0F；同时链接脚本ORIGIN必须为0x90000000且带rx属性，函数须加__attribute__((section(".qspi_text"), noinline, used))，并确保初始化代码在内部Flash中完成Flash唤醒（0x06+0x05轮询），否则取指失败触发HardFault。
QSPI外设初始化必须配对设置Memory-Mapped Mode寄存器
单片机（如STM32H7、GD32E5、RT106x）的QSPI控制器要启用XIP，不能只调用HAL_QSPI_Init()就完事——关键在QSPI_InitTypeDef结构体里把MemoryMappedMode设为ENABLE，且FifoThreshold、SampleShifting、FlashSize等字段必须与Flash芯片手册严格对齐。比如W25Q80DV的容量是0x0F（128Mbit = 16MB），填错会导致地址解码偏移，读到全是0xFF。
常见错误现象：__attribute__((section(".qspi_flash"))) void my_func() { ... }函数编译进QSPI区域后，一调用就硬故障（HardFault），多数是Prescaler值算错导致时钟超限，或ClockMode没设成QSPI_CLOCK_MODE_0（空闲低电平）却用了上升沿采样。
- 务必查芯片Reference Manual中“QSPI memory-mapped mode timing requirements”小节，确认最大允许频率（如GD32E507是133MHz，但W25Q80DV仅支持104MHz）
-
TimeoutActivation建议关掉（DISABLE），XIP模式下超时机制会干扰连续取指 - STM32H7需额外使能
QUADSPI->CR |= QUADSPI_CR_TCEN（timeout counter enable）才能让中断正常响应，否则DMA传输卡死
链接脚本里QSPI地址段必须与硬件映射空间一致
ARM Cortex-M系列通常将QSPI Flash映射到0x90000000起始的地址空间（如STM32H7是0x90000000–0x9FFFFFFF），但这个范围不是固定死的——它由QSPI控制器的ABR（Address Bit Register）和DCR（Device Configuration Register）共同决定。链接脚本（.ld文件）里定义的MEMORY区域必须完全匹配，否则ld会把代码塞进错误位置，上电后PC跳转到无效地址。
示例（STM32H743）：
立即学习“C++免费学习笔记（深入）”；
MEMORY
{
QSPI_FLASH (rx) : ORIGIN = 0x90000000, LENGTH = 16M
}
SECTIONS
{
.qspi_text : { *(.qspi_text) } > QSPI_FLASH
}
注意：ORIGIN不能写成0x90000000U（带U后缀会被ld当常量处理，可能截断），也不能漏掉rx属性（只读+可执行），否则GCC生成的ELF头部标记错误，启动时MPU或MMU拒绝执行。
- GD32E5系列默认映射基址是0x90000000，但可通过
QSPI->ABR重定向，此时链接脚本必须同步更新 - 如果使用IAR，需在.icf里用
place at address mem:0x90000000 { readonly section .qspi_text };，语法和GCC不兼容 - 务必检查
objdump -h your.elf输出，确认.qspi_text的VMA（Virtual Memory Address）确实是0x90000000开头
函数/变量加属性前必须保证编译器不内联且不优化掉
给函数加__attribute__((section(".qspi_text"), long_call, noinline))只是第一步；若函数太短，GCC可能无视noinline直接内联进RAM区代码里，运行时还是从SRAM取指。更隐蔽的问题是const全局变量加了__attribute__((section(".qspi_rodata")))，但链接器发现它没被引用，直接丢弃——结果运行时访问该地址触发总线错误（BusFault）。
解决方法：
- 所有标为QSPI段的函数，末尾加
__attribute__((used))强制保留，即使未显式调用 - 避免在QSPI函数里调用未标记的RAM函数（如
printf），否则跳转指令会落到非cacheable区域，性能暴跌甚至死锁 - STM32H7需开启
SCB->CCR |= SCB_CCR_BP_Msk（branch prediction enable），否则QSPI取指延迟高，循环分支预测失败率飙升 - 调试时用
readelf -S your.elf | grep qspi确认符号确实落在目标段，而不是被--gc-sections删掉了
上电后首次访问QSPI Flash前必须完成初始化序列
QSPI控制器进入Memory-Mapped Mode后，并不自动发送初始化命令（如0x05读状态、0x06写使能）。必须在跳转到QSPI代码前，用Indirect Mode手动执行一次Flash唤醒流程：发0x06（Write Enable）、0x05（Read Status）轮询BUSY位清零。否则CPU从0x90000000取第一条指令时，Flash还在power-up busy状态，返回全0xFF，直接硬故障。
典型坑点：
- 初始化代码本身不能放在QSPI里（否则形成死循环），必须固化在内部Flash或SRAM中执行
- GD32E5的QSPI有
QUADSPI_CR_PRESCALER寄存器，上电默认值非0，需先写0再配置，否则分频异常 - 某些Flash（如IS25LP080D）需要先发0xB7（Enable Quad I/O）才能支持QSPI四线读，漏掉这步，XIP模式下地址线A0-A1会误驱动成数据线，读出乱码
最易被忽略的是Cache一致性：CM7内核开启ICache后，若QSPI Flash内容被外部工具（如J-Link）擦写过，ICache里还存着旧指令，必须调用SCB_InvalidateICache()，否则跑飞。
