Android CameraServer架构理解

0. 全链路架构总览

+=====================================================================+ | App 层 (Java/Native) | | android.hardware.camera2 (Camera2 API) | | android.hardware.Camera (Camera1 API, 兼容垫片) | +=====================================================================+ | Binder IPC: AIDL (ICameraDeviceUser / ICamera) v +=====================================================================+ | Framework 层 (Camera Framework) | | CameraManager -> CameraDevice -> CameraCaptureSession | | CameraDeviceCallbacks (结果/事件回调) | | CaptureRequest / OutputConfiguration | +=====================================================================+ | Binder IPC: AIDL (ICameraService) v +=====================================================================+ | Camera Service 进程 (cameraserver) | | [本文重点分析的 libcameraservice] | | CameraService -> CameraDeviceClient -> Camera3Device | | CameraProviderManager -> ProviderInfo -> DeviceInfo3 | +=====================================================================+ | Binder IPC: AIDL (ICameraProvider/ICameraDeviceSession) [当前标准] | HIDL (旧版本兼容) v +=====================================================================+ | Camera Provider 进程 (vendor 分区) | | AIDL 接口实现 (当前标准) -> HAL3 接口调用 | | HIDL 接口 (旧版本兼容) | | 通过 dlopen 加载 HAL3 SO 库 | +=====================================================================+ | HAL3 接口 (camera_module_t / camera3_device_t) v +=====================================================================+ | Camera HAL (厂商实现) | | 通过 dlopen 加载 HAL3 SO 库 | | 处理图像处理流水线、流配置、请求处理 | +=====================================================================+ | v +=====================================================================+ | Camera Driver (内核层) | | V4L2 框架 | | v4l2_subdev 子设备 | +=====================================================================+ | I2C / MIPI CSI v +=====================================================================+ | Camera Hardware (硬件层) | | Sensor / ISP (IPE/BPS) / Lens Actuator / OIS / Flash / EEPROM | +=====================================================================+

核心设计理念:

• Treble 项目: 将平台厂商实现 (vendor) 与系统框架 (system) 隔离，Camera HAL Module 从 Camera Service 解耦到独立进程 Camera Provider
• 双重跨进程: App->Service 通过 AIDL，Service->Provider 通过 AIDL（当前标准，旧平台兼容 HIDL）
• 接口与实现分离: AIDL 接口定义暴露给厂商实现，HAL3 接口由厂商填充具体逻辑

各层职责:

1. 总体架构设计 (libcameraservice)

1.1 Camera Service 内部分层架构

+-------------------------------------------------------------------+ | App 进程 (Java/Native) | | android.hardware.camera2 / android.hardware.Camera | +-------------------------------------------------------------------+ | (Binder IPC: ICameraDeviceUser / ICamera) v +-------------------------------------------------------------------+ | cameraserver 进程 (libcameraservice) | | | | +--------------------+ +------------------------------------+ | | | CameraService | | CameraProviderManager | | | | (Binder 服务) |--->| (HAL Provider 发现) | | | | "media.camera" | | ProviderInfo[] -> DeviceInfo3 | | | +--------------------+ +------------------------------------+ | | | | | | +-------v-----------+ +-----------v-----------+ | | | API 层 | | HAL 传输层 | | | | api1/ Camera2Client| | aidl/ AidlCameraService| | | | api2/ CameraDevice | | hidl/ HidlCameraService| | | | Client | +------------------------+ | | +--------+----------+ | | | | v | | +--------v----------+ +-------------------+ | | | 客户端基类 | | Camera3Device | | | | Camera2ClientBase |<--->| (Device3 层) | | | +--------------------+ | AidlCamera3Device | | | | HidlCamera3Device | | | +-------------------+ | | | | | +---------------------------------v-------------------------------+| | | Stream 层 (device3/) || | | Camera3Stream -> Camera3IOStreamBase -> Camera3OutputStream || | | -> Camera3InputStream || | | -> Camera3SharedOutputStream || | | Camera3StreamSplitter / Camera3BufferManager || | +------------------------------------------------------------------+| +-------------------------------------------------------------------+ | (AIDL IPC) [当前标准，HIDL 为旧版本兼容] v +-------------------------------------------------------------------+ | Camera HAL (厂商实现) | | ICameraDeviceSession / ICameraDevice | +-------------------------------------------------------------------+

1.2 目录结构

1.3 Binder 服务注册与双重角色

CameraService继承BinderService<CameraService>，通过静态instantiate()注册为"media.camera"服务。服务入口点是AidlCameraService（NDK 稳定 AIDL），它包装了核心CameraService类。

Camera Service 的双重角色:

• 对上 (AIDL Server): 作为服务端，通过 AIDL 接口处理来自 Camera Framework 的跨进程请求
• 对下 (AIDL Client): 作为客户端，通过 AIDL 接口将请求转发至 Camera Provider（旧平台兼容 HIDL）

1.4 AIDL 接口定义

1.4 API1 状态说明

API1 (android.hardware.Camera)仍在使用，但不再是直接对接 Camera HAL 1.0。它作为兼容垫片运行在 HAL3 之上：

• App 调用ICamera(Binder) ->CameraService::connect()(API_1) ->Camera2Client(翻译层) ->Camera3Device(HAL3)
• HAL 1.0 已被明确拒绝 (ERROR_DEPRECATED_HAL)
• 代码库中无废弃标记、无移除计划、无 feature flag 控制 API1
• CameraProviderManager::getAPI1CompatibleCameraDeviceIds()等兼容性基础设施仍在维护

2. 核心模块详解

2.1 CameraService（中央服务）

文件:CameraService.h/.cpp(290KB 源码, 72KB 头文件 – 代码库中最大)

继承关系:

CameraService : BinderService<CameraService>, BnCameraService, IBinder::DeathRecipient, CameraProviderManager::StatusListener, IServiceManager::LocalRegistrationCallback, AttributionAndPermissionUtilsEncapsulator

关键内部类:

关键成员变量:

• mCameraProviderManager(sp) – HAL provider 管理
• mActiveClientManager(CameraClientManager) – 活跃客户端追踪/驱逐
• mCameraStates(map<string, shared_ptr>) – 每设备状态
• mFlashlight(sp) – 闪光灯/手电筒控制
• mServiceLock(Mutex) – 主服务锁
• mUidPolicy,mSensorPrivacyPolicy– 隐私执行
• mTorchStatusMap,mTorchClientMap– 手电筒状态追踪
• mVirtualDeviceCameraIdMapper– 虚拟设备 camera ID 重映射

ICameraService Binder 接口方法:

• getNumberOfCameras(),getCameraInfo(),getCameraCharacteristics()– 相机枚举
• connect()– API1 连接 (返回 ICamera)
• connectDevice()– API2 连接 (返回 ICameraDeviceUser)
• addListener()/removeListener()– 相机状态回调
• setTorchMode(),turnOnTorchWithStrengthLevel(),getTorchStrengthLevel()– 手电筒控制
• getConcurrentCameraIds(),isConcurrentSessionConfigurationSupported()– 并发相机
• injectCamera(),injectSessionParams()– 测试注入
• warmUp()– 预热相机设备
• notifySystemEvent(),notifyDeviceStateChange()– 系统事件

2.2 Camera2ClientBase（模板客户端基类）

文件:common/Camera2ClientBase.h/.cpp

Camera2ClientBase<TClientBase> : TClientBase, NotificationListener

API1 (Camera2Client) 和 API2 (CameraDeviceClient) 共享的模板基类。提供:

• connect()/disconnect()– 设备生命周期
• initialize(sp<CameraProviderManager>)– 调用initializeImpl()创建 Camera3Device
• 通知回调:notifyError(),notifyShutter(),notifyAutoFocus/Exposure/Whitebalance()
• notifyActive()/notifyIdle()– 空闲/活跃状态切换

关键成员:mDevice(sp) – HAL3 设备包装。

2.3 Camera2Client（API1 客户端）

文件:api1/Camera2Client.h/.cpp

Camera2Client : Camera2ClientBase<CameraService::Client>

在 HAL3 之上实现旧版android.hardware.Camera(API1) 接口。包含 API1 专用流水线组件:

• StreamingProcessor– 管理预览/录像流
• CaptureSequencer– 编排拍照序列
• JpegProcessor– JPEG 编码
• ZslProcessor– 零快门延迟处理
• CallbackProcessor– 回调数据传递
• Parameters– API1 参数管理

请求 ID 范围: 预览 (10M-20M), 录像 (20M-30M), 拍照 (30M-40M)。

2.4 CameraDeviceClient（API2 客户端）

文件:api2/CameraDeviceClient.h/.cpp

CameraDeviceClientBase : CameraService::BasicClient, BnCameraDeviceUser CameraDeviceClient : Camera2ClientBase<CameraDeviceClientBase>, FrameProcessorBase::FilteredListener

现代 Camera2 API 实现。关键方法:

• submitRequest()/submitRequestList()/cancelRequest()– 捕获请求管理
• beginConfigure()/endConfigure()/createStream()/deleteStream()– 流配置
• startStreaming()/waitUntilIdle()/flush()– 流生命周期
• prepare()/tearDown()– Buffer 预分配
• switchToOffline()– 切换到离线处理

关键成员:mFrameProcessor,mStreamMap,mConfiguredOutputs,mCompositeStreamMap,mResultMetadataQueue。

组合流:DepthCompositeStream,HeicCompositeStream,JpegRCompositeStream– 继承CompositeStream基类。

与 Camera3Device 的连接关系 (初始化时建立):

1. Camera2ClientBase::initialize()调用Camera3Device::initialize()初始化设备
2. Camera3Device::setNotifyCallback()将 Camera2ClientBase 注册为事件回调接收者
3. 实例化FrameProcessorBase并传入Camera3Device，建立 metadata 中转联系
4. FrameProcessorBase启动后台线程，等待 Camera3Device 的结果
5. Camera3Device 事件 (notify) -> 直接给 CameraDeviceClient
6. Camera3Device metadata -> FrameProcessorBase -> CameraDeviceClient

2.5 Camera3Device（HAL3 设备）

文件:device3/Camera3Device.h/.cpp

Camera3Device : CameraDeviceBase, SetErrorInterface, InflightRequestUpdateInterface, RequestBufferInterface, FlushBufferInterface

核心设备抽象。抽象类 –AidlCamera3Device和HidlCamera3Device提供传输层特定实现。

关键内部类:

状态机:

STATUS_ERROR -> STATUS_UNINITIALIZED -> STATUS_UNCONFIGURED -> STATUS_CONFIGURED -> STATUS_ACTIVE

关键成员:

• mInterface(sp) – HAL 会话接口
• mOutputStreams(StreamSet) – 所有活跃输出流
• mInputStream(sp) – 可选输入流
• mRequestThread(sp) – 请求提交线程
• mStatusTracker(sp) – 空闲/活跃状态追踪
• mBufferManager(sp) – 共享 Buffer 管理
• mInFlightMap– 在途请求追踪
• mDistortionMappers,mZoomRatioMappers,mRotateAndCropMappers,mUHRCropAndMeteringRegionMappers– 每相机 metadata 映射器

Camera3Device 作为 ICameraDeviceCallback 的角色:

• Camera3Device 实现了 Provider 端的ICameraDeviceCallback接口
• 初始化时通过CameraProviderManager::openSession()将自身作为回调传入 Provider
• Provider 通过此回调将结果 (notify/processCaptureResult/returnStreamBuffers) 回传给 Camera3Device
• Camera3Device 内部再将事件和数据分发给 CameraDeviceClient 和 FrameProcessorBase

2.6 AidlCamera3Device / HidlCamera3Device（传输层）

AidlCamera3Device(device3/aidl/AidlCamera3Device.h/.cpp) —当前标准:

• AidlHalInterface包装ICameraDeviceSession(AIDL)
• 使用AidlRequestMetadataQueue(FMQ) 实现快速请求提交
• AidlCameraDeviceCallbacks实现BnCameraDeviceCallback(processCaptureResult, notify, requestStreamBuffers, returnStreamBuffers)
• 通过std::shared_ptr管理（NDK 后端要求）

HidlCamera3Device(device3/hidl/HidlCamera3Device.h/.cpp) —旧版本兼容:

• HidlHalInterface包装多版本 HIDL 会话 (V3_2 至 V3_7)
• 使用RequestMetadataQueue(HIDL FMQ)
• 版本化会话指针:mHidlSession(V3_2),mHidlSession_3_3…mHidlSession_3_7

2.7 CameraProviderManager（HAL Provider 管理器）

文件:common/CameraProviderManager.h/.cpp

CameraProviderManager : hidl::manager::V1_0::IServiceNotification, IServiceManager::LocalRegistrationCallback

发现并管理所有 Camera HAL provider（当前标准 AIDL，兼容旧版 HIDL）。

关键内部结构:

关键方法:initialize(),getCameraCount(),getCameraDeviceIds(),getCameraCharacteristics(),openAidlSession(),openHidlSession(),setTorchMode(),hasFlashUnit(),isSessionConfigurationSupported(),warmUp()。

2.8 Stream 层次结构

Camera3StreamInterface (纯虚接口) | v Camera3Stream (基类, 继承 camera_stream C 结构体) | v Camera3IOStreamBase (增加 buffer 计数、帧计数) | +---> Camera3OutputStream (输出到 Surface 消费者) | | | +---> Camera3SharedOutputStream (通过 StreamSplitter 支持多 Surface) | +---> Camera3InputStream (输入/重处理, 来自 BufferItemConsumer)

Camera3OutputStream:处理 Buffer 出队/入队到 Surface、BufferManager 集成、批量操作、PreviewFrameSpacer (显示 Vsync 同步)、镜像模式、丢帧支持。

Camera3SharedOutputStream:通过Camera3StreamSplitter支持最多 4 个消费者 Surface。用于共享相机会话。

Camera3FakeStream:用于测试/注入的伪流。

2.9 StatusTracker

文件:device3/StatusTracker.h/.cpp

StatusTracker : Thread

通过聚合组件状态 (流、RequestThread、BufferManager) 追踪空闲/活跃状态。后台线程处理状态变更事件和合并的 fence。当所有组件都空闲且所有 fence 信号就绪时，通过notifyStatus()通知 Camera3Device。

2.10 CameraFlashlight

文件:CameraFlashlight.h/.cpp

FlashControlBase (抽象) | +---> ProviderFlashControl (HAL provider v2.4+) CameraFlashlight (门面)

管理闪光单元发现和手电筒控制。使用CameraProviderManager进行 provider 级手电筒控制。旧的 HAL v1 向后兼容模式已移除。

2.11 Buffer 管理

Camera3BufferManager(device3/Camera3BufferManager.h/.cpp): 跨流管理共享 Buffer 池。动态分配/授予/回收 Buffer。

Camera3StreamSplitter(device3/Camera3StreamSplitter.h/.cpp): 将单个 HAL 输出流拆分到多个消费者 Surface。由 Camera3SharedOutputStream 使用。

PreviewFrameSpacer(device3/PreviewFrameSpacer.h/.cpp): 重新调整预览帧间距以匹配显示 Vsync 时序。

2.12 CameraServiceWatchdog（看门狗）

文件:CameraServiceWatchdog.h/.cpp

功能：检测 Camera HAL 的异常状态（卡死/超时），超时后杀死相关进程并生成 tombstone 用于调试。

工作机制：

• 独立线程，通过循环计数器（cycle counter）监控每个被监视线程的执行时间
• 周期长度：kCycleLengthMs = 100ms（每个 cycle 100ms）
• 最大周期：kMaxCycles = 650（即最大容忍65 秒）

使用方式：通过WATCH()宏包裹需要监控的函数调用：

#defineWATCH(toMonitor)watchThread([&](){returntoMonitor;},gettid(),__FUNCTION__)

当前监控的调用（Camera3Device.cpp）：

• interface->close()(line 384) — HAL 关闭操作
• mRequestThread->flush()(line 1899) — flush 操作

超时处理流程：

1. 周期 0~487 (0~48.7s): 正常监控，cycles 递增
2. cycles == mMaxCycles * 3/4(487): 预警告 — 通知 CameraServiceProxy dump 所有相关进程的 stack trace
3. cycles >= mMaxCycles(650 = 65s): 触发 abort
   • 激活 Perfetto trace（300s 冷却期）
   • 记录 close 日志（CAMERA_WATCHDOG_ERROR）
   • kill(provider_pids, SIGABRT)— 杀死 Provider 进程
   • abort()— 杀死 cameraserver 进程，生成 tombstone

关键代码位置：

• 初始化:Camera3Device.cpp:283— 创建并启动 watchdog 线程
• 监控 close():Camera3Device.cpp:384
• 监控 flush():Camera3Device.cpp:1899
• 启用/禁用:Camera3Device.cpp:4774—setCameraServiceWatchdog()

禁用方式：

adb shell cmd media.camera set-watchdog0# 禁用adb shell cmd media.camera set-watchdog1# 启用

2.13 关键类间关系（继承、组合、聚合、关联）

继承层次

Core Device 继承链：

RefBase └── FrameProducer └── CameraDeviceBase └── Camera3Device ├── AidlCamera3Device │ └── AidlCamera3SharedDevice └── HidlCamera3Device

Stream 继承链：

RefBase └── Camera3StreamInterface ├── Camera3OutputStreamInterface └── Camera3Stream └── Camera3IOStreamBase ├── Camera3OutputStream │ └── Camera3SharedOutputStream └── Camera3InputStream

Client 继承链：

RefBase └── BasicClient ├── Client (BnCamera) [API1] │ └── Camera2ClientBase<Client> │ └── Camera2Client [API1] └── CameraDeviceClientBase (BnCameraDeviceUser) └── Camera2ClientBase<CameraDeviceClientBase> └── CameraDeviceClient [API2]

HAL Interface 继承链：

HalInterface (Camera3Device 内部类) ├── AidlHalInterface └── HidlHalInterface RequestThread ├── AidlRequestThread └── HidlRequestThread

组合关系（强生命周期 sp<>, unique_ptr<>）

CameraService 拥有：

• sp<CameraProviderManager>— Provider 管理器
• sp<CameraFlashlight>— 闪光灯控制
• sp<UidPolicy>,sp<SensorPrivacyPolicy>— 策略管理
• CameraClientManager— 管理所有sp<BasicClient>
• vector<sp<ServiceListener>>— 服务监听器列表

Camera2ClientBase<T> 拥有：

• sp<CameraDeviceBase> mDevice— 实际为 Camera3Device 子类
• shared_ptr<CameraServiceProxyWrapper>

CameraDeviceClient (API2) 拥有：

• sp<FrameProcessorBase>— 帧处理器
• map<SurfaceKey, sp<CompositeStream>>— 复合流映射
• unique_ptr<MetadataQueue>— FMQ 结果队列

Camera3Device 拥有：

• sp<HalInterface> mInterface— HAL 接口（Aidl/Hidl）
• sp<RequestThread>— 请求提交线程
• sp<PreparerThread>— Buffer 预分配线程
• sp<StatusTracker>— 状态追踪
• sp<Camera3BufferManager>— Buffer 管理
• sp<Camera3DeviceInjectionMethods>— 注入方法
• StreamSet— 输出流集合（包含 sp<Camera3Stream>）

Camera3OutputStream 拥有：

• sp<Surface> mConsumer— 消费者 Surface
• sp<Camera3BufferManager>— Buffer 管理（外部设置）
• sp<BufferProducerListener>— 生产者监听

AidlHalInterface 拥有：

• shared_ptr<ICameraDeviceSession>— AIDL 会话
• shared_ptr<AidlRequestMetadataQueue>— 请求 FMQ

HidlHalInterface 拥有：

• sp<ICameraDeviceSession>V3_2~V3_7 — 多版本 HIDL 会话
• shared_ptr<RequestMetadataQueue>— 请求 FMQ

聚合关系（弱生命周期 wp<>, 原始指针）

Camera3Device 持有弱引用：

• wp<NotificationListener>— 通知监听（CameraDeviceClient）

RequestThread 持有弱引用：

• wp<Camera3Device>— 父设备
• wp<NotificationListener>— 通知监听

FrameProcessorBase 持有弱引用：

• wp<FrameProducer>— 设备（Camera3Device）

Camera3Stream 持有弱引用：

• wp<Camera3StreamBufferFreedListener>— Buffer 释放监听
• wp<StatusTracker>— 状态追踪

AidlCameraDeviceCallbacks 持有弱引用：

• wp<AidlCamera3Device>— 父设备

关联关系（非拥有）

AidlCameraService → CameraService：

• CameraService* mCameraService（原始指针，不拥有）— AidlCameraService 包装 CameraService 的 AIDL 接口

Camera3OutputUtils / Camera3OutputUtilsTemplated：

• 自由函数命名空间，通过参数引用 CaptureOutputStates 等结构体操作 StreamSet、InFlightMap 等

所有权链总览

CameraService ├── sp<CameraProviderManager> ├── sp<CameraFlashlight> ├── CameraClientManager (管理 sp<BasicClient>) └── vector<sp<ServiceListener>> Camera2ClientBase<T> ├── sp<CameraDeviceBase> (实际 Camera3Device) └── shared_ptr<CameraServiceProxyWrapper> Camera3Device ├── sp<HalInterface> (Aidl/Hidl) ├── sp<RequestThread> ├── sp<PreparerThread> ├── sp<StatusTracker> ├── sp<Camera3BufferManager> ├── StreamSet (sp<Camera3Stream>) └── wp<NotificationListener> (CameraDeviceClient) Camera3OutputStream ├── sp<Surface> mConsumer ├── sp<Camera3BufferManager> └── wp<Camera3StreamBufferFreedListener> AidlHalInterface ├── shared_ptr<ICameraDeviceSession> └── shared_ptr<AidlRequestMetadataQueue> FrameProcessorBase └── wp<FrameProducer> (Camera3Device)

设计模式