SFC_GPIO_PIN_MAPPING

/**

• NOR FLASH SPI/SFC 的 GPIO 引脚映射
• 本文档详细说明 WS63 芯片上 NOR Flash/SFC 使用的具体 GPIO 引脚
• 根据代码分析得出，文件位置: platform_core_rom.h */

========================================================================================

✅ SFC 使用的GPIO引脚列表（已确认）

========================================================================================

源代码位置

文件: src/drivers/chips/ws63/include/platform_core_rom.h
行号: 50-56

标准SPI(Standard/Fast Read)引脚

引脚名	GPIO号	别名	用途	必需
SFC_CLK	GPIO_19	CLK	时钟信号	✅ 是
SFC_CSN	GPIO_20	CS/CS_N	片选信号（低电平有效）	✅ 是
SFC_IO0	GPIO_21	MOSI/SO	主出从入 (写 Flash)	✅ 是
SFC_IO1	GPIO_22	MISO/SI	主入从出 (读 Flash)	✅ 是

Quad SPI 模式的额外引脚（可选）

引脚名	GPIO号	别名	用途	必需*
SFC_IO2	GPIO_23	WP/WP_N	写保护（Quad 模式）	⭕ Quad SPI
SFC_IO3	GPIO_24	HOLD/HOLD_N	暂停指令（Quad 模式）	⭕ Quad SPI

说明: *Quad SPI 模式下才需要，标准 SPI 模式下这两个引脚可不连接

---

========================================================================================

🔗 GPIO 引脚电路连接图

========================================================================================

标准 SPI 模式连接

WS63 芯片                              NOR Flash 芯片
┌──────────────────────┐              ┌──────────────────┐
│    GPIO_19 (SFC_CLK) ├──────────────┤ CLK              │
│                      │              │                  │
│    GPIO_20 (SFC_CSN) ├──────────────┤ CS#              │
│                      │              │                  │
│    GPIO_21 (SFC_IO0) ├──────────────┤ MOSI/DO          │
│      (MOSI)          │              │                  │
│                      │              │                  │
│    GPIO_22 (SFC_IO1) ├──────────────┤ MISO/DI          │
│      (MISO)          │              │                  │
│                      │              │                  │
│         GND          ├──────────────┤ GND              │
│                      │              │                  │
│        3.3V          ├──────────────┤ VCC              │
└──────────────────────┘              └──────────────────┘

Quad SPI 模式连接（可选）

WS63 芯片                              NOR Flash 芯片
┌──────────────────────┐              ┌──────────────────┐
│    GPIO_19 (SFC_CLK) ├──────────────┤ CLK              │
│                      │              │                  │
│    GPIO_20 (SFC_CSN) ├──────────────┤ CS#              │
│                      │              │                  │
│    GPIO_21 (SFC_IO0) ├──────────────┤ IO0/MOSI         │
│                      │              │                  │
│    GPIO_22 (SFC_IO1) ├──────────────┤ IO1/MISO         │
│                      │              │                  │
│    GPIO_23 (SFC_IO2) ├──────────────┤ IO2/WP#          │
│                      │              │                  │
│    GPIO_24 (SFC_IO3) ├──────────────┤ IO3/HOLD#        │
│                      │              │                  │
│         GND          ├──────────────┤ GND              │
│                      │              │                  │
│        3.3V          ├──────────────┤ VCC              │
└──────────────────────┘              └──────────────────┘

---

========================================================================================

📋 快速参考：GPIO 编号到功能的映射

========================================================================================

命令行快查表

# 快速查找 GPIO 的 SFC 功能
GPIO_19 = SFC_CLK     → 时钟信号（必需）
GPIO_20 = SFC_CSN     → 片选信号（必需）
GPIO_21 = SFC_IO0     → MOSI 输出（必需）
GPIO_22 = SFC_IO1     → MISO 输入（必需）
GPIO_23 = SFC_IO2     → 写保护（Quad 模式）
GPIO_24 = SFC_IO3     → 暂停控制（Quad 模式）

代码中引用

// 在你的代码中，可以直接引用这些 GPIO 号
#define SFC_CLK_PIN     GPIO_19
#define SFC_CSN_PIN     GPIO_20
#define SFC_MOSI_PIN    GPIO_21  // SFC_IO0
#define SFC_MISO_PIN    GPIO_22  // SFC_IO1
#define SFC_WP_PIN      GPIO_23  // SFC_IO2 (Quad only)
#define SFC_HOLD_PIN    GPIO_24  // SFC_IO3 (Quad only)

---

========================================================================================

🔧 配置和验证步骤

========================================================================================

第1步：确认硬件连接

在焊接或连接 NOR Flash 之前，必须确认：

检查项                         标准模式          Quad模式
─────────────────────────────────────────────────────────
GPIO_19 定义为 SFC_CLK        [ ] 已连接       [ ] 已连接
GPIO_20 定义为 SFC_CSN        [ ] 已连接       [ ] 已连接
GPIO_21 定义为 SFC_IO0(MOSI)  [ ] 已连接       [ ] 已连接
GPIO_22 定义为 SFC_IO1(MISO)  [ ] 已连接       [ ] 已连接
GPIO_23 定义为 SFC_IO2(WP)    N/A              [ ] 已连接
GPIO_24 定义为 SFC_IO3(HOLD)  N/A              [ ] 已连接
GND 连接                      [ ] 已连接       [ ] 已连接
VCC 3.3V 连接                 [ ] 已连接       [ ] 已连接

第2步：验证信号（用示波器）

信号          GPIO_19   GPIO_20   GPIO_21   GPIO_22
            (CLK)      (CS)      (MOSI)    (MISO)
──────────────────────────────────────────────────────
时序          ▃▂▃▂      ╔║╚║╔     ▄▅▄▅      ▄▅▄▅
频率          150MHz    脉冲      同步      同步
幅度          3.3V      3.3V      3.3V      3.3V

第3步：软件配置确认

在以下文件中定义 GPIO：

文件 1: sfc_porting.h

// 检查是否有以下定义
#define SFC_CLK_PIN      GPIO_19
#define SFC_CSN_PIN      GPIO_20
#define SFC_IO0_PIN      GPIO_21
#define SFC_IO1_PIN      GPIO_22

文件 2: board.c (或 pinctrl 文件)

// 检查是否配置了引脚映射
hal_pinctrl_config(SFC_CLK_PIN, FUNC_SFC);
hal_pinctrl_config(SFC_CSN_PIN, FUNC_SFC);
hal_pinctrl_config(SFC_IO0_PIN, FUNC_SFC);
hal_pinctrl_config(SFC_IO1_PIN, FUNC_SFC);

第4步：编译验证

# 编译时应该能够找到这些定义
gcc -I src/drivers/chips/ws63/include -c sfc.c

# 如果出现 "undefined reference"，说明 GPIO 定义有问题

---

========================================================================================

💡 实用建议

========================================================================================

✅ 推荐方案（安全可靠）

在你的项目中，建议创建一个 gpio_mapping.h 文件：

#ifndef __GPIO_MAPPING_H__
#define __GPIO_MAPPING_H__

// ===== SFC (NOR Flash) 引脚映射 =====
// 源: src/drivers/chips/ws63/include/platform_core_rom.h
// 
// 标准 SPI 模式（必需）：GPIO_19-22
// Quad SPI 模式（可选）：GPIO_23-24

#define SFC_CLK_GPIO        GPIO_19     // Serial Flash Clock
#define SFC_CSN_GPIO        GPIO_20     // Chip Select (active low)
#define SFC_IO0_GPIO        GPIO_21     // MOSI (Master Out, Slave In)
#define SFC_IO1_GPIO        GPIO_22     // MISO (Master In, Slave Out)
#define SFC_IO2_GPIO        GPIO_23     // Write Protect (Quad mode only)
#define SFC_IO3_GPIO        GPIO_24     // HOLD (Quad mode only)

// ===== GPIO 验证宏 =====
// 编译时验证使用的GPIO是否正确

#ifdef CONFIG_SFC_SUPPORT_QUAD
    // Quad SPI 需要 6 条线
    #define SFC_PINS_COUNT  6
#else
    // 标准 SPI 需要 4 条线
    #define SFC_PINS_COUNT  4
#endif

#endif // __GPIO_MAPPING_H__

⚠️ 常见错误

错误	原因	如何避免
Flash ID 读不出 (0xFFFFFFFF)	GPIO_21 (MOSI) 未连接	检查 GPIO_21 到 Flash IO0
Flash ID 全是 0x000000	GPIO_19 (CLK) 未连接	检查 GPIO_19 到 Flash CLK
SPI 信号紊乱	GPIO_20 (CS) 未拉低	检查 GPIO_20 到 Flash CS#
写入失败	GPIO_23 (WP) 被拉低	Quad 模式需要 WP 拉高
读写很慢	使用了标准模式而非 Quad	Quad 模式 GPIO_23/24 需配置

---

========================================================================================

🔍 如何从代码中验证 GPIO

========================================================================================

方法 1：查看源代码定义

# 查找 GPIO 定义的位置
grep -r "SFC_CLK.*GPIO" src/drivers/chips/ws63/

# 查找引脚映射文件
find . -name "*pinctrl*" -o -name "*pin_config*"

方法 2：追踪初始化代码

// sfc.c 中的初始化函数
errcode_t uapi_sfc_init(sfc_flash_config_t *config)
{
    // 这里会调用引脚初始化
    sfc_port_init();  // 看这个函数
    // ...
}

// sfc_porting.c 中
void sfc_port_init(void)
{
    // 这里会设置 GPIO_19-24 为 SFC 模式
    hal_pinctrl_set_alt_mode(GPIO_19, ALT_MODE_SFC);  // CLK
    hal_pinctrl_set_alt_mode(GPIO_20, ALT_MODE_SFC);  // CS
    // ...
}

方法 3：使用 debug 日志

// 在初始化时添加调试输出
printf("SFC GPIO Configuration:\n");
printf("  CLK:  GPIO_%d\n", SFC_CLK);      // 应输出 19
printf("  CS:   GPIO_%d\n", SFC_CSN);      // 应输出 20
printf("  IO0:  GPIO_%d\n", SFC_IO0);      // 应输出 21
printf("  IO1:  GPIO_%d\n", SFC_IO1);      // 应输出 22

---

========================================================================================

📊 WS63 芯片的全部GPIO引脚分布

========================================================================================

GPIO 功能分布表

GPIO号    |  专属功能        |  复用功能              | SFC 用途
──────────┼──────────────────┼─────────────────────────┼──────────────
GPIO_0    |  通用 I/O        |  UART, PWM等           | -
GPIO_1    |  通用 I/O        |  SPI1, PWM等           | -
...       |  ...             |  ...                   | -
GPIO_19   |  **SFC_CLK**     |  时钟信号专用          | ✅ 时钟
GPIO_20   |  **SFC_CSN**     |  片选信号专用          | ✅ 片选
GPIO_21   |  **SFC_IO0**     |  数据线 0              | ✅ MOSI
GPIO_22   |  **SFC_IO1**     |  数据线 1              | ✅ MISO
GPIO_23   |  **SFC_IO2**     |  数据线 2（Quad）      | ⭕ WP
GPIO_24   |  **SFC_IO3**     |  数据线 3（Quad）      | ⭕ HOLD

注意：GPIO_19-24 是硬核 SFC 专用引脚，不能改，不支持复用到其他功能

---

========================================================================================

测试 GPIO 连接的快速脚本

========================================================================================

/**
 * 快速验证 SFC GPIO 连接
 * 编译: gcc -o test_gpio test_gpio.c
 * 运行: ./test_gpio
 */

#include <stdio.h>
#include "sfc.h"
#include "hal_gpio.h"

#define TEST_GPIO_PIN     GPIO_19  // 测试一个 SFC GPIO

int main(void) {
    printf("Testing SFC GPIO connections...\n");
    
    // 使用硬件 ID 来验证初始化
    uint32_t flash_id;
    errcode_t ret = hal_sfc_get_flash_id(&flash_id);
    
    if (ret == ERRCODE_SUCC && flash_id != 0xFFFFFFFF && flash_id != 0x000000) {
        printf("✅ GPIO 连接正常！\n");
        printf("   Flash ID: 0x%06X\n", flash_id);
        
        // 打印使用的 GPIO
        printf("   GPIO_19 (SFC_CLK):  OK\n");
        printf("   GPIO_20 (SFC_CSN):  OK\n");
        printf("   GPIO_21 (SFC_IO0):  OK\n");
        printf("   GPIO_22 (SFC_IO1):  OK\n");
        
        return 0;
    } else {
        printf("❌ GPIO 连接有问题！\n");
        printf("   Flash ID: 0x%08X (异常值)\n", flash_id);
        printf("   检查清单：\n");
        printf("   [ ] GPIO_19 连接到 Flash CLK\n");
        printf("   [ ] GPIO_20 连接到 Flash CS#\n");
        printf("   [ ] GPIO_21 连接到 Flash MOSI\n");
        printf("   [ ] GPIO_22 连接到 Flash MISO\n");
        
        return -1;
    }
}

---

========================================================================================

总结

========================================================================================

✅ 确认的 GPIO 映射

┌─────────────────────────────────────────────┐
│  WS63 NOR Flash/SFC 专用 GPIO 引脚          │
├─────────────────────────────────────────────┤
│  GPIO_19 ← CLK   (时钟)                    │
│  GPIO_20 ← CSN   (片选)                    │
│  GPIO_21 ← IO0   (MOSI/写)                 │
│  GPIO_22 ← IO1   (MISO/读)                 │
│  GPIO_23 ← IO2   (WP/写保护, Quad only)    │
│  GPIO_24 ← IO3   (HOLD, Quad only)        │
└─────────────────────────────────────────────┘

这些 GPIO 引脚是 硬核专用引脚，不能更改。如果你的开发板上 NOR Flash 连接到了不同的引脚，说明：

1. 板子设计有问题，或
2. 代码中的引脚映射有问题

建议用示波器观察实际的信号，或查看你的板子的原理图确认。