Gavare's eXperimental Emulator:
Configuration files

Back to the index


Configuration files


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 emulated 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.