diff --git a/docs/system/loongarch/loongson3.rst b/docs/system/loongarch/loongson3.rst
deleted file mode 100644
index fa3acd01c0..0000000000
--- a/docs/system/loongarch/loongson3.rst
+++ /dev/null
@@ -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
diff --git a/docs/system/loongarch/virt.rst b/docs/system/loongarch/virt.rst
new file mode 100644
index 0000000000..2d8f7e1db5
--- /dev/null
+++ b/docs/system/loongarch/virt.rst
@@ -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
diff --git a/target/loongarch/README b/target/loongarch/README
deleted file mode 100644
index 1823375d04..0000000000
--- a/target/loongarch/README
+++ /dev/null
@@ -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/
diff --git a/target/loongarch/README.md b/target/loongarch/README.md
new file mode 100644
index 0000000000..6a5ff8acd5
--- /dev/null
+++ b/target/loongarch/README.md
@@ -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
