Configuration Descriptor
 └── Interface Association Descriptor (IAD)
      └── Video Control (VC) Interface
           └── VC Header Descriptor
           └── Input Terminal Descriptor (Camera)
           └── Processing Unit Descriptor
           └── Extension Unit Descriptor (厂商私有控制)
           └── Output Terminal Descriptor (USB Streaming)
      └── Video Streaming (VS) Interface (Alternate Setting 0 = 零带宽)
           └── VS Input Header Descriptor
           └── **Format Descriptors** (每种像素格式一个)
                └── **Frame Descriptors** (每种分辨率/帧率组合一个)
           └── Color Matching Descriptor (可选)

// 统一像素格式枚举（映射 FourCC）
enum class PixelFormat : uint32_t {
    YUY2  = FOURCC('Y','U','Y','2'),
    NV12  = FOURCC('N','V','1','2'),
    MJPEG = FOURCC('M','J','P','G'),
    H264  = FOURCC('H','2','6','4'),
    // ... 可扩展
};

struct FrameSpec {
    uint32_t width;
    uint32_t height;
    // 支持离散帧率列表或连续范围
    std::vector<uint32_t> discreteIntervals; // 100ns 单位
    struct { uint32_t min, max, step; } continuousRange;
    bool isContinuous() const { return continuousRange.step > 0; }
};

struct FormatCapability {
    PixelFormat pixelFormat;
    uint8_t formatIndex;      // bFormatIndex
    std::vector<FrameSpec> frames; // 索引对应 bFrameIndex
    bool supportsH264AnnexB() const { return pixelFormat == PixelFormat::H264; }
};

struct DeviceCapability {
    std::string devicePath;   // 平台唯一标识
    std::string friendlyName;
    uint16_t vid, pid;
    std::vector<FormatCapability> formats;
};

flowchart TD
    A[打开设备句柄] --> B{平台分支}
    B -->|Windows MF| C[枚举 IMFMediaType]
    B -->|Linux V4L2| D[VIDIOC_ENUM_FMT + ENUM_FRAMESIZES + ENUM_FRAMEINTERVALS]
    B -->|macOS| E[AVFoundation formats + IOKit 补充]
    B -->|Android| F[UsbDeviceConnection.controlTransfer 解析描述符]
    C --> G[归一化填充 DeviceCapability]
    D --> G
    E --> G
    F --> G
    G --> H[缓存至 CapabilityRegistry]
    H --> I[返回给上层策略引擎]

struct BusinessRequirement {
    // 硬性约束
    uint32_t minWidth, minHeight;
    uint32_t maxWidth, maxHeight;
    uint32_t targetFps;           // 期望帧率
    bool preferHardwareCodec;     // 优先 H.264/H.265 减轻 CPU
    bool lowLatencyMode;          // 优先 MJPEG/YUY2 低延迟
    size_t maxBandwidthBps;       // 带宽上限（如 USB 2.0 约 35-40 MB/s）
    // 软性权重
    double wResolution = 1.0;
    double wFrameRate  = 1.2;
    double wCpuCost    = 0.8;     // 解码开销惩罚
    double wLatency    = 1.5;
};

double ScoreFormat(const FormatCapability& fmt, const FrameSpec& frame,
                   const BusinessRequirement& req) {
    // 1. 硬性过滤
    if (frame.width < req.minWidth || frame.width > req.maxWidth) return -1;
    if (frame.height < req.minHeight || frame.height > req.maxHeight) return -1;

    // 2. 计算可达成帧率
    double achievableFps = CalcMaxAchievableFps(frame, req.maxBandwidthBps);
    if (achievableFps < req.targetFps * 0.9) return -1; // 容差 10%

    // 3. 多维度加权
    double score = 0;
    score += req.wResolution * (frame.width * frame.height) / (1920.0*1080.0);
    score += req.wFrameRate * (achievableFps / req.targetFps);
    
    // CPU 成本估算：H.264 硬解=0.2, MJPEG 软解=0.6, YUY2 免解码=0.1
    double cpuCost = EstimateCpuCost(fmt.pixelFormat);
    score -= req.wCpuCost * cpuCost;
    
    // 延迟估算：压缩格式通常引入 1-2 帧缓冲
    double latencyPenalty = (fmt.pixelFormat == PixelFormat::YUY2 || fmt.pixelFormat == PixelFormat::NV12) ? 0 : 1.5;
    score -= req.wLatency * latencyPenalty;

    return score;
}

bool NegotiateBestFormat(DeviceHandle& dev, const BusinessRequirement& req,
                         FormatCapability* outFmt, FrameSpec* outFrame) {
    auto caps = CapabilityRegistry::Get(dev.devicePath);
    std::vector<Candidate> candidates;
    
    for (auto& fmt : caps.formats) {
        for (size_t fi = 0; fi < fmt.frames.size(); ++fi) {
            double s = ScoreFormat(fmt, fmt.frames[fi], req);
            if (s > 0) candidates.push_back({&fmt, &fmt.frames[fi], s, (uint8_t)fi});
        }
    }
    if (candidates.empty()) return false;
    
    std::sort(candidates.begin(), candidates.end(),
              [](auto& a, auto& b){ return a.score > b.score; });
    
    // 尝试 Top-N 回退
    for (size_t i = 0; i < std::min<size_t>(candidates.size(), 3); ++i) {
        if (dev.ProbeCommit(candidates[i].fmt->formatIndex,
                            candidates[i].frameIndex,
                            candidates[i].frame->discreteIntervals[0])) {
            *outFmt = *candidates[i].fmt;
            *outFrame = *candidates[i].frame;
            return true;
        }
        LOG_WARN("ProbeCommit failed for top-{} candidate, fallback...", i+1);
    }
    return false;
}

+----------------------------------------------------------+
|  Application Layer (业务层: 视频会议/录制/推流 SDK)       |
+----------------------------------------------------------+
|  Camera Abstraction Layer (统一接口: Open/Start/Stop/Control) |
|  - IDeviceEnumerator                                     |
|  - ICapabilityProvider                                   |
|  - IFormatNegotiator                                     |
|  - IStreamController                                     |
+----------------------------------------------------------+
|  Platform Adapters (平台适配层)                           |
|  - WindowsMFAdapter   - LinuxV4L2Adapter                 |
|  - MacOSAVFAadapter   - AndroidUSBAdapter                |
+----------------------------------------------------------+
|  OS Kernel / System Framework                            |
+----------------------------------------------------------+

template<typename T>
concept CameraAdapter = requires(T a, DeviceCapability& cap) {
    { a.EnumerateDevices() } -> std::same_as<std::vector<DeviceInfo>>;
    { a.OpenDevice(std::string_view) } -> std::same_as<DeviceHandle>;
    { a.QueryCapability(DeviceHandle&, DeviceCapability&) } -> std::same_as<bool>;
    { a.ProbeCommit(DeviceHandle&, uint8_t, uint8_t, uint32_t) } -> std::same_as<bool>;
    { a.StartStream(DeviceHandle&, FrameCallback) } -> std::same_as<bool>;
    { a.StopStream(DeviceHandle&) } -> std::same_as<void>;
    { a.CloseDevice(DeviceHandle&) } -> std::same_as<void>;
};

// 跨平台统一句柄：封装 FD / HANDLE / AHardwareBuffer
struct ZeroCopyBuffer {
    enum class BackendType { DMA_BUF, D3D11_TEXTURE, HARDWARE_BUFFER, CPU_FALLBACK } backend;
    uint32_t width, height, stride;
    PixelFormat format;
    uint64_t timestampUs;      // 单调时钟时间戳
    uint32_t frameId;          // 单调递增帧序号
    
    // 平台特有字段（联合体节省内存）
    union {
        int dmaBufFd;                    // Linux: dmabuf fd
        struct { void* texture; uint32_t subresource; } d3d11; // Windows: ID3D11Texture2D*
        AHardwareBuffer* hardwareBuffer; // Android: AHardwareBuffer*
        void* cpuPtr;                    // Fallback: malloc/mmap addr
    };
    size_t size;                         // 缓冲区总大小
    
    // 引用计数 + 自定义释放器（跨进程/跨 API 传递安全）
    std::shared_ptr<void> owner; 
};

class FrameFence {
public:
    // 阻塞等待 GPU/编码器消费完成，超时返回 false
    virtual bool Wait(uint32_t timeoutMs) = 0;
    // 信号量置位（生产者填充完毕 / 消费者释放）
    virtual void Signal() = 0;
    // 导出跨进程/跨 API 句柄
    virtual std::variant<int, HANDLE, VkFence> ExportHandle() = 0;
    static std::unique_ptr<FrameFence> Create(ZeroCopyBuffer::BackendType type);
};

// Linux 实现：封装 sync_file (dma_fence) / timeline semaphore
// Windows 实现：封装 ID3D11Fence / KeyedMutex (D3D11) / D3D12 Fence
// Android 实现：封装 AHardwareBuffer_fence / SyncFence
// Vulkan 通用：VkSemaphore / VkFence (VK_KHR_external_semaphore_fd)

graph LR
    A[UVC Device] -->|V4L2 DMABUF CAPTURE| B[Kernel Videobuf2]
    B -->|Export DMABUF FD| C[User Space: ZeroCopyBuffer Pool]
    C -->|Import DMABUF| D[V4L2 M2M Encoder (H.264/HEVC)]
    C -->|Import DMABUF| E[EGL/Vulkan Renderer]
    D -->|Bitstream| F[Network/RTP]
    E -->|Swapchain| G[Display]
    style C fill:#f9f,stroke:#333

enum class DfuStatus { IDLE, DOWNLOADING, VERIFYING, MANIFEST, COMPLETE, ERROR };

struct DfuProgress {
    DfuStatus status;
    uint32_t bytesTransferred;
    uint32_t totalBytes;
    float percent;          // 0.0 ~ 1.0
    std::string errorMsg;   // 非空表示失败
    bool canCancel;
};

class IDfuUpdater {
public:
    virtual ~IDfuUpdater() = default;
    // 扫描支持 DFU 的设备 (需匹配 VID/PID/Interface Class)
    virtual std::vector<DeviceInfo> ScanDfuDevices() = 0;
    // 开始升级 (异步，进度通过 callback 回调)
    virtual bool StartUpgrade(const DeviceInfo& dev, 
                              std::istream& firmwareImage, // 支持加密流/网络流
                              std::function<void(const DfuProgress&)> cb) = 0;
    virtual void Cancel() = 0;
    // 升级后强制重新枚举 (触发 USB Reset)
    virtual void TriggerReEnumerate(const DeviceInfo& dev) = 0;
};

stateDiagram-v2
    [*] --> appIDLE
    appIDLE --> appDETACH : 用户发起升级 / 检测新版本
    appDETACH --> dfuIDLE : USB Reset + 重新枚举为 DFU Interface
    dfuIDLE --> dfuDNLOAD_SYNC : SET_CUR(DFU_DNLOAD, wBlockNum=0)
    dfuDNLOAD_SYNC --> dfuDNBUSY : 设备处理中
    dfuDNBUSY --> dfuDNLOAD_IDLE : GET_STATUS OK
    dfuDNLOAD_IDLE --> dfuDNLOAD_SYNC : 发送下一块 (wBlockNum++)
    dfuDNLOAD_IDLE --> dfuMANIFEST_SYNC : 最后一块 (wLength=0)
    dfuMANIFEST_SYNC --> dfuMANIFEST : 设备烧写 Flash
    dfuMANIFEST --> dfuMANIFEST_WAIT_RESET : 烧写完成
    dfuMANIFEST_WAIT_RESET --> appIDLE : USB Reset 重新枚举为 Application
    dfuMANIFEST --> dfuERROR : 校验失败/掉电
    dfuERROR --> dfuIDLE : CLR_STATUS 恢复

// 关键指标定义 (Go 伪代码，对应 C++ 埋点)
var (
    // 设备层
    CameraDeviceEnumeratedTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
        Name: "camera_device_enumerated_total", Help: "设备枚举总次数"},
        []string{"platform", "vid", "pid", "result"}) // result: success/permission_denied/not_found
    
    CameraCapabilityProbeDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{
        Name: "camera_capability_probe_duration_seconds", Buckets: []float64{.01, .05, .1, .5, 1}},
        []string{"platform", "format_count"})

    // 协商层
    CameraFormatNegotiationResult = prometheus.NewCounterVec(prometheus.CounterOpts{
        Name: "camera_format_negotiation_result_total", Help: "协商结果"},
        []string{"target_fps", "target_res", "selected_format", "selected_fps", "fallback_count", "result"}) // result: success/timeout/bandwidth_exceed/unsupported

    // 流层 (零拷贝关键)
    CameraFrameLatencyE2E = prometheus.NewHistogramVec(prometheus.HistogramOpts{
        Name: "camera_frame_latency_e2e_ms", Buckets: prometheus.ExponentialBuckets(1, 2, 10)},
        []string{"pipeline", "format", "resolution"}) // 从 V4L2 DQBUF / MF Sample Ready 到 Encoder/Renderer 提交完成
    
    CameraFrameDropTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
        Name: "camera_frame_drop_total", Help: "丢帧计数"},
        []string{"reason"}) // reason: buffer_full/late_timestamp/decoder_error/usb_error
    
    CameraZeroCopyBufferPoolUsage = prometheus.NewGaugeVec(prometheus.GaugeOpts{
        Name: "camera_zero_copy_buffer_pool_usage", Help: "零拷贝缓冲池使用率"},
        []string{"pool_name", "state"}) // state: free/in_use/starved
    
    // DFU 层
    CameraDfuUpgradeDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{
        Name: "camera_dfu_upgrade_duration_seconds", Buckets: []float64{10, 30, 60, 120, 300}},
        []string{"fw_version", "result"})
)

// 每次 OpenDevice 生成 TraceID，贯穿 Probe -> Negotiate -> StartStream -> FrameCallback
struct CameraTraceContext {
    std::string traceId;        // UUID v7 (含时间戳)
    std::string sessionId;      // 业务会话 ID (如会议 ID)
    std::string devicePath;
    uint32_t pid, tid;          // 进程/线程 ID
};

// 宏定义统一日志格式 (JSON Lines 便于 ELK/Loki 采集)
#define CAM_LOG(level, ctx, fmt, ...) 
    Logger::Log(level, {{"trace_id", ctx.traceId}, {"session_id", ctx.sessionId}, 
                        {"device", ctx.devicePath}, {"pid", ctx.pid}, {"tid", ctx.tid}}, 
                        fmt, ##__VA_ARGS__)

// 使用示例
CAM_LOG(INFO, ctx, "ProbeCommit success: fmt_idx={} frame_idx={} interval={}us", 
        fmtIdx, frameIdx, intervalUs);
CAM_LOG(WARN, ctx, "Frame dropped: reason=buffer_full pool_usage={}/{}", used, total);

groups:
- name: camera_pipeline_alerts
  rules:
  - alert: CameraHighFrameDropRate
    expr: |
      sum(rate(camera_frame_drop_total[1m])) by (device, reason) 
      / sum(rate(camera_frame_captured_total[1m])) by (device) > 0.05
    for: 2m
    labels:
      severity: warning
    annotations:
      summary: "设备 {{ $labels.device }} 丢帧率超过 5% (原因: {{ $labels.reason }})"
      runbook_url: "https://wiki.example.com/runbook/camera-frame-drop"

  - alert: CameraZeroCopyPoolStarved
    expr: |
      camera_zero_copy_buffer_pool_usage{state="starved"} > 0
    for: 30s
    labels:
      severity: critical
    annotations:
      summary: "零拷贝缓冲池 {{ $labels.pool_name }} 耗尽，可能导致延迟抖动或丢帧"

  - alert: CameraDfuFailureRateHigh
    expr: |
      sum(rate(camera_dfu_upgrade_duration_seconds_count{result="failed"}[1h])) 
      / sum(rate(camera_dfu_upgrade_duration_seconds_count[1h])) > 0.1
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "近 1 小时 DFU 升级失败率超过 10%，需排查固件签名/设备兼容性"

+------------------+      USB/IP over Ethernet      +------------------------+
|  CI Runner (x86) | <----------------------------> |  Device Under Test (DUT) |
|  (Test Orchestrator)                          |  (Physical Camera /      |
|  - pytest / gtest                             |   FPGA Simulator)        |
|  - Allure Report                              |                          |
+------------------+                            +------------------------+
        ^                                                ^
        |                                                |
        |  Control API (REST/gRPC)                       |  Video Signal Input
        |                                                |  (HDMI/DP -> PG -> USB Capture)
        v                                                v
+------------------+                            +------------------------+
|  USB Hub Controller|------------------------->|  Programmable USB Hub    |
|  (Acroname API)    |   Power Cycle / Port     |  (Port Enable/Disable,   |
|  - Port Power Ctrl |   Disable / Re-enumerate |   Voltage/Current Monitor)|
|  - Voltage Monitor |                          +------------------------+
+------------------+

# conftest.py - 会话级 Hub 控制 fixture
import pytest
import requests # Acroname Hub REST API

@pytest.fixture(scope="session")
def hub_controller(config):
    hub = AcronameHubController(config["hub_ip"], config["hub_token"])
    hub.enable_all_ports() # 初始化全开
    yield hub
    hub.disable_all_ports() # 收尾断电

# test_enumeration.py
def test_hotplug_1000_cycles(hub_controller, camera_adapter, port=1):
    """压力测试：单端口 1000 次热插拔枚举"""
    success = 0
    for i in range(1000):
        # 1. 断电模拟拔出
        hub_controller.set_port_power(port, False)
        time.sleep(0.5) # 设备掉电时间
        
        # 2. 上电模拟插入
        hub_controller.set_port_power(port, True)
        
        # 3. 等待枚举稳定 (轮询适配层)
        dev_info = wait_for_enumeration(camera_adapter, timeout=5.0, vid=0x1234, pid=0x5678)
        assert dev_info is not None, f"Cycle {i}: Enumeration timeout"
        
        # 4. 快速能力探测 + 启流 1 帧验证
        caps = camera_adapter.query_capability(dev_info.path)
        assert caps.formats, f"Cycle {i}: No formats"
        
        handle = camera_adapter.open_device(dev_info.path)
        frame = camera_adapter.grab_one_frame(handle, timeout=2.0)
        assert frame and frame.width > 0, f"Cycle {i}: Grab frame failed"
        camera_adapter.close_device(handle)
        
        success += 1
    
    # 生成 Allure 报告附件
    allure.attach(f"Success Rate: {success}/1000", name="Hotplug Summary")
    assert success == 1000, f"Hotplug stability failed: {success}/1000"

# test_bandwidth.py
def test_multi_camera_bandwidth_saturation(hub_controller, camera_adapter, ports=[1,2,3,4]):
    """并发 4 路 1080p@30 MJPEG 启流，验证带宽仲裁与降级"""
    handles = []
    for p in ports:
        hub_controller.set_port_power(p, True)
        dev = wait_for_enumeration(camera_adapter, vid=0x1234, pid=0x5678)
        h = camera_adapter.open_device(dev.path)
        # 协商 1080p@30 MJPEG (约 150-200 Mbps/路)
        ok = camera_adapter.negotiate_and_start(h, width=1920, height=1080, fps=30, fmt="MJPEG")
        assert ok, f"Port {p} negotiate failed"
        handles.append(h)
    
    # 运行 60s 监控丢帧/带宽
    time.sleep(60)
    stats = [camera_adapter.get_stream_stats(h) for h in handles]
    for i, s in enumerate(stats):
        assert s.drop_rate < 0.01, f"Port {ports[i]} drop rate {s.drop_rate} > 1%"
        # 验证实际帧率接近 30
        assert 28 < s.actual_fps < 32, f"Port {ports[i]} fps {s.actual_fps} abnormal"
    
    for h in handles: camera_adapter.stop_stream(h); camera_adapter.close_device(h)

sequenceDiagram
    participant App
    participant CameraSDK
    participant OS_Permission
    participant User
    App->>CameraSDK: RequestCameraAccess(purpose="video_meeting")
    CameraSDK->>OS_Permission: Check/System Request (AVFoundation/Manifest/CameraManager)
    OS_Permission->>User: 系统弹窗: "App 想访问摄像头用于视频会议"
    User-->>OS_Permission: Allow / Deny / Ask Every Time
    OS_Permission-->>CameraSDK: Grant / Deny
    alt Grant
        CameraSDK->>App: Callback(Success, DeviceList)
    else Deny
        CameraSDK->>App: Callback(Denied, Reason=PERMISSION_DENIED)
        App->>User: 引导去设置页开启 (Deep Link: app-settings:)
    end