Getting Started

This page takes you from nothing installed to a kernel of your own running on your own machine. You do not need an FPGA or a cloud account.

A kernel is a small program that runs on the Sparsr processor. A host application is your ordinary program, which loads the kernel, moves data in and out of the device and starts it. You write both.

Step 1 - install the SDK

Download the Sparsr Kernel SDK from the Sparsr Developer Zone and unpack it. You get one directory:

sparsr-sdk-<version>/
  bin/         spasm (the assembler) and sparsr-vm (the processor, as a program)
  lib/         the host library and the backends it can run on
  include/     sparsr.h for your host program, sparsr_intrinsics.h or sparsr.S for your kernel
  ldscripts/   the link script a kernel is built with
  startup/     the startup file a C kernel is built with
  examples/    working examples, which is where to start

You do not install anything system-wide and you do not need root. Every path in the examples is relative to this directory, so keep them where they are and build them in place.

Step 2 - install a RISC-V compiler

A kernel written in C is compiled by a stock RISC-V bare-metal GCC. Sparsr provides no compiler of its own, only the three files GCC needs.

sudo apt install gcc-riscv64-unknown-elf binutils-riscv64-unknown-elf

Skip this step only if you are running an example that is already built. Every kernel in this chapter is compiled with this toolchain.

Step 3 - run an example

cd sparsr-sdk-<version>/examples/03_kernel_in_c
make run

Expect this:

lane 0: 0x0F0F0000 ^ 0x00FF0000 = 0x0FF00000
...
Wide XOR check passed.

That built a kernel from C, built a host program, and ran them together against the Sparsr VM, which is the Sparsr processor as a program on your CPU. The kernel is four wide instructions:

#include "sparsr_intrinsics.h"

#define ROW_A      1
#define ROW_B      2
#define ROW_RESULT 3

void kernel_main(void) {
    _sparsr_wl(SPARSR_W1, ROW_A);          /* load a wide vector    */
    _sparsr_wl(SPARSR_W2, ROW_B);          /* and another one       */
    _sparsr_wxor(SPARSR_W3, SPARSR_W1, SPARSR_W2);   /* XOR the whole register at once */
    _sparsr_ws(SPARSR_W3, ROW_RESULT);     /* write the result back */
}

Each of those four lines becomes exactly one machine instruction.

Step 4 - write your own

The job is to find the part of your program that does a lot of bitwise work on large bit vectors, and move that part into a kernel. The rest of your program does not change.

A typical loop looks like this on the host side:

#include "sparsr.h"

sparsr_kernel_init();                                  /* pick the backend        */
sparsr_write_data_wmem(vector_a, 1);                   /* send data to the device */
sparsr_write_data_wmem(vector_b, 2);
sparsr_load_batch_from_bin("build/my_kernel.spex", 0); /* load the kernel         */
sparsr_execute_batch(0);                               /* run it                  */

while (sparsr_read_status() == 0) { }                  /* wait for it to finish   */

uint8_t *result = sparsr_read_data_wmem(3);            /* read the answer back    */

Host App Development explains every one of those calls and the memories they address.

Step 5 - pick a language for the kernel

Write your kernel in C. It is a real language with real control flow, and the VM runs every RV32I instruction. The rest of this chapter assumes C.

If you would rather write the instruction stream yourself, write RISC-V assembly in a .S file. spasm hands it to the stock RISC-V assembler and linker, so it targets the same device a C kernel does.

The FPGA is part-way through the same move. Its scalar half decodes a subset of RV32I as of September 2026, and its wide half decodes the wide instructions in their RISC-V form. See the Instruction Set page for exactly which instructions each side runs today.

Step 6 - run it on hardware

A Sparsr card is an FPGA on an AWS EC2 F2 instance. The Quick start on AWS launches one in your own AWS account, loads the Sparsr FPGA image onto the card, and runs a C kernel there. It uses the same host program and the same kernel as on the VM. Only SPARSR_BACKEND changes, from vm to fpgaf2.

The card does not run every instruction the VM runs yet. Check the Instruction Set page before you move your own kernel onto it.

Where to go next

• Writing a Kernel in C - the rules, the intrinsics and the build line.
• Host App Development - how your program feeds the device.
• Tooling and CLI Reference - spasm and sparsr-vm.
• Memory Model - the three memories, and how wide vectors move in and out of them.