Design - Revision history

Mako at 19:54, 18 April 2026

2026-04-18T19:54:57Z

← Older revision		Revision as of 19:54, 18 April 2026
Line 38:		Line 38:
	The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.		The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.

	Naively, the [[wikipedia:Instruction_cycle\|instruction cycle]] may be emulated to interpret A64 code on a per-instruction basis. While providing the most accurate CPU emulation, interpretation does, however, also carry drastic overhead in its slow and repetitive nature. jabara instead emulates A64 using [[wikipedia:Binary_translation#Dynamic_binary_translation\|dynamic binary translation]] (DBT), in which [[wikipedia:Basic_block\|basic blocks]] of A64 code are collectively translated to the ISA of the emulator ("host") machine, providing performance often better than that of the NX within basic blocks. Existing NX emulators commonly accomplish this using the [https://github.com/lioncash/dynarmic dynarmic] [[wikipedia:Dynamic_recompilation\|dynamic recompiler]]. However, due to the difficulty of using [https://isocpp.org C++] libraries in Rust codebases, as well as the aforementioned issues present in the the buildsystem of yuzu that stem partially from that of dynarmic, the [http://github.com/unicorn-engine/unicorn Unicorn] CPU emulator framework, which provides [https://github.com/unicorn-engine/unicorn/tree/master/bindings/rust/unicorn-engine Rust bindings] for its underlying [https://www.c-language.org C] implementation, was chosen for jabara. Unicorn emulates various architectures, including AArch64, using [[wikipedia:Just-in-time_compilation\|just-in-time compilation]] (JIT), a DBT technique also used by dynarmic that makes Unicorn a sufficiently performant framework for Tegra X1 emulation. It is based on [https://www.qemu.org QEMU], a widely-used generic machine emulator ~~ramework~~ that achieves near-native performance in many scenarios.		Naively, the [[wikipedia:Instruction_cycle\|instruction cycle]] may be emulated to interpret A64 code on a per-instruction basis. While providing the most accurate CPU emulation, interpretation does, however, also carry drastic overhead in its slow and repetitive nature. jabara instead emulates A64 using [[wikipedia:Binary_translation#Dynamic_binary_translation\|dynamic binary translation]] (DBT), in which [[wikipedia:Basic_block\|basic blocks]] of A64 code are collectively translated to the ISA of the emulator ("host") machine, providing performance often better than that of the NX within basic blocks. Existing NX emulators commonly accomplish this using the [https://github.com/lioncash/dynarmic dynarmic] [[wikipedia:Dynamic_recompilation\|dynamic recompiler]]. However, due to the difficulty of using [https://isocpp.org C++] libraries in Rust codebases, as well as the aforementioned issues present in the the buildsystem of yuzu that stem partially from that of dynarmic, the [http://github.com/unicorn-engine/unicorn Unicorn] CPU emulator framework, which provides [https://github.com/unicorn-engine/unicorn/tree/master/bindings/rust/unicorn-engine Rust bindings] for its underlying [https://www.c-language.org C] implementation, was chosen for jabara. Unicorn emulates various architectures, including AArch64, using [[wikipedia:Just-in-time_compilation\|just-in-time compilation]] (JIT), a DBT technique also used by dynarmic that makes Unicorn a sufficiently performant framework for Tegra X1 emulation. It is based on [https://www.qemu.org QEMU], a widely-used generic machine emulator framework that achieves near-native performance in many scenarios.

	AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels Exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to that of the caller, and may only be returned from to an EL lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor, so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.		AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels Exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to that of the caller, and may only be returned from to an EL lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor, so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.

Mako at 19:46, 18 April 2026

2026-04-18T19:46:51Z

← Older revision		Revision as of 19:46, 18 April 2026
Line 18:		Line 18:

	== Foundations ==		== Foundations ==
	Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu<ref group="note">suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.		Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu<ref group="note">suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of [https://learn.microsoft.com/en-us/dotnet/csharp/ C#] and [https://dotnet.microsoft.com/en-us/ .NET] by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.

	To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.		To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.
Line 33:		Line 33:
	Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are combinations of both LLE and HLE.		Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are combinations of both LLE and HLE.

	All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In ~~official~~ NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.		All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In officially licensed NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.

	=== CPU ===		=== CPU ===
	The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.		The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.

	~~AArch64 implements privilege as~~ [~~https~~:~~//developer~~.~~arm~~.~~com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels~~] (~~ELs~~) ~~numbered <~~code~~>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised~~ to ~~an EL identical to or higher than that~~ of the ~~caller~~, ~~and may only be returned from to an EL identical to or lower~~ than that of the ~~callee~~. ~~The~~ NX ~~mostly follows~~ the ~~typical AArch64 EL software model in which userland code runs at <code>EL0<~~/~~code>~~, the ~~OS at <code>EL1<~~/~~code>~~, the ~~hypervisor at <code>EL2<~~/~~code>~~, ~~and the~~ [https://~~developer.arm~~.com/~~documentation~~/~~100935~~/~~0100~~/~~Switching~~-~~betwen~~-~~the~~-~~Normal~~-~~and~~-~~Secure~~-~~worlds- Secure Monitor~~] ~~at <code>EL3</code>~~, ~~though the NX lacks~~ a ~~hypervisor, so exceptions raised~~ by ~~<code>EL1<~~/~~code> are taken directly to <code>EL3<~~/~~code>~~. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. ~~Exceptions raised to <code>EL1</code> must hence be handled by jabara~~, ~~and higher ELs—of which only <code>EL3</code> is~~ used ~~by the NX—can be ignored~~.		Naively, the [[wikipedia:Instruction_cycle\|instruction cycle]] may be emulated to interpret A64 code on a per-instruction basis. While providing the most accurate CPU emulation, interpretation does, however, also carry drastic overhead in its slow and repetitive nature. jabara instead emulates A64 using [[wikipedia:Binary_translation#Dynamic_binary_translation\|dynamic binary translation]] (DBT), in which [[wikipedia:Basic_block\|basic blocks]] of A64 code are collectively translated to the ISA of the emulator ("host") machine, providing performance often better than that of the NX within basic blocks. Existing NX emulators commonly accomplish this using the [https://github.com/lioncash/dynarmic dynarmic] [[wikipedia:Dynamic_recompilation\|dynamic recompiler]]. However, due to the difficulty of using [https://isocpp.org C++] libraries in Rust codebases, as well as the aforementioned issues present in the the buildsystem of yuzu that stem partially from that of dynarmic, the [http://github.com/unicorn-engine/unicorn Unicorn] CPU emulator framework, which provides [https://github.com/unicorn-engine/unicorn/tree/master/bindings/rust/unicorn-engine Rust bindings] for its underlying [https://www.c-language.org C] implementation, was chosen for jabara. Unicorn emulates various architectures, including AArch64, using [[wikipedia:Just-in-time_compilation\|just-in-time compilation]] (JIT), a DBT technique also used by dynarmic that makes Unicorn a sufficiently performant framework for Tegra X1 emulation. It is based on [https://www.qemu.org QEMU], a widely-used generic machine emulator ramework that achieves near-native performance in many scenarios.

	In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.		AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels Exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to that of the caller, and may only be returned from to an EL lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor, so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.

			In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>[https://developer.arm.com/documentation/111182/2025-09_ASL1/Base-Instructions/SVC--Supervisor-call-?lang=en SVC]</code> ("supervisor call") A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications. The Rust bindings for Unicorn expose <code>[https://docs.rs/unicorn-engine/latest/unicorn_engine/struct.Unicorn.html#method.add_intr_hook Unicorn<'a, D>::add_intr_hook]</code>, which hooks guest interrupts and exceptions, passing a <code>u32</code> interrupt code to the hook function. The interrupt codes are defined in <code>[https://git.zelda.sr/jabara/unicorn/src/commit/3811fdcb861dc7686dde0ec0a7624bb92e277647/qemu/target/arm/cpu.h#L32-L52 qemu/target/arm/cpu.h]</code>, with <code>EXCP_SWI</code> ('''s'''oft'''w'''are '''i'''nterrupt) being the code used for guest exceptions. If a caught interrupt is a software interrupt, the details of the exception raised are available via the Exception Syndrome Register for the current Exception level; for <code>SVC</code> exceptions, this is <code>EL1</code>, so the <code>[https://developer.arm.com/documentation/111180/2025-09_ASL1/AArch64-Registers/ESR-EL1--Exception-Syndrome-Register--EL1-?lang=en ESR_EL1]</code> (Exception Syndrome Register (EL1)) register must be read. <code>SVC</code> exceptions can be identified by an <code>[https://developer.arm.com/documentation/111180/2025-09_ASL1/AArch64-Registers/ESR-EL1--Exception-Syndrome-Register--EL1-?lang=en#fieldset_0-31_26 EC]</code> (Exception Class) value of <code>0b010101</code> ("<code>SVC</code> instruction execution in AArch64 state"), located at bits <code>26</code> through <code>31</code>, and an <code>[https://developer.arm.com/documentation/111180/2025-09_ASL1/AArch64-Registers/ESR-EL1--Exception-Syndrome-Register--EL1-?lang=en#fieldset_0-25_25 IL]</code> (Instruction Length) value of <code>0b1</code> ("32-bit instruction trapped"), located at bit <code>25</code>. The immediate argument, <code>[https://developer.arm.com/documentation/111182/2025-09_ASL1/Base-Instructions/SVC--Supervisor-call-?lang=en#imm imm16]</code>, of a caught <code>SVC</code> exception is encoded in the <code>[https://developer.arm.com/documentation/111180/2025-09_ASL1/AArch64-Registers/ESR-EL1--Exception-Syndrome-Register--EL1-?lang=en#fieldset_0-24_0_11 ISS]</code> (Instruction Specific Syndrome) field, located at bits <code>0</code> through <code>15</code>. <code>imm16</code> is then used to uniquely identify the called SVC, allowing the correct SVC implementation in jabara to be called. Exception Syndrome Registers are not exposed by Unicorn's AArch64 API, so Unicorn was forked to [https://git.zelda.sr/jabara/unicorn jabara/unicorn] to add this functionality, exposing an <code>ESR</code> read-only pseudoregister that accesses the Exception Syndrome Register for the current Exception level, always <code>EL1</code> in jabara. This allows SVCs to be implemented per immediate (<code>imm16</code>) in native Rust code, callable by the guest machine with the <code>SVC</code> instruction.

	== Notes ==		== Notes ==

Mako at 06:03, 12 April 2026

2026-04-12T06:03:30Z

← Older revision		Revision as of 06:03, 12 April 2026
Line 38:		Line 38:
	The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.		The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.

	AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to or higher than that of the caller, and may only be returned from to an EL identical to or lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor. so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.		AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to or higher than that of the caller, and may only be returned from to an EL identical to or lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor, so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.

	In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.		In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.

Mako at 09:25, 10 April 2026

2026-04-10T09:25:49Z

← Older revision		Revision as of 09:25, 10 April 2026
Line 31:		Line 31:
	The primary goal of NX emulation is to implement enough of the NX's [[wikipedia:System_on_a_chip\|system on a chip]] (SoC), the [[wikipedia:Tegra#Tegra_X1\|Tegra X1]], and the NX operating system, Horizon OS ('''HOS'''), to allow [[wikipedia:User_space_and_kernel_space\|userland]] NX applications to run.		The primary goal of NX emulation is to implement enough of the NX's [[wikipedia:System_on_a_chip\|system on a chip]] (SoC), the [[wikipedia:Tegra#Tegra_X1\|Tegra X1]], and the NX operating system, Horizon OS ('''HOS'''), to allow [[wikipedia:User_space_and_kernel_space\|userland]] NX applications to run.

	Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are ~~a combination~~ of both LLE and HLE.		Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are combinations of both LLE and HLE.

	All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.		All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.

Mako at 09:24, 10 April 2026

2026-04-10T09:24:20Z

← Older revision		Revision as of 09:24, 10 April 2026
Line 38:		Line 38:
	The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.		The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.

	AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to or higher than that of the caller, and may only be returned from to an EL identical to or lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, a hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor. so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.		AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to or higher than that of the caller, and may only be returned from to an EL identical to or lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, the hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor. so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.

	In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.		In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.

Mako at 09:23, 10 April 2026

2026-04-10T09:23:01Z

← Older revision		Revision as of 09:23, 10 April 2026
Line 34:		Line 34:

	All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.		All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.

			=== CPU ===
			The Tegra X1 contains four [[wikipedia:ARM_Cortex-A57\|ARM Cortex-A57]] cores used by the NX, as well as four unused [[wikipedia:ARM_Cortex-A53\|ARM Cortex-A53]] cores. The Cortex-A57 implements the [[wikipedia:ARM_architecture_family#Armv8-A\|Armv8-A]] instruction set architecture (ISA). Only its 64-bit mode ('''AArch64''') is used by HOS, so the target of jabara's CPU emulation is to emulate an AArch64 core. The instruction set used by AArch64 is known as '''A64'''.

			AArch64 implements privilege as [https://developer.arm.com/documentation/102412/0103/Privilege-and-Exception-levels/Exception-levels exception levels] (ELs) numbered <code>EL0</code> through <code>EL3</code>. In this exception model, exceptions may only be raised to an EL identical to or higher than that of the caller, and may only be returned from to an EL identical to or lower than that of the callee. The NX mostly follows the typical AArch64 EL software model in which userland code runs at <code>EL0</code>, the OS at <code>EL1</code>, a hypervisor at <code>EL2</code>, and the [https://developer.arm.com/documentation/100935/0100/Switching-betwen-the-Normal-and-Secure-worlds- Secure Monitor] at <code>EL3</code>, though the NX lacks a hypervisor. so exceptions raised by <code>EL1</code> are taken directly to <code>EL3</code>. Because jabara emulates HOS itself, its implementation of HOS functionality can be thought of as <code>EL1</code> code—however, as this code is entirely invisible to the guest system, it is not actually running at any EL. Exceptions raised to <code>EL1</code> must hence be handled by jabara, and higher ELs—of which only <code>EL3</code> is used by the NX—can be ignored.

			In AArch64, SVCs are implemented as exceptions raised to <code>EL1</code> by the <code>SVC</code> A64 instruction. As raising execution to <code>EL1</code> is required for userland (<code>EL0</code>) applications to call kernel (<code>EL1</code>) functionality, SVCs are used for all userland calls to kernel code, and hence must be implemented in jabara in order to run userland NX applications.

	== Notes ==		== Notes ==

Mako at 08:39, 10 April 2026

2026-04-10T08:39:14Z

← Older revision		Revision as of 08:39, 10 April 2026
Line 33:		Line 33:
	Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are a combination of both LLE and HLE.		Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are a combination of both LLE and HLE.

	All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach allows kernel methods and SVCs to be implemented in an optimally performant matter ~~and avoids codebase clutter~~.		All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach avoids codebase clutter and allows kernel methods and SVCs to be implemented in an optimally performant matter.

	== Notes ==		== Notes ==

Mako at 08:37, 10 April 2026

2026-04-10T08:37:15Z

← Older revision		Revision as of 08:37, 10 April 2026
Line 18:		Line 18:

	== Foundations ==		== Foundations ==
	Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu<ref>suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.		Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu<ref group="note">suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.

	To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.		To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.

Mako at 08:35, 10 April 2026

2026-04-10T08:35:47Z

← Older revision		Revision as of 08:35, 10 April 2026
Line 18:		Line 18:

	== Foundations ==		== Foundations ==
	Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu ~~or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu,~~<ref ~~group="note"~~>suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.		Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu<ref>suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.

	To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.		To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.
Line 29:		Line 29:

	=== Overview ===		=== Overview ===
	Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE).		The primary goal of NX emulation is to implement enough of the NX's [[wikipedia:System_on_a_chip\|system on a chip]] (SoC), the [[wikipedia:Tegra#Tegra_X1\|Tegra X1]], and the NX operating system, Horizon OS ('''HOS'''), to allow [[wikipedia:User_space_and_kernel_space\|userland]] NX applications to run.

			Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE). In the simplest sense, the emulated ("guest") machine transforms input data into output data. LLE and HLE differ in that LLE emulators emulate the processes by which input data are transformed, while HLE emulators only emulate the visible results (i.e. corresponding output to given input). Many modern emulators are a combination of both LLE and HLE.

			All existing NX emulators are at least in part HLE. However, unlike existing NX emulators, which contain aspects of LLE in that they generally attempt to recreate kernel classes and their functionality with relative accuracy, jabara takes an approach much closer to pure HLE, implementing kernel functionality only accurately enough such that its behavior as exposed by the HOS [https://switchbrew.org/wiki/SVC supervisor calls] ('''SVCs''') is accurate to what is expected by their userland callers.<ref group="note">In official NX applications, the only direct caller of HOS SVCs is the Nintendo SDK (<code>nnsdk</code>).</ref> This approach allows kernel methods and SVCs to be implemented in an optimally performant matter and avoids codebase clutter.

	== Notes ==		== Notes ==

Mako at 07:14, 10 April 2026

2026-04-10T07:14:01Z

← Older revision		Revision as of 07:14, 10 April 2026
Line 18:		Line 18:

	== Foundations ==		== Foundations ==
	Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu, made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.		Implementing TAS functionality in a fork of an existing NX emulator, such as, at the time, suyu or Ryujinx, was considered. However, the complex and outdated buildsystem of yuzu, and, by extension, that of forks such as suyu,<ref group="note">suyu is currently unmaintained and [https://eden-emu.dev Eden] is its most current active fork. However, suyu was current at the time this development decision was made.</ref> made forking suyu unviable, and the use of C# and .NET by Ryujinx made forking Ryujinx undesirable. To avoid having to work with such codebases, jabara became an entirely separate emulation project.

	To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.		To best benefit users and developers, jabara was chosen to be a [[wikipedia:Free_and_open-source_software\|free and open source]] software project in order to allow free modification and redistribution and encourage community contribution. jabara is licensed under the [https://www.gnu.org/licenses/gpl-3.0.en.html GNU GPLv3] and can be used under the terms of any later version of the GPL. Nintendo has a history of issuing DMCA takedown requests to emulation projects,<ref>https://consumerrights.wiki/w/Nintendo#History_against_console_emulation</ref> especially to public GitHub repositories, so the decision was made to selfhost the relevant Git repositories on an instance of [https://forgejo.org Forgejo]. The public Git forge can be accessed at https://git.zelda.sr.
Line 25:		Line 25:

	[[JabaraWiki:About\|This wiki]], an instance of [https://www.mediawiki.org MediaWiki], was created during development to organize project design on this article. By release, this wiki will also document emulator features and provide various emulator setup and TASing guides.		[[JabaraWiki:About\|This wiki]], an instance of [https://www.mediawiki.org MediaWiki], was created during development to organize project design on this article. By release, this wiki will also document emulator features and provide various emulator setup and TASing guides.

			== Emulation ==

			=== Overview ===
			Two general approaches exist to system emulation: low-level emulation (LLE) and high-level emulation (HLE).

			== Notes ==
			<references group="note" />

	== References ==		== References ==