1 #LyX 1.6.5 created this file. For more info see http://www.lyx.org/
6 \use_default_options true
11 \font_typewriter default
12 \font_default_family default
19 \paperfontsize default
28 \paperorientation portrait
38 \paragraph_separation indent
40 \quotes_language english
43 \paperpagestyle default
44 \tracking_changes false
60 \begin_layout Standard
61 JPC-RR is licenced under GNU GPL v2.
63 \begin_inset Quotes eld
67 \begin_inset Quotes erd
77 \begin_layout Subsection
81 \begin_layout Standard
82 To get started, you need BIOS image, VGABIOS image and DOS boot floppy and
83 JDK for Java 6 standard edition (later versions should they appear should
85 Note: JRE is not enough.
89 \begin_layout Standard
90 Note that to play back recorded movies, you need exact same version of BIOS
91 image, VGABIOS image and DOS boot floppy as was used when making the movie
92 (in addition to exact same versions of other needed media).
95 \begin_layout Standard
97 The stuff in streamtools is only needed for recording videos.
100 \begin_layout Subsection
104 \begin_layout Standard
106 The streamtools stuff is only needed for dumping videos.
109 \begin_layout Subsection
113 \begin_layout Standard
114 First you need to get and make some important images.
115 Obtain BIOS image, VGABIOS image and DOS boot floppy from somewhere and
119 \begin_layout LyX-Code
123 \begin_layout LyX-Code
124 java ImageMaker --BIOS library/BIOS <bios image file>
127 \begin_layout LyX-Code
128 java ImageMaker --BIOS library/VGABIOS <vgabios image file>
131 \begin_layout LyX-Code
132 java ImageMaker --floppy1440 library/DOSfloppy <dos floppy name>
135 \begin_layout Standard
136 This makes loadable images out of what you obtained.
137 Most DOS boot floppies are 1440KiB in size (if yours isn't change that
139 You also might want to make some game images:
142 \begin_layout LyX-Code
143 java ImageMaker --HDD=128,63,16 library/somegame <game installation directory>
146 \begin_layout Standard
147 This makes ~128MB HDD image out of installation directory.
150 \begin_layout Subsection
154 \begin_layout Standard
155 There is premade autoexec script called assemble.bat that has fairly reasonable
160 \begin_layout LyX-Code
161 java JPCApplication -library library -autoexec assemble.bat
164 \begin_layout Standard
166 \begin_inset Quotes eld
170 \begin_inset Quotes erd
173 specifies that contents of directory 'library' are to be used as library.
174 The script pops up settings for new emulated PC (if you want to load savestate,
176 Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
177 selected), DOSfloppy for fda (boot device should be set to fda) and game
178 image as some HD drive
181 \begin_layout Subsection
185 \begin_layout Itemize
186 Putting the game as hdd causes boot to be bit faster.
189 \begin_layout Itemize
190 Some BIOS versions have
191 \begin_inset Quotes eld
194 press F12 to select boot device
195 \begin_inset Quotes erd
199 Hit <enter> from emulated keyboard and that prompt will go away in about
200 half emulated second (it stays several emulated seconds otherwise).
204 \begin_layout Itemize
205 If game doesn't need lots of memory, hitting F5 to skip intialization files
207 If it does need more memory, run config.sys commands but not autoexec.bat.
211 \begin_layout Itemize
212 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
216 \begin_layout Section
217 Making JPC-RR format images from raw images
220 \begin_layout Standard
221 Due to various factors, JPC-RR can't use raw image files directly but requires
222 its own image format.
223 There is tool called ImageMaker that can make JPC-RR images from raw images.
224 Each image has format, ID an name.
225 Format and name are specified when making image.
226 ID is automatically calculated from format and contents.
227 Name does not affect the ID but is purely for convience so one doesn't
228 have to specify long image IDs manually.
231 \begin_layout Subsection
235 \begin_layout Standard
236 The syntax for ImageMaker when making images is:
239 \begin_layout LyX-Code
240 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
243 \begin_layout Standard
244 <destination> is file name for JPC-RR format image to write.
245 <source> is either name of regular file (raw image file) or name of directory
246 tree with files (supported for making floppy or hard disk images only).
247 In case of directory tree, the files are layout deterministically to disk,
248 so the ID will always be the same for given geometry and type.
249 <name> is name to give to disk.
253 \begin_layout LyX-Code
254 --BIOS BIOS image (note: VGABIOS is also of this type).
257 \begin_layout LyX-Code
258 --CDROM CD-ROM image.
261 \begin_layout LyX-Code
262 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
265 \begin_layout LyX-Code
266 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
269 \begin_layout LyX-Code
270 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
273 \begin_layout LyX-Code
274 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
277 \begin_layout LyX-Code
278 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
281 \begin_layout LyX-Code
282 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
285 \begin_layout LyX-Code
286 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
289 \begin_layout LyX-Code
290 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
293 \begin_layout LyX-Code
294 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
297 \begin_layout LyX-Code
298 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
301 \begin_layout LyX-Code
302 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
305 \begin_layout LyX-Code
306 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
309 \begin_layout LyX-Code
310 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
313 \begin_layout LyX-Code
314 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
317 \begin_layout LyX-Code
318 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
321 \begin_layout LyX-Code
322 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
325 \begin_layout LyX-Code
326 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
329 \begin_layout LyX-Code
330 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
333 \begin_layout LyX-Code
334 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
337 \begin_layout LyX-Code
338 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
341 \begin_layout LyX-Code
342 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
345 \begin_layout LyX-Code
346 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
349 \begin_layout LyX-Code
350 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
353 \begin_layout LyX-Code
354 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
357 \begin_layout LyX-Code
358 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
361 \begin_layout LyX-Code
362 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
365 \begin_layout LyX-Code
366 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
369 \begin_layout LyX-Code
370 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
373 \begin_layout LyX-Code
374 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
377 \begin_layout LyX-Code
378 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
381 \begin_layout LyX-Code
382 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
385 \begin_layout Subsection
389 \begin_layout Itemize
390 If making image from directory, the names of the files must conform to FAT
391 naming restrictions (8+3 character names, no spaces, etc).
392 Avoid filenames with non-ASCII characters.
396 \begin_layout Itemize
397 The DOS limit of 112 or 224 files for floppies does not apply to images
398 created from directory trees.
399 The minimum limit value used is 512.
400 If even that isn't enough, the limit is automatically increased to fit
401 all the needed directory entries.
404 \begin_layout Itemize
405 Making boot disks from tree does NOT work.
406 Even if you got system boot files there, it still won't work.
409 \begin_layout Itemize
410 Only floppy disks and hard drives can be made from directory trees.
411 BIOS images and CDROM images require image file.
414 \begin_layout Itemize
415 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
416 Disks with over 63 sectors per track don't work with DOS.
417 Wheither disks with over 127 tracks per side work with DOS is unknown.
418 Also avoid 1024-tracks per side HDDs.
421 \begin_layout Itemize
422 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
424 1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
425 1-16 sides for HDD, 1 or 2 sides for floppy.
426 This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
427 and 516096KiB for HDDs.
430 \begin_layout Itemize
431 There are multiple image file contents that represent the same image.
432 The one with smallest size is picked when creating image.
435 \begin_layout Itemize
436 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
440 \begin_layout Subsection
444 \begin_layout LyX-Code
445 --volumelabel=label Give specified volume label (affects ID).
446 Only meaningful when making image out of directory tree.
447 Default is no volume label.
450 \begin_layout LyX-Code
451 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
452 Only meaningful when making image out of directory tree.
453 The default timestamp is 19900101T000000Z.
456 \begin_layout Subsection
460 \begin_layout Standard
464 \begin_layout LyX-Code
465 $ java ImageMaker <imagefile>
468 \begin_layout Standard
469 Variety of information about image is displayed (especially for floppies/HDDs).
470 Two important fields are calculated and claimed disk ID.
471 They should be the same.
472 If they are not, then the image file is corrupt (sadly, imagemaker has
473 bugs and bugs that cause it to write corrupt images have been seen).
476 \begin_layout Subsection
477 Advanced: The disk ID algorithm
480 \begin_layout Standard
481 The disk ID is calculated as:
484 \begin_layout LyX-Code
485 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
488 \begin_layout Standard
489 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
490 state and 128-bit output using the deprecated rotation constants (as specified
491 in Skein hash function reference documentation versions 1.0 and 1.1).
492 The <image> is the whole image, including parts not stored in image file.
493 The reason for keeping using the deprecated constants are:
496 \begin_layout Itemize
497 Changing the constants would change the IDs, which would invalidate existing
501 \begin_layout Itemize
502 This is not about cryptographic security
505 \begin_layout Itemize
506 The new constants don't improve security that much anyway.
509 \begin_layout Subsubsection
513 \begin_layout Standard
514 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
515 <geometry> is as follows (this is exactly the same form as it appears in
519 \begin_layout LyX-Code
520 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
523 \begin_layout LyX-Code
524 Byte 0 bits 2-5: Head count - 1.
527 \begin_layout LyX-Code
528 Byte 0 bits 6-7: Reserved, must be 0.
531 \begin_layout LyX-Code
532 Byte 1: Bits 0-7 of track count per side - 1.
535 \begin_layout LyX-Code
536 Byte 2: Sector count per track - 1.
539 \begin_layout Subsubsection
540 CD-ROM and BIOS images
543 \begin_layout Standard
544 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
549 \begin_layout Subsection
550 Advanced: Disk Image format
553 \begin_layout Standard
554 The disk image consists of following parts:
557 \begin_layout Itemize
561 \begin_layout Itemize
565 \begin_layout Itemize
569 \begin_layout Itemize
573 \begin_layout Itemize
577 \begin_layout Itemize
578 type-specific geometry/size data
581 \begin_layout Itemize
585 \begin_layout Subsubsection
589 \begin_layout Standard
590 Magic in disk image files is following 5 bytes:
591 \begin_inset Quotes eld
595 \begin_inset Quotes erd
601 \begin_layout Subsubsection
605 \begin_layout Standard
606 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
609 \begin_layout Subsubsection
613 \begin_layout Standard
614 Type code is single byte.
615 0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
616 Other values are reserved.
619 \begin_layout Subsubsection
623 \begin_layout Standard
624 Disk comment length is given as two-byte big-endian value.
625 New images should have 0 here.
628 \begin_layout Subsubsection
632 \begin_layout Standard
634 Comment field is there for backward compatiblity.
635 Comment length gives length of this field in bytes.
638 \begin_layout Subsubsection
639 Type-specific geometry/size data (floppies and HDDs)
642 \begin_layout Standard
643 Floppies and HDDs have 3-byte geometry data:
646 \begin_layout LyX-Code
647 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
650 \begin_layout LyX-Code
651 Byte 0 bits 2-5: Head count - 1.
654 \begin_layout LyX-Code
655 Byte 0 bits 6-7: Reserved, must be 0.
658 \begin_layout LyX-Code
659 Byte 1: Bits 0-7 of track count per side - 1.
662 \begin_layout LyX-Code
663 Byte 2: Sector count per track - 1.
666 \begin_layout Subsubsection
667 Type specific-geometry/size data (CD-ROMs)
670 \begin_layout Standard
671 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
674 \begin_layout Subsubsection
675 Type specific-geometry/size data (BIOS images)
678 \begin_layout Standard
679 BIOS images have 4-byte big-endian byte (not sector or block) count.
682 \begin_layout Subsubsection
683 Actual image data (floppy/HDD)
686 \begin_layout Standard
687 Floppy or HDD imagedata consists of following subparts:
690 \begin_layout Itemize
694 \begin_layout Itemize
698 \begin_layout Itemize
702 \begin_layout Itemize
706 \begin_layout Standard
707 Storage method is single byte.
708 Sectors present gives number of last nonzero sector + 1 (zero if image
712 \begin_layout Subsubsection
713 Floppy/HDD storage method 0: Raw storage
716 \begin_layout Standard
717 This storage method has empty header.
718 Image data is raw dump of first sectors present sectors.
721 \begin_layout Subsubsection
722 Floppy/HDD storage method 1: Sectormap
725 \begin_layout Standard
726 Image data header contains bitfield with just enough bytes to have one bit
728 The order of bits is such that number of bit corresponding to each sector
729 in byte is sector number modulo 8 and byte number is floor of sector number
730 divided by 8 when sector numbers are counted from zero.
731 If bit corresponding to sector is set, then the sector is present in image
732 data, otherwise it is absent and assumed to be all-zeroes.
735 \begin_layout Standard
736 Image data contains dumps of all present sectors in order of increasing
740 \begin_layout Subsubsection
741 Floppy/HDD storage method 2: Extent first sector zero
744 \begin_layout Standard
745 Image data is empty as storage-specific data is mangled with image data.
746 The image data alternates between blocks encoding zero sectors and blocks
747 encoding nonzero sectors.
748 The first block encodes zero sectors.
752 \begin_layout Standard
753 Block encoding zero sectors consist of single 1-4 byte little-endian value
754 encoding number of sectors in block - 1.
755 Number of bytes is determined by sectors present value.
756 It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
757 for more than 16777216.
758 All sectors in block are filled with zeroes and are not stored.
761 \begin_layout Standard
762 Block encoding nonzero sectors has same block count as zero sector block
763 but is followed by the sectors stored raw.
766 \begin_layout Subsubsection
767 Floppy/HDD storage method 3: Extent first sector nonzero
770 \begin_layout Standard
771 Same as storage method 2 but first block is nonzero sector block.
774 \begin_layout Subsubsection
775 Actual image data (CD-ROMs and BIOS images)
778 \begin_layout Standard
779 These store image data raw.
780 The amount of data is specified by sector/byte count.
783 \begin_layout Section
787 \begin_layout Subsection
788 org.jpc.utils.RAWToPNG
791 \begin_layout Standard
795 \begin_layout LyX-Code
796 $ java org.jpc.utils.RAWToPNG <input> <outputprefix>
799 \begin_layout Standard
800 Reads RAW video data from <input> (may be named pipe) and dumps PNG frames
801 received as '<outputprefix><runningcount>.png'.
802 Also saves '<outputprefix>.timing' which contains frame timing data (each
803 line consists of time in nanoseconds, space, and filename).
806 \begin_layout Section
810 \begin_layout Standard
811 The actual emulator is invoked as:
814 \begin_layout LyX-Code
815 $ java JPCApplication <options>...
818 \begin_layout Standard
819 The valid options are:
822 \begin_layout LyX-Code
823 -library <library> Use the specified directory when searching for images
824 (can only be specified once).
827 \begin_layout LyX-Code
828 -autoexec <script> Execute contents of specified file as commands when starting
832 \begin_layout Subsection
836 \begin_layout Standard
837 When emulator is started, command line comes up.
838 Following commands are known:
841 \begin_layout Itemize
842 'exit': exit immediately
845 \begin_layout Itemize
846 'load <plugin>': Load plugin (no arguments)
849 \begin_layout Itemize
850 'load <plugin>(<arguments>)': load plugin with arguments.
853 \begin_layout Itemize
854 'command <command> [<arguments>...]': Invoke command via external command interface.
857 \begin_layout Standard
858 When one gets command line, its useful to load some plugins.
859 See section about plugins.
860 Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
861 like to start PC immediately.
864 \begin_layout Subsection
865 PC settings dialog notes
868 \begin_layout Itemize
869 CPU divider base frequency before division is 1GHz.
872 \begin_layout Itemize
873 Images can be specified by name or by ID.
874 Name is relative to library directory.
875 If the image is in subdirectory of image directory, the directory separator
876 is is '/' regardless of what the host OS uses.
879 \begin_layout Itemize
880 CD-ROM and hdc are mutually exclusive
883 \begin_layout Itemize
884 Modules is comma-seperated list of modules to load.
885 To pass arguments to some modules, enclose the arguments in ().
886 Same module can be specified twice only if parameters differ.
889 \begin_layout Itemize
890 FPU emulator is specified by class name.
891 If core has built-in FPU emulator, then this should be left blank.
892 Without core-builtin FPU emulator, blank value means
893 \begin_inset Quotes eld
897 \begin_inset Quotes erd
903 \begin_layout Itemize
904 Setting boot device doesn't work with some BIOS versions.
905 Those versions prompt the boot device anyway.
908 \begin_layout Subsection
909 Audio output channels
912 \begin_layout Standard
913 PC can have one or more audio output channels.
914 The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
916 Modules that have audio outputs get channel names of form <classname>-<sequenti
917 al>, where <classname> is name of main module class and sequential is number
919 Note that same module can have multiple output channels.
920 If multiple modules of same class request audio outputs, the <sequential>
921 values of subsequent module start where previous left off.
924 \begin_layout Subsection
928 \begin_layout Standard
929 Plugins actually execute the tasks of the emulator.
930 They can be loaded using
931 \begin_inset Quotes eld
935 \begin_inset Quotes erd
938 or 'load <plugin>(<arguments>)
939 \begin_inset Quotes erd
945 \begin_layout Standard
946 Different Plugins using the same output (like running PCMonitor and PNGDumper)
947 should not conflict because connector output hold locking is desinged to
948 handle multiple readers.
951 \begin_layout Standard
952 If no plugin used requires GUI, then the emulator can be run without having
956 \begin_layout Subsubsection
957 plugin: org.jpc.plugins.PCControl
960 \begin_layout Standard
961 No arguments, requires and uses GUI.
964 \begin_layout Standard
965 Runs the PC emulator core.
966 Has capability to start/stop emulation, breakpoint after certain time or
967 start/end of VGA vertical retrace.
968 Also can create, savestate and loadstate PC emulation.
969 Memory dumping is supported.
973 \begin_layout Subsubsection
974 plugin: org.jpc.plugins.PCRunner
977 \begin_layout Standard
978 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
982 \begin_layout Standard
983 Loads PC from savestate and just runs it.
985 Also automatically quits once stoptime is reached.
988 \begin_layout Subsubsection
989 plugin: org.jpc.plugins.PCMonitor
992 \begin_layout Standard
993 No arguments, requires and uses GUI.
996 \begin_layout Standard
997 VGA monitor for emulated PC.
1000 \begin_layout Subsubsection
1001 plugin: org.jpc.plugins.VirtualKeyboard
1004 \begin_layout Standard
1005 No arguments, requires and uses GUI.
1008 \begin_layout Standard
1009 On-screen keyboard for emulated PC.
1012 \begin_layout Subsubsection
1013 plugin: org.jpc.plugins.PCStartStopTest
1016 \begin_layout Standard
1017 No arguments, requires and uses GUI.
1020 \begin_layout Standard
1021 Small plugin testing remote PC start/stop.
1022 Also supports sending some common keypresses.
1025 \begin_layout Subsubsection
1026 plugin: org.jpc.plugins.RAWVideoDumper
1029 \begin_layout Standard
1030 Takes 'rawoutput=<file>' as argument.
1031 Does not require nor use GUI.
1034 \begin_layout Standard
1035 Dumps all generated frames to RAW file <file>.
1036 Rawoutput is required.
1037 The raw file consists of concatenation of zlib streams.
1038 The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1039 each acting as time offset of 2^32-1 nanoseconds and saved frames.
1040 The saved frame has time offset in nanoseconds (big endian) as first four
1041 bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1042 The next two bytes are big-endian width, next two big-endian height.
1043 Finally frame has 4 * width * height bytes of data that encodes pixels
1044 using 4 bytes per pixel, in left-to-right, up-to-down order.
1045 Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1046 green channel and byte 3 is blue channel.
1049 \begin_layout Standard
1050 Dumping to pipe is supported.
1053 \begin_layout Subsubsection
1054 plugin: org.jpc.plugins.RAWAudioDumper
1057 \begin_layout Standard
1058 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1059 'offset=<offset>' as arguments, separated by ','.
1060 Does not require nor use GUI.
1063 \begin_layout Standard
1064 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1065 file (file, mandatory).
1066 The resulting file consists of records, 8 bytes each.
1067 Each record has three fields.
1068 First 4 byte unsinged little endian timedelta value (in nanoseconds), then
1069 2 byte unsigned little endian new left channel volume, then 2 byte unsigned
1070 little endian new right channel volume.
1071 Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1075 \begin_layout Subsubsection
1076 plugin: org.jpc.plugins.LuaPlugin
1079 \begin_layout Standard
1080 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1081 kernel, requires and uses GUI.
1084 \begin_layout Standard
1085 Lua VM for executing scripts.
1088 \begin_layout Section
1089 Some error messages and explanations
1092 \begin_layout Itemize
1093 <filename> is Not a valid image file
1096 \begin_layout Itemize
1097 <filename> is not image file
1100 \begin_layout Itemize
1101 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1105 \begin_layout Itemize
1106 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1110 \begin_layout Itemize
1111 Can't read disk image sector map.
1114 \begin_layout Itemize
1115 Can't read disk image extent.
1118 \begin_layout Standard
1119 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1120 image at all or its corrupt.
1123 \begin_layout Itemize
1124 <filename> is image of unknown type.
1127 \begin_layout Itemize
1128 <filename> has unrecognized geometry <x> <y> <z>
1131 \begin_layout Standard
1132 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1133 containing something current version can't comprehend.
1136 \begin_layout Itemize
1137 Invalid format specifier <something>.
1140 \begin_layout Itemize
1141 Invalid syntax of --floppy= or --HDD= option.
1144 \begin_layout Itemize
1145 Invalid format specifier/option <something>.
1148 \begin_layout Standard
1149 Invalid option or format specifier was given.
1153 \begin_layout Itemize
1154 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1157 \begin_layout Standard
1158 Check syntax of command.
1159 Especially that diskname is present!
1162 \begin_layout Itemize
1163 The image has <nnn> sectors while it should have <yyy> according to selected
1167 \begin_layout Itemize
1168 Raw image file length not divisible by 512.
1171 \begin_layout Itemize
1172 Trying to read sector out of range.
1175 \begin_layout Standard
1176 The selected geometry is wrong or raw image is incomplete.
1179 \begin_layout Itemize
1180 Invalid disk name (Should not happen!).
1183 \begin_layout Itemize
1184 Invalid geometry to be written.
1187 \begin_layout Standard
1188 This is a very likely a bug in program.
1191 \begin_layout Itemize
1192 What the heck <filename> is? It's not regular file nor directory.
1195 \begin_layout Standard
1196 That sort of file can't be used as input for image making, or the file just
1200 \begin_layout Itemize
1201 BIOS images can only be made out of regular files.
1204 \begin_layout Itemize
1205 CD images can only be made out of regular files.
1208 \begin_layout Standard
1209 Source image specified is not regular file, but image of that type can't
1210 be made of anything else.
1213 \begin_layout Itemize
1214 Can't read raw bios image file.
1217 \begin_layout Itemize
1218 Can't read sector <nnn> from image.
1221 \begin_layout Standard
1222 Reading the raw image file failed for some reason.
1225 \begin_layout Itemize
1226 Bad library line: "<something>".
1230 \begin_layout Standard
1231 Syntax error in image library.
1234 \begin_layout Itemize
1235 Removing image <something> a.k.a.
1236 "<something>" as it no longer exists.
1239 \begin_layout Standard
1240 The image file no longer exists so it gets removed from library.
1243 \begin_layout Itemize
1244 Removing image <something> a.k.a.
1245 "<something>" due to <some> conflict.
1248 \begin_layout Standard
1249 Image library code killed some image from library due to some kind of conflict
1250 with image being added.
1253 \begin_layout Itemize
1254 Too much data to fit into given space.
1257 \begin_layout Standard
1258 The tree you gave contains takes just too much space to fit into disk of
1262 \begin_layout Section
1263 Advanced: Savestate/movie format
1266 \begin_layout Subsection
1270 \begin_layout Standard
1271 JRSR archive format packs multiple text archive members to text archive.
1272 It does not support binary members.
1273 JRSR archives have first five bytes form the magic.
1275 \begin_inset Quotes eld
1279 \begin_inset Quotes erd
1282 followed by LINEFEED character (0x0A, 0x0D, 0x0D 0x0A, 0xC2 0x85).
1283 There are three kinds of lines after that (lines are terminated by LINEFEED
1287 \begin_layout Itemize
1291 \begin_layout Itemize
1295 \begin_layout Itemize
1299 \begin_layout Standard
1300 Sequencing rules are as follows: Start member is allowed anywhere.
1301 Member line is allowed only inside member (member started but not ended).
1302 End member is only allowed inside member.
1303 End of file is only allowed outside member.
1304 Note that those three are all the kinds of lines allowed.
1307 \begin_layout Subsubsection
1311 \begin_layout Standard
1312 Start member line is given as
1313 \begin_inset Quotes eld
1317 \begin_inset Quotes erd
1320 <SPACE> <membername> <LINEFEED>.
1321 <SPACE> is SPACE character (only one!, 0x20) and <LINEFEED> is LINEFEED
1323 Multiple <SPACE>s would mean member with name beginning with <SPACE>.
1324 The member name is UTF-8 encoded and maximum allowed length is 1024 bytes
1325 (256-1024 codepoints).
1326 Starting member inside another implicitly ends the previous member.
1329 \begin_layout Subsubsection
1333 \begin_layout Standard
1334 Member line is given as
1335 \begin_inset Quotes eld
1339 \begin_inset Quotes erd
1342 <content><LINEFEED>.
1343 It gives another line for member contents.
1344 <content> is passed raw to layers above.
1347 \begin_layout Subsubsection
1351 \begin_layout Standard
1352 End member line is given as
1353 \begin_inset Quotes eld
1357 \begin_inset Quotes erd
1361 It ends the current member.
1362 The following line can only be start member line or file may end.
1365 \begin_layout Subsection
1366 Four-to-Five encoding
1369 \begin_layout Standard
1370 Binary members are encoded into text by so-called four-to-five encoding.
1371 This encoding can encode single byte to two, two bytes to three, three
1372 bytes to four and four bytes to five.
1373 Four-to-five encoding has five kinds of blocks.
1374 All SPACE and CHARACTER TABULATION characters are completely ignored, even
1375 in middle of blocks.
1378 \begin_layout Subsubsection
1382 \begin_layout Standard
1383 End stream block is encoded as '!'.
1384 It ends the stream instantly.
1385 There is also implicit end of stream at end of input to decoding.
1388 \begin_layout Subsubsection
1389 Other four block types
1392 \begin_layout Standard
1393 Other four block types take the value to be encoded, read it as big-endian
1395 Then they write it as base-93 big-endian value.
1396 Then length specific constants are added to digits of that number to yield
1397 ASCII values for characters (those are stored in order):
1400 \begin_layout Standard
1401 \begin_inset Tabular
1402 <lyxtabular version="3" rows="5" columns="6">
1404 <column alignment="center" valignment="top" width="0">
1405 <column alignment="center" valignment="top" width="0">
1406 <column alignment="center" valignment="top" width="0">
1407 <column alignment="center" valignment="top" width="0">
1408 <column alignment="center" valignment="top" width="0">
1409 <column alignment="center" valignment="top" width="0">
1411 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1414 \begin_layout Plain Layout
1420 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1423 \begin_layout Plain Layout
1429 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1432 \begin_layout Plain Layout
1438 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1441 \begin_layout Plain Layout
1447 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1450 \begin_layout Plain Layout
1456 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1459 \begin_layout Plain Layout
1467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1470 \begin_layout Plain Layout
1476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1479 \begin_layout Plain Layout
1485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1488 \begin_layout Plain Layout
1494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1497 \begin_layout Plain Layout
1503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1506 \begin_layout Plain Layout
1512 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1515 \begin_layout Plain Layout
1523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1526 \begin_layout Plain Layout
1532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1535 \begin_layout Plain Layout
1541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1544 \begin_layout Plain Layout
1550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1553 \begin_layout Plain Layout
1559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1562 \begin_layout Plain Layout
1568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1571 \begin_layout Plain Layout
1579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1582 \begin_layout Plain Layout
1588 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1591 \begin_layout Plain Layout
1597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1600 \begin_layout Plain Layout
1606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1609 \begin_layout Plain Layout
1615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1618 \begin_layout Plain Layout
1624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1627 \begin_layout Plain Layout
1635 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1638 \begin_layout Plain Layout
1644 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1647 \begin_layout Plain Layout
1653 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1656 \begin_layout Plain Layout
1662 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1665 \begin_layout Plain Layout
1671 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1674 \begin_layout Plain Layout
1680 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1683 \begin_layout Plain Layout
1697 \begin_layout Standard
1698 Blocks which encode values greater than what is possible for value of that
1699 length are fatal errors.
1703 \begin_layout Subsection
1707 \begin_layout Standard
1708 UTF-8 encoding is used to encode lines of Unicode codepoints into bytes.
1711 \begin_layout Subsection
1712 Line component encoing
1715 \begin_layout Standard
1716 Line component encoding sits on top of UTF-8 encoding.
1717 Line component encoding encodes non-empty 1-D array of non-empty strings
1718 into line, and thus array of those into member.
1719 Empty lines or lines that don't contain any components are ignored.
1720 Line starts with depth value of 0 and must end with depth value of zero.
1723 \begin_layout Standard
1724 Components are seperated by component separators.
1725 Empty components are ignored.
1726 Following codepoints are separators on depth 0 if not escaped:
1729 \begin_layout Itemize
1731 The depth is read pre-increment.
1734 \begin_layout Itemize
1736 The depth is read post-decrement.
1739 \begin_layout Itemize
1740 Codepoints 0x20, and 0x09.
1743 \begin_layout Itemize
1744 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1747 \begin_layout Itemize
1748 Codepoints 0x2000-0x200A.
1751 \begin_layout Standard
1752 The following characters are special:
1755 \begin_layout Itemize
1757 Increments depth by 1 if not escaped (and appears in component).
1760 \begin_layout Itemize
1762 Decrements depth by 1 if not escaped (and appears in component).
1763 Depth going negative is an error.
1766 \begin_layout Itemize
1770 Next character is interpretted as literal.
1771 Error if at end of line.
1774 \begin_layout Standard
1775 Otherwise, characters are interpretted as literals and appear in components.
1776 Depth must be zero at end of line.
1779 \begin_layout Subsection
1783 \begin_layout Standard
1784 Header section is in archive member "header".
1785 It uses line component encoding.
1786 The first component of each line is name of header, and subsequent ones
1788 How many parameters are expected is dependent on what header it is:
1791 \begin_layout Subsubsection
1795 \begin_layout Itemize
1796 Header name: "PROJECTID"
1799 \begin_layout Itemize
1803 \begin_layout Itemize
1804 Argument #1: <project-id-string>
1807 \begin_layout Itemize
1811 \begin_layout Standard
1813 Project ID is generated when PC is assembled and is then preserved in save
1815 It is used for computing rerecord counts.
1816 Emulator treats it as opaque string, the IDs it generates are formed by
1817 48 random hexadecimal digits.
1820 \begin_layout Subsubsection
1824 \begin_layout Itemize
1825 Header name: "SAVESTATEID"
1828 \begin_layout Itemize
1832 \begin_layout Itemize
1833 Argument #1: <savestate-id-string>
1836 \begin_layout Itemize
1840 \begin_layout Standard
1841 Gives save state ID.
1842 Each save state has its own save state ID.
1843 Treated as opaque string, but generated as 48 random hexadecimal digits.
1844 The presence of this header signals whether there is save state to be loaded.
1845 If this header is present, save state load will be attempted.
1846 If absent, save state is not to be loaded even if present (and correct
1847 savestate load would be technically impossible anyway).
1850 \begin_layout Standard
1851 The value is used to prevent loading incompatible save states in preserve
1852 event stream mode and also to find the point in event stream where one
1856 \begin_layout Subsubsection
1860 \begin_layout Itemize
1861 Header name: "RERECORDS"
1864 \begin_layout Itemize
1868 \begin_layout Itemize
1869 Argument #1: <rerecords>
1872 \begin_layout Itemize
1876 \begin_layout Standard
1877 Gives rerecord count.
1878 PC assembly (except when loading save state) initializes current rerecord
1880 Must be non-negative and decimal number using ASCII digit characters.
1883 \begin_layout LyX-Code
1884 On loading save state:
1887 \begin_layout LyX-Code
1888 1) If project ID matches with previous:
1891 \begin_layout LyX-Code
1892 1a) If loaded rerecord count is larger or equal to current rerecord count:
1895 \begin_layout LyX-Code
1896 1a-a) Current rerecord count is loaded rerecord count + 1.
1899 \begin_layout LyX-Code
1903 \begin_layout LyX-Code
1904 1b-a) Current rerecord count increments by 1.
1907 \begin_layout LyX-Code
1911 \begin_layout LyX-Code
1912 2a) Current rerecord count is loaded rerecord count + 1.
1915 \begin_layout Standard
1916 The current rerecord count at time of save is saved to save state.
1919 \begin_layout Subsubsection
1923 \begin_layout Itemize
1924 Header name: "AUTHORS"
1927 \begin_layout Itemize
1928 Components: 2 or more
1931 \begin_layout Itemize
1932 Arguments: free form
1935 \begin_layout Itemize
1939 \begin_layout Standard
1940 Gives authors of run.
1941 Each argument gives one author.
1942 May be present multiple times.
1945 \begin_layout Subsubsection
1949 \begin_layout Itemize
1950 Header name: "COMMENT"
1953 \begin_layout Itemize
1954 Components: 2 or more
1957 \begin_layout Itemize
1958 Arguments: free form
1961 \begin_layout Itemize
1965 \begin_layout Standard
1966 Various kinds of free form data.
1967 Not parsed further by emulator.
1970 \begin_layout Subsection
1971 Initialization segment:
1974 \begin_layout Standard
1975 If SAVESTATEID header isn't present (not a save state), member "initialization"
1976 gives PC initialization parameters for assembling the PC.
1977 It is present anyway even if SAVESTATEID is present (savestate).
1980 \begin_layout Standard
1981 Following parameters are used (space separates components):
1984 \begin_layout LyX-Code
1988 \begin_layout Standard
1989 Gives Image ID of main system BIOS (mandatory)
1992 \begin_layout LyX-Code
1996 \begin_layout Standard
1997 Gives Image ID of VGA BIOS (mandatory).
2000 \begin_layout LyX-Code
2004 \begin_layout Standard
2005 Gives Image ID of hda.
2006 Present only if system has hard disk hda.
2009 \begin_layout LyX-Code
2013 \begin_layout Standard
2014 Gives Image ID of hdb.
2015 Present only if system has hard disk hdb.
2018 \begin_layout LyX-Code
2022 \begin_layout Standard
2023 Gives Image ID of hdc.
2024 Present only if system has hard disk hdc.
2027 \begin_layout LyX-Code
2031 \begin_layout Standard
2032 Gives Image ID of hdd.
2033 Present only if system has hard disk hdd.
2036 \begin_layout LyX-Code
2040 \begin_layout Standard
2041 Gives Image ID of disk in slot <num>.
2042 Slot number must be non-negative.
2045 \begin_layout LyX-Code
2046 \begin_inset Quotes eld
2050 \begin_inset Quotes erd
2056 \begin_layout Standard
2057 Gives image name of disk in slot <num>.
2058 Slot number must be non-negative.
2059 The slot must be previously declared using
2060 \begin_inset Quotes eld
2064 \begin_inset Quotes erd
2070 \begin_layout LyX-Code
2074 \begin_layout Standard
2075 Gives Image slot to initially put into floppy drive fda.
2076 Disk must be of floppy type.
2077 If none present, no disk is initially put there.
2080 \begin_layout LyX-Code
2084 \begin_layout Standard
2085 Gives Image slot to initially put into floppy drive fdb.
2086 Disk must be of floppy type.
2087 If none present, no disk is initially put there.
2090 \begin_layout LyX-Code
2094 \begin_layout Standard
2095 Gives Image slot to initially put into CD-ROM drive hdc.
2096 Not allowed if hard disk hdc is present.
2097 Disk must be of CD-ROM type.
2098 If none present no disk is initially put there.
2101 \begin_layout LyX-Code
2102 "INITIALTIME" <time>
2105 \begin_layout Standard
2106 Number of milliseconds since Unix epoch to system start up time.
2110 \begin_layout Standard
2115 \begin_layout LyX-Code
2116 "CPUDIVIDER" <divider>
2119 \begin_layout Standard
2120 Set CPU frequency divider (dividing the 1GHz master clock).
2121 Allowed range is 1-256.
2125 \begin_layout LyX-Code
2126 "MEMORYSIZE" <pages>
2129 \begin_layout Standard
2130 Number of 4KiB pages of RAM memory.
2131 Allowed range 256-262144.
2135 \begin_layout LyX-Code
2139 \begin_layout Standard
2141 Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2145 \begin_layout LyX-Code
2146 "LOADMODULEA" <module> <parameters>
2149 \begin_layout Standard
2150 Load module <module> with parameters <parameters>.
2153 \begin_layout LyX-Code
2154 "LOADMODULE" <module>
2157 \begin_layout Standard
2158 Load module <module> with no parameters
2161 \begin_layout LyX-Code
2162 \begin_inset Quotes eld
2166 \begin_inset Quotes erd
2172 \begin_layout Standard
2173 Use class <fpu> as FPU emulator.
2176 \begin_layout Subsection
2177 Event record format:
2180 \begin_layout Standard
2181 Event record is in archive member "events".
2182 It uses line component encoding.
2183 Each line gives an event.
2184 First component of each line gives time stamp.
2185 These timestamps MUST be in increasing order and all MUST be non-negative.
2186 Time stamp time unit is exactly 1 nanosecond of emulated time.
2189 \begin_layout Standard
2190 The second component of each line is name of class to dispatch to.
2191 Further components are passed as-is to event handlers.
2192 "Class" name "SAVESTATE" is special.
2193 This takes one or two additional components, first of which gives the save
2194 state ID of save state that occurred there.
2195 The save state IDs MUST be unique in entire event stream.
2196 The second argument to savestate (if present) is rerecord count at time
2197 of saving that savestate (useful for calulating rerecord count of movie
2198 starting from savestate).
2201 \begin_layout Subsubsection
2202 Keyboard keypress/keyrelease event:
2205 \begin_layout Itemize
2206 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2209 \begin_layout Itemize
2210 Argument #1: Fixed: "KEYEDGE"
2213 \begin_layout Itemize
2214 Argument #2: Key number.
2215 Valid values are 1-83, 85-95, 129-197 and 199-223
2218 \begin_layout Standard
2219 Send key press or key release.
2220 Keys work in toggle button manner.
2221 The event time must be multiple of 66 666, and must not be less than 60
2222 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2223 on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2226 \begin_layout Subsubsection
2230 \begin_layout Itemize
2231 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2234 \begin_layout Itemize
2235 Argument #1: Fixed: "PAUSE"
2238 \begin_layout Standard
2239 Send pause key event.
2240 The time restrictions are identical to KEYEDGE event.
2243 \begin_layout Subsubsection
2244 Joystick button event:
2247 \begin_layout Itemize
2248 Dispatch to: org.jpc.modules.Joystick
2251 \begin_layout Itemize
2253 \begin_inset Quotes eld
2257 \begin_inset Quotes erd
2261 \begin_inset Quotes eld
2265 \begin_inset Quotes erd
2269 \begin_inset Quotes eld
2273 \begin_inset Quotes erd
2277 \begin_inset Quotes eld
2281 \begin_inset Quotes erd
2287 \begin_layout Itemize
2289 \begin_inset Quotes eld
2293 \begin_inset Quotes erd
2297 \begin_inset Quotes eld
2301 \begin_inset Quotes erd
2307 \begin_layout Standard
2308 Send button down/up event.
2309 No time restrictions.
2312 \begin_layout Subsubsection
2313 Joystick axis event:
2316 \begin_layout Itemize
2317 Dispatch to: org.jpc.modules.Joystick
2320 \begin_layout Itemize
2322 \begin_inset Quotes eld
2326 \begin_inset Quotes erd
2330 \begin_inset Quotes eld
2334 \begin_inset Quotes erd
2338 \begin_inset Quotes eld
2342 \begin_inset Quotes erd
2346 \begin_inset Quotes eld
2350 \begin_inset Quotes erd
2356 \begin_layout Itemize
2357 Argument #2: Multivibrator unstable state length in ns.
2360 \begin_layout Standard
2361 Set amount of time multivibrator remains in unstable state.
2362 No time restrictions.
2365 \begin_layout Subsubsection
2369 \begin_layout Itemize
2370 Dispatch to: org.jpc.emulator.PC$ResetButton
2373 \begin_layout Itemize
2377 \begin_layout Standard
2381 \begin_layout Subsubsection
2385 \begin_layout Itemize
2386 Dispatch to: org.jpc.emulator.PC$DiskChanger
2389 \begin_layout Itemize
2390 Argument #1: Fixed: "FDA"
2393 \begin_layout Itemize
2394 Argument #2: Number of image slot to put there.
2398 \begin_layout Standard
2399 The disk number MUST be -1 or valid disk number.
2400 -1 MUST NOT be used if there is no disk in floppy drive A.
2401 This event causes specified disk to be placed to FDA or FDA disk to be
2402 ejected with no replacement if disk number is -1.
2403 The specified disk if not -1 must be of floppy type.
2404 The specified disk if valid must not be in any other drive.
2407 \begin_layout Subsubsection
2411 \begin_layout Itemize
2412 Dispatch to: org.jpc.emulator.PC$DiskChanger
2415 \begin_layout Itemize
2416 Argument #1: Fixed: "FDB"
2419 \begin_layout Itemize
2420 Argument #2: Number of image slot to put there.
2424 \begin_layout Standard
2425 The disk number MUST be -1 or valid disk number.
2426 -1 MUST NOT be used if there is no disk in floppy drive B.
2427 This event causes specified disk to be placed to FDB or FDB disk to be
2428 ejected with no replacement if disk number is -1.
2429 The specified disk if not -1 must be of floppy type.
2430 The specified disk if valid must not be in any other drive.
2433 \begin_layout Subsubsection
2437 \begin_layout Itemize
2438 Dispatch to: org.jpc.emulator.PC$DiskChanger
2441 \begin_layout Itemize
2442 Argument #1: Fixed: "CDROM"
2445 \begin_layout Itemize
2446 Argument #2: Number of image slot to put there.
2450 \begin_layout Standard
2451 The disk number MUST be -1 or valid disk number.
2452 -1 MUST NOT be used if there is no disk in CD-ROM.
2453 This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2454 to be ejected with no replacement if disk number is -1.
2455 The specified disk if not -1 must be of CD-ROM type.
2458 \begin_layout Standard
2459 This event has no effect if CD-ROM is locked.
2462 \begin_layout Subsubsection
2463 Write protect floppy:
2466 \begin_layout Itemize
2467 Dispatch to: org.jpc.emulator.PC$DiskChanger
2470 \begin_layout Itemize
2471 Argument #1: Fixed: "WRITEPROTECT"
2474 \begin_layout Itemize
2475 Argument #2: Number of image slot to manipulate
2478 \begin_layout Standard
2479 Write protects specified disk.
2480 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2483 \begin_layout Subsubsection
2484 Write unprotect floppy:
2487 \begin_layout Itemize
2488 Dispatch to: org.jpc.emulator.PC$DiskChanger
2491 \begin_layout Itemize
2492 Argument #1: Fixed: "WRITEUNPROTECT"
2495 \begin_layout Itemize
2496 Argument #2: Number of image slot to manipulate
2499 \begin_layout Standard
2500 Disables write protection specified disk.
2501 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2504 \begin_layout Subsection
2508 \begin_layout Standard
2509 Actual savestate format is not documented here.
2510 It is close to impossible to comprehend without access to emulator source
2514 \begin_layout Section
2515 Advanced: Making class dumpable
2518 \begin_layout Standard
2519 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
2520 and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
2521 <init>(org.jpc.emulator.SRLoader).
2522 Non-static inner classes can not be dumpable (make them static using tricks
2523 similar to what javac uses).
2526 \begin_layout Standard
2527 If dumped class has dumpable superclass, the first thing dumping function
2528 needs to do is to call dumper function of superclass and first thing loading
2529 constructor needs to do is to call loading constructor of superclass.
2530 If class has no dumpable superclass, dumper doesn't need to do anything
2531 special, while loader needs to call objectCreated(this) on SRLoader object
2532 passed as parameter.
2536 \begin_layout Standard
2537 Following these fixed parts, dump all members that are part of mutable state
2541 \begin_layout Subsection
2542 Member dumping/loading functions
2545 \begin_layout Standard
2546 There is dumping/loading function for following (all functions dumping/loading
2547 reference types can handle null):
2550 \begin_layout Itemize
2551 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
2554 \begin_layout Itemize
2555 byte: SRDumper.dumpByte, SRLoader.loadByte
2558 \begin_layout Itemize
2559 short: SRDumper.dumpShort, SRLoader.loadShort
2562 \begin_layout Itemize
2563 int: SRDumper.dumpInt, SRLoader.loadInt
2566 \begin_layout Itemize
2567 long: SRDumper.dumpLong, SRLoader.loadLong
2570 \begin_layout Itemize
2571 String: SRDumper.dumpString, SRLoader.loadString
2574 \begin_layout Itemize
2575 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
2578 \begin_layout Itemize
2579 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
2582 \begin_layout Itemize
2583 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
2586 \begin_layout Itemize
2587 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
2590 \begin_layout Itemize
2591 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
2594 \begin_layout Itemize
2595 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
2598 \begin_layout Itemize
2599 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
2602 \begin_layout Itemize
2603 special object: SRDumper.specialObject, SRLoader.specialObject
2606 \begin_layout Subsubsection
2610 \begin_layout Itemize
2611 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
2614 \begin_layout Itemize
2615 Special objects are various static objects that don't need to be stored
2616 because they don't have mutable fields.
2619 \begin_layout Itemize
2620 Don't dump fields related to event state feedback.
2623 \begin_layout Itemize
2624 Don't dump temporary flags that are only used while PC is running.
2625 Savestate when PC is running isn't possible anyway.
2628 \begin_layout Itemize
2629 Some connectors dump fields related to connector output, some don't.
2632 \begin_layout Section
2633 Advanced: Making output connectors
2636 \begin_layout Standard
2637 Implementing interface org.jpc.emulator.DisplayController signals that this
2638 is display controller, inhibiting loading of the standard VGA display controlle
2639 r if loaded as module.
2643 \begin_layout Subsection
2644 Interface org.jpc.emulator.OutputConnector
2647 \begin_layout Standard
2648 Class is made to be output connector by implementing this interface.
2649 This interface specifies the methods used for output hold locking.
2650 Class org.jpc.emulator.OutputConnectorLocking has implementations of these
2651 that are suitable for calling.
2655 \begin_layout Subsubsection
2656 Method subscribeOutput(Object)
2659 \begin_layout Standard
2660 Subscribes the output, with specified object as handle.
2663 \begin_layout Subsubsection
2664 Method unsubscribeOutput(Object)
2667 \begin_layout Standard
2668 Unsubscribe the specified handle object from output.
2671 \begin_layout Subsubsection
2672 Method waitOutput(Object)
2675 \begin_layout Standard
2676 Wait for output on specified connector using specified handle object.
2677 Returns true on success, false if wait was interrupted by thread interrupt.
2681 \begin_layout Subsubsection
2682 Method releaseOutput(Object)
2685 \begin_layout Standard
2686 Release connector from p.o.v.
2691 \begin_layout Subsubsection
2695 \begin_layout Standard
2696 Release threads waiting on waitOutput() and block until all subscribers
2697 have returned from waitOutput() and enteired releaseOutput().
2700 \begin_layout Subsubsection
2701 Method releaseOutputWaitAll(object)
2704 \begin_layout Standard
2705 Like releaseOutput(), but waits until all handles have released their output.
2708 \begin_layout Subsection
2709 Class org.jpc.emulator.VGADigtalOut
2712 \begin_layout Standard
2713 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
2714 VGA output connector.
2715 If module provodes output connector, it needs to implement org.jpc.emulator.Displa
2719 \begin_layout Subsubsection
2723 \begin_layout Standard
2724 Get width of display (watch out, can return 0).
2727 \begin_layout Subsubsection
2731 \begin_layout Standard
2732 Get height of display (watch out, can return 0).
2735 \begin_layout Subsubsection
2736 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
2739 \begin_layout Standard
2740 Returns the dirty region (region modified since last output).
2743 \begin_layout Subsubsection
2747 \begin_layout Standard
2748 Get buffer of ints, at least width * height elements (left-to-right, top-down,
2749 one value per pixel) giving pixel data.
2750 Value for each pixel is 65536 * <red-component> + 256 * <green-component>
2754 \begin_layout Subsubsection
2755 Method resizeDisplay(int _width, int _height)
2758 \begin_layout Standard
2759 Resize the display to be of specified size.
2762 \begin_layout Subsubsection
2763 Method dirtyDisplayRegion(int x, int y, int w, int h)
2766 \begin_layout Standard
2767 Mark the specified region as dirty.
2770 \begin_layout Subsubsection
2771 Method resetDirtyRegion()
2774 \begin_layout Standard
2775 Resets the dirty region to be empty.
2778 \begin_layout Subsection
2779 Class org.jpc.emulator.PC method getVideoOutput()
2782 \begin_layout Standard
2783 Get VGA output connector for PC.
2786 \begin_layout Subsection
2787 Interface org.jpc.emulator.DisplayController.
2790 \begin_layout Standard
2791 Implementing this class signals that module is VGA controller.
2792 There can be only one such module active at time and presence of such module
2793 prevents loading builtin VGA controller emulation code.
2796 \begin_layout Subsubsection
2797 Method getOutputDevice()
2800 \begin_layout Standard
2801 Get VGA output connector for this VGA device.
2804 \begin_layout Subsection
2805 Class org.jpc.emulator.SoundDigitalOut
2808 \begin_layout Standard
2809 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
2810 Each connector can transfer stereo signal at arbitiary sampling rate.
2811 Modules that have audio connectors need to implement interface org.jpc.emulator.So
2812 undOutputDevice, as this signals that output connectors should be created.
2815 \begin_layout Subsubsection
2816 Method addSample(long, short, short)
2819 \begin_layout Standard
2820 Add stereo sample at time given by first argument.
2821 The second and third arguments give volume on left and right channels.
2824 \begin_layout Subsubsection
2825 Method addSample(long, short)
2828 \begin_layout Standard
2829 Add mono sample at time given by first argument.
2830 The second argument give volume on both channels.
2833 \begin_layout Subsubsection
2834 Method readBlock(Block)
2837 \begin_layout Standard
2838 Reads block of output (atomic versus addSample).
2839 Block structure has following fields which are filled:
2842 \begin_layout Itemize
2843 timeBase: Time base for block.
2846 \begin_layout Itemize
2847 baseLeft: Left volume at time base.
2850 \begin_layout Itemize
2851 baseRight: Right volume at time base
2854 \begin_layout Itemize
2855 blockNo: Sequence number of block filled.
2858 \begin_layout Itemize
2859 samples: Number of samples in block
2862 \begin_layout Itemize
2863 sampleTiming: Number of nanoseconds since last sample
2866 \begin_layout Itemize
2867 sampleLeft: Left channel samples
2870 \begin_layout Itemize
2871 sampleRight: Right channel samples
2874 \begin_layout Subsection
2875 Interface org.jpc.emulator.SoundOutputDevice
2878 \begin_layout Standard
2879 Implementing this interface signals that module has audio output channels.
2882 \begin_layout Subsubsection
2883 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
2886 \begin_layout Standard
2887 Return the number of sound channels module has.
2890 \begin_layout Subsubsection
2891 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
2894 \begin_layout Standard
2895 This is called once per sound channel requested giving precreated sound
2899 \begin_layout Subsection
2900 Class org.jpc.emulator.PC method getSoundOut(String)
2903 \begin_layout Standard
2904 Get sound output with specified name.
2907 \begin_layout Section
2908 Advanced: Writing event targets
2911 \begin_layout Standard
2912 Whereas output connectors are the way output is dispatched, input is dispatched
2914 Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
2917 \begin_layout Standard
2918 Event targets also provode methods which then encode events and dispatch
2919 them forward (without doing anything else) to event recorder.
2920 Also, event targets may have methods for obtaining state.
2923 \begin_layout Subsection
2924 Interface org.jpc.emulator.EventDispatchTarget
2927 \begin_layout Standard
2928 Interface that marks class capable of receiving events.
2931 \begin_layout Subsubsection
2932 Method setEventRecorder(EventRecorder)
2935 \begin_layout Standard
2936 Set the event recorder input events are sent to.
2939 \begin_layout Subsubsection
2940 Method startEventCheck()
2943 \begin_layout Standard
2944 Signals target to reset all state related to event checking and state feedback.
2945 This may be called at any time in order to reinitialialize event checking/feedb
2949 \begin_layout Subsubsection
2950 Method doEvent(long, String[], int) throws IOException
2953 \begin_layout Standard
2954 Event dispatch handler.
2955 The first argument is event time, second is parameters and third is what
2957 If target doesn't like the event, throw IOException.
2958 Following types (the integer parameter) are used:
2961 \begin_layout LyX-Code
2962 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
2965 \begin_layout LyX-Code
2966 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
2967 for reinitialization
2970 \begin_layout LyX-Code
2971 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
2974 \begin_layout LyX-Code
2975 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
2979 \begin_layout Subsubsection
2980 Method endEventCheock()
2983 \begin_layout Standard
2984 End event reinitialization.
2988 \begin_layout Subsubsection
2989 Method getEventTimeLowBound(long, String[]) throws IOException
2992 \begin_layout Standard
2993 Return the time value that's the earliest possiblity for this event to occur.
2994 Returning any time in past (including -1) causes event to fire as soon
2996 The long parameter gives the current scheduled time for event.
2999 \begin_layout Section
3003 \begin_layout Standard
3004 Modules are various extensions that run inside emulator core.
3005 As such, they affect sync.
3006 Modules must implement interface org.jpc.emulator.HardwareComponent (they
3007 are hardware components) and must be dumpable.
3008 Additionally, they need either constructor <init>() or <init>(String).
3009 The first is if no parameters are passed, the second is for case where
3010 parameters are passed.
3013 \begin_layout Standard
3014 Aside of the constructors, modules need to obey the ordinary conventions
3015 for hardware components.
3016 No code outside modules needs to know that module exists.
3019 \begin_layout Section
3023 \begin_layout Standard
3024 Plugins handle various UI tasks.
3025 They need to implement interface org.jpc.Plugin.
3028 \begin_layout Subsection
3029 Interface org.jpc.pluginsbase.Plugin
3032 \begin_layout Subsubsection
3033 Method systemShutdown()
3036 \begin_layout Standard
3037 Called when emulator shuts down.
3038 Either called in dedicated thread or in thread that called emulatorShutdown().
3039 These handlers should do the bare minimum to get files on disk to consistent
3041 After these calls from all plugins have finished, emulator exits.
3042 Do not try to manipulate UI from these methods, as doing that easily leads
3046 \begin_layout Subsubsection
3047 Method reconnect(PC)
3050 \begin_layout Standard
3051 Gives new PC to connect to.
3052 Null is passed if plugin should disconnect.
3055 \begin_layout Subsubsection
3059 \begin_layout Standard
3060 Called in dedicated thread after plugin is initialized.
3063 \begin_layout Subsubsection
3067 \begin_layout Standard
3068 Called after PC has stopped.
3071 \begin_layout Subsubsection
3075 \begin_layout Standard
3076 Called before PC starts.
3079 \begin_layout Subsubsection
3080 Method notifyArguments(String[])
3083 \begin_layout Standard
3084 Pass arguments from command line.
3087 \begin_layout Subsubsection
3088 Constructor <init>(Plugins)
3091 \begin_layout Standard
3092 This constructor is used to initialize plugins that don't take parameters.
3095 \begin_layout Subsubsection
3096 Constructor <init>(Plugins, String)
3099 \begin_layout Standard
3100 This constructor is used to initialize plugins that take parameters.
3103 \begin_layout Subsection
3104 Class org.jpc.pluginsbase.Plugins
3107 \begin_layout Standard
3108 This class provodes various methods for manipulating plugins.
3111 \begin_layout Subsubsection
3112 Method isShuttingDown()
3115 \begin_layout Standard
3116 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3117 via VM exit, CTRL+C or explicitly.
3118 Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3121 \begin_layout Subsubsection
3122 Method shutdownEmulator()
3125 \begin_layout Standard
3126 Shut down and exit the emulator.
3127 All plugin shutdown functions are called in this thread.
3130 \begin_layout Subsubsection
3131 Method reconnectPC(PC)
3134 \begin_layout Standard
3135 Signal reconnectPC event to all plugins.
3138 \begin_layout Subsubsection
3142 \begin_layout Standard
3143 Signal pcStarting() event to all plugins.
3146 \begin_layout Subsubsection
3150 \begin_layout Standard
3151 Signal pcStopping() event to all plugins.
3154 \begin_layout Subsection
3155 Interface org.jpc.pluginsbase.ExternalCommandInterface
3158 \begin_layout Standard
3159 Implementing interface org.jpc.pluginsbase.ExternalCommandInterface signals
3160 that plugin can receive commands via external commands interface.
3163 \begin_layout Subsubsection
3164 Method invokeCommand(String cmd, String[] args)
3167 \begin_layout Standard
3168 Invoke specified command using specified arguments.
3169 Return true if event is to be shallowed, false to continue trying to pass
3173 \begin_layout Section
3174 Lua kernel programming
3177 \begin_layout Standard
3178 At startup, kernel gets its arguments in 'args' table and the script name
3179 to run in 'scriptname' string.
3180 It should enter the named script in protected mode.
3183 \begin_layout Standard
3184 The Lua VM exports numerious callbacks to kernel.
3185 The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3188 \begin_layout Itemize
3189 Always grab any functions used into local variables so nobody can mess with
3193 \begin_layout Itemize
3194 Don't use global variables in kernel (except for those passed).
3197 \begin_layout Subsection
3201 \begin_layout Standard
3202 All standard Lua functions in tables main, 'math', 'coroutine', 'string'
3203 and 'table' (safe to re-export with exception of print, loadfile and dofile,
3204 which should be wrapped).
3207 \begin_layout Subsection
3208 Bit manipulation: none
3211 \begin_layout Standard
3212 Bitwise none function is exported as 'jpcrr_raw.bit_none(num...)'.
3213 It takes zero or more numbers and returns number (numbers have 48 bits).
3214 The number returned has those bits set that are set in none of inputs.
3218 \begin_layout Subsection
3219 Bit manipulation: any
3222 \begin_layout Standard
3223 Bitwise any function is exported as 'jpcrr_raw.bit_any(num...)'.
3224 It takes zero or more numbers and returns number (numbers have 48 bits).
3225 The number returned has those bits set that are set in any of inputs.
3229 \begin_layout Subsection
3230 Bit manipulation: parity
3233 \begin_layout Standard
3234 Bitwise parity function is exported as 'jpcrr_raw.bit_parity(num...)'.
3235 It takes zero or more numbers and returns number (numbers have 48 bits).
3236 The number returned has those bits set that are set in even number of of
3241 \begin_layout Subsection
3242 Bit manipulation: all
3245 \begin_layout Standard
3246 Bitwise parity function is exported as 'jpcrr_raw.bit_all(num...)'.
3247 It takes zero or more numbers and returns number (numbers have 48 bits).
3248 The number returned has those bits set that are set in all of inputs.
3252 \begin_layout Subsection
3253 Bit manipulation: lshift
3256 \begin_layout Standard
3257 Left shift function is exported as 'jpcrr_raw.bit_lshift(num base, num shift)'.
3258 It takes two numbers and returns first number shifted by second.
3260 Numbers have 48 bits, using shifts outside 0-47 gives unpredictable results.
3264 \begin_layout Subsection
3265 Bit manipulation: rshift
3268 \begin_layout Standard
3269 Right logical shift function is exported as 'jpcrr_raw.bit_rshift(num base,
3271 It takes two numbers and returns first number shifted by second number
3273 Numbers have 48 bits, using shifts outside 0-47 gives unpredictable results.
3277 \begin_layout Subsection
3278 Bit manipulation: arshift
3281 \begin_layout Standard
3282 Right arithmetic shift function is exported as 'jpcrr_raw.bit_arshift(num
3284 It takes two numbers and returns first number shifted by second number
3285 places right, with highest bit copied.
3286 Numbers have 48 bits, using shifts outside 0-47 gives unpredictable results.
3290 \begin_layout Subsection
3291 Bit manipulation: add
3294 \begin_layout Standard
3295 Add function is exported as 'jpcrr_raw.bit_add(num...)'.
3296 It takes zero or more numbers and returns number (numbers have 48 bits).
3297 The number returned is sum of all of inputs modulo
3298 \begin_inset Formula $2^{48}$
3305 \begin_layout Subsection
3306 Bit manipulation: addneg
3309 \begin_layout Standard
3310 Add negated function is exported as 'jpcrr_raw.bit_addneg(num...)'.
3311 It takes zero or more numbers and returns number (numbers have 48 bits).
3312 The number returned is 0 minus of all of inputs modulo
3313 \begin_inset Formula $2^{48}$
3320 \begin_layout Subsection
3321 Bit manipulation: addalt
3324 \begin_layout Standard
3325 Add alternate function is exported as 'jpcrr_raw.bit_addalt(num...)'.
3326 It takes zero or more numbers and returns number (numbers have 48 bits).
3327 The number returned is sum of odd arguments (first argument is odd) minus
3328 sum of even arguments modulo
3329 \begin_inset Formula $2^{48}$
3336 \begin_layout Subsection
3337 Bit manipulation: tohex
3340 \begin_layout Standard
3341 Add alternate function is exported as 'jpcrr_raw.bit_tohex(num number)'.
3342 It takes number and returns hexadecimal representation of it.
3346 \begin_layout Subsection
3350 \begin_layout Standard
3351 Console ouput function is exported as 'jpcrr_raw.print_console_msg(sring
3353 It prints its string argument as new line on Lua console (should not be
3354 re-exported, use to construct replacement print).
3357 \begin_layout Subsection
3361 \begin_layout Standard
3362 Binary I/O file open function is exported as 'jpcrr_raw.io_openbinary(string
3363 name, string mode)'.
3364 It takes two strings, first is name of file to open, second is mode, either
3366 \begin_inset Quotes eld
3370 \begin_inset Quotes erd
3374 \begin_inset Quotes eld
3378 \begin_inset Quotes erd
3382 The returned object has following methods:
3385 \begin_layout Itemize
3386 file:length(): Returns length of file as number.
3389 \begin_layout Itemize
3390 file:set_length(num len): Truncate file to len bytes.
3393 \begin_layout Itemize
3394 file:read(num offset, num length): Read up to length bytes starting from
3396 The file character set is assumed to be Latin1.
3399 \begin_layout Itemize
3400 file:write(num offset, string str): Write str starting from offset offset.
3401 Writing non-Latin1 characters gives unpredictable results.
3402 Only available on files opened for read/write.
3405 \begin_layout Itemize
3406 file:close(): Close file.
3407 No file operations can be done anymore.
3410 \begin_layout Standard
3411 The function should be filtered to enforce path constraints.
3414 \begin_layout Subsection
3418 \begin_layout Standard
3419 Text input open function is exported as 'jpcrr_raw.io_opentextinput(string
3421 It takes one string, name of file to open.
3422 The returned object has following methods:
3425 \begin_layout Itemize
3426 file:read(): Read next line.
3427 The file encoding is assumed to be UTF-8.
3430 \begin_layout Itemize
3431 file:close(): Close file.
3432 No file operations can be done anymore.
3435 \begin_layout Standard
3436 The function should be filtered to enforce path constraints.
3439 \begin_layout Subsection
3443 \begin_layout Standard
3444 Text output open function is exported as 'jpcrr_raw.io_opentextoutput(string
3446 It takes one string, name of file to open.
3447 The returned object has following methods:
3450 \begin_layout Itemize
3451 file:write(string line): Write line line to file.
3452 File encoding is assumed to be UTF-8.
3455 \begin_layout Itemize
3456 file:close(): Close file.
3457 No file operations can be done anymore.
3460 \begin_layout Standard
3461 The function should be filtered to enforce path constraints.
3464 \begin_layout Subsection
3468 \begin_layout Standard
3469 ECI invocation functions 'jpcrr_raw.invoke(string name [, table args])' and
3470 'jpcrr_raw.invoke_synchronous(string name [, table args])'.
3471 These functions run specified ECI function with specified arguments.
3472 The updates ECI call makes to arguments is reflected to table passed as
3474 The synchronous version waits that any slow command processing gets done
3475 before returning (assemble, save, load and dump have such slow processing).
3476 These functions return nothing.
3477 Safe to re-export, use as base for more functions.
3480 \begin_layout Subsection
3484 \begin_layout Standard
3485 'jpcrr_raw.pc_running()'.
3486 Returns true if PC is running, false otherwise.
3487 Assemble, save, load and dump require PC not being running to be possible.
3490 \begin_layout Subsection
3494 \begin_layout Standard
3495 'jpcrr_raw.pc_connected()'.
3496 Returns true if PC is connected, false otherwise.
3499 \begin_layout Subsection
3503 \begin_layout Standard
3504 'jpcrr_raw.wait_vga()' waits for VGA to enter frame hold mode and returns
3505 true (if it returns false, the wait got interrupted for some reason and
3506 VGA is in rendering mode).
3507 While VGA is in frame hold, PC execution is locked out and things like
3508 memory reading and writing can be done without races (but load/save is
3510 'jpcrr_raw.release_vga()' acknowledges frame hold processing (VGA can re-enter
3514 \begin_layout Standard
3515 Frame hold happens once per frame at start of vertical retrace.
3516 Note that running Lua script must wait frame holds and release them or
3517 main PC execution will hang on first frame hold.