From 2131faf66e268d465d3f6fde156409efb6e765fd Mon Sep 17 00:00:00 2001 From: arcane-quill Date: Mon, 11 May 2026 14:55:06 +0200 Subject: [PATCH 1/6] ume: Add user mode emulation section to documentation #764 Added section on User Mode Emulation to the tutorial. --- docs/refman/tutorial.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index 40168f53e..8ba9bf444 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2002,3 +2002,9 @@ In addition, several behavioral aspects of the cache can be specified, such as w ## Processor Definition \lbl{tut_prc_definition} + +## User Mode Emulation + +\lbl{tut_ume_definition} + +The \ac{UserModeEmulation} definition determines how a VADL specification maps to QEMU's Linux user-mode emulation (UME). From 121c854f39493bed95f33a98116f84ddb0d5fa37 Mon Sep 17 00:00:00 2001 From: arcane-quill Date: Sun, 17 May 2026 11:12:20 +0200 Subject: [PATCH 2/6] ume: Add some vadl and general info to ume section #764 --- docs/refman/tutorial.md | 49 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index 8ba9bf444..91b6b11f7 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2007,4 +2007,51 @@ In addition, several behavioral aspects of the cache can be specified, such as w \lbl{tut_ume_definition} -The \ac{UserModeEmulation} definition determines how a VADL specification maps to QEMU's Linux user-mode emulation (UME). +The \ac{UserModeEmulation} definition determines how a specification from a VADL file maps to QEMU's Linux user mode emulation (UME). +The UME is used to run Linux ELF binaries without having to emulate the full machine. +To achieve this it needs to intercept system calls (syscalls) based on the syscall instruction of the architecture given by the VADL file. +The associated register conventions (the \ac{ABI}) need to be mapped to determine the system call number, its arguments, and where to +place the return value. + +\listing{user_mode_emulation, User Mode Emulation Definition} +~~~{.vadl} +user mode emulation UME for RV64 with ABI = { +  +} +~~~ +\endlisting + +A \ac{UME} section starts with the keyword `user mode emulation` followed by a unique identifier. +Some elements inside of the \ac{UME} section rely on previously defined \ac{ISA} elements, so it needs to be referenced +using the `for` keyword after the identifier. +Definitions from the referenced \ac{RV64} are now available for use inside the \ac{UME} section. +The `with` keyword binds the \ac{ABI} to the section. + +### Exception Definition + +Varying exceptions are defined in the VADL like: + +\listing{user_mode_emulation_exc, User Mode Emulation Definition Exceptions} +~~~{.vadl} +user mode emulation UME for RV64 with ABI = { +  +} +~~~ +\endlisting + +It is also possible to select the desired OS in the .vadl file (e.g. Linux or BSD). In order for this to work, custom VADL annotations +and tokens are added to the .ATG file. + +Templates are generated based on a RISCV implementation from QEMU's linux-user section, that has been interpolated using Thymeleaf to be viable for +any architecture specified in the VADL. + +The cpu_loop intercepts the specific syscall instruction and dispatches to the syscall translator. + +Syscalls are translated by utilizing QEMU's integrated do_syscall() function that maps guest syscall numbers to host syscall numbers and +writes the return value back into the guest's return register. + +The mechanics of how unix signals are handed to a guest process are handled in signal.c, which makes sure that the host signal gets intercepted, a signal frame +gets set up on the guest stack and the guest PC gets returned to the registered signal handler of the guest whenever a guest program triggers a signal - for example +by accessing an invalid address (SIGSEV). + +Additional testing infrastructure ensures that the UME works as intended. From 669dc51af3e7eda0af06b32562f4f49c33554d71 Mon Sep 17 00:00:00 2001 From: arcane-quill Date: Mon, 18 May 2026 09:09:19 +0200 Subject: [PATCH 3/6] ume: Add UME section example #764 --- docs/refman/tutorial.md | 47 +++++++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index 91b6b11f7..32c14c7fa 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2015,8 +2015,14 @@ place the return value. \listing{user_mode_emulation, User Mode Emulation Definition} ~~~{.vadl} -user mode emulation UME for RV64 with ABI = { -  +[os : linux] +user mode emulation UME from RV64IM with ABI = { +syscall instruction = ECALL + +syscall number = a7 +syscall argument = a{0..5} +syscall return = a0 + } ~~~ \endlisting @@ -2027,6 +2033,26 @@ using the `for` keyword after the identifier. Definitions from the referenced \ac{RV64} are now available for use inside the \ac{UME} section. The `with` keyword binds the \ac{ABI} to the section. + +In the example in listing \r{user_mode_emulation}, the \ac{UME} section uses `ECALL` from the \ac{RV64IM} and the register aliases `a7`, `a0` +from the \ac{ABI} `ABI`. These aliases represent X(17) and X(10), respectively. +The annotation `[os : linux]` selects for which target operating system system +calls are forwarded and which syscall number table should be used. + +The `syscall instruction` declaration determines the \ac{ISA} instruction that triggers a +syscall. The syscall keyword is currently specific to the \ac{UME} section. + +The `syscall number` declaration names the register that holds the syscall number +when the syscall instruction is executed. + +The `syscall argument` declaration names the registers that hold the syscall +arguments. +The syscall argument convention utilizes six registers, instead of eight, compared to the function +argument convention in the \ac{ABI} (`function argument = a{0..7}`). + +The `syscall return` declaration determines into which register the host operating system will write the return value of the forwarded syscall. This differs with the function return convention in the \ac{ABI} because it is a single register instead of spanning across two (`return value = a{0..1}`). + + ### Exception Definition Varying exceptions are defined in the VADL like: @@ -2039,19 +2065,4 @@ user mode emulation UME for RV64 with ABI = { ~~~ \endlisting -It is also possible to select the desired OS in the .vadl file (e.g. Linux or BSD). In order for this to work, custom VADL annotations -and tokens are added to the .ATG file. - -Templates are generated based on a RISCV implementation from QEMU's linux-user section, that has been interpolated using Thymeleaf to be viable for -any architecture specified in the VADL. - -The cpu_loop intercepts the specific syscall instruction and dispatches to the syscall translator. - -Syscalls are translated by utilizing QEMU's integrated do_syscall() function that maps guest syscall numbers to host syscall numbers and -writes the return value back into the guest's return register. - -The mechanics of how unix signals are handed to a guest process are handled in signal.c, which makes sure that the host signal gets intercepted, a signal frame -gets set up on the guest stack and the guest PC gets returned to the registered signal handler of the guest whenever a guest program triggers a signal - for example -by accessing an invalid address (SIGSEV). - -Additional testing infrastructure ensures that the UME works as intended. +It is also possible to select the desired OS in the .vadl file (e.g. Linux or BSD). From 5d25435d18b08d6e9f977e8cc3ec89ce7a897c8e Mon Sep 17 00:00:00 2001 From: Andreas Krall <145031929+AndreasKrall@users.noreply.github.com> Date: Mon, 18 May 2026 13:52:26 +0200 Subject: [PATCH 4/6] Apply suggestion from @AndreasKrall fixed typo --- docs/refman/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index 32c14c7fa..e7f576960 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2016,7 +2016,7 @@ place the return value. \listing{user_mode_emulation, User Mode Emulation Definition} ~~~{.vadl} [os : linux] -user mode emulation UME from RV64IM with ABI = { +user mode emulation UME for RV64IM with ABI = { syscall instruction = ECALL syscall number = a7 From 25e47ec1c775435109e357fa55900c2ee2e22203 Mon Sep 17 00:00:00 2001 From: arcane-quill Date: Sun, 31 May 2026 14:55:38 +0200 Subject: [PATCH 5/6] ume: Add provisional syscall handling strategy #764 --- docs/refman/tutorial.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index e7f576960..31b1d2f0d 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2016,12 +2016,12 @@ place the return value. \listing{user_mode_emulation, User Mode Emulation Definition} ~~~{.vadl} [os : linux] -user mode emulation UME for RV64IM with ABI = { +user mode emulation UME for RV64UME with ABI = { syscall instruction = ECALL -syscall number = a7 +syscall register = a7 syscall argument = a{0..5} -syscall return = a0 +return register = a0 } ~~~ @@ -2033,9 +2033,10 @@ using the `for` keyword after the identifier. Definitions from the referenced \ac{RV64} are now available for use inside the \ac{UME} section. The `with` keyword binds the \ac{ABI} to the section. - In the example in listing \r{user_mode_emulation}, the \ac{UME} section uses `ECALL` from the \ac{RV64IM} and the register aliases `a7`, `a0` -from the \ac{ABI} `ABI`. These aliases represent X(17) and X(10), respectively. +from the \ac{ABI}. These aliases represent X(17) and X(10), respectively, but they can be defined interchangeably (either \ac{ABI} alias registers or +actual registers from the \ac{ISA} definition). + The annotation `[os : linux]` selects for which target operating system system calls are forwarded and which syscall number table should be used. @@ -2052,8 +2053,26 @@ argument convention in the \ac{ABI} (`function argument = a{0..7}`). The `syscall return` declaration determines into which register the host operating system will write the return value of the forwarded syscall. This differs with the function return convention in the \ac{ABI} because it is a single register instead of spanning across two (`return value = a{0..1}`). +### Syscall Definition + +The Linux syscall numbers differ between architectures, so each VADL file needs to contain a table +that defines the specific syscalls. + +\listing{user_mode_emulation_syscalls, User Mode Emulation Syscalls} +~~~{.vadl} +enumeration LinuxSyscall : Bits<64> = { + sys_riscv_hwprobe = 258 + , sys_riscv_flush_icache = 259 +} +~~~ +\endlisting + +The `enumeration` keyword is used to define a set of named constants, in this case the +key-value pairs are the name of the syscall and its respective number. A generic syscall +table already exists, so the table defined in the VADL file provides the architecture-specific syscalls +that should either be added to or overwrite the generic ones. -### Exception Definition +### Exception Definition (work in progress) Varying exceptions are defined in the VADL like: @@ -2064,5 +2083,3 @@ user mode emulation UME for RV64 with ABI = { } ~~~ \endlisting - -It is also possible to select the desired OS in the .vadl file (e.g. Linux or BSD). From de77275de79502aec4d4e9c81481e92ff93b6a4a Mon Sep 17 00:00:00 2001 From: arcane-quill Date: Wed, 3 Jun 2026 14:45:06 +0200 Subject: [PATCH 6/6] ume: Add syscall table definition #764 --- docs/refman/tutorial.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/refman/tutorial.md b/docs/refman/tutorial.md index 31b1d2f0d..4262c785b 100644 --- a/docs/refman/tutorial.md +++ b/docs/refman/tutorial.md @@ -2072,6 +2072,21 @@ key-value pairs are the name of the syscall and its respective number. A generic table already exists, so the table defined in the VADL file provides the architecture-specific syscalls that should either be added to or overwrite the generic ones. +\listing{user_mode_emulation, User Mode Emulation Definition} +~~~{.vadl} +[os : linux] +user mode emulation UME for RV64UME with ABI = { +... + +syscall table = LinuxSyscall + +} +~~~ +\endlisting + +The `syscall table` declaration defines the previously mentioned enumeration `LinuxSyscall` as the syscall table that is +being used for the \ac{UME}. + ### Exception Definition (work in progress) Varying exceptions are defined in the VADL like: