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

Signed-off-by: Yanteng Si <[email protected]>

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 Old and New World Differences: This document describes the differences between the old and new software environments of LoongArch.
+** https://loongson.github.io/LoongArch-Old-and-New-World-Differences-EN.pdf[HTML version].
+** https://loongson.github.io/LoongArch-Old-and-New-World-Differences-EN.pdf[PDF version].
+

docs/LoongArch-Old-and-New-World-Differences-CN.adoc

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

docs/LoongArch-Old-and-New-World-Differences-EN.adoc

@@ -0,0 +1,83 @@
+= LoongArch-Old-and-New-World-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 stage
+is the commercialized product stage, in which the company's R&D focused
+on the ecological building stage from scratch and brought a lot of baggage;
+the second stage is the upstream stage of the software package, in which
+the engineers responsible for the relevant software packages (especially
+the underlying compiler, kernel, etc.) listened to the opinions of the
+community maintainer and the general developers, and successively The code
+was partially refactored, and some of the baggage was also shed.
+
+
+The second stage lasted about two years, which is quite a long time for a
+commercial company, which is unacceptable. So during this time, the product
+version has been using the software ecology of the first phase, which was
+called the old world by the company's engineers, and users only had access
+to binary packages. As of today, the commercial OS distributions we use,
+such as loongnix, uos, and Kylin, belong to the old world.
+
+
+Corresponding to the old world, the second stage of the upstream software
+ecology is called the new world by engineers and the majority of community
+developers. The new world software ecology has a feature that we can directly
+pull down the source code of the package from the community and be able to
+run it directly after compiling and installing it on the LoongArch machine,
+so the new world is open source friendly, and the new world OS distribution
+that we can get now are CLFS, Archlinux, and Gentoo (upstreamed).
+
+=== LoongArch's old and new worlds have four main levels
+
+* BIOS
+* grub
+* linux
+* OS
+
+==== BIOS
+
+BIOS distinguishes the old and new worlds with different memory addressing
+methods. Those with virtual addresses are the old world, and those with
+physical addresses are the new world.
+
+Because the UEFI and ACPI specifications specify that the BIOS must use a
+physical address, while the product version of the BIOS uses a virtual
+address, in order to enter the specification, so the new world BIOS must
+change to a physical address; the old world uses the X86 interrupt controller
+data structure, the new world uses loongson interrupt controller data structure.
+
+==== grub
+
+grub distinguishes the old world and the new world by bootstrapping kernels
+of different formats. The old world is the one that can only recognize the
+ELF kernel, and the new world is the one that can only recognize the Linux
+EFI stub in PE format; The old world passes rd_start/rd_size, the new world
+passes initrd and adds Loadfile2 to be passed internally.
+
+==== linux
+
+The kernel distinguishes the old world and the new world with different boot
+protocols. Those using the ELF boot protocol are old world and those using
+the EFI stub boot protocol are new world. In addition, old world kernel
+NSIG=128, user_pt_regs does not export orig_a0; new world kernel NSIG=64,
+user_pt_regs should export orig_a0; old world MINSIGSTKSZ/SIGSTKSZ=2048/8192,
+new world MINSIGSTKSZ/ SIGSTKSZ=4096/16384; at the same time, the old and
+new world kernels have slight differences in structures such as ucontext,
+sigcontext, rt_sigframe. Interested readers can go to the linux-arch archive
+at lore.kernel.org to compare the differences between the various versions
+of patches for the LoongArch kernel going upstream.
+
+==== OS
+
+The OS distinguishes the old world and the new world with different lib. The
+old world uses /lib64/ld.so.1 and the new world uses lib64/ld-linux-loongarch-lp64d.so.1;
+the Glibc symbol version also differs, with the old world using 2.27 and the
+new world using 2.36.
+
+

docs/README-CN.adoc

@@ -46,6 +46,9 @@
 * 龙芯架构 SMBIOS 规范：该文档定义了龙芯架构处理器附加信息，是 SMBIOS 结构 type 44 的补充。本文档仅提供 *英文版*。
 ** link:LoongArch-Processor-SMBIOS-Spec-EN.html[HTML 版本]。
 
+* LoongArch新旧世界差异：该文档描述了LoongArch新旧软件生态的差异。
+** link:LoongArch-Old-and-New-World-Differences-CN.html[HTML 版本]。
+** link:LoongArch-Old-and-New-World-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 Old and New World Differences: This document describes the differences between the old and new software environments of LoongArch.
+** link:LoongArch-Old-and-New-World-Differences-EN.html[HTML version].
+** link:LoongArch-Old-and-New-World-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.