# GXemul: Configuration files

Back to the index.

- Introduction
- Configuration file syntax
- A minimal example

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

Note that from a performance perspective, it is best to just have one machine per configuration file, and run several GXemul instances concurrently (with one machine per instance). The two advantages to having more than one machine in a single configuration file are:

- the network `net ( )` is trivially shared between the specified machines, and
- breaking into the debugger will freeze all machines simultaneously.

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