Simics scripts for starting RISC-V machines are located in the [project]/targets/risc-v-simple/ directory, while the actual configuration scripts can be found in the targets/risc-v-simple/ directory in the corresponding add-on package.

3.1 Build and run

You need to build the Linux software stack for the RISC-V simple system before you can boot it, since the package does not include any prebuilt binaries. The target scripts are built to assume a Buildroot configuration, which is described in this section. You can also use other Linux and operating system build, which will require adjusting the software configuration parameters of the system.

3.1.1 Building linux, bootloader, and root file system

This is how you use Buildroot to create a bootable software set up for the RISC-V simple, as used by default by the target scripts.

Start by cloning buildroot:

$ git clone https://github.com/buildroot/buildroot.git

Add a configuration file called simics_simple_riscv_defconfig to the configs directory. Copy the following text into the file:

# Architecture
BR2_riscv=y
BR2_RISCV_64=y

# System
BR2_TARGET_GENERIC_GETTY_PORT="ttyS0"
BR2_SYSTEM_DHCP="eth0"

# Kernel
BR2_LINUX_KERNEL=y
BR2_LINUX_KERNEL_USE_ARCH_DEFAULT_CONFIG=y
BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE="5.17"
BR2_PACKAGE_HOST_LINUX_HEADERS_CUSTOM_5_17=y
BR2_LINUX_KERNEL_IMAGE=y

# Boot loader
BR2_TARGET_OPENSBI=y
BR2_TARGET_OPENSBI_PLAT="generic"

# Root file system
BR2_TARGET_ROOTFS_EXT2=y

# Host packages
BR2_PACKAGE_HOST_DTC=y

Configure Buildroot to use this configuration:
```
$ make simics_simple_riscv_defconfig
```
Build:
```
$ make
```

Check the directory output/images. There should be something like this:

output/images/
├── fw_dynamic.bin
├── fw_dynamic.elf
├── fw_jump.bin
├── fw_jump.elf
├── Image
├── rootfs.ext2
└── rootfs.tar

Copy Image, rootfs.ext2 and fw_jump.elf to your Simics project, into the folder [project]/targets/risc-v-simple/images/linux. You might have to create this folder if it does not already exist.

3.1.2 Run RISC-V Simple Simics Platform

Open a shell in your Simics project
Start a new Simics simulation session:
```
$ ./simics
```
Load the RISC-V simple target script from the Simics simulator command line:
```
simics> load-target target = "risc-v-simple/linux"
```
Run the simulation:
```
simics> run
```

Wait a short while. The target system should boot, and the target system serial console should show something like this:

[    0.105470] EXT4-fs (vda): mounted filesystem with ordered data mode. Quota mode: disabled.
[    0.106430] VFS: Mounted root (ext4 filesystem) on device 254:0.
[    0.107130] devtmpfs: mounted
[    0.107700] Freeing unused kernel image (initmem) memory: 2152K
[    0.123900] Run /sbin/init as init process
[    0.138840] EXT4-fs (vda): re-mounted. Quota mode: disabled.
Starting syslogd: OK
Starting klogd: OK
Running sysctl: OK
Saving random seed: [    0.155108] random: dd: uninitialized urandom read (32 bytes read)
OK
Starting network: OK

Welcome to Buildroot
buildroot login: root
#

3.1.3 Enabling SSH

The Buildroot configuration above does not include a secure shell (SSH) server or client. To use remote login with the target system, either from the host or from another simulated machine, you need to add SSH to the configuration.

First step is to configure Builtroot to include the SSH daemon into your root file system and add an sshd configuration.

Add these two lines into [BUILDROOT_DIR]/configs/simics_simple_riscv_defconfig

BR2_ROOTFS_OVERLAY="board/simics/risc-v-simple/rootfs_overlay"
BR2_PACKAGE_OPENSSH=y

To configure sshd to allow root to login over SSH, add this file (and create the necessary folder hierarchy):
[BUILDROOT_DIR]/board/simics/risc-v-simple/rootfs_overlay/etc/ssh/sshd_config

PermitRootLogin yes
PermitEmptyPasswords yes
AuthorizedKeysFile .ssh/authorized_keys
Subsystem sftp /usr/libexec/sftp-server

With SSH thus added and configured, reconfigure and rebuild the root file system:

Configure Buildroot to use this configuration:
```
$ make simics_simple_riscv_defconfig
```
Build:
```
$ make
```

Copy the the output/images/rootfs.ext2 to your Simics project as described in section 3.1.1.

Start a new Simics simulation as described in section 3.1.2 and wait for linux to boot up.

Check the target machine IPv4 address using ifconfig. In the target system serial console:

# ifconfig
eth0      Link encap:Ethernet  HWaddr 00:17:A0:00:00:00
          inet addr:10.10.0.10  Bcast:10.10.0.255  Mask:255.255.255.0
          inet6 addr: 11:2233:4455:6677:217:a0ff:fe00:0/64 Scope:Global
          inet6 addr: fe80::217:a0ff:fe00:0/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:5 errors:0 dropped:0 overruns:0 frame:0
          TX packets:11 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:1196 (1.1 KiB)  TX bytes:1675 (1.6 KiB)

You need to enable the Simics simulator real time mode, since otherwise the SSH TCP connection will time out because simulated time runs faster than real time.

To provide access to the simulated target machine from the host, you must enable NAPT-based real networking.

running> stop
simics> enable-real-time-mode
Real-time mode enabled.
simics> connect-real-network target-ip = 10.10.0.10
NAPT enabled with gateway 10.10.0.1/24 on link ethernet_switch0.link.
NAPT enabled with gateway fe80::2220:20ff:fe20:2000/64 on link ethernet_switch0.link.
Host TCP port 4021 -> 10.10.0.10:21
Host TCP port 4022 -> 10.10.0.10:22
Host TCP port 4023 -> 10.10.0.10:23
Host TCP port 4080 -> 10.10.0.10:80
Warning: This can expose the target system on the host local network.
Real DNS enabled at 10.10.0.1/24 on link ethernet_switch0.link.
Real DNS enabled at fe80::2220:20ff:fe20:2000/64 on link ethernet_switch0.link.
simics> run

In this example port 4022 on the host is forwarded to port 22 in the target machine (which is the port used for SSH). This number can be different, if port 4022 is in use the Simics simulator will select another, free, port to use.

Now we are ready to ssh into the target machine. In another terminal on your host:

$ ssh root@localhost -p 4022
[...]
# uname -a
Linux buildroot 6.1.9 #1 SMP Fri Feb  3 11:58:53 CET 2023 riscv64 GNU/Linux
#

3.1.4 Modifying the device tree

If you change the hardware configuration of the target system by changing the number of cores or the size of memory, you need to also provide the software stack with an updated device tree blob (DTB) file.

The device tree binary blob that is used by default is located at [RISC-V-simple-package]/targets/risc-v-simple/risc-v-simple.dtb. A text version exists as well, targets/risc-v-simple/risc-v-simple.dts.

To compile changes to the .dts file into a new .dtb, you need the program dtc. If you have that installed already you can use it. Otherwise the buildroot project you just built generated that program for you: [BUILDROOT_DIR]/output/host/bin/dtc. You can copy the text version, edit it, and compile as shown below, to create your local version local-risc-v-simple.dtb.

$ [BUILDROOT_DIR]/output/host/bin/dtc -O dtb -o local-risc-v-simple.dtb copy-risc-v-simple.dts

Running with your modified device tree:

simics> load-target target = "risc-v-simple/linux" linux:runtime:dtb_image = local-risc-v-simple.dtb

3.2 Machine Scripts and Parameters

Documentation of target parameters is missing because autogeneration is not supported yet.