Running Examples on AtomSim

The RISC-V Atom project consists of a wide range of examples programs out-of-the-box to test. These examples programs reside in RVATOM/sw/examples directory.

Switch to examples directory

$ cd sw/examples

Lets run the classical “hello World!” example first!

Hello World Example

The source code for the hello-world example resides in the hello-asm directory. You can have a look at the source code. First we need to compile the hello world example with our RISC-V gcc cross-compiler. For this purpose, use the provided makefile as following.

$ make soctarget=atombones ex=hello-asm compile

The above command should generate a hello.elf file in the hello-asm directory. Now fire up atomsim and provide the generated elf file as argument.

$ atomsim hello-asm/hello.elf
Hello World!
  -- from Assembly

Alternatively, use make run to run the example.

$ make soctarget=atombones ex=hello-asm run

We can compile other examples also in the similar fashion by using the following syntax:

$ make soctarget=<TARGET> ex=<EXAMPLE> compile
$ make soctarget=<TARGET> ex=<EXAMPLE> run


Run $ make help to get more information about supported targets and examples.

The Runexamples Script

Instead of testing all examples one-by-one, we can use the provided atomsim-runexamples script to automatically compile and simulate all examples.

Simply invoke the script as following

$ atomsim-runexamples

atomsim-runexamples script internally uses the same makefile that we used earlier, with the run-all target. Therefore we can alternatively get the same result by using the make command (in RVATOM/sw/examples directory).

$ make soctarget=atombones run-all

Using Atomsim Vuart

By default AtomSim relays the output of the running application on stdout. But, in this mode of operation, user cannot provide any input to the running program. Alternatively, Atomsim can estabilish a two-way communication with AtomSim through a linux serial port. This functionality is provided by the Vuart module in Atomsim.

Generating virtual serial ports

A pair of connected serial ports can be generated by usng the provided atomsim-gen-vports script as following.

$ atomsim-gen-vports

This will generate a pair of new virtual serial ports in /dev/pts and links them together using the socat linux command. This means that whatever is sent to port-1 is recieved at port-2 and vice versa. Further, this script also generates symlinks to these generated ports in the RVATOM directory as simport and userport.

Interacting with Stdout and Stdin over virtual ports

Open a new terminal (say terminal-2) and run the screen command as following

$ screen $RVATOM/userport 9600

And on the other terminal (terminal-1) run atomsim as following

$ atomsim hello-asm/hello.s --vuart=$RVATOM/simport

You should now be able to see the output on the terminal-2.

To close the screen command press ctrl+a, type :quit and press enter.

Adding New Examples

To add a new example to the existing framework, simply create a directory under the RVATOM/sw/examples directory.

$ mkdir newexample

Next, put your source files under this directory.

$ cat newexample.c
#include <stdio.h>
void main()
    char hello[] = "New Example\n";

Finally add a new file named Makefile.include in the same directory which defines the name of the source files and executable file as follows.

$ cat Makefile.include
src_files = newexample.c
executable = newexample.elf

That’s it! Now you can use the same compile and run commands as discussed earlier to run this example.