【android bluetooth 框架分析 01】【关键线程 3】【bt_jni_thread 线程介绍】

1. bt_jni_thread 职责介绍

bt_jni_thread 这个线程的作用是专门负责处理蓝牙 JNI 层的消息循环，也可以说是 C++ 层和 Java 层交互的桥梁线程。

1.1 什么是 JNI 层？为什么需要这个线程？

JNI（Java Native Interface）是 Android 用来让 Java 和 C/C++ 代码通信的机制。在蓝牙协议栈中：

• Java 层（APP 或框架）发送蓝牙指令。
• C++ 层（Native 蓝牙协议栈）负责底层逻辑，比如连接蓝牙设备、传输数据等。
• 中间就是 JNI 层，它用来做“翻译官” —— 把 Java 的指令转成 C++ 能理解的函数调用，反之也一样。

1.2 职责总结

1. 消息分发器（Message Dispatcher）
   所有 JNI 相关的调用（比如设备连接状态回调、扫描结果等），都通过这个线程发送回 Java 层。

2. 避免阻塞主线程（Non-blocking）
   蓝牙操作可能会耗时，比如搜索设备、建立连接等。如果不单独开线程处理，会拖慢系统，甚至 ANR（应用无响应）。

3. 保证线程安全（Thread Safety）
   蓝牙操作涉及很多共享资源（socket、状态等），用一个专门的线程可以避免多线程访问冲突。

4. 事件循环（Message Loop）
   这个线程运行的是一个“消息循环”，就是不断读取事件队列中的消息，然后按顺序处理。

1.3 为什么这样设计很重要？

• 安全性（Safe）：
  如果所有 JNI 回调都在主线程或者随便哪个线程跑，容易出现崩溃或者状态错乱。

• 效率（Efficient）：
  用单独线程做专门的事，可以提高系统响应速度，用户操作不会被蓝牙事件卡住。

• 解耦（Decoupled）：
  Java 层、JNI 层、Native 层之间职责分明，出了问题更容易排查和维护。

1.4 总结一句话：

bt_jni_thread 就像是蓝牙 JNI 层的“接线员”，负责有序、高效、安全地处理 Java 与 C++ 层的消息传递，是整个 Android 蓝牙系统稳定运行的重要一环。

2. 如何工作的？

既然 bt_jni_thread 职责已经很清晰了， 那我们就探索一下， bt_jni_thread 是如何启动 ， 如何接收事件， 以及处理事件的？

• system/btif/src/btif_core.cc

2.1 线程何时启动

static MessageLoopThread jni_thread("bt_jni_thread");

bt_status_t btif_init_bluetooth() {
  LOG_INFO("%s entered", __func__);
  exit_manager = new base::AtExitManager();
  jni_thread.StartUp(); // 创建 bt_jni_thread 线程
  invoke_thread_evt_cb(ASSOCIATE_JVM);
  LOG_INFO("%s finished", __func__);
  return BT_STATUS_SUCCESS;
}

调用流程

[stack_manager.cc:event_init_stack] ->

[btif_init_bluetooth]

• 是在 调用 stack_manager 的 event_init_stack 函数阶段触发的， event_init_stack的调用流程， 请参考 之前的文章 介绍 bt_stack_manager_thread

2.2 如何下发任务到 该线程

bt_jni_thread 线程已经启动， 那我们如何下发任务给 该线程去处理呢？
答案是通过 do_in_jni_thread 函数

1. do_in_jni_thread

bt_status_t do_in_jni_thread(const base::Location& from_here,
                             base::OnceClosure task) {
  if (!jni_thread.DoInThread(from_here, std::move(task))) {
    LOG(ERROR) << __func__ << ": Post task to task runner failed!";
    return BT_STATUS_FAIL;
  }
  return BT_STATUS_SUCCESS;
}

这个函数的目的是：

把你传进来的任务 task 安排到 bt_jni_thread 线程里去执行。

参数解释：

• from_here：记录任务来源，用于调试（比如你从哪个文件、哪一行调用的这个函数）。
• task：要在线程中执行的逻辑（闭包或 lambda 表达式）。

实现逻辑：

• 它调用了：jni_thread.DoInThread(from_here, std::move(task));

• 让 bt_jni_thread 来执行这个任务。如果失败（比如线程未启动），就返回 BT_STATUS_FAIL。

• 那些场景会用到 do_in_jni_thread
  

• 从搜素结果来看， 凡是设计到 jni 交互的场景都 在使用。 这个也验证了 本章已开始就介绍的 bt_jni_thread 职责。

这个函数主要用途：

• 线程切换：你可能当前在蓝牙主线程、HAL 线程、APP 线程，但 JNI 的东西要在 bt_jni_thread 里跑，必须切过去。

• 线程安全：统一通过 bt_jni_thread 来操作 JNI，避免多线程同时调用 JNI 导致 crash。

• 任务封装：代码结构更清晰，异步任务都包成一个 Closure 任务发送。

2. btif_transfer_context

bt_status_t btif_transfer_context(tBTIF_CBACK* p_cback, uint16_t event,
                                  char* p_params, int param_len,
                                  tBTIF_COPY_CBACK* p_copy_cback) {
  tBTIF_CONTEXT_SWITCH_CBACK* p_msg = (tBTIF_CONTEXT_SWITCH_CBACK*)osi_malloc(
      sizeof(tBTIF_CONTEXT_SWITCH_CBACK) + param_len);

  BTIF_TRACE_VERBOSE("btif_transfer_context event %d, len %d", event,
                     param_len);

  /* allocate and send message that will be executed in btif context */
  p_msg->hdr.event = BT_EVT_CONTEXT_SWITCH_EVT; /* internal event */
  p_msg->p_cb = p_cback;

  p_msg->event = event; /* callback event */

  /* check if caller has provided a copy callback to do the deep copy */
  if (p_copy_cback) {
    p_copy_cback(event, p_msg->p_param, p_params);
  } else if (p_params) {
    memcpy(p_msg->p_param, p_params, param_len); /* callback parameter data */
  }

  do_in_jni_thread(base::Bind(&bt_jni_msg_ready, p_msg));
  return BT_STATUS_SUCCESS;
}


static void bt_jni_msg_ready(void* context) {
  tBTIF_CONTEXT_SWITCH_CBACK* p = (tBTIF_CONTEXT_SWITCH_CBACK*)context;
  if (p->p_cb) p->p_cb(p->event, p->p_param);
  osi_free(p);
}

btif_transfer_context(...)，它的作用是：

把来自 HAL 或 Stack 的事件，转移（transfer）到 JNI 线程（bt_jni_thread）中执行，并调用对应的回调函数。

这个函数起到了核心的“线程桥梁”和“事件分发器”的作用。
函数入参解释

1. 分配内存

   tBTIF_CONTEXT_SWITCH_CBACK* p_msg = (tBTIF_CONTEXT_SWITCH_CBACK*)osi_malloc(...);

   创建一个消息对象 p_msg，用来封装要执行的任务。

2. 设置元数据

   p_msg->hdr.event = BT_EVT_CONTEXT_SWITCH_EVT; p_msg->p_cb = p_cback; p_msg->event = event;

   标记这个是“上下文切换事件”，并把事件编号和要执行的回调函数绑定进来。

3. 拷贝参数
   如果参数非空，尝试用 p_copy_cback() 深拷贝参数；否则直接用 memcpy() 复制。

4. 投递给 JNI 线程执行

   do_in_jni_thread(base::Bind(&bt_jni_msg_ready, p_msg));

   把这个封装好的消息送到 bt_jni_thread 中，由 bt_jni_msg_ready() 函数去调度并执行真正的回调。

5. 返回成功

   return BT_STATUS_SUCCESS;

这样设计意义是什么？

总结

• btif_transfer_context() 是一个线程切换和任务派发的机制。

• 它不是 Java 调 Native 的唯一通道，但在需要切换到 bt_jni_thread 执行的下行任务中非常关键。

• 它和 do_in_jni_thread() 一起构成了 Android 蓝牙协议栈中线程调度和事件派发的基础工具。

3. 使用举例

1. 上行 native -> java

01-10 06:48:39.160  2024  3120 I bluetooth: packages/modules/Bluetooth/system/bta/dm/bta_dm_main.cc:65 bta_dm_search_sm_execute: bta_dm_search_sm_execute state:1, event:0x205

01-10 06:48:39.160  2024  3120 I bt_btif : packages/modules/Bluetooth/system/main/bte_logmsg.cc:198 LogMsg: btif_dm_search_devices_evt event=BTA_DM_DISC_CMPL_EVT

01-10 06:48:39.161  2024  2493 I bt_btif : packages/modules/Bluetooth/system/main/bte_logmsg.cc:198 LogMsg: operator(): HAL bt_hal_cbacks->discovery_state_changed_cb

01-10 06:48:39.161  2024  2493 I AdapterProperties: Callback:discoveryStateChangeCallback with state:0

当我们发起扫描, 扫描结束后， 会上报一个状态给 java 层。

我们来梳理一下这个调用流程：

• system/btif/src/btif_dm.cc

static int start_discovery(void) {
  if (!interface_ready()) return BT_STATUS_NOT_READY;
  // 当我们触发 扫描时， 是跑在 main_thread 中的
  do_in_main_thread(FROM_HERE, base::BindOnce(btif_dm_start_discovery));
  return BT_STATUS_SUCCESS;
}


void btif_dm_start_discovery(void) {
  BTIF_TRACE_EVENT("%s", __func__);

  /* no race here because we're guaranteed to be in the main thread */
  if (bta_dm_is_search_request_queued()) {
    LOG_INFO("%s skipping start discovery because a request is queued",
             __func__);
    return;
  }

  /* Will be enabled to true once inquiry busy level has been received */
  btif_dm_inquiry_in_progress = false;
  /* find nearby devices */
  BTA_DmSearch(btif_dm_search_devices_evt);
}

• app 侧发起扫描， 就会触发 btif_dm_start_discovery 调用，
• 在触发扫描时，我们注册了 btif_dm_search_devices_evt 回调函数

当芯片上报扫描 结束时，就会 回调 btif_dm_search_devices_evt 。 这个过程怎么回调到的，暂时不表， 后面有机会，专门单独表述，这种机制。

• system/btif/src/btif_dm.cc

static void btif_dm_search_devices_evt(tBTA_DM_SEARCH_EVT event,
                                       tBTA_DM_SEARCH* p_search_data) {
                               
  // 此时发现收到了 扫描结束事件
    case BTA_DM_DISC_CMPL_EVT: {
      // 这里会触发
      invoke_discovery_state_changed_cb(BT_DISCOVERY_STOPPED);
    } break;                       

}

• 触发调用 invoke_discovery_state_changed_cb

• system/btif/src/bluetooth.cc

void invoke_discovery_state_changed_cb(bt_discovery_state_t state) {
  do_in_jni_thread(FROM_HERE, base::BindOnce(
                                  [](bt_discovery_state_t state) {
                                    HAL_CBACK(bt_hal_cbacks,
                                              discovery_state_changed_cb,
                                              state);
                                  },
                                  state));
}

• HAL_CBACK(bt_hal_cbacks, discovery_state_changed_cb,…)
  • 上述的 调用会打印如下log
  • HAL bt_hal_cbacks->discovery_state_changed_cb
• 此时就会调用到 discovery_state_changed_cb
• 从这里开始 回调 hal 层， 将 discovery_state_changed_cb 回调放置到 bt_jni_thread 线程中去处理， 从这里往下都是跑在 bt_jni_thread 中。

• android/app/jni/com_android_bluetooth_btservice_AdapterService.cpp

static bt_callbacks_t sBluetoothCallbacks = {
...
                                             discovery_state_changed_callback, // 这里会被回调到
                                             ...
};



static void discovery_state_changed_callback(bt_discovery_state_t state) {
  CallbackEnv sCallbackEnv(__func__);
  if (!sCallbackEnv.valid()) return;

  ALOGV("%s: DiscoveryState:%d ", __func__, state);

  sCallbackEnv->CallVoidMethod(
      sJniCallbacksObj, method_discoveryStateChangeCallback, (jint)state);
}


static void classInitNative(JNIEnv* env, jclass clazz) {
...
	  method_discoveryStateChangeCallback = env->GetMethodID(
      jniCallbackClass, "discoveryStateChangeCallback", "(I)V");
}

• 此时回调到 discovery_state_changed_callback 他最终回调到 java 侧的 AdapterProperties::discoveryStateChangeCallback

• android/app/src/com/android/bluetooth/btservice/AdapterProperties.java

    void discoveryStateChangeCallback(int state) {
        infoLog("Callback:discoveryStateChangeCallback with state:" + state);
        synchronized (mObject) {
            Intent intent;
            if (state == AbstractionLayer.BT_DISCOVERY_STOPPED) {
                mDiscovering = false;
                mService.clearDiscoveringPackages();
                mDiscoveryEndMs = System.currentTimeMillis();
                intent = newIntent(BluetoothAdapter.ACTION_DISCOVERY_FINISHED,
                        BluetoothAdapterExt.ACTION_DISCOVERY_FINISHED);
                mService.sendBroadcast(intent, BLUETOOTH_SCAN,
                        Utils.getTempAllowlistBroadcastOptions());
            } else if (state == AbstractionLayer.BT_DISCOVERY_STARTED) {
                mDiscovering = true;
                mDiscoveryEndMs = System.currentTimeMillis() + DEFAULT_DISCOVERY_TIMEOUT_MS;
                intent = newIntent(BluetoothAdapter.ACTION_DISCOVERY_STARTED,
                        BluetoothAdapterExt.ACTION_DISCOVERY_STARTED);
                mService.sendBroadcast(intent, BLUETOOTH_SCAN,
                        Utils.getTempAllowlistBroadcastOptions());
            }
        }
    }

2. 下行 java -> native

在车机的蓝牙电话通话过程中， 我们可以随意在 车机上切换当前来电是在手机接听，还是车机接听。 也就是 hfp 中 SCO 的建立和断开。 这里我们看一下 主动去建立 SCO的流程。

• android/app/jni/com_android_bluetooth_hfpclient.cpp

static jboolean connectAudioNative(JNIEnv* env, jobject object,
                                   jbyteArray address) {
	...

  bt_status_t status =
      sBluetoothHfpClientInterface->connect_audio((const RawAddress*)addr);
	...
}

• system/btif/src/btif_hf_client.cc

static bt_status_t connect_audio(const RawAddress* bd_addr) {
  btif_hf_client_cb_t* cb = btif_hf_client_get_cb_by_bda(*bd_addr);
  if (cb == NULL || !is_connected(cb)) return BT_STATUS_FAIL;

  CHECK_BTHF_CLIENT_SLC_CONNECTED(cb);

  if ((get_default_hf_client_features() & BTA_HF_CLIENT_FEAT_CODEC) &&
      (cb->peer_feat & BTA_HF_CLIENT_PEER_CODEC)) {
    BTA_HfClientSendAT(cb->handle, BTA_HF_CLIENT_AT_CMD_BCC, 0, 0, NULL);
  } else {
    BTA_HfClientAudioOpen(cb->handle);
  }

  /* Inform the application that the audio connection has been initiated
   * successfully */
  // 之间加入到 bt_jni_thread 中去执行
  btif_transfer_context(btif_in_hf_client_generic_evt,
                        BTIF_HF_CLIENT_CB_AUDIO_CONNECTING, (char*)bd_addr,
                        sizeof(RawAddress), NULL);
  return BT_STATUS_SUCCESS;
}

• 这里通过 btif_transfer_context 将建立 sco 的操作放置到 bt_jni_thread 线程中去执行了。

2.3 线程何时终止

bt_status_t btif_cleanup_bluetooth() {
  LOG_INFO("%s entered", __func__);
  btif_dm_cleanup();
  invoke_thread_evt_cb(DISASSOCIATE_JVM);
  btif_queue_release();
  jni_thread.ShutDown();
  delete exit_manager;
  exit_manager = nullptr;
  btif_dut_mode = 0;
  LOG_INFO("%s finished", __func__);
  return BT_STATUS_SUCCESS;
}

• system/btif/src/stack_manager.cc

static void event_clean_up_stack(std::promise<void> promise) {
	...

  btif_cleanup_bluetooth();

  ...
}

• 当我们点击关闭蓝牙时 bt_stack_manager_thread 线程会去触发 event_clean_up_stack 调用， 在这个里面，会去讲我们的 bt_jni_thread 线程终止的。

3. bt_hal_cbacks 介绍

3.1 HAL_CBACK

在上面 2.2.2.1 小结介绍上行 流时， 我们看到了 HAL_CBACK 的调用，本节就来看看 这部分是如何 做到的。

void invoke_discovery_state_changed_cb(bt_discovery_state_t state) {
  do_in_jni_thread(FROM_HERE, base::BindOnce(
                                  [](bt_discovery_state_t state) {
                                    HAL_CBACK(bt_hal_cbacks,
                                              discovery_state_changed_cb,
                                              state);
                                  },
                                  state));
}

#define HAL_CBACK(P_CB, P_CBACK, ...)                              \
  do {                                                             \
    if ((P_CB) && (P_CB)->P_CBACK) {                               \
      BTIF_TRACE_API("%s: HAL %s->%s", __func__, #P_CB, #P_CBACK); \
      (P_CB)->P_CBACK(__VA_ARGS__);                                \
    } else {                                                       \
      ASSERTC(0, "Callback is NULL", 0);                           \
    }                                                              \
  } while (0)

• 这里是一个宏函数，
• 可以直接把 HAL_CBACK(bt_hal_cbacks, discovery_state_changed_cb 调用替换为：
  • bt_hal_cbacks->discovery_state_changed_cb(state)

但是这不是重点， 重点是 bt_hal_cbacks 初始化以及 这些回调函数的含义

3.2 bt_callbacks_t

• system/btif/src/bluetooth.cc

static bt_callbacks_t* bt_hal_cbacks = NULL;

typedef struct {
    /** set to sizeof(bt_callbacks_t) */
    size_t size;
    adapter_state_changed_callback adapter_state_changed_cb;
    adapter_properties_callback adapter_properties_cb;
    remote_device_properties_callback remote_device_properties_cb;
    device_found_callback device_found_cb;
    discovery_state_changed_callback discovery_state_changed_cb; // 会调用到这里
    pin_request_callback pin_request_cb;
    ssp_request_callback ssp_request_cb;
    bond_state_changed_callback bond_state_changed_cb;
    acl_state_changed_callback acl_state_changed_cb;
    callback_thread_event thread_evt_cb;
    dut_mode_recv_callback dut_mode_recv_cb;
    le_test_mode_callback le_test_mode_cb;
    energy_info_callback energy_info_cb;
} bt_callbacks_t;

bt_callbacks_t 结构体是 Bluetooth HAL（硬件抽象层） 定义的一组回调接口，用于 Native 层通过回调与上层框架通信，比如 Java 层或者 JNI 层。

3.3 bt_hal_cbacks 如何初始化的

• system/btif/src/bluetooth.cc

static bt_callbacks_t* bt_hal_cbacks = NULL;

那这里的 bt_hal_cbacks 是如何初始化的？

• android/app/jni/com_android_bluetooth_btservice_AdapterService.cpp

static bool initNative(JNIEnv* env, jobject obj, jboolean isGuest,
                       jboolean isCommonCriteriaMode, int configCompareResult,
                       jobjectArray initFlags, jboolean isAtvDevice,
                       jstring userDataDirectory) {


// 将 sBluetoothCallbacks 传递出去
int ret = sBluetoothInterface->init(
      &sBluetoothCallbacks, isGuest == JNI_TRUE ? 1 : 0,
      isCommonCriteriaMode == JNI_TRUE ? 1 : 0, configCompareResult, flags,
      isAtvDevice == JNI_TRUE ? 1 : 0, user_data_directory);


}


static bt_callbacks_t sBluetoothCallbacks = {sizeof(sBluetoothCallbacks),
                                             adapter_state_change_callback,
                                             adapter_properties_callback,
                                             remote_device_properties_callback,
                                             device_found_callback,
                                             discovery_state_changed_callback,
                                             pin_request_callback,
                                             ssp_request_callback,
                                             bond_state_changed_callback,
                                             address_consolidate_callback,
                                             le_address_associate_callback,
                                             acl_state_changed_callback,
                                             callback_thread_event,
                                             dut_mode_recv_callback,
                                             le_test_mode_recv_callback,
                                             energy_info_recv_callback,
                                             link_quality_report_callback,
                                             generate_local_oob_data_callback,
                                             switch_buffer_size_callback,
                                             switch_codec_callback};

• 当我们拉起我们的 蓝牙进程服务时， 将触发 initNative 调用

• 此时通过 sBluetoothInterface->init( &sBluetoothCallbacks

  • 将我们的 sBluetoothCallbacks 传递出去。

• system/btif/src/bluetooth.cc

static int init(bt_callbacks_t* callbacks, bool start_restricted,
                bool is_common_criteria_mode, int config_compare_result,
                const char** init_flags, bool is_atv,
                const char* user_data_directory) {


  set_hal_cbacks(callbacks); // 直接将 callbacks 给了 bt_hal_cbacks

}



void set_hal_cbacks(bt_callbacks_t* callbacks) { bt_hal_cbacks = callbacks; }

• 这里所有的 hal 回调都将回调到 sBluetoothCallbacks 中。

4. 小结

bt_jni_thread 是 AOSP 蓝牙系统中 native → Java 方向的专用线程桥梁，同时也承担部分 profile 层轻量控制任务的执行职责。它不是全能线程，但在 JNI 回调中不可或缺。

为什么要有 bt_jni_thread

核心职责

使用场景举例

看到这里大家可以思考一下问题：

• native <-> java 上下行的事件， 一定都要 放在 bt_jni_thread 线程中执行吗？
• 答案