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
+
+