p4runtime-go-controller

用于编写 P4Runtime 控制器的 Go SDK 和 p4ctl CLI。

文档网站 | 快速上手 | API 参考（英文） | English

• 协议基线为 P4Runtime 1.3.0。可用操作取决于目标实现，集成测试覆盖 BMv2。
• 使用 gRPC 和官方 P4Runtime protobuf 定义。
• 通过 log/slog 输出结构化日志，应用可通过 gRPC 拦截器接入度量和链路追踪。内置 metrics 接口及适配器仍在规划中。详见 日志与度量。

已发布版本按 Go 1 兼容性规则 保持同一主版本内的源码兼容。v2 与 v1.1.1 不保持源码兼容。详见 CHANGELOG 和 发布指南。

安装

需要 Go 1.26 或更新版本。在应用的 Go 模块目录中运行：

go get github.com/zhh2001/p4runtime-go-controller/v2@v2.0.1

CLI 安装及本地开发方式见 快速上手。

快速上手

启动项目自带的 BMv2 目标前，请按 快速上手指南 获取仓库并准备工具。原生模式需要本地 p4c-bm2-ss 和 simple_switch_grpc，Docker 模式也需要本地 P4 编译器。

package main

import (
    "context"
    "log"
    "time"

    "github.com/zhh2001/p4runtime-go-controller/v2/client"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    c, err := client.Dial(ctx, "127.0.0.1:9559",
        client.WithDeviceID(1),
        client.WithElectionID(client.ElectionID{High: 0, Low: 1}),
        client.WithInsecure(),
    )
    if err != nil {
        log.Fatalf("dial: %v", err)
    }
    defer c.Close()

    if err := c.BecomePrimary(ctx); err != nil {
        log.Fatalf("arbitration: %v", err)
    }
    log.Println("device 1 的主控制器已选出")
}

更多示例见 examples/ 目录，涵盖连接、管线安装、固定表项 L2 转发、Packet I/O 和计数器读取。

Counter、Meter 和 Register 的读取接口只用 -1 表示读取整个数组，写入必须指定非负索引。普通索引会在发送请求前按 P4Info 的数组大小校验。声明了 index_type_name 的索引由目标在转换后检查，SDK 保留其非负原值。

Pipeline 在构造时复制 P4Info 和设备配置，Info、Raw 及资源查询返回独立副本。修改输入或查询结果不会影响后续索引、校验及管线下发。跨次查询应通过资源 ID 判断身份。需要修改管线时，编辑 Info() 返回的副本，再构造新的 Pipeline。构造期间不能修改输入。指针循环及异常 nil 消息会在构造阶段报错，普通类型和资源规则仍由相应 API 或目标检查。详见 Pipeline 数据所有权。

Counter API 读写间接计数器，direct counter 使用原始 client API。写入同时发送 packets 和 bytes，由目标按声明单位处理。计数保留协议的 int64 原值，不截断为 32 位，也不将负值改为无符号十进制数。Write(ctx, name, index, 0, 0) 发送显式零值以清空对应计数。详见 Counter 读写。

Meter 写入会按 P4Info 校验类型，速率和突发量必须非负。EBurst 用于单速率三色 meter。双速率要求 PIR >= CIR，单速率要求 CIR = PIR、CBurst = PBurst。Write(Config{}) 发送显式全零配置，Reset 通过省略 Config 恢复默认 GREEN，不清空逐颜色计数器。旧 PI 使用 -1 表示默认行为的调用应改为 Reset。详见 Meter 配置。

功能矩阵

能力	状态
连接管理（TLS、keepalive、重连）	已就绪
Mastership / 仲裁（128 位 election ID）	已就绪
管线配置（VERIFY / RECONCILE / COMMIT）	已就绪
P4Info 按名索引	已就绪
表项写入（EXACT / LPM / TERNARY / RANGE / OPTIONAL）	已就绪
Counters、Meters、Registers	已就绪
PacketIn / PacketOut	已就绪
Digest 订阅与 Ack	已就绪
PRE（组播组 / 克隆会话）	已就绪（v1.1）
流生命周期结构化日志（log/slog）	已就绪
内置 metrics 采集	规划中
Prometheus 适配器	规划中
OpenTelemetry gRPC 拦截器示例	规划中

版本兼容

控制器版本	P4Runtime 规范
v1.x	1.3.0+
v2.x	1.3.0+

这里列出的是协议基础版本。可选资源和新字段需要目标支持。PRE 的字节端口要求 P4Runtime 1.4 或更新版本，备份副本要求 1.5 或更新版本。详见 PRE。

BMv2 集成测试覆盖控制面请求和以太网转发。仓库尚未验证 Stratum 和基于 Tofino 的硬件。验证范围及已知 BMv2 限制见 目标支持说明。

文档

• ARCHITECTURE.md：分层设计、数据流与架构决策。
• docs/quickstart.md：快速上手。
• v1 到 v2 升级指南：模块路径、源码和行为变化。
• docs/troubleshooting.md：常见问题。
• docs/observability.md：日志配置与采集入口。
• docs/glossary.md：术语表。

安全

漏洞报告流程见 SECURITY.md。请不要在公共 issue 中提交可能影响在线控制器的安全问题。

许可证

遵循 Apache License, Version 2.0，第三方归属信息见 NOTICE。

翻译同步状态：2026-10-13。若发现翻译落后于英文版，请提交 PR。