# quickcalcaddr

**Repository Path**: stesen/quickcalcaddr

## Basic Information

- **Project Name**: quickcalcaddr
- **Description**: quickcalcaddr
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-20
- **Last Updated**: 2026-02-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickCalcAddr

跨平台进程内存地址计算工具（Rust 实现）

## 功能特性

支持三种工作模式：

1. **地址转 VMA (addr2vma)**: 给定 PID 和虚拟地址，定位其在 `/proc/pid/maps` 中的 VMA，计算偏移，支持持久化保存
2. **VMA 转地址 (vma2addr)**: 给定 VMA 标识（名称+权限+偏移），计算指定 PID 中的绝对地址
3. **Watchpoint 监控**: 对指定内存地址设置数据断点，监控读/写访问，触发时打印调用栈

## 目标平台

| 平台 | 架构 | 状态 |
|------|------|------|
| Linux | x86_64, aarch64 | ✅ 已支持 |
| Android | arm64-v8a, armeabi-v7a, x86_64 | ✅ 已支持 |
| OpenHarmony | arm64-v8a, x86_64 | ✅ 已支持 |

## 编译指南

### 快速构建（使用脚本）

项目提供了自动化构建脚本，可以同时构建所有支持的平台：

```bash
# 构建所有平台的 Release 版本
./scripts/build-all.sh release

# 构建所有平台的 Debug 版本
./scripts/build-all.sh debug
```

输出文件将放在 `dist/` 目录中：
```
dist/
├── quickcalcaddr-linux-x86_64
├── quickcalcaddr-linux-aarch64
├── quickcalcaddr-android-arm64-v8a
├── quickcalcaddr-android-armeabi-v7a
├── quickcalcaddr-android-x86_64
├── quickcalcaddr-ohos-arm64-v8a
├── quickcalcaddr-ohos-armeabi-v7a
└── quickcalcaddr-ohos-x86_64
```

### 环境准备

#### 1. 安装 Rust 工具链

```bash
# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装交叉编译工具
rustup target add x86_64-unknown-linux-gnu
rustup target add aarch64-unknown-linux-gnu
rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add x86_64-linux-android
rustup target add aarch64-unknown-linux-musl
rustup target add x86_64-unknown-linux-musl
```

#### 2. 安装交叉编译工具

```bash
# 安装 cross 工具（推荐）
cargo install cross --git https://github.com/cross-rs/cross

# 或者手动安装工具链（见下文各平台说明）
```

### Linux 平台编译

#### x86_64（本地编译）

```bash
# 本地编译（适用于 x86_64 Linux）
cargo build --release --target x86_64-unknown-linux-gnu

# 输出文件
target/x86_64-unknown-linux-gnu/release/quickcalcaddr
```

#### aarch64（交叉编译）

```bash
# 使用 cross 工具（推荐，无需本地安装工具链）
cross build --release --target aarch64-unknown-linux-gnu

# 或者手动安装工具链后编译
# Ubuntu/Debian:
sudo apt-get install gcc-aarch64-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu
```

### Android 平台编译

#### 1. 安装 Android NDK

```bash
# 下载 NDK（推荐 r25c 或更高版本）
# https://developer.android.com/ndk/downloads

# 设置环境变量
export ANDROID_NDK_HOME=/path/to/android-ndk-r25c
export PATH=$PATH:$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin
```

#### 2. 配置 Cargo

创建/编辑 `~/.cargo/config.toml`：

```toml
[target.aarch64-linux-android]
linker = "aarch64-linux-android21-clang"
ar = "llvm-ar"

[target.armv7-linux-androideabi]
linker = "armv7a-linux-androideabi21-clang"
ar = "llvm-ar"

[target.x86_64-linux-android]
linker = "x86_64-linux-android21-clang"
ar = "llvm-ar"
```

#### 3. 编译

```bash
# ARM64 (arm64-v8a)
cargo build --profile release-android --target aarch64-linux-android

# ARMv7 (armeabi-v7a)
cargo build --profile release-android --target armv7-linux-androideabi

# x86_64
cargo build --profile release-android --target x86_64-linux-android
```

或者使用标准 release 配置：

```bash
cargo build --release --target aarch64-linux-android
```

#### 4. 输出文件

```
target/aarch64-linux-android/release/quickcalcaddr      # ARM64
target/armv7-linux-androideabi/release/quickcalcaddr    # ARMv7
target/x86_64-linux-android/release/quickcalcaddr       # x86_64
```

#### 5. 推送到设备测试

```bash
# 推送到 Android 设备
adb push target/aarch64-linux-android/release/quickcalcaddr /data/local/tmp/
adb shell chmod +x /data/local/tmp/quickcalcaddr

# 运行测试（需要 shell 权限）
adb shell /data/local/tmp/quickcalcaddr --help
```

### OpenHarmony (OHOS) 平台编译

OpenHarmony 是 Tier 2 官方支持平台，target 为 `*-unknown-linux-ohos`。

参考文档：https://doc.rust-lang.org/beta/rustc/platform-support/openharmony.html

#### 1. 安装 OpenHarmony SDK

从 [OpenHarmony 官网](https://gitee.com/openharmony/docs/tree/master/zh-cn/release-notes) 下载对应版本的 **"Public SDK package for the standard system"**。

```bash
# 解压 SDK
unzip ohos-sdk-linux-*.zip -d ~/ohos-sdk

# 设置环境变量
export OHOS_SDK_HOME=$HOME/ohos-sdk
```

#### 2. 创建 Clang 包装脚本

OpenHarmony SDK 需要包装脚本来正确设置 target 和 sysroot。

**快速设置（推荐）**：

```bash
# 使用提供的设置脚本
export OHOS_SDK_HOME=$HOME/ohos-sdk
./scripts/setup-ohos.sh
```

**手动设置**：

创建 `~/ohos-sdk/aarch64-unknown-linux-ohos-clang.sh`：

```bash
#!/bin/sh
exec $OHOS_SDK_HOME/linux/native/llvm/bin/clang \
  -target aarch64-linux-ohos \
  --sysroot=$OHOS_SDK_HOME/linux/native/sysroot \
  -D__MUSL__ \
  "$@"
```

创建 `~/ohos-sdk/aarch64-unknown-linux-ohos-clang++.sh`：

```bash
#!/bin/sh
exec $OHOS_SDK_HOME/linux/native/llvm/bin/clang++ \
  -target aarch64-linux-ohos \
  --sysroot=$OHOS_SDK_HOME/linux/native/sysroot \
  -D__MUSL__ \
  "$@"
```

创建 `~/ohos-sdk/armv7-unknown-linux-ohos-clang.sh`：

```bash
#!/bin/sh
exec $OHOS_SDK_HOME/linux/native/llvm/bin/clang \
  -target arm-linux-ohos \
  --sysroot=$OHOS_SDK_HOME/linux/native/sysroot \
  -D__MUSL__ \
  -mfloat-abi=softfp \
  "$@"
```

创建 `~/ohos-sdk/x86_64-unknown-linux-ohos-clang.sh`：

```bash
#!/bin/sh
exec $OHOS_SDK_HOME/linux/native/llvm/bin/clang \
  -target x86_64-linux-ohos \
  --sysroot=$OHOS_SDK_HOME/linux/native/sysroot \
  -D__MUSL__ \
  "$@"
```

设置可执行权限：

```bash
chmod +x ~/ohos-sdk/*-unknown-linux-ohos-clang*.sh
```

#### 3. 配置 Cargo

编辑 `~/.cargo/config.toml`：

```toml
[target.aarch64-unknown-linux-ohos]
linker = "/home/YOUR_USERNAME/ohos-sdk/aarch64-unknown-linux-ohos-clang.sh"
ar = "/home/YOUR_USERNAME/ohos-sdk/linux/native/llvm/bin/llvm-ar"

[target.armv7-unknown-linux-ohos]
linker = "/home/YOUR_USERNAME/ohos-sdk/armv7-unknown-linux-ohos-clang.sh"
ar = "/home/YOUR_USERNAME/ohos-sdk/linux/native/llvm/bin/llvm-ar"

[target.x86_64-unknown-linux-ohos]
linker = "/home/YOUR_USERNAME/ohos-sdk/x86_64-unknown-linux-ohos-clang.sh"
ar = "/home/YOUR_USERNAME/ohos-sdk/linux/native/llvm/bin/llvm-ar"
```

#### 4. 添加 Rust Target

```bash
# ARM64 (arm64-v8a)
rustup target add aarch64-unknown-linux-ohos

# ARMv7 (armeabi-v7a)
rustup target add armv7-unknown-linux-ohos

# x86_64
rustup target add x86_64-unknown-linux-ohos
```

#### 5. 编译

```bash
# ARM64 (arm64-v8a)
cargo build --profile release-ohos --target aarch64-unknown-linux-ohos

# ARMv7 (armeabi-v7a)
cargo build --profile release-ohos --target armv7-unknown-linux-ohos

# x86_64
cargo build --profile release-ohos --target x86_64-unknown-linux-ohos
```

或者使用标准 release 配置：

```bash
cargo build --release --target aarch64-unknown-linux-ohos
```

#### 6. 输出文件

```
target/aarch64-unknown-linux-ohos/release/quickcalcaddr   # ARM64
target/armv7-unknown-linux-ohos/release/quickcalcaddr     # ARMv7
target/x86_64-unknown-linux-ohos/release/quickcalcaddr    # x86_64
```

#### 7. 推送到设备测试

```bash
# 推送到 OpenHarmony 设备
hdc file send target/aarch64-unknown-linux-ohos/release/quickcalcaddr /data/local/tmp/
hdc shell chmod +x /data/local/tmp/quickcalcaddr

# 运行测试
hdc shell /data/local/tmp/quickcalcaddr --help
```

#### 8. 常见问题

**Q: 编译时提示找不到 `__MUSL__` 定义？**
A: 确保包装脚本中添加了 `-D__MUSL__` 参数。

**Q: 链接时提示找不到系统库？**
A: 确保包装脚本中正确设置了 `--sysroot` 指向 OpenHarmony SDK 的 sysroot 目录。

**Q: 如何在 CI/CD 中自动构建？**
A: 可以将 SDK 和包装脚本提交到代码仓库，在 CI 中设置 `OHOS_SDK_HOME` 环境变量即可。

## 使用方法

### 模式一：地址转 VMA

```bash
# 解析运行中进程的地址
quickcalcaddr addr2-vma -p <PID> -a 0x7f8b1234a30

# 保存结果供后续使用
quickcalcaddr addr2-vma -p <PID> -a 0x7f8b1234a30 -s my_state

# 从文件解析（离线分析）
quickcalcaddr addr2-vma -f /path/to/maps.txt -a 0x7f8b1234a30
```

示例输出：
```
PID: 1234
Address: 0x7f8b1234a30

VMA Information:
  Pathname: /lib/libc.so.6
  Range: 0x7f8b1230000 - 0x7f8b1240000
  Permissions: r-xp
  File Offset: 0x0
  Size: 64 KB

Offset Calculation:
  Absolute Address: 0x7f8b1234a30
  VMA Start:        0x7f8b1230000
  Offset in VMA:    0x4a30 (18992 bytes)

[Saved with ID: my_state]
```

### 模式二：VMA 转地址

```bash
# 根据 VMA 名称和偏移计算地址
quickcalcaddr vma2-addr -p <PID> -n "libc.so.6" -r "r-xp" -o 0x4a30
```

### 模式三：Watchpoint 监控（需要 LLDB）

```bash
# 在设备上启动 lldb-server
adb shell /data/local/tmp/lldb-server platform --listen "*:1234" --server

# 监控写操作
quickcalcaddr --lldb-remote 192.168.1.100:1234 watchpoint -p <PID> -a 0x7f8b1234a30

# 监控读写操作，指定大小
quickcalcaddr --lldb-remote 192.168.1.100:1234 watchpoint -p <PID> -a 0x7f8b1234a30 -t read_write -s 4
```

### 状态管理

```bash
# 列出所有保存的状态
quickcalcaddr list

# 查看状态详情
quickcalcaddr show my_state

# 删除状态
quickcalcaddr delete my_state

# 导出状态为 JSON
quickcalcaddr export my_state > backup.json

# 从 JSON 导入状态
quickcalcaddr import < backup.json
```

## 项目结构

```
.
├── src/
│   ├── main.rs              # 程序入口
│   ├── cli.rs               # CLI 参数定义
│   ├── lib.rs               # 库导出
│   ├── error.rs             # 错误类型
│   ├── maps/                # Maps 解析
│   │   ├── mod.rs
│   │   ├── parser.rs        # /proc/pid/maps 解析器
│   │   └── provider.rs      # Maps 提供者
│   ├── platform/            # 平台抽象
│   │   ├── mod.rs
│   │   ├── linux.rs         # Linux 实现
│   │   └── android.rs       # Android 实现
│   ├── resolver/            # 地址解析
│   │   ├── mod.rs
│   │   └── matcher.rs       # VMA 匹配器
│   ├── service/             # 服务层
│   │   ├── mod.rs           # AddressService
│   │   └── watchpoint.rs    # Watchpoint 服务
│   ├── state/               # 状态管理
│   │   └── mod.rs           # SavedState, StateManager
│   └── mocks.rs             # 测试 Mock
├── scripts/                 # 构建脚本
│   ├── build-all.sh         # 全平台构建脚本
│   └── setup-ohos.sh        # OpenHarmony SDK 设置脚本
├── tests/                   # 集成测试
├── benches/                 # 基准测试
└── Cargo.toml
```

## 测试

```bash
# 运行所有测试
cargo test

# 运行并显示输出
cargo test -- --nocapture

# 运行基准测试
cargo bench

# 交叉编译测试
cross test --target aarch64-unknown-linux-gnu
```

## 架构设计

```
CLI 层
    │
服务层 (AddressService, WatchpointService)
    │
提供者层 (MapsProvider, LLDBSession)
    │
平台层 (LinuxPlatform, AndroidPlatform)
```

## 常见问题

### 1. Android 编译错误：`cannot find -lc`

**解决方案**：确保正确设置了 NDK 环境变量，并使用 NDK 提供的 linker。

```bash
export ANDROID_NDK_HOME=/path/to/ndk
export PATH=$PATH:$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin
```

### 2. OpenHarmony 找不到 musl 工具链

**解决方案**：确保 OpenHarmony SDK 的 LLVM 工具链在 PATH 中。

```bash
export OHOS_SDK_HOME=/path/to/ohos-sdk
export PATH=$PATH:$OHOS_SDK_HOME/native/llvm/bin
```

### 3. 交叉编译时链接错误

**解决方案**：使用 `cross` 工具可以简化交叉编译过程。

```bash
cargo install cross
cross build --release --target aarch64-unknown-linux-gnu
```

### 4. 运行时权限问题

在 Android 和 OpenHarmony 上，访问 `/proc/<pid>/maps` 需要特殊权限：

- **Android**：需要 shell 用户或 root 权限
- **OpenHarmony**：需要系统权限或调试签名

## 许可证

MIT OR Apache-2.0