5 JPC-RR is licenced under GNU GPL v2. See file “LICENSE”
11 To get started, you need BIOS image, VGABIOS image and DOS boot
12 floppy and JDK for Java 6 standard edition (later versions should
13 they appear should also work). Note: JRE is not enough. These
14 four are not included due to licencing and size issues.
16 Working versions of first tree can be obtained from original JPC
17 source package. The fourth can be downloaded from Sun or
18 installed from package manager.
20 Working versions of BIOS/VGABIOS (diffrent versions) can also be
21 obtained from Debian GNU/Linux by ripping them out of certain
22 packages. But using these is not recommended. Also, DOS boot
23 floppy can be obtained from ODIN.
25 Note that to play back recorded movies, you need exact same
26 version of BIOS image, VGABIOS image and DOS boot floppy as was
27 used when making the movie.
29 See compile.sh. The stuff in streamtools is only needed for
34 See compile.sh. The streamtools stuff is only needed for dumping
39 First you need to get and make some important images. Obtain BIOS
40 image, VGABIOS image and DOS boot floppy from somewhere and do:
44 java ImageMaker --BIOS library/BIOS <bios image file>
46 java ImageMaker --BIOS library/VGABIOS <vgabios image file>
48 java ImageMaker --floppy1440 library/DOSfloppy <dos floppy name>
50 This makes loadable images out of what you obtained. Most DOS
51 boot floppies are 1440KiB in size (if yours isn't change that
52 floppy1440 part). You also might want to make some game images:
54 java ImageMaker --HDD=128,63,16 library/somegame <game
55 installation directory>
57 This makes ~128MB HDD image out of installation directory.
61 There is premade autoexec script called assemble.bat that has
62 fairly reasonable defaults. To use it:
64 java JPCApplication -library library -autoexec assemble.bat
66 The “-library library” specifies that contents of directory
67 'library' are to be used as library. The script pops up settings
68 for new emulated PC (if you want to load savestate, click
69 cancel). Select BIOS and VGABIOS for BIOS and VGABIOS image (they
70 should be already selected), DOSfloppy for fda (boot device
71 should be set to fda) and game image as some HD drive
75 • Putting the game as hdd causes boot to be bit faster.
77 • Some BIOS versions have “press F12 to select boot device”. Hit
78 <enter> from emulated keyboard and that prompt will go away in
79 about half emulated second (it stays several emulated seconds
82 • If game doesn't need lots of memory, hitting F5 to skip
83 intialization files is fastest. If it does need more memory,
84 run config.sys commands but not autoexec.bat.
86 • Some DOS disks have DOSIDLE with them, don't use it as it
87 messes badly with emulator.
89 3 Making JPC-RR format images from raw images
91 Due to various factors, JPC-RR can't use raw image files directly
92 but requires its own image format. There is tool called
93 ImageMaker that can make JPC-RR images from raw images. Each
94 image has format, ID an name. Format and name are specified when
95 making image. ID is automatically calculated from format and
96 contents. Name does not affect the ID but is purely for convience
97 so one doesn't have to specify long image IDs manually.
101 The syntax for ImageMaker when making images is:
103 $ java ImageMaker <format> [<options>...] <destination> <source>
106 <destination> is file name for JPC-RR format image to write.
107 <source> is either name of regular file (raw image file) or name
108 of directory tree with files (supported for making floppy or hard
109 disk images only). In case of directory tree, the files are
110 layout deterministically to disk, so the ID will always be the
111 same for given geometry and type. <name> is name to give to disk.
114 --BIOS BIOS image (note: VGABIOS is also of this type).
116 --CDROM CD-ROM image.
118 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
120 --floppy=tracks,sectors,sides Floppy disk with specified
123 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
125 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
127 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
129 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
131 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
133 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
135 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
137 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
139 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
141 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
143 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
145 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double
148 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double
151 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double
154 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double
157 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double
160 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double
163 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double
166 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double
169 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double
172 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double
175 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double
178 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double
181 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double
184 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double
187 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double
190 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double
193 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double
196 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double
201 • If making image from directory, the names of the files must
202 conform to FAT naming restrictions (8+3 character names, no
203 spaces, etc). Avoid filenames with non-ASCII characters.
205 • The DOS limit of 112 or 224 files for floppies does not apply
206 to images created from directory trees. The minimum limit value
207 used is 512. If even that isn't enough, the limit is
208 automatically increased to fit all the needed directory
211 • Making boot disks from tree does NOT work. Even if you got
212 system boot files there, it still won't work.
214 • Only floppy disks and hard drives can be made from directory
215 trees. BIOS images and CDROM images require image file.
217 • Avoid floppies with custom geometry (floppy geometry does
218 affect disk ID). Disks with over 63 sectors per track don't
219 work with DOS. Wheither disks with over 127 tracks per side
220 work with DOS is unknown. Also avoid 1024-tracks per side HDDs.
222 • The geometry limits are: 2-1024 tracks per side for HDD, 1-256
223 tracks per side for floppy. 1-63 sectors per track for HDD,
224 1-255 sectors per track for floppy. 1-16 sides for HDD, 1 or 2
225 sides for floppy. This gives size limit of 65280KiB for floppy
226 disks (but note the DOS limit!) and 516096KiB for HDDs.
228 • There are multiple image file contents that represent the same
229 image. The one with smallest size is picked when creating
232 • Note: Although the IDs are 128 bits long, they are not MD5
237 --volumelabel=label Give specified volume label (affects ID).
238 Only meaningful when making image out of directory tree. Default
241 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files
242 (affects ID). Only meaningful when making image out of directory
243 tree. The default timestamp is 19900101T000000Z.
245 3.4 Image information
249 $ java ImageMaker <imagefile>
251 Variety of information about image is displayed (especially for
252 floppies/HDDs). Two important fields are calculated and claimed
253 disk ID. They should be the same. If they are not, then the image
254 file is corrupt (sadly, imagemaker has bugs and bugs that cause
255 it to write corrupt images have been seen).
257 3.5 Advanced: The disk ID algorithm
259 The disk ID is calculated as:
261 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
263 Where Skein-256-128-deprecated is Skein hash function with
264 256-bit internal state and 128-bit output using the deprecated
265 rotation constants (as specified in Skein hash function reference
266 documentation versions 1.0 and 1.1). The <image> is the whole
267 image, including parts not stored in image file. The reason for
268 keeping using the deprecated constants are:
270 • Changing the constants would change the IDs, which would
271 invalidate existing images
273 • This is not about cryptographic security
275 • The new constants don't improve security that much anyway.
277 3.5.1 Floppies and HDDs
279 Floppies have <typecode> value 0 (single byte) and HDDs have 1
280 (single byte). <geometry> is as follows (this is exactly the same
281 form as it appears in image header):
283 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
285 Byte 0 bits 2-5: Head count - 1.
287 Byte 0 bits 6-7: Reserved, must be 0.
289 Byte 1: Bits 0-7 of track count per side - 1.
291 Byte 2: Sector count per track - 1.
293 3.5.2 CD-ROM and BIOS images
295 CD-ROMs have <typecode> value 2 (single byte) and BIOS images
296 have 3 (single byte). <geometry> is blank.
298 3.6 Advanced: Disk Image format
300 The disk image consists of following parts:
312 • type-specific geometry/size data
318 Magic in disk image files is following 5 bytes: “IMAGE”
322 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
326 Type code is single byte. 0 for floppies, 1 for HDDs, 2 for
327 CD-ROMs and 3 for BIOS images. Other values are reserved.
331 Disk comment length is given as two-byte big-endian value. New
332 images should have 0 here.
336 Ignored. Comment field is there for backward compatiblity.
337 Comment length gives length of this field in bytes.
339 3.6.6 Type-specific geometry/size data (floppies and HDDs)
341 Floppies and HDDs have 3-byte geometry data:
343 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
345 Byte 0 bits 2-5: Head count - 1.
347 Byte 0 bits 6-7: Reserved, must be 0.
349 Byte 1: Bits 0-7 of track count per side - 1.
351 Byte 2: Sector count per track - 1.
353 3.6.7 Type specific-geometry/size data (CD-ROMs)
355 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
357 3.6.8 Type specific-geometry/size data (BIOS images)
359 BIOS images have 4-byte big-endian byte (not sector or block)
362 3.6.9 Actual image data (floppy/HDD)
364 Floppy or HDD imagedata consists of following subparts:
374 Storage method is single byte. Sectors present gives number of
375 last nonzero sector + 1 (zero if image is all zeroes)
377 3.6.10 Floppy/HDD storage method 0: Raw storage
379 This storage method has empty header. Image data is raw dump of
380 first sectors present sectors.
382 3.6.11 Floppy/HDD storage method 1: Sectormap
384 Image data header contains bitfield with just enough bytes to
385 have one bit per present sector. The order of bits is such that
386 number of bit corresponding to each sector in byte is sector
387 number modulo 8 and byte number is floor of sector number divided
388 by 8 when sector numbers are counted from zero. If bit
389 corresponding to sector is set, then the sector is present in
390 image data, otherwise it is absent and assumed to be all-zeroes.
392 Image data contains dumps of all present sectors in order of
393 increasing sector number.
395 3.6.12 Floppy/HDD storage method 2: Extent first sector zero
397 Image data is empty as storage-specific data is mangled with
398 image data. The image data alternates between blocks encoding
399 zero sectors and blocks encoding nonzero sectors. The first block
400 encodes zero sectors.
402 Block encoding zero sectors consist of single 1-4 byte
403 little-endian value encoding number of sectors in block - 1.
404 Number of bytes is determined by sectors present value. It is 1
405 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
406 for more than 16777216. All sectors in block are filled with
407 zeroes and are not stored.
409 Block encoding nonzero sectors has same block count as zero
410 sector block but is followed by the sectors stored raw.
412 3.6.13 Floppy/HDD storage method 3: Extent first sector nonzero
414 Same as storage method 2 but first block is nonzero sector block.
416 3.6.14 Actual image data (CD-ROMs and BIOS images)
418 These store image data raw. The amount of data is specified by
423 4.1 org.jpc.utils.RAWToPNG
427 $ java org.jpc.utils.RAWToPNG <input> <outputprefix>
429 Reads RAW video data from <input> (may be named pipe) and dumps
430 PNG frames received as '<outputprefix><runningcount>.png'. Also
431 saves '<outputprefix>.timing' which contains frame timing data
432 (each line consists of time in nanoseconds, space, and filename).
434 5 The actual emulator
436 The actual emulator is invoked as:
438 $ java JPCApplication <options>...
440 The valid options are:
442 -library <library> Use the specified directory when searching for
443 images (can only be specified once).
445 -autoexec <script> Execute contents of specified file as commands
450 When emulator is started, command line comes up. Following
453 • 'exit': exit immediately
455 • 'load <plugin>': Load plugin (no arguments)
457 • 'load <plugin>(<arguments>)': load plugin with arguments.
459 • 'command <command> [<arguments>...]': Invoke command via
460 external command interface.
462 When one gets command line, its useful to load some plugins. See
463 section about plugins. Note: Load runner plugin
464 (PCControl/PCRunner and so) last, as some runners like to start
467 5.2 PC settings dialog notes
469 • CPU divider base frequency before division is 1GHz.
471 • Images can be specified by name or by ID. Name is relative to
472 library directory. If the image is in subdirectory of image
473 directory, the directory separator is is '/' regardless of what
476 • CD-ROM and hdc are mutually exclusive
478 • Modules is comma-seperated list of modules to load. To pass
479 arguments to some modules, enclose the arguments in (). Same
480 module can be specified twice only if parameters differ.
482 • FPU emulator is specified by class name. If core has built-in
483 FPU emulator, then this should be left blank. Without
484 core-builtin FPU emulator, blank value means “no fpu”.
486 • Setting boot device doesn't work with some BIOS versions. Those
487 versions prompt the boot device anyway.
489 5.3 Audio output channels
491 PC can have one or more audio output channels. The name of audio
492 output associated with PC speaker is:
493 'org.jpc.emulator.peripheral.PCSpeaker-0'. Modules that have
494 audio outputs get channel names of form <classname>-<sequential>,
495 where <classname> is name of main module class and sequential is
496 number starting from zero. Note that same module can have
497 multiple output channels. If multiple modules of same class
498 request audio outputs, the <sequential> values of subsequent
499 module start where previous left off.
503 Plugins actually execute the tasks of the emulator. They can be
504 loaded using “load <plugin>” or 'load <plugin>(<arguments>)” from
507 Different Plugins using the same output (like running PCMonitor
508 and PNGDumper) should not conflict because connector output hold
509 locking is desinged to handle multiple readers.
511 If no plugin used requires GUI, then the emulator can be run
512 without having GUI available.
514 5.4.1 plugin: org.jpc.plugins.PCControl
516 No arguments, requires and uses GUI.
518 Runs the PC emulator core. Has capability to start/stop
519 emulation, breakpoint after certain time or start/end of VGA
520 vertical retrace. Also can create, savestate and loadstate PC
521 emulation. Memory dumping is supported.
523 5.4.2 plugin: org.jpc.plugins.PCRunner
525 Takes name of savestate or movie as argument. Does not require
528 Loads PC from savestate and just runs it. CTRL+C to quit.
530 5.4.3 plugin: org.jpc.plugins.PCMonitor
532 No arguments, requires and uses GUI.
534 VGA monitor for emulated PC.
536 5.4.4 plugin: org.jpc.plugins.VirtualKeyboard
538 No arguments, requires and uses GUI.
540 On-screen keyboard for emulated PC.
542 5.4.5 plugin: org.jpc.plugins.PCStartStopTest
544 No arguments, requires and uses GUI.
546 Small plugin testing remote PC start/stop. Also supports sending
547 some common keypresses.
549 5.4.6 plugin: org.jpc.plugins.RAWVideoDumper
551 Takes 'rawoutput=<file>' as argument. Does not require nor use
554 Dumps all generated frames to RAW file <file>. Rawoutput is
555 required. The raw file consists of concatenation of zlib streams.
556 The uncompressed stream is concatenation of time skips (FFh FFh
557 FFh FFh), each acting as time offset of 2^32-1 nanoseconds and
558 saved frames. The saved frame has time offset in nanoseconds (big
559 endian) as first four bytes (must be at most 2^32-2, as 2^32-1 is
560 reserved for time skip). The next two bytes are big-endian width,
561 next two big-endian height. Finally frame has 4 * width * height
562 bytes of data that encodes pixels using 4 bytes per pixel, in
563 left-to-right, up-to-down order. Byte 0 of each pixel is
564 reserved, byte 1 is the red channel, byte 2 is green channel and
565 byte 3 is blue channel.
567 Dumping to pipe is supported.
569 5.4.7 plugin: org.jpc.plugins.RAWAudioDumper
571 Takes 'src=<name of audio output channel>',
572 'file=<output-filename>' and 'offset=<offset>' as arguments,
573 separated by ','. Does not require nor use GUI.
575 Dumps output from specified audio output channel (src, mandatory)
576 to RAW-format file (file, mandatory). The resulting file consists
577 of records, 8 bytes each. Each record has three fields. First 4
578 byte unsinged little endian timedelta value (in nanoseconds),
579 then 2 byte unsigned little endian new left channel volume, then
580 2 byte unsigned little endian new right channel volume.
581 Optionally 'offset' can be set to positive value (in nanoseconds)
582 to delay the audio by.
584 6 Some error messages and explanations
586 • <filename> is Not a valid image file
588 • <filename> is not image file
590 • <filename> claims to be floppy with illegal geometry: <x>
591 tracks, <y> sides and <z> sectors.
593 • <filename> claims to be HDD with illegal geometry: <x> tracks,
594 <y> sides and <z> sectors.
596 • Can't read disk image sector map.
598 • Can't read disk image extent.
600 Code expects <filename> to be valid JPC-RR format image, but it
601 isn't JPC-RR image at all or its corrupt.
603 • <filename> is image of unknown type.
605 • <filename> has unrecognized geometry <x> <y> <z>
607 Possibly corrupt image, not JPC-RR image, or JPC-RR image from
608 future version containing something current version can't
611 • Invalid format specifier <something>.
613 • Invalid syntax of --floppy= or --HDD= option.
615 • Invalid format specifier/option <something>.
617 Invalid option or format specifier was given. Check for typos.
619 • java ImageMaker [<options>...] <format> <destination> <source>
622 Check syntax of command. Especially that diskname is present!
624 • The image has <nnn> sectors while it should have <yyy>
625 according to selected geometry.
627 • Raw image file length not divisible by 512.
629 • Trying to read sector out of range.
631 The selected geometry is wrong or raw image is incomplete.
633 • Invalid disk name (Should not happen!).
635 • Invalid geometry to be written.
637 This is a very likely a bug in program.
639 • What the heck <filename> is? It's not regular file nor
642 That sort of file can't be used as input for image making, or the
643 file just doesn't exist.
645 • BIOS images can only be made out of regular files.
647 • CD images can only be made out of regular files.
649 Source image specified is not regular file, but image of that
650 type can't be made of anything else.
652 • Can't read raw bios image file.
654 • Can't read sector <nnn> from image.
656 Reading the raw image file failed for some reason.
658 • Bad library line: "<something>". Ignored.
660 Syntax error in image library.
662 • Removing image <something> a.k.a. "<something>" as it no longer
665 The image file no longer exists so it gets removed from library.
667 • Removing image <something> a.k.a. "<something>" due to <some>
670 Image library code killed some image from library due to some
671 kind of conflict with image being added.
673 • Too much data to fit into given space.
675 The tree you gave contains takes just too much space to fit into
678 7 Advanced: Savestate/movie format
682 JRSR archive format packs multiple text archive members to text
683 archive. It does not support binary members. JRSR archives have
684 first five bytes form the magic. It is “JRSR” followed by
685 LINEFEED character (0x0A, 0x0D, 0x0D 0x0A, 0xC2 0x85). There are
686 three kinds of lines after that (lines are terminated by LINEFEED
695 Sequencing rules are as follows: Start member is allowed
696 anywhere. Member line is allowed only inside member (member
697 started but not ended). End member is only allowed inside member.
698 End of file is only allowed outside member. Note that those three
699 are all the kinds of lines allowed.
703 Start member line is given as “!BEGIN” <SPACE> <membername>
704 <LINEFEED>. <SPACE> is SPACE character (only one!, 0x20) and
705 <LINEFEED> is LINEFEED chacter. Multiple <SPACE>s would mean
706 member with name beginning with <SPACE>. The member name is UTF-8
707 encoded and maximum allowed length is 1024 bytes (256-1024
708 codepoints). Starting member inside another implicitly ends the
713 Member line is given as “+”<content><LINEFEED>. It gives another
714 line for member contents. <content> is passed raw to layers
719 End member line is given as “!END”<LINEFEED>. It ends the current
720 member. The following line can only be start member line or file
723 7.2 Four-to-Five encoding
725 Binary members are encoded into text by so-called four-to-five
726 encoding. This encoding can encode single byte to two, two bytes
727 to three, three bytes to four and four bytes to five.
728 Four-to-five encoding has five kinds of blocks. All SPACE and
729 CHARACTER TABULATION characters are completely ignored, even in
732 7.2.1 End stream block
734 End stream block is encoded as '!'. It ends the stream instantly.
735 There is also implicit end of stream at end of input to decoding.
737 7.2.2 Other four block types
739 Other four block types take the value to be encoded, read it as
740 big-endian value. Then they write it as base-93 big-endian value.
741 Then length specific constants are added to digits of that number
742 to yield ASCII values for characters (those are stored in order):
745 +------------+------------+------------+------------+------------+-----------+
746 | To encode | 1st char. | 2nd char. | 3rd char. | 4th char. | 5th char. |
747 +------------+------------+------------+------------+------------+-----------+
748 +------------+------------+------------+------------+------------+-----------+
749 | 1 byte | 34 | 34 | - | - | - |
750 +------------+------------+------------+------------+------------+-----------+
751 | 2 bytes | 37 | 34 | 34 | - | - |
752 +------------+------------+------------+------------+------------+-----------+
753 | 3 bytes | 45 | 34 | 34 | 34 | - |
754 +------------+------------+------------+------------+------------+-----------+
755 | 4 bytes | 66 | 34 | 34 | 34 | 34 |
756 +------------+------------+------------+------------+------------+-----------+
759 Blocks which encode values greater than what is possible for
760 value of that length are fatal errors.
764 UTF-8 encoding is used to encode lines of Unicode codepoints into
767 7.4 Line component encoing
769 Line component encoding sits on top of UTF-8 encoding. Line
770 component encoding encodes non-empty 1-D array of non-empty
771 strings into line, and thus array of those into member. Empty
772 lines or lines that don't contain any components are ignored.
773 Line starts with depth value of 0 and must end with depth value
776 Components are seperated by component separators. Empty
777 components are ignored. Following codepoints are separators on
778 depth 0 if not escaped:
780 • Codepoint of '('. The depth is read pre-increment.
782 • Codepoint of ')'. The depth is read post-decrement.
784 • Codepoints 0x20, and 0x09.
786 • Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
788 • Codepoints 0x2000-0x200A.
790 The following characters are special:
792 • '('. Increments depth by 1 if not escaped (and appears in
795 • ')'. Decrements depth by 1 if not escaped (and appears in
796 component). Depth going negative is an error.
798 • '\'. Next character is interpretted as literal. Error if at end
801 Otherwise, characters are interpretted as literals and appear in
802 components. Depth must be zero at end of line.
806 Header section is in archive member "header". It uses line
807 component encoding. The first component of each line is name of
808 header, and subsequent ones are arguments. How many parameters
809 are expected is dependent on what header it is:
811 7.5.1 PROJECTID header:
813 • Header name: "PROJECTID"
817 • Argument #1: <project-id-string>
821 Gives project ID. Project ID is generated when PC is assembled
822 and is then preserved in save states. It is used for computing
823 rerecord counts. Emulator treats it as opaque string, the IDs it
824 generates are formed by 48 random hexadecimal digits.
826 7.5.2 SAVESTATEID header:
828 • Header name: "SAVESTATEID"
832 • Argument #1: <savestate-id-string>
836 Gives save state ID. Each save state has its own save state ID.
837 Treated as opaque string, but generated as 48 random hexadecimal
838 digits. The presence of this header signals whether there is save
839 state to be loaded. If this header is present, save state load
840 will be attempted. If absent, save state is not to be loaded even
841 if present (and correct savestate load would be technically
844 The value is used to prevent loading incompatible save states in
845 preserve event stream mode and also to find the point in event
846 stream where one left off.
848 7.5.3 RERECORDS header:
850 • Header name: "RERECORDS"
854 • Argument #1: <rerecords>
858 Gives rerecord count. PC assembly (except when loading save
859 state) initializes current rerecord count to zero. Must be
860 non-negative and decimal number using ASCII digit characters.
862 On loading save state:
864 1) If project ID matches with previous:
866 1a) If loaded rerecord count is larger or equal to current
869 1a-a) Current rerecord count is loaded rerecord count + 1.
873 1b-a) Current rerecord count increments by 1.
877 2a) Current rerecord count is loaded rerecord count + 1.
879 The current rerecord count at time of save is saved to save
882 7.5.4 AUTHORS header:
884 • Header name: "AUTHORS"
886 • Components: 2 or more
888 • Arguments: free form
892 Gives authors of run. Each argument gives one author. May be
893 present multiple times.
895 7.5.5 COMMENT header:
897 • Header name: "COMMENT"
899 • Components: 2 or more
901 • Arguments: free form
905 Various kinds of free form data. Not parsed further by emulator.
907 7.6 Initialization segment:
909 If SAVESTATEID header isn't present (not a save state), member
910 "initialization" gives PC initialization parameters for
911 assembling the PC. It is present anyway even if SAVESTATEID is
914 Following parameters are used (space separates components):
918 Gives Image ID of main system BIOS (mandatory)
922 Gives Image ID of VGA BIOS (mandatory).
926 Gives Image ID of hda. Present only if system has hard disk hda.
930 Gives Image ID of hdb. Present only if system has hard disk hdb.
934 Gives Image ID of hdc. Present only if system has hard disk hdc.
938 Gives Image ID of hdd. Present only if system has hard disk hdd.
942 Gives Image ID of disk in slot <num>. Slot number must be
945 “DISKNAME” <num> <name>
947 Gives image name of disk in slot <num>. Slot number must be
948 non-negative. The slot must be previously declared using “DISK”.
952 Gives Image slot to initially put into floppy drive fda. Disk
953 must be of floppy type. If none present, no disk is initially put
958 Gives Image slot to initially put into floppy drive fdb. Disk
959 must be of floppy type. If none present, no disk is initially put
964 Gives Image slot to initially put into CD-ROM drive hdc. Not
965 allowed if hard disk hdc is present. Disk must be of CD-ROM type.
966 If none present no disk is initially put there.
970 Number of milliseconds since Unix epoch to system start up time.
973 0-4102444799999. Mandatory.
975 "CPUDIVIDER" <divider>
977 Set CPU frequency divider (dividing the 1GHz master clock).
978 Allowed range is 1-256. Mandatory.
982 Number of 4KiB pages of RAM memory. Allowed range 256-262144.
987 Set boot device. Valid devices are "FLOPPY" (boot from fda),
988 "HDD" (boot from hda) and "CDROM" (boot from CD).
990 "LOADMODULEA" <module> <parameters>
992 Load module <module> with parameters <parameters>.
994 "LOADMODULE" <module>
996 Load module <module> with no parameters
1000 Use class <fpu> as FPU emulator.
1002 7.7 Event record format:
1004 Event record is in archive member "events". It uses line
1005 component encoding. Each line gives an event. First component of
1006 each line gives time stamp. These timestamps MUST be in
1007 increasing order and all MUST be non-negative. Time stamp time
1008 unit is exactly 1 nanosecond of emulated time.
1010 The second component of each line is name of class to dispatch
1011 to. Further components are passed as-is to event handlers.
1012 "Class" name "SAVESTATE" is special. This takes one or two
1013 additional components, first of which gives the save state ID of
1014 save state that occurred there. The save state IDs MUST be unique
1015 in entire event stream. The second argument to savestate (if
1016 present) is rerecord count at time of saving that savestate
1017 (useful for calulating rerecord count of movie starting from
1020 7.7.1 Keyboard keypress/keyrelease event:
1022 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1024 • Argument #1: Fixed: "KEYEDGE"
1026 • Argument #2: Key number. Valid values are 1-83, 85-95, 129-197
1029 Send key press or key release. Keys work in toggle button manner.
1030 The event time must be multiple of 66 666, and must not be less
1031 than 60 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs
1032 after last KEYEDGE on key >128 and 10 * 66 666 TUs after last
1033 KEYEDGE on key <128.
1037 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1039 • Argument #1: Fixed: "PAUSE"
1041 Send pause key event. The time restrictions are identical to
1046 • Dispatch to: org.jpc.emulator.PC$ResetButton
1052 7.7.4 Fda disk change:
1054 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1056 • Argument #1: Fixed: "FDA"
1058 • Argument #2: Number of image slot to put there.
1060 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1061 used if there is no disk in floppy drive A. This event causes
1062 specified disk to be placed to FDA or FDA disk to be ejected with
1063 no replacement if disk number is -1. The specified disk if not -1
1064 must be of floppy type. The specified disk if valid must not be
1067 7.7.5 Fdb disk change:
1069 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1071 • Argument #1: Fixed: "FDB"
1073 • Argument #2: Number of image slot to put there.
1075 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1076 used if there is no disk in floppy drive B. This event causes
1077 specified disk to be placed to FDB or FDB disk to be ejected with
1078 no replacement if disk number is -1. The specified disk if not -1
1079 must be of floppy type. The specified disk if valid must not be
1084 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1086 • Argument #1: Fixed: "CDROM"
1088 • Argument #2: Number of image slot to put there.
1090 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1091 used if there is no disk in CD-ROM. This event causes specified
1092 disk to be placed to CD-ROM or CD-ROM disk to be ejected with no
1093 replacement if disk number is -1. The specified disk if not -1
1094 must be of CD-ROM type.
1096 This event has no effect if CD-ROM is locked.
1098 7.7.7 Write protect floppy:
1100 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1102 • Argument #1: Fixed: "WRITEPROTECT"
1104 • Argument #2: Number of image slot to manipulate
1106 Write protects specified disk. The disk MUST NOT be in any drive
1107 and MUST be valid floppy-type disk.
1109 7.7.8 Write unprotect floppy:
1111 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1113 • Argument #1: Fixed: "WRITEUNPROTECT"
1115 • Argument #2: Number of image slot to manipulate
1117 Disables write protection specified disk. The disk MUST NOT be in
1118 any drive and MUST be valid floppy-type disk.
1122 Actual savestate format is not documented here. It is close to
1123 impossible to comprehend without access to emulator source
1126 8 Advanced: Making class dumpable
1128 Class is made dumpable by implementing interface
1129 org.jpc.emulator.SRDumpable and implementing method
1130 dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
1131 <init>(org.jpc.emulator.SRLoader). Non-static inner classes can
1132 not be dumpable (make them static using tricks similar to what
1135 If dumped class has dumpable superclass, the first thing dumping
1136 function needs to do is to call dumper function of superclass and
1137 first thing loading constructor needs to do is to call loading
1138 constructor of superclass. If class has no dumpable superclass,
1139 dumper doesn't need to do anything special, while loader needs to
1140 call objectCreated(this) on SRLoader object passed as parameter.
1142 Following these fixed parts, dump all members that are part of
1143 mutable state in emulator core.
1145 8.1 Member dumping/loading functions
1147 There is dumping/loading function for following (all functions
1148 dumping/loading reference types can handle null):
1150 • boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
1152 • byte: SRDumper.dumpByte, SRLoader.loadByte
1154 • short: SRDumper.dumpShort, SRLoader.loadShort
1156 • int: SRDumper.dumpInt, SRLoader.loadInt
1158 • long: SRDumper.dumpLong, SRLoader.loadLong
1160 • String: SRDumper.dumpString, SRLoader.loadString
1162 • boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
1164 • byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
1166 • short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
1168 • int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
1170 • long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
1172 • double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
1174 • <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
1176 • special object: SRDumper.specialObject, SRLoader.specialObject
1180 • Dumpable objects come out as type of
1181 org.jpc.emulator.SRDumpable.
1183 • Special objects are various static objects that don't need to
1184 be stored because they don't have mutable fields.
1186 • Don't dump fields related to event state feedback.
1188 • Don't dump temporary flags that are only used while PC is
1189 running. Savestate when PC is running isn't possible anyway.
1191 • Some connectors dump fields related to connector output, some
1194 9 Advanced: Making output connectors
1196 Implementing interface org.jpc.emulator.DisplayController signals
1197 that this is display controller, inhibiting loading of the
1198 standard VGA display controller if loaded as module.
1200 9.1 Interface org.jpc.emulator.OutputConnector
1202 Class is made to be output connector by implementing this
1203 interface. This interface specifies the methods used for output
1204 hold locking. Class org.jpc.emulator.OutputConnectorLocking has
1205 implementations of these that are suitable for calling.
1207 9.1.1 Method subscribeOutput(Object)
1209 Subscribes the output, with specified object as handle.
1211 9.1.2 Method unsubscribeOutput(Object)
1213 Unsubscribe the specified handle object from output.
1215 9.1.3 Method waitOutput(Object)
1217 Wait for output on specified connector using specified handle
1218 object. Returns true on success, false if wait was interrupted by
1219 thread interrupt. Blocking.
1221 9.1.4 Method releaseOutput(Object)
1223 Release connector from p.o.v. of given handle. Does not block.
1225 9.1.5 Method holdOutput()
1227 Release threads waiting on waitOutput() and block until all
1228 subscribers have returned from waitOutput() and enteired
1231 9.1.6 Method releaseOutputWaitAll(object)
1233 Like releaseOutput(), but waits until all handles have released
1236 9.2 Class org.jpc.emulator.VGADigtalOut
1238 Class org.jpc.emulator.VGADigtalOut (already implements
1239 OutputConnector) implements VGA output connector. If module
1240 provodes output connector, it needs to implement
1241 org.jpc.emulator.DisplayController.
1243 9.2.1 Method getWidth()
1245 Get width of display (watch out, can return 0).
1247 9.2.2 Method getHeight()
1249 Get height of display (watch out, can return 0).
1251 9.2.3 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(),
1254 Returns the dirty region (region modified since last output).
1256 9.2.4 Method getBuffer()
1258 Get buffer of ints, at least width * height elements
1259 (left-to-right, top-down, one value per pixel) giving pixel data.
1260 Value for each pixel is 65536 * <red-component> + 256 *
1261 <green-component> + <blue-component>.
1263 9.2.5 Method resizeDisplay(int _width, int _height)
1265 Resize the display to be of specified size.
1267 9.2.6 Method dirtyDisplayRegion(int x, int y, int w, int h)
1269 Mark the specified region as dirty.
1271 9.2.7 Method resetDirtyRegion()
1273 Resets the dirty region to be empty.
1275 9.3 Class org.jpc.emulator.PC method getVideoOutput()
1277 Get VGA output connector for PC.
1279 9.4 Interface org.jpc.emulator.DisplayController.
1281 Implementing this class signals that module is VGA controller.
1282 There can be only one such module active at time and presence of
1283 such module prevents loading builtin VGA controller emulation
1286 9.4.1 Method getOutputDevice()
1288 Get VGA output connector for this VGA device.
1290 9.5 Class org.jpc.emulator.SoundDigitalOut
1292 Class org.jpc.emulator.SoundDigitalOut provodes output connector
1293 for sound. Each connector can transfer stereo signal at arbitiary
1294 sampling rate. Modules that have audio connectors need to
1295 implement interface org.jpc.emulator.SoundOutputDevice, as this
1296 signals that output connectors should be created.
1298 9.5.1 Method addSample(long, short, short)
1300 Add stereo sample at time given by first argument. The second and
1301 third arguments give volume on left and right channels.
1303 9.5.2 Method addSample(long, short)
1305 Add mono sample at time given by first argument. The second
1306 argument give volume on both channels.
1308 9.5.3 Method readBlock(Block)
1310 Reads block of output (atomic versus addSample). Block structure
1311 has following fields which are filled:
1313 • timeBase: Time base for block.
1315 • baseLeft: Left volume at time base.
1317 • baseRight: Right volume at time base
1319 • blockNo: Sequence number of block filled.
1321 • samples: Number of samples in block
1323 • sampleTiming: Number of nanoseconds since last sample
1325 • sampleLeft: Left channel samples
1327 • sampleRight: Right channel samples
1329 9.6 Interface org.jpc.emulator.SoundOutputDevice
1331 Implementing this interface signals that module has audio output
1335 org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
1337 Return the number of sound channels module has.
1340 org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
1342 This is called once per sound channel requested giving precreated
1345 9.7 Class org.jpc.emulator.PC method getSoundOut(String)
1347 Get sound output with specified name.
1349 10 Advanced: Writing event targets
1351 Whereas output connectors are the way output is dispatched, input
1352 is dispatched via event targets. Event targets need to implement
1353 interface org.jpc.emulator.EventDispatchTarget.
1355 Event targets also provode methods which then encode events and
1356 dispatch them forward (without doing anything else) to event
1357 recorder. Also, event targets may have methods for obtaining
1360 10.1 Interface org.jpc.emulator.EventDispatchTarget
1362 Interface that marks class capable of receiving events.
1364 10.1.1 Method setEventRecorder(EventRecorder)
1366 Set the event recorder input events are sent to.
1368 10.1.2 Method startEventCheck()
1370 Signals target to reset all state related to event checking and
1371 state feedback. This may be called at any time in order to
1372 reinitialialize event checking/feedback state.
1374 10.1.3 Method doEvent(long, String[], int) throws IOException
1376 Event dispatch handler. The first argument is event time, second
1377 is parameters and third is what to do with it. If target doesn't
1378 like the event, throw IOException. Following types (the integer
1379 parameter) are used:
1381 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
1383 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in
1384 event replay for reinitialization
1386 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay
1389 3 (EventRecorder.EVENT_EXECUTE): This event occurs now. Execute
1392 10.1.4 Method endEventCheock()
1394 End event reinitialization. Usually unused.
1396 10.1.5 Method getEventTimeLowBound(long, String[]) throws
1399 Return the time value that's the earliest possiblity for this
1400 event to occur. Returning any time in past (including -1) causes
1401 event to fire as soon as possible. The long parameter gives the
1402 current scheduled time for event.
1406 Modules are various extensions that run inside emulator core. As
1407 such, they affect sync. Modules must implement interface
1408 org.jpc.emulator.HardwareComponent (they are hardware components)
1409 and must be dumpable. Additionally, they need either constructor
1410 <init>() or <init>(String). The first is if no parameters are
1411 passed, the second is for case where parameters are passed.
1413 Aside of the constructors, modules need to obey the ordinary
1414 conventions for hardware components. No code outside modules
1415 needs to know that module exists.
1419 Plugins handle various UI tasks. They need to implement interface
1422 12.1 Interface org.jpc.pluginsbase.Plugin
1424 12.1.1 Method systemShutdown()
1426 Called when emulator shuts down. Either called in dedicated
1427 thread or in thread that called emulatorShutdown(). These
1428 handlers should do the bare minimum to get files on disk to
1429 consistent state. After these calls from all plugins have
1430 finished, emulator exits. Do not try to manipulate UI from these
1431 methods, as doing that easily leads into deadlock.
1433 12.1.2 Method reconnect(PC)
1435 Gives new PC to connect to. Null is passed if plugin should
1438 12.1.3 Method main()
1440 Called in dedicated thread after plugin is initialized.
1442 12.1.4 Method pcStopping()
1444 Called after PC has stopped.
1446 12.1.5 Method pcStarting()
1448 Called before PC starts.
1450 12.1.6 Method notifyArguments(String[])
1452 Pass arguments from command line.
1454 12.1.7 Constructor <init>(Plugins)
1456 This constructor is used to initialize plugins that don't take
1459 12.1.8 Constructor <init>(Plugins, String)
1461 This constructor is used to initialize plugins that take
1464 12.2 Class org.jpc.pluginsbase.Plugins
1466 This class provodes various methods for manipulating plugins.
1468 12.2.1 Method isShuttingDown()
1470 Returns true if Plugins.shutdownEmulator() has been called
1471 somehow, either via VM exit, CTRL+C or explicitly. Useful to skip
1472 cleanups involving GUI, as these are too deadlock-prone.
1474 12.2.2 Method shutdownEmulator()
1476 Shut down and exit the emulator. All plugin shutdown functions
1477 are called in this thread.
1479 12.2.3 Method reconnectPC(PC)
1481 Signal reconnectPC event to all plugins.
1483 12.2.4 Method pcStarted()
1485 Signal pcStarting() event to all plugins.
1487 12.2.5 Method pcStopped()
1489 Signal pcStopping() event to all plugins.
1491 12.3 Interface org.jpc.pluginsbase.ExternalCommandInterface
1493 Implementing interface
1494 org.jpc.pluginsbase.ExternalCommandInterface signals that plugin
1495 can receive commands via external commands interface.
1497 12.3.1 Method invokeCommand(String cmd, String[] args)
1499 Invoke specified command using specified arguments. Return true
1500 if event is to be shallowed, false to continue trying to pass it