📚 课程目录第3章 SDK初始化与设备管理

3. SDK初始化与设备管理

Broadcom SDK 的初始化并不是一次简单的函数调用，而是一条从“库加载”到“设备可用”的完整链路。理解这条链路，才能写出一个真正能跑起来的最小初始化程序。本节围绕 SDK 启动流程、设备探测、配置加载、内存与 DMA 初始化四个环节展开，并给出一个可编译运行的最小示例。

一、SDK 启动的整体链路

Broadcom SDK（如 OpenNSL、SAI 或厂商 SDK）在用户态通常以共享库形式提供，初始化过程可以概括为：加载库 → 建立系统抽象层 → 探测设备 → 加载配置 → 初始化内存与 DMA → 打开设备 → 完成端口/表项初始化。每一步都有明确的输入与输出，任何一步失败都会导致后续无法继续。

二、设备探测：找到目标交换芯片

设备探测的目标是确定系统中存在哪些可管理的交换芯片，并获取其设备类型、单元号（unit）和访问方式。以 PCIe 接入的交换芯片为例，SDK 会扫描 PCIe 总线，匹配厂商 ID 与设备 ID，然后为每个匹配到的设备分配一个 unit 编号。对于通过 MDIO 或 SPI 接入的芯片，探测方式则是读取芯片 ID 寄存器（如 CMIC_DEVICE_ID）并与已知型号表比对。

探测阶段需要关注三个输出：设备类型（如 Tomahawk、Trident）、unit 编号（后续所有 API 的第一个参数）、访问句柄（PCIe BAR 映射地址或 MDIO 总线号）。如果探测不到设备，常见原因是驱动未加载、PCIe 链路未训练成功或芯片未上电。

三、配置加载：决定内存与 DMA 布局

Broadcom SDK 的配置通常来自一个文本文件（如 config.bcm），其中包含大量键值对。与内存和 DMA 直接相关的典型配置项包括：

dma_desc_size：DMA 描述符大小，影响每个队列可容纳的包数量；
pkt_dma_pool_size：DMA 缓冲池总大小，决定可同时驻留的报文数；
use_pci_dma：是否使用 PCIe DMA 通道；
mem_scan_interval：内存扫描周期，用于检测泄漏。

配置加载的实质是把这些键值对解析为 SDK 内部的结构体，并在内存初始化时按此分配。若配置项缺失，SDK 会使用默认值；若配置项非法（如 dma_desc_size 不是 2 的幂），初始化会直接返回错误。

四、内存与 DMA 初始化

内存初始化分为两部分：控制面内存和数据面 DMA 内存。控制面内存用于存放表项、端口状态和 SDK 内部结构，通常由 SDK 自行管理；数据面 DMA 内存需要与硬件共享，必须满足物理连续、对齐和缓存一致性要求。

在 Linux 用户态下，DMA 内存通常通过 mmap 映射大页（hugepage）或使用 dma_alloc_coherent（内核态）获得。关键参数包括：起始物理地址、大小、对齐粒度（通常 4KB 或 64B）。初始化完成后，SDK 会把这些内存注册到 DMA 引擎，并建立描述符环（descriptor ring）。

提示：DMA 内存一旦分配，其物理地址在设备生命周期内不应改变。若使用大页，建议在系统启动时预留，避免运行期碎片化导致分配失败。

五、最小可运行初始化程序

下面给出一个基于 OpenNSL 风格 API 的最小初始化程序框架。它完成了库加载、系统初始化、设备探测、配置加载、内存与 DMA 初始化、打开设备六个步骤。示例中的参数为教学假设值，实际使用时需根据芯片型号和板卡调整。

#include <stdio.h>
#include <stdlib.h>
#include <opennsl/error.h>
#include <opennsl/switch.h>

#define UNIT  0
#define CONFIG_FILE  "./config.bcm"

int main(void)
{
    int rv;

    /* 1. 初始化系统抽象层 */
    rv = opennsl_init();
    if (rv != OPENNSL_E_NONE) {
        fprintf(stderr, "opennsl_init failed: %s\n", opennsl_errmsg(rv));
        return -1;
    }

    /* 2. 加载配置文件（内存与 DMA 参数在此生效） */
    rv = opennsl_config_load(UNIT, CONFIG_FILE);
    if (rv != OPENNSL_E_NONE) {
        fprintf(stderr, "config load failed: %s\n", opennsl_errmsg(rv));
        opennsl_cleanup();
        return -1;
    }

    /* 3. 探测设备：扫描 PCIe，绑定 unit 0 */
    rv = opennsl_switch_probe(UNIT);
    if (rv != OPENNSL_E_NONE) {
        fprintf(stderr, "device probe failed: %s\n", opennsl_errmsg(rv));
        opennsl_cleanup();
        return -1;
    }

    /* 4. 初始化内存与 DMA（描述符环、缓冲池） */
    rv = opennsl_switch_mem_init(UNIT);
    if (rv != OPENNSL_E_NONE) {
        fprintf(stderr, "mem/dma init failed: %s\n", opennsl_errmsg(rv));
        opennsl_cleanup();
        return -1;
    }

    /* 5. 打开设备，进入可操作状态 */
    rv = opennsl_switch_open(UNIT);
    if (rv != OPENNSL_E_NONE) {
        fprintf(stderr, "switch open failed: %s\n", opennsl_errmsg(rv));
        opennsl_cleanup();
        return -1;
    }

    printf("SDK init OK, unit %d ready.\n", UNIT);

    /* 6. 此处可下发端口/表项操作，示例中直接关闭 */
    opennsl_switch_close(UNIT);
    opennsl_cleanup();
    return 0;
}

编译时需链接 SDK 库，例如：gcc -o init_demo init_demo.c -lopennsl -lpthread。运行前确保 config.bcm 存在且参数合法。若程序输出 SDK init OK, unit 0 ready.，说明初始化链路全部通过；若在某一步返回错误，可根据错误码定位是探测失败、配置非法还是 DMA 内存不足。

六、结果判断与常见问题

现象	可能原因	排查方向
probe 返回 `OPENNSL_E_NOT_FOUND`	PCIe 未枚举到芯片	检查 `lspci` 是否出现厂商 ID，确认驱动已加载
config_load 返回 `OPENNSL_E_PARAM`	配置项非法或缺失必填项	核对 `dma_desc_size` 是否为 2 的幂，检查文件路径
mem_init 返回 `OPENNSL_E_MEMORY`	DMA 内存分配失败	检查大页预留、`ulimit` 限制和物理内存余量
switch_open 返回 `OPENNSL_E_BUSY`	设备已被其他进程占用	确认无重复初始化，检查是否有残留进程持有句柄

注意：初始化失败后必须调用 opennsl_cleanup() 释放已分配资源，否则再次运行时会因资源残留而失败。DMA 内存尤其需要显式释放，避免物理内存泄漏。

掌握这条初始化链路后，后续的端口配置、VLAN 创建、ACL 下发才有稳定的运行基础。建议在最小程序跑通后，逐步增加端口初始化和表项操作，每增加一步都验证返回码，形成可复现的调试节奏。