Configuration Files
Introduction
Configuration files are used to keep all the parameters of an assembly of VMB devices in one central place. If possible, all devices that connect to the motherboard should read one and the same configuration file when starting. As a further convenience, the motherboard can be configured - using this same configuration file - to start all the devices that belong to the assembly, binging up (and later down) a consistent set of devices.
Parameters
In a configuration file, a parameter specification is given by a line that starts with the parameter name followed by one or more spaces (or tabs) and the value of the parameter. Parameter names are not case sensitive. Values are either numeric values, given either as decimal or hexadecimal numbers (e.g. 0xFF), or strings. String values extend from the first non blank character to the last non blank character of the line. Sometimes it is necessary to enclose string parameters in double quotes (for instance if it starts with a space).
As a rule, all paramters that can go in a configuration file can also be used on the command line using the parameter name as "long" options (prefixed with a minusminus) and vice versa.
Most "long" options, especially those that are used often,
are also available as short, single letter options (prefixed with a single minus). Short options are for use on the command line only, they dont work in configuration files. As an example, you can get a list of all parameters of a VMB device by starting it with the "-?" option (short) or the "--help" option (long).
As with any option, you could use the long otion "help" also in a configuration file - but obviously, in this case the option is intended for interactive use.
Using the Windows version, you can also select "Configuration" from the "Help" menu to get a Text windows displaying all parameters and their current settings.
Starting a Device
When a device is started, it does a quick check of its command line to find out if contains a configuration file either in the form "-c filename" or "--config filename". If either one is present, there is no further search for any other configuration file and the command line is used as described below. If the command line does not specify a configuration file, the current working directory is searched for a file named "default.vmb". If such a file exists, it is read. So you can keep all the files belonging to an assembly of devices in one directory and place the default configuration in this file. If there is no such file in the current working directory, the directory where the devices executable is located will be searched for a "default.vmb" file. If found, this file will be processed if not, no configuration file is processed.
After processing a possible "default.vmb" configuration file, the device will process the command line. This way, parameters specified on the command line take precedence over parameters specified in the default file. The parameters on the command line are processed form left to right,. Later parameters can overwrite settings by earlier parameters. This rule holds also for a configuration file specified on the comand line. Its content will overwrite paramters earlier on the command line (or in the file) and can be overwritten themselves by parameters later on the command line.
Typically, only the motherboard is started - either in Unix style from the command line or by a doubleclick. Under Windows, the installation program mentioned below will set a file association betwen ".vmb" files and the motherboard. So doubleclicking a configuration file will start the motherboard with this configuration file as command line parameter. All the rest of the devices that form the desired assembly are then started by the motherboard as specified in the configuration file (using the "exec" option).
Common Parameters
Most devices will need one of the following parameters:
General
- host
value: hostname or IP address of the host where the bus is located
short option: -h, long option: --host, default: localhost
- port
value: the port number where the bus is located
short option: -p, long option: --port, default: 9002
- address
value: the physical address where the resource is located
short option: -a, long option: --address, default: 0x8000000000000000
- size
value: size of address range in byte
short option: -s, long option: --size, default: 8
- interrupt
value: interrupt send by device
short option: -i, long option: --interrupt, default: 8
- disableinterrupt
to disable interrupts by this device
short option: -Q, long option: --disableinterrupt, default: false
User Interface
- x
value: the x position of the window
short option: -x, long option: --x , default: 0
- y
value: the y position of the window
short option: -y, long option: --y, default: 0
- minimized
start with a minimized window
short option: -m, long option: --minimized, default: false
Debugging
- debug
to switch on generation of debug output
short option: -d, long option: --debug, default: false
- verbose
to make debugging verbose; same as debugmask 0 (see below)
short option: -v, long option: --verbose, default: false
- debugmask
value: the debug mask
Each bit set in the debug mask switches off certain categories of debug messages. As a rule, low bits correspond to more important messages. The bits are:
- 0x01 Fatal Errors
- 0x02 Errors
- 0x04 Warnings
- 0x08 Notification (unusual events that normaly do not occur)
- 0x10 Progress (usual events the normaly occur and trace the working of a device)
- 0x20 Info (more detailed reports on the workings of a device)
- 0x40 Message (trace the exchange of messages over the bus)
- 0x80 Payload (display the content of the payload transported over the bus)
You can OR together these bits to suppress the debug messages you do not want to see. The default value is a good choice for a program unter test but without any specific hint about malfunction.
short option: -M long option: --debugmask, default : 0xFFF0
- help
to print usage and configuration information
short option: -?, long option: --help
Configuration
- define
value: the device name for conditionals (see below). Note: if the device name is the first item on the command line after the program name, you can omit the "-D" or the "--define". Just puting the device name first is sufficient.
short option: -D, long option: --define, default: the programs name
- config
value: filename for a configuration file
short option: -c, long option: --config, default: none
Executing Commands
- exec
value: the command line of the command to be executed. This parameter is for use by the motherboard, but in the future, other devices might have the need to start auxiliar devices using the exec parameter. If the parameter value does not give the program to be executed with an absolute path name, the motherboard will try to find the program first in the current working directory, then in the same directory where the motherboard executable resides, and finally on the system path. This mechanism together with configuration file variables (as explained below) should enable you to write configurations that start whole assemblies with a doubleclick and still can be moved around in the directory tree.
short option: -X, long option: --exec, default: none
Conditionals
Looking at the list of parameters and the intended use in a central configuration file, you might wonder how to specify the address of a device in a file that is shared by all the devices in an assembly. The answer is: by designating parts of the configuration file for specific devices using a conditional.
A conditional has the simple form:
#if devicename
...
#endif
When a device reads a configuration file and it encounters a conditional, it will check its device name against the devicename given in the conditional. If the names are equal it will continue to process the input. If the names are not equal it will simply skip over the input until it finds the #endif. By default, the name of a device it the name of the program. So a section like
#if ram
address 0x10000000
size 0x400000
#endif
will apply to the ram device, giving 4MB Ram at address 0x100000000. If you have two ram modules as part of your assembly, you can use --define highram or -D highram on the command line when starting the second ram device and the configuration file then contains this:
#if ram
address 0x10000000
size 0x400000
#endif
#if highram
address 0x80000000
size 0x400000
#endif
Comments
When configuration files get more and mor complex, it is a good idea to sprinkle in some comments. Do do so, just begin a line with a hashmark #, then the rest of the whole line will be ignored.
Variables
Currently, configuration files know only two variables: #FILE# and #PATH#. Any occurence on the sting #FILE# in a parameter value will be replaced by the full absolute filename of the configuration file itself; any occurrence of #PATH# will be replaced by the full absolute path (including the last "/" or "\" character) of the configuration file. A typical use of such a variable is
exec rom -c "#FILE#"
here the motherboard will start the rom device with the same configuration file by explicitely specifying it on the devices command line. Note the double qoutes. Especially under Windows, filenames often contain spaces. Without the double quotes, the -c option would only take the first part of the string #FILE'#, up to the first space as argument value. An other example is:
#if rom
address 0x0
file "#PATH#linux/vmlinux.img"
#endif
Here the rom device gets the rom image vmlinux.img from the linux subdirectory of the directory that contains the configuration file.