deleted file mode 100644
@@ -1,41 +0,0 @@
-:orphan:
-
-==========================================
-loongson3 virt generic platform (``virt``)
-==========================================
-
-The ``virt`` machine use gpex host bridge, and there are some
-emulated devices on virt board, such as loongson7a RTC device,
-IOAPIC device, ACPI device and so on.
-
-Supported devices
------------------
-
-The ``virt`` machine supports:
-- Gpex host bridge
-- Ls7a RTC device
-- Ls7a IOAPIC device
-- Ls7a ACPI device
-- Fw_cfg device
-- PCI/PCIe devices
-- Memory device
-- CPU device. Type: Loongson-3A5000.
-
-CPU and machine Type
---------------------
-
-The ``qemu-system-loongarch64`` provides emulation for virt
-machine. You can specify the machine type ``virt`` and
-cpu type ``Loongson-3A5000``.
-
-Boot options
-------------
-
-Now the ``virt`` machine can run test program in ELF format and the
-method of compiling is in target/loongarch/README.
-
-.. code-block:: bash
-
- $ qemu-system-loongarch64 -machine virt -m 4G -cpu Loongson-3A5000 \
- -smp 1 -kernel hello -monitor none -display none \
- -chardev file,path=hello.out,id=output -serial chardev:output
new file mode 100644
@@ -0,0 +1,41 @@
+:orphan:
+
+=================================================
+LoongArch generic virtualized platform (``virt``)
+=================================================
+
+The ``virt`` machine has a GPEX host bridge, and some more emulated devices
+such as the LS7A RTC, IOAPIC, ACPI device and so on.
+
+Being a machine type designed for virtualized use cases, the machine resembles
+a Loongson 3A5000 + LS7A1000 board, but is not an exact emulation.
+For example, only cascading of the EXTIOI interrupt is implemented.
+Also, only the RTC block of the LS7A1000 is emulated; for the other devices
+the QEMU models are used.
+Normally you do not need to care about any of these.
+
+Supported devices
+-----------------
+
+The ``virt`` machine supports:
+
+- GPEX host bridge
+- LS7A RTC device
+- LS7A IOAPIC device
+- LS7A ACPI device
+- fw_cfg device
+- PCI/PCIe devices
+- Memory device
+- CPU device. Defaults to ``qemu64-v1.00``.
+
+Boot options
+------------
+
+Some more information could be found in the QEMU sources at
+``target/loongarch/README.md``. A simple example being:
+
+.. code-block:: bash
+
+ $ qemu-system-loongarch64 -machine virt -m 4G -smp 1 -kernel hello \
+ -monitor none -display none \
+ -chardev file,path=hello.out,id=output -serial chardev:output
deleted file mode 100644
@@ -1,99 +0,0 @@
-- Introduction
-
- LoongArch is the general processor architecture of Loongson.
-
- The following versions of the LoongArch core are supported
- core: 3A5000
- https://github.com/loongson/LoongArch-Documentation/releases/download/2021.08.17/LoongArch-Vol1-v1.00-EN.pdf
-
- We can get the latest loongarch documents at https://github.com/loongson/LoongArch-Documentation/tags.
-
-
-- System emulation
-
- Mainly emulate a virt 3A5000 board and ls7a bridge that is not exactly the same as the host.
- 3A5000 support multiple interrupt cascading while here we just emulate the extioi interrupt
- cascading. LS7A1000 host bridge support multiple devices, such as sata, gmac, uart, rtc
- and so on. But we just realize the rtc. Others use the qemu common devices. It does not affect
- the general use. We also introduced the emulation of devices at docs/system/loongarch/virt.rst.
-
- This version only supports running binary files in ELF format, and does not depend on BIOS and kernel file.
- You can compile the test program with 'make & make check-tcg' and run the test case with the following command:
-
- 1. Install LoongArch cross-tools on X86 machines.
-
- Download cross-tools.
-
- wget https://github.com/loongson/build-tools/releases/download/2022.05.29/loongarch64-clfs-5.0-cross-tools-gcc-full.tar.xz
-
- tar -vxf loongarch64-clfs-5.0-cross-tools-gcc-full.tar.xz -C /opt
-
- Config cross-tools env.
-
- . setenv.sh
-
- setenv.sh:
-
- #!/bin/sh
- set -x
- CC_PREFIX=/opt/cross-tools
-
- export PATH=$CC_PREFIX/bin:$PATH
- export LD_LIBRARY_PATH=$CC_PREFIX/lib:$LD_LIBRARY_PATH
- export LD_LIBRARY_PATH=$CC_PREFIX/loongarch64-unknown-linux-gnu/lib/:$LD_LIBRARY_PATH
- set +x
-
- 2. Test tests/tcg/multiarch.
-
- ./configure --disable-rdma --disable-pvrdma --prefix=/usr \
- --target-list="loongarch64-softmmu" \
- --disable-libiscsi --disable-libnfs --disable-libpmem \
- --disable-glusterfs --enable-libusb --enable-usb-redir \
- --disable-opengl --disable-xen --enable-spice --disable-werror \
- --enable-debug --disable-capstone --disable-kvm --enable-profiler
-
- cd build/
-
- make && make check-tcg
-
- or
-
- ./build/qemu-system-loongarch64 -machine virt -m 4G -cpu Loongson-3A5000 -smp 1 -kernel build/tests/tcg/loongarch64-softmmu/hello -monitor none -display none -chardev file,path=hello.out,id=output -serial chardev:output
-
-- Linux-user emulation
-
- We already support Linux user emulation. We can use LoongArch cross-tools to build LoongArch executables on X86 machines,
- and We can also use qemu-loongarch64 to run LoongArch executables.
-
- 1. Config cross-tools env.
-
- see System emulation.
-
- 2. Test tests/tcg/multiarch.
-
- ./configure --static --prefix=/usr --disable-werror --target-list="loongarch64-linux-user" --enable-debug
-
- cd build
-
- make && make check-tcg
-
- 3. Run LoongArch system basic command with loongarch-clfs-system.
-
- - Config clfs env.
-
- wget https://github.com/loongson/build-tools/releases/download/2022.05.29/loongarch64-clfs-system-5.0.tar.bz2
-
- tar -vxf loongarch64-clfs-system-5.0.tar.bz2 -C /opt/clfs
-
- cp /opt/clfs/lib64/ld-linux-loongarch-lp64d.so.1 /lib64
-
- export LD_LIBRARY_PATH="/opt/clfs/lib64"
-
- - Run LoongArch system basic command.
-
- ./qemu-loongarch64 /opt/clfs/usr/bin/bash
- ./qemu-loongarch64 /opt/clfs/usr/bin/ls
- ./qemu-loongarch64 /opt/clfs/usr/bin/pwd
-
-- Note.
- We can get the latest LoongArch documents or LoongArch tools at https://github.com/loongson/
new file mode 100644
@@ -0,0 +1,75 @@
+# QEMU LoongArch target
+
+## Introduction
+
+LoongArch is the general-purpose instruction set architecture developed by
+Loongson. Documentation can be found at [the LoongArch Documentation repository][docs-repo].
+
+[docs-repo]: https://github.com/loongson/LoongArch-Documentation
+
+Currently the following CPU models are supported:
+
+|`-cpu name`|Description|
+|:----------|:----------|
+|`qemu64-v1.00`|Virtual model similar to the Loongson 3A5000, compatible with LoongArch64 v1.00.|
+
+## Trying out
+
+For some of the steps or development/debug purposes, you may have to set up
+cross toolchains if you are not running on native LoongArch hardware.
+
+Now that LoongArch support has been merged in the GNU toolchain packages and
+Linux, you may make your own toolchains like with any other architectures;
+Loongson also has made available [their pre-compiled toolchain binaries for x86][build-tools].
+You may follow the respective instructions to set up your development
+environment.
+
+[build-tools]: https://github.com/loongson/build-tools
+
+### System emulation
+
+Both raw ELF images and EFI stub kernels together with UEFI firmware image are
+supported.
+
+For running raw ELF images with system emulation:
+
+```sh
+# In the build directory:
+./qemu-system-loongarch64 -m 4G -smp 1 \
+ -kernel build/tests/tcg/loongarch64-softmmu/hello \
+ -monitor none -display none \
+ -chardev file,path=hello.out,id=output -serial chardev:output
+```
+
+For a more complete emulation with UEFI firmware, currently there is no
+pre-compiled firmware blob yet, but in the meantime you may compile your own
+firmware image with Loongson's forked [EDK II][edk2] and
+[corresponding platform code][edk2-plat].
+
+[edk2]: https://github.com/loongson/edk2-LoongarchVirt
+[edk2-plat]: https://github.com/loongson/edk2-platforms
+
+Once you have the firmware image in place, you could boot EFI images with it.
+For example:
+
+```sh
+./qemu-system-loongarch64 -m 4G smp 4 \
+ -bios path/to/your/QEMU_EFI.fd \
+ -kernel path/to/your/vmlinux \
+ -initrd path/to/your/initramfs/if/you/have/one \
+ -append 'root=/dev/ram rdinit=/sbin/init console=ttyS0,115200'
+ -nographic
+```
+
+### Linux-user emulation
+
+Linux-user emulation is fully supported, and there are already several Linux
+distributions available with ready-to-use sysroot tarballs, for example
+[CLFS][clfs] and [Gentoo][gentoo].
+
+You may compile static qemu-user binaries then follow suitable instructions
+for your distribution (set up binfmt\_misc, etc.) to make yourself a LoongArch
+chroot for experimentation.
+
+[clfs]: https://github.com/sunhaiyong1978/CLFS-for-LoongArch
+[gentoo]: https://wiki.gentoo.org/wiki/Project:LoongArch