From ce8902aa705e45639fca63c8fd2619f83ca29eec Mon Sep 17 00:00:00 2001 From: zhangxiaowei16 Date: Sat, 9 May 2026 17:12:28 +0800 Subject: [PATCH] docs: reference orphaned A2DP and Feature Context figures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two figures previously shipped with the API reference were not referenced by any document: - figures/a2dp.png (under framework/bluetooth/) — A2DP connection state machine diagram. - figures/ft_context.svg (under framework/feature/) — Relationship between the Feature framework interface (ft_value_t / ft_context_ref) and the frontend runtime (JSValue / JSContext). Instead of deleting them, both figures are now properly referenced: - bt_a2dp.md gains a new 'Connection State Machine' section that renders the A2DP state machine diagram with a description of each state. - feature_framework_context.md gains a new 'Feature Context and Frontend Runtime' section that uses ft_context.svg to explain the value/context mapping between the Feature framework and frontend runtimes. Chinese and English versions are kept in sync. --- en/api/framework/bluetooth/bt_a2dp.md | 15 +++++++++++++++ .../feature/feature_framework_context.md | 10 ++++++++++ zh-cn/api/framework/bluetooth/bt_a2dp.md | 15 +++++++++++++++ .../feature/feature_framework_context.md | 10 ++++++++++ 4 files changed, 50 insertions(+) diff --git a/en/api/framework/bluetooth/bt_a2dp.md b/en/api/framework/bluetooth/bt_a2dp.md index 955d20b3..b017645c 100644 --- a/en/api/framework/bluetooth/bt_a2dp.md +++ b/en/api/framework/bluetooth/bt_a2dp.md @@ -14,6 +14,21 @@ Header files: #include "bt_a2dp.h", #include "bt_a2dp_sink.h", #include "bt_a2dp - **Transport modes**: Supports hardware offloading and non-offloading modes +## Connection State Machine + +The state transitions during A2DP connection establishment, audio streaming, and disconnection are shown below: + +![A2DP State Machine](figures/a2dp.png) + +State definitions: + +- **Idle**: No A2DP connection is established. +- **Opening**: An A2DP connection is being established (after the local side initiates `A2DP connect`). +- **Opened**: The A2DP signaling connection has been established and the audio stream is ready. +- **Started**: The audio stream has started and audio data is being transmitted. +- **Closing**: The A2DP connection is being torn down until the peer confirms `A2DP disconnected`. + + ## Synchronous Interfaces diff --git a/en/api/framework/feature/feature_framework_context.md b/en/api/framework/feature/feature_framework_context.md index 65edcf87..944f2a58 100644 --- a/en/api/framework/feature/feature_framework_context.md +++ b/en/api/framework/feature/feature_framework_context.md @@ -18,6 +18,16 @@ Header: `#include ` - **Must release**: Objects created by `ft_from_xxx`, objects created by `ft_new_object`, elements retrieved by `ft_array_at`, properties returned by `ft_obj_get_property`, results from `ft_parse_json` - Strings: `const char*` returned by `ft_to_string` must be released with `ft_free_string` +## Feature Context and Frontend Runtime + +The diagram below shows how the Feature framework uses `ft_value_t` and `ft_context_ref` to uniformly wrap native objects of frontend runtimes (using QuickJS as an example): + +![Feature Context and Frontend Runtime](figures/ft_context.svg) + +- **Feature Framework Interface**: The unified C interface exposed by the Feature framework, consisting of `ft_value_t` (data) and `ft_context_ref` (context). +- **JS Implementation**: The concrete frontend runtime implementation. `ft_value_t` maps to `JSValue`, and `ft_context_ref` maps to `JSContext`, with an N:1 relationship between them (multiple values belong to the same context). +- When switching to another frontend (for example, WAMR), the Feature implementation code does not need to change; only the underlying mapping needs to be replaced. + ## Type and Context Access ### ft_context_get_data diff --git a/zh-cn/api/framework/bluetooth/bt_a2dp.md b/zh-cn/api/framework/bluetooth/bt_a2dp.md index 7b26e0ad..e5046280 100644 --- a/zh-cn/api/framework/bluetooth/bt_a2dp.md +++ b/zh-cn/api/framework/bluetooth/bt_a2dp.md @@ -14,6 +14,21 @@ openvela 蓝牙 A2DP（高级音频分发）接口，支持音频流的发送（ - **传输模式**：支持硬件卸载（Offloading）和非卸载模式 +## 连接状态机 + +A2DP 连接建立、流传输以及断开过程中的状态转换如下图所示： + +![A2DP 状态机](figures/a2dp.png) + +各状态含义： + +- **Idle**：空闲，未建立 A2DP 连接。 +- **Opening**：正在建立 A2DP 连接（本端发起 `A2DP connect` 之后）。 +- **Opened**：A2DP 信令连接已建立，可准备音频流。 +- **Started**：音频流已启动，正在传输音频数据。 +- **Closing**：正在断开 A2DP 连接，直至对端确认 `A2DP disconnected`。 + + ## 同步接口 diff --git a/zh-cn/api/framework/feature/feature_framework_context.md b/zh-cn/api/framework/feature/feature_framework_context.md index b3b8d17c..e5cf043a 100644 --- a/zh-cn/api/framework/feature/feature_framework_context.md +++ b/zh-cn/api/framework/feature/feature_framework_context.md @@ -18,6 +18,16 @@ Feature 框架提供的统一数据类型与上下文操作接口。通过 `ft_v - **必须释放**：`ft_from_xxx` 创建的对象、`ft_new_object` 新建对象、`ft_array_at` 取出的元素、`ft_obj_get_property` 返回的属性、`ft_parse_json` 解析结果 - 字符串：`ft_to_string` 返回的 `const char*` 必须用 `ft_free_string` 释放 +## Feature Context 与前端运行时的关系 + +下图展示了 Feature 框架如何通过 `ft_value_t` 与 `ft_context_ref` 统一封装前端运行时（以 QuickJS 为例）的原生对象： + +![Feature Context 与前端运行时的关系](figures/ft_context.svg) + +- **Feature Framework Interface**：Feature 框架对外提供的统一 C 接口，由 `ft_value_t`（数据）与 `ft_context_ref`（上下文）两部分组成。 +- **JS Implementation**：具体前端运行时的实现。`ft_value_t` 背后对应 `JSValue`，`ft_context_ref` 背后对应 `JSContext`，两者之间是 N:1 的关系（多个值归属于同一上下文）。 +- 切换其他前端（如 WAMR）时，Feature 实现侧的代码不需要修改，只需替换底层映射关系。 + ## 类型与上下文访问 ### ft_context_get_data