DOCSEARCHbyAlgolia
Submit Docs

jor1k Documentation

repository·master·Indexed 23 days ago

https://github.com/s-macke/jor1k

jor1k is a JavaScript-based OpenRISC 1000 emulator capable of running Linux and other operating systems like RTEMS directly in a web browser. It provides a CPU facade supporting multiple implementations including safe, dynamic, asm.js, WebAssembly, and multi-core SMP. The library also includes a RISC-V CPU implementation and tools for hardware emulation, state inspection, and instruction execution within a browser environment.

Tokens
1.4K
Snippets
0
Records
9
Agent score
83%

What's inside jor1k

  1. Overview of jor1k

    master
    jor1k is an OpenRISC 1000 emulator written in JavaScript that runs Linux. It is designed to run in almost any modern web browser, allowing for hardware emulation and OS execution directly in a web environment.

  2. Explore jor1k demos

    master

    You can interact with the emulator through various pre-configured demos:

    • Main Demo: The primary entry point for the emulator.
    • C Code Execution: Specialized demos that allow you to edit, compile, and run C code directly in your browser.
    • Symmetric Multiprocessing (SMP): Demonstrations of multi-core support with 2, 4, 8, or 16 cores (note that stability may decrease as core count increases).
    • RTEMS: A demo running the Real Time Operating System (RTEMS).
    • RISC-V Implementation: A demo of the RISC-V CPU implementation. To use it, wait for the first message to appear in the terminal, then select bbl from the dropdown menu.

  3. Download files or blobs using download()

    master

    The download function allows you to trigger a browser download for various data types, including strings, Blobs, Files, or dataURLs. It handles cross-browser compatibility, including legacy support for IE10+ and Safari.

    Arguments

    • data: The content to download. Can be a string, Blob, File, or a dataURL string.
    • strFileName (optional): The name to be assigned to the downloaded file. Defaults to `

  4. Inspect CPU state with toString()

    master
    The CPU class provides a toString() method that returns a formatted string representing the current state of the machine. This includes the Program Counter (PC), the contents of the general-purpose registers (r0-r31), and specific Control and Status Register (CSR) values like mstatus, mcause, mbadaddress, and mepc.

  5. Initialize the RISC-V CPU with the CPU class

    master

    The CPU class acts as a facade for different RISC-V CPU implementations. To use it, instantiate the CPU class with the required hardware abstractions (ram, htif, heap) and then call the asynchronous .Init() method to load the specific implementation.

    Supported cpuname values:

    • "safe": Uses SafeCPU implementation.
    • "asm": Uses FastCPU implementation.
    • "wasm": Uses a WebAssembly-based implementation (requires riscv.wasm to be fetchable).

    Note: The CPU class forwards several methods to the underlying implementation, including Reset, Step, RaiseInterrupt, AnalyzeImage, GetTicks, GetTimeToNextInterrupt, ProgressTime, and ClearInterrupt.

  6. Initialize the OpenRISC 1000 CPU emulator

    master

    To use the OpenRISC 1000 emulator, instantiate the CPU class and call its Init() method. The CPU class acts as a facade that abstracts over different underlying CPU implementations.

    Available CPU types (cpuname):

    • safe: A safe implementation.
    • dynamic: A dynamic implementation.
    • asm: A high-performance asm.js implementation (singleton).
    • smp: A multi-core SMP implementation (singleton).
    • wasm: A WebAssembly implementation.

    Required parameters for the constructor:

    • cpuname: The name of the CPU implementation to use.
    • ram: A RAM object providing memory access methods (e.g., Read32Big, Write32Big, Read16Big, Write16Big, Read8Big, Write8Big, and a memory property for WASM).
    • heap: A typed array representing the heap.
    • ncores: The number of cores (required for smp).

  7. Control the CPU execution and state

    master

    Once initialized, the CPU instance provides several methods to control the emulator and inspect its state. These methods are forwarded to the underlying implementation:

    • Step(): Executes a single instruction.
    • Reset(): Resets the CPU state.
    • RaiseInterrupt(): Triggers an interrupt.
    • ClearInterrupt(): Clears an interrupt.
    • ProgressTime(ticks): Advances the simulated time.
    • GetTicks(): Returns the current simulated clock ticks.
    • GetTimeToNextInterrupt(): Returns the time remaining until the next interrupt.
    • AnalyzeImage(): Analyzes the current instruction image.
    • GetFlags(): Retrieves CPU flags.
    • SetFlags(flags): Sets CPU flags.
    • GetStat(): Retrieves CPU status.
    • InvalidateTLB(): Invalidates the Translation Lookaside Buffer.

    Additionally, calling .toString() on the CPU instance returns a human-readable string representing the current machine state, including the Program Counter (PC), register values (r0-r31), and various status register (SR) flags (e.g., Supervisor mode, Interrupt enabled, etc.).

  8. Available CPU implementation methods

    master

    The CPU facade forwards the following methods to the underlying implementation (Safe, Fast, or WASM). These methods allow you to control the emulation lifecycle and inspect the state:

    • Reset(): Resets the CPU state.
    • Step(): Executes a single instruction or step.
    • RaiseInterrupt(): Triggers an interrupt.
    • ClearInterrupt(): Clears pending interrupts.
    • AnalyzeImage(): Analyzes the current execution image.
    • GetTicks(): Returns the current execution ticks.
    • GetTimeToNextInterrupt(): Returns the estimated time until the next interrupt.
    • ProgressTime(ticks): Advances the emulation time by a specific number of ticks.

    If using the wasm implementation, the following additional methods are available via the WASM exports:

    • GetFlags()
    • GetStat()
    • GetPC()
    • InvalidateTLB()
    • SetFlags()

  9. Available CPU implementation types

    master

    The CPU facade supports several underlying implementations, each suited for different performance or feature requirements:

    TypeDescription
    safeA safe CPU implementation.
    dynamicA dynamic CPU implementation.
    asmA high-performance asm.js implementation. Note: This is a singleton.
    smpA multi-core Symmetric Multi-Processing implementation. Note: This is a singleton.
    wasmA WebAssembly-based implementation.