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
20 See compile.sh. The stuff in streamtools is only needed for
25 See compile.sh. The streamtools stuff is only needed for dumping
30 First you need to get and make some important images. Obtain BIOS
31 image, VGABIOS image and DOS boot floppy from somewhere and do:
35 java ImageMaker --BIOS library/BIOS <bios image file>
37 java ImageMaker --BIOS library/VGABIOS <vgabios image file>
39 java ImageMaker --floppy1440 library/DOSfloppy <dos floppy name>
41 This makes loadable images out of what you obtained. Most DOS
42 boot floppies are 1440KiB in size (if yours isn't change that
43 floppy1440 part). You also might want to make some game images:
45 java ImageMaker --HDD=128,63,16 library/somegame <game
46 installation directory>
48 This makes ~128MB HDD image out of installation directory.
52 There is premade autoexec script called assemble.bat that has
53 fairly reasonable defaults. To use it:
55 java JPCApplication -library library -autoexec assemble.bat
57 The “-library library” specifies that contents of directory
58 'library' are to be used as library. The script pops up settings
59 for new emulated PC (if you want to load savestate, click
60 cancel). Select BIOS and VGABIOS for BIOS and VGABIOS image (they
61 should be already selected), DOSfloppy for fda (boot device
62 should be set to fda) and game image as some HD drive
66 • Putting the game as hdd causes boot to be bit faster.
68 • Some BIOS versions have “press F12 to select boot device”. Hit
69 <enter> from emulated keyboard and that prompt will go away in
70 about half emulated second (it stays several emulated seconds
73 • If game doesn't need lots of memory, hitting F5 to skip
74 intialization files is fastest. If it does need more memory,
75 run config.sys commands but not autoexec.bat.
77 • Some DOS disks have DOSIDLE with them, don't use it as it
78 messes badly with emulator.
80 3 Making JPC-RR format images from raw images
82 Due to various factors, JPC-RR can't use raw image files directly
83 but requires its own image format. There is tool called
84 ImageMaker that can make JPC-RR images from raw images. Each
85 image has format, ID an name. Format and name are specified when
86 making image. ID is automatically calculated from format and
87 contents. Name does not affect the ID but is purely for convience
88 so one doesn't have to specify long image IDs manually.
92 The syntax for ImageMaker when making images is:
94 $ java ImageMaker <format> [<options>...] <destination> <source>
97 <destination> is file name for JPC-RR format image to write.
98 <source> is either name of regular file (raw image file) or name
99 of directory tree with files (supported for making floppy or hard
100 disk images only). In case of directory tree, the files are
101 layout deterministically to disk, so the ID will always be the
102 same for given geometry and type. <name> is name to give to disk.
105 --BIOS BIOS image (note: VGABIOS is also of this type).
107 --CDROM CD-ROM image.
109 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
111 --floppy=tracks,sectors,sides Floppy disk with specified
114 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
116 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
118 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
120 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
122 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
124 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
126 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
128 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
130 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
132 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
134 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
136 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double
139 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double
142 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double
145 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double
148 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double
151 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double
154 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double
157 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double
160 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double
163 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double
166 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double
169 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double
172 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double
175 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double
178 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double
181 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double
184 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double
187 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double
192 • If making image from directory, the names of the files must
193 conform to FAT naming restrictions (8+3 character names, no
194 spaces, etc). Avoid filenames with non-ASCII characters.
196 • The DOS limit of 112 or 224 files for floppies does not apply
197 to images created from directory trees. The minimum limit value
198 used is 512. If even that isn't enough, the limit is
199 automatically increased to fit all the needed directory
202 • Making boot disks from tree does NOT work. Even if you got
203 system boot files there, it still won't work.
205 • Only floppy disks and hard drives can be made from directory
206 trees. BIOS images and CDROM images require image file.
208 • Avoid floppies with custom geometry (floppy geometry does
209 affect disk ID). Disks with over 63 sectors per track don't
210 work with DOS. Wheither disks with over 127 tracks per side
211 work with DOS is unknown. Also avoid 1024-tracks per side HDDs.
213 • The geometry limits are: 2-1024 tracks per side for HDD, 1-256
214 tracks per side for floppy. 1-63 sectors per track for HDD,
215 1-255 sectors per track for floppy. 1-16 sides for HDD, 1 or 2
216 sides for floppy. This gives size limit of 65280KiB for floppy
217 disks (but note the DOS limit!) and 516096KiB for HDDs.
219 • There are multiple image file contents that represent the same
220 image. The one with smallest size is picked when creating
223 • Note: Although the IDs are 128 bits long, they are not MD5
228 --volumelabel=label Give specified volume label (affects ID).
229 Only meaningful when making image out of directory tree. Default
232 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files
233 (affects ID). Only meaningful when making image out of directory
234 tree. The default timestamp is 19900101T000000Z.
236 3.4 Image information
240 $ java ImageMaker <imagefile>
242 Variety of information about image is displayed (especially for
243 floppies/HDDs). Two important fields are calculated and claimed
244 disk ID. They should be the same. If they are not, then the image
245 file is corrupt (sadly, imagemaker has bugs and bugs that cause
246 it to write corrupt images have been seen).
248 3.5 Advanced: The disk ID algorithm
250 The disk ID is calculated as:
252 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
254 Where Skein-256-128-deprecated is Skein hash function with
255 256-bit internal state and 128-bit output using the deprecated
256 rotation constants (as specified in Skein hash function reference
257 documentation versions 1.0 and 1.1). The <image> is the whole
258 image, including parts not stored in image file. The reason for
259 keeping using the deprecated constants are:
261 • Changing the constants would change the IDs, which would
262 invalidate existing images
264 • This is not about cryptographic security
266 • The new constants don't improve security that much anyway.
268 3.5.1 Floppies and HDDs
270 Floppies have <typecode> value 0 (single byte) and HDDs have 1
271 (single byte). <geometry> is as follows (this is exactly the same
272 form as it appears in image header):
274 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
276 Byte 0 bits 2-5: Head count - 1.
278 Byte 0 bits 6-7: Reserved, must be 0.
280 Byte 1: Bits 0-7 of track count per side - 1.
282 Byte 2: Sector count per track - 1.
284 3.5.2 CD-ROM and BIOS images
286 CD-ROMs have <typecode> value 2 (single byte) and BIOS images
287 have 3 (single byte). <geometry> is blank.
289 3.6 Advanced: Disk Image format
291 The disk image consists of following parts:
303 • type-specific geometry/size data
309 Magic in disk image files is following 5 bytes: “IMAGE”
313 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
317 Type code is single byte. 0 for floppies, 1 for HDDs, 2 for
318 CD-ROMs and 3 for BIOS images. Other values are reserved.
322 Disk comment length is given as two-byte big-endian value. New
323 images should have 0 here.
327 Ignored. Comment field is there for backward compatiblity.
328 Comment length gives length of this field in bytes.
330 3.6.6 Type-specific geometry/size data (floppies and HDDs)
332 Floppies and HDDs have 3-byte geometry data:
334 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
336 Byte 0 bits 2-5: Head count - 1.
338 Byte 0 bits 6-7: Reserved, must be 0.
340 Byte 1: Bits 0-7 of track count per side - 1.
342 Byte 2: Sector count per track - 1.
344 3.6.7 Type specific-geometry/size data (CD-ROMs)
346 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
348 3.6.8 Type specific-geometry/size data (BIOS images)
350 BIOS images have 4-byte big-endian byte (not sector or block)
353 3.6.9 Actual image data (floppy/HDD)
355 Floppy or HDD imagedata consists of following subparts:
365 Storage method is single byte. Sectors present gives number of
366 last nonzero sector + 1 (zero if image is all zeroes)
368 3.6.10 Floppy/HDD storage method 0: Raw storage
370 This storage method has empty header. Image data is raw dump of
371 first sectors present sectors.
373 3.6.11 Floppy/HDD storage method 1: Sectormap
375 Image data header contains bitfield with just enough bytes to
376 have one bit per present sector. The order of bits is such that
377 number of bit corresponding to each sector in byte is sector
378 number modulo 8 and byte number is floor of sector number divided
379 by 8 when sector numbers are counted from zero. If bit
380 corresponding to sector is set, then the sector is present in
381 image data, otherwise it is absent and assumed to be all-zeroes.
383 Image data contains dumps of all present sectors in order of
384 increasing sector number.
386 3.6.12 Floppy/HDD storage method 2: Extent first sector zero
388 Image data is empty as storage-specific data is mangled with
389 image data. The image data alternates between blocks encoding
390 zero sectors and blocks encoding nonzero sectors. The first block
391 encodes zero sectors.
393 Block encoding zero sectors consist of single 1-4 byte
394 little-endian value encoding number of sectors in block - 1.
395 Number of bytes is determined by sectors present value. It is 1
396 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
397 for more than 16777216. All sectors in block are filled with
398 zeroes and are not stored.
400 Block encoding nonzero sectors has same block count as zero
401 sector block but is followed by the sectors stored raw.
403 3.6.13 Floppy/HDD storage method 3: Extent first sector nonzero
405 Same as storage method 2 but first block is nonzero sector block.
407 3.6.14 Actual image data (CD-ROMs and BIOS images)
409 These store image data raw. The amount of data is specified by
414 4.1 org.jpc.utils.RAWToPNG
418 $ java org.jpc.utils.RAWToPNG <input> <outputprefix>
420 Reads RAW video data from <input> (may be named pipe) and dumps
421 PNG frames received as '<outputprefix><runningcount>.png'. Also
422 saves '<outputprefix>.timing' which contains frame timing data
423 (each line consists of time in nanoseconds, space, and filename).
425 5 The actual emulator
427 The actual emulator is invoked as:
429 $ java JPCApplication <options>...
431 The valid options are:
433 -library <library> Use the specified directory when searching for
434 images (can only be specified once).
436 -autoexec <script> Execute contents of specified file as commands
441 When emulator is started, command line comes up. Following
444 • 'exit': exit immediately
446 • 'load <plugin>': Load plugin (no arguments)
448 • 'load <plugin>(<arguments>)': load plugin with arguments.
450 • 'command <command> [<arguments>...]': Invoke command via
451 external command interface.
453 When one gets command line, its useful to load some plugins. See
454 section about plugins. Note: Load runner plugin
455 (PCControl/PCRunner and so) last, as some runners like to start
458 5.2 PC settings dialog notes
460 • CPU divider base frequency before division is 1GHz.
462 • Images can be specified by name or by ID. Name is relative to
463 library directory. If the image is in subdirectory of image
464 directory, the directory separator is is '/' regardless of what
467 • CD-ROM and hdc are mutually exclusive
469 • Modules is comma-seperated list of modules to load. To pass
470 arguments to some modules, enclose the arguments in (). Same
471 module can be specified twice only if parameters differ.
473 • FPU emulator is specified by class name. If core has built-in
474 FPU emulator, then this should be left blank. Without
475 core-builtin FPU emulator, blank value means “no fpu”.
477 • Setting boot device doesn't work with some BIOS versions. Those
478 versions prompt the boot device anyway.
480 5.3 Audio output channels
482 PC can have one or more audio output channels. The name of audio
483 output associated with PC speaker is:
484 'org.jpc.emulator.peripheral.PCSpeaker-0'. Modules that have
485 audio outputs get channel names of form <classname>-<sequential>,
486 where <classname> is name of main module class and sequential is
487 number starting from zero. Note that same module can have
488 multiple output channels. If multiple modules of same class
489 request audio outputs, the <sequential> values of subsequent
490 module start where previous left off.
494 Plugins actually execute the tasks of the emulator. They can be
495 loaded using “load <plugin>” or 'load <plugin>(<arguments>)” from
498 Different Plugins using the same output (like running PCMonitor
499 and PNGDumper) should not conflict because connector output hold
500 locking is desinged to handle multiple readers.
502 If no plugin used requires GUI, then the emulator can be run
503 without having GUI available.
505 5.4.1 plugin: org.jpc.plugins.PCControl
507 No arguments, requires and uses GUI.
509 Runs the PC emulator core. Has capability to start/stop
510 emulation, breakpoint after certain time or start/end of VGA
511 vertical retrace. Also can create, savestate and loadstate PC
512 emulation. Memory dumping is supported.
514 5.4.2 plugin: org.jpc.plugins.PCRunner
516 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>'
517 Does not require nor use GUI.
519 Loads PC from savestate and just runs it. CTRL+C to quit. Also
520 automatically quits once stoptime is reached.
522 5.4.3 plugin: org.jpc.plugins.PCMonitor
524 No arguments, requires and uses GUI.
526 VGA monitor for emulated PC.
528 5.4.4 plugin: org.jpc.plugins.VirtualKeyboard
530 No arguments, requires and uses GUI.
532 On-screen keyboard for emulated PC.
534 5.4.5 plugin: org.jpc.plugins.PCStartStopTest
536 No arguments, requires and uses GUI.
538 Small plugin testing remote PC start/stop. Also supports sending
539 some common keypresses.
541 5.4.6 plugin: org.jpc.plugins.RAWVideoDumper
543 Takes 'rawoutput=<file>' as argument. Does not require nor use
546 Dumps all generated frames to RAW file <file>. Rawoutput is
547 required. The raw file consists of concatenation of zlib streams.
548 The uncompressed stream is concatenation of time skips (FFh FFh
549 FFh FFh), each acting as time offset of 2^32-1 nanoseconds and
550 saved frames. The saved frame has time offset in nanoseconds (big
551 endian) as first four bytes (must be at most 2^32-2, as 2^32-1 is
552 reserved for time skip). The next two bytes are big-endian width,
553 next two big-endian height. Finally frame has 4 * width * height
554 bytes of data that encodes pixels using 4 bytes per pixel, in
555 left-to-right, up-to-down order. Byte 0 of each pixel is
556 reserved, byte 1 is the red channel, byte 2 is green channel and
557 byte 3 is blue channel.
559 Dumping to pipe is supported.
561 5.4.7 plugin: org.jpc.plugins.RAWAudioDumper
563 Takes 'src=<name of audio output channel>',
564 'file=<output-filename>' and 'offset=<offset>' as arguments,
565 separated by ','. Does not require nor use GUI.
567 Dumps output from specified audio output channel (src, mandatory)
568 to RAW-format file (file, mandatory). The resulting file consists
569 of records, 8 bytes each. Each record has three fields. First 4
570 byte unsinged little endian timedelta value (in nanoseconds),
571 then 2 byte unsigned little endian new left channel volume, then
572 2 byte unsigned little endian new right channel volume.
573 Optionally 'offset' can be set to positive value (in nanoseconds)
574 to delay the audio by.
576 5.4.8 plugin: org.jpc.plugins.LuaPlugin
578 Takes 'kernel=<name of lua kernel file>', other parameters are
579 passed to kernel, requires and uses GUI.
581 Lua VM for executing scripts.
583 6 Some error messages and explanations
585 • <filename> is Not a valid image file
587 • <filename> is not image file
589 • <filename> claims to be floppy with illegal geometry: <x>
590 tracks, <y> sides and <z> sectors.
592 • <filename> claims to be HDD with illegal geometry: <x> tracks,
593 <y> sides and <z> sectors.
595 • Can't read disk image sector map.
597 • Can't read disk image extent.
599 Code expects <filename> to be valid JPC-RR format image, but it
600 isn't JPC-RR image at all or its corrupt.
602 • <filename> is image of unknown type.
604 • <filename> has unrecognized geometry <x> <y> <z>
606 Possibly corrupt image, not JPC-RR image, or JPC-RR image from
607 future version containing something current version can't
610 • Invalid format specifier <something>.
612 • Invalid syntax of --floppy= or --HDD= option.
614 • Invalid format specifier/option <something>.
616 Invalid option or format specifier was given. Check for typos.
618 • java ImageMaker [<options>...] <format> <destination> <source>
621 Check syntax of command. Especially that diskname is present!
623 • The image has <nnn> sectors while it should have <yyy>
624 according to selected geometry.
626 • Raw image file length not divisible by 512.
628 • Trying to read sector out of range.
630 The selected geometry is wrong or raw image is incomplete.
632 • Invalid disk name (Should not happen!).
634 • Invalid geometry to be written.
636 This is a very likely a bug in program.
638 • What the heck <filename> is? It's not regular file nor
641 That sort of file can't be used as input for image making, or the
642 file just doesn't exist.
644 • BIOS images can only be made out of regular files.
646 • CD images can only be made out of regular files.
648 Source image specified is not regular file, but image of that
649 type can't be made of anything else.
651 • Can't read raw bios image file.
653 • Can't read sector <nnn> from image.
655 Reading the raw image file failed for some reason.
657 • Bad library line: "<something>". Ignored.
659 Syntax error in image library.
661 • Removing image <something> a.k.a. "<something>" as it no longer
664 The image file no longer exists so it gets removed from library.
666 • Removing image <something> a.k.a. "<something>" due to <some>
669 Image library code killed some image from library due to some
670 kind of conflict with image being added.
672 • Too much data to fit into given space.
674 The tree you gave contains takes just too much space to fit into
677 7 Advanced: Savestate/movie format
681 JRSR archive format packs multiple text archive members to text
682 archive. It does not support binary members. JRSR archives have
683 first five bytes form the magic. It is “JRSR” followed by
684 LINEFEED character (0x0A, 0x0D, 0x0D 0x0A, 0xC2 0x85). There are
685 three kinds of lines after that (lines are terminated by LINEFEED
694 Sequencing rules are as follows: Start member is allowed
695 anywhere. Member line is allowed only inside member (member
696 started but not ended). End member is only allowed inside member.
697 End of file is only allowed outside member. Note that those three
698 are all the kinds of lines allowed.
702 Start member line is given as “!BEGIN” <SPACE> <membername>
703 <LINEFEED>. <SPACE> is SPACE character (only one!, 0x20) and
704 <LINEFEED> is LINEFEED chacter. Multiple <SPACE>s would mean
705 member with name beginning with <SPACE>. The member name is UTF-8
706 encoded and maximum allowed length is 1024 bytes (256-1024
707 codepoints). Starting member inside another implicitly ends the
712 Member line is given as “+”<content><LINEFEED>. It gives another
713 line for member contents. <content> is passed raw to layers
718 End member line is given as “!END”<LINEFEED>. It ends the current
719 member. The following line can only be start member line or file
722 7.2 Four-to-Five encoding
724 Binary members are encoded into text by so-called four-to-five
725 encoding. This encoding can encode single byte to two, two bytes
726 to three, three bytes to four and four bytes to five.
727 Four-to-five encoding has five kinds of blocks. All SPACE and
728 CHARACTER TABULATION characters are completely ignored, even in
731 7.2.1 End stream block
733 End stream block is encoded as '!'. It ends the stream instantly.
734 There is also implicit end of stream at end of input to decoding.
736 7.2.2 Other four block types
738 Other four block types take the value to be encoded, read it as
739 big-endian value. Then they write it as base-93 big-endian value.
740 Then length specific constants are added to digits of that number
741 to yield ASCII values for characters (those are stored in order):
744 +------------+------------+------------+------------+------------+-----------+
745 | To encode | 1st char. | 2nd char. | 3rd char. | 4th char. | 5th char. |
746 +------------+------------+------------+------------+------------+-----------+
747 +------------+------------+------------+------------+------------+-----------+
748 | 1 byte | 34 | 34 | - | - | - |
749 +------------+------------+------------+------------+------------+-----------+
750 | 2 bytes | 37 | 34 | 34 | - | - |
751 +------------+------------+------------+------------+------------+-----------+
752 | 3 bytes | 45 | 34 | 34 | 34 | - |
753 +------------+------------+------------+------------+------------+-----------+
754 | 4 bytes | 66 | 34 | 34 | 34 | 34 |
755 +------------+------------+------------+------------+------------+-----------+
758 Blocks which encode values greater than what is possible for
759 value of that length are fatal errors.
763 UTF-8 encoding is used to encode lines of Unicode codepoints into
766 7.4 Line component encoing
768 Line component encoding sits on top of UTF-8 encoding. Line
769 component encoding encodes non-empty 1-D array of non-empty
770 strings into line, and thus array of those into member. Empty
771 lines or lines that don't contain any components are ignored.
772 Line starts with depth value of 0 and must end with depth value
775 Components are seperated by component separators. Empty
776 components are ignored. Following codepoints are separators on
777 depth 0 if not escaped:
779 • Codepoint of '('. The depth is read pre-increment.
781 • Codepoint of ')'. The depth is read post-decrement.
783 • Codepoints 0x20, and 0x09.
785 • Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
787 • Codepoints 0x2000-0x200A.
789 The following characters are special:
791 • '('. Increments depth by 1 if not escaped (and appears in
794 • ')'. Decrements depth by 1 if not escaped (and appears in
795 component). Depth going negative is an error.
797 • '\'. Next character is interpretted as literal. Error if at end
800 Otherwise, characters are interpretted as literals and appear in
801 components. Depth must be zero at end of line.
805 Header section is in archive member "header". It uses line
806 component encoding. The first component of each line is name of
807 header, and subsequent ones are arguments. How many parameters
808 are expected is dependent on what header it is:
810 7.5.1 PROJECTID header:
812 • Header name: "PROJECTID"
816 • Argument #1: <project-id-string>
820 Gives project ID. Project ID is generated when PC is assembled
821 and is then preserved in save states. It is used for computing
822 rerecord counts. Emulator treats it as opaque string, the IDs it
823 generates are formed by 48 random hexadecimal digits.
825 7.5.2 SAVESTATEID header:
827 • Header name: "SAVESTATEID"
831 • Argument #1: <savestate-id-string>
835 Gives save state ID. Each save state has its own save state ID.
836 Treated as opaque string, but generated as 48 random hexadecimal
837 digits. The presence of this header signals whether there is save
838 state to be loaded. If this header is present, save state load
839 will be attempted. If absent, save state is not to be loaded even
840 if present (and correct savestate load would be technically
843 The value is used to prevent loading incompatible save states in
844 preserve event stream mode and also to find the point in event
845 stream where one left off.
847 7.5.3 RERECORDS header:
849 • Header name: "RERECORDS"
853 • Argument #1: <rerecords>
857 Gives rerecord count. PC assembly (except when loading save
858 state) initializes current rerecord count to zero. Must be
859 non-negative and decimal number using ASCII digit characters.
861 On loading save state:
863 1) If project ID matches with previous:
865 1a) If loaded rerecord count is larger or equal to current
868 1a-a) Current rerecord count is loaded rerecord count + 1.
872 1b-a) Current rerecord count increments by 1.
876 2a) Current rerecord count is loaded rerecord count + 1.
878 The current rerecord count at time of save is saved to save
881 7.5.4 AUTHORS header:
883 • Header name: "AUTHORS"
885 • Components: 2 or more
887 • Arguments: free form
891 Gives authors of run. Each argument gives one author. May be
892 present multiple times.
894 7.5.5 COMMENT header:
896 • Header name: "COMMENT"
898 • Components: 2 or more
900 • Arguments: free form
904 Various kinds of free form data. Not parsed further by emulator.
906 7.6 Initialization segment:
908 If SAVESTATEID header isn't present (not a save state), member
909 "initialization" gives PC initialization parameters for
910 assembling the PC. It is present anyway even if SAVESTATEID is
913 Following parameters are used (space separates components):
917 Gives Image ID of main system BIOS (mandatory)
921 Gives Image ID of VGA BIOS (mandatory).
925 Gives Image ID of hda. Present only if system has hard disk hda.
929 Gives Image ID of hdb. Present only if system has hard disk hdb.
933 Gives Image ID of hdc. Present only if system has hard disk hdc.
937 Gives Image ID of hdd. Present only if system has hard disk hdd.
941 Gives Image ID of disk in slot <num>. Slot number must be
944 “DISKNAME” <num> <name>
946 Gives image name of disk in slot <num>. Slot number must be
947 non-negative. The slot must be previously declared using “DISK”.
951 Gives Image slot to initially put into floppy drive fda. Disk
952 must be of floppy type. If none present, no disk is initially put
957 Gives Image slot to initially put into floppy drive fdb. Disk
958 must be of floppy type. If none present, no disk is initially put
963 Gives Image slot to initially put into CD-ROM drive hdc. Not
964 allowed if hard disk hdc is present. Disk must be of CD-ROM type.
965 If none present no disk is initially put there.
969 Number of milliseconds since Unix epoch to system start up time.
972 0-4102444799999. Mandatory.
974 "CPUDIVIDER" <divider>
976 Set CPU frequency divider (dividing the 1GHz master clock).
977 Allowed range is 1-256. Mandatory.
981 Number of 4KiB pages of RAM memory. Allowed range 256-262144.
986 Set boot device. Valid devices are "FLOPPY" (boot from fda),
987 "HDD" (boot from hda) and "CDROM" (boot from CD).
989 "LOADMODULEA" <module> <parameters>
991 Load module <module> with parameters <parameters>.
993 "LOADMODULE" <module>
995 Load module <module> with no parameters
999 Use class <fpu> as FPU emulator.
1001 7.7 Event record format:
1003 Event record is in archive member "events". It uses line
1004 component encoding. Each line gives an event. First component of
1005 each line gives time stamp. These timestamps MUST be in
1006 increasing order and all MUST be non-negative. Time stamp time
1007 unit is exactly 1 nanosecond of emulated time.
1009 The second component of each line is name of class to dispatch
1010 to. Further components are passed as-is to event handlers.
1011 "Class" name "SAVESTATE" is special. This takes one or two
1012 additional components, first of which gives the save state ID of
1013 save state that occurred there. The save state IDs MUST be unique
1014 in entire event stream. The second argument to savestate (if
1015 present) is rerecord count at time of saving that savestate
1016 (useful for calulating rerecord count of movie starting from
1019 7.7.1 Keyboard keypress/keyrelease event:
1021 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1023 • Argument #1: Fixed: "KEYEDGE"
1025 • Argument #2: Key number. Valid values are 1-83, 85-95, 129-197
1028 Send key press or key release. Keys work in toggle button manner.
1029 The event time must be multiple of 66 666, and must not be less
1030 than 60 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs
1031 after last KEYEDGE on key >128 and 10 * 66 666 TUs after last
1032 KEYEDGE on key <128.
1036 • Dispatch to: org.jpc.emulator.peripheral.Keyboard
1038 • Argument #1: Fixed: "PAUSE"
1040 Send pause key event. The time restrictions are identical to
1043 7.7.3 Joystick button event:
1045 • Dispatch to: org.jpc.modules.Joystick
1047 • Argument #1: “BUTTONA”, “BUTTONB”, “BUTTONC” or “BUTTOND”
1049 • Argument #2: “0” if released, “1” if pressed
1051 Send button down/up event. No time restrictions.
1053 7.7.4 Joystick axis event:
1055 • Dispatch to: org.jpc.modules.Joystick
1057 • Argument #1: “AXISA”, “AXISB”, “AXISC” or “AXISD”
1059 • Argument #2: Multivibrator unstable state length in ns.
1061 Set amount of time multivibrator remains in unstable state. No
1066 • Dispatch to: org.jpc.emulator.PC$ResetButton
1072 7.7.6 Fda disk change:
1074 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1076 • Argument #1: Fixed: "FDA"
1078 • Argument #2: Number of image slot to put there.
1080 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1081 used if there is no disk in floppy drive A. This event causes
1082 specified disk to be placed to FDA or FDA disk to be ejected with
1083 no replacement if disk number is -1. The specified disk if not -1
1084 must be of floppy type. The specified disk if valid must not be
1087 7.7.7 Fdb disk change:
1089 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1091 • Argument #1: Fixed: "FDB"
1093 • Argument #2: Number of image slot to put there.
1095 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1096 used if there is no disk in floppy drive B. This event causes
1097 specified disk to be placed to FDB or FDB disk to be ejected with
1098 no replacement if disk number is -1. The specified disk if not -1
1099 must be of floppy type. The specified disk if valid must not be
1104 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1106 • Argument #1: Fixed: "CDROM"
1108 • Argument #2: Number of image slot to put there.
1110 The disk number MUST be -1 or valid disk number. -1 MUST NOT be
1111 used if there is no disk in CD-ROM. This event causes specified
1112 disk to be placed to CD-ROM or CD-ROM disk to be ejected with no
1113 replacement if disk number is -1. The specified disk if not -1
1114 must be of CD-ROM type.
1116 This event has no effect if CD-ROM is locked.
1118 7.7.9 Write protect floppy:
1120 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1122 • Argument #1: Fixed: "WRITEPROTECT"
1124 • Argument #2: Number of image slot to manipulate
1126 Write protects specified disk. The disk MUST NOT be in any drive
1127 and MUST be valid floppy-type disk.
1129 7.7.10 Write unprotect floppy:
1131 • Dispatch to: org.jpc.emulator.PC$DiskChanger
1133 • Argument #1: Fixed: "WRITEUNPROTECT"
1135 • Argument #2: Number of image slot to manipulate
1137 Disables write protection specified disk. The disk MUST NOT be in
1138 any drive and MUST be valid floppy-type disk.
1142 Actual savestate format is not documented here. It is close to
1143 impossible to comprehend without access to emulator source
1146 8 Advanced: Making class dumpable
1148 Class is made dumpable by implementing interface
1149 org.jpc.emulator.SRDumpable and implementing method
1150 dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
1151 <init>(org.jpc.emulator.SRLoader). Non-static inner classes can
1152 not be dumpable (make them static using tricks similar to what
1155 If dumped class has dumpable superclass, the first thing dumping
1156 function needs to do is to call dumper function of superclass and
1157 first thing loading constructor needs to do is to call loading
1158 constructor of superclass. If class has no dumpable superclass,
1159 dumper doesn't need to do anything special, while loader needs to
1160 call objectCreated(this) on SRLoader object passed as parameter.
1162 Following these fixed parts, dump all members that are part of
1163 mutable state in emulator core.
1165 8.1 Member dumping/loading functions
1167 There is dumping/loading function for following (all functions
1168 dumping/loading reference types can handle null):
1170 • boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
1172 • byte: SRDumper.dumpByte, SRLoader.loadByte
1174 • short: SRDumper.dumpShort, SRLoader.loadShort
1176 • int: SRDumper.dumpInt, SRLoader.loadInt
1178 • long: SRDumper.dumpLong, SRLoader.loadLong
1180 • String: SRDumper.dumpString, SRLoader.loadString
1182 • boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
1184 • byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
1186 • short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
1188 • int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
1190 • long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
1192 • double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
1194 • <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
1196 • special object: SRDumper.specialObject, SRLoader.specialObject
1200 • Dumpable objects come out as type of
1201 org.jpc.emulator.SRDumpable.
1203 • Special objects are various static objects that don't need to
1204 be stored because they don't have mutable fields.
1206 • Don't dump fields related to event state feedback.
1208 • Don't dump temporary flags that are only used while PC is
1209 running. Savestate when PC is running isn't possible anyway.
1211 • Some connectors dump fields related to connector output, some
1214 9 Advanced: Making output connectors
1216 Implementing interface org.jpc.emulator.DisplayController signals
1217 that this is display controller, inhibiting loading of the
1218 standard VGA display controller if loaded as module.
1220 9.1 Interface org.jpc.emulator.OutputConnector
1222 Class is made to be output connector by implementing this
1223 interface. This interface specifies the methods used for output
1224 hold locking. Class org.jpc.emulator.OutputConnectorLocking has
1225 implementations of these that are suitable for calling.
1227 9.1.1 Method subscribeOutput(Object)
1229 Subscribes the output, with specified object as handle.
1231 9.1.2 Method unsubscribeOutput(Object)
1233 Unsubscribe the specified handle object from output.
1235 9.1.3 Method waitOutput(Object)
1237 Wait for output on specified connector using specified handle
1238 object. Returns true on success, false if wait was interrupted by
1239 thread interrupt. Blocking.
1241 9.1.4 Method releaseOutput(Object)
1243 Release connector from p.o.v. of given handle. Does not block.
1245 9.1.5 Method holdOutput()
1247 Release threads waiting on waitOutput() and block until all
1248 subscribers have returned from waitOutput() and enteired
1251 9.1.6 Method releaseOutputWaitAll(object)
1253 Like releaseOutput(), but waits until all handles have released
1256 9.2 Class org.jpc.emulator.VGADigtalOut
1258 Class org.jpc.emulator.VGADigtalOut (already implements
1259 OutputConnector) implements VGA output connector. If module
1260 provodes output connector, it needs to implement
1261 org.jpc.emulator.DisplayController.
1263 9.2.1 Method getWidth()
1265 Get width of display (watch out, can return 0).
1267 9.2.2 Method getHeight()
1269 Get height of display (watch out, can return 0).
1271 9.2.3 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(),
1274 Returns the dirty region (region modified since last output).
1276 9.2.4 Method getBuffer()
1278 Get buffer of ints, at least width * height elements
1279 (left-to-right, top-down, one value per pixel) giving pixel data.
1280 Value for each pixel is 65536 * <red-component> + 256 *
1281 <green-component> + <blue-component>.
1283 9.2.5 Method resizeDisplay(int _width, int _height)
1285 Resize the display to be of specified size.
1287 9.2.6 Method dirtyDisplayRegion(int x, int y, int w, int h)
1289 Mark the specified region as dirty.
1291 9.2.7 Method resetDirtyRegion()
1293 Resets the dirty region to be empty.
1295 9.3 Class org.jpc.emulator.PC method getVideoOutput()
1297 Get VGA output connector for PC.
1299 9.4 Interface org.jpc.emulator.DisplayController.
1301 Implementing this class signals that module is VGA controller.
1302 There can be only one such module active at time and presence of
1303 such module prevents loading builtin VGA controller emulation
1306 9.4.1 Method getOutputDevice()
1308 Get VGA output connector for this VGA device.
1310 9.5 Class org.jpc.emulator.SoundDigitalOut
1312 Class org.jpc.emulator.SoundDigitalOut provodes output connector
1313 for sound. Each connector can transfer stereo signal at arbitiary
1314 sampling rate. Modules that have audio connectors need to
1315 implement interface org.jpc.emulator.SoundOutputDevice, as this
1316 signals that output connectors should be created.
1318 9.5.1 Method addSample(long, short, short)
1320 Add stereo sample at time given by first argument. The second and
1321 third arguments give volume on left and right channels.
1323 9.5.2 Method addSample(long, short)
1325 Add mono sample at time given by first argument. The second
1326 argument give volume on both channels.
1328 9.5.3 Method readBlock(Block)
1330 Reads block of output (atomic versus addSample). Block structure
1331 has following fields which are filled:
1333 • timeBase: Time base for block.
1335 • baseLeft: Left volume at time base.
1337 • baseRight: Right volume at time base
1339 • blockNo: Sequence number of block filled.
1341 • samples: Number of samples in block
1343 • sampleTiming: Number of nanoseconds since last sample
1345 • sampleLeft: Left channel samples
1347 • sampleRight: Right channel samples
1349 9.6 Interface org.jpc.emulator.SoundOutputDevice
1351 Implementing this interface signals that module has audio output
1355 org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
1357 Return the number of sound channels module has.
1360 org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
1362 This is called once per sound channel requested giving precreated
1365 9.7 Class org.jpc.emulator.PC method getSoundOut(String)
1367 Get sound output with specified name.
1369 10 Advanced: Writing event targets
1371 Whereas output connectors are the way output is dispatched, input
1372 is dispatched via event targets. Event targets need to implement
1373 interface org.jpc.emulator.EventDispatchTarget.
1375 Event targets also provode methods which then encode events and
1376 dispatch them forward (without doing anything else) to event
1377 recorder. Also, event targets may have methods for obtaining
1380 10.1 Interface org.jpc.emulator.EventDispatchTarget
1382 Interface that marks class capable of receiving events.
1384 10.1.1 Method setEventRecorder(EventRecorder)
1386 Set the event recorder input events are sent to.
1388 10.1.2 Method startEventCheck()
1390 Signals target to reset all state related to event checking and
1391 state feedback. This may be called at any time in order to
1392 reinitialialize event checking/feedback state.
1394 10.1.3 Method doEvent(long, String[], int) throws IOException
1396 Event dispatch handler. The first argument is event time, second
1397 is parameters and third is what to do with it. If target doesn't
1398 like the event, throw IOException. Following types (the integer
1399 parameter) are used:
1401 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
1403 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in
1404 event replay for reinitialization
1406 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay
1409 3 (EventRecorder.EVENT_EXECUTE): This event occurs now. Execute
1412 10.1.4 Method endEventCheock()
1414 End event reinitialization. Usually unused.
1416 10.1.5 Method getEventTimeLowBound(long, String[]) throws
1419 Return the time value that's the earliest possiblity for this
1420 event to occur. Returning any time in past (including -1) causes
1421 event to fire as soon as possible. The long parameter gives the
1422 current scheduled time for event.
1426 Modules are various extensions that run inside emulator core. As
1427 such, they affect sync. Modules must implement interface
1428 org.jpc.emulator.HardwareComponent (they are hardware components)
1429 and must be dumpable. Additionally, they need either constructor
1430 <init>() or <init>(String). The first is if no parameters are
1431 passed, the second is for case where parameters are passed.
1433 Aside of the constructors, modules need to obey the ordinary
1434 conventions for hardware components. No code outside modules
1435 needs to know that module exists.
1439 Plugins handle various UI tasks. They need to implement interface
1442 12.1 Interface org.jpc.pluginsbase.Plugin
1444 12.1.1 Method systemShutdown()
1446 Called when emulator shuts down. Either called in dedicated
1447 thread or in thread that called emulatorShutdown(). These
1448 handlers should do the bare minimum to get files on disk to
1449 consistent state. After these calls from all plugins have
1450 finished, emulator exits. Do not try to manipulate UI from these
1451 methods, as doing that easily leads into deadlock.
1453 12.1.2 Method reconnect(PC)
1455 Gives new PC to connect to. Null is passed if plugin should
1458 12.1.3 Method main()
1460 Called in dedicated thread after plugin is initialized.
1462 12.1.4 Method pcStopping()
1464 Called after PC has stopped.
1466 12.1.5 Method pcStarting()
1468 Called before PC starts.
1470 12.1.6 Method notifyArguments(String[])
1472 Pass arguments from command line.
1474 12.1.7 Constructor <init>(Plugins)
1476 This constructor is used to initialize plugins that don't take
1479 12.1.8 Constructor <init>(Plugins, String)
1481 This constructor is used to initialize plugins that take
1484 12.2 Class org.jpc.pluginsbase.Plugins
1486 This class provodes various methods for manipulating plugins.
1488 12.2.1 Method isShuttingDown()
1490 Returns true if Plugins.shutdownEmulator() has been called
1491 somehow, either via VM exit, CTRL+C or explicitly. Useful to skip
1492 cleanups involving GUI, as these are too deadlock-prone.
1494 12.2.2 Method shutdownEmulator()
1496 Shut down and exit the emulator. All plugin shutdown functions
1497 are called in this thread.
1499 12.2.3 Method reconnectPC(PC)
1501 Signal reconnectPC event to all plugins.
1503 12.2.4 Method pcStarted()
1505 Signal pcStarting() event to all plugins.
1507 12.2.5 Method pcStopped()
1509 Signal pcStopping() event to all plugins.
1511 12.3 Interface org.jpc.pluginsbase.ExternalCommandInterface
1513 Implementing interface
1514 org.jpc.pluginsbase.ExternalCommandInterface signals that plugin
1515 can receive commands via external commands interface.
1517 12.3.1 Method invokeCommand(String cmd, String[] args)
1519 Invoke specified command using specified arguments. Return true
1520 if event is to be shallowed, false to continue trying to pass it
1523 13 Lua kernel programming
1525 At startup, kernel gets its arguments in 'args' table and the
1526 script name to run in 'scriptname' string. It should enter the
1527 named script in protected mode.
1529 The Lua VM exports numerious callbacks to kernel. The kernel can
1530 then choose to omit, wrap or re-export these to Lua scripts.
1532 • Always grab any functions used into local variables so nobody
1535 • Don't use global variables in kernel (except for those passed).
1539 All standard Lua functions in tables main, 'math', 'coroutine',
1540 'string' and 'table' (safe to re-export with exception of print,
1541 loadfile and dofile, which should be wrapped).
1543 13.2 Bit manipulation: none
1545 Bitwise none function is exported as
1546 'jpcrr_raw.bit_none(num...)'. It takes zero or more numbers and
1547 returns number (numbers have 48 bits). The number returned has
1548 those bits set that are set in none of inputs. Safe to re-export.
1550 13.3 Bit manipulation: any
1552 Bitwise any function is exported as 'jpcrr_raw.bit_any(num...)'.
1553 It takes zero or more numbers and returns number (numbers have 48
1554 bits). The number returned has those bits set that are set in any
1555 of inputs. Safe to re-export.
1557 13.4 Bit manipulation: parity
1559 Bitwise parity function is exported as
1560 'jpcrr_raw.bit_parity(num...)'. It takes zero or more numbers and
1561 returns number (numbers have 48 bits). The number returned has
1562 those bits set that are set in even number of of inputs. Safe to
1565 13.5 Bit manipulation: all
1567 Bitwise parity function is exported as
1568 'jpcrr_raw.bit_all(num...)'. It takes zero or more numbers and
1569 returns number (numbers have 48 bits). The number returned has
1570 those bits set that are set in all of inputs. Safe to re-export.
1572 13.6 Bit manipulation: lshift
1574 Left shift function is exported as 'jpcrr_raw.bit_lshift(num
1575 base, num shift)'. It takes two numbers and returns first number
1576 shifted by second. number places left. Numbers have 48 bits,
1577 using shifts outside 0-47 gives unpredictable results. Safe to
1580 13.7 Bit manipulation: rshift
1582 Right logical shift function is exported as
1583 'jpcrr_raw.bit_rshift(num base, num shift)'. It takes two numbers
1584 and returns first number shifted by second number places right.
1585 Numbers have 48 bits, using shifts outside 0-47 gives
1586 unpredictable results. Safe to re-export.
1588 13.8 Bit manipulation: arshift
1590 Right arithmetic shift function is exported as
1591 'jpcrr_raw.bit_arshift(num base, num shift)'. It takes two
1592 numbers and returns first number shifted by second number places
1593 right, with highest bit copied. Numbers have 48 bits, using
1594 shifts outside 0-47 gives unpredictable results. Safe to
1597 13.9 Bit manipulation: add
1599 Add function is exported as 'jpcrr_raw.bit_add(num...)'. It takes
1600 zero or more numbers and returns number (numbers have 48 bits).
1601 The number returned is sum of all of inputs modulo 2^{48}. Safe
1604 13.10 Bit manipulation: addneg
1606 Add negated function is exported as
1607 'jpcrr_raw.bit_addneg(num...)'. It takes zero or more numbers and
1608 returns number (numbers have 48 bits). The number returned is 0
1609 minus of all of inputs modulo 2^{48}. Safe to re-export.
1611 13.11 Bit manipulation: addalt
1613 Add alternate function is exported as
1614 'jpcrr_raw.bit_addalt(num...)'. It takes zero or more numbers and
1615 returns number (numbers have 48 bits). The number returned is sum
1616 of odd arguments (first argument is odd) minus sum of even
1617 arguments modulo 2^{48}. Safe to re-export.
1619 13.12 Bit manipulation: tohex
1621 Add alternate function is exported as 'jpcrr_raw.bit_tohex(num
1622 number)'. It takes number and returns hexadecimal representation
1623 of it. Safe to re-export.
1625 13.13 Console output:
1627 Console ouput function is exported as
1628 'jpcrr_raw.print_console_msg(sring line)'. It prints its string
1629 argument as new line on Lua console (should not be re-exported,
1630 use to construct replacement print).
1634 Binary I/O file open function is exported as
1635 'jpcrr_raw.io_openbinary(string name, string mode)'. It takes two
1636 strings, first is name of file to open, second is mode, either “r”
1637 or “rw”. The returned object has following methods:
1639 • file:length(): Returns length of file as number.
1641 • file:set_length(num len): Truncate file to len bytes.
1643 • file:read(num offset, num length): Read up to length bytes
1644 starting from offset offset. The file character set is assumed
1647 • file:write(num offset, string str): Write str starting from
1648 offset offset. Writing non-Latin1 characters gives
1649 unpredictable results. Only available on files opened for
1652 • file:close(): Close file. No file operations can be done
1655 The function should be filtered to enforce path constraints.
1659 Text input open function is exported as
1660 'jpcrr_raw.io_opentextinput(string name)'. It takes one string,
1661 name of file to open. The returned object has following methods:
1663 • file:read(): Read next line. The file encoding is assumed to be
1666 • file:close(): Close file. No file operations can be done
1669 The function should be filtered to enforce path constraints.
1673 Text output open function is exported as
1674 'jpcrr_raw.io_opentextoutput(string name)'. It takes one string,
1675 name of file to open. The returned object has following methods:
1677 • file:write(string line): Write line line to file. File encoding
1678 is assumed to be UTF-8.
1680 • file:close(): Close file. No file operations can be done
1683 The function should be filtered to enforce path constraints.
1687 ECI invocation functions 'jpcrr_raw.invoke(string name [, table
1688 args])' and 'jpcrr_raw.invoke_synchronous(string name [, table
1689 args])'. These functions run specified ECI function with
1690 specified arguments. The updates ECI call makes to arguments is
1691 reflected to table passed as parameter. The synchronous version
1692 waits that any slow command processing gets done before returning
1693 (assemble, save, load and dump have such slow processing). These
1694 functions return nothing. Safe to re-export, use as base for more
1699 'jpcrr_raw.pc_running()'. Returns true if PC is running, false
1700 otherwise. Assemble, save, load and dump require PC not being
1701 running to be possible.
1705 'jpcrr_raw.pc_connected()'. Returns true if PC is connected,
1708 13.20 VGA wait/release:
1710 'jpcrr_raw.wait_vga()' waits for VGA to enter frame hold mode and
1711 returns true (if it returns false, the wait got interrupted for
1712 some reason and VGA is in rendering mode). While VGA is in frame
1713 hold, PC execution is locked out and things like memory reading
1714 and writing can be done without races (but load/save is not
1715 possible). 'jpcrr_raw.release_vga()' acknowledges frame hold
1716 processing (VGA can re-enter rendering mode).
1718 Frame hold happens once per frame at start of vertical retrace.
1719 Note that running Lua script must wait frame holds and release
1720 them or main PC execution will hang on first frame hold.