Initial support for loongarch64-unknown-linux-gnu

[zhaixiaojuan]

Hi, We hope to add a new port in rust for LoongArch.

LoongArch intro
LoongArch is a RISC style ISA which is independently designed by Loongson
Technology in China. It is divided into two versions, the 32-bit version (LA32)
and the 64-bit version (LA64). LA64 applications have application-level
backward binary compatibility with LA32 applications. LoongArch is composed of
a basic part (Loongson Base) and an expanded part. The expansion part includes
Loongson Binary Translation (LBT), Loongson VirtualiZation (LVZ), Loongson SIMD
EXtension (LSX) and Loongson Advanced SIMD EXtension(LASX).

Currently the LA464 processor core supports LoongArch ISA and the Loongson
3A5000 processor integrates 4 64-bit LA464 cores. LA464 is a four-issue 64-bit
high-performance processor core. It can be used as a single core for high-end
embedded and desktop applications, or as a basic processor core to form an
on-chip multi-core system for server and high-performance machine applications.

Documentations:
ISA:
https://loongson.github.io/LoongArch-Documentation/LoongArch-Vol1-EN.html
ABI:
https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.html
More docs can be found at:
https://loongson.github.io/LoongArch-Documentation/README-EN.html

Since last year, we have locally adapted two versions of rust, rust1.41 and rust1.57, and completed the test locally.
I'm not sure if I'm submitting all the patches at once, so I split up the patches and here's one of the commits

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @wesleywiser (or someone else) soon.

Please see the contribution instructions for more information.

[rust-highfive]

⚠️ Warning ⚠️

• These commits modify compiler targets. (See the Target Tier Policy.)

[bjorn3]

1. Does the LLVM version used by rustc already support it? If so you will probably need to add it to

   rust/src/bootstrap/native.rs

   Line 473 in ff18038

   None => "AVR;M68k",

   and

   rust/config.toml.example

   Line 112 in ff18038

   #experimental-targets = "AVR;M68k"

2. Can you please quote the tier 3 target policy (https://doc.rust-lang.org/rustc/target-tier-policy.html#tier-3-target-policy) and reply inline with an answer to all questions and affirming for each requirement that it is met. See the PR description of Add SOLID targets #86191 as an example how to do this.
3. Can you add the respective documention to src/doc/rustc/src/SUMMARY.md, src/doc/rustc/src/platform-support.md and add a target file to src/doc/rustc/src/platform-support?

[zhaixiaojuan]

Does the LLVM version used by rustc already support it?

Regarding the loongarch architecture, the llvm code is currently being submitted officially, and there are 28 patches that have been merged into the llvm main branch. For details, see https://github.com/llvm/llvm-project

I will answer the policies of the tier 3 target policy one by one later

[zhaixiaojuan]

There are a total of 12 targets in the LoongArch architecture, this PR is about adding support for the loongarch64-unknown-linux-gnu.

Related PRs

• libc: Add loongarch64 support #2765
• cc: Add Loongarch64 support #637

Tier 3 Target Policy

As tier 3 targets, the new targets are required to adhere to the tier 3 target policy requirements. This section quotes each requirement in entirety and describes how they are met.

• A tier 3 target must have a designated developer or developers (the "target maintainers") on record to be CCed when issues arise regarding the target. (The mechanism to track and CC such developers may evolve over time.)

I would be responsible for maintaining the LoongArch target

• Targets must use naming consistent with any existing targets; for instance, a target for the same CPU or OS as an existing Rust target should use the same name for that CPU or OS. Targets should normally use the same names and naming conventions as used elsewhere in the broader ecosystem beyond Rust (such as in other toolchains), unless they have a very good reason to diverge. Changing the name of a target can be highly disruptive, especially once the target reaches a higher tier, so getting the name right is important even for a tier 3 target.

  • Target names should not introduce undue confusion or ambiguity unless absolutely necessary to maintain ecosystem compatibility. For example, if the name of the target makes people extremely likely to form incorrect beliefs about what it targets, the name should be changed or augmented to disambiguate it.

The new target names follow this format: <machine>-<vendor>-<os><fabi_suffix><abiext_suffix>, which is already adopted by most existing targets. denotes the platform vendor name, this field is omitted in some existing targets

More targets will be supported in the future, currently only loongarch64-unknown-linux-gnu is supported.

• Tier 3 targets may have unusual requirements to build or use, but must not create legal issues or impose onerous legal terms for the Rust project or for Rust developers or users.

  • The target must not introduce license incompatibilities.
  • Anything added to the Rust repository must be under the standard Rust license (MIT OR Apache-2.0).
  • The target must not cause the Rust tools or libraries built for any other host (even when supporting cross-compilation to the target) to depend on any new dependency less permissive than the Rust licensing policy. This applies whether the dependency is a Rust crate that would require adding new license exceptions (as specified by the tidy tool in the rust-lang/rust repository), or whether the dependency is a native library or binary. In other words, the introduction of the target must not cause a user installing or running a version of Rust or the Rust tools to be subject to any new license requirements.
  • If the target supports building host tools (such as rustc or cargo), those host tools must not depend on proprietary (non-FOSS) libraries, other than ordinary runtime libraries supplied by the platform and commonly used by other binaries built for the target. For instance, rustc built for the target may depend on a common proprietary C runtime library or console output library, but must not depend on a proprietary code generation library or code optimization library. Rust's license permits such combinations, but the Rust project has no interest in maintaining such combinations within the scope of Rust itself, even at tier 3.
  • Targets should not require proprietary (non-FOSS) components to link a functional binary or library.
  • "onerous" here is an intentionally subjective term. At a minimum, "onerous" legal/licensing terms include but are not limited to: non-disclosure requirements, non-compete requirements, contributor license agreements (CLAs) or equivalent, "non-commercial"/"research-only"/etc terms, requirements conditional on the employer or employment of any particular Rust developers, revocable terms, any requirements that create liability for the Rust project or its developers or users, or any requirements that adversely affect the livelihood or prospects of the Rust project or its developers or users.

We intend to make the contribution fully available under the standard Rust license with no additional legal restrictions whatsoever. This PR does not introduce any new dependency less permissive than the Rust license policy, and we are willing to ensure this doesn't happen for future contributions regarding the new targets.

The new targets don't support building host tools.
A platform-provided C compiler toolchain is required, and obtaining address of the cross toolchain GNU LoongArch toolchain.

• Tier 3 targets should attempt to implement as much of the standard libraries as possible and appropriate (core for most targets, alloc for targets that can support dynamic memory allocation, std for targets with an operating system or equivalent layer of system-provided functionality), but may leave some code unimplemented (either unavailable or stubbed out as appropriate), whether because the target makes it impossible to implement or challenging to implement. The authors of pull requests are not obligated to avoid calling any portions of the standard library on the basis of a tier 3 target not implementing those portions.

The target has implemented the functions in core, alloc, std

• The target must provide documentation for the Rust community explaining how to build for the target, using cross-compilation if possible. If the target supports running tests (even if they do not pass), the documentation must explain how to run tests for the target, using emulation if possible or dedicated hardware if necessary.

See src/doc/rustc/src/platform-support/loongarch-linux.md.

• Neither this policy nor any decisions made regarding targets shall create any binding agreement or estoppel by any party. If any member of an approving Rust team serves as one of the maintainers of a target, or has any legal or employment requirement (explicit or implicit) that might affect their decisions regarding a target, they must recuse themselves from any approval decisions regarding the target's tier status, though they may otherwise participate in discussions.

  • This requirement does not prevent part or all of this policy from being cited in an explicit contract or work agreement (e.g. to implement or maintain support for a target). This requirement exists to ensure that a developer or team responsible for reviewing and approving a target does not face any legal threats or obligations that would prevent them from freely exercising their judgment in such approval, even if such judgment involves subjective matters or goes beyond the letter of these requirements.

• Tier 3 targets must not impose burden on the authors of pull requests, or other developers in the community, to maintain the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a block on the PR based on a tier 3 target. Do not send automated messages or notifications (via any medium, including via @) to a PR author or others involved with a PR regarding a tier 3 target, unless they have opted into such messages.

  • Backlinks such as those generated by the issue/PR tracker when linking to an issue or PR are not considered a violation of this policy, within reason. However, such messages (even on a separate repository) must not generate notifications to anyone involved with a PR who has not requested such notifications.

• Patches adding or updating tier 3 targets must not break any existing tier 2 or tier 1 target, and must not knowingly break another tier 3 target without approval of either the compiler team or the maintainers of the other tier 3 target.

  • In particular, this may come up when working on closely related targets, such as variations of the same architecture with different features. Avoid introducing unconditional uses of features that another variation of the target may not have; use conditional compilation or runtime detection, as appropriate, to let each target run code supported by that target.

We acknowledge these requirements and intend to ensure they are met.

There are no closely related targets at the moment.

[wesleywiser]

Awesome, thanks @zhaixiaojuan! It looks like there's just two UI tests that need to be updated to include a mention of the target and then we can merge.

[xry111]

@xen0n please review.

[xen0n]

@zhaixiaojuan, thanks for submitting the initial code; you did so a bit too early though, with no chance of passing CI, and the LLVM port was still vaporware at the time of your submission. Not to say this is inappropriate behavior, but next time you could use more patience ;-)

And you haven't submitted an MCP for such a user-facing change, per the target tier policy. I've submitted one, at rust-lang/compiler-team#518, but I'm so glad you used the same tuple naming as mine...

Anyway, please keep me CC'd on your future changes. I'm familiar with both MIPS and LoongArch, in addition to general upstream practices, so I hope I could provide useful reviews.

[xen0n]

The document is so hopelessly Chinglish... I'll need some time to edit that into a more readable state, due to $day_job. The target definition seems good though.

[xry111]

@zhaixiaojuan, thanks for submitting the initial code; you did so a bit too early though, with no chance of passing CI, and the LLVM port was still vaporware at the time of your submission. Not to say this is inappropriate behavior, but next time you could use more patience ;-)

So it seems I lost the competition because I didn't expect Rust can be reviewed before LLVM and glibc :). Another reason is I'm mostly lying flat (or 摆烂) w/o a firmware to boot 5.19 kernel (with the "final" version of userspace API).

And, we need to review rust-lang/libc code again once glibc upstreamed, in case something in glibc API changes.

And you haven't submitted an MCP for such a user-facing change, per the target tier policy. I've submitted one, at rust-lang/compiler-team#518, but I'm so glad you used the same tuple naming as mine...

The doc says:

A proposed new tier 3 target must be reviewed and approved by a member of the compiler team based on these
requirements. The reviewer may choose to gauge broader compiler team consensus via a MCP.

So it's not @zhaixiaojuan 's responsibility to raise a MCP.

BTW I've used a different tuple (w/o f64) in my fork but I agree a tuple with f64 is better.

[xen0n]

@zhaixiaojuan, thanks for submitting the initial code; you did so a bit too early though, with no chance of passing CI, and the LLVM port was still vaporware at the time of your submission. Not to say this is inappropriate behavior, but next time you could use more patience ;-)

So it seems I lost the competition because I didn't expect Rust can be reviewed before LLVM and glibc :). Another reason is I'm mostly lying flat (or 摆烂) w/o a firmware to boot 5.19 kernel (with the "final" version of userspace API).

Me too, to some degree; it's completely unexpected to see a port heading straight to main branch, before the underlying ABI is officially frozen. The kernel ABI, while already effectively stable, was definitely not upstream (i.e. in Linus' tree) when this PR was created.

But again, too much hostility to the hardware vendor itself isn't helpful; while the particular vendor might be inexperienced at upstream work at first, everyone invariably grows up and become more competent, and having someone inside the company can surely help.

And thanks for putting the original 摆烂 aside "lying flat" for extra clarity ;-) ("lying flat" is technically equivalent to "躺平", subtly different to "摆烂" which carries a bit stronger mood.)

And, we need to review rust-lang/libc code again once glibc upstreamed, in case something in glibc API changes.

Okay I'll take a look at that code later; it's already merged but currently useless due to this PR still being open, so any fixups should be okay. The Rust ecosystem is quite swift at upgrading libc too. (No pun intended on "swift")

And you haven't submitted an MCP for such a user-facing change, per the target tier policy. I've submitted one, at rust-lang/compiler-team#518, but I'm so glad you used the same tuple naming as mine...

The doc says:

A proposed new tier 3 target must be reviewed and approved by a member of the compiler team based on these
requirements. The reviewer may choose to gauge broader compiler team consensus via a MCP.

So it's not @zhaixiaojuan 's responsibility to raise a MCP.

Hmm, in my vision the LoongArch is to eventually rise to Tier 2 with host tools status, because this is a serious platform fully meant for native use (near drop-in replacement for almost any amd64/arm64 workstation needs), so a MCP is indeed necessary. But here the OP is starting with Tier 3 so I agree a MCP is not necessary in this case. Still we'd really like to have more eyes on the target support so the MCP isn't wasted either...

BTW I've used a different tuple (w/o f64) in my fork but I agree a tuple with f64 is better.

In general Rust target tuples are modeled after Debian multiarch tuples, so f64 for the LP64D ABI. And here we arrive at consensus -- so precious in the Loongson world ;-)

[xry111]

But again, too much hostility to the hardware vendor itself isn't helpful; while the particular vendor might be inexperienced at upstream work at first, everyone invariably grows up and become more competent, and having someone inside the company can surely help.

I don't want to be hostile and I apologize if my words sound hostile. To me Loongson behaves much better than "some x86 and ARM vendors".

I'm kind of disappointed because "I lost a competition" (it does not mean anyone is doing things incorrectly).

And I've been educated many times not to (mis)treat everything as a competition (I have a heavy OI and ICPC background so I have a strange tendency to misbehave in this way. Apologize again for that.)

[xen0n]

But again, too much hostility to the hardware vendor itself isn't helpful; while the particular vendor might be inexperienced at upstream work at first, everyone invariably grows up and become more competent, and having someone inside the company can surely help.

I don't want to be hostile and I apologize if my words sound hostile. To me Loongson behaves much better than "some x86 and ARM vendors".

I'm kind of disappointed because "I lost a competition" (it does not mean anyone is doing things incorrectly).

And I've been educated many times not to (mis)treat everything as a competition (I have a heavy OI and ICPC background so I have a strange tendency to misbehave in this way. Apologize again for that.)

No problem. You and I, as the "community powers", are somehow "racing" with the HW vendor to arguably provide "better" code, because we simply are more experienced than even the vendor, and can express ourselves better with English, so there might be some sense of superiority (优越感) in play. We indeed have to kill that superiority mindset. It's the vendor developers that are getting paid for the work after all, not us; in addition to that, true high-quality and/or launch-day support cannot be achieved with outsiders due to the embargoes involved for future models, so we must work together anyway.

[zhaixiaojuan]

@xen0n @xry111
I am very happy to get your comments and opinions. I have very little experience working in the community, and I have a lot to learn and ask from you, and I look forward to your guidance.

The document is so hopelessly Chinglish... I'll need some time to edit that into a more readable state, due to $day_job. The target definition seems good though.

If you have the time, I'd love to see your revisions and guidance on the documentation to make up for my deficiencies.

So it seems I lost the competition because I didn't expect Rust can be reviewed before LLVM and glibc :). Another reason is I'm mostly lying flat (or 摆烂) w/o a firmware to boot 5.19 kernel (with the "final" version of userspace API).
And, we need to review rust-lang/libc code again once glibc upstreamed, in case something in glibc API changes.

I think we have a cooperative rather than a competitive relationship. There are still many shortcomings in my understanding of rust, so I am glad that you can take the time to review the code and point out inappropriate content.

No problem. You and I, as the "community powers", are somehow "racing" with the HW vendor to arguably provide "better" code, because we simply are more experienced than even the vendor, and can express ourselves better with English, so there might be some sense of superiority (优越感) in play. We indeed have to kill that superiority mindset. It's the vendor developers that are getting paid for the work after all, not us; in addition to that, true high-quality and/or launch-day support cannot be achieved with outsiders due to the embargoes involved for future models, so we must work together anyway.

I will take your advice and guidance seriously for better code for the community. I also look forward to jointly promoting the development of the rust community as a collaborator in the future

[xry111]

I've spotted some Chinglish but my English is not well either.

[xry111]

Suggested change

	[LoongArch] LoongArch is a RISC style ISA which is independently designed by Loongson Technology in China.
	[LoongArch] is a new RISC ISA developed by Loongson Technology, based in China.

[xry111]

Suggested change

	This target can be cross-compiled as `x86_64`, and cross-compilation on other hosts is not currently supported.
	This target can be cross-compiled on a `x86_64-unknown-linux-gnu` host. Cross-compilation on other hosts may work but is not tested.

[xen0n]

"This target can be cross-compiled. Cross-compiling from x86_64-unknown-linux-gnu is known to work; any other host will likely work too."

[xry111]

Suggested change

	Make sure `loongarch64-unknown-linux-gnu-gcc` is included in `$PATH`. Alternatively, you can use GNU LoongArch Toolchain by adding the following to `config.toml`:
	Make sure `loongarch64-unknown-linux-gnu-gcc` can be searched from the directories specified in`$PATH`. Alternatively, you can use GNU LoongArch Toolchain by adding the following to `config.toml`:

[xen0n]

"Make sure loongarch64-unknown-linux-gnu-gcc is in $PATH." is enough. "can be searched from" is Chinglish too ;-)

[xry111]

I think "in $PATH" is some sort of ambigious (it's a directory listed in $PATH or a file in those directories?)

The following is copied from "man execl":

"Can be sought in the directory pathnames specified in the PATH environment variable."

[xry111]

Suggested change

	cc = "loongarch64-unknown-linux-gnu-gcc"
	cc = "/path/to/loongarch64-unknown-linux-gnu-gcc"

I think it's better to use an absolute path for these examples? With no explicit path it's same as a search in $PATH.

[xry111]

Suggested change

	A platform-provided C compiler toolchain is required, and obtaining address of the cross toolchain [GNU LoongArch toolchain](https://github.com/loongson/build-tools/releases).
	A GNU toolchain for LoongArch target is required. It can be downloaded from https://github.com/loongson/build-tools/releases, or built from the source code of GCC (12.1.0 or later) and Binutils (2.39 or later).

I'm not really sure about how to specify the minimal Binutils version, as 2.39 not released yet but 2.38 does not work.

[xry111]

Should we remove "abiext_suffix" for now as it's not used anywhere?

[bors]

📌 Commit a3f0046 has been approved by wesleywiser

It is now in the queue for this repository.

[bjorn3]

Suggested change

	The target name follow this format: `<machine>-<vendor>-<os><fabi_suffix>, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` the operating system name.
	The target name follow this format: `<machine>-<vendor>-<os><fabi_suffix>`, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` the operating system name.

[heiher]

Oops, Is it better to fix this PR or a new one? thanks

[bjorn3]

A new PR works better I think given that this PR is already included in a rollup.