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.
15 Note that to play back recorded movies, you need exact same
16 version of BIOS image, VGABIOS image and DOS boot floppy as was
17 used when making the movie (in addition to exact same versions of
22 See compile.sh or compile.bat. The streamtools stuff is only
23 needed for dumping videos.
27 First you need to get and make some important images. Obtain BIOS
28 image, VGABIOS image and DOS boot floppy from somewhere. After
29 starting the emulator, use Drives -> Import Image to import the
30 images (ignore the error about no BIOS images being found).
34 There is premade autoexec script called assemble.jpcrrinit that
35 has fairly reasonable defaults. To use it:
37 java JPCApplication -autoexec assemble.jpcrrinit
39 The script pops up settings for new emulated PC (if you want to
40 load savestate, click cancel). Select BIOS and VGABIOS for BIOS
41 and VGABIOS image (they should be already selected), DOSfloppy
42 for fda (boot device should be set to fda) and game image as some
47 • Putting the game as hdd (the fourth hard disk slot) causes boot
50 • Some BIOS versions have “press F12 to select boot device”. Hit
51 <enter> from emulated keyboard and that prompt will go away in
52 about half emulated second (it stays several emulated seconds
55 • If game doesn't need lots of memory, hitting F5 to skip
56 intialization files is fastest. If it does need more memory,
57 run config.sys commands but not autoexec.bat.
59 • Some DOS disks have DOSIDLE with them, don't use it as it
60 messes badly with emulator.
62 3 Making JPC-RR format images from raw images
64 Due to various factors, JPC-RR can't use raw image files directly
65 but requires its own image format.
67 3.1 Importing images from GUI:
69 Use Drives -> Import Image to import existing directories or
70 image files. Dialog prompting parameters will be displayed. When
71 importing floppy images, check “standard geometry” if possible,
72 that enables geometry autodetection, which is reasonable
73 virtually all of the time it is offered.
77 • If making image from directory, the names of the files must
78 conform to FAT naming restrictions (8+3 character names, no
79 spaces, etc). Avoid filenames with non-ASCII characters.
81 • The DOS limit of 112 or 224 files for floppies does not apply
82 to images created from directory trees. The minimum limit value
83 used is 512. If even that isn't enough, the limit is
84 automatically increased to fit all the needed directory
87 • Making boot disks from tree does NOT work. Even if you got
88 system boot files there, it still won't work.
90 • Only floppy disks and hard drives can be made from directory
91 trees. BIOS images and CDROM images require image file.
93 • Avoid floppies with custom geometry (floppy geometry does
94 affect disk ID). Disks with over 63 sectors per track don't
95 work with DOS. Wheither disks with over 127 tracks per side
96 work with DOS is unknown. Also avoid 1024-tracks per side HDDs.
98 • The geometry limits are: 2-1024 tracks per side for HDD, 1-256
99 tracks per side for floppy. 1-63 sectors per track for HDD,
100 1-255 sectors per track for floppy. 1-16 sides for HDD, 1 or 2
101 sides for floppy. This gives size limit of 65280KiB for floppy
102 disks (but note the DOS limit!) and 516096KiB for HDDs.
104 • There are multiple image file contents that represent the same
105 image. The one with smallest size is picked when creating
108 • Note: Although the IDs are 128 bits long, they are not MD5
111 3.3 Importing from command line
113 There is tool called ImageMaker that can make JPC-RR images from
114 raw images. Each image has format, ID an name. Format and name
115 are specified when making image. ID is automatically calculated
116 from format and contents. Name does not affect the ID but is
117 purely for convience so one doesn't have to specify long image
122 The syntax for ImageMaker when making images is:
124 $ java ImageMaker <format> [<options>...] <destination> <source>
127 <destination> is file name for JPC-RR format image to write.
128 <source> is either name of regular file (raw image file) or name
129 of directory tree with files (supported for making floppy or hard
130 disk images only). In case of directory tree, the files are
131 layout deterministically to disk, so the ID will always be the
132 same for given geometry and type. <name> is name to give to disk.
135 --BIOS BIOS image (note: VGABIOS is also of this type).
137 --CDROM CD-ROM image.
139 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
141 --floppy=tracks,sectors,sides Floppy disk with specified
144 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
146 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
148 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
150 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
152 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
154 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
156 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
158 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
160 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
162 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
164 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
166 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double
169 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double
172 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double
175 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double
178 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double
181 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double
184 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double
187 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double
190 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double
193 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double
196 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double
199 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double
202 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double
205 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double
208 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double
211 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double
214 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double
217 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double
222 --volumelabel=label Give specified volume label (affects ID).
223 Only meaningful when making image out of directory tree. Default
226 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files
227 (affects ID). Only meaningful when making image out of directory
228 tree. The default timestamp is 19900101T000000Z.
230 3.3.3 Image information
234 $ java ImageMaker <imagefile>
236 Variety of information about image is displayed (especially for
237 floppies/HDDs). Two important fields are calculated and claimed
238 disk ID. They should be the same. If they are not, then the image
239 file is corrupt (sadly, imagemaker has bugs and bugs that cause
240 it to write corrupt images have been seen).
242 3.4 Advanced: The disk ID algorithm
244 The disk ID is calculated as:
246 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
248 Where Skein-256-128-deprecated is Skein hash function with
249 256-bit internal state and 128-bit output using the deprecated
250 rotation constants (as specified in Skein hash function reference
251 documentation versions 1.0 and 1.1). The <image> is the whole
252 image, including parts not stored in image file. The reason for
253 keeping using the deprecated constants are:
255 • Changing the constants would change the IDs, which would
256 invalidate existing images
258 • This is not about cryptographic security
260 • The new constants don't improve security that much anyway.
262 3.4.1 Floppies and HDDs
264 Floppies have <typecode> value 0 (single byte) and HDDs have 1
265 (single byte). <geometry> is as follows (this is exactly the same
266 form as it appears in image header):
268 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
270 Byte 0 bits 2-5: Head count - 1.
272 Byte 0 bits 6-7: Reserved, must be 0.
274 Byte 1: Bits 0-7 of track count per side - 1.
276 Byte 2: Sector count per track - 1.
278 3.4.2 CD-ROM and BIOS images
280 CD-ROMs have <typecode> value 2 (single byte) and BIOS images
281 have 3 (single byte). <geometry> is blank.
283 3.5 Advanced: Disk Image format
285 The disk image consists of following parts, concatenated in this
286 order without padding:
298 • type-specific geometry/size data
306 Magic in disk image files is following 5 bytes: “IMAGE”
310 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
314 Type code is single byte. 0 for floppies, 1 for HDDs, 2 for
315 CD-ROMs and 3 for BIOS images. Other values are reserved.
317 3.5.4 Disk name length
319 Obsolete. Disk name length is given as two-byte big-endian value.
320 New images should have 0 here.
324 Ignored. Name field is there for backward compatiblity. Disk name
325 length gives length of this field in bytes.
327 3.5.6 Type-specific geometry/size data (floppies and HDDs)
329 Floppies and HDDs have 3-byte geometry data:
331 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
333 Byte 0 bits 2-5: Head count - 1.
335 Byte 0 bits 6-7: Reserved, must be 0.
337 Byte 1: Bits 0-7 of track count per side - 1.
339 Byte 2: Sector count per track - 1.
341 3.5.7 Type specific-geometry/size data (CD-ROMs)
343 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
345 3.5.8 Type specific-geometry/size data (BIOS images)
347 BIOS images have 4-byte big-endian byte (not sector or block)
350 3.5.9 Actual image data (floppy/HDD)
352 Floppy or HDD imagedata consists of following subparts:
362 Storage method is single byte. Sectors present gives number of
363 last nonzero sector + 1 (zero if image is all zeroes)
365 3.5.10 Floppy/HDD storage method 0: Raw storage
367 This storage method has empty header. Image data is raw dump of
368 first sectors present sectors.
370 3.5.11 Floppy/HDD storage method 1: Sectormap
372 Image data header contains bitfield with just enough bytes to
373 have one bit per present sector. The order of bits is such that
374 number of bit corresponding to each sector in byte is sector
375 number modulo 8 and byte number is floor of sector number divided
376 by 8 when sector numbers are counted from zero. If bit
377 corresponding to sector is set, then the sector is present in
378 image data, otherwise it is absent and assumed to be all-zeroes.
380 Image data contains dumps of all present sectors in order of
381 increasing sector number.
383 3.5.12 Floppy/HDD storage method 2: Extent first sector zero
385 Image data is empty as storage-specific data is mangled with
386 image data. The image data alternates between blocks encoding
387 zero sectors and blocks encoding nonzero sectors. The first block
388 encodes zero sectors.
390 Block encoding zero sectors consist of single 1-4 byte
391 little-endian value encoding number of sectors in block - 1.
392 Number of bytes is determined by sectors present value. It is 1
393 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
394 for more than 16777216. All sectors in block are filled with
395 zeroes and are not stored.
397 Block encoding nonzero sectors has same block count as zero
398 sector block but is followed by the sectors stored raw.
400 3.5.13 Floppy/HDD storage method 3: Extent first sector nonzero
402 Same as storage method 2 but first block is nonzero sector block.
404 3.5.14 Actual image data (CD-ROMs and BIOS images)
406 These store image data raw. The amount of data is specified by
411 Comments are given as list of strings, with UTF-8 encoded strings
412 following 2-octet big-endian length. Comment list is terminated
413 by entry with length 0 (0x00 0x00). Comments are optional and may
416 4 The actual emulator
418 The actual emulator is invoked as:
420 $ java JPCApplication <options>...
422 The valid options are:
424 -autoexec <script> Execute contents of specified file as commands
427 -noautoexec Don't run autoexec files.
429 -norenames Copy&Delete files instead of renaming. Mainly meant
430 for debugging copy&delte code.
432 -imagemaker <options> Run in image maker mode (run with parameter
433 '-imagemaker' with no further parameters for help)
435 If no arguments are given, defaults of autoexec file of
436 'assemble.jpcrrinit' are used.
440 When emulator is started, command line comes up. Following
443 • 'exit': exit immediately. Dumps in progress are gracefully
446 • 'kill': Save stack traces and kill the emulator (for debugging
447 only). Any dumps in progress are likely corrupted.
449 • 'library <library>': set library directory to <library>.
451 • 'load <plugin>': Load plugin (no arguments)
453 • 'load <plugin>(<arguments>)': load plugin with arguments.
455 • 'command <command> [<arguments>...]': Invoke command via
456 external command interface.
458 • 'call<command> [<arguments>...]': Invoke command via external
459 command interface and print return values.
461 • 'lsdisks [<filename>]' Print listing of all known disks. If
462 <filename> is specified, save output to specified file.
464 • 'diskinfo [<filename>] <imagename>' Print Information about
465 <imagename> (can be disk name or ID). If <filename> is
466 specified, save output to specified file.
468 When one gets command line, its useful to load some plugins. See
469 section about plugins. Note: Load runner plugin
470 (PCControl/PCRunner and so) last, as some runners like to start
473 4.2 PC settings dialog notes
475 • CPU divider base frequency before division is 1GHz.
477 • Images can be specified by name or by ID. Name is relative to
478 library directory. If the image is in subdirectory of image
479 directory, the directory separator is is '/' regardless of what
482 • CD-ROM and hdc are mutually exclusive
484 • Modules is comma-seperated list of modules to load. To pass
485 arguments to some modules, enclose the arguments in (). Same
486 module can be specified twice only if parameters differ.
488 • Setting boot device doesn't work with some BIOS versions. Those
489 versions prompt the boot device anyway.
491 4.3 Audio output channels
493 PC can have one or more audio output channels. The name of audio
494 output associated with PC speaker is:
495 'org.jpc.emulator.peripheral.PCSpeaker-0'. Modules that have
496 audio outputs get channel names of form <classname>-<sequential>,
497 where <classname> is name of main module class and sequential is
498 number starting from zero. Note that same module can have
499 multiple output channels. If multiple modules of same class
500 request audio outputs, the <sequential> values of subsequent
501 module start where previous left off.
505 Plugins actually execute the tasks of the emulator. They can be
506 loaded using “load <plugin>” or 'load <plugin>(<arguments>)” from
509 Different Plugins using the same output (like running PCMonitor
510 and RAWVideoDumper) should not conflict because connector output
511 hold locking is desinged to handle multiple readers.
513 If no plugin used requires GUI, then the emulator can be run
514 without having GUI available.
516 4.4.1 plugin: org.jpc.plugins.PCControl
518 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1',
519 requires and uses GUI.
521 Runs the PC emulator core. Has capability to start/stop
522 emulation, breakpoint after certain time or start/end of VGA
523 vertical retrace. Also can create, savestate and loadstate PC
524 emulation. Memory dumping is supported.
526 'extramenu=<file>' causes Plugin to load extra menu entries from
527 <file>. 'uncompressedsave=1' causes savestates to be written
528 uncompressed (useful if they are stored in VCS supporting delta
531 4.4.2 plugin: org.jpc.plugins.PCRunner
533 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>'
534 Does not require nor use GUI.
536 Loads PC from savestate and just runs it. CTRL+C to quit. Also
537 automatically quits once stoptime is reached.
539 4.4.3 plugin: org.jpc.plugins.PCMonitor
541 No arguments, requires and uses GUI.
543 VGA monitor for emulated PC.
545 4.4.4 plugin: org.jpc.plugins.VirtualKeyboard
547 No arguments, requires and uses GUI.
549 On-screen keyboard for emulated PC.
551 4.4.5 plugin: org.jpc.plugins.PCStartStopTest
553 No arguments, requires and uses GUI.
555 Small plugin testing remote PC start/stop. Also supports sending
556 some common keypresses.
558 4.4.6 plugin: org.jpc.plugins.RAWVideoDumper
560 Takes 'rawoutput=<file>' as argument. Does not require nor use
563 Dumps all generated frames to RAW file <file>. Rawoutput is
564 required. The raw file consists of concatenation of zlib streams.
565 The uncompressed stream is concatenation of time skips (FFh FFh
566 FFh FFh), each acting as time offset of 2^32-1 nanoseconds and
567 saved frames. The saved frame has time offset in nanoseconds (big
568 endian) as first four bytes (must be at most 2^32-2, as 2^32-1 is
569 reserved for time skip). The next two bytes are big-endian width,
570 next two big-endian height. Finally frame has 4 * width * height
571 bytes of data that encodes pixels using 4 bytes per pixel, in
572 left-to-right, up-to-down order. Byte 0 of each pixel is
573 reserved, byte 1 is the red channel, byte 2 is green channel and
574 byte 3 is blue channel.
576 Dumping to pipe is supported.
578 4.4.7 plugin: org.jpc.plugins.RAWAudioDumper
580 Takes 'src=<name of audio output channel>',
581 'file=<output-filename>' and 'offset=<offset>' as arguments,
582 separated by ','. Does not require nor use GUI.
584 Dumps output from specified audio output channel (src, mandatory)
585 to RAW-format file (file, mandatory). The resulting file consists
586 of records, 4 or 8 bytes each. 4 byte record consists of 0xFF
587 0xFF 0xFF 0xFF and means to increase next time delta by 2^{32}-1
588 ns. Otherwise record is 8 bytes. Each 8 byte record has three
589 fields. First 4 byte unsinged big endian timedelta value (in
590 nanoseconds, must be smaller than 2^{32}-1), then 2 byte signed
591 big endian new left channel volume, then 2 byte signed big endian
592 new right channel volume. Optionally 'offset' can be set to
593 positive value (in nanoseconds) to delay the audio by.
595 4.4.8 plugin: org.jpc.plugins.LuaPlugin
597 Takes 'kernel=<name of lua kernel file>', other parameters are
598 passed to kernel, requires and uses GUI.
600 Lua VM for executing scripts.
602 4.4.9 plugin: org.jpc.plugins.JoystickInput
604 No parameters. Displays window for sending joystick input.
608 5.1 org.jpc.modules.Joystick:
612 • Resources: I/O port 0x201
614 Emulates joystick game port.
616 5.2 org.jpc.modules.SoundCard
618 • Arguments: Optional resources specification
620 • Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
624 5.3 org.jpc.modules.GMIDIInterface
626 • Arguments: Optional resources specification
628 • Resources (defaults): I/O port 0x330-0x331, IRQ 9
630 Emulates General MIDI interface.
632 5.4 org.jpc.modules.FMCard
634 • Arguments: Optional resources specification
636 • Resources (defaults): I/O port 0x338-0x33B
640 5.5 org.jpc.modules.BasicFPU:
646 Crude FPU (x87) emulator.
650 Hacks are saved to savestates but not movies.
654 Force bit 1 of physical address 0x0410 to zero, signaling that
655 the system has no FPU. BIOS assumes system has FPU but some games
656 use that bit to detect FPU, trying to use it if it is “present”.
657 Try this if game startup hangs with lots of trying to use FPU but
658 not present errors. Don't use if there is FPU present. Needed to
659 get games like Blake Stone / Wolfenstein 3-D to work (FPU
660 emulator allows it to start but causes graphical glitches).
664 Update basic VGA parameters before vretrace, not after it. Some
665 games (e.g. Commander Keen 4) don't like if this isn't done and
666 some games (e.g. Mario & Luigi) don't like if it is done. Wrong
667 value manifests as jerky scrolling (scrolling back and forth and
668 fixed statusbars move).
670 7 Some error messages and explanations
672 • <filename> is Not a valid image file
674 • <filename> is not image file
676 • <filename> claims to be floppy with illegal geometry: <x>
677 tracks, <y> sides and <z> sectors.
679 • <filename> claims to be HDD with illegal geometry: <x> tracks,
680 <y> sides and <z> sectors.
682 • Can't read disk image sector map.
684 • Can't read disk image extent.
686 Code expects <filename> to be valid JPC-RR format image, but it
687 isn't JPC-RR image at all or its corrupt.
689 • <filename> is image of unknown type.
691 • <filename> has unrecognized geometry <x> <y> <z>
693 Possibly corrupt image, not JPC-RR image, or JPC-RR image from
694 future version containing something current version can't
697 • Invalid format specifier <something>.
699 • Invalid syntax of --floppy= or --HDD= option.
701 • Invalid format specifier/option <something>.
703 Invalid option or format specifier was given. Check for typos.
705 • java ImageMaker [<options>...] <format> <destination> <source>
708 Check syntax of command. Especially that diskname is present!
710 • The image has <nnn> sectors while it should have <yyy>
711 according to selected geometry.
713 • Raw image file length not divisible by 512.
715 • Trying to read sector out of range.
717 The selected geometry is wrong or raw image is incomplete.
719 • Invalid disk name (Should not happen!).
721 • Invalid geometry to be written.
723 This is a very likely a bug in program.
725 • What the heck <filename> is? It's not regular file nor
728 That sort of file can't be used as input for image making, or the
729 file just doesn't exist.
731 • BIOS images can only be made out of regular files.
733 • CD images can only be made out of regular files.
735 Source image specified is not regular file, but image of that
736 type can't be made of anything else.
738 • Can't read raw bios image file.
740 • Can't read sector <nnn> from image.
742 Reading the raw image file failed for some reason.
744 • Bad library line: "<something>". Ignored.
746 Syntax error in image library.
748 • Removing image <something> a.k.a. "<something>" as it no longer
751 The image file no longer exists so it gets removed from library.
753 • Removing image <something> a.k.a. "<something>" due to <some>
756 Image library code killed some image from library due to some
757 kind of conflict with image being added.
759 • Too much data to fit into given space.
761 The tree you gave contains takes just too much space to fit into
764 8 Advanced: Savestate/movie format
766 8.1 Special character classes
770 Following Unicode codepoints (encoded as UTF-8) are interpretted
773 • Codepoints 0x20, and 0x09.
775 • Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
777 • Codepoints 0x2000-0x200A.
781 Following byte sequences are interpretted as linefeeds (line
784 • Byte 0x0A (UTF-8 encoded codepoint 0x0A)
786 • Byte 0x0D (UTF-8 encoded codepoint 0x0D)
788 • Byte 0x1C (UTF-8 encoded codepoint 0x1C)
790 • Byte 0x1D (UTF-8 encoded codepoint 0x1D)
792 • Byte 0x1E (UTF-8 encoded codepoint 0x1E)
794 • Bytes 0xC2 0x85 (UTF-8 for unicode control character NL,
797 • Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
801 JRSR archive format packs multiple text archive members to text
802 archive. It does not support binary members. JRSR archives have
803 first five or six bytes form the magic. It is “JRSR” followed by
804 LINEFEED character There are four kinds of lines after that
805 (lines are terminated by LINEFEED byte/bytes):
815 Sequencing rules are as follows: Start member is allowed anywhere
816 (after magic). Member line is allowed only inside member (member
817 started but not ended). End member is only allowed inside member.
818 End of file is only allowed outside member. Blank line is allowed
819 anywhere after magic.
823 Start member line is given as “!BEGIN” <SPACE>+ <membername>
824 <LINEFEED>. <SPACE>+ any number of SPACE characters at least one
825 and <LINEFEED> is LINEFEED chacter. The member name is UTF-8
826 encoded and maximum allowed line length is 2048 bytes (including
827 LINEFEED, which means name is limited to 509-2040 codepoints
828 depending on characters used). Starting member inside another
829 implicitly ends the previous member.
833 Member line is given as “+”<content><LINEFEED>. It gives another
834 line for member contents. <content> is passed raw to layers above
835 (followed by line termination)
839 End member line is given as “!END”<LINEFEED>. It ends the current
840 member. The following line can only be start member line or file
845 Blank line is given as <LINEFEED>. Lines like that are ignored.
847 8.3 Four-to-Five encoding
849 Binary members are encoded into text by so-called four-to-five
850 encoding. This encoding can encode single byte to two, two bytes
851 to three, three bytes to four and four bytes to five.
852 Four-to-five encoding has five kinds of blocks. All SPACE and
853 LINEFEED characters are completely ignored, even in middle of
856 8.3.1 End stream block
858 End stream block is encoded as '!'. It ends the stream instantly.
859 There is also implicit end of stream at end of input to decoding.
861 8.3.2 Other four block types
863 Other four block types take the value to be encoded, read it as
864 big-endian value. Then they write it as base-93 big-endian value.
865 Then length specific constants are added to digits of that number
866 to yield ASCII values for characters (those are stored in order):
869 +------------+------------+------------+------------+------------+-----------+
870 | To encode | 1st char. | 2nd char. | 3rd char. | 4th char. | 5th char. |
871 +------------+------------+------------+------------+------------+-----------+
872 +------------+------------+------------+------------+------------+-----------+
873 | 1 byte | 34 | 34 | - | - | - |
874 +------------+------------+------------+------------+------------+-----------+
875 | 2 bytes | 37 | 34 | 34 | - | - |
876 +------------+------------+------------+------------+------------+-----------+
877 | 3 bytes | 45 | 34 | 34 | 34 | - |
878 +------------+------------+------------+------------+------------+-----------+
879 | 4 bytes | 66 | 34 | 34 | 34 | 34 |
880 +------------+------------+------------+------------+------------+-----------+
883 Blocks which encode values greater than what is possible for
884 value of that length are fatal errors.
886 8.4 Line component encoing
888 Line component encoding sits on top of UTF-8 encoding. Line
889 component encoding encodes non-empty 1-D array of non-empty
890 strings into line, and thus array of those into member. Empty
891 lines or lines that don't contain any components are ignored.
892 Line starts with depth value of 0 and must end with depth value
895 Components are seperated by component separators. Empty
896 components are ignored. Following codepoints are separators on
897 depth 0 if not escaped:
899 • Codepoint of '('. The depth is read pre-increment.
901 • Codepoint of ')'. The depth is read post-decrement.
903 • Any SPACE character
905 The following characters are special:
907 • '('. Increments depth by 1 if not escaped (and appears in
910 • ')'. Decrements depth by 1 if not escaped (and appears in
911 component). Depth going negative is an error.
913 • '\'. Next character is interpretted as literal. Error if at end
916 Otherwise, characters are interpretted as literals and appear in
917 components. Depth must be zero at end of line.
921 Header section is in archive member "header". It uses line
922 component encoding. The first component of each line is name of
923 header, and subsequent ones are arguments. How many parameters
924 are expected is dependent on what header it is:
926 8.5.1 PROJECTID header:
928 • Header name: "PROJECTID"
932 • Argument #1: <project-id-string>
936 Gives project ID. Project ID is generated when PC is assembled
937 and is then preserved in save states. It is used for computing
938 rerecord counts. Emulator treats it as opaque string, the IDs it
939 generates are formed by 48 random hexadecimal digits.
941 8.5.2 SAVESTATEID header:
943 • Header name: "SAVESTATEID"
947 • Argument #1: <savestate-id-string>
951 Gives save state ID. Each save state has its own save state ID.
952 Treated as opaque string, but generated as 48 random hexadecimal
953 digits. The presence of this header signals whether there is save
954 state to be loaded. If this header is present, save state load
955 will be attempted. If absent, save state is not to be loaded even
956 if present (and correct savestate load would be technically
959 The value is used to prevent loading incompatible save states in
960 preserve event stream mode and also to find the point in event
961 stream where one left off.
963 8.5.3 RERECORDS header:
965 • Header name: "RERECORDS"
969 • Argument #1: <rerecords>
973 Gives rerecord count. PC assembly (except when loading save
974 state) initializes current rerecord count to zero. Must be
975 non-negative and decimal number using ASCII digit characters.
977 On loading save state:
979 1) If project ID matches with previous:
981 1a) If loaded rerecord count is larger or equal to current
984 1a-a) Current rerecord count is loaded rerecord count + 1.
988 1b-a) Current rerecord count increments by 1.
992 2a) Current rerecord count is loaded rerecord count + 1.
994 The current rerecord count at time of save is saved to save
999 • Header name: "SYSTEM"
1003 • Argument #1: <system-id-string>
1007 Gives system this movie/save is for. The only currently
1008 recognized values are “PC-JPC-RR-r10” and “PC-JPC-RR-r11.3” (if
1009 this header is absent, use default system). Invalid values
1010 trigger error on load time. The “PC-JPC-RR-r11.3” should be used
1011 if INITIALSTATE headers are present to avoid earlier versions
1012 from getting confused by those.
1014 8.5.5 AUTHORS header:
1016 • Header name: "AUTHORS"
1018 • Components: 2 or more
1020 • Arguments: free form
1024 Gives authors of run. Each argument gives one author (who has
1025 full name but no nickname). May be present multiple times.
1027 8.5.6 AUTHORNICKS header:
1029 • Header name: "AUTHORNICKS"
1031 • Components: 2 or more
1033 • Arguments: free form
1037 Gives authors of run. Each argument gives one author (who has
1038 nickname but no full name). May be present multiple times.
1040 8.5.7 AUTHORFULL header:
1042 • Header name: "AUTHORFULL"
1046 • Arguments: free form
1050 Gives author of run. First argument is full name of author, and
1051 second is nickname of author. May be present multiple times.
1053 8.5.8 COMMENT header:
1055 • Header name: "COMMENT"
1057 • Components: 2 or more
1059 • Arguments: free form
1063 Various kinds of free form data. Not parsed further by emulator.
1065 8.5.9 INITIALSTATE header:
1067 • Header name: "INITIALSTATE"
1069 • Components: 2 or more
1071 • Arguments: Name of initial state
1075 Denotes that “initialization-”<name> is valid initial state.
1077 8.6 Initialization segment:
1079 If SAVESTATEID header isn't present (not a save state), member
1080 "initialization" (or “initialization-”<name>) gives PC
1081 initialization parameters for assembling the PC. It is present
1082 anyway even if SAVESTATEID is present (savestate).
1084 Following parameters are used (space separates components):
1088 Gives Image ID of main system BIOS (mandatory)
1092 Gives Image ID of VGA BIOS (mandatory).
1096 Gives Image ID of hda. Present only if system has hard disk hda.
1100 Gives Image ID of hdb. Present only if system has hard disk hdb.
1104 Gives Image ID of hdc. Present only if system has hard disk hdc.
1108 Gives Image ID of hdd. Present only if system has hard disk hdd.
1112 Gives Image ID of disk in slot <num>. Slot number must be
1115 “DISKNAME” <num> <name>
1117 kGives image name of disk in slot <num>. Slot number must be
1118 non-negative. The slot must be previously declared using “DISK”.
1122 Gives Image slot to initially put into floppy drive fda. Disk
1123 must be of floppy type. If none present, no disk is initially put
1128 Gives Image slot to initially put into floppy drive fdb. Disk
1129 must be of floppy type. If none present, no disk is initially put
1134 Gives Image slot to initially put into CD-ROM drive hdc. Not
1135 allowed if hard disk hdc is present. Disk must be of CD-ROM type.
1136 If none present no disk is initially put there.
1138 "INITIALTIME" <time>
1140 Number of milliseconds since Unix epoch to system start up time.
1143 0-4102444799999. Mandatory.
1145 "CPUDIVIDER" <divider>
1147 Set CPU frequency divider (dividing the 1GHz master clock).
1148 Allowed range is 1-256. Mandatory.
1150 "MEMORYSIZE" <pages>
1152 Number of 4KiB pages of RAM memory. Allowed range 256-262144.
1157 Set boot device. Valid devices are "FLOPPY" (boot from fda),
1158 "HDD" (boot from hda) and "CDROM" (boot from CD).
1160 "LOADMODULEA" <module> <parameters>
1162 Load module <module> with parameters <parameters>.
1164 "LOADMODULE" <module>
1166 Load module <module> with no parameters
1170 Use class <fpu> as FPU emulator.
1174 Use I/O port delay emulation (each I/O port read/write takes
1179 Emulate VGA horizontal retrace.
1181 8.7 Event record format:
1183 Event record is in archive member "events". It uses line
1184 component encoding. Each line gives an event. First component of
1185 each line gives time stamp. These timestamps MUST be in
1186 increasing order and all MUST be non-negative. Time stamp time
1187 unit is exactly 1 nanosecond of emulated time.
1189 The second component of each line is name of class to dispatch
1190 to. Further components are passed as-is to event handlers.
1191 Classes with names consisting only of uppercase A-Z and 0-9 are
1192 special and reserved. It is error to encounter unknown such
1195 8.7.1 Savestate event
1197 • Dispatch to: SAVESTATE
1199 • Argument #1: Savestate id
1201 • Argument #2 (optional): Rerecord count at time of saving
1204 Signals that savestate has occured here. The save state IDs MUST
1205 be unique in entire event stream. The second argument to
1206 savestate (if present) is rerecord count at time of saving that
1207 savestate (useful for calulating rerecord count of movie starting
1208 from savestate). No time restrictions
1212 • Dispatch to: OPTION
1214 • Argument #1: “ABSOLUTE” or “RELATIVE”
1216 Controls various options. “ABSOLUTE” turns on absolute mode
1217 (default) where event timestamps are absolute. “RELATIVE” turns
1218 on relative mode where event timestamps are relative to last
1219 event in stream. The OPTION event itself is not affected by
1220 timing change. No time restrictions. Unknown arguments are
1223 8.7.3 Keyboard keypress/keyrelease event:
1225 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1227 • Argument #1: Fixed: "KEYEDGE"
1229 • Argument #2: Key number. Valid values are 1-83, 85-95, 129-197
1232 Send key press or key release. Keys work in toggle button manner.
1233 The event time must be multiple of 66 666, and must not be less
1234 than 60 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs
1235 after last KEYEDGE on key >128 and 10 * 66 666 TUs after last
1236 KEYEDGE on key <128.
1240 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1242 • Argument #1: Fixed: "PAUSE"
1244 Send pause key event. The time restrictions are identical to
1247 8.7.5 Mouse button event:
1249 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1251 • Argument #1: Fixed: "MOUSEBUTTON"
1253 • Argument #2: Number of button to release or press (0-4)
1255 Presses or releases the designated mouse button.
1257 8.7.6 X mouse motion event:
1259 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1261 • Argument #1: Fixed: "XMOUSEMOTION"
1263 • Argument #2: Number of units to move (-255 - 255)
1265 Move the mouse in X direction by specified amount. Positive is
1268 8.7.7 Y mouse motion event:
1270 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1272 • Argument #1: Fixed: "YMOUSEMOTION"
1274 • Argument #2: Number of units to move (-255 - 255)
1276 Move the mouse in Y direction by specified amount. Positive is
1279 8.7.8 Z mouse motion event:
1281 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1283 • Argument #1: Fixed: "ZMOUSEMOTION"
1285 • Argument #2: Number of units to move (-7 - 7)
1287 Move the mouse in Z direction (scrollwheel) by specified amount.
1289 8.7.9 Joystick button event:
1291 • Dispatch to: org.jpc.modules.Joystick
1293 • Argument #1: “BUTTONA”, “BUTTONB”, “BUTTONC” or “BUTTOND”
1295 • Argument #2: “0” if released, “1” if pressed
1297 Send button down/up event. No time restrictions.
1299 8.7.10 Joystick axis event:
1301 • Dispatch to: org.jpc.modules.Joystick
1303 • Argument #1: “AXISA”, “AXISB”, “AXISC” or “AXISD”
1305 • Argument #2: Multivibrator unstable state length in ns.
1307 Set amount of time multivibrator remains in unstable state. No
1312 • Dispatch to: org.jpc.emulator.PC$ResetButton
1318 8.7.12 Fda disk change:
1320 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1322 • Argument #1: Fixed: "FDA"
1324 • Argument #2: Number of image slot to put there.
1326 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1327 used if there is no disk in floppy drive A. This event causes
1328 specified disk to be placed to FDA or FDA disk to be ejected with
1329 no replacement if disk number is -1. The specified disk if not -1
1330 must be of floppy type. The specified disk if valid must not be
1333 8.7.13 Fdb disk change:
1335 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1337 • Argument #1: Fixed: "FDB"
1339 • Argument #2: Number of image slot to put there.
1341 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1342 used if there is no disk in floppy drive B. This event causes
1343 specified disk to be placed to FDB or FDB disk to be ejected with
1344 no replacement if disk number is -1. The specified disk if not -1
1345 must be of floppy type. The specified disk if valid must not be
1348 8.7.14 Change CDROM:
1350 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1352 • Argument #1: Fixed: "CDROM"
1354 • Argument #2: Number of image slot to put there.
1356 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1357 used if there is no disk in CD-ROM. This event causes specified
1358 disk to be placed to CD-ROM or CD-ROM disk to be ejected with no
1359 replacement if disk number is -1. The specified disk if not -1
1360 must be of CD-ROM type.
1362 This event has no effect if CD-ROM is locked.
1364 8.7.15 Write protect floppy:
1366 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1368 • Argument #1: Fixed: "WRITEPROTECT"
1370 • Argument #2: Number of image slot to manipulate
1372 Write protects specified disk. The disk MUST NOT be in any drive
1373 and MUST be valid floppy-type disk.
1375 8.7.16 Write unprotect floppy:
1377 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1379 • Argument #1: Fixed: "WRITEUNPROTECT"
1381 • Argument #2: Number of image slot to manipulate
1383 Disables write protection specified disk. The disk MUST NOT be in
1384 any drive and MUST be valid floppy-type disk.
1386 8.8 Diskinfo sections
1388 Diskinfo sections are named “diskinfo-”<id of disk>. They use
1389 line component encoding, fieldtype being first component on each
1390 line (value being the second). Following fields are defined:
1394 Gives type of image. Possible values are
1396 • “FLOPPY” (floppy disk)
1402 • “BIOS” (BIOS/VGABIOS image)
1404 • “UNKNOWN” (what the heck is this???)
1412 (BIOS images only) Gives length of BIOS image
1416 MD5 of raw disk/BIOS image without any headers or trailers.
1420 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
1424 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256
1425 for floppy, 1-1024 for HDD).
1429 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for
1430 floppy, 1-16 for HDD).
1434 (FLOPPY/HDD images only) Number of sectors per track (1-255 for
1435 floppy, 1-63 for HDD).
1439 Line from image comment block. Usually give data about files
1440 image has. May or may not be present (multiple times)
1444 Output info is stored in section “output-info”. Its relatively
1445 new, so it might not be present (then the contents have to be
1446 guessed based on modules present). Each line gives information
1447 about one output, first field being the type of output.
1451 For video output, there are no parameters so line is just “VIDEO”
1456 For audio output, the only parameter is name of output, so first
1457 component is “AUDIO” and second component is name of audio
1462 Actual savestate format is not documented here. It is close to
1463 impossible to comprehend without access to emulator source
1466 9 Advanced: Making class dumpable
1468 Class is made dumpable by implementing interface
1469 org.jpc.emulator.SRDumpable and implementing method
1470 dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
1471 <init>(org.jpc.emulator.SRLoader). Non-static inner classes can
1472 not be dumpable (make them static using tricks similar to what
1475 If dumped class has dumpable superclass, the first thing dumping
1476 function needs to do is to call dumper function of superclass and
1477 first thing loading constructor needs to do is to call loading
1478 constructor of superclass. If class has no dumpable superclass,
1479 dumper doesn't need to do anything special, while loader needs to
1480 call objectCreated(this) on SRLoader object passed as parameter.
1482 Following these fixed parts, dump all members that are part of
1483 mutable state in emulator core.
1485 9.1 Member dumping/loading functions
1487 There is dumping/loading function for following (all functions
1488 dumping/loading reference types can handle null):
1490 • boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
1492 • byte: SRDumper.dumpByte, SRLoader.loadByte
1494 • short: SRDumper.dumpShort, SRLoader.loadShort
1496 • int: SRDumper.dumpInt, SRLoader.loadInt
1498 • long: SRDumper.dumpLong, SRLoader.loadLong
1500 • String: SRDumper.dumpString, SRLoader.loadString
1502 • boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
1504 • byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
1506 • short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
1508 • int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
1510 • long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
1512 • double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
1514 • <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
1516 • special object: SRDumper.specialObject, SRLoader.specialObject
1520 • Dumpable objects come out as type of
1521 org.jpc.emulator.SRDumpable.
1523 • Special objects are various static objects that don't need to
1524 be stored because they don't have mutable fields.
1526 • Don't dump fields related to event state feedback.
1528 • Don't dump temporary flags that are only used while PC is
1529 running. Savestate when PC is running isn't possible anyway.
1531 • Some connectors dump fields related to connector output, some
1534 10 Advanced: Writing event targets
1536 Whereas output connectors are the way output is dispatched, input
1537 is dispatched via event targets. Event targets need to implement
1538 interface org.jpc.emulator.EventDispatchTarget.
1540 Event targets also provode methods which then encode events and
1541 dispatch them forward (without doing anything else) to event
1542 recorder. Also, event targets may have methods for obtaining
1545 10.1 Interface org.jpc.emulator.EventDispatchTarget
1547 Interface that marks class capable of receiving events.
1549 10.1.1 Method setEventRecorder(EventRecorder)
1551 Set the event recorder input events are sent to.
1553 10.1.2 Method startEventCheck()
1555 Signals target to reset all state related to event checking and
1556 state feedback. This may be called at any time in order to
1557 reinitialialize event checking/feedback state.
1559 10.1.3 Method doEvent(long, String[], int) throws IOException
1561 Event dispatch handler. The first argument is event time, second
1562 is parameters and third is what to do with it. If target doesn't
1563 like the event, throw IOException. Following types (the integer
1564 parameter) are used:
1566 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
1568 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in
1569 event replay for reinitialization
1571 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay
1574 3 (EventRecorder.EVENT_EXECUTE): This event occurs now. Execute
1577 10.1.4 Method endEventCheock()
1579 End event reinitialization. Usually unused.
1581 10.1.5 Method getEventTimeLowBound(long, String[]) throws
1584 Return the time value that's the earliest possiblity for this
1585 event to occur. Returning any time in past (including -1) causes
1586 event to fire as soon as possible. The long parameter gives the
1587 current scheduled time for event.
1591 Modules are various extensions that run inside emulator core. As
1592 such, they affect sync. Modules must implement interface
1593 org.jpc.emulator.HardwareComponent (they are hardware components)
1594 and must be dumpable. Additionally, they need either constructor
1595 <init>() or <init>(String). The first is if no parameters are
1596 passed, the second is for case where parameters are passed.
1598 Aside of the constructors, modules need to obey the ordinary
1599 conventions for hardware components. No code outside modules
1600 needs to know that module exists.
1604 Plugins handle various UI tasks. They need to implement interface
1607 12.1 Interface org.jpc.pluginsbase.Plugin
1609 12.1.1 Method systemShutdown()
1611 Called when emulator shuts down. Either called in dedicated
1612 thread or in thread that called emulatorShutdown(). These
1613 handlers should do the bare minimum to get files on disk to
1614 consistent state. After these calls from all plugins have
1615 finished, emulator exits. Do not try to manipulate UI from these
1616 methods, as doing that easily leads into deadlock.
1618 12.1.2 Method reconnect(PC)
1620 Gives new PC to connect to. Null is passed if plugin should
1623 12.1.3 Method main()
1625 Called in dedicated thread after plugin is initialized.
1627 12.1.4 Method pcStopping()
1629 Called after PC has stopped.
1631 12.1.5 Method pcStarting()
1633 Called before PC starts.
1635 12.1.6 Method notifyArguments(String[])
1637 Pass arguments from command line.
1639 12.1.7 Constructor <init>(Plugins)
1641 This constructor is used to initialize plugins that don't take
1644 12.1.8 Constructor <init>(Plugins, String)
1646 This constructor is used to initialize plugins that take
1649 12.2 Class org.jpc.pluginsbase.Plugins
1651 This class provodes various methods for manipulating plugins.
1653 12.2.1 Method isShuttingDown()
1655 Returns true if Plugins.shutdownEmulator() has been called
1656 somehow, either via VM exit, CTRL+C or explicitly. Useful to skip
1657 cleanups involving GUI, as these are too deadlock-prone.
1659 12.2.2 Method shutdownEmulator()
1661 Shut down and exit the emulator. All plugin shutdown functions
1662 are called in this thread.
1664 12.2.3 Method reconnectPC(PC)
1666 Signal reconnectPC event to all plugins.
1668 12.2.4 Method pcStarted()
1670 Signal pcStarting() event to all plugins.
1672 12.2.5 Method pcStopped()
1674 Signal pcStopping() event to all plugins.
1676 13 Inter-plugin communication
1678 13.1 Receiving communications
1680 To receive invocation/call by name 'foo-bar', declare public
1681 method named 'eci_foo_bar'. Arguments to this method can
1682 currently be String, Integer (int) or Long (long). Last argument
1683 may be array over these types to get variable number of
1684 arguments. On call, each argument gets value from call. If last
1685 argument is array, it gets all overflowing arguments. If return
1686 type is void or method returns boolean false, call is assumed to
1687 have completed. If return value is boolean true, it is assumed
1688 that there is more processing.
1691 org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd,
1694 Invoke command asynchronously, broadcasting to all plugins. Does
1695 not wait for slow commands to complete. cmd is the name to send
1696 and args are the arguments to pass.
1699 org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String
1702 Same as invokeExternalCommand, but waits for slow commands to
1706 org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String
1709 Similar to invokeExternalCommandSynchornous, but:
1711 • Quits calling more plugins when it gets successful reply.
1713 • Returns said reply
1715 13.5 void org.jpc.pluginsbase.Plugins.returnValue(Object... ret)
1717 Gives return value to return from call and signals that command
1720 13.6 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
1722 Signals that command has completed. Only needed if there is no
1723 return value and eci_ method returned false (not done yet).
1725 14 Lua kernel programming
1727 At startup, kernel gets its arguments in 'args' table and the
1728 script name to run in 'scriptname' string. It should enter the
1729 named script in protected mode.
1731 The Lua VM exports numerious callbacks to kernel. The kernel can
1732 then choose to omit, wrap or re-export these to Lua scripts.
1734 • Always grab any functions used into local variables so nobody
1737 • Don't use global variables in kernel (except for those passed).