How to create a simulation ?

A simulation for the Java System Simulator is a folder containing at least a file called simulation.json. This file describes the simulated computer architecture. In addition, the same folder may contain supporting files, such as floppy disk images, hard disk images, paper tape files.

Structure of the simulation.json file

The simulation.json file is a regular JSON file. It contains three elements:

• the devices (cpu, memory, disk controllers, etc.) that form the simulated architecture, with their individual configuration options (including any disk images, preloaded ROMs, etc.);
• connections between the devices (memory mappings, I/O port mappings, control bus connections, etc.);
• simulation options (name, simulation speed, maximum simulation steps, etc.).

Devices

Devices are defined in the simulation.json file, inside an array of objects, with the key "devices". Each device object must have at least a "name", a "type", and a "configuration" field. The "type" field must clearly identify a valid JSS device. The "configuration" field is an array of configuration options, specific to the device. Device types and specific configuration options are available under JSS Devices. Configuration options that keep their default values may remain unspecified.

Example (this is only a fraction of a real simulation.json file; complete simulations are available here) :

{
	......
	"devices": [
		{
			"name":"ASR33",
			"type":"ASR33Teletype",
			"configuration":[
				{"key":"tape_in", "value":"write_tty.hex"}
			]
		},
		......
	],
	......
}

Device connections

Device connections are defined in the simulation.json file, inside an array of objects, with the key "connections". Each connection object must have at least a "type", a "src", and a "dev" field. The "type" field clearly identifies the connection type. The "src" field identifies the device to which the "dev" device is attached. From a programming perspective, internally the system will invoke the "type" method on the "src" object with the additional fields as parameters.

Example (this is only a fraction of a real simulation.json file; complete simulations are available here) :

{
	......
	"connections": [
		{"type":"attachDataDevice", "src":"MemoryBUS", "dev":"ROM", "start":59392,"end":61439,"offset":59392, "name":"bootrom", "enabled":true},
		{"type":"attachDataDevice", "src":"MemoryBUS", "dev":"ROM", "start":63488,"end":65535,"offset":59392, "name":"MonitorROM"},
		{"type":"attachToDataBus", "src":"CPU", "dev":"MemoryBUS"},
		......
	],
	......
}

Simulation options

Simulation options are defined in the simulation.json file as top level fields. Available options are:

• name - the simulation name;
• maximum_steps - specifies a number of steps after which the simulation will become automatically suspended. Default value is 0, disabling the automatic suspend;
• delay_between_steps_ms, delay_between_steps_ns - non-zero values will introduce a delay between simulation steps. This allows reducing the simulation speed and is useful to make it seem like real hardware, slower than the host machine;
• onCPUInvalidOpcodeException - specifies the system behaviour when an invalid CPU opcode is encountered. A value of "CONTINUE" will let the simulation continue, while a value of "SUSPEND" will automatically suspend the simulation.

Example (this is only a fraction of a real simulation.json file; complete simulations are available here) :

{
	"name":"MDS 80 booting CP/M 2.2",
	"maximum_steps":0,
	"delay_between_steps_ms":0,
	"delay_between_steps_ns":5000,
	"onCPUInvalidOpcodeException":"SUSPEND",

	"devices": [
		......
	],

	"connections": [
		......
	]
}

Hints

• Devices are initialized (including window creation) in the order they are written in the simulation.json file. If you want a certain device window to be on top when starting the simulation, place that device last in the "devices" object.
• Most numerical values in the simulation.json file can be expressed in decimal, hexadecimal, octal or binary. Decimal numbers should be written without quotes. Hexadecimal numbers may start with 0x, 0h, $0, or h and may end with h (examples: 0x3f0, 3f0h). Octal numbers may start with 0q, 0o, q, or o and may end with q or o (examples: 0q100, 100q). Binary numbers may start with 0b or 0y and may end with b or y (examples: 0b0011, 1101b).
• If there is an error while reading the simulation.json an exception will be thrown in the console. The simulation may remain in an undefined state (most likely not running).

Run the simulation

After creating a simulation, you should run it. If you don't know how, a short guide is available here.