|
| 1 | +--- |
| 2 | +title: Quickstart Images |
| 3 | +layout: page |
| 4 | +nav_order: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +# Quick Start with Docker Images |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | + - An x86 Linux workstation with support for `docker` or `podman` |
| 12 | + |
| 13 | +The fastest way to get started with OpenRISC is to use our pre-build [docker](https://www.docker.com) |
| 14 | +container images. These provide a base development environment to see how things work. Other tutorials |
| 15 | +assume you are running and installing software on your own workstation, but they could be adapted to run |
| 16 | +in these docker images. |
| 17 | + |
| 18 | +## About Editors |
| 19 | + |
| 20 | +As the images have no editor installed by default you can create a simple |
| 21 | +program using `cat` as below. If needed you can install an editor with `apt-get` |
| 22 | +or by extending the docker image. |
| 23 | + |
| 24 | +Create a `hello.c` |
| 25 | + |
| 26 | +```bash |
| 27 | +cat <<EOF >hello.c |
| 28 | +#include <stdio.h> |
| 29 | +
|
| 30 | +int main() { |
| 31 | + puts("Hello\n"); |
| 32 | + return 0; |
| 33 | +} |
| 34 | +EOF |
| 35 | +``` |
| 36 | + |
| 37 | +## Simulator Environment |
| 38 | + |
| 39 | +### Hello World |
| 40 | + |
| 41 | +The below example shows how you can download the docker image |
| 42 | +and run the image using `podman`. You could also use `docker` if you like. |
| 43 | + |
| 44 | +This then uses the or1k simulator to simulate our Hello World program. |
| 45 | + |
| 46 | +To pull and run the image run: |
| 47 | + |
| 48 | +```bash |
| 49 | +podman pull stffrdhrn/or1k-sim-env |
| 50 | +podman run -it --rm stffrdhrn/or1k-sim-env |
| 51 | +``` |
| 52 | + |
| 53 | +This will bring you to the container prompt which |
| 54 | +has access to the simulator development environment. |
| 55 | + |
| 56 | +Create the `hello.c` file as described above, then to compile our program run |
| 57 | +`gcc` from the OpenRISC toolchain as below: |
| 58 | + |
| 59 | +```bash |
| 60 | +or1k-elf-gcc hello.c -o hello |
| 61 | +``` |
| 62 | + |
| 63 | +After the program is compiled we can run the program in the simulator with the |
| 64 | +following: |
| 65 | + |
| 66 | +```bash |
| 67 | +or1k-elf-sim -f /opt/or1k/sim.cfg hello |
| 68 | +``` |
| 69 | + |
| 70 | +Putting it all together: |
| 71 | + |
| 72 | +``` |
| 73 | +$ podman pull stffrdhrn/or1k-sim-env |
| 74 | +$ podman run -it --rm stffrdhrn/or1k-sim-env |
| 75 | +
|
| 76 | +root@011a54cf7988:/tmp# cat <<EOF >hello.c |
| 77 | +> #include <stdio.h> |
| 78 | +> |
| 79 | +> int main() { |
| 80 | +> puts("Hello\n"); |
| 81 | +> return 0; |
| 82 | +> } |
| 83 | +> EOF |
| 84 | +root@011a54cf7988:/tmp# or1k-elf-gcc hello.c -o hello |
| 85 | +root@011a54cf7988:/tmp# or1k-elf-sim -f /opt/or1k/sim.cfg hello |
| 86 | +
|
| 87 | +Seeding random generator with value 0xcf48d5be |
| 88 | +Insn MMU 0KB: 1 ways, 64 sets, entry size 1 bytes |
| 89 | +Data MMU 0KB: 1 ways, 64 sets, entry size 1 bytes |
| 90 | +Ethernet TAP type |
| 91 | +Verbose on, simdebug off, interactive prompt off |
| 92 | +Machine initialization... |
| 93 | +Clock cycle: 10ns |
| 94 | +No data cache. |
| 95 | +No instruction cache. |
| 96 | +BPB simulation off. |
| 97 | +BTIC simulation off. |
| 98 | +Or1ksim 2025-04-27 |
| 99 | +Building automata... done, num uncovered: 0/215. |
| 100 | +Parsing operands data... done. |
| 101 | +Warning: Failed to open TUN/TAP device: No such file or directory |
| 102 | +Or1ksim: Console listening for telnet on port 10084 |
| 103 | +UART at 0x90000000 |
| 104 | +Resetting Tick Timer. |
| 105 | +Resetting Power Management. |
| 106 | +Resetting PIC. |
| 107 | +Starting at 0x00000000 |
| 108 | +loadcode: filename hello startaddr=00000000 virtphy_transl=00000000 |
| 109 | +Not COFF file format |
| 110 | +ELF type: 0x0002 |
| 111 | +ELF machine: 0x005c |
| 112 | +ELF version: 0x00000001 |
| 113 | +ELF sec = 13 |
| 114 | +Program Header: PT_LOAD, vaddr: 0x00000000, paddr: 0x0 offset: 0x00002000, filesz: 0x000069a8, memsz: 0x000069a8 |
| 115 | +Program Header: PT_LOAD, vaddr: 0x000089a8, paddr: 0x89a8 offset: 0x000089a8, filesz: 0x000006b4, memsz: 0x00000b88 |
| 116 | +WARNING: sim_init: Debug module not enabled, cannot start remote service to GDB |
| 117 | +Hello |
| 118 | +``` |
| 119 | + |
| 120 | +## FuseSoC Environment |
| 121 | + |
| 122 | +We also have an FPGA development environment for OpenRISC available. The below |
| 123 | +example shows how to build and run a simple program. The program runs on a [iverlog](https://bleyer.org/icarus/) |
| 124 | +verilog simulator but you can also use the FuseSoC backend to generate a bitstream. |
| 125 | + |
| 126 | +To pull and run the image run: |
| 127 | + |
| 128 | +```bash |
| 129 | +podman pull stffrdhrn/or1k-verilog-env |
| 130 | +podman run -it --rm stffrdhrn/or1k-verilog-env |
| 131 | +``` |
| 132 | + |
| 133 | +This will bring you to the container prompt which |
| 134 | +has access to the verilog development environment. |
| 135 | + |
| 136 | +``` |
| 137 | +Create the `hello.c` file as described above, then to compile our program run |
| 138 | +`gcc` from the OpenRISC toolchain as below: |
| 139 | +
|
| 140 | +```bash |
| 141 | +or1k-elf-gcc hello.c -o hello |
| 142 | +``` |
| 143 | + |
| 144 | +After our program is compiled we want to prepare to run the program, check that the |
| 145 | +fusesoc environment is setup correctly using the following commands: |
| 146 | + |
| 147 | +```bash |
| 148 | +cd cores |
| 149 | +fusesoc core-info mor1kx-generic |
| 150 | +``` |
| 151 | + |
| 152 | +Changing directories to `/tmp/src/cores` is needed as fusesoc looks |
| 153 | +for verilog IP cores starting in the current directory. The `fusesoc core-info` |
| 154 | +command checks if our `mor1kx-generic` SoC is available as expected. |
| 155 | + |
| 156 | +To compile to verilog SoC and run it we use: |
| 157 | + |
| 158 | +```bash |
| 159 | +fusesoc run --target mor1kx_tb mor1kx-generic --elf_load ../hello |
| 160 | +``` |
| 161 | + |
| 162 | +This runs `mor1kx-generic` `mor1kx_tb` (mor1kx test bench target), which is the |
| 163 | +simulator that allows loading elf executables to memory and run them. Please |
| 164 | +explore the other arguments such as `--help` and `--trace_enable --trace_to_screen`. |
| 165 | + |
| 166 | +Putting it all together: |
| 167 | + |
| 168 | +``` |
| 169 | +$ podman pull stffrdhrn/or1k-verilog-env |
| 170 | +$ podman run -it --rm stffrdhrn/or1k-verilog-env |
| 171 | +
|
| 172 | +or1kuser@fb306c0dc35e:/tmp/src$ cat <<EOF >hello.c |
| 173 | +> #include <stdio.h> |
| 174 | +> |
| 175 | +> int main() { |
| 176 | +> puts("Hello\n"); |
| 177 | +> return 0; |
| 178 | +> } |
| 179 | +> EOF |
| 180 | +or1kuser@fb306c0dc35e:/tmp/src$ or1k-elf-gcc hello.c -o hello |
| 181 | +or1kuser@fb306c0dc35e:/tmp/src$ cd cores |
| 182 | +or1kuser@fb306c0dc35e:/tmp/src/cores$ fusesoc core-info mor1kx-generic |
| 183 | +or1kuser@fb306c0dc35e:/tmp/src/cores$ fusesoc run --target mor1kx_tb mor1kx-generic --elf_load ../hello |
| 184 | +
|
| 185 | +INFO: Preparing ::adv_debug_sys:3.1.0-r1 |
| 186 | +INFO: Downloading olofk/adv_debug_sys from github |
| 187 | +INFO: Preparing ::cdc_utils:0.1-r1 |
| 188 | +INFO: Downloading fusesoc/cdc_utils from github |
| 189 | +INFO: Preparing ::elf-loader:1.0.3 |
| 190 | +INFO: Preparing ::intgen:1.0 |
| 191 | +INFO: Preparing ::jtag_tap:1.13-r1 |
| 192 | +INFO: Downloading olofk/jtag from github |
| 193 | +INFO: Preparing ::jtag_vpi:0-r5 |
| 194 | +INFO: Downloading fjullien/jtag_vpi from github |
| 195 | +INFO: Preparing ::mor1kx:5.2 |
| 196 | +INFO: Preparing ::uart16550:1.5.5-r1 |
| 197 | +INFO: Downloading olofk/uart16550 from github |
| 198 | +INFO: Preparing ::verilog-arbiter:0-r3 |
| 199 | +INFO: Downloading bmartini/verilog-arbiter from github |
| 200 | +INFO: Preparing ::vlog_tb_utils:1.1-r1 |
| 201 | +INFO: Downloading fusesoc/vlog_tb_utils from github |
| 202 | +INFO: Preparing ::wb_common:1.0.3 |
| 203 | +INFO: Downloading fusesoc/wb_common from github |
| 204 | +INFO: Preparing ::wb_intercon:1.4.1 |
| 205 | +INFO: Downloading olofk/wb_intercon from github |
| 206 | +INFO: Preparing ::wb_ram:1.1-r1 |
| 207 | +INFO: Downloading fusesoc/wb_ram from github |
| 208 | +INFO: Preparing ::mor1kx-generic:1.1 |
| 209 | +INFO: Setting up project |
| 210 | +WARNING: This backend is deprecated and will eventually be removed. Please migrate to the flow API instead. See https://edalize.readthedocs.io/en/latest/ref/migrations.html#migrating-from-the-tool-api-to-the-flow-api for more details. |
| 211 | +WARNING: src/jtag_vpi_0-r5/jtag_common.c has unknown file type 'cSource' |
| 212 | +WARNING: src/jtag_vpi_0-r5/jtag_vpi.c has unknown file type 'cSource' |
| 213 | +INFO: Running pre_build script check_libelf |
| 214 | +INFO: Building |
| 215 | +INFO: Running |
| 216 | +vvp -n -M. -l icarus.log -melf_loader_vpi -mjtag_vpi mor1kx-generic_1.1 -fst +elf_load=/tmp/src/hello |
| 217 | +Program header 0: addr 0x00000000, size 0x000069A8 |
| 218 | +Program header 1: addr 0x000089A8, size 0x000006B4 |
| 219 | +elf-loader: /tmp/src/hello was loaded |
| 220 | +Loading 9239 words |
| 221 | + 0 : Illegal Wishbone B3 cycle type (xxx) |
| 222 | +Hello |
| 223 | +
|
| 224 | +src/mor1kx_5.2/bench/verilog/mor1kx_monitor.v:140: $finish called at 171635 (1s) |
| 225 | +``` |
| 226 | + |
| 227 | +## Further Reading |
| 228 | + |
| 229 | + - [stffrdhrn/or1k-docker-images](https://github.com/stffrdhrn/or1k-docker-images) - OpenRISC docker images home page |
0 commit comments