LoongArch-Documentation/docs/README-EN.adoc

= LoongArch Documentation
Loongson Technology Corporation Limited
:docinfodir: ../themes
:docinfo: shared
:doctype: book
:toc: left

== Introduction

The documentation for LoongArch.

* You can find documents online https://loongson.github.io/LoongArch-Documentation[here].

* You can find all historical versions 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. (*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.
** 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.03-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 ELF psABI: This manual describes the LoongArch ELF psABI.
** link:LoongArch-ELF-ABI-EN.html[HTML version].
** link:LoongArch-ELF-ABI-EN.pdf[PDF version].

* LoongArch toolchain conventions: This document describes the command-line interface and relevant OS conventions of LoongArch toolchains.
** link:LoongArch-toolchain-conventions-EN.html[HTML version].
** link:LoongArch-toolchain-conventions-EN.pdf[PDF version].

* LoongArch Processor SMBIOS Spec: This document introduces additional information about LoongArch in SMBIOS.
** link:LoongArch-Processor-SMBIOS-Spec-EN.html[HTML version].

== 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 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']
----

== 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.

Please follow the link:style-guide-EN.html[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 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 documents, and use https://github.com/asciidoctor/asciidoctor-pdf[Asciidoctor PDF] to generate PDF 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].
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.

. 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 project better.

The contributors are listed in alphabetical order:

[source]
----
include::../contributors.txt[]
----