Quick Start with Docker Images

Prerequisites

An x86 Linux workstation with support for docker or podman

The fastest way to get started with OpenRISC is to use our pre-build docker container images. These provide a base development environment to see how things work. Other tutorials assume you are running and installing software on your own workstation, but they could be adapted to run in these docker images.

About Editors

As the images have no editor installed by default you can create a simple program using cat as below. If needed you can install an editor with apt-get or by extending the docker image.

Create a hello.c

cat <<EOF >hello.c
#include <stdio.h>

int main() {
    puts("Hello\n");
    return 0;
}
EOF

Simulator Environment

Hello World

The below example shows how you can download the docker image and run the image using podman. You could also use docker if you like.

This then uses the or1k simulator to simulate our Hello World program.

To pull and run the image run:

podman pull stffrdhrn/or1k-sim-env
podman run -it --rm stffrdhrn/or1k-sim-env

This will bring you to the container prompt which has access to the simulator development environment.

Create the hello.c file as described above, then to compile our program run gcc from the OpenRISC toolchain as below:

or1k-elf-gcc hello.c -o hello

After the program is compiled we can run the program in the simulator with the following:

or1k-elf-sim -f /opt/or1k/sim.cfg hello

Putting it all together:

$ podman pull stffrdhrn/or1k-sim-env
$ podman run -it --rm stffrdhrn/or1k-sim-env

root@011a54cf7988:/tmp# cat <<EOF >hello.c
> #include <stdio.h>
>
> int main() {
>     puts("Hello\n");
>     return 0;
> }
> EOF
root@011a54cf7988:/tmp# or1k-elf-gcc hello.c -o hello
root@011a54cf7988:/tmp# or1k-elf-sim -f /opt/or1k/sim.cfg hello

Seeding random generator with value 0xcf48d5be
Insn MMU 0KB: 1 ways, 64 sets, entry size 1 bytes
Data MMU 0KB: 1 ways, 64 sets, entry size 1 bytes
Ethernet TAP type
Verbose on, simdebug off, interactive prompt off
Machine initialization...
Clock cycle: 10ns
No data cache.
No instruction cache.
BPB simulation off.
BTIC simulation off.
Or1ksim 2025-04-27
Building automata... done, num uncovered: 0/215.
Parsing operands data... done.
Warning: Failed to open TUN/TAP device: No such file or directory
Or1ksim: Console listening for telnet on port 10084
UART at 0x90000000
Resetting Tick Timer.
Resetting Power Management.
Resetting PIC.
Starting at 0x00000000
loadcode: filename hello  startaddr=00000000  virtphy_transl=00000000
Not COFF file format
ELF type: 0x0002 
ELF machine: 0x005c
ELF version: 0x00000001
ELF sec = 13
Program Header: PT_LOAD, vaddr: 0x00000000, paddr: 0x0 offset: 0x00002000, filesz: 0x000069a8, memsz: 0x000069a8
Program Header: PT_LOAD, vaddr: 0x000089a8, paddr: 0x89a8 offset: 0x000089a8, filesz: 0x000006b4, memsz: 0x00000b88
WARNING: sim_init: Debug module not enabled, cannot start remote service to GDB
Hello

FuseSoC Environment

We also have an FPGA development environment for OpenRISC available. The below example shows how to build and run a simple program. The program runs on a iverlog verilog simulator but you can also use the FuseSoC backend to generate a bitstream.

To pull and run the image run:

podman pull stffrdhrn/or1k-verilog-env
podman run -it --rm stffrdhrn/or1k-verilog-env

This will bring you to the container prompt which has access to the verilog development environment.

Create the hello.c file as described above, then to compile our program run gcc from the OpenRISC toolchain as below:

or1k-elf-gcc hello.c -o hello

This will compile our Hello World program using the OpenRISC baremetal toolchain and output an ELF file to hello.

After our program is compiled we want to prepare to run the program, check that the fusesoc environment is setup correctly using the following commands:

cd cores
fusesoc core-info mor1kx-generic

Changing directories to /tmp/src/cores is needed as fusesoc looks for verilog IP cores starting in the current directory. The fusesoc core-info command checks if our mor1kx-generic SoC is available as expected.

To compile and run the verilog SoC we use:

fusesoc run --target mor1kx_tb mor1kx-generic --elf_load ../hello

This runs mor1kx-generic mor1kx_tb (mor1kx test bench target), which is the simulator that allows loading elf executables to memory and run them. Please explore the other arguments such as --help and --trace_enable --trace_to_screen.