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 -library library -autoexec assemble.jpcrrinit
39 The “-library library” specifies that contents of directory
40 'library' are to be used as library. The script pops up settings
41 for new emulated PC (if you want to load savestate, click
42 cancel). Select BIOS and VGABIOS for BIOS and VGABIOS image (they
43 should be already selected), DOSfloppy for fda (boot device
44 should be set to fda) and game image as some HD drive
48 • Putting the game as hdd (the fourth hard disk slot) causes boot
51 • Some BIOS versions have “press F12 to select boot device”. Hit
52 <enter> from emulated keyboard and that prompt will go away in
53 about half emulated second (it stays several emulated seconds
56 • If game doesn't need lots of memory, hitting F5 to skip
57 intialization files is fastest. If it does need more memory,
58 run config.sys commands but not autoexec.bat.
60 • Some DOS disks have DOSIDLE with them, don't use it as it
61 messes badly with emulator.
63 3 Making JPC-RR format images from raw images
65 Due to various factors, JPC-RR can't use raw image files directly
66 but requires its own image format.
68 3.1 Importing images from GUI:
70 Use Drives -> Import Image to import existing directories or
71 image files. Dialog prompting parameters will be displayed. When
72 importing floppy images, check “standard geometry” if possible,
73 that enables geometry autodetection, which is reasonable
74 virtually all of the time it is offered.
78 • If making image from directory, the names of the files must
79 conform to FAT naming restrictions (8+3 character names, no
80 spaces, etc). Avoid filenames with non-ASCII characters.
82 • The DOS limit of 112 or 224 files for floppies does not apply
83 to images created from directory trees. The minimum limit value
84 used is 512. If even that isn't enough, the limit is
85 automatically increased to fit all the needed directory
88 • Making boot disks from tree does NOT work. Even if you got
89 system boot files there, it still won't work.
91 • Only floppy disks and hard drives can be made from directory
92 trees. BIOS images and CDROM images require image file.
94 • Avoid floppies with custom geometry (floppy geometry does
95 affect disk ID). Disks with over 63 sectors per track don't
96 work with DOS. Wheither disks with over 127 tracks per side
97 work with DOS is unknown. Also avoid 1024-tracks per side HDDs.
99 • The geometry limits are: 2-1024 tracks per side for HDD, 1-256
100 tracks per side for floppy. 1-63 sectors per track for HDD,
101 1-255 sectors per track for floppy. 1-16 sides for HDD, 1 or 2
102 sides for floppy. This gives size limit of 65280KiB for floppy
103 disks (but note the DOS limit!) and 516096KiB for HDDs.
105 • There are multiple image file contents that represent the same
106 image. The one with smallest size is picked when creating
109 • Note: Although the IDs are 128 bits long, they are not MD5
112 3.3 Importing from command line
114 There is tool called ImageMaker that can make JPC-RR images from
115 raw images. Each image has format, ID an name. Format and name
116 are specified when making image. ID is automatically calculated
117 from format and contents. Name does not affect the ID but is
118 purely for convience so one doesn't have to specify long image
123 The syntax for ImageMaker when making images is:
125 $ java ImageMaker <format> [<options>...] <destination> <source>
128 <destination> is file name for JPC-RR format image to write.
129 <source> is either name of regular file (raw image file) or name
130 of directory tree with files (supported for making floppy or hard
131 disk images only). In case of directory tree, the files are
132 layout deterministically to disk, so the ID will always be the
133 same for given geometry and type. <name> is name to give to disk.
136 --BIOS BIOS image (note: VGABIOS is also of this type).
138 --CDROM CD-ROM image.
140 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
142 --floppy=tracks,sectors,sides Floppy disk with specified
145 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
147 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
149 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
151 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
153 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
155 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
157 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
159 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
161 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
163 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
165 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
167 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double
170 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double
173 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double
176 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double
179 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double
182 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double
185 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double
188 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double
191 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double
194 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double
197 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double
200 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double
203 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double
206 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double
209 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double
212 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double
215 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double
218 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double
223 --volumelabel=label Give specified volume label (affects ID).
224 Only meaningful when making image out of directory tree. Default
227 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files
228 (affects ID). Only meaningful when making image out of directory
229 tree. The default timestamp is 19900101T000000Z.
231 3.3.3 Image information
235 $ java ImageMaker <imagefile>
237 Variety of information about image is displayed (especially for
238 floppies/HDDs). Two important fields are calculated and claimed
239 disk ID. They should be the same. If they are not, then the image
240 file is corrupt (sadly, imagemaker has bugs and bugs that cause
241 it to write corrupt images have been seen).
243 3.4 Advanced: The disk ID algorithm
245 The disk ID is calculated as:
247 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
249 Where Skein-256-128-deprecated is Skein hash function with
250 256-bit internal state and 128-bit output using the deprecated
251 rotation constants (as specified in Skein hash function reference
252 documentation versions 1.0 and 1.1). The <image> is the whole
253 image, including parts not stored in image file. The reason for
254 keeping using the deprecated constants are:
256 • Changing the constants would change the IDs, which would
257 invalidate existing images
259 • This is not about cryptographic security
261 • The new constants don't improve security that much anyway.
263 3.4.1 Floppies and HDDs
265 Floppies have <typecode> value 0 (single byte) and HDDs have 1
266 (single byte). <geometry> is as follows (this is exactly the same
267 form as it appears in image header):
269 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
271 Byte 0 bits 2-5: Head count - 1.
273 Byte 0 bits 6-7: Reserved, must be 0.
275 Byte 1: Bits 0-7 of track count per side - 1.
277 Byte 2: Sector count per track - 1.
279 3.4.2 CD-ROM and BIOS images
281 CD-ROMs have <typecode> value 2 (single byte) and BIOS images
282 have 3 (single byte). <geometry> is blank.
284 3.5 Advanced: Disk Image format
286 The disk image consists of following parts, concatenated in this
287 order without padding:
299 • type-specific geometry/size data
307 Magic in disk image files is following 5 bytes: “IMAGE”
311 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
315 Type code is single byte. 0 for floppies, 1 for HDDs, 2 for
316 CD-ROMs and 3 for BIOS images. Other values are reserved.
318 3.5.4 Disk name length
320 Obsolete. Disk name length is given as two-byte big-endian value.
321 New images should have 0 here.
325 Ignored. Name field is there for backward compatiblity. Disk name
326 length gives length of this field in bytes.
328 3.5.6 Type-specific geometry/size data (floppies and HDDs)
330 Floppies and HDDs have 3-byte geometry data:
332 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
334 Byte 0 bits 2-5: Head count - 1.
336 Byte 0 bits 6-7: Reserved, must be 0.
338 Byte 1: Bits 0-7 of track count per side - 1.
340 Byte 2: Sector count per track - 1.
342 3.5.7 Type specific-geometry/size data (CD-ROMs)
344 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
346 3.5.8 Type specific-geometry/size data (BIOS images)
348 BIOS images have 4-byte big-endian byte (not sector or block)
351 3.5.9 Actual image data (floppy/HDD)
353 Floppy or HDD imagedata consists of following subparts:
363 Storage method is single byte. Sectors present gives number of
364 last nonzero sector + 1 (zero if image is all zeroes)
366 3.5.10 Floppy/HDD storage method 0: Raw storage
368 This storage method has empty header. Image data is raw dump of
369 first sectors present sectors.
371 3.5.11 Floppy/HDD storage method 1: Sectormap
373 Image data header contains bitfield with just enough bytes to
374 have one bit per present sector. The order of bits is such that
375 number of bit corresponding to each sector in byte is sector
376 number modulo 8 and byte number is floor of sector number divided
377 by 8 when sector numbers are counted from zero. If bit
378 corresponding to sector is set, then the sector is present in
379 image data, otherwise it is absent and assumed to be all-zeroes.
381 Image data contains dumps of all present sectors in order of
382 increasing sector number.
384 3.5.12 Floppy/HDD storage method 2: Extent first sector zero
386 Image data is empty as storage-specific data is mangled with
387 image data. The image data alternates between blocks encoding
388 zero sectors and blocks encoding nonzero sectors. The first block
389 encodes zero sectors.
391 Block encoding zero sectors consist of single 1-4 byte
392 little-endian value encoding number of sectors in block - 1.
393 Number of bytes is determined by sectors present value. It is 1
394 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
395 for more than 16777216. All sectors in block are filled with
396 zeroes and are not stored.
398 Block encoding nonzero sectors has same block count as zero
399 sector block but is followed by the sectors stored raw.
401 3.5.13 Floppy/HDD storage method 3: Extent first sector nonzero
403 Same as storage method 2 but first block is nonzero sector block.
405 3.5.14 Actual image data (CD-ROMs and BIOS images)
407 These store image data raw. The amount of data is specified by
412 Comments are given as list of strings, with UTF-8 encoded strings
413 following 2-octet big-endian length. Comment list is terminated
414 by entry with length 0 (0x00 0x00). Comments are optional and may
417 4 The actual emulator
419 The actual emulator is invoked as:
421 $ java JPCApplication <options>...
423 The valid options are:
425 -autoexec <script> Execute contents of specified file as commands
428 -noautoexec Don't run autoexec files.
430 -norenames Copy&Delete files instead of renaming. Mainly meant
431 for debugging copy&delte code.
433 If no arguments are given, defaults of autoexec file of
434 'assemble.jpcrrinit' are used.
438 When emulator is started, command line comes up. Following
441 • 'exit': exit immediately. Dumps in progress are gracefully
444 • 'kill': Save stack traces and kill the emulator (for debugging
445 only). Any dumps in progress are likely corrupted.
447 • 'library <library>': set library directory to <library>.
449 • 'load <plugin>': Load plugin (no arguments)
451 • 'load <plugin>(<arguments>)': load plugin with arguments.
453 • 'command <command> [<arguments>...]': Invoke command via
454 external command interface.
456 • 'call<command> [<arguments>...]': Invoke command via external
457 command interface and print return values.
459 • 'lsdisks [<filename>]' Print listing of all known disks. If
460 <filename> is specified, save output to specified file.
462 • 'diskinfo [<filename>] <imagename>' Print Information about
463 <imagename> (can be disk name or ID). If <filename> is
464 specified, save output to specified file.
466 When one gets command line, its useful to load some plugins. See
467 section about plugins. Note: Load runner plugin
468 (PCControl/PCRunner and so) last, as some runners like to start
471 4.2 PC settings dialog notes
473 • CPU divider base frequency before division is 1GHz.
475 • Images can be specified by name or by ID. Name is relative to
476 library directory. If the image is in subdirectory of image
477 directory, the directory separator is is '/' regardless of what
480 • CD-ROM and hdc are mutually exclusive
482 • Modules is comma-seperated list of modules to load. To pass
483 arguments to some modules, enclose the arguments in (). Same
484 module can be specified twice only if parameters differ.
486 • Setting boot device doesn't work with some BIOS versions. Those
487 versions prompt the boot device anyway.
489 4.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 RAWVideoDumper) should not conflict because connector output
509 hold 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 4.4.1 plugin: org.jpc.plugins.PCControl
516 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1',
517 requires and uses GUI.
519 Runs the PC emulator core. Has capability to start/stop
520 emulation, breakpoint after certain time or start/end of VGA
521 vertical retrace. Also can create, savestate and loadstate PC
522 emulation. Memory dumping is supported.
524 'extramenu=<file>' causes Plugin to load extra menu entries from
525 <file>. 'uncompressedsave=1' causes savestates to be written
526 uncompressed (useful if they are stored in VCS supporting delta
529 4.4.2 plugin: org.jpc.plugins.PCRunner
531 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>'
532 Does not require nor use GUI.
534 Loads PC from savestate and just runs it. CTRL+C to quit. Also
535 automatically quits once stoptime is reached.
537 4.4.3 plugin: org.jpc.plugins.PCMonitor
539 No arguments, requires and uses GUI.
541 VGA monitor for emulated PC.
543 4.4.4 plugin: org.jpc.plugins.VirtualKeyboard
545 No arguments, requires and uses GUI.
547 On-screen keyboard for emulated PC.
549 4.4.5 plugin: org.jpc.plugins.PCStartStopTest
551 No arguments, requires and uses GUI.
553 Small plugin testing remote PC start/stop. Also supports sending
554 some common keypresses.
556 4.4.6 plugin: org.jpc.plugins.RAWVideoDumper
558 Takes 'rawoutput=<file>' as argument. Does not require nor use
561 Dumps all generated frames to RAW file <file>. Rawoutput is
562 required. The raw file consists of concatenation of zlib streams.
563 The uncompressed stream is concatenation of time skips (FFh FFh
564 FFh FFh), each acting as time offset of 2^32-1 nanoseconds and
565 saved frames. The saved frame has time offset in nanoseconds (big
566 endian) as first four bytes (must be at most 2^32-2, as 2^32-1 is
567 reserved for time skip). The next two bytes are big-endian width,
568 next two big-endian height. Finally frame has 4 * width * height
569 bytes of data that encodes pixels using 4 bytes per pixel, in
570 left-to-right, up-to-down order. Byte 0 of each pixel is
571 reserved, byte 1 is the red channel, byte 2 is green channel and
572 byte 3 is blue channel.
574 Dumping to pipe is supported.
576 4.4.7 plugin: org.jpc.plugins.RAWAudioDumper
578 Takes 'src=<name of audio output channel>',
579 'file=<output-filename>' and 'offset=<offset>' as arguments,
580 separated by ','. Does not require nor use GUI.
582 Dumps output from specified audio output channel (src, mandatory)
583 to RAW-format file (file, mandatory). The resulting file consists
584 of records, 4 or 8 bytes each. 4 byte record consists of 0xFF
585 0xFF 0xFF 0xFF and means to increase next time delta by 2^{32}-1
586 ns. Otherwise record is 8 bytes. Each 8 byte record has three
587 fields. First 4 byte unsinged big endian timedelta value (in
588 nanoseconds, must be smaller than 2^{32}-1), then 2 byte signed
589 big endian new left channel volume, then 2 byte signed big endian
590 new right channel volume. Optionally 'offset' can be set to
591 positive value (in nanoseconds) to delay the audio by.
593 4.4.8 plugin: org.jpc.plugins.LuaPlugin
595 Takes 'kernel=<name of lua kernel file>', other parameters are
596 passed to kernel, requires and uses GUI.
598 Lua VM for executing scripts.
600 4.4.9 plugin: org.jpc.plugins.JoystickInput
602 No parameters. Displays window for sending joystick input.
606 5.1 org.jpc.modules.Joystick:
610 • Resources: I/O port 0x201
612 Emulates joystick game port.
614 5.2 org.jpc.modules.SoundCard
616 • Arguments: Optional resources specification
618 • Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
622 5.3 org.jpc.modules.FMCard
624 • Arguments: Optional resources specification
626 • Resources (defaults): I/O port 0x338-0x33B
630 5.4 org.jpc.modules.BasicFPU:
636 Crude FPU (x87) emulator.
640 Hacks are saved to savestates but not movies.
644 Force bit 1 of physical address 0x0410 to zero, signaling that
645 the system has no FPU. BIOS assumes system has FPU but some games
646 use that bit to detect FPU, trying to use it if it is “present”.
647 Try this if game startup hangs with lots of trying to use FPU but
648 not present errors. Don't use if there is FPU present. Needed to
649 get games like Blake Stone / Wolfenstein 3-D to work (FPU
650 emulator allows it to start but causes graphical glitches).
654 Update basic VGA parameters before vretrace, not after it. Some
655 games (e.g. Commander Keen 4) don't like if this isn't done and
656 some games (e.g. Mario & Luigi) don't like if it is done. Wrong
657 value manifests as jerky scrolling (scrolling back and forth and
658 fixed statusbars move).
660 7 Some error messages and explanations
662 • <filename> is Not a valid image file
664 • <filename> is not image file
666 • <filename> claims to be floppy with illegal geometry: <x>
667 tracks, <y> sides and <z> sectors.
669 • <filename> claims to be HDD with illegal geometry: <x> tracks,
670 <y> sides and <z> sectors.
672 • Can't read disk image sector map.
674 • Can't read disk image extent.
676 Code expects <filename> to be valid JPC-RR format image, but it
677 isn't JPC-RR image at all or its corrupt.
679 • <filename> is image of unknown type.
681 • <filename> has unrecognized geometry <x> <y> <z>
683 Possibly corrupt image, not JPC-RR image, or JPC-RR image from
684 future version containing something current version can't
687 • Invalid format specifier <something>.
689 • Invalid syntax of --floppy= or --HDD= option.
691 • Invalid format specifier/option <something>.
693 Invalid option or format specifier was given. Check for typos.
695 • java ImageMaker [<options>...] <format> <destination> <source>
698 Check syntax of command. Especially that diskname is present!
700 • The image has <nnn> sectors while it should have <yyy>
701 according to selected geometry.
703 • Raw image file length not divisible by 512.
705 • Trying to read sector out of range.
707 The selected geometry is wrong or raw image is incomplete.
709 • Invalid disk name (Should not happen!).
711 • Invalid geometry to be written.
713 This is a very likely a bug in program.
715 • What the heck <filename> is? It's not regular file nor
718 That sort of file can't be used as input for image making, or the
719 file just doesn't exist.
721 • BIOS images can only be made out of regular files.
723 • CD images can only be made out of regular files.
725 Source image specified is not regular file, but image of that
726 type can't be made of anything else.
728 • Can't read raw bios image file.
730 • Can't read sector <nnn> from image.
732 Reading the raw image file failed for some reason.
734 • Bad library line: "<something>". Ignored.
736 Syntax error in image library.
738 • Removing image <something> a.k.a. "<something>" as it no longer
741 The image file no longer exists so it gets removed from library.
743 • Removing image <something> a.k.a. "<something>" due to <some>
746 Image library code killed some image from library due to some
747 kind of conflict with image being added.
749 • Too much data to fit into given space.
751 The tree you gave contains takes just too much space to fit into
754 8 Advanced: Savestate/movie format
756 8.1 Special character classes
760 Following Unicode codepoints (encoded as UTF-8) are interpretted
763 • Codepoints 0x20, and 0x09.
765 • Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
767 • Codepoints 0x2000-0x200A.
771 Following byte sequences are interpretted as linefeeds (line
774 • Byte 0x0A (UTF-8 encoded codepoint 0x0A)
776 • Byte 0x0D (UTF-8 encoded codepoint 0x0D)
778 • Byte 0x1C (UTF-8 encoded codepoint 0x1C)
780 • Byte 0x1D (UTF-8 encoded codepoint 0x1D)
782 • Byte 0x1E (UTF-8 encoded codepoint 0x1E)
784 • Bytes 0xC2 0x85 (UTF-8 for unicode control character NL,
787 • Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
791 JRSR archive format packs multiple text archive members to text
792 archive. It does not support binary members. JRSR archives have
793 first five or six bytes form the magic. It is “JRSR” followed by
794 LINEFEED character There are four kinds of lines after that
795 (lines are terminated by LINEFEED byte/bytes):
805 Sequencing rules are as follows: Start member is allowed anywhere
806 (after magic). Member line is allowed only inside member (member
807 started but not ended). End member is only allowed inside member.
808 End of file is only allowed outside member. Blank line is allowed
809 anywhere after magic.
813 Start member line is given as “!BEGIN” <SPACE>+ <membername>
814 <LINEFEED>. <SPACE>+ any number of SPACE characters at least one
815 and <LINEFEED> is LINEFEED chacter. The member name is UTF-8
816 encoded and maximum allowed line length is 2048 bytes (including
817 LINEFEED, which means name is limited to 509-2040 codepoints
818 depending on characters used). Starting member inside another
819 implicitly ends the previous member.
823 Member line is given as “+”<content><LINEFEED>. It gives another
824 line for member contents. <content> is passed raw to layers above
825 (followed by line termination)
829 End member line is given as “!END”<LINEFEED>. It ends the current
830 member. The following line can only be start member line or file
835 Blank line is given as <LINEFEED>. Lines like that are ignored.
837 8.3 Four-to-Five encoding
839 Binary members are encoded into text by so-called four-to-five
840 encoding. This encoding can encode single byte to two, two bytes
841 to three, three bytes to four and four bytes to five.
842 Four-to-five encoding has five kinds of blocks. All SPACE and
843 LINEFEED characters are completely ignored, even in middle of
846 8.3.1 End stream block
848 End stream block is encoded as '!'. It ends the stream instantly.
849 There is also implicit end of stream at end of input to decoding.
851 8.3.2 Other four block types
853 Other four block types take the value to be encoded, read it as
854 big-endian value. Then they write it as base-93 big-endian value.
855 Then length specific constants are added to digits of that number
856 to yield ASCII values for characters (those are stored in order):
859 +------------+------------+------------+------------+------------+-----------+
860 | To encode | 1st char. | 2nd char. | 3rd char. | 4th char. | 5th char. |
861 +------------+------------+------------+------------+------------+-----------+
862 +------------+------------+------------+------------+------------+-----------+
863 | 1 byte | 34 | 34 | - | - | - |
864 +------------+------------+------------+------------+------------+-----------+
865 | 2 bytes | 37 | 34 | 34 | - | - |
866 +------------+------------+------------+------------+------------+-----------+
867 | 3 bytes | 45 | 34 | 34 | 34 | - |
868 +------------+------------+------------+------------+------------+-----------+
869 | 4 bytes | 66 | 34 | 34 | 34 | 34 |
870 +------------+------------+------------+------------+------------+-----------+
873 Blocks which encode values greater than what is possible for
874 value of that length are fatal errors.
876 8.4 Line component encoing
878 Line component encoding sits on top of UTF-8 encoding. Line
879 component encoding encodes non-empty 1-D array of non-empty
880 strings into line, and thus array of those into member. Empty
881 lines or lines that don't contain any components are ignored.
882 Line starts with depth value of 0 and must end with depth value
885 Components are seperated by component separators. Empty
886 components are ignored. Following codepoints are separators on
887 depth 0 if not escaped:
889 • Codepoint of '('. The depth is read pre-increment.
891 • Codepoint of ')'. The depth is read post-decrement.
893 • Any SPACE character
895 The following characters are special:
897 • '('. Increments depth by 1 if not escaped (and appears in
900 • ')'. Decrements depth by 1 if not escaped (and appears in
901 component). Depth going negative is an error.
903 • '\'. Next character is interpretted as literal. Error if at end
906 Otherwise, characters are interpretted as literals and appear in
907 components. Depth must be zero at end of line.
911 Header section is in archive member "header". It uses line
912 component encoding. The first component of each line is name of
913 header, and subsequent ones are arguments. How many parameters
914 are expected is dependent on what header it is:
916 8.5.1 PROJECTID header:
918 • Header name: "PROJECTID"
922 • Argument #1: <project-id-string>
926 Gives project ID. Project ID is generated when PC is assembled
927 and is then preserved in save states. It is used for computing
928 rerecord counts. Emulator treats it as opaque string, the IDs it
929 generates are formed by 48 random hexadecimal digits.
931 8.5.2 SAVESTATEID header:
933 • Header name: "SAVESTATEID"
937 • Argument #1: <savestate-id-string>
941 Gives save state ID. Each save state has its own save state ID.
942 Treated as opaque string, but generated as 48 random hexadecimal
943 digits. The presence of this header signals whether there is save
944 state to be loaded. If this header is present, save state load
945 will be attempted. If absent, save state is not to be loaded even
946 if present (and correct savestate load would be technically
949 The value is used to prevent loading incompatible save states in
950 preserve event stream mode and also to find the point in event
951 stream where one left off.
953 8.5.3 RERECORDS header:
955 • Header name: "RERECORDS"
959 • Argument #1: <rerecords>
963 Gives rerecord count. PC assembly (except when loading save
964 state) initializes current rerecord count to zero. Must be
965 non-negative and decimal number using ASCII digit characters.
967 On loading save state:
969 1) If project ID matches with previous:
971 1a) If loaded rerecord count is larger or equal to current
974 1a-a) Current rerecord count is loaded rerecord count + 1.
978 1b-a) Current rerecord count increments by 1.
982 2a) Current rerecord count is loaded rerecord count + 1.
984 The current rerecord count at time of save is saved to save
989 • Header name: "SYSTEM"
993 • Argument #1: <system-id-string>
997 Gives system this movie/save is for. The only currently
998 recognized value is “PC-JPC-RR-r10” (if this header is absent,
999 use default system). Invalid values trigger error on load time.
1001 8.5.5 AUTHORS header:
1003 • Header name: "AUTHORS"
1005 • Components: 2 or more
1007 • Arguments: free form
1011 Gives authors of run. Each argument gives one author (who has
1012 full name but no nickname). May be present multiple times.
1014 8.5.6 AUTHORNICKS header:
1016 • Header name: "AUTHORNICKS"
1018 • Components: 2 or more
1020 • Arguments: free form
1024 Gives authors of run. Each argument gives one author (who has
1025 nickname but no full name). May be present multiple times.
1027 8.5.7 AUTHORFULL header:
1029 • Header name: "AUTHORFULL"
1033 • Arguments: free form
1037 Gives author of run. First argument is full name of author, and
1038 second is nickname of author. May be present multiple times.
1040 8.5.8 COMMENT header:
1042 • Header name: "COMMENT"
1044 • Components: 2 or more
1046 • Arguments: free form
1050 Various kinds of free form data. Not parsed further by emulator.
1052 8.6 Initialization segment:
1054 If SAVESTATEID header isn't present (not a save state), member
1055 "initialization" gives PC initialization parameters for
1056 assembling the PC. It is present anyway even if SAVESTATEID is
1057 present (savestate).
1059 Following parameters are used (space separates components):
1063 Gives Image ID of main system BIOS (mandatory)
1067 Gives Image ID of VGA BIOS (mandatory).
1071 Gives Image ID of hda. Present only if system has hard disk hda.
1075 Gives Image ID of hdb. Present only if system has hard disk hdb.
1079 Gives Image ID of hdc. Present only if system has hard disk hdc.
1083 Gives Image ID of hdd. Present only if system has hard disk hdd.
1087 Gives Image ID of disk in slot <num>. Slot number must be
1090 “DISKNAME” <num> <name>
1092 kGives image name of disk in slot <num>. Slot number must be
1093 non-negative. The slot must be previously declared using “DISK”.
1097 Gives Image slot to initially put into floppy drive fda. Disk
1098 must be of floppy type. If none present, no disk is initially put
1103 Gives Image slot to initially put into floppy drive fdb. Disk
1104 must be of floppy type. If none present, no disk is initially put
1109 Gives Image slot to initially put into CD-ROM drive hdc. Not
1110 allowed if hard disk hdc is present. Disk must be of CD-ROM type.
1111 If none present no disk is initially put there.
1113 "INITIALTIME" <time>
1115 Number of milliseconds since Unix epoch to system start up time.
1118 0-4102444799999. Mandatory.
1120 "CPUDIVIDER" <divider>
1122 Set CPU frequency divider (dividing the 1GHz master clock).
1123 Allowed range is 1-256. Mandatory.
1125 "MEMORYSIZE" <pages>
1127 Number of 4KiB pages of RAM memory. Allowed range 256-262144.
1132 Set boot device. Valid devices are "FLOPPY" (boot from fda),
1133 "HDD" (boot from hda) and "CDROM" (boot from CD).
1135 "LOADMODULEA" <module> <parameters>
1137 Load module <module> with parameters <parameters>.
1139 "LOADMODULE" <module>
1141 Load module <module> with no parameters
1145 Use class <fpu> as FPU emulator.
1149 Use I/O port delay emulation (each I/O port read/write takes
1154 Emulate VGA horizontal retrace.
1156 8.7 Event record format:
1158 Event record is in archive member "events". It uses line
1159 component encoding. Each line gives an event. First component of
1160 each line gives time stamp. These timestamps MUST be in
1161 increasing order and all MUST be non-negative. Time stamp time
1162 unit is exactly 1 nanosecond of emulated time.
1164 The second component of each line is name of class to dispatch
1165 to. Further components are passed as-is to event handlers.
1166 Classes with names consisting only of uppercase A-Z and 0-9 are
1167 special and reserved. It is error to encounter unknown such
1170 8.7.1 Savestate event
1172 • Dispatch to: SAVESTATE
1174 • Argument #1: Savestate id
1176 • Argument #2 (optional): Rerecord count at time of saving
1179 Signals that savestate has occured here. The save state IDs MUST
1180 be unique in entire event stream. The second argument to
1181 savestate (if present) is rerecord count at time of saving that
1182 savestate (useful for calulating rerecord count of movie starting
1183 from savestate). No time restrictions
1187 • Dispatch to: OPTION
1189 • Argument #1: “ABSOLUTE” or “RELATIVE”
1191 Controls various options. “ABSOLUTE” turns on absolute mode
1192 (default) where event timestamps are absolute. “RELATIVE” turns
1193 on relative mode where event timestamps are relative to last
1194 event in stream. The OPTION event itself is not affected by
1195 timing change. No time restrictions. Unknown arguments are
1198 8.7.3 Keyboard keypress/keyrelease event:
1200 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1202 • Argument #1: Fixed: "KEYEDGE"
1204 • Argument #2: Key number. Valid values are 1-83, 85-95, 129-197
1207 Send key press or key release. Keys work in toggle button manner.
1208 The event time must be multiple of 66 666, and must not be less
1209 than 60 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs
1210 after last KEYEDGE on key >128 and 10 * 66 666 TUs after last
1211 KEYEDGE on key <128.
1215 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1217 • Argument #1: Fixed: "PAUSE"
1219 Send pause key event. The time restrictions are identical to
1222 8.7.5 Mouse button event:
1224 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1226 • Argument #1: Fixed: "MOUSEBUTTON"
1228 • Argument #2: Number of button to release or press (0-4)
1230 Presses or releases the designated mouse button.
1232 8.7.6 X mouse motion event:
1234 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1236 • Argument #1: Fixed: "XMOUSEMOTION"
1238 • Argument #2: Number of units to move (-255 - 255)
1240 Move the mouse in X direction by specified amount. Positive is
1243 8.7.7 Y mouse motion event:
1245 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1247 • Argument #1: Fixed: "YMOUSEMOTION"
1249 • Argument #2: Number of units to move (-255 - 255)
1251 Move the mouse in Y direction by specified amount. Positive is
1254 8.7.8 Z mouse motion event:
1256 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1258 • Argument #1: Fixed: "ZMOUSEMOTION"
1260 • Argument #2: Number of units to move (-7 - 7)
1262 Move the mouse in Z direction (scrollwheel) by specified amount.
1264 8.7.9 Joystick button event:
1266 • Dispatch to: org.jpc.modules.Joystick
1268 • Argument #1: “BUTTONA”, “BUTTONB”, “BUTTONC” or “BUTTOND”
1270 • Argument #2: “0” if released, “1” if pressed
1272 Send button down/up event. No time restrictions.
1274 8.7.10 Joystick axis event:
1276 • Dispatch to: org.jpc.modules.Joystick
1278 • Argument #1: “AXISA”, “AXISB”, “AXISC” or “AXISD”
1280 • Argument #2: Multivibrator unstable state length in ns.
1282 Set amount of time multivibrator remains in unstable state. No
1287 • Dispatch to: org.jpc.emulator.PC$ResetButton
1293 8.7.12 Fda disk change:
1295 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1297 • Argument #1: Fixed: "FDA"
1299 • Argument #2: Number of image slot to put there.
1301 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1302 used if there is no disk in floppy drive A. This event causes
1303 specified disk to be placed to FDA or FDA disk to be ejected with
1304 no replacement if disk number is -1. The specified disk if not -1
1305 must be of floppy type. The specified disk if valid must not be
1308 8.7.13 Fdb disk change:
1310 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1312 • Argument #1: Fixed: "FDB"
1314 • Argument #2: Number of image slot to put there.
1316 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1317 used if there is no disk in floppy drive B. This event causes
1318 specified disk to be placed to FDB or FDB disk to be ejected with
1319 no replacement if disk number is -1. The specified disk if not -1
1320 must be of floppy type. The specified disk if valid must not be
1323 8.7.14 Change CDROM:
1325 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1327 • Argument #1: Fixed: "CDROM"
1329 • Argument #2: Number of image slot to put there.
1331 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1332 used if there is no disk in CD-ROM. This event causes specified
1333 disk to be placed to CD-ROM or CD-ROM disk to be ejected with no
1334 replacement if disk number is -1. The specified disk if not -1
1335 must be of CD-ROM type.
1337 This event has no effect if CD-ROM is locked.
1339 8.7.15 Write protect floppy:
1341 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1343 • Argument #1: Fixed: "WRITEPROTECT"
1345 • Argument #2: Number of image slot to manipulate
1347 Write protects specified disk. The disk MUST NOT be in any drive
1348 and MUST be valid floppy-type disk.
1350 8.7.16 Write unprotect floppy:
1352 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1354 • Argument #1: Fixed: "WRITEUNPROTECT"
1356 • Argument #2: Number of image slot to manipulate
1358 Disables write protection specified disk. The disk MUST NOT be in
1359 any drive and MUST be valid floppy-type disk.
1361 8.8 Diskinfo sections
1363 Diskinfo sections are named “diskinfo-”<id of disk>. They use
1364 line component encoding, fieldtype being first component on each
1365 line (value being the second). Following fields are defined:
1369 Gives type of image. Possible values are
1371 • “FLOPPY” (floppy disk)
1377 • “BIOS” (BIOS/VGABIOS image)
1379 • “UNKNOWN” (what the heck is this???)
1387 (BIOS images only) Gives length of BIOS image
1391 MD5 of raw disk/BIOS image without any headers or trailers.
1395 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
1399 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256
1400 for floppy, 1-1024 for HDD).
1404 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for
1405 floppy, 1-16 for HDD).
1409 (FLOPPY/HDD images only) Number of sectors per track (1-255 for
1410 floppy, 1-63 for HDD).
1414 Line from image comment block. Usually give data about files
1415 image has. May or may not be present (multiple times)
1419 Output info is stored in section “output-info”. Its relatively
1420 new, so it might not be present (then the contents have to be
1421 guessed based on modules present). Each line gives information
1422 about one output, first field being the type of output.
1426 For video output, there are no parameters so line is just “VIDEO”
1431 For audio output, the only parameter is name of output, so first
1432 component is “AUDIO” and second component is name of audio
1437 Actual savestate format is not documented here. It is close to
1438 impossible to comprehend without access to emulator source
1441 9 Advanced: Making class dumpable
1443 Class is made dumpable by implementing interface
1444 org.jpc.emulator.SRDumpable and implementing method
1445 dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
1446 <init>(org.jpc.emulator.SRLoader). Non-static inner classes can
1447 not be dumpable (make them static using tricks similar to what
1450 If dumped class has dumpable superclass, the first thing dumping
1451 function needs to do is to call dumper function of superclass and
1452 first thing loading constructor needs to do is to call loading
1453 constructor of superclass. If class has no dumpable superclass,
1454 dumper doesn't need to do anything special, while loader needs to
1455 call objectCreated(this) on SRLoader object passed as parameter.
1457 Following these fixed parts, dump all members that are part of
1458 mutable state in emulator core.
1460 9.1 Member dumping/loading functions
1462 There is dumping/loading function for following (all functions
1463 dumping/loading reference types can handle null):
1465 • boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
1467 • byte: SRDumper.dumpByte, SRLoader.loadByte
1469 • short: SRDumper.dumpShort, SRLoader.loadShort
1471 • int: SRDumper.dumpInt, SRLoader.loadInt
1473 • long: SRDumper.dumpLong, SRLoader.loadLong
1475 • String: SRDumper.dumpString, SRLoader.loadString
1477 • boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
1479 • byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
1481 • short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
1483 • int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
1485 • long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
1487 • double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
1489 • <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
1491 • special object: SRDumper.specialObject, SRLoader.specialObject
1495 • Dumpable objects come out as type of
1496 org.jpc.emulator.SRDumpable.
1498 • Special objects are various static objects that don't need to
1499 be stored because they don't have mutable fields.
1501 • Don't dump fields related to event state feedback.
1503 • Don't dump temporary flags that are only used while PC is
1504 running. Savestate when PC is running isn't possible anyway.
1506 • Some connectors dump fields related to connector output, some
1509 10 Advanced: Making output connectors
1511 Implementing interface org.jpc.emulator.DisplayController signals
1512 that this is display controller, inhibiting loading of the
1513 standard VGA display controller if loaded as module.
1515 10.1 Interface org.jpc.emulator.OutputConnector
1517 Class is made to be output connector by implementing this
1518 interface. This interface specifies the methods used for output
1519 hold locking. Class org.jpc.emulator.OutputConnectorLocking has
1520 implementations of these that are suitable for calling.
1522 10.1.1 Method subscribeOutput(Object)
1524 Subscribes the output, with specified object as handle.
1526 10.1.2 Method unsubscribeOutput(Object)
1528 Unsubscribe the specified handle object from output.
1530 10.1.3 Method waitOutput(Object)
1532 Wait for output on specified connector using specified handle
1533 object. Returns true on success, false if wait was interrupted by
1534 thread interrupt. Blocking.
1536 10.1.4 Method releaseOutput(Object)
1538 Release connector from p.o.v. of given handle. Does not block.
1540 10.1.5 Method holdOutput()
1542 Release threads waiting on waitOutput() and block until all
1543 subscribers have returned from waitOutput() and enteired
1546 10.1.6 Method releaseOutputWaitAll(object)
1548 Like releaseOutput(), but waits until all handles have released
1551 10.2 Class org.jpc.emulator.VGADigtalOut
1553 Class org.jpc.emulator.VGADigtalOut (already implements
1554 OutputConnector) implements VGA output connector. If module
1555 provodes output connector, it needs to implement
1556 org.jpc.emulator.DisplayController.
1558 10.2.1 Method getWidth()
1560 Get width of display (watch out, can return 0).
1562 10.2.2 Method getHeight()
1564 Get height of display (watch out, can return 0).
1566 10.2.3 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(),
1569 Returns the dirty region (region modified since last output).
1571 10.2.4 Method getBuffer()
1573 Get buffer of ints, at least width * height elements
1574 (left-to-right, top-down, one value per pixel) giving pixel data.
1575 Value for each pixel is 65536 * <red-component> + 256 *
1576 <green-component> + <blue-component>.
1578 10.2.5 Method resizeDisplay(int _width, int _height)
1580 Resize the display to be of specified size.
1582 10.2.6 Method dirtyDisplayRegion(int x, int y, int w, int h)
1584 Mark the specified region as dirty.
1586 10.2.7 Method resetDirtyRegion()
1588 Resets the dirty region to be empty.
1590 10.3 Class org.jpc.emulator.PC method getVideoOutput()
1592 Get VGA output connector for PC.
1594 10.4 Interface org.jpc.emulator.DisplayController.
1596 Implementing this class signals that module is VGA controller.
1597 There can be only one such module active at time and presence of
1598 such module prevents loading builtin VGA controller emulation
1601 10.4.1 Method getOutputDevice()
1603 Get VGA output connector for this VGA device.
1605 10.5 Class org.jpc.emulator.SoundDigitalOut
1607 Class org.jpc.emulator.SoundDigitalOut provodes output connector
1608 for sound. Each connector can transfer stereo signal at arbitiary
1609 sampling rate. Modules that have audio connectors need to
1610 implement interface org.jpc.emulator.SoundOutputDevice, as this
1611 signals that output connectors should be created.
1613 10.5.1 Method addSample(long, short, short)
1615 Add stereo sample at time given by first argument. The second and
1616 third arguments give volume on left and right channels.
1618 10.5.2 Method addSample(long, short)
1620 Add mono sample at time given by first argument. The second
1621 argument give volume on both channels.
1623 10.5.3 Method readBlock(Block)
1625 Reads block of output (atomic versus addSample). Block structure
1626 has following fields which are filled:
1628 • timeBase: Time base for block.
1630 • baseLeft: Left volume at time base.
1632 • baseRight: Right volume at time base
1634 • blockNo: Sequence number of block filled.
1636 • samples: Number of samples in block
1638 • sampleTiming: Number of nanoseconds since last sample
1640 • sampleLeft: Left channel samples
1642 • sampleRight: Right channel samples
1644 10.6 Interface org.jpc.emulator.SoundOutputDevice
1646 Implementing this interface signals that module has audio output
1650 org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
1652 Return the number of sound channels module has.
1655 org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
1657 This is called once per sound channel requested giving precreated
1660 10.7 Class org.jpc.emulator.PC method getSoundOut(String)
1662 Get sound output with specified name.
1664 11 Advanced: Writing event targets
1666 Whereas output connectors are the way output is dispatched, input
1667 is dispatched via event targets. Event targets need to implement
1668 interface org.jpc.emulator.EventDispatchTarget.
1670 Event targets also provode methods which then encode events and
1671 dispatch them forward (without doing anything else) to event
1672 recorder. Also, event targets may have methods for obtaining
1675 11.1 Interface org.jpc.emulator.EventDispatchTarget
1677 Interface that marks class capable of receiving events.
1679 11.1.1 Method setEventRecorder(EventRecorder)
1681 Set the event recorder input events are sent to.
1683 11.1.2 Method startEventCheck()
1685 Signals target to reset all state related to event checking and
1686 state feedback. This may be called at any time in order to
1687 reinitialialize event checking/feedback state.
1689 11.1.3 Method doEvent(long, String[], int) throws IOException
1691 Event dispatch handler. The first argument is event time, second
1692 is parameters and third is what to do with it. If target doesn't
1693 like the event, throw IOException. Following types (the integer
1694 parameter) are used:
1696 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
1698 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in
1699 event replay for reinitialization
1701 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay
1704 3 (EventRecorder.EVENT_EXECUTE): This event occurs now. Execute
1707 11.1.4 Method endEventCheock()
1709 End event reinitialization. Usually unused.
1711 11.1.5 Method getEventTimeLowBound(long, String[]) throws
1714 Return the time value that's the earliest possiblity for this
1715 event to occur. Returning any time in past (including -1) causes
1716 event to fire as soon as possible. The long parameter gives the
1717 current scheduled time for event.
1721 Modules are various extensions that run inside emulator core. As
1722 such, they affect sync. Modules must implement interface
1723 org.jpc.emulator.HardwareComponent (they are hardware components)
1724 and must be dumpable. Additionally, they need either constructor
1725 <init>() or <init>(String). The first is if no parameters are
1726 passed, the second is for case where parameters are passed.
1728 Aside of the constructors, modules need to obey the ordinary
1729 conventions for hardware components. No code outside modules
1730 needs to know that module exists.
1734 Plugins handle various UI tasks. They need to implement interface
1737 13.1 Interface org.jpc.pluginsbase.Plugin
1739 13.1.1 Method systemShutdown()
1741 Called when emulator shuts down. Either called in dedicated
1742 thread or in thread that called emulatorShutdown(). These
1743 handlers should do the bare minimum to get files on disk to
1744 consistent state. After these calls from all plugins have
1745 finished, emulator exits. Do not try to manipulate UI from these
1746 methods, as doing that easily leads into deadlock.
1748 13.1.2 Method reconnect(PC)
1750 Gives new PC to connect to. Null is passed if plugin should
1753 13.1.3 Method main()
1755 Called in dedicated thread after plugin is initialized.
1757 13.1.4 Method pcStopping()
1759 Called after PC has stopped.
1761 13.1.5 Method pcStarting()
1763 Called before PC starts.
1765 13.1.6 Method notifyArguments(String[])
1767 Pass arguments from command line.
1769 13.1.7 Constructor <init>(Plugins)
1771 This constructor is used to initialize plugins that don't take
1774 13.1.8 Constructor <init>(Plugins, String)
1776 This constructor is used to initialize plugins that take
1779 13.2 Class org.jpc.pluginsbase.Plugins
1781 This class provodes various methods for manipulating plugins.
1783 13.2.1 Method isShuttingDown()
1785 Returns true if Plugins.shutdownEmulator() has been called
1786 somehow, either via VM exit, CTRL+C or explicitly. Useful to skip
1787 cleanups involving GUI, as these are too deadlock-prone.
1789 13.2.2 Method shutdownEmulator()
1791 Shut down and exit the emulator. All plugin shutdown functions
1792 are called in this thread.
1794 13.2.3 Method reconnectPC(PC)
1796 Signal reconnectPC event to all plugins.
1798 13.2.4 Method pcStarted()
1800 Signal pcStarting() event to all plugins.
1802 13.2.5 Method pcStopped()
1804 Signal pcStopping() event to all plugins.
1806 14 Inter-plugin communication
1808 14.1 Receiving communications
1810 To receive invocation/call by name 'foo-bar', declare public
1811 method named 'eci_foo_bar'. Arguments to this method can
1812 currently be String, Integer (int) or Long (long). Last argument
1813 may be array over these types to get variable number of
1814 arguments. On call, each argument gets value from call. If last
1815 argument is array, it gets all overflowing arguments. If return
1816 type is void or method returns boolean false, call is assumed to
1817 have completed. If return value is boolean true, it is assumed
1818 that there is more processing.
1821 org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd,
1824 Invoke command asynchronously, broadcasting to all plugins. Does
1825 not wait for slow commands to complete. cmd is the name to send
1826 and args are the arguments to pass.
1829 org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String
1832 Same as invokeExternalCommand, but waits for slow commands to
1836 org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String
1839 Similar to invokeExternalCommandSynchornous, but:
1841 • Quits calling more plugins when it gets successful reply.
1843 • Returns said reply
1845 14.5 void org.jpc.pluginsbase.Plugins.returnValue(Object... ret)
1847 Gives return value to return from call and signals that command
1850 14.6 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
1852 Signals that command has completed. Only needed if there is no
1853 return value and eci_ method returned false (not done yet).
1855 15 Lua kernel programming
1857 At startup, kernel gets its arguments in 'args' table and the
1858 script name to run in 'scriptname' string. It should enter the
1859 named script in protected mode.
1861 The Lua VM exports numerious callbacks to kernel. The kernel can
1862 then choose to omit, wrap or re-export these to Lua scripts.
1864 • Always grab any functions used into local variables so nobody
1867 • Don't use global variables in kernel (except for those passed).