Skip to content

README.en.rst

Latest commit

 

History

History
245 lines (161 loc) · 8.16 KB

README.en.rst

File metadata and controls

245 lines (161 loc) · 8.16 KB

LATX (LoongArch Architecture Translator for x86)

LATX (LoongArch Architecture Translator for x86) is a high-performance user-level binary translator designed specifically for the LoongArch architecture, enabling efficient execution of x86 applications on LoongArch-based systems.

Built upon QEMU 6 with substantial optimizations, LATX significantly outperforms the original QEMU implementation.

The project leverages LoongArch's advanced instruction set extensions (such as vector extensions and binary translation instructions) to achieve high-efficiency translation of x86 instructions. Key optimizations include AOT (Ahead-of-Time) compilation and runtime library pass-through, with the latter partially inspired by and referencing source code from the box64 project.

中文版本点击这里 >>

Commit Convention

Commit Convention (English)

Project Background

As the LoongArch ecosystem evolves, compatibility and performance bottlenecks arise when running legacy x86 applications. Existing emulators such as vanilla QEMU cannot fully satisfy these demands regarding efficiency and compatibility.

Therefore, we extended QEMU 6 with targeted optimizations, such as AOT compilation and library pass-through, substantially reducing the overhead of instruction translation and execution to achieve "faster, more stable, and more compatible" performance.

History and Evolution

The project's development has progressed through several stages:

  • 2021: Project initiation, initial port to QEMU 6 completed; Alpha stage reached in Q3.
  • 2022: Added library pass-through optimizations, Project entered the Beta phase in Q3.
  • 2023: Continued enhancements to system calls support and refined instruction-level optimizations.
  • 2024: Project advanced to the Release Candidate (RC) stage.

Project Structure

To ensure clarity and simplicity in the project's public history, nearly two thousand commits of LATX have been squashed into a single commit for this repository.

The main project directory structure is as follows:

lat
├── ...
├── latxbuild/                           # Scripts used for compilation
├── target/
│   └── i386/
│       └── latx/
│           └── context/                 # Library pass-through related
│           └── convert.py               # Generates LA instruction function templates
│           └── ir1/
│               └── ir1.c                # IR1: Intermediate Representation of x86 instructions
│           └── ir2/
│               └── ir2.c                # IR2: Intermediate Representation for LA instructions
│               └── ir2-relocate.c       # Label handling logic
│               └── la-append.c          # Generated by convert.py after compilation
│               └── ir2-assemble.c
│           └── latx-options.c           # LATX functional options
│           └── optimization/
│               └── flag-reduction.c     # TB internal eflags reduction optimization
│               └── hbr.c                # Register high-bit calculation optimization
│               └── imm-cache.c          # Immediate number load optimization
│               └── insts-pattern.c      # Semantic-level instruction combination optimization
│               └── ir1-optimization.c   # IR1-level optimization scanning
│               └── ir2-optimization.c   # IR2-level instruction scheduling
│               └── tu.c                 # Translation Unit (TU) optimization
│               └── ...
│           └── sbt/                     # AOT-related components
│           └── translator/              # Translation functions
│               └── tr-logic.c           # Logic instruction translation functions
│               └── tr-arith.c           # Arithmetic instruction translation functions
│               └── ...
│           └── wrapper/                 # Library pass-through related
│           └── ...
├── ...
└── README.rst                           # This document

Major Contributors

Numerous individuals have contributed greatly to this project's success. Below are the top 10 contributors by commit volume. Special thanks also to those who contributed to documentation, community management, workflow automation, and testing:

  1. Lu Zeng <luzeng87@gmail.com>
    • Project Owner, initiated and led overall design and architecture
    • Promoted and oversaw performance optimization strategies
    • Extensive contributions to compatibility and optimization work
  2. Hanlu Li <heuleehanlu@gmail.com>
    • Project Maintainer
    • Author of 16K compatibility shadow page module
    • Major contributions in compatibility and optimization
  3. Wenqiang Wei <weiwenqiang@mail.ustc.edu.cn>
    • Co-developer and maintainer of AOT module
    • Translation Unit (TU) optimization co-developer and maintainer
    • Maintainer of shadow page module
  4. Jing Li <654224414@qq.com>
    • Early developer of the AOT module
    • Maintainer of the library pass-through module
  5. Qi Hu <spcreply@outlook.com>
    • Primary author of eflags elimination-related optimizations
  6. Yanzhi Lan <lanyanzhi19@mails.ucas.ac.cn>
    • Co-developer of TU optimization
    • Extensive instruction-level optimization contributions
  7. Chaoyi Liu <lcy285183897@gmail.com>
    • Maintainer of insts-pattern optimization
    • Lead developer of instruction-level testing
  8. Jinyang Shen <2509109915@qq.com>
    • Early-stage developer
    • Contributor to Capstone module optimizations
  9. Rengan Yue <y347812075@163.com>
    • Maintainer of software floating-point module and related optimizations
  10. Xiaotian Wu <yetist@gmail.com>
    • Contributor for adaptation to new-world support

Build

STEP1:

git clone --depth=1 --recursive https://github.com/lat-opensource/lat
cd lat

STEP2:

  • debian
apt install -y git ninja-build libssl-dev libc6 gcc g++ pkg-config libglib2.0-dev libdrm-dev lsb-release make python3-setuptools
  • Arch Linux
pacman -S --noconfirm ninja gcc pkgconf python3 python-setuptools openssl-static openssl
  • AOSC OS
oma install -y gcc nettle pcre2 libffi gnutls glib zlib glib-static libgcrypt-static libgpg-error-static libnfs-static pcre-static zlib-static zstd-static openssl-static pkg-config ninja

STEP3:

./latxbuild/build-release.sh

AVX Instruction Support

To build a version that supports AVX instructions, you need to add parameters during compilation:

./latxbuild/build-release.sh -a

To meet software compatibility requirements, enabling the reporting of AVX-related CPUID information in LATX requires a separate setting:

export LATX_AVX_CPUID=1

Future Plans (TODO)

Future optimizations and improvements include but are not limited to:

  • [ ] Support for advanced x86 instruction extensions (e.g., AVX).
  • [ ] Further expansion of library pass-through optimization coverage.
  • [ ] Development of detailed performance analysis toolchains for quick bottleneck identification.
  • [ ] Enhanced documentation and user guidance.

We welcome discussions, feature requests, bug reports, and suggestions through Issues. Community and developer involvement is warmly invited to further the LoongArch ecosystem.

License

This project is a secondary development based on the QEMU. The original QEMU project is released under the GNU General Public License version 2 (GPLv2).

Accordingly, this project is also licensed under the terms of the GPLv2.

Acknowledgments

Special thanks to the QEMU and box64 projects and their developers for their invaluable open-source contributions and support.

If you have any questions or suggestions, please feel free to engage with us through Issues!