Janus Native Bridge - ARM64/ARM32 to x86_64 Binary Translation Layer
Janus is a dynamic binary translation (DBT) library that enables running ARM64 and ARM32 (AArch32) binaries on x86_64 platforms. It implements the Android Native Bridge interface, allowing seamless execution of ARM libraries on x86_64 systems.
- ARM64 to x86_64 Translation: Full AArch64 instruction set translation
- ARM32/Thumb to x86_64 Translation: Complete ARM32 and Thumb-16/32 support
- SIMD/NEON Support: SSE/AVX accelerated NEON translation
- Translation Cache: LRU-based cache with hot block detection
- Performance Monitoring: Real-time profiling and statistics
- ELF Loading: Full ELF binary loading and relocation
- Native Bridge API: Android-compatible interface
- JNI Tools: Call capture, recording, replay, and simulation
- Multi-threading: Thread-safe cache management
- Translation Speed: ~100K instructions/second
- Cache Hit Rate: 70-90% (typical workloads)
- Code Expansion: 1.5-2.5x (ARM→x86)
- Execution Performance: 50-60% of native (target: 80-90%)
# Clone repository
git clone https://github.com/monkeycode-ai/janus.git
cd janus
# Build
make
# Test
./run_tests.sh# Standard build
make
# Debug build (with symbols and logs)
make debug
# Performance monitoring enabled
make perf
# AVX acceleration
make avx
# All debug flags
make debug-all
# Clean
make cleanThe build produces libjanus.so, a shared library (~275KB).
| Document | Description |
|---|---|
| README | Project overview |
| README_zh | 中文文档 |
| USAGE | Detailed usage guide |
| API | API reference |
| ARCHITECTURE | Architecture design |
| PERFORMANCE | Performance optimization |
| TESTING | Testing guide |
| CONTRIBUTING | Contribution guidelines |
| PROJECT_PLAN | Project roadmap |
#include "janus.h"
janus_Context ctx;
janus_Context *pctx = &ctx;
// Initialize
int rc = janus_init(pctx, "/path/to/arm/libs", "guest_cmd");
if (rc != JANUS_OK) {
fprintf(stderr, "Init failed: %d\n", rc);
return 1;
}
// Set execution mode
janus_set_mode(pctx, JANUS_MODE_ARM64);
// Translate
uint8_t *x86_code = NULL;
size_t x86_size = 0;
int rc = janus_convert(pctx, arm_code, arm_size, &x86_code, &x86_size);
// Execute x86_code...
// Cleanup
free(x86_code);
janus_destroy(pctx);#include "modules/janus_tcache.h"
// Create cache
janus_translation_cache_t *cache = janus_tcache_create(2 * 1024 * 1024);
// Lookup
janus_tcache_entry_t *entry = janus_tcache_lookup(cache, arm_pc);
if (entry) {
// Cache hit
uint8_t *code = janus_tcache_get_code(entry);
execute(code);
} else {
// Cache miss
uint8_t *x86 = translate(arm_code);
janus_tcache_insert(cache, arm_pc, x86, x86_size);
}#include "modules/janus_perf.h"
// Initialize
janus_perf_init();
// ... run your program ...
// Print report
janus_perf_print_report();
// Export JSON
char json[4096];
janus_perf_export_json(json, sizeof(json));┌─────────────────────────────────────────────────┐
│ Application Layer (ARM Binary) │
├─────────────────────────────────────────────────┤
│ Native Bridge API Layer │
├─────────────────────────────────────────────────┤
│ Dynamic Binary Translation Layer │
│ ┌──────────┬──────────┬──────────────┐ │
│ │ Decoder │Translator│ Code Gen │ │
│ └──────────┴──────────┴──────────────┘ │
├─────────────────────────────────────────────────┤
│ Execution Engine & Cache Management │
├─────────────────────────────────────────────────┤
│ Memory Management (ELF Loader) │
├─────────────────────────────────────────────────┤
│ Host System (x86_64) │
└─────────────────────────────────────────────────┘
janus/
├── janus.c # Main integration file
├── janus.h # Public API
├── Makefile # Build system
├── LICENSE # LGPL-3.0+
├── README.md # This file
├── README_zh.md # 中文版文档
├── USAGE.md # Usage guide
├── API.md # API reference
├── ARCHITECTURE.md # Architecture doc
├── PERFORMANCE.md # Performance guide
├── TESTING.md # Testing guide
├── CONTRIBUTING.md # Contribution guide
├── PROJECT_PLAN.md # Project roadmap
└── modules/ # Translation modules
├── janus_decode64.c # ARM64 decoder
├── janus_translate64.c # ARM64 translator
├── janus_translate32.c # ARM32 translator
├── janus_translate_thumb.c # Thumb translator
├── janus_neon.c # NEON/SIMD support
├── janus_emit.c # x86 code generator
├── janus_tcache.c # Translation cache
├── janus_perf.c # Performance monitor
├── janus_dbt.c # DBT runtime
├── janus_elf.c # ELF loader
├── janus_syscall.c # Syscall handling
├── janus_signal.c # Signal handling
├── janus_jni_*.c # JNI tools
└── ...
- ✅ Data processing (ADD, SUB, AND, ORR, EOR, etc.)
- ✅ Load/store (LDR, STR, LDP, STP)
- ✅ Branches (B, BL, BR, BLR, RET, B COND)
- ✅ Conditional (CBZ, CBNZ, TBZ, TBNZ)
- ✅ SIMD/NEON (ADD, SUB, MUL, etc.)
- ✅ Floating-point (FADD, FSUB, FMUL, FDIV)
- ✅ Atomic (LDAXR, STLXR, CAS, LDADD)
- ✅ System (MRS, MSR, barriers)
- ✅ ARM32 data processing
- ✅ ARM32 load/store
- ✅ ARM32 multiply (MUL, MLA, UMULL, etc.)
- ✅ Thumb-16 instructions
- ✅ Thumb-2 instructions
- ✅ VFP/NEON
This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0+). See the LICENSE file for details.
The LGPL license allows you to:
- Use this library in proprietary applications
- Link against the library without disclosing your source code
- Modify the library itself (changes must be released under LGPL)
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests
- Submit a pull request
- GitHub Issues: Bug reports and feature requests
- Discussion Forum: General questions and discussions
- Email List: Developer communication
Thanks to all contributors and users who make Janus possible!
Last updated: 2026-05-30