Add LoongArch-Old-and-New-World-Differences

README.adoc

@@ -50,3 +50,8 @@ To make it easier to download, each HTML page contains embedded CSS and images.
 
 * LoongArch Processor SMBIOS Spec: This document introduces additional information about LoongArch in SMBIOS.
 ** https://loongson.github.io/LoongArch-Documentation/LoongArch-Processor-SMBIOS-Spec-EN.html[HTML version].
+
+* LoongArch ABI 1.0 and ABI 2.0 Differences: This document describes the differences between the old and new software environments of LoongArch.
+** https://loongson.github.io/LoongArch-ABI-1.0-and-ABI-2.0-Differences-EN.html[HTML version].
+** https://loongson.github.io/LoongArch-ABI-1.0-and-ABI-2.0-Differences-EN.pdf[PDF version].
+

docs/LoongArch-ABI-1.0-and-ABI-2.0-Differences-CN.adoc

@@ -0,0 +1,61 @@
+= LoongArch ABI 1.0 和 ABI 2.0  差异
+龙芯中科技术股份有限公司
+:docinfodir: ../themes
+:docinfo: shared
+:doctype: book
+:toc: left
+:toc-title: 目录
+:scripts: cjk
+
+== 概述
+
+LoongArch 的软件生态经历了两个阶段。第一阶段是商业化的产品阶段，在这一阶段，公司的研发重点是从无到有的生态建设阶段，而且带了很多包袱；第二阶段是软件包的 upstream 阶段，在这一阶段，负责相关软件包（尤其是底层的编译器、内核等）的工程师听取了社区 maintainer 和广大开发者的意见，陆续对代码进行了局部重构，同时也甩掉了一些包袱。
+
+第二阶段大概持续了两年，对于一个商业公司来说，时间相当漫长，这是不可接受的。所以在此期间，产品版一直使用第一阶段的软件生态，该阶段软件生态被公司的工程师称为 ABI 1.0 （俗称旧世界），且用户只能获取到二进制软件包，截止到今天，我们使用的 loongnix、uos、Kylin 等商业操作系统发行版都属于 ABI 1.0。
+
+与 ABI 1.0 相对应的，第二阶段的 upstream 软件生态被工程师和广大社区开发者称之为 ABI 2.0 （俗称新世界），ABI 2.0 的软件生态有一个特点，即我们可以直接从社区拉下来软件包的源代码，在 LoongArch 机器上编译安装后，能直接运行，所以，ABI 2.0 是对开源友好的，我们现在能获取到的 ABI 2.0 操作系统发行版有 CLFS、Archlinux、Gentoo（upstreamed）。
+
+=== LoongArch的 ABI 1.0/2.0 的差异一共有四个层次
+
+* 固件
+* 引导器
+* 内核
+* 操作系统
+
+==== 固件
+
+ABI 1.0 和 ABI 2.0 在固件层面的区分主要在于 EFI 应用程序启动时 MMU 所处状态，以及各数据结构中指针字段所含地址的形式。
+
+由于 UEFI、ACPI 规范规定了固件必须使用物理地址，而产品版固件使用的是虚拟地址，为了进规范，所以 ABI 2.0 固件必须改用物理地址；ABI 1.0 使用 X86 中断控制器数据结构，ABI 2.0 使用龙芯中断控制器数据结构；另外新 ABI 1.0 使用的 UEFI 数据结构也不太相同。
+
+==== 引导器
+
+grub 以引导不同格式的内核来区分 ABI 1.0 和 ABI 2.0。只能识别 ELF 内核的为 ABI 1.0，只能识别 PE 格式的 Linux EFI stub 的为 ABI 2.0；ABI 1.0 传递 rd_start/rd_size，ABI 2.0 传递 initrd，并增加了 Loadfile2 在内部传递。
+
+==== 内核
+
+内核以不同的引导协议来区分 ABI 1.0 和 ABI 2.0。使用ELF引导协议的为 ABI 1.0，使用 EFI stub 引导协议的为 ABI 2.0。同时，ABI 1.0 内核 NSIG=128，user_pt_regs不导出 orig_a0；ABI 2.0 内核 NSIG=64，user_pt_regs 要导出 orig_a0；ABI 1.0 的 MINSIGSTKSZ/SIGSTKSZ=2048/8192，ABI 2.0 的 MINSIGSTKSZ/SIGSTKSZ=4096/16384；另外，ABI 1.0/2.0 内核在 ucontext、sigcontext、rt_sigframe 等结构体上也有些许差异。感兴趣的读者可以去 lore.kernel.org 的 linux-arch 存档里面对比 LoongArch 内核进上游的各个版本补丁之间的差异。
+
+==== 操作系统
+
+OS 以不同的动态链接器路径来区分 ABI 1.0 和 ABI 2.0。ABI 1.0 使用 /lib64/ld.so.1，ABI 2.0 使用 /lib64/ld-linux-loongarch-lp64d.so.1；ABI 1.0 有79、80系统调用，ABI 2.0 没有；ABI 1.0 的/proc/cpuinfo字段名称是小写，ABI 2.0 的大都改为首字母大写；Glibc symbol version 也有差异。
+
+在日常开发过程中，OS开发者会更关注软件版本，所以这里列一个待完善的表格，后续有需要，请开发者及时提pr修改。
+
+.ABI 1.0/2.0 具有标志性的软件版本
+|===
+|名称 |ABI 1.0 |ABI 2.0
+
+|gcc
+|8.3
+|12.0
+
+|glibc symbol version
+|2.27
+|2.36
+
+|linux
+|4.19
+|5.19
+|===
+

docs/LoongArch-ABI-1.0-and-ABI-2.0-Differences-EN.adoc

@@ -0,0 +1,61 @@
+= LoongArch ABI 1.0 and ABI 2.0 Differences
+Loongson Technology Corporation Limited
+:docinfodir: ../themes
+:docinfo: shared
+:doctype: book
+:toc: left
+
+== Introduction
+
+LoongArch's software ecology has gone through two stages. The first phase is the commercial product stage, in which the company's R&D focused on building the ecology from scratch, and brought a lot of baggage with it; the second stage is the package upstream stage, in which the engineers responsible for the relevant packages (especially the underlying compiler, kernel, etc.) listened to the opinions of community maintainers and developers, and refactored the code partially one after another, and also got rid of some package.
+
+The second stage lasted about two years, which is a long time for a commercial company and is unacceptable. So during this time, the product version has been using the first stage of the software ecology, which is called ABI 1.0 (commonly known as the old world) by the company's engineers, and users only have access to binary packages, and as of today, we use loongnix, uos, Kylin, and other commercial OS distributions that belong to ABI 1.0.
+
+The second stage of upstream software ecology is called ABI 2.0 (commonly known as the new world) by engineers and community developers. Archlinux, Gentoo (upstreamed).
+
+=== LoongArch's ABI 1.0/2.0 difference has four levels
+
+* BIOS
+* grub
+* linux
+* OS
+
+==== BIOS
+
+The difference between ABI 1.0 and ABI 2.0 at the BIOS level lies mainly in the state of the MMU at the start of the EFI application and in the form of the addresses contained in the pointer fields of each data structure.
+
+Since the UEFI and ACPI specifications require the BIOS to use physical addresses, while the product version BIOS uses virtual addresses, the ABI 2.0 BIOS must change to physical addresses in order to enter the specifications; ABI 1.0 uses the X86 interrupt controller data structure, while ABI 2.0 uses the Loongson interrupt controller data structure; in addition, the new ABI 1.0 uses a different UEFI data structure.
+
+==== grub
+
+grub distinguishes between ABI 1.0 and ABI 2.0 by bootstrapping kernels of different formats; ABI 1.0 only recognizes ELF kernels, ABI 2.0 only recognizes PE format Linux EFI stubs; ABI 1.0 passes rd_start/rd_size, ABI 2.0 passes initrd, and adds Loadfile2 for internal passing.
+
+==== linux
+
+The kernel distinguishes ABI 1.0 and ABI 2.0 with different boot protocols: ABI 1.0 with ELF boot protocol, ABI 2.0 with EFI stub boot protocol, and ABI 1.0 with NSIG=128 and user_pt_regs without orig_a0 export; ABI 2.0 with NSIG=64 and user_pt_regs with orig_a0 export; ABI 1.0 with MINSIGSTKSZ/SIGSTKSZ=2048/8192, ABI 2.0 MINSIGSTKSZ/SIGSTKSZ=4096/16384; in addition, ABI 1.0/2.0 kernel has slight differences in ucontext, sigcontext, rt_sigframe and other structures. Interested readers can go to the linux-arch archive at lore.kernel.org to compare the differences between the patches for each version of the LoongArch kernel upstream.
+
+==== OS
+
+The OS distinguishes ABI 1.0 and ABI 2.0 by the different program interpreter; ABI 1.0 uses /lib64/ld.so.1, ABI 2.0 uses /lib64/ld-linux-loongarch-lp64d.so.1; ABI 1.0 has 79 and 80 system calls, ABI 2.0 does not; ABI 1.0's /proc/cpuinfo field name is lowercase, ABI 2.0 has mostly uppercase; Glibc symbol version also differs.
+
+In the daily development process, OS developers will pay more attention to the software version, so here is a table to be improved, subsequent to the need, please submit a modification pull request in a timely manner.
+
+.Key Software Versions for ABI 1.0/2.0
+|===
+|Name |ABI 1.0 |ABI 2.0
+
+|gcc
+|8.3
+|12.0
+
+|glibc symbol version
+|2.27
+|2.36
+
+|linux
+|4.19
+|5.19
+|===
+
+
+

docs/README-CN.adoc

@@ -46,6 +46,9 @@
 * 龙芯架构 SMBIOS 规范：该文档定义了龙芯架构处理器附加信息，是 SMBIOS 结构 type 44 的补充。本文档仅提供 *英文版*。
 ** link:LoongArch-Processor-SMBIOS-Spec-EN.html[HTML 版本]。
 
+* LoongArch ABI 1.0 和 ABI 2.0 差异：该文档描述了LoongArch新旧软件生态的差异。
+** link:LoongArch-ABI-1.0-and-ABI-2.0-Differences-CN.html[HTML 版本]。
+** link:LoongArch-ABI-1.0-and-ABI-2.0-Differences-CN.pdf[PDF 版本]。
 
 [[getting-start]]
 == 开始

docs/README-EN.adoc

@@ -54,6 +54,10 @@ To make it easier to download, each HTML page contains embedded CSS and images.
 * LoongArch Processor SMBIOS Spec: This document introduces additional information about LoongArch in SMBIOS.
 ** link:LoongArch-Processor-SMBIOS-Spec-EN.html[HTML version].
 
+* LoongArch ABI 1.0 and ABI 2.0 Differences: This document describes the differences between the old and new software environments of LoongArch.
+** link:LoongArch-ABI-1.0-and-ABI-2.0-Differences-EN.html[HTML version].
+** link:LoongArch-ABI-1.0-and-ABI-2.0-Differences-EN.pdf[PDF 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.