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:

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:

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

Run the simulation

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