Gavare's eXperimental Emulator: Configuration files

Back to the index

## Configuration files

- Configuration file syntax
- A minimal example
- Network across multiple hosts

### Configuration file syntax:

Configuration files are simple text files. I don't have time to write down a formal syntax right now, so I hope that conveying the syntax through an example is good enough:

    !!gxemul     <-- configuration files must start like this
    !
    !  This is an example configuration file for GXemul.
    !  Anything following an exclamation mark (and also the exclamation
    !  mark itself) is ignored.
    !
    !  Each configuration file should contain one emul entry. Almost
    !  everything else is optional.

    emul(
        name("my test emul")	 !  Optional name of this emulation

        !  This creates an ethernet network:
        net(
    	ipv4net("10.2.0.0")  !  The default is 10.0.0.0/8, but
    	ipv4len(16)          !  it can be overridden like this.
    	!  local_port(12345)
    	!  add_remote("localhost:12346")
        )

        !  This creates a machine:
        machine(
    	name("My test machine")

    	! serial_nr(123)    ! Useful when emulating multiple machines
    	                    ! on multiple hosts, and they need to have
    	                    ! unique MAC addresses, etc.

    	type("dec")		!  This is actually not optional
    	subtype("5000/200")

    	cpu("R3000")    !  Normally set implicitly to a reasonable
    			!  value, depending on type and subtype

    	! ncpus(4)
    	! use_random_bootstrap_cpu(yes)

    	memory(128)	!  128 MB memory. This overrides
    			!  the default amount of memory for
    			!  this machine type.

    	! random_mem_contents(yes)

    	! prom_emulation(no)

    	! byte_order(big)    !  Normally set implicitly (because
    			     !  of type and subtype, or decided
    			     !  from the file loaded with load

    	load("netbsd-INSTALL")
    	bootname("netbsd")
    	bootarg("-a")

    	! n_gfx_cards(2)         !  for DECstation dual/tripple-head
    	! emulated_hz(10000000)  !  for fixing the emulated clock speed

    	! add_x11_display("otherbox:0")  !  for dual/tripple-head etc
    	! add_x11_display("thisbox:0")

    	{
    	    Devices can be added like this:

    	    device("8250 addr=0x18000800 addr_mult=4")

    	    The name comes first, followed by optional parameters.
    	    Remember to use 0x for hexadecimal values.
    	}

    	! force_netboot(yes)
    	! start_paused(yes)

    	! max_random_cycles(5)

    	disk("nbsd.img")
    	disk("6c:cdrom.iso")

    	use_x11(yes)
    	x11_scaledown(2)

    	! bintrans(disable)
    	! old_bintrans(enable)
    	! bintrans_size(24)

    	! slow_serial_interrupts_hack_for_linux(yes)

    	! debugger_on_badaddr(yes)

    	{
    	    Long comments spanning multiple lines should be surrounded
    	    with tuborg parentheses.

    	    {  Long comments can be nested.  }

    	}

        )

        !  Multiple machine are allowed.
        machine(
    	name("another machine")
    	type("hpcmips")
    	subtype("be300")

    	...
        )
    )

Starting the emulator with a configuration file is as simple as

    	$ gxemul @myconfig

if myconfig is the name of the configuration file.

### A minimal example:

Here is an example of what a minimal configuration file might look like:

    !!gxemul
    emul(
        machine(
            subtype("3max")
            load("netbsd-pmax-INSTALL-2.0")
        )
    )

For most machine types, `type` is needed. If only `subtype` is specified, and the name is unique (i.e. there is only one major type which has such a subtype), then the `type` can be omitted. Also, adding a `net` is quite useful, especially for netbooting kernels.

### Network across multiple hosts:

It is possible to add multiple `machine` entries into one configuration file. This will cause the emulator to try to run all those machines simultaneously. An alternative (and better) solution for doing this, which gives higher reliability (stability) and performance, is to have one configuration file per machine.

    !!gxemul
    !
    !  Configuration file for a
    !  "client" machine, netbooting
    !  of another machine.

    emul(
        net(
    	local_port(15000)
    	add_remote("localhost:15001")
        )
        machine(
    	name("client machine")
    	serial_nr(1)	!  10.0.0.1

    	type("sgi")
    	subtype("o2")
            load("netbsd-GENERIC32_IP3x.gz")
        )
    )

    !!gxemul
    !
    !  Configuration file for the
    !  "server" machine.
    !

    emul(
        net(
    	local_port(15001)
    	add_remote("localhost:15000")
        )
        machine(
    	name("nfs server")
    	serial_nr(2)	!  10.0.0.2

            type("dec")
            subtype("3max")
            disk("nbsd_pmax.img")
        )
    )

This example creates a network using the default settings (10.0.0.0/8), but it also allows the network to be connected to other emulator instances. `local_port(15000)` means that anything coming in to UDP port 15000 on the host is added to the network. All ethernet packets on the network are also sent out to all other connected machines (those added with `add_remote()`).

As you can see in the example, this is a configuration file for netbooting a NetBSD/sgimips diskless machine, with a NetBSD/pmax machine acting as the nfs server. Note that the nfs server has ports 15000 and 15001 reversed!

"`localhost`" can be changed to the Internet hostname of a remote machine, to run the simulation across a physical network.

NOTE: There is no error checking or security checking of any kind. All UDP packets arriving at the input port are added to the emulated ethernet. This is not very good of course; use this feature at your own risk.