Introduction

The documentation for LoongArch.

  • You can find documents online here.

  • You can find all historical versions here.

The HTML versions are more readable than the PDF versions, not only because there exist tables of excessive length, but also because the theme of HTML versions is easier to customize. To make it easier to download, each HTML page contains embedded CSS and images.

Documents

  • LoongArch Reference Manual - Volume 1: Basic Architecture: This manual describes the basic part of the LoongArch architecture.

  • LoongArch Reference Manual - Volume 2: Vector Extensions: This manual describes the vector extensions (SIMD and Advanced SIMD Extensions) of the LoongArch architecture. (TBD)

    • HTML version.

    • PDF version.

    • Original document.

  • LoongArch Reference Manual - Volume 3: Virtualization and Binary Translation Extensions: This manual describes the virtualization and binary translation extensions of the LoongArch architecture. (TBD)

    • HTML version.

    • PDF version.

    • Original document.

  • Loongson 3A5000/3B5000 Processor Reference Manual - Multicore Processor Architecture, Register Descriptions and System Software Programming Guide: This manual introduces the Loongson 3A5000/3B5000 multicore processor architecture and register descriptions.

  • Loongson 7A1000 Bridge User Manual: This manual describes the overall bridge architecture, clock structure, address space, configuration registers, and individual functional interfaces, primarily for BIOS and kernel developers.

  • LoongArch ELF psABI: This manual describes the LoongArch ELF psABI.

  • LoongArch toolchain conventions: This document describes the command-line interface and relevant OS conventions of LoongArch toolchains.

  • LoongArch Processor SMBIOS Spec: This document introduces additional information about LoongArch in SMBIOS.

Translator’s Note

Due to the limited knowledge of the translators, there are some inevitable errors and omissions existing in this document, please feel free to correct.

P.S. Since the academic level of the original authors is extraordinary high, words and phrases in the original documents are so profound that the translators with limited knowledge could not express them accurately even if they tried their best.

Getting Started

We strongly recommend that you develop on Linux/UNIX or macOS. If you want to develop on Windows, see Developing on Windows first.

  1. Make sure the Ruby development environment is installed.

  2. Install bunlder:

    gem install bundler

  3. Clone this project:

    git clone https://github.com/loongson/LoongArch-Documentation

  4. Enter the project repo and install the gems into the project using the bundle command (this will take a while, during which time about 20MB of data will be downloaded):

    cd LoongArch-Documentation
bundle config set --local path .bundle/gems
bundle

  5. Now you can generate the documents.

    • Convert AsciiDoc to both HTML and PDF:

      bundle exec rake book:all

    • Convert AsciiDoc to HTML only:

      bundle exec rake book:html

    • Convert AsciiDoc to PDF only:

      bundle exec rake book:pdf

    • Convert specified book.adoc to HTML:

      bundle exec rake book:html['book.adoc']

    • Convert specified book.adoc to PDF:

      bundle exec rake book:pdf['book.adoc']

Contributing

Thank you for taking the time to contribute!

You can create an issue or submit a pull request directly. If you submit a pull request, you can see the preview version here after successful rendering.

Please follow the Style Guide when writing documents.

The HTML versions of documents will be deployed automatically, while the PDF versions will be published manually. If you find an issue in the documents as found on the release page, please cross-check that it is still present in this repo. The issue may have already been corrected, but the changes have not been published yet.

Branch gh-pages is generated by Github Actions, which is used to publish a project site by Github Pages. So you should not modify this branch directly.

References

Troubleshooting

Developing on Windows

Some of the file paths are so long that they exceed the 260-character limit of the Windows API, which can cause some strange problems.

In Windows 10 version 1607 and later, these problems can be solved. If you are using an earlier version, or if you don’t want to do some extra operations, you might consider using Docker, refer to Developing on Docker for more details.

  1. Enable long paths.

  2. Use the latest Git. Execute all commands with Git Bash. Run git config --global core.longpaths true to modify the global configuration or run git config core.longpaths true in the repo to modify the local configuration.

  3. Use the latest JRuby instead of Ruby.

The rest is the same as in Getting Started, but JRuby runs much slower and may have cmd popups when running commands.

Developing on Docker

We assume you know how to develop with Docker. If you don’t, please refer to the official tutorial.

You may find the official Docker container useful.

License

This work is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-nd/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

Contributors

Since the release of the project, we have gotten several errata and content changes donated. Here are all the people who have contributed to LoongArch Documentation as an open source project. Thank you everyone for helping make this project better.

The contributors are listed in alphabetical order:

Chao LI <lichao@loongson.cn>
Chenghua Xu <xuchenghua@loongson.cn>
Dandan Zhang <zhangdandan@loongson.cn>
Feiyang Chen <chenfeiyang@loongson.cn>
FreeFlyingSheep <fyang.168.hi@163.com>
Konstantin Romanov <konstantinsromanov@gmail.com>
LI Chao <lichao@loongson.cn>
limeidan <limeidan@loongson.cn>
liuzhensong <liuzhensong@loongson.cn>
mengqinggang <mengqinggang@loongson.cn>
Qi Hu <huqi@loongson.cn>
qmuntal <quimmuntal@gmail.com>
tangxiaolin <tangxiaolin@loongson.cn>
WANG Xuerui <git@xen0n.name>
wangguofeng <wangguofeng@loongson.cn>
Wu Xiaotian <wuxiaotian@loongson.cn>
Wu Xiaotian <yetist@gmail.com>
Xi Ruoyao <xry111@mengyan1223.wang>
Yang Yujie <yangyujie@alumni.sjtu.edu.cn>
Yang Yujie <yangyujie@loongson.cn>
Yanteng <siyanteng@loongson.cn>
Yanteng Si <siyanteng@loongson.cn>
Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.