AOSP 13相机源码地图：从Camera2到HAL层的代码路径与调试指南

刚接触AOSP源码的人，十有八九都会在“相机相关代码到底在哪”这个问题上卡壳。搜索“camera”关键字，几百上千个结果扑面而来，分布在几十个目录里，根本分不清哪个是应用层、哪个是框架层、哪个是HAL层。这不是你能力不行，而是相机这模块在Android里确实是个异常庞大的横向体系，横跨了从Java到C++再到内核驱动的所有层级。我在AOSP 13（对应Android 13）上做过几轮相机相关的定制和问题排查，踩过不少坑，也把顶层目录和代码脉络梳理得比较清楚了。这篇内容就是把我整理的这份“地图”拿出来共享，不说废话，直接告诉你AOSP 13里相机代码分别在哪里、每一层的关键类是什么、层与层之间如何衔接、出了问题又该去哪一层排查。适合做ROM定制、系统相机二开、HAL移植调试的开发者参考。

1. 先说结论：相机模块在系统里的五层分布

1.1 一次打开相机的完整调用链

要理解代码位置，先要在脑子里建立起一条调用链。相机这玩意不是孤立的一坨代码，而是一条完整的链路：用户点击相机App的图标开始，到屏幕上出现画面，中间至少经历五层。

先看应用层。你打开相机App（在AOSP里默认是packages/apps/Camera2），App调用的是Android框架层提供的API，具体来说就是CameraManager这个核心入口。应用层通过Binder机制，把“打开相机”的请求发送给系统进程里的CameraService。CameraService是贯穿整个相机系统的中枢，它不直接操作硬件，而是继续向下，通过CameraProviderManager这个管理类去连接HAL层（硬件抽象层）提供的Camera Provider服务。HAL层里的Provider会创建出具体的CameraDevice，然后这个Device再通过内核的V4L2框架或者厂商私有的ISP驱动，真正去操作CMOS传感器、ISP图像处理器这些物理硬件。

这条链路，从Java到JNI再到C++，最后到内核驱动，每一层都有自己对应的源码位置。把这条链路刻在脑子里，比死记硬背目录管用得多。

1.2 AOSP 13相机模块目录速查总表

我先给一张我整理的顶层速查表，你可以直接存下来当参考。它不是把每个文件都列出来，而是先把大方向和核心目录讲清楚，后面的章节再逐层展开。

1.3 AOSP 13和老版本相比，目录有哪些变化

AOSP 13里相机模块的顶层结构和Android 11、12差别不算大，但有件值得注意的事情：HAL层的接口正在从HIDL往AIDL迁移。在AOSP 13的源码里，你会同时看到hardware/interfaces/camera下面的provider/2.x、device/3.x这些HIDL版本，以及新加入的provider/aidl、device/aidl、metadata/aidl这些AIDL版本。所以你在源码里搜索camera，结果比老版本更多更杂，有一部分原因就在这里。搞搞清楚HIDL和AIDL接口文件分别放在哪，能少走很多弯路，这块我在第4章细讲。

2. 应用层与Camera2 API：先从你最熟悉的代码下手

2.1 Camera2 API源码到底藏在哪里

先说最容易被问到的问题：“我想看CameraManager的源码，它在哪个目录？”答案在frameworks/base/core/java/android/hardware/camera2下面。这里放着CameraManager.java、CameraDevice.java、CameraCaptureSession.java、CaptureRequest.java、CaptureResult.java这一整套Camera2 API的Java类。这是真正的“地基”，应用层开发者天天打交道的全是这里的类。

有一点值得注意，这个目录下面其实分了一堆子包，比如android.hardware.camera2.params、android.hardware.camera2.legacy、android.hardware.camera2.impl。特别是legacy包很关键，它是在没有HAL3实现的情况下用老接口模拟Camera2行为的地方。如果你在某台设备上发现Camera2的特性不对劲，想确认是不是走了兼容模式，去legacy包里看代码就对了。

我自己的经验：平时做应用层开发，如果只是调用标准API，其实不太需要去翻这些源码。但如果你想做系统定制，比如改默认相机的某些行为、加自定义相机权限、调整预览流程的时序，那就必须从这里开始读代码。

2.2 AOSP 13默认相机应用不只是“Camera2”

AOSP源码里自带的相机应用路径是packages/apps/Camera2，名字叫Camera2，但它其实就是个标准的相机App。你去看它的源码，主目录是src，里面按功能模块拆了包，比如拍照的CaptureModule、录像的VideoModule、相册的Gallery等等。从Android 12、13开始，这个默认相机应用也在不断往CameraX框架上迁移，这里说的CameraX是AndroidX库里的那套Jetpack组件，不是系统内置的模块。

所以你要是想改默认相机的UI或者交互逻辑，两个地方都要看：一个是packages/apps/Camera2的源码（这是Rom里真正运行的App），另一个是外部库里的CameraX相关代码，SDK里CameraX一般是以jar包形式引入的，AOSP完整源码树里可以在third_party下面的androidx相关目录找到对应实现。

2.3 应用层和框架层之间的桥梁：JNI与Binder

应用层调用CameraManager的openCamera方法，但相机App是运行在应用进程里的，CameraService是运行在system_server进程里的，这两者怎么跨进程通信？答案是Binder。相关代码在frameworks/base/core/java/android/hardware/camera2/CameraManager.java里，它通过ServiceManager获取名为“media.camera”的系统服务，拿到ICameraService这个Binder接口代理，再进一步调connectDevice。

这里的Binder接口定义文件在两个位置：Java层接口在frameworks/base/core/java/android/hardware/ICameraService.aidl（对应Callback等AIDL接口），C++层实现则在frameworks/av/camera/目录下。搜索的时候注意，ICameraService可能在服务端和客户端都有一套，如果你要调整框架层API，得同时改这两个地方，保持AIDL接口一致，否则编译会报错或者运行时报Binder异常。

实际开发中，改框架层相机API是件比较重的事，因为涉及AIDL版本兼容。如果你只是想在厂商ROM里加个私有功能，优先考虑在CameraService内部开放接口，而不是改ICameraService的公共AIDL，后者会让所有第三方App都受到影响。

3. 核心中枢：CameraService源码拆解与调试入口

3.1 带你摸清CameraService的家底

CameraService是相机系统的灵魂，代码在frameworks/av/services/camera/libcameraservice目录。这个目录并不是你想象的那种一个文件几百行的简单单元，而是分了好几个各司其职的子目录。我按它内部的代码组织来给你拆一下。

这里有几个必须知道的子目录：api1是旧版本Camera API（Camera类）的服务端实现，里面就是CameraClient类和它的逻辑；api2是Camera2 API（CameraDevice、CameraCaptureSession等）的服务端实现，核心类是CameraDeviceClient和CameraDeviceClientBase；device3不是对应“相机设备3”，而是对应HAL3硬件抽象层，也就是Camera3Device，这是连接HAL3最核心的一个类；common里面是公共逻辑，最值钱的是CameraProviderManager，它用来扫描系统里所有Camera HAL Provider，统一管理HAL设备的加载、枚举、连接。

先记住这几个目录，基本就摸清了CameraService的老底。它的入口文件在libcameraservice/CameraService.cpp，里面实现了ICameraService接口，还有connectDevice（打开相机设备）、addListener（注册相机事件回调）、getCameraCharacteristics（获取相机参数）、getCameraIdList（枚举相机ID列表）这些核心方法。

3.2 CameraService启动流程和关键调用逻辑

系统开机后，CameraService是通过main函数启动的。Android系统里CameraService其实跑在一个独立的Native服务进程里，至于具体是谁创建的，要不要用系统权限，这跟早期的media进程和SurfaceFlinger进程设计有关。在AOSP 13里，CameraService在frameworks/av/services/camera/libcameraservice/main_camera.cpp里有单独的入口，通过serviceManager把自己注册成“media.camera”服务。

应用层调openCamera的时候，实际调用的是CameraService.connectDevice方法，然后经过一系列验证和处理，最终创建CameraDeviceClient并返回给应用层。这里面有个比较深的分支：connectDevice里会根据传入的客户端类型（老Camera API还是Camera2 API）走不同的创建逻辑。如果你发现某个定制需求在应用层改不动，很有可能就是要在connectDevice这里做文章。

还有个小细节：CameraService里有一套“Provider连接”机制。它是通过CameraProviderManager去和HAL层的Provider建立连接的。如果你的系统里有多个Camera Provider（比如内置摄像头Provider和外接USB摄像头Provider），管理它们的代码逻辑就在CameraProviderManager里。Android 13里这部分有多线程回调切换、Provider重启检测等复杂逻辑，一旦HAL进程crash了，CameraProviderManager会帮忙发送设备状态变化通知到上层。

3.3 调试必会：dumpsys和logcat配合定位

排查相机问题，最核心的调试命令就是adb shell dumpsys media.camera。这个命令会输出CameraService当前所有状态：相机ID列表、每个相机设备的打开状态、对应的CameraClient关键信息、会话数量等等。我排查问题第一件事就是执行它，看当前系统认为相机是好的还是坏的。

第二个排查工具是logcat。相机系统中每个关键环节都会打印带TAG的日志。应用层是CameraManager，框架层是CameraService、CameraDeviceClient、Camera3Device，HAL层是CameraProvider或CameraHardware。你打开logcat的时候，直接按这些TAG过滤，能很快定位到底是哪一层出问题。

之前遇到一个很奇怪的问题：相机画面偶尔黑屏，但相机Crash日志里什么都没有。我当时就是用dumpsys media.camera查看设备状态发现设备是正常的，再去抓logcat中带Camera3Device的日志，最后定位到是HAL返回的CaptureResult里缺一个关键metadata字段，导致上层在后处理时错误地把画面丢弃了。没有dumpsys和logcat这两板斧，这种问题是真的无从下手。

3.4 进阶工具：抓取Binder调用栈

如果问题在应用层和CameraService之间的Binder通信上，普通logcat不够直观，可以用binder相关的调试工具。在Android 13的C++层，你可以通过debuggerd拿到特定进程的Binder线程栈；在Java层，则可以用systrace或者简单的抓栈工具去查看block在主线程上的问题。在做相机App预热、快速连拍优化的时候，会经常用到这些手段。这一步不是日常必做，但会了它，排查一些诡异的线程卡顿问题会轻松很多。

4. HAL层与驱动层：跨过硬件门槛的关键代码

4.1 HIDL与AIDL并存，AOSP 13的HAL接口到底怎么看

HAL层是连接系统框架和硬件驱动的桥梁。我在AOSP 13源码里搜索camera HAL时，发现接口目录在hardware/interfaces/camera下面，分HIDL和AIDL两种写法。HIDL版本一般是跟着老的vendor实现走的，即provider/2.4、2.5版本，device/3.4、3.5版本，metadata/3.3、3.4版本，这些是用.hal文件描述的；AIDL版本则是新结构，路径在provider/aidl、device/aidl、metadata/aidl下面，接口文件用.aidl描述，代码结构更传统、更轻量。

Android 13是HIDL到AIDL迁移的重要版本，Google官方推荐新开发的HAL直接用AIDL。如果你去硬件厂商的BSP源码里看，就会发现很多厂商还没有完全放弃HIDL的实现，两种格式都被编译进系统里。判断当前设备使用的到底是哪个版本的HAL，可以通过dumpsys media.camera查看CameraProviderManager的日志，它会打印出加载的Provider服务名称和服务类型。

HAL层代码里最核心的接口其实是这样的结构。Provider负责枚举和提供CameraDevice实例；Device代表单个物理摄像头，负责创建Session和配置数据流；Session就是一次会话，接收CaptureRequest，返回CaptureResult和图像数据。这三个层次对应下来，基本上就是hardware/interfaces/camera/provider、device、metadata三个目录了。

4.2 HAL Device 与 Camera3Device 的协作流程

框架层的Camera3Device和HAL层的Device之间，调用流程是这样的：Camera3Device先通过CameraProviderManager拿到HAL Device的Binder代理，然后调用initialize方法传入框架的错误通知回调，再通过configureStreams配置数据流格式和数量，之后通过processCaptureRequest提交一个拍摄请求。HAL端拿到拍摄请求后，从BufferQueue拿GraphicBuffer，填充图像数据，再通过回调把帧数据返回到上层。这个过程里涉及大量metadata（元数据）的传递，大部分相机参数如曝光、白平衡、对焦都是通过metadata传递的。

你要是想改成像的清晰度、色彩风格这种参数，从这两层下手。通常做法是在HAL的实现里修改3A算法输出，或者在框架层我们习惯用Camera3Device里做过的一些后处理调整。但是注意，如果在HAL层直接改参数，比如把对比度或饱和度调高，那上游API里的设置项可能就失效了，因为HAL可以解读并覆盖metadata。

4.3 驱动层的代码位置和厂商私有实现

真正驱动硬件的代码在Linux内核里。如果你需要看V4L2的核心实现，路径在kernel/drivers/media/v4l2-core；平台相关的ISP摄像头驱动则在kernel/drivers/media/platform下面，不同厂商对应的平台目录会不同。除了V4L2框架，还有个Media Controller框架也是相机驱动相关，路径在kernel/drivers/media/mc。

但这些内核驱动和AOSP的关系其实没那么直接，ROM开发一般很少去动它，因为底层驱动出厂后就已经定死了。除非你要做摄像头传感器适配、新增外接摄像头支持，否则不建议在内核驱动上花太多时间。大部分情况下，上层改到HAL这一层就足够了——真到需要改内核驱动的程度，那基本是硬件厂商的BSP工程师在做的事。你可以通过读v4l2-*工具源码，或者厂商公开的驱动程序接口文档，来了解驱动和HAL的交互。

厂商HAL层面，通常会在vendor/xxx/proprietary或者hardware/xxx/camera下面，源码不一定在AOSP开源包里。很多时候你拿到的是一个编译好的二进制.so文件和一个公开头文件，这时候如果想改HAL行为，只能向厂商要代码，或者用一些动态库替换手段去调试，后者非常复杂，不建议一般开发者尝试。

5. 实际排查：黑屏、闪退、定制相机的几个常见场景

5.1 场景一：预览黑屏或画面不动

这是相机问题里最常见的。黑屏不等于没打开摄像头，而是打开了但图像没上来。遇到黑屏，我的排查顺序是：先看logcat里有没有Camera3Device的报错，再看dumpsys media.camera输出里有没有ERROR状态，接着看HAL返回的Buffer是不是空的。

如果logcat里出现“configureStreams failed”或者“processCaptureRequest failed”类似的日志，基本可以确定问题出在HAL层或驱动层。如果日志一直很干净，却依然黑屏，那有可能反而是应用层自己没有绑定到CameraCaptureSession的Surface，或者预览Surface提前被销毁了。这种定位思路比漫无目的地搜代码更有效。

我在AOSP 13上遇到过一种情况：相机App切换到后台再切回来，偶尔黑屏，最后排查发现是CameraDeviceClient在处理会话关闭和重新打开的时序上有个竞态条件。当时锁定的关键日志就是CameraService里的一条“session closed but not destroyed”警告。所以在调试的时候不要只看表面，要学会分析时序。

5.2 场景二：相机打不开或者提示被占用

相机打不开的常见原因比想象中复杂，但大体就这么几类：一是确实发生了一个真实异常导致应用崩溃或系统服务被杀掉；二是权限不够，没有CAMERA权限；三是SELinux策略把它拦住了，这在定制ROM里很常见——因为权限或内核驱动的标签不对，上层没法访问设备节点。

• 先执行adb shell dumpsys media.camera确认设备本身状态。
• 再查看/data/system/users/0/package-restrictions.xml里是否禁用了相机相关组件。
• 然后检查SELinux的avc日志，看有没有被拦截的节点访问记录。

这些步骤做完，绝大多数“打不开”问题都能定位。尤其是SELinux，它是最隐性也最容易被忽略的坑。你改动HAL服务路径、新增相机节点后，必须同步修改对应.te文件。

5.3 场景三：定制系统相机App时容易踩的坑

做ROM定制的人，免不了要改系统相机App。这里有一个经典误区是直接改AOSP默认相机应用包里的代码会觉得无所谓，其实不然，系统性质的App是带有privileged权限的，它跟framework层的交互很多地方是通过系统级接口完成的。

你定制相机App的时候要特别注意：一是manifest里要申请系统级权限，比如CAMERA、RECORD_AUDIO这些自不必说，但像MANAGE_CAMERA或者MANAGE_USERS这种权限，普通App签名压根拿不到；二是如果你修改了包名，那么所有关联的权限策略、默认Intent、快捷方式都要同步调整，不然点击相机桌面图标会没反应；三是在App里调用CameraManager.openCamera时，资源的释放必须跟CameraService的生命周期处理好，否则容易出现“相机被占用”的假死状态，也会导致第三方App无法使用相机。

我做过一次系统相机的UI大改，当时没有注意到包名里隐藏的共享UserId逻辑，结果装上去之后手机设置里的“存储空间”全都变成了相机应用的数据目录，折腾了好久才发现是因为系统级App在用sharedUserId时对默认存储目录有硬性要求，改包名后这个关联就断了。

5.4 场景四：HAL移植或者升级时的坑

如果你的工作涉及把设备从老版本升级到Android 13，那HAL层的接口迁移是重头戏。HIDL的HAL要改成AIDL或者至少保证两个框架层都能正常枚举到服务。这个工程里最常见的问题是接口版本不匹配——框架层要求3.6版本，但HAL实现还是3.4版本，导致configureStreams里传的参数格式对不上，表现出来就是预览花屏或者直接crash。

排查这种问题，logcat里会明确打出版本不匹配和接口定义差异，一看便知。另一个高频问题就是Android 13新增的动态范围控制和色彩管理相关metadata，如果你的HAL没有适配新版本里引入的那些公共tag，上层API读取到的相机能力值可能为空，导致很多功能莫名其妙不可用。

6. 再分享一点学习路径上的心得

我自己入AOSP相机这坑的时候，走过不少弯路。一开始我也是一头扎进代码里，从CameraManager的Java源码一行一行往下读，结果读了两周还是一头雾水。后来调了几个实际项目，踩的坑多了才回过神来：了解源码位置的核心价值，不是为了“读过代码”，而是为了在出问题时能在分钟级时间内定位到该看哪一层的哪个文件。

这里分享一个我觉得很高效的学习方法：不要从源码的头部开始读，而是先抓一次完整的相机打开过程的logcat，从日志里反推出每一层的调用时序。日志里的TAG会带着类名和方法名，你顺藤摸瓜，很快就能把应用层、CameraService、HAL三个层次之间的真实调用关系摸得清清楚楚。这个方法我后来安利给好几个做系统定制的新人，反馈都说比单纯看源码管用得多。

再补充一个实用技巧：在源码里搜索的时候，不要只搜“camera”这种单词。IDE里用全项目搜索的时候，强烈建议搜类名，比如CameraDeviceClient、Camera3Device、CameraProviderManager这种唯一性强的类名，定位效果远好于搜关键词。另外，AOSP源码里的注释质量和老代码历史都很值得挖掘，很多看起来怪异的逻辑，其实注释里都解释了当时为什么要这么设计，读注释就是在读古人的智慧。

图纸和地图都给你了，剩下的路得自己踩出来。相机这套链路很长，但每一层都不难懂，难的是把五层串成一条线。你只要愿意花时间，把这条线走通一次，以后再碰到任何相机问题，你心里都会有个底：现在这个问题，卡在哪一层。