mirror of
https://github.com/loongson/LoongArch-Documentation.git
synced 2026-10-16 21:50:36 +08:00
Feiyang Chen= LoongArch Documentation Loongson Technology Corporation Limited :docinfodir: themes :docinfo: shared :doctype: book :toc: left == Introduction This is the translation of LoongArch documentation. * You can find documents online https://loongson.github.io/LoongArch-Documentation[here]. * You can find all historical versions here https://github.com/loongson/LoongArch-Documentation/releases[here]. The HTML versions are more readable than the PDF versions, not only because there exists 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. ** link:LoongArch-Vol1-EN.html[HTML version]. ** link:LoongArch-Vol1-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf[Original document]. * LoongArch Reference Manual - Volume 2: Vector Extensions: This manual describes the vector extensions (SIMD and Advanced SIMD Extensions) of the LoongArch architecture. ** link:LoongArch-Vol2-EN.html[HTML version]. ** link:LoongArch-Vol2-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol2-v1.00-CN.pdf[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. ** link:LoongArch-Vol3-EN.html[HTML version]. ** link:LoongArch-Vol3-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol3-v1.00-CN.pdf[Original document]. * Loongson 3A5000/3B5000 Registers Technical 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. ** link:Loongson-3A5000-usermanual-EN.html[HTML version]. ** link:Loongson-3A5000-usermanual-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-v1.00-CN.pdf[Original document]. * 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. ** link:Loongson-7A1000-usermanual-EN.html[HTML version]. ** link:Loongson-7A1000-usermanual-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-v2.00-CN.pdf[Original document]. * LoongArch ABI: This manual describes the LoongArch ABI. ** link:LoongArch-ABI-EN.html[HTML version]. ** link:LoongArch-ABI-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ABI-v1.00-CN.pdf[Original document]. == Translator`'s Note These documents were translated by Yanteng Si and Feiyang Chen. 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 Start We *strongly recommend* that you develop on Linux/UNIX or macOS. If you want to develop on Windows, see <<Developing on Windows>> first. . Make sure the https://www.ruby-lang.org/en/downloads[Ruby development environment] is installed. . Install bunlder: + [source] ---- gem install bundler ---- . Clone this project: + [source] ---- git clone https://github.com/loongson/LoongArch-Documentation ---- . 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): + [source] ---- cd LoongArch-Documentation && bundle config set --local path .bundle/gems && bundle ---- . Now you can generate the documents. + * Convert AsciiDoc to both HTML and PDF: + [source] ---- bundle exec rake book:all ---- * Convert AsciiDoc to HTML only: + [source] ---- bundle exec rake book:html ---- * Convert AsciiDoc to PDF only: + [source] ---- bundle exec rake book:pdf ---- * Convert specified `book.adoc` to HTML: + [source] ---- bundle exec rake book:html['book.adoc'] ---- * Convert specified `book.adoc` to PDF: + [source] ---- bundle exec rake book:pdf['book.adoc'] ---- == Questions [qanda] Are there any prerequisites I need to take?:: Install the environment refer to the <<Getting Start>>, and then see <<References>> for more information. Why not use autogenerated section IDs?:: Due to many duplicate titles, custom section IDs (`+[[id]]+`) are better when being referenced (`+<<id,name>>+`). Why not use named HTML entities?:: Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+×+`), so you have to use entity numbers (e.g. `+×+`) here. Are there any convenience tools?:: See https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] for tools that may be useful (e.g. for generating a list of tables). == 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 https://loongson.github.io/LoongArch-Documentation-Preview[here] after successful rendering. The HTML versions of documents will be deployed automatically, while the PDF versions will be published manually. If you find an issue about the documents as found on the https://github.com/loongson/LoongArch-Documentation/releases[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 https://docs.github.com/en/actions[Github Actions], which is used to publish a project site by https://docs.github.com/en/pages[Github Pages]. So you should not modify this branch directly. == References * This project was inspired by https://github.com/progit/progit2[Pro Git, Second Edition]. * This project use https://asciidoctor.org[Asciidoctor] to generate HTML, and use https://github.com/asciidoctor/asciidoctor-pdf[Asciidoctor PDF] to generate documents. * See https://docs.asciidoctor.org/asciidoc/latest[AsciiDoc Language Documentation] for AsciiDoc syntax. * See https://github.com/darshandsoni/asciidoctor-skins[ asciidoctor-skins] for CSS stylesheets for asciidoctor. See https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide] for the style of a PDF file generated by Asciidoctor PDF from AsciiDoc. == 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. . https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later[Enable] long paths. . Use the latest https://git-scm.com/downloads[Git]. 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. . Use the latest https://www.jruby.org/download[JRuby] instead of Ruby. The rest is the same as in <<Getting Start>>, but JRuby runs much slower and may have cmd popups when running commands. === Developing on Docker We assume you know how to develop with https://www.docker.com[Docker]. If you don`'t, please refer to the https://docs.docker.com/get-started/overview[official tutorial]. You may find the official https://hub.docker.com/r/asciidoctor/docker-asciidoctor[Docker container] useful. == License include::LICENSE[] == 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 https://github.com/loongson/LoongArch-Documentation[LoongArch Documentation] as an open source project. Thank you everyone for helping make this a better book for everyone. The contributors are listed in alphabetical order. [source] ---- include::contributors.txt[] ----