GXemul:   Configuration files

Back to the index


Configuration files


Introduction:

GXemul can be started by entering machine settings directly on the command line, or by reading a configuration file (a "configuration script").

Configuration files in GXemul are useful/necessary for three reasons:

  1. It can be difficult to remember long command lines with lots of options.
  2. Some settings cannot be fully controlled on the command line. They can only be set using configuration files.
  3. Complex setups of multiple machines, or complex network setups, are not supported on the command line.


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:

  
!  This is an example configuration file for GXemul.
!  Anything following an exclamation mark (and also the exclamation
!  mark itself) is ignored.
!
!  Almost all settings are optional.

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 setting the emulated clock speed (mostly fake)

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

	{
	    Devices can be added like this:

	    device("ns16550 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)

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

	use_x11(yes)
	x11_scaledown(2)

	! slow_serial_interrupts_hack_for_linux(yes)

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

	    {  Long comments can be nested.  }

	}

)

!  Multiple machine definitions 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:

 
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.