Merge pull request #1 from scylaac/release

Release v2.10, based on the original LoongArch ELF ABI document

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to the Application Binary Interface
+
+## Thank you for taking the time to contribute!
+
+We accept bug fixes and feature proposals through two means: by filing an issue,
+or by submitting a pull request (PR).
+
+## Create an issue
+
+You can create an issue at https://github.com/loongson/la-abi-specs/issues to
+submit bug reports or make proposals.
+
+## Pull request
+
+To contribute fixes or improvements, you are welcome to submit a pull request
+on https://github.com/loongson/la-abi-specs/pull. The workflow for submitting
+a pull request is as follows:
+
+### Sign Contributor License Agreement (CLA)
+
+Contributors must sign CLA before their pull requests can be merged. Please
+contact [email protected] regarding how to sign the CLA.
+
+### Make the actual pull request
+
+Follow [Github pull requests documentation](https://docs.github.com/en/pull-requests)
+to submit the PR.
+
+### Review of pull request
+
+Pull requests need to be reviewed before they can be merged. Anyone can review
+the requests, but approval from at least one Loongson reviewer is required.
+
+### Merging the change
+
+Pull request can be merged once the change has been reviewed properly, which
+can only be done by one of the administrators. If your change hasn't been merged
+for more than a week after it has been accepted, leave a comment on the pull
+request.

Makefile

@@ -0,0 +1,24 @@
+SRC = lapcs.adoc laelf.adoc ladwarf.adoc
+PDF = la-abi.pdf
+
+PDF_THEME = themes/la-abi-pdf.yml
+
+.PHONY: all clean
+
+$(PDF): $(PDF:.pdf=.adoc) $(SRC) $(PDF_THEME)
+	asciidoctor-pdf \
+		-a compress \
+		-a date="$(DATE)" \
+		-a monthyear="$(MONTHYEAR)" \
+		-a pdf-style="$(PDF_THEME)" \
+		-a pdf-fontsdir=fonts \
+		-v \
+		$< -o $@
+
+html: $(patsubst %.adoc, %.html, $(SRC))
+
+%.html: %.adoc
+	asciidoctor $^ -o $@
+
+clean:
+	-rm -rf $(patsubst %.adoc, %.html, $(SRC))

README.md

@@ -0,0 +1,91 @@
+# Application Binary Interface for the LoongArch™ Architecture
+
+This is the official documentation of the Application Binary Interface
+for the LoongArch™ Architecture.
+
+## Releases
+
+The latest ABI documentation releases are available at
+https://github.com/loongson/la-abi-specs and are licensed under the Creative
+Commons Attribution-NonCommercial-NoDerivatives 4.0 International
+(CC BY-NC-ND 4.0) License.
+
+## Defect reports
+
+Please report defects in or enhancements to the specifications in this folder to
+the [issue tracker page on GitHub](https://github.com/loongson/la-abi-specs/issues).
+
+## List of documents
+
+specification                                            | latest
+---                                                      | ---
+Procedure Call Standard for the LoongArch™ Architecture  | [lapcs](lapcs.adoc)
+ELF for the LoongArch™ Architecture                      | [laelf](laelf.adoc)
+DWARF for the LoongArch™ Architecture                    | [ladwarf](ladwarf.adoc)
+
+## Contributing
+
+Please refer to the contribution guidelines in [CONTRIBUTING](CONTRIBUTING.md).
+
+## License
+
+The ABI documents and their source files are currently licensed under the
+Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International
+(CC BY-NC-ND 4.0) License. Contributions to these files are accepted under
+the same 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.
+
+## Revision History
+
+Legacy versions of the documents were released at the Github repository
+[LoongArch-Documentation](https://github.com/loongson/LoongArch-Documentation).
+These include version 1.00, 2.00 and 2.01.
+
+All changes to the documents in a subsequent release should be declared in their
+change history section respectively. Timestamps in the form `YYYYMMDD` should be used
+for versioning of the individual documents in this folder, and a global version
+number which correspond to a combination of individual document versions will still
+be assigned to every new release of this collection.
+
+This global version number will continue to follow the legacy versioning scheme,
+where a change of the major version (currently 1 and 2) could potentially degrade
+binary compatibility between objects conforming to these specifications, while a
+change to the two-digit minor version signifies other bugfixes and improvements.
+
+Please note that we do not expect the major version to change at any time in the
+forseeable future, and the minor version may increase by more than 1 in a new public
+release for project management purposes.
+
+- **v1.00**
+
+    * Add register usage convention, data type conventions and the list of ELF relocation types.
+
+- **v2.00**
+
+    * Add description of ILP32 data model.
+    * Add description of return value register aliases.
+    * Add relocation types with direct immediate-filling semantics.
+    * Add ABI version porting guidelines for toolchain implementations.
+    * Add link to SysV gABI documentation.
+    * Adjust asciidoc code style.
+
+- **v2.01**
+
+    * Adjust description of ABI type encoding scheme.
+    * Add header for all tables.
+
+- **v2.10**
+
+    * Split the original psABI documentation (v2.01) into the `lapcs` and `laelf` documents.
+    * Add the *DWARF standard for the LoongArch™ architecture* (`ladwarf`) document.
+    * Differentiate machine data types with the C/C++ types.
+    * Clarify parameter passing rules for small `struct`s that contain both floating-point and integer members.
+    * Clarify parameter passing rules for `struct`s that contain zero-length arrays or bitfields.
+
+## I18n
+
+This specification is written in both English and Chinese. In the event of any
+inconsistency between the same document version in two languages, the Chinese
+version shall prevail.

VERSION

@@ -0,0 +1,7 @@
+Application Binary Interface for the LoongArch™ Architecture, version 2.10
+
+List of documents:
+
+* Procedure Call Standard for the LoongArch™ Architecture, version 20230519
+* ELF for the LoongArch™ Architecture, version 20230519
+* DWARF for the LoongArch™ Architecture, version 20230425

la-abi.adoc

@@ -0,0 +1,37 @@
+= Application Binary Interface for the LoongArch™ Architecture
+Version 2.10
+Copyright © Loongson Technology 2023. All rights reserved.
+:toc: macro
+:toclevels: 3
+:toctitle:
+:doctype: article
+:icons: font
+
+toc::[]
+
+== Preamble
+
+This is the official documentation of the Application Binary Interface
+for the LoongArch™ Architecture.
+
+The latest ABI documentation releases are available at
+https://github.com/loongson/la-abi-specs and are licensed under the Creative
+Commons Attribution-NonCommercial-NoDerivatives 4.0 International
+(CC BY-NC-ND 4.0) 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.
+
+This specification is written in both English and Chinese. In the event of any
+inconsistency between the same document version in two languages, the Chinese
+version shall prevail.
+
+:sectnums:
+<<<
+include::lapcs.adoc[]
+
+<<<
+include::laelf.adoc[]
+
+<<<
+include::ladwarf.adoc[]

ladwarf.adoc

@@ -0,0 +1,108 @@
+= DWARF for the LoongArch™ Architecture
+Version 20230425 +
+Copyright © Loongson Technology 2023. All rights reserved.
+
+== Abstract
+
+This document describes the use of the DWARF debugging information format
+in the Application Binary Interface (ABI) for the LoongArch architecture.
+
+== Keywords
+
+LoongArch, DWARF, Stack frame, CFA, CIE
+
+== Version History
+
+[%header,cols="^2,8"]
+|====
+|Version
+^|Description
+
+|20230425
+|initial version.
+|====
+
+== Overview
+
+The DWARF debugging format for LoongArch uses _DWARF Standard_ <<dwarfstd>>.
+This specification only describes LoongArch-specific definitions.
+
+== Terms and Abbreviations
+
+**DWARF** +
+Debugging With Attributed Record Formats.
+
+== LoongArch-specific DWARF Definitions
+
+=== DWARF Register Numbers
+
+DWARF Standard suggests that the mapping from a DWARF register name to a
+target register number should be defined by the ABI for the target architecture.
+DWARF register names are encoded as unsigned LEB128 integers.
+
+The table below lists the mapping from DWARF register numbers to LoongArch64
+registers.
+
+.Mapping from DWARF register numbers to LoongArch64 registers
+[%header,cols="^1,^1,^2"]
+[width=80%]
+|===
+| DWARF Register Number | LoongArch64 Register Name | Description
+
+| 0 -  31               | `$r0` - `$r31`            | General-purpose Register
+| 32 - 63               | `$f0` - `$f31`            | Floating-point Register
+| 64 -                  |                           | Reserved for future standard extensions
+|===
+
+
+=== CFA (Canonical Frame Address)
+
+The term Canonical Frame Address (CFA) is defined in _DWARF Debugging Information Format Version 5_ <<dwarf5>>, §6.4 Call Frame Information.
+
+This ABI adopts the typical definition of `CFA` given there:
+
+  the CFA is defined to be the value of the stack pointer at the call site in the
+  previous frame (which may be different from its value on entry to the current frame).
+
+The position of `CFA` in frame structure of LoongArch is shown below:
+
+           |                |
+           | previous frame |
+           |________________|
+  CFA----->|________________|<------ previous sp
+           |_______ra_______|
+           |_______fp_______|
+           |                |
+           | current frame  |
+           |________________|
+           |________________|<------ current sp
+
+
+=== CIE (Common Information Entry)
+
+The `$r1` register is used to store the return address of the function,
+and the value of the return address register field in `CIE` structure is `1`.
+
+The default `CFA` register at the function entry is `$r3`, and initial_instructions
+field in `CIE` structure can define `3` as the default `CFA` register.
+
+=== Call frame instructions
+
+Using the existing definitions in DWARF Standard.
+
+
+=== DWARF expression operations
+
+Using the existing definitions in DWARF Standard.
+
+
+[bibliography]
+== References
+
+* [[[dwarfstd]]] DWARF Standard,
+https://dwarfstd.org/
+
+* [[[dwarf5]]] DWARF Debugging Information Format Version 5,
+https://dwarfstd.org/doc/DWARF5.pdf
+
+