Project 3 — OpenSBI + S-mode Payload

# Place this section in .text.entry so the linker script can
# put it at the very start of the binary (0x80200000).
.section .text.entry
.global _start

_start:
    # la = Load Address.  Expands to: auipc t0, %pcrel_hi(sym)
    #                                  addi  t0, t0, %pcrel_lo(sym)
    # Both instructions are PC-relative — safe under mcmodel=medany
    # for targets within ±2 GB of the current PC.
    la      sp, _sstack_top     # sp ← top of our 8 KB S-mode stack

    # Install the S-mode trap vector BEFORE calling any C code.
    # If anything faults before stvec is set the CPU will vector
    # to OpenSBI's internal handler which knows nothing about our
    # stack and will hang silently.
    la      t0, _strap_vector
    csrw    stvec, t0          # MODE = Direct (bits[1:0]=0b00)

    # Jump to C.  a0 (hartid) and a1 (DTB) set by OpenSBI.
    # We have not touched a0/a1 so they reach payload_main intact.
    call    payload_main

    # payload_main never returns but spin safely if it somehow does.
1:  wfi
    j       1b

# .align 2 = align to 4 bytes.  RISC-V spec requires stvec[1:0]=0b00
# for Direct mode, so the vector address must be 4-byte aligned.
.align 2
.global _strap_vector
_strap_vector:
    # Make room on the stack: 256 bytes (32 slots × 8 bytes each).
    # sp must already be valid — which it is because we set it in _start.
    addi    sp, sp, -256

    # Save all caller-saved registers.  The trap can fire in the middle
    # of any code path, so these registers may contain live values.
    # Callee-saved registers (s0-s11) are preserved by C functions.
    sd      ra,   0(sp)  # return address — must preserve, call clobbers ra
    sd      t0,   8(sp)  # temporaries
    sd      t1,  16(sp)
    sd      t2,  24(sp)
    sd      a0,  32(sp)  # a0-a7: argument / return-value registers
    sd      a1,  40(sp)  # a0 and a1 also hold sbiret results
    sd      a2,  48(sp)
    sd      a3,  56(sp)
    sd      a4,  64(sp)
    sd      a5,  72(sp)
    sd      a6,  80(sp)
    sd      a7,  88(sp)
    sd      t3,  96(sp)  # more temporaries
    sd      t4, 104(sp)
    sd      t5, 112(sp)
    sd      t6, 120(sp)

    # Call the C handler.  It reads scause and sepc itself via inline asm.
    call    payload_trap_handler

    # Restore all 16 registers in reverse order.
    ld      ra,   0(sp)
    ld      t0,   8(sp)
    ld      t1,  16(sp)
    ld      t2,  24(sp)
    ld      a0,  32(sp)
    ld      a1,  40(sp)
    ld      a2,  48(sp)
    ld      a3,  56(sp)
    ld      a4,  64(sp)
    ld      a5,  72(sp)
    ld      a6,  80(sp)
    ld      a7,  88(sp)
    ld      t3,  96(sp)
    ld      t4, 104(sp)
    ld      t5, 112(sp)
    ld      t6, 120(sp)
    addi    sp, sp, 256       # release the stack frame

    # sret: restores sepc → PC, restores SPP → privilege level
    # The interrupted code continues exactly where it was.
    sret

# ── S-mode stack: 8 KB, page-aligned ──────────────────────────
.section .sstack
.align 12                   # 2^12 = 4096-byte page alignment
_sstack_bottom:
    .space  8192             # reserve 8 KB of zeros
_sstack_top:                # sp starts here; stack grows downward

/* Every SBI ecall returns two values in a0 and a1.
 * We wrap them in a struct so callers get both atomically.        */
struct sbiret {
    long error;   /* 0 = SBI_SUCCESS; negative = error code */
    long value;   /* result — e.g. spec version, impl ID, probe answer */
};

/* ── Extension IDs (EID) ──────────────────────────────────────
 * EIDs 0x00–0x0F are "legacy" (SBI v0.1, deprecated).
 * EIDs 0x10+ are the SBI v1.0 standard extensions.
 * The string EIDs (e.g. 0x54494D45 = "TIME") are defined so
 * that you can read the ID as ASCII.                             */
#define SBI_EXT_BASE    0x10        /* mandatory on all v1.0 implementations */
#define SBI_EXT_TIME    0x54494D45  /* 'T','I','M','E' — set timer */
#define SBI_EXT_IPI     0x735049    /* 's','P','I'  — send IPI */
#define SBI_EXT_RFENCE  0x52464E43  /* 'R','F','N','C' — remote fence */
#define SBI_EXT_HSM     0x48534D    /* 'H','S','M' — hart state management */
#define SBI_EXT_SRST    0x53525354  /* 'S','R','S','T' — system reset */

/* ── BASE function IDs (used with SBI_EXT_BASE) ──────────────── */
#define SBI_BASE_GET_SPEC_VERSION   0
#define SBI_BASE_GET_IMPL_ID        1
#define SBI_BASE_GET_IMPL_VERSION   2
#define SBI_BASE_PROBE_EXTENSION    3  /* a0=eid → returns 0=absent, >0=present */
#define SBI_BASE_GET_MVENDORID      4
#define SBI_BASE_GET_MARCHID        5

/* ── TIME function ID ─────────────────────────────────────────── */
#define SBI_TIME_SET_TIMER          0  /* a0=absolute stime value */

/* ── Implementation IDs ──────────────────────────────────────── */
#define SBI_IMPL_OPENSBI            1

/* QEMU virt places an NS16550A UART at 0x10000000.
 * OpenSBI already initialised it — we can write directly.       */
#define UART0     0x10000000UL

/* volatile: the compiler must not cache these — they are hardware regs.
 * UART_TX  (offset 0x00) = Transmit Holding Register — write a byte here.
 * UART_LSR (offset 0x05) = Line Status Register — bit 5 = THRE.          */
#define UART_TX   (*(volatile unsigned char*)(UART0 + 0x00))
#define UART_LSR  (*(volatile unsigned char*)(UART0 + 0x05))
#define UART_THRE (1 << 5)  /* Transmit Holding Register Empty — safe to send */

static void uart_putc(char c) {
    /* Spin until UART is ready, then write the character. */
    while (!(UART_LSR & UART_THRE));
    UART_TX = c;
}

static void puts(const char *s) { while (*s) uart_putc(*s++); }

/* Print 64-bit value as 0xHHHHHHHHHHHHHHHH (always 16 nibbles). */
static void put_hex(unsigned long v) {
    const char *h = "0123456789ABCDEF";
    puts("0x");
    /* Shift 60 bits right to get the most-significant nibble first,
     * then step down 4 bits at a time to the least-significant nibble. */
    for (int i = 60; i >= 0; i -= 4)
        uart_putc(h[(v >> i) & 0xF]);
}

/* The 'time' CSR (0xC01) is a read-only alias for mtime.
 * It is always readable from S-mode — OpenSBI does not block it.
 *
 * DO NOT try to read CLINT mtime directly via MMIO (0x200BFF8).
 * OpenSBI's PMP configuration marks the entire CLINT region
 * (0x2000000–0x200FFFF) as M-mode only.  An S-mode MMIO load
 * to that address will take a load access fault (mcause=5).       */
static inline unsigned long long get_time(void) {
    unsigned long t;
    __asm__ volatile("csrr %0, time" : "=r"(t));
    return t;
}

/* stimecmp is the S-mode timer compare register added by the sstc extension.
 *
 * When stimecmp is present and MENVCFG.STCE=1 (set by OpenSBI):
 *   - S-mode can write stimecmp directly to schedule a timer interrupt.
 *   - When time >= stimecmp, the STI bit (bit 5) of sip fires.
 *   - The interrupt arrives as an STI: scause = 0x8000000000000005.
 *   - No SBI ecall is needed — zero M-mode involvement.
 *
 * stimecmp CSR number = 0x14D.
 * riscv64-unknown-elf-gcc 10.2 does not recognise the mnemonic 'stimecmp'
 * because it predates the _sstc ISA extension string in that toolchain.
 * Using the raw CSR number (0x14D) bypasses this — the assembler accepts
 * any valid 12-bit CSR number regardless of ISA extensions.            */
static inline void set_stimecmp(unsigned long long t) {
    __asm__ volatile("csrw 0x14D, %0" :: "r"(t));
    /* Encoding: csrw 0x14D, rs1
     * This is functionally identical to: csrw stimecmp, rs1
     * RISC-V CSR instructions always accept the CSR as an immediate.  */
}

#define TIMER_INTERVAL  5000000ULL
/* QEMU's virtual CLINT runs at 10 MHz on most builds.
 * 5,000,000 ticks ≈ 0.5 seconds per tick.
 * The exact period doesn't matter — we just want visible output.   */

/* SBI v1.0 calling convention (SBI spec §3.1):
 *
 *   BEFORE ecall        AFTER ecall
 *   a7 = Extension ID   a0 = error code (0 = success)
 *   a6 = Function ID    a1 = return value
 *   a0-a5 = arguments
 *
 * 'ecall' in S-mode generates an "environment call from S-mode"
 * exception (mcause = 9).  OpenSBI's M-mode handler dispatches
 * based on a7 (EID) and a6 (FID), runs the implementation,
 * stores results in a0/a1, and mret-s back to S-mode.
 *
 * The register constraints below bind C variables to hardware
 * registers so GCC knows exactly which physical registers carry
 * the arguments and receive the results.                          */

static struct sbiret sbi_ecall(
    unsigned long eid, unsigned long fid,
    unsigned long a0,  unsigned long a1,
    unsigned long a2,  unsigned long a3,
    unsigned long a4,  unsigned long a5)
{
    /* "register ... __asm__("aN")" = this C variable MUST live in
     * hardware register aN for the duration of the inline asm block.
     * Without this, GCC might load the value into a different register
     * and the ecall would pass garbage.                              */
    register unsigned long _a0 __asm__("a0") = a0;
    register unsigned long _a1 __asm__("a1") = a1;
    register unsigned long _a2 __asm__("a2") = a2;
    register unsigned long _a3 __asm__("a3") = a3;
    register unsigned long _a4 __asm__("a4") = a4;
    register unsigned long _a5 __asm__("a5") = a5;
    register unsigned long _a6 __asm__("a6") = fid;  /* function ID */
    register unsigned long _a7 __asm__("a7") = eid;  /* extension ID */

    __asm__ volatile("ecall"
        : "+r"(_a0), "+r"(_a1)   /* "+r" = read-write: GCC treats as both
                                    input and output.  OpenSBI overwrites
                                    a0 with error and a1 with value.     */
        : "r"(_a2), "r"(_a3),   /* "r"  = read-only input registers       */
          "r"(_a4), "r"(_a5),
          "r"(_a6), "r"(_a7)
        : "memory");             /* memory clobber: OpenSBI may read/write
                                    memory (e.g. device tree, UART).     */

    return (struct sbiret){ .error = _a0, .value = _a1 };
}

static void demo_sbi_base(void) {
    struct sbiret ret;

    /* ── GET_SPEC_VERSION ──────────────────────────────────────────
     * Returns the SBI specification version this firmware implements.
     * Packed as: bits[30:24] = major, bits[23:0] = minor.
     * Example: 0x03000000 → major=3, minor=0 → print "3.0"           */
    ret = sbi_ecall(SBI_EXT_BASE, SBI_BASE_GET_SPEC_VERSION, 0,0,0,0,0,0);
    puts("  SBI Spec Version : ");
    put_dec((ret.value >> 24) & 0x7F);  /* major in bits[30:24] */
    uart_putc('.');
    put_dec(ret.value & 0xFFFFFF);       /* minor in bits[23:0]  */

    /* ── PROBE_EXTENSION ──────────────────────────────────────────
     * Pass any EID in a0; returns 0 = not present, >0 = available.
     * Use this at runtime rather than assuming extension support.      */
    unsigned long exts[] = {
        SBI_EXT_TIME, SBI_EXT_IPI, SBI_EXT_RFENCE,
        SBI_EXT_HSM,  SBI_EXT_SRST
    };
    const char *names[] = { "TIME", "IPI", "RFENCE", "HSM", "SRST" };
    puts("  Extensions       : ");
    for (int i = 0; i < 5; i++) {
        ret = sbi_ecall(SBI_EXT_BASE, SBI_BASE_PROBE_EXTENSION,
                        exts[i], 0,0,0,0,0);
        if (ret.value)  /* non-zero = extension present */
            { puts(names[i]); uart_putc(' '); }
    }
}

/* SBI TIME extension (EID = 0x54494D45 "TIME").
 *
 * Old way — legacy SBI v0.1 (deprecated since SBI v0.2):
 *   a7 = 0x00 (SET_TIMER legacy), a0 = timer_value
 *   This is how zsbl.S in Project 2 arms the timer.
 *
 * Correct way — SBI v1.0:
 *   a7 = 0x54494D45 (extension "TIME"), a6 = 0 (SET_TIMER function)
 *   a0 = stime_value (absolute value — timer fires when time >= this)
 *
 * Both write mtimecmp in M-mode.  The v1.0 form is what production
 * firmware beyond OpenSBI v0.x will support.                        */
static void sbi_set_timer(unsigned long long t) {
    sbi_ecall(SBI_EXT_TIME, SBI_TIME_SET_TIMER, t, 0,0,0,0,0);
}

static void demo_timer(void) {
    /* On QEMU with sstc, we write stimecmp directly (no SBI ecall).
     * OpenSBI set MENVCFG.STCE=1 during boot, enabling S-mode writes.  */
    set_stimecmp(get_time() + TIMER_INTERVAL);
    /* The CPU will now fire an STI when time >= stimecmp.
     * But interrupts are still globally disabled — we must enable them. */

    /* Enable Supervisor Timer Interrupt Enable — bit 5 in sie.
     * Without this bit set, the STI pending bit (sip.STIP) will never
     * be acted upon even when time >= stimecmp.                         */
    unsigned long sie;
    __asm__ volatile("csrr %0, sie" : "=r"(sie));
    sie |= (1UL << 5);   /* bit 5 = STIE */
    __asm__ volatile("csrw sie, %0" :: "r"(sie));

    /* Enable global S-mode interrupt enable — bit 1 in sstatus.
     * This is the master interrupt switch for S-mode.  Even with
     * STIE set, no interrupt fires until sstatus.SIE=1.              */
    unsigned long ss;
    __asm__ volatile("csrr %0, sstatus" : "=r"(ss));
    ss |= (1UL << 1);    /* bit 1 = SIE */
    __asm__ volatile("csrw sstatus, %0" :: "r"(ss));

    /* wfi: Wait For Interrupt — suspends the hart until an interrupt
     * is pending and enabled.  More power-efficient than spinning.
     * Break out of the loop once we have received 3 interrupts.      */
    while (timer_count < 3)
        __asm__ volatile("wfi");
}

void payload_trap_handler(void) {
    unsigned long scause, sepc;
    __asm__ volatile("csrr %0, scause" : "=r"(scause));
    __asm__ volatile("csrr %0, sepc"   : "=r"(sepc));

    /* scause bit 63: 1 = interrupt (async), 0 = exception (sync).
     * Interrupts and exceptions share the same CSR but use the top
     * bit as a type discriminator.                                    */
    if (scause & (1UL << 63)) {
        unsigned long code = scause & ~(1UL << 63); /* strip the type bit */

        if (code == 5) {
            /* code 5 = Supervisor Timer Interrupt (STI).
             * Fires because time >= stimecmp (sstc path).
             * With sstc, the interrupt clears automatically once
             * stimecmp is written to a future value.                */
            timer_count++;
            puts("[IRQ] Timer #");
            put_dec(timer_count);
            puts("  time=");
            put_hex((unsigned long)get_time());
            puts("\r\n");

            if (timer_count < 3) {
                /* Re-arm: write a new stimecmp value in the future. */
                set_stimecmp(get_time() + TIMER_INTERVAL);
            } else {
                /* Disarm: set stimecmp to max so it never fires again. */
                set_stimecmp(0xFFFFFFFFFFFFFFFFULL);
                /* Also clear STIE in sie for belt-and-suspenders. */
                unsigned long sie;
                __asm__ volatile("csrr %0, sie" : "=r"(sie));
                sie &= ~(1UL << 5);
                __asm__ volatile("csrw sie, %0" :: "r"(sie));
            }
        } else if (code == 1) {
            /* code 1 = Supervisor Software Interrupt (SSI).
             * Fallback path: OpenSBI injects STIP via sip.SSIP
             * on hardware without sstc.  Should not fire on QEMU virt
             * when sstc is present — included for completeness.        */
            timer_count++;
            puts("[IRQ] SSI Timer #"); put_dec(timer_count); puts("\r\n");
            __asm__ volatile("csrc sip, %0" :: "r"(1UL << 1)); /* clear SSIP */
            if (timer_count < 3)
                sbi_set_timer(get_time() + TIMER_INTERVAL);
        } else {
            puts("[IRQ] Unknown code="); put_dec(code); puts("\r\n");
        }
    } else {
        /* Synchronous exception.  Print diagnostics and skip the
         * faulting instruction by advancing sepc by 4 bytes.          */
        puts("[EXC] scause="); put_hex(scause);
        puts(" sepc=");        put_hex(sepc); puts("\r\n");
        __asm__ volatile("csrw sepc, %0" :: "r"(sepc + 4));
    }
}

/* Global interrupt counter — declared volatile because it is written
 * by the trap handler (interrupt context) and read in demo_timer()
 * (normal context).  volatile prevents the compiler from caching the
 * value in a register across the wfi instruction.                     */
static volatile int timer_count = 0;

/* Called by entry.S after sp and stvec are set up.
 * a0 and a1 set by OpenSBI are passed through intact:
 *   a0 = hartid (which hardware thread/core we are running on)
 *   a1 = DTB physical address (device tree blob OpenSBI built)      */
void payload_main(unsigned long hartid, unsigned long dtb) {
    puts("\r\n########################################\r\n");
    puts("#   OpenSBI Payload Demo               #\r\n");
    puts("########################################\r\n");
    puts("  Hart ID : "); put_hex(hartid); puts("\r\n");
    puts("  DTB     : "); put_hex(dtb);    puts("\r\n");

    demo_sbi_base();       /* query spec version, impl, extensions */
    demo_sbi_comparison(); /* print note on legacy vs SBI v1.0 convention */
    demo_timer();          /* write stimecmp, wfi, 3 timer interrupts */

    puts("\r\n########################################\r\n");
    puts("#   Demo complete. System halted.       #\r\n");
    puts("########################################\r\n");

    while (1) __asm__ volatile("wfi"); /* halt: power-efficient infinite loop */
}

/* Tell the linker which symbol is the entry point.
 * This sets the ELF e_entry field.  QEMU's -kernel reads e_entry
 * to find the program's start address.                           */
ENTRY(_start)

MEMORY {
    /* 0x80200000: the address fw_jump jumps to (FW_JUMP_ADDR).
     * Must match the make variable passed during OpenSBI build.  */
    RAM (rwx) : ORIGIN = 0x80200000, LENGTH = 2M
}

SECTIONS {
    . = 0x80200000;

    .text : {
        *(.text.entry)  /* _start MUST be first — entry.S .text.entry */
        *(.text*)       /* all other .text from payload.c and entry.S  */
    } > RAM

    .rodata : { *(.rodata*) } > RAM   /* string literals, const arrays */
    .data   : { *(.data*)   } > RAM   /* initialised global variables */

    .bss : {
        _bss_start = .;
        *(.bss*) *(COMMON)          /* zero-initialised globals */
        _bss_end = .;
    } > RAM

    .sstack : { *(.sstack) } > RAM    /* 8 KB stack from entry.S */
}

CROSS   = riscv64-unknown-elf-
AS      = $(CROSS)as
CC      = $(CROSS)gcc
LD      = $(CROSS)ld

# rv64imac_zicsr:
#   rv64    = 64-bit base integer ISA
#   i       = base integer (RV64I)
#   m       = multiply/divide
#   a       = atomic instructions
#   c       = compressed 16-bit instructions
#   _zicsr  = CSR instructions (csrr, csrw, etc.)
#
# _zicsr must be explicit on GCC 12+ which separates it from the base ISA.
# GCC 10.2 (used in this project) includes CSR instructions in rv64imac
# by default — but including _zicsr doesn't hurt.
# We do NOT add _sstc because GCC 10.2 doesn't know it.
# We use raw CSR number 0x14D for stimecmp instead.              
ARCH    = -march=rv64imac_zicsr -mabi=lp64

ASFLAGS = -g $(ARCH)
CFLAGS  = -g -O0 $(ARCH) \
           -nostdlib -nostartfiles \  # no C runtime startup code
           -ffreestanding \           # no hosted standard library
           -fno-builtin \             # do not replace puts/memcpy with builtins
           -Wall \
           -mcmodel=medany \          # PC-relative ±2 GB addressing
           -mno-relax                 # disable linker relaxation (avoids GNU ld issues)

OPENSBI = $(HOME)/eclipse-workspace/opensbi/build/platform/generic/firmware/fw_jump.elf

all: payload.elf

payload.elf: entry.o payload.o
	$(LD) -T linker.ld -nostdlib -o $@ $^

entry.o: entry.S
	$(AS) $(ASFLAGS) -o $@ $<

payload.o: payload.c
	$(CC) $(CFLAGS) -c -o $@ $<

# Run with your locally-built OpenSBI
qemu-run: all
	qemu-system-riscv64 \
		-machine virt \
		-nographic \
		-bios $(OPENSBI) \
		-kernel payload.elf

# Same but paused — waiting for GDB on port 1234
qemu: all
	qemu-system-riscv64 \
		-machine virt \
		-nographic \
		-bios $(OPENSBI) \
		-kernel payload.elf -s -S

clean:
	rm -f *.o *.elf

.PHONY: all clean qemu qemu-run

cat > ~/eclipse-workspace/opensbi/opensbi_payload/debug_qemu.sh << 'EOF'
#!/bin/bash
qemu-system-riscv64 \
    -machine virt \
    -nographic \
    -bios ~/eclipse-workspace/opensbi/build/platform/generic/firmware/fw_jump.elf \
    -kernel ~/eclipse-workspace/opensbi/opensbi_payload/payload.elf \
    -S -s
EOF
chmod +x ~/eclipse-workspace/opensbi/opensbi_payload/debug_qemu.sh

set arch riscv:rv64
set confirm off

# Load symbols for both ELFs so you can step through OpenSBI AND your payload
symbol-file /home/vikram/eclipse-workspace/opensbi/opensbi_payload/payload.elf
add-symbol-file /home/vikram/eclipse-workspace/opensbi/build/platform/generic/firmware/fw_jump.elf 0x80000000

# Hardware breakpoint — reliable even before memory is fully initialised
hbreak *0x80200000
continue