Signed-off-by: Karthika B <[email protected]> --- docs/system/riscv/vega.rst | 219 +++++++++++++++++++++++++++++++++++ docs/system/target-riscv.rst | 1 + 2 files changed, 220 insertions(+) create mode 100644 docs/system/riscv/vega.rst
diff --git a/docs/system/riscv/vega.rst b/docs/system/riscv/vega.rst new file mode 100644 index 0000000000..78656682d0 --- /dev/null +++ b/docs/system/riscv/vega.rst @@ -0,0 +1,219 @@ +CDAC VEGA series RISC-V SoC (``vega``) +======================================= + +VEGA is a series of 32-bit and 64-bit processors based on the RISC-V ISA, developed by C-DAC (Centre for Development of Advanced Computing, India) under the DIR-V program. The vega QEMU machine model supports both the 32-bit and 64-bit VEGA variants. + +As with other QEMU RISC-V machine models, vega provides functional emulation of the VEGA SoC’s memory map, interrupt controllers, and peripherals. + +For more details on the VEGA processor series, please see: +https://vegaprocessors.in/ + +For VEGA documentation, please see: +https://cdac-vega.gitlab.io/ + +Supported devices +------------------ + +The ``vega`` machine supports the following devices: + + * Up to 4 RISC-V cores, RV32 or RV64 + * Platform-Level Interrupt Controller (PLIC) + * Core Level Interruptor (CLINT) + * 1 UART + * 4 virtio-mmio transports + +Boot options +------------ + +The ``vega`` machine supports two boot modes. + +Bare-metal +~~~~~~~~~~ + +Bare-metal payloads are loaded via ``-bios`` (not ``-kernel``). No +device tree is generated or loaded in this mode; the UART is always +accessed with a fixed 4-byte register stride (shift=2, io-width=4). + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega,dram-base=0x80000000 \ + -smp 1 -m 2G \ + -display none -serial stdio \ + -bios path/to/baremetal.elf + +VEGA SDK +^^^^^^^^ + +VEGA SDK can be used to build baremetal example applications, such as +a "hello world" UART program, for both the Thejas32 (``vega32``, RV32) +and Thejas64 (``vega64``, RV64) SoCs. + +Install VEGA tools +'''''''''''''''''' + +For Thejas32 SoC (Aries boards): + +.. code-block:: bash + + $ git clone https://gitlab.com/cdac-vega/vega-tools-rv32.git + $ cd vega-tools-rv32 + $ ./setup-env.sh + $ cd .. + +For Thejas64 SoC: + +.. code-block:: bash + + $ git clone https://gitlab.com/cdac-vega/vega-tools-rv64.git + $ cd vega-tools-rv64 + $ ./setup-env.sh + $ cd .. + +Install VEGA SDK +'''''''''''''''' + +For Thejas32 SoC (Aries boards): + +.. code-block:: bash + + $ git clone https://gitlab.com/cdac-vega/vega-sdk.git + $ cd vega-sdk + $ git checkout aries + $ ./setup.sh + +For Thejas64 SoC: + +.. code-block:: bash + + $ git clone https://gitlab.com/cdac-vega/vega-sdk.git + $ cd vega-sdk + $ ./setup-thejas64.sh + +Build and run the hello world example +'''''''''''''''''''''''''''''''''''''' +.. code-block:: bash + + $ cd vega-sdk + $ cd examples/uart/hello_world + $ make + + +.. note:: + + The ``dram-base`` value must match the address the payload was + actually linked for; it is not a fixed VEGA default. The examples + below use ``dram-base=0x20000``, matching this SDK's hello-world + build for both Thejas32 and Thejas64 -- other payloads (e.g. a + Linux boot via BBL) are linked for a different address and need + their own matching ``dram-base`` value. + +.. code-block:: bash + + $ qemu-system-riscv32 -M vega,dram-base=0x20000 \ + -smp 1 -m 2G \ + -display none -serial stdio \ + -bios hello.elf + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega,dram-base=0x20000 \ + -smp 1 -m 2G \ + -display none -serial stdio \ + -bios hello.elf + +Both should print:: + + Hello World + + +Linux / BBL +~~~~~~~~~~~ + +Linux boot requires a user-supplied device tree via ``-dtb``. The +``vega`` machine does not generate a device tree internally; passing +``-kernel`` without ``-dtb`` (and without ``-bios``) is a +configuration error and QEMU will refuse to start. + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega,dram-base=0x400000000 \ + -smp 4 -m 2G \ + -display none -serial stdio -bios none \ + -kernel bbl -dtb vega.dtb -initrd rootfs.cpio + +Networking (virtio-net) can be attached the same way as on other +virtio-mmio boards: + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega,dram-base=0x400000000 \ + -smp 4 -m 2G \ + -display none -serial stdio -bios none \ + -kernel bbl -dtb vega.dtb -initrd rootfs.cpio \ + -netdev tap,id=net0,ifname=tap0,script=no,downscript=no \ + -device virtio-net-device,netdev=net0 + +.. note:: + + VEGA's PLIC uses the ``cdac,plic-1.0.0`` compatible string, + recognized by CDAC's own PLIC driver bundled in CDAC's + Buildroot-based BBL/Linux builds. The CLINT is addressed as a + standard ``riscv,clint0``, which CDAC's firmware uses directly + without a vendor-specific driver; all CDAC-produced VEGA firmware + variants use this generic CLINT compatible string. + +CPU defaults +------------ + +The ``vega`` machine supports both RV32 and RV64 harts, matching the +VEGA processor series. The CPU type defaults automatically to the +correct width for the binary in use (``qemu-system-riscv32`` selects +``vega32``, ``qemu-system-riscv64`` selects ``vega64``) and bakes in +VEGA's fixed baseline: I, M, A, S and U, Zicsr, and Zifencei, with the +current RISC-V privileged architecture specification and SV32/SV39 +paging respectively. No ``-cpu`` argument is required to boot. +Additional extensions (e.g. F/D/C) can still be enabled explicitly if +needed: + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega -cpu vega64,f=true,d=true,c=true ... + $ qemu-system-riscv32 -M vega -cpu vega32,f=true,d=true,c=true ... + +.. note:: + + ``TYPE_RISCV_CPU_VEGA32``/``TYPE_RISCV_CPU_VEGA64`` are parented on + ``TYPE_RISCV_CPU_SIFIVE_U`` rather than the generic base CPU type, + since the generic type's default ISA extensions cannot be fully + narrowed for VEGA's actual silicon (QEMU's CPU-class extension + merge is additive only). One consequence worth documenting: SiFive + U's default privileged specification version (1.10.0) is explicitly + overridden back to the current version in both VEGA CPU types, + since firmware built against the modern privileged spec can hang + early in boot (in CLINT/timer setup) against the older version. If + you build a custom CPU subtype from a similar parent, do not assume + privileged spec version propagates the way ISA extension bits + might. + +dram-base option +----------------- + +VEGA silicon can be configured with DRAM at different base addresses. +This is exposed as a machine property: + +.. code-block:: bash + + $ qemu-system-riscv64 -M vega,dram-base=0x400000000 ... + +If ``dram-base`` is not specified, QEMU falls back to a default +address and prints a warning. + +PLIC and CLINT address overlap +------------------------------- + +On real VEGA silicon, the PLIC and CLINT are mapped at the same base +address but are distinguished by non-overlapping register offset +ranges, decoded internally by the SoC's interconnect. This is a +genuine hardware characteristic, not a QEMU modelling error; compiling +a VEGA device tree will produce a ``dtc`` ``unique_unit_address`` +warning for this reason, which is expected and can be ignored. diff --git a/docs/system/target-riscv.rst b/docs/system/target-riscv.rst index 3ad5d1ddaf..cf056011d5 100644 --- a/docs/system/target-riscv.rst +++ b/docs/system/target-riscv.rst @@ -71,6 +71,7 @@ undocumented; you can get a complete list by running riscv/mips riscv/shakti-c riscv/sifive_u + riscv/vega riscv/virt riscv/xiangshan-kunminghu -- 2.43.0 ------------------------------------------------------------------------------------------------------------ [ C-DAC is on Social-Media too. Kindly follow us at: Facebook: https://www.facebook.com/CDACINDIA & Twitter: @cdacindia ] This e-mail is for the sole use of the intended recipient(s) and may contain confidential and privileged information. If you are not the intended recipient, please contact the sender by reply e-mail and destroy all copies and the original message. Any unauthorized review, use, disclosure, dissemination, forwarding, printing or copying of this email is strictly prohibited and appropriate legal action will be taken. ------------------------------------------------------------------------------------------------------------
