127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# softbus_core
|
||
|
||
**路径：** `src/softbus_core`
|
||
**构建目标：** `softbus_core`（STATIC 库）
|
||
**层级：** L0 内核层
|
||
|
||
## 1. 概述
|
||
|
||
`softbus_core` 是全项目共享内核，提供数据模型、身份标识、配置加载、插件 ABI、日志、平台信号与时间对齐。所有上层模块均依赖本库，且模型设计保持**传输中立**——不含 D-Bus、HTTP、OPC UA 特定字段。
|
||
|
||
## 2. CONSTRAINTS
|
||
|
||
- `softbus_core` 拥有进程无关的共享模型、元数据定义、插件接口与配置解析。
|
||
- 模型结构体必须保持传输中立，不得在字段中编码 D-Bus、HTTP、Qt 或 OPC UA 特定语义。
|
||
- 插件接口须保持 ABI 稳定：优先新增字段与能力方法，避免改变已有方法语义。
|
||
- `ObjectRef` 五层路径是唯一对象寻址约定，格式为 `Site/System/Asset/Device/Point`。
|
||
- 空配置与首次运行状态合法，`ProfileLoader` 失败须由调用方处理。
|
||
- `traceId` 由 `DeviceIdentity` 统一生成，格式 `trace-xxxxxxxx`。
|
||
|
||
## 3. 子模块
|
||
|
||
### 3.1 models — 数据模型
|
||
|
||
| 类型 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| `RawPacket` | `models/RawPacket.h` | 边缘上行原始包 |
|
||
| `RawBusMessage` | `models/RawBusMessage.h` | `RawPacket` 类型别名 |
|
||
| `DOMMessage` | `models/DOMMessage.h` | 统一语义消息 |
|
||
| `ObjectModelTree` | `models/ObjectModel.h` | 五层对象树定义 |
|
||
| `ObjectRef` | `models/ObjectModel.h` | 对象引用与路径转换 |
|
||
| `MetadataDef` | `models/MetadataDef.h` | 测点元数据（dataType, unit, scale） |
|
||
|
||
**RawPacket 字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `traceId` | string | 追踪标识 |
|
||
| `timestampNs` | uint64_t | 纳秒时间戳 |
|
||
| `runtimeDeviceId` | string | 运行时设备 ID |
|
||
| `sourceId` | string | 源对象路径 |
|
||
| `protocolTag` | string | 协议标签 |
|
||
| `payload` | vector<uint8_t> | 原始字节 |
|
||
|
||
**DOMMessage 字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | string | 消息标识（通常等于 objectRef） |
|
||
| `sourceId` | string | 源对象路径 |
|
||
| `domain` | string | 数据域，如 `Process` |
|
||
| `quality` | string | 数据质量，如 `Good` |
|
||
| `value` | json | 语义值对象 |
|
||
| `traceId` | string | 追踪标识 |
|
||
| `timestampNs` | uint64_t | 时间戳 |
|
||
|
||
### 3.2 identity — 设备身份
|
||
|
||
| 类/函数 | 说明 |
|
||
|---------|------|
|
||
| `DeviceIdentity::generateTraceId()` | 生成 `trace-xxxxxxxx` |
|
||
| `DeviceIdentity::generateRuntimeDeviceId()` | 生成 `runtime-xxxxxxxx` |
|
||
| `DeviceIdentity::buildObjectRef(tree, device, point)` | 从模型构建 ObjectRef |
|
||
|
||
### 3.3 config — 配置加载
|
||
|
||
| 类 | 说明 |
|
||
|----|------|
|
||
| `ProfileLoader` | 解析 `daemon_profile.json` → `DaemonProfile` |
|
||
| `DaemonProfile` | 含 `opcua`、`uplink`、`plugins`、`security` 子结构 |
|
||
| `ObjectModelTree::loadFromFile()` | 解析 `softbus_model.json` |
|
||
|
||
### 3.4 plugin — 插件基础设施
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `IFramer` | 分帧：`extract(data, size) → FrameResult` |
|
||
| `IParser` | 解析：`parseFrame(data, size, sourceId) → ParseResult` |
|
||
| `PluginLoader` | dlopen/LoadLibrary 动态加载插件 |
|
||
| `SOFTBUS_PLUGIN_API` | C ABI 导出宏 |
|
||
|
||
**插件 C ABI 导出函数：**
|
||
|
||
```c
|
||
SOFTBUS_PLUGIN_API IFramer* create_framer();
|
||
SOFTBUS_PLUGIN_API void destroy_framer(IFramer* framer);
|
||
SOFTBUS_PLUGIN_API IParser* create_parser();
|
||
SOFTBUS_PLUGIN_API void destroy_parser(IParser* parser);
|
||
```
|
||
|
||
### 3.5 其他子模块
|
||
|
||
| 子模块 | 文件 | 说明 | Phase 1 状态 |
|
||
|--------|------|------|-------------|
|
||
| logging | `Logger.h/.cpp` | 单例日志，`SB_LOG_*` 宏自动附带 `[文件::函数]` 调用位置 | 已用 |
|
||
| time | `HwClock.h/.cpp` | 纳秒级时间戳 | 已用 |
|
||
| alignment | `TimeAligner.h/.cpp` | 多通道时间对齐 | 未接入 |
|
||
| platform | `PlatformSignal.h/.cpp` | SIGINT 优雅退出 | 已用 |
|
||
| queue | `LockFreeQueue.h` | 无锁队列 | 预留 |
|
||
|
||
## 4. 依赖
|
||
|
||
- **对外（PUBLIC）：** nlohmann_json
|
||
- **被依赖：** 所有其他模块
|
||
|
||
## 5. 统一入口
|
||
|
||
```cpp
|
||
#include <softbus_core/softbus_core.h>
|
||
```
|
||
|
||
聚合所有 public 头文件，供上层模块一次性引入。
|
||
|
||
## 6. 配置关联
|
||
|
||
| 配置文件 | 加载方 | 对应类型 |
|
||
|----------|--------|----------|
|
||
| `config/daemon_profile.json` | `ProfileLoader` | `DaemonProfile` |
|
||
| `config/softbus_model.json` | `ObjectModelTree` | `ObjectModelTree` |
|
||
|
||
## 7. 构建
|
||
|
||
```cmake
|
||
# src/softbus_core/CMakeLists.txt
|
||
add_library(softbus_core STATIC ...)
|
||
target_link_libraries(softbus_core PUBLIC nlohmann_json::nlohmann_json Threads::Threads)
|
||
```
|