1 #LyX 1.6.6 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 Subsection
99 \begin_layout Standard
100 See compile.sh or compile.bat.
101 The streamtools stuff is only needed for dumping videos.
104 \begin_layout Subsection
108 \begin_layout Standard
109 First you need to get and make some important images.
110 Obtain BIOS image, VGABIOS image and DOS boot floppy from somewhere.
111 After starting the emulator, use Drives -> Import Image to import the images
112 (ignore the error about no BIOS images being found).
115 \begin_layout Subsection
119 \begin_layout Standard
120 There is premade autoexec script called assemble.jpcrrinit that has fairly
125 \begin_layout LyX-Code
126 java JPCApplication -library library -autoexec assemble.jpcrrinit
129 \begin_layout Standard
131 \begin_inset Quotes eld
135 \begin_inset Quotes erd
138 specifies that contents of directory 'library' are to be used as library.
139 The script pops up settings for new emulated PC (if you want to load savestate,
141 Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
142 selected), DOSfloppy for fda (boot device should be set to fda) and game
143 image as some HD drive
146 \begin_layout Subsection
150 \begin_layout Itemize
151 Putting the game as hdd (the fourth hard disk slot) causes boot to be bit
155 \begin_layout Itemize
156 Some BIOS versions have
157 \begin_inset Quotes eld
160 press F12 to select boot device
161 \begin_inset Quotes erd
165 Hit <enter> from emulated keyboard and that prompt will go away in about
166 half emulated second (it stays several emulated seconds otherwise).
170 \begin_layout Itemize
171 If game doesn't need lots of memory, hitting F5 to skip intialization files
173 If it does need more memory, run config.sys commands but not autoexec.bat.
177 \begin_layout Itemize
178 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
182 \begin_layout Section
183 Making JPC-RR format images from raw images
186 \begin_layout Standard
187 Due to various factors, JPC-RR can't use raw image files directly but requires
188 its own image format.
192 \begin_layout Subsection
193 Importing images from GUI:
196 \begin_layout Standard
197 Use Drives -> Import Image to import existing directories or image files.
198 Dialog prompting parameters will be displayed.
199 When importing floppy images, check
200 \begin_inset Quotes eld
204 \begin_inset Quotes erd
207 if possible, that enables geometry autodetection, which is reasonable virtually
208 all of the time it is offered.
211 \begin_layout Subsection
215 \begin_layout Itemize
216 If making image from directory, the names of the files must conform to FAT
217 naming restrictions (8+3 character names, no spaces, etc).
218 Avoid filenames with non-ASCII characters.
222 \begin_layout Itemize
223 The DOS limit of 112 or 224 files for floppies does not apply to images
224 created from directory trees.
225 The minimum limit value used is 512.
226 If even that isn't enough, the limit is automatically increased to fit
227 all the needed directory entries.
230 \begin_layout Itemize
231 Making boot disks from tree does NOT work.
232 Even if you got system boot files there, it still won't work.
235 \begin_layout Itemize
236 Only floppy disks and hard drives can be made from directory trees.
237 BIOS images and CDROM images require image file.
240 \begin_layout Itemize
241 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
242 Disks with over 63 sectors per track don't work with DOS.
243 Wheither disks with over 127 tracks per side work with DOS is unknown.
244 Also avoid 1024-tracks per side HDDs.
247 \begin_layout Itemize
248 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
250 1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
251 1-16 sides for HDD, 1 or 2 sides for floppy.
252 This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
253 and 516096KiB for HDDs.
256 \begin_layout Itemize
257 There are multiple image file contents that represent the same image.
258 The one with smallest size is picked when creating image.
261 \begin_layout Itemize
262 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
266 \begin_layout Subsection
267 Importing from command line
270 \begin_layout Standard
271 There is tool called ImageMaker that can make JPC-RR images from raw images.
272 Each image has format, ID an name.
273 Format and name are specified when making image.
274 ID is automatically calculated from format and contents.
275 Name does not affect the ID but is purely for convience so one doesn't
276 have to specify long image IDs manually.
279 \begin_layout Subsubsection
283 \begin_layout Standard
284 The syntax for ImageMaker when making images is:
287 \begin_layout LyX-Code
288 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
291 \begin_layout Standard
292 <destination> is file name for JPC-RR format image to write.
293 <source> is either name of regular file (raw image file) or name of directory
294 tree with files (supported for making floppy or hard disk images only).
295 In case of directory tree, the files are layout deterministically to disk,
296 so the ID will always be the same for given geometry and type.
297 <name> is name to give to disk.
301 \begin_layout LyX-Code
302 --BIOS BIOS image (note: VGABIOS is also of this type).
305 \begin_layout LyX-Code
306 --CDROM CD-ROM image.
309 \begin_layout LyX-Code
310 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
313 \begin_layout LyX-Code
314 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
317 \begin_layout LyX-Code
318 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
321 \begin_layout LyX-Code
322 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
325 \begin_layout LyX-Code
326 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
329 \begin_layout LyX-Code
330 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
333 \begin_layout LyX-Code
334 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
337 \begin_layout LyX-Code
338 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
341 \begin_layout LyX-Code
342 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
345 \begin_layout LyX-Code
346 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
349 \begin_layout LyX-Code
350 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
353 \begin_layout LyX-Code
354 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
357 \begin_layout LyX-Code
358 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
361 \begin_layout LyX-Code
362 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
365 \begin_layout LyX-Code
366 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
369 \begin_layout LyX-Code
370 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
373 \begin_layout LyX-Code
374 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
377 \begin_layout LyX-Code
378 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
381 \begin_layout LyX-Code
382 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
385 \begin_layout LyX-Code
386 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
389 \begin_layout LyX-Code
390 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
393 \begin_layout LyX-Code
394 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
397 \begin_layout LyX-Code
398 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
401 \begin_layout LyX-Code
402 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
405 \begin_layout LyX-Code
406 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
409 \begin_layout LyX-Code
410 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
413 \begin_layout LyX-Code
414 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
417 \begin_layout LyX-Code
418 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
421 \begin_layout LyX-Code
422 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
425 \begin_layout LyX-Code
426 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
429 \begin_layout LyX-Code
430 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
433 \begin_layout Subsubsection
437 \begin_layout LyX-Code
438 --volumelabel=label Give specified volume label (affects ID).
439 Only meaningful when making image out of directory tree.
440 Default is no volume label.
443 \begin_layout LyX-Code
444 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
445 Only meaningful when making image out of directory tree.
446 The default timestamp is 19900101T000000Z.
449 \begin_layout Subsubsection
453 \begin_layout Standard
457 \begin_layout LyX-Code
458 $ java ImageMaker <imagefile>
461 \begin_layout Standard
462 Variety of information about image is displayed (especially for floppies/HDDs).
463 Two important fields are calculated and claimed disk ID.
464 They should be the same.
465 If they are not, then the image file is corrupt (sadly, imagemaker has
466 bugs and bugs that cause it to write corrupt images have been seen).
469 \begin_layout Subsection
470 Advanced: The disk ID algorithm
473 \begin_layout Standard
474 The disk ID is calculated as:
477 \begin_layout LyX-Code
478 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
481 \begin_layout Standard
482 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
483 state and 128-bit output using the deprecated rotation constants (as specified
484 in Skein hash function reference documentation versions 1.0 and 1.1).
485 The <image> is the whole image, including parts not stored in image file.
486 The reason for keeping using the deprecated constants are:
489 \begin_layout Itemize
490 Changing the constants would change the IDs, which would invalidate existing
494 \begin_layout Itemize
495 This is not about cryptographic security
498 \begin_layout Itemize
499 The new constants don't improve security that much anyway.
502 \begin_layout Subsubsection
506 \begin_layout Standard
507 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
508 <geometry> is as follows (this is exactly the same form as it appears in
512 \begin_layout LyX-Code
513 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
516 \begin_layout LyX-Code
517 Byte 0 bits 2-5: Head count - 1.
520 \begin_layout LyX-Code
521 Byte 0 bits 6-7: Reserved, must be 0.
524 \begin_layout LyX-Code
525 Byte 1: Bits 0-7 of track count per side - 1.
528 \begin_layout LyX-Code
529 Byte 2: Sector count per track - 1.
532 \begin_layout Subsubsection
533 CD-ROM and BIOS images
536 \begin_layout Standard
537 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
542 \begin_layout Subsection
543 Advanced: Disk Image format
546 \begin_layout Standard
547 The disk image consists of following parts, concatenated in this order without
551 \begin_layout Itemize
555 \begin_layout Itemize
559 \begin_layout Itemize
563 \begin_layout Itemize
567 \begin_layout Itemize
571 \begin_layout Itemize
572 type-specific geometry/size data
575 \begin_layout Itemize
579 \begin_layout Itemize
583 \begin_layout Subsubsection
587 \begin_layout Standard
588 Magic in disk image files is following 5 bytes:
589 \begin_inset Quotes eld
593 \begin_inset Quotes erd
599 \begin_layout Subsubsection
603 \begin_layout Standard
604 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
607 \begin_layout Subsubsection
611 \begin_layout Standard
612 Type code is single byte.
613 0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
614 Other values are reserved.
617 \begin_layout Subsubsection
621 \begin_layout Standard
623 Disk name length is given as two-byte big-endian value.
624 New images should have 0 here.
627 \begin_layout Subsubsection
631 \begin_layout Standard
633 Name field is there for backward compatiblity.
634 Disk name length gives length of this field in bytes.
637 \begin_layout Subsubsection
638 Type-specific geometry/size data (floppies and HDDs)
641 \begin_layout Standard
642 Floppies and HDDs have 3-byte geometry data:
645 \begin_layout LyX-Code
646 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
649 \begin_layout LyX-Code
650 Byte 0 bits 2-5: Head count - 1.
653 \begin_layout LyX-Code
654 Byte 0 bits 6-7: Reserved, must be 0.
657 \begin_layout LyX-Code
658 Byte 1: Bits 0-7 of track count per side - 1.
661 \begin_layout LyX-Code
662 Byte 2: Sector count per track - 1.
665 \begin_layout Subsubsection
666 Type specific-geometry/size data (CD-ROMs)
669 \begin_layout Standard
670 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
673 \begin_layout Subsubsection
674 Type specific-geometry/size data (BIOS images)
677 \begin_layout Standard
678 BIOS images have 4-byte big-endian byte (not sector or block) count.
681 \begin_layout Subsubsection
682 Actual image data (floppy/HDD)
685 \begin_layout Standard
686 Floppy or HDD imagedata consists of following subparts:
689 \begin_layout Itemize
693 \begin_layout Itemize
697 \begin_layout Itemize
701 \begin_layout Itemize
705 \begin_layout Standard
706 Storage method is single byte.
707 Sectors present gives number of last nonzero sector + 1 (zero if image
711 \begin_layout Subsubsection
712 Floppy/HDD storage method 0: Raw storage
715 \begin_layout Standard
716 This storage method has empty header.
717 Image data is raw dump of first sectors present sectors.
720 \begin_layout Subsubsection
721 Floppy/HDD storage method 1: Sectormap
724 \begin_layout Standard
725 Image data header contains bitfield with just enough bytes to have one bit
727 The order of bits is such that number of bit corresponding to each sector
728 in byte is sector number modulo 8 and byte number is floor of sector number
729 divided by 8 when sector numbers are counted from zero.
730 If bit corresponding to sector is set, then the sector is present in image
731 data, otherwise it is absent and assumed to be all-zeroes.
734 \begin_layout Standard
735 Image data contains dumps of all present sectors in order of increasing
739 \begin_layout Subsubsection
740 Floppy/HDD storage method 2: Extent first sector zero
743 \begin_layout Standard
744 Image data is empty as storage-specific data is mangled with image data.
745 The image data alternates between blocks encoding zero sectors and blocks
746 encoding nonzero sectors.
747 The first block encodes zero sectors.
751 \begin_layout Standard
752 Block encoding zero sectors consist of single 1-4 byte little-endian value
753 encoding number of sectors in block - 1.
754 Number of bytes is determined by sectors present value.
755 It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
756 for more than 16777216.
757 All sectors in block are filled with zeroes and are not stored.
760 \begin_layout Standard
761 Block encoding nonzero sectors has same block count as zero sector block
762 but is followed by the sectors stored raw.
765 \begin_layout Subsubsection
766 Floppy/HDD storage method 3: Extent first sector nonzero
769 \begin_layout Standard
770 Same as storage method 2 but first block is nonzero sector block.
773 \begin_layout Subsubsection
774 Actual image data (CD-ROMs and BIOS images)
777 \begin_layout Standard
778 These store image data raw.
779 The amount of data is specified by sector/byte count.
782 \begin_layout Subsubsection
786 \begin_layout Standard
787 Comments are given as list of strings, with UTF-8 encoded strings following
788 2-octet big-endian length.
789 Comment list is terminated by entry with length 0 (0x00 0x00).
790 Comments are optional and may be absent.
793 \begin_layout Section
797 \begin_layout Standard
798 The actual emulator is invoked as:
801 \begin_layout LyX-Code
802 $ java JPCApplication <options>...
805 \begin_layout Standard
806 The valid options are:
809 \begin_layout LyX-Code
810 -autoexec <script> Execute contents of specified file as commands when starting
814 \begin_layout LyX-Code
815 -noautoexec Don't run autoexec files.
818 \begin_layout LyX-Code
819 -norenames Copy&Delete files instead of renaming.
820 Mainly meant for debugging copy&delte code.
823 \begin_layout Standard
824 If no arguments are given, defaults of autoexec file of 'assemble.jpcrrinit'
828 \begin_layout Subsection
832 \begin_layout Standard
833 When emulator is started, command line comes up.
834 Following commands are known:
837 \begin_layout Itemize
838 'exit': exit immediately.
839 Dumps in progress are gracefully closed.
842 \begin_layout Itemize
843 'kill': Save stack traces and kill the emulator (for debugging only).
844 Any dumps in progress are likely corrupted.
847 \begin_layout Itemize
848 'library <library>': set library directory to <library>.
851 \begin_layout Itemize
852 'load <plugin>': Load plugin (no arguments)
855 \begin_layout Itemize
856 'load <plugin>(<arguments>)': load plugin with arguments.
859 \begin_layout Itemize
860 'command <command> [<arguments>...]': Invoke command via external command interface.
863 \begin_layout Itemize
864 'call<command> [<arguments>...]': Invoke command via external command interface
865 and print return values.
868 \begin_layout Itemize
869 'lsdisks [<filename>]' Print listing of all known disks.
870 If <filename> is specified, save output to specified file.
873 \begin_layout Itemize
874 'diskinfo [<filename>] <imagename>' Print Information about <imagename>
875 (can be disk name or ID).
876 If <filename> is specified, save output to specified file.
879 \begin_layout Standard
880 When one gets command line, its useful to load some plugins.
881 See section about plugins.
882 Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
883 like to start PC immediately.
886 \begin_layout Subsection
887 PC settings dialog notes
890 \begin_layout Itemize
891 CPU divider base frequency before division is 1GHz.
894 \begin_layout Itemize
895 Images can be specified by name or by ID.
896 Name is relative to library directory.
897 If the image is in subdirectory of image directory, the directory separator
898 is is '/' regardless of what the host OS uses.
901 \begin_layout Itemize
902 CD-ROM and hdc are mutually exclusive
905 \begin_layout Itemize
906 Modules is comma-seperated list of modules to load.
907 To pass arguments to some modules, enclose the arguments in ().
908 Same module can be specified twice only if parameters differ.
911 \begin_layout Itemize
912 Setting boot device doesn't work with some BIOS versions.
913 Those versions prompt the boot device anyway.
916 \begin_layout Subsection
917 Audio output channels
920 \begin_layout Standard
921 PC can have one or more audio output channels.
922 The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
924 Modules that have audio outputs get channel names of form <classname>-<sequenti
925 al>, where <classname> is name of main module class and sequential is number
927 Note that same module can have multiple output channels.
928 If multiple modules of same class request audio outputs, the <sequential>
929 values of subsequent module start where previous left off.
932 \begin_layout Subsection
936 \begin_layout Standard
937 Plugins actually execute the tasks of the emulator.
938 They can be loaded using
939 \begin_inset Quotes eld
943 \begin_inset Quotes erd
946 or 'load <plugin>(<arguments>)
947 \begin_inset Quotes erd
953 \begin_layout Standard
954 Different Plugins using the same output (like running PCMonitor and RAWVideoDump
955 er) should not conflict because connector output hold locking is desinged
956 to handle multiple readers.
959 \begin_layout Standard
960 If no plugin used requires GUI, then the emulator can be run without having
964 \begin_layout Subsubsection
965 plugin: org.jpc.plugins.PCControl
968 \begin_layout Standard
969 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1', requires and
973 \begin_layout Standard
974 Runs the PC emulator core.
975 Has capability to start/stop emulation, breakpoint after certain time or
976 start/end of VGA vertical retrace.
977 Also can create, savestate and loadstate PC emulation.
978 Memory dumping is supported.
982 \begin_layout Standard
983 'extramenu=<file>' causes Plugin to load extra menu entries from <file>.
984 'uncompressedsave=1' causes savestates to be written uncompressed (useful
985 if they are stored in VCS supporting delta compression).
988 \begin_layout Subsubsection
989 plugin: org.jpc.plugins.PCRunner
992 \begin_layout Standard
993 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
997 \begin_layout Standard
998 Loads PC from savestate and just runs it.
1000 Also automatically quits once stoptime is reached.
1003 \begin_layout Subsubsection
1004 plugin: org.jpc.plugins.PCMonitor
1007 \begin_layout Standard
1008 No arguments, requires and uses GUI.
1011 \begin_layout Standard
1012 VGA monitor for emulated PC.
1015 \begin_layout Subsubsection
1016 plugin: org.jpc.plugins.VirtualKeyboard
1019 \begin_layout Standard
1020 No arguments, requires and uses GUI.
1023 \begin_layout Standard
1024 On-screen keyboard for emulated PC.
1027 \begin_layout Subsubsection
1028 plugin: org.jpc.plugins.PCStartStopTest
1031 \begin_layout Standard
1032 No arguments, requires and uses GUI.
1035 \begin_layout Standard
1036 Small plugin testing remote PC start/stop.
1037 Also supports sending some common keypresses.
1040 \begin_layout Subsubsection
1041 plugin: org.jpc.plugins.RAWVideoDumper
1044 \begin_layout Standard
1045 Takes 'rawoutput=<file>' as argument.
1046 Does not require nor use GUI.
1049 \begin_layout Standard
1050 Dumps all generated frames to RAW file <file>.
1051 Rawoutput is required.
1052 The raw file consists of concatenation of zlib streams.
1053 The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1054 each acting as time offset of 2^32-1 nanoseconds and saved frames.
1055 The saved frame has time offset in nanoseconds (big endian) as first four
1056 bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1057 The next two bytes are big-endian width, next two big-endian height.
1058 Finally frame has 4 * width * height bytes of data that encodes pixels
1059 using 4 bytes per pixel, in left-to-right, up-to-down order.
1060 Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1061 green channel and byte 3 is blue channel.
1064 \begin_layout Standard
1065 Dumping to pipe is supported.
1068 \begin_layout Subsubsection
1069 plugin: org.jpc.plugins.RAWAudioDumper
1072 \begin_layout Standard
1073 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1074 'offset=<offset>' as arguments, separated by ','.
1075 Does not require nor use GUI.
1078 \begin_layout Standard
1079 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1080 file (file, mandatory).
1081 The resulting file consists of records, 4 or 8 bytes each.
1082 4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1084 \begin_inset Formula $2^{32}-1$
1088 Otherwise record is 8 bytes.
1089 Each 8 byte record has three fields.
1090 First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1092 \begin_inset Formula $2^{32}-1$
1095 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1096 big endian new right channel volume.
1097 Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1101 \begin_layout Subsubsection
1102 plugin: org.jpc.plugins.LuaPlugin
1105 \begin_layout Standard
1106 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1107 kernel, requires and uses GUI.
1110 \begin_layout Standard
1111 Lua VM for executing scripts.
1114 \begin_layout Subsubsection
1115 plugin: org.jpc.plugins.JoystickInput
1118 \begin_layout Standard
1120 Displays window for sending joystick input.
1123 \begin_layout Section
1127 \begin_layout Subsection
1128 org.jpc.modules.Joystick:
1131 \begin_layout Itemize
1135 \begin_layout Itemize
1136 Resources: I/O port 0x201
1139 \begin_layout Standard
1140 Emulates joystick game port.
1143 \begin_layout Subsection
1144 org.jpc.modules.SoundCard
1147 \begin_layout Itemize
1148 Arguments: Optional resources specification
1151 \begin_layout Itemize
1152 Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
1155 \begin_layout Standard
1156 Emulates Sound card.
1159 \begin_layout Subsection
1160 org.jpc.modules.FMCard
1163 \begin_layout Itemize
1164 Arguments: Optional resources specification
1167 \begin_layout Itemize
1168 Resources (defaults): I/O port 0x338-0x33B
1171 \begin_layout Standard
1175 \begin_layout Subsection
1176 org.jpc.modules.BasicFPU:
1179 \begin_layout Itemize
1183 \begin_layout Itemize
1187 \begin_layout Standard
1188 Crude FPU (x87) emulator.
1191 \begin_layout Section
1195 \begin_layout Standard
1196 Hacks are saved to savestates but not movies.
1199 \begin_layout Subsection
1203 \begin_layout Standard
1204 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1206 BIOS assumes system has FPU but some games use that bit to detect FPU,
1207 trying to use it if it is
1208 \begin_inset Quotes eld
1212 \begin_inset Quotes erd
1216 Try this if game startup hangs with lots of trying to use FPU but not present
1218 Don't use if there is FPU present.
1219 Needed to get games like Blake Stone / Wolfenstein 3-D to work (FPU emulator
1220 allows it to start but causes graphical glitches).
1223 \begin_layout Subsection
1227 \begin_layout Standard
1228 Update basic VGA parameters before vretrace, not after it.
1230 Commander Keen 4) don't like if this isn't done and some games (e.g.
1231 Mario & Luigi) don't like if it is done.
1232 Wrong value manifests as jerky scrolling (scrolling back and forth and
1233 fixed statusbars move).
1236 \begin_layout Section
1237 Some error messages and explanations
1240 \begin_layout Itemize
1241 <filename> is Not a valid image file
1244 \begin_layout Itemize
1245 <filename> is not image file
1248 \begin_layout Itemize
1249 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1253 \begin_layout Itemize
1254 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1258 \begin_layout Itemize
1259 Can't read disk image sector map.
1262 \begin_layout Itemize
1263 Can't read disk image extent.
1266 \begin_layout Standard
1267 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1268 image at all or its corrupt.
1271 \begin_layout Itemize
1272 <filename> is image of unknown type.
1275 \begin_layout Itemize
1276 <filename> has unrecognized geometry <x> <y> <z>
1279 \begin_layout Standard
1280 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1281 containing something current version can't comprehend.
1284 \begin_layout Itemize
1285 Invalid format specifier <something>.
1288 \begin_layout Itemize
1289 Invalid syntax of --floppy= or --HDD= option.
1292 \begin_layout Itemize
1293 Invalid format specifier/option <something>.
1296 \begin_layout Standard
1297 Invalid option or format specifier was given.
1301 \begin_layout Itemize
1302 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1305 \begin_layout Standard
1306 Check syntax of command.
1307 Especially that diskname is present!
1310 \begin_layout Itemize
1311 The image has <nnn> sectors while it should have <yyy> according to selected
1315 \begin_layout Itemize
1316 Raw image file length not divisible by 512.
1319 \begin_layout Itemize
1320 Trying to read sector out of range.
1323 \begin_layout Standard
1324 The selected geometry is wrong or raw image is incomplete.
1327 \begin_layout Itemize
1328 Invalid disk name (Should not happen!).
1331 \begin_layout Itemize
1332 Invalid geometry to be written.
1335 \begin_layout Standard
1336 This is a very likely a bug in program.
1339 \begin_layout Itemize
1340 What the heck <filename> is? It's not regular file nor directory.
1343 \begin_layout Standard
1344 That sort of file can't be used as input for image making, or the file just
1348 \begin_layout Itemize
1349 BIOS images can only be made out of regular files.
1352 \begin_layout Itemize
1353 CD images can only be made out of regular files.
1356 \begin_layout Standard
1357 Source image specified is not regular file, but image of that type can't
1358 be made of anything else.
1361 \begin_layout Itemize
1362 Can't read raw bios image file.
1365 \begin_layout Itemize
1366 Can't read sector <nnn> from image.
1369 \begin_layout Standard
1370 Reading the raw image file failed for some reason.
1373 \begin_layout Itemize
1374 Bad library line: "<something>".
1378 \begin_layout Standard
1379 Syntax error in image library.
1382 \begin_layout Itemize
1383 Removing image <something> a.k.a.
1384 "<something>" as it no longer exists.
1387 \begin_layout Standard
1388 The image file no longer exists so it gets removed from library.
1391 \begin_layout Itemize
1392 Removing image <something> a.k.a.
1393 "<something>" due to <some> conflict.
1396 \begin_layout Standard
1397 Image library code killed some image from library due to some kind of conflict
1398 with image being added.
1401 \begin_layout Itemize
1402 Too much data to fit into given space.
1405 \begin_layout Standard
1406 The tree you gave contains takes just too much space to fit into disk of
1410 \begin_layout Section
1411 Advanced: Savestate/movie format
1414 \begin_layout Subsection
1415 Special character classes
1418 \begin_layout Subsubsection
1422 \begin_layout Standard
1423 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1427 \begin_layout Itemize
1428 Codepoints 0x20, and 0x09.
1431 \begin_layout Itemize
1432 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1435 \begin_layout Itemize
1436 Codepoints 0x2000-0x200A.
1439 \begin_layout Subsubsection
1443 \begin_layout Standard
1444 Following byte sequences are interpretted as linefeeds (line change):
1447 \begin_layout Itemize
1448 Byte 0x0A (UTF-8 encoded codepoint 0x0A)
1451 \begin_layout Itemize
1452 Byte 0x0D (UTF-8 encoded codepoint 0x0D)
1455 \begin_layout Itemize
1456 Byte 0x1C (UTF-8 encoded codepoint 0x1C)
1459 \begin_layout Itemize
1460 Byte 0x1D (UTF-8 encoded codepoint 0x1D)
1463 \begin_layout Itemize
1464 Byte 0x1E (UTF-8 encoded codepoint 0x1E)
1467 \begin_layout Itemize
1468 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL, codepoint 0x85)
1471 \begin_layout Itemize
1472 Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
1475 \begin_layout Subsection
1479 \begin_layout Standard
1480 JRSR archive format packs multiple text archive members to text archive.
1481 It does not support binary members.
1482 JRSR archives have first five or six bytes form the magic.
1484 \begin_inset Quotes eld
1488 \begin_inset Quotes erd
1491 followed by LINEFEED character There are four kinds of lines after that
1492 (lines are terminated by LINEFEED byte/bytes):
1495 \begin_layout Itemize
1499 \begin_layout Itemize
1503 \begin_layout Itemize
1507 \begin_layout Itemize
1511 \begin_layout Standard
1512 Sequencing rules are as follows: Start member is allowed anywhere (after
1514 Member line is allowed only inside member (member started but not ended).
1515 End member is only allowed inside member.
1516 End of file is only allowed outside member.
1517 Blank line is allowed anywhere after magic.
1520 \begin_layout Subsubsection
1524 \begin_layout Standard
1525 Start member line is given as
1526 \begin_inset Quotes eld
1530 \begin_inset Quotes erd
1533 <SPACE>+ <membername> <LINEFEED>.
1534 <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1536 The member name is UTF-8 encoded and maximum allowed line length is 2048
1537 bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1538 depending on characters used).
1539 Starting member inside another implicitly ends the previous member.
1542 \begin_layout Subsubsection
1546 \begin_layout Standard
1547 Member line is given as
1548 \begin_inset Quotes eld
1552 \begin_inset Quotes erd
1555 <content><LINEFEED>.
1556 It gives another line for member contents.
1557 <content> is passed raw to layers above (followed by line termination)
1560 \begin_layout Subsubsection
1564 \begin_layout Standard
1565 End member line is given as
1566 \begin_inset Quotes eld
1570 \begin_inset Quotes erd
1574 It ends the current member.
1575 The following line can only be start member line or file may end.
1578 \begin_layout Subsubsection
1582 \begin_layout Standard
1583 Blank line is given as <LINEFEED>.
1584 Lines like that are ignored.
1587 \begin_layout Subsection
1588 Four-to-Five encoding
1591 \begin_layout Standard
1592 Binary members are encoded into text by so-called four-to-five encoding.
1593 This encoding can encode single byte to two, two bytes to three, three
1594 bytes to four and four bytes to five.
1595 Four-to-five encoding has five kinds of blocks.
1596 All SPACE and LINEFEED characters are completely ignored, even in middle
1600 \begin_layout Subsubsection
1604 \begin_layout Standard
1605 End stream block is encoded as '!'.
1606 It ends the stream instantly.
1607 There is also implicit end of stream at end of input to decoding.
1610 \begin_layout Subsubsection
1611 Other four block types
1614 \begin_layout Standard
1615 Other four block types take the value to be encoded, read it as big-endian
1617 Then they write it as base-93 big-endian value.
1618 Then length specific constants are added to digits of that number to yield
1619 ASCII values for characters (those are stored in order):
1622 \begin_layout Standard
1623 \begin_inset Tabular
1624 <lyxtabular version="3" rows="5" columns="6">
1626 <column alignment="center" valignment="top" width="0">
1627 <column alignment="center" valignment="top" width="0">
1628 <column alignment="center" valignment="top" width="0">
1629 <column alignment="center" valignment="top" width="0">
1630 <column alignment="center" valignment="top" width="0">
1631 <column alignment="center" valignment="top" width="0">
1633 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1636 \begin_layout Plain Layout
1642 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1645 \begin_layout Plain Layout
1651 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1654 \begin_layout Plain Layout
1660 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1663 \begin_layout Plain Layout
1669 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1672 \begin_layout Plain Layout
1678 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1681 \begin_layout Plain Layout
1689 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1692 \begin_layout Plain Layout
1698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1701 \begin_layout Plain Layout
1707 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1710 \begin_layout Plain Layout
1716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1719 \begin_layout Plain Layout
1725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1728 \begin_layout Plain Layout
1734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1737 \begin_layout Plain Layout
1745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1748 \begin_layout Plain Layout
1754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1757 \begin_layout Plain Layout
1763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1766 \begin_layout Plain Layout
1772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1775 \begin_layout Plain Layout
1781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1784 \begin_layout Plain Layout
1790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1793 \begin_layout Plain Layout
1801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1804 \begin_layout Plain Layout
1810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1813 \begin_layout Plain Layout
1819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1822 \begin_layout Plain Layout
1828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1831 \begin_layout Plain Layout
1837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1840 \begin_layout Plain Layout
1846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1849 \begin_layout Plain Layout
1857 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1860 \begin_layout Plain Layout
1866 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1869 \begin_layout Plain Layout
1875 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1878 \begin_layout Plain Layout
1884 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1887 \begin_layout Plain Layout
1893 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1896 \begin_layout Plain Layout
1902 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1905 \begin_layout Plain Layout
1919 \begin_layout Standard
1920 Blocks which encode values greater than what is possible for value of that
1921 length are fatal errors.
1925 \begin_layout Subsection
1926 Line component encoing
1929 \begin_layout Standard
1930 Line component encoding sits on top of UTF-8 encoding.
1931 Line component encoding encodes non-empty 1-D array of non-empty strings
1932 into line, and thus array of those into member.
1933 Empty lines or lines that don't contain any components are ignored.
1934 Line starts with depth value of 0 and must end with depth value of zero.
1937 \begin_layout Standard
1938 Components are seperated by component separators.
1939 Empty components are ignored.
1940 Following codepoints are separators on depth 0 if not escaped:
1943 \begin_layout Itemize
1945 The depth is read pre-increment.
1948 \begin_layout Itemize
1950 The depth is read post-decrement.
1953 \begin_layout Itemize
1957 \begin_layout Standard
1958 The following characters are special:
1961 \begin_layout Itemize
1963 Increments depth by 1 if not escaped (and appears in component).
1966 \begin_layout Itemize
1968 Decrements depth by 1 if not escaped (and appears in component).
1969 Depth going negative is an error.
1972 \begin_layout Itemize
1976 Next character is interpretted as literal.
1977 Error if at end of line.
1980 \begin_layout Standard
1981 Otherwise, characters are interpretted as literals and appear in components.
1982 Depth must be zero at end of line.
1985 \begin_layout Subsection
1989 \begin_layout Standard
1990 Header section is in archive member "header".
1991 It uses line component encoding.
1992 The first component of each line is name of header, and subsequent ones
1994 How many parameters are expected is dependent on what header it is:
1997 \begin_layout Subsubsection
2001 \begin_layout Itemize
2002 Header name: "PROJECTID"
2005 \begin_layout Itemize
2009 \begin_layout Itemize
2010 Argument #1: <project-id-string>
2013 \begin_layout Itemize
2017 \begin_layout Standard
2019 Project ID is generated when PC is assembled and is then preserved in save
2021 It is used for computing rerecord counts.
2022 Emulator treats it as opaque string, the IDs it generates are formed by
2023 48 random hexadecimal digits.
2026 \begin_layout Subsubsection
2030 \begin_layout Itemize
2031 Header name: "SAVESTATEID"
2034 \begin_layout Itemize
2038 \begin_layout Itemize
2039 Argument #1: <savestate-id-string>
2042 \begin_layout Itemize
2046 \begin_layout Standard
2047 Gives save state ID.
2048 Each save state has its own save state ID.
2049 Treated as opaque string, but generated as 48 random hexadecimal digits.
2050 The presence of this header signals whether there is save state to be loaded.
2051 If this header is present, save state load will be attempted.
2052 If absent, save state is not to be loaded even if present (and correct
2053 savestate load would be technically impossible anyway).
2056 \begin_layout Standard
2057 The value is used to prevent loading incompatible save states in preserve
2058 event stream mode and also to find the point in event stream where one
2062 \begin_layout Subsubsection
2066 \begin_layout Itemize
2067 Header name: "RERECORDS"
2070 \begin_layout Itemize
2074 \begin_layout Itemize
2075 Argument #1: <rerecords>
2078 \begin_layout Itemize
2082 \begin_layout Standard
2083 Gives rerecord count.
2084 PC assembly (except when loading save state) initializes current rerecord
2086 Must be non-negative and decimal number using ASCII digit characters.
2089 \begin_layout LyX-Code
2090 On loading save state:
2093 \begin_layout LyX-Code
2094 1) If project ID matches with previous:
2097 \begin_layout LyX-Code
2098 1a) If loaded rerecord count is larger or equal to current rerecord count:
2101 \begin_layout LyX-Code
2102 1a-a) Current rerecord count is loaded rerecord count + 1.
2105 \begin_layout LyX-Code
2109 \begin_layout LyX-Code
2110 1b-a) Current rerecord count increments by 1.
2113 \begin_layout LyX-Code
2117 \begin_layout LyX-Code
2118 2a) Current rerecord count is loaded rerecord count + 1.
2121 \begin_layout Standard
2122 The current rerecord count at time of save is saved to save state.
2125 \begin_layout Subsubsection
2129 \begin_layout Itemize
2130 Header name: "AUTHORS"
2133 \begin_layout Itemize
2134 Components: 2 or more
2137 \begin_layout Itemize
2138 Arguments: free form
2141 \begin_layout Itemize
2145 \begin_layout Standard
2146 Gives authors of run.
2147 Each argument gives one author (who has full name but no nickname).
2148 May be present multiple times.
2151 \begin_layout Subsubsection
2155 \begin_layout Itemize
2156 Header name: "AUTHORNICKS"
2159 \begin_layout Itemize
2160 Components: 2 or more
2163 \begin_layout Itemize
2164 Arguments: free form
2167 \begin_layout Itemize
2171 \begin_layout Standard
2172 Gives authors of run.
2173 Each argument gives one author (who has nickname but no full name).
2174 May be present multiple times.
2177 \begin_layout Subsubsection
2181 \begin_layout Itemize
2182 Header name: "AUTHORFULL"
2185 \begin_layout Itemize
2189 \begin_layout Itemize
2190 Arguments: free form
2193 \begin_layout Itemize
2197 \begin_layout Standard
2198 Gives author of run.
2199 First argument is full name of author, and second is nickname of author.
2200 May be present multiple times.
2203 \begin_layout Subsubsection
2207 \begin_layout Itemize
2208 Header name: "COMMENT"
2211 \begin_layout Itemize
2212 Components: 2 or more
2215 \begin_layout Itemize
2216 Arguments: free form
2219 \begin_layout Itemize
2223 \begin_layout Standard
2224 Various kinds of free form data.
2225 Not parsed further by emulator.
2228 \begin_layout Subsection
2229 Initialization segment:
2232 \begin_layout Standard
2233 If SAVESTATEID header isn't present (not a save state), member "initialization"
2234 gives PC initialization parameters for assembling the PC.
2235 It is present anyway even if SAVESTATEID is present (savestate).
2238 \begin_layout Standard
2239 Following parameters are used (space separates components):
2242 \begin_layout LyX-Code
2246 \begin_layout Standard
2247 Gives Image ID of main system BIOS (mandatory)
2250 \begin_layout LyX-Code
2254 \begin_layout Standard
2255 Gives Image ID of VGA BIOS (mandatory).
2258 \begin_layout LyX-Code
2262 \begin_layout Standard
2263 Gives Image ID of hda.
2264 Present only if system has hard disk hda.
2267 \begin_layout LyX-Code
2271 \begin_layout Standard
2272 Gives Image ID of hdb.
2273 Present only if system has hard disk hdb.
2276 \begin_layout LyX-Code
2280 \begin_layout Standard
2281 Gives Image ID of hdc.
2282 Present only if system has hard disk hdc.
2285 \begin_layout LyX-Code
2289 \begin_layout Standard
2290 Gives Image ID of hdd.
2291 Present only if system has hard disk hdd.
2294 \begin_layout LyX-Code
2298 \begin_layout Standard
2299 Gives Image ID of disk in slot <num>.
2300 Slot number must be non-negative.
2303 \begin_layout LyX-Code
2304 \begin_inset Quotes eld
2308 \begin_inset Quotes erd
2314 \begin_layout Standard
2315 kGives image name of disk in slot <num>.
2316 Slot number must be non-negative.
2317 The slot must be previously declared using
2318 \begin_inset Quotes eld
2322 \begin_inset Quotes erd
2328 \begin_layout LyX-Code
2332 \begin_layout Standard
2333 Gives Image slot to initially put into floppy drive fda.
2334 Disk must be of floppy type.
2335 If none present, no disk is initially put there.
2338 \begin_layout LyX-Code
2342 \begin_layout Standard
2343 Gives Image slot to initially put into floppy drive fdb.
2344 Disk must be of floppy type.
2345 If none present, no disk is initially put there.
2348 \begin_layout LyX-Code
2352 \begin_layout Standard
2353 Gives Image slot to initially put into CD-ROM drive hdc.
2354 Not allowed if hard disk hdc is present.
2355 Disk must be of CD-ROM type.
2356 If none present no disk is initially put there.
2359 \begin_layout LyX-Code
2360 "INITIALTIME" <time>
2363 \begin_layout Standard
2364 Number of milliseconds since Unix epoch to system start up time.
2368 \begin_layout Standard
2373 \begin_layout LyX-Code
2374 "CPUDIVIDER" <divider>
2377 \begin_layout Standard
2378 Set CPU frequency divider (dividing the 1GHz master clock).
2379 Allowed range is 1-256.
2383 \begin_layout LyX-Code
2384 "MEMORYSIZE" <pages>
2387 \begin_layout Standard
2388 Number of 4KiB pages of RAM memory.
2389 Allowed range 256-262144.
2393 \begin_layout LyX-Code
2397 \begin_layout Standard
2399 Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2403 \begin_layout LyX-Code
2404 "LOADMODULEA" <module> <parameters>
2407 \begin_layout Standard
2408 Load module <module> with parameters <parameters>.
2411 \begin_layout LyX-Code
2412 "LOADMODULE" <module>
2415 \begin_layout Standard
2416 Load module <module> with no parameters
2419 \begin_layout LyX-Code
2420 \begin_inset Quotes eld
2424 \begin_inset Quotes erd
2430 \begin_layout Standard
2431 Use class <fpu> as FPU emulator.
2434 \begin_layout LyX-Code
2435 \begin_inset Quotes eld
2439 \begin_inset Quotes erd
2445 \begin_layout Standard
2446 Use I/O port delay emulation (each I/O port read/write takes 666ns).
2449 \begin_layout LyX-Code
2450 \begin_inset Quotes eld
2454 \begin_inset Quotes erd
2460 \begin_layout Standard
2461 Emulate VGA horizontal retrace.
2464 \begin_layout Subsection
2465 Event record format:
2468 \begin_layout Standard
2469 Event record is in archive member "events".
2470 It uses line component encoding.
2471 Each line gives an event.
2472 First component of each line gives time stamp.
2473 These timestamps MUST be in increasing order and all MUST be non-negative.
2474 Time stamp time unit is exactly 1 nanosecond of emulated time.
2477 \begin_layout Standard
2478 The second component of each line is name of class to dispatch to.
2479 Further components are passed as-is to event handlers.
2480 Classes with names consisting only of uppercase A-Z and 0-9 are special
2482 It is error to encounter unknown such special class.
2485 \begin_layout Subsubsection
2489 \begin_layout Itemize
2490 Dispatch to: SAVESTATE
2493 \begin_layout Itemize
2494 Argument #1: Savestate id
2497 \begin_layout Itemize
2498 Argument #2 (optional): Rerecord count at time of saving savestate
2501 \begin_layout Standard
2502 Signals that savestate has occured here.
2503 The save state IDs MUST be unique in entire event stream.
2504 The second argument to savestate (if present) is rerecord count at time
2505 of saving that savestate (useful for calulating rerecord count of movie
2506 starting from savestate).
2507 No time restrictions
2510 \begin_layout Subsubsection
2514 \begin_layout Itemize
2518 \begin_layout Itemize
2520 \begin_inset Quotes eld
2524 \begin_inset Quotes erd
2528 \begin_inset Quotes eld
2532 \begin_inset Quotes erd
2538 \begin_layout Standard
2539 Controls various options.
2541 \begin_inset Quotes eld
2545 \begin_inset Quotes erd
2548 turns on absolute mode (default) where event timestamps are absolute.
2550 \begin_inset Quotes eld
2554 \begin_inset Quotes erd
2557 turns on relative mode where event timestamps are relative to last event
2559 The OPTION event itself is not affected by timing change.
2560 No time restrictions.
2561 Unknown arguments are errors.
2564 \begin_layout Subsubsection
2565 Keyboard keypress/keyrelease event:
2568 \begin_layout Itemize
2569 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2572 \begin_layout Itemize
2573 Argument #1: Fixed: "KEYEDGE"
2576 \begin_layout Itemize
2577 Argument #2: Key number.
2578 Valid values are 1-83, 85-95, 129-197 and 199-223
2581 \begin_layout Standard
2582 Send key press or key release.
2583 Keys work in toggle button manner.
2584 The event time must be multiple of 66 666, and must not be less than 60
2585 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2586 on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2589 \begin_layout Subsubsection
2593 \begin_layout Itemize
2594 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2597 \begin_layout Itemize
2598 Argument #1: Fixed: "PAUSE"
2601 \begin_layout Standard
2602 Send pause key event.
2603 The time restrictions are identical to KEYEDGE event.
2606 \begin_layout Subsubsection
2610 \begin_layout Itemize
2611 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2614 \begin_layout Itemize
2615 Argument #1: Fixed: "MOUSEBUTTON"
2618 \begin_layout Itemize
2619 Argument #2: Number of button to release or press (0-4)
2622 \begin_layout Standard
2623 Presses or releases the designated mouse button.
2626 \begin_layout Subsubsection
2627 X mouse motion event:
2630 \begin_layout Itemize
2631 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2634 \begin_layout Itemize
2635 Argument #1: Fixed: "XMOUSEMOTION"
2638 \begin_layout Itemize
2639 Argument #2: Number of units to move (-255 - 255)
2642 \begin_layout Standard
2643 Move the mouse in X direction by specified amount.
2647 \begin_layout Subsubsection
2648 Y mouse motion event:
2651 \begin_layout Itemize
2652 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2655 \begin_layout Itemize
2656 Argument #1: Fixed: "YMOUSEMOTION"
2659 \begin_layout Itemize
2660 Argument #2: Number of units to move (-255 - 255)
2663 \begin_layout Standard
2664 Move the mouse in Y direction by specified amount.
2668 \begin_layout Subsubsection
2669 Z mouse motion event:
2672 \begin_layout Itemize
2673 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2676 \begin_layout Itemize
2677 Argument #1: Fixed: "ZMOUSEMOTION"
2680 \begin_layout Itemize
2681 Argument #2: Number of units to move (-7 - 7)
2684 \begin_layout Standard
2685 Move the mouse in Z direction (scrollwheel) by specified amount.
2688 \begin_layout Subsubsection
2689 Joystick button event:
2692 \begin_layout Itemize
2693 Dispatch to: org.jpc.modules.Joystick
2696 \begin_layout Itemize
2698 \begin_inset Quotes eld
2702 \begin_inset Quotes erd
2706 \begin_inset Quotes eld
2710 \begin_inset Quotes erd
2714 \begin_inset Quotes eld
2718 \begin_inset Quotes erd
2722 \begin_inset Quotes eld
2726 \begin_inset Quotes erd
2732 \begin_layout Itemize
2734 \begin_inset Quotes eld
2738 \begin_inset Quotes erd
2742 \begin_inset Quotes eld
2746 \begin_inset Quotes erd
2752 \begin_layout Standard
2753 Send button down/up event.
2754 No time restrictions.
2757 \begin_layout Subsubsection
2758 Joystick axis event:
2761 \begin_layout Itemize
2762 Dispatch to: org.jpc.modules.Joystick
2765 \begin_layout Itemize
2767 \begin_inset Quotes eld
2771 \begin_inset Quotes erd
2775 \begin_inset Quotes eld
2779 \begin_inset Quotes erd
2783 \begin_inset Quotes eld
2787 \begin_inset Quotes erd
2791 \begin_inset Quotes eld
2795 \begin_inset Quotes erd
2801 \begin_layout Itemize
2802 Argument #2: Multivibrator unstable state length in ns.
2805 \begin_layout Standard
2806 Set amount of time multivibrator remains in unstable state.
2807 No time restrictions.
2810 \begin_layout Subsubsection
2814 \begin_layout Itemize
2815 Dispatch to: org.jpc.emulator.PC$ResetButton
2818 \begin_layout Itemize
2822 \begin_layout Standard
2826 \begin_layout Subsubsection
2830 \begin_layout Itemize
2831 Dispatch to: org.jpc.emulator.PC$DiskChanger
2834 \begin_layout Itemize
2835 Argument #1: Fixed: "FDA"
2838 \begin_layout Itemize
2839 Argument #2: Number of image slot to put there.
2843 \begin_layout Standard
2844 The disk number MUST be -1 or valid disk number.
2845 -1 MUST NOT be used if there is no disk in floppy drive A.
2846 This event causes specified disk to be placed to FDA or FDA disk to be
2847 ejected with no replacement if disk number is -1.
2848 The specified disk if not -1 must be of floppy type.
2849 The specified disk if valid must not be in any other drive.
2852 \begin_layout Subsubsection
2856 \begin_layout Itemize
2857 Dispatch to: org.jpc.emulator.PC$DiskChanger
2860 \begin_layout Itemize
2861 Argument #1: Fixed: "FDB"
2864 \begin_layout Itemize
2865 Argument #2: Number of image slot to put there.
2869 \begin_layout Standard
2870 The disk number MUST be -1 or valid disk number.
2871 -1 MUST NOT be used if there is no disk in floppy drive B.
2872 This event causes specified disk to be placed to FDB or FDB disk to be
2873 ejected with no replacement if disk number is -1.
2874 The specified disk if not -1 must be of floppy type.
2875 The specified disk if valid must not be in any other drive.
2878 \begin_layout Subsubsection
2882 \begin_layout Itemize
2883 Dispatch to: org.jpc.emulator.PC$DiskChanger
2886 \begin_layout Itemize
2887 Argument #1: Fixed: "CDROM"
2890 \begin_layout Itemize
2891 Argument #2: Number of image slot to put there.
2895 \begin_layout Standard
2896 The disk number MUST be -1 or valid disk number.
2897 -1 MUST NOT be used if there is no disk in CD-ROM.
2898 This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2899 to be ejected with no replacement if disk number is -1.
2900 The specified disk if not -1 must be of CD-ROM type.
2903 \begin_layout Standard
2904 This event has no effect if CD-ROM is locked.
2907 \begin_layout Subsubsection
2908 Write protect floppy:
2911 \begin_layout Itemize
2912 Dispatch to: org.jpc.emulator.PC$DiskChanger
2915 \begin_layout Itemize
2916 Argument #1: Fixed: "WRITEPROTECT"
2919 \begin_layout Itemize
2920 Argument #2: Number of image slot to manipulate
2923 \begin_layout Standard
2924 Write protects specified disk.
2925 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2928 \begin_layout Subsubsection
2929 Write unprotect floppy:
2932 \begin_layout Itemize
2933 Dispatch to: org.jpc.emulator.PC$DiskChanger
2936 \begin_layout Itemize
2937 Argument #1: Fixed: "WRITEUNPROTECT"
2940 \begin_layout Itemize
2941 Argument #2: Number of image slot to manipulate
2944 \begin_layout Standard
2945 Disables write protection specified disk.
2946 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2949 \begin_layout Subsection
2953 \begin_layout Standard
2954 Diskinfo sections are named
2955 \begin_inset Quotes eld
2959 \begin_inset Quotes erd
2963 They use line component encoding, fieldtype being first component on each
2964 line (value being the second).
2965 Following fields are defined:
2968 \begin_layout Subsubsection
2972 \begin_layout Standard
2973 Gives type of image.
2977 \begin_layout Itemize
2978 \begin_inset Quotes eld
2982 \begin_inset Quotes erd
2988 \begin_layout Itemize
2989 \begin_inset Quotes eld
2993 \begin_inset Quotes erd
2999 \begin_layout Itemize
3000 \begin_inset Quotes eld
3004 \begin_inset Quotes erd
3010 \begin_layout Itemize
3011 \begin_inset Quotes eld
3015 \begin_inset Quotes erd
3018 (BIOS/VGABIOS image)
3021 \begin_layout Itemize
3022 \begin_inset Quotes eld
3026 \begin_inset Quotes erd
3029 (what the heck is this???)
3032 \begin_layout Subsubsection
3036 \begin_layout Standard
3040 \begin_layout Subsubsection
3044 \begin_layout Standard
3045 (BIOS images only) Gives length of BIOS image
3048 \begin_layout Subsubsection
3052 \begin_layout Standard
3053 MD5 of raw disk/BIOS image without any headers or trailers.
3056 \begin_layout Subsubsection
3060 \begin_layout Standard
3061 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
3064 \begin_layout Subsubsection
3068 \begin_layout Standard
3069 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
3073 \begin_layout Subsubsection
3077 \begin_layout Standard
3078 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
3082 \begin_layout Subsubsection
3086 \begin_layout Standard
3087 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
3091 \begin_layout Subsubsection
3095 \begin_layout Standard
3096 Line from image comment block.
3097 Usually give data about files image has.
3098 May or may not be present (multiple times)
3101 \begin_layout Subsection
3105 \begin_layout Standard
3106 Output info is stored in section
3107 \begin_inset Quotes eld
3111 \begin_inset Quotes erd
3115 Its relatively new, so it might not be present (then the contents have
3116 to be guessed based on modules present).
3117 Each line gives information about one output, first field being the type
3121 \begin_layout Subsubsection
3125 \begin_layout Standard
3126 For video output, there are no parameters so line is just
3127 \begin_inset Quotes eld
3131 \begin_inset Quotes erd
3137 \begin_layout Subsubsection
3141 \begin_layout Standard
3142 For audio output, the only parameter is name of output, so first component
3144 \begin_inset Quotes eld
3148 \begin_inset Quotes erd
3151 and second component is name of audio output.
3154 \begin_layout Subsection
3158 \begin_layout Standard
3159 Actual savestate format is not documented here.
3160 It is close to impossible to comprehend without access to emulator source
3164 \begin_layout Section
3165 Advanced: Making class dumpable
3168 \begin_layout Standard
3169 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
3170 and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
3171 <init>(org.jpc.emulator.SRLoader).
3172 Non-static inner classes can not be dumpable (make them static using tricks
3173 similar to what javac uses).
3176 \begin_layout Standard
3177 If dumped class has dumpable superclass, the first thing dumping function
3178 needs to do is to call dumper function of superclass and first thing loading
3179 constructor needs to do is to call loading constructor of superclass.
3180 If class has no dumpable superclass, dumper doesn't need to do anything
3181 special, while loader needs to call objectCreated(this) on SRLoader object
3182 passed as parameter.
3186 \begin_layout Standard
3187 Following these fixed parts, dump all members that are part of mutable state
3191 \begin_layout Subsection
3192 Member dumping/loading functions
3195 \begin_layout Standard
3196 There is dumping/loading function for following (all functions dumping/loading
3197 reference types can handle null):
3200 \begin_layout Itemize
3201 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
3204 \begin_layout Itemize
3205 byte: SRDumper.dumpByte, SRLoader.loadByte
3208 \begin_layout Itemize
3209 short: SRDumper.dumpShort, SRLoader.loadShort
3212 \begin_layout Itemize
3213 int: SRDumper.dumpInt, SRLoader.loadInt
3216 \begin_layout Itemize
3217 long: SRDumper.dumpLong, SRLoader.loadLong
3220 \begin_layout Itemize
3221 String: SRDumper.dumpString, SRLoader.loadString
3224 \begin_layout Itemize
3225 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
3228 \begin_layout Itemize
3229 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
3232 \begin_layout Itemize
3233 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
3236 \begin_layout Itemize
3237 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
3240 \begin_layout Itemize
3241 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
3244 \begin_layout Itemize
3245 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
3248 \begin_layout Itemize
3249 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
3252 \begin_layout Itemize
3253 special object: SRDumper.specialObject, SRLoader.specialObject
3256 \begin_layout Subsubsection
3260 \begin_layout Itemize
3261 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
3264 \begin_layout Itemize
3265 Special objects are various static objects that don't need to be stored
3266 because they don't have mutable fields.
3269 \begin_layout Itemize
3270 Don't dump fields related to event state feedback.
3273 \begin_layout Itemize
3274 Don't dump temporary flags that are only used while PC is running.
3275 Savestate when PC is running isn't possible anyway.
3278 \begin_layout Itemize
3279 Some connectors dump fields related to connector output, some don't.
3282 \begin_layout Section
3283 Advanced: Making output connectors
3286 \begin_layout Standard
3287 Implementing interface org.jpc.emulator.DisplayController signals that this
3288 is display controller, inhibiting loading of the standard VGA display controlle
3289 r if loaded as module.
3293 \begin_layout Subsection
3294 Interface org.jpc.emulator.OutputConnector
3297 \begin_layout Standard
3298 Class is made to be output connector by implementing this interface.
3299 This interface specifies the methods used for output hold locking.
3300 Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3301 that are suitable for calling.
3305 \begin_layout Subsubsection
3306 Method subscribeOutput(Object)
3309 \begin_layout Standard
3310 Subscribes the output, with specified object as handle.
3313 \begin_layout Subsubsection
3314 Method unsubscribeOutput(Object)
3317 \begin_layout Standard
3318 Unsubscribe the specified handle object from output.
3321 \begin_layout Subsubsection
3322 Method waitOutput(Object)
3325 \begin_layout Standard
3326 Wait for output on specified connector using specified handle object.
3327 Returns true on success, false if wait was interrupted by thread interrupt.
3331 \begin_layout Subsubsection
3332 Method releaseOutput(Object)
3335 \begin_layout Standard
3336 Release connector from p.o.v.
3341 \begin_layout Subsubsection
3345 \begin_layout Standard
3346 Release threads waiting on waitOutput() and block until all subscribers
3347 have returned from waitOutput() and enteired releaseOutput().
3350 \begin_layout Subsubsection
3351 Method releaseOutputWaitAll(object)
3354 \begin_layout Standard
3355 Like releaseOutput(), but waits until all handles have released their output.
3358 \begin_layout Subsection
3359 Class org.jpc.emulator.VGADigtalOut
3362 \begin_layout Standard
3363 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3364 VGA output connector.
3365 If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3369 \begin_layout Subsubsection
3373 \begin_layout Standard
3374 Get width of display (watch out, can return 0).
3377 \begin_layout Subsubsection
3381 \begin_layout Standard
3382 Get height of display (watch out, can return 0).
3385 \begin_layout Subsubsection
3386 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3389 \begin_layout Standard
3390 Returns the dirty region (region modified since last output).
3393 \begin_layout Subsubsection
3397 \begin_layout Standard
3398 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3399 one value per pixel) giving pixel data.
3400 Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3404 \begin_layout Subsubsection
3405 Method resizeDisplay(int _width, int _height)
3408 \begin_layout Standard
3409 Resize the display to be of specified size.
3412 \begin_layout Subsubsection
3413 Method dirtyDisplayRegion(int x, int y, int w, int h)
3416 \begin_layout Standard
3417 Mark the specified region as dirty.
3420 \begin_layout Subsubsection
3421 Method resetDirtyRegion()
3424 \begin_layout Standard
3425 Resets the dirty region to be empty.
3428 \begin_layout Subsection
3429 Class org.jpc.emulator.PC method getVideoOutput()
3432 \begin_layout Standard
3433 Get VGA output connector for PC.
3436 \begin_layout Subsection
3437 Interface org.jpc.emulator.DisplayController.
3440 \begin_layout Standard
3441 Implementing this class signals that module is VGA controller.
3442 There can be only one such module active at time and presence of such module
3443 prevents loading builtin VGA controller emulation code.
3446 \begin_layout Subsubsection
3447 Method getOutputDevice()
3450 \begin_layout Standard
3451 Get VGA output connector for this VGA device.
3454 \begin_layout Subsection
3455 Class org.jpc.emulator.SoundDigitalOut
3458 \begin_layout Standard
3459 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3460 Each connector can transfer stereo signal at arbitiary sampling rate.
3461 Modules that have audio connectors need to implement interface org.jpc.emulator.So
3462 undOutputDevice, as this signals that output connectors should be created.
3465 \begin_layout Subsubsection
3466 Method addSample(long, short, short)
3469 \begin_layout Standard
3470 Add stereo sample at time given by first argument.
3471 The second and third arguments give volume on left and right channels.
3474 \begin_layout Subsubsection
3475 Method addSample(long, short)
3478 \begin_layout Standard
3479 Add mono sample at time given by first argument.
3480 The second argument give volume on both channels.
3483 \begin_layout Subsubsection
3484 Method readBlock(Block)
3487 \begin_layout Standard
3488 Reads block of output (atomic versus addSample).
3489 Block structure has following fields which are filled:
3492 \begin_layout Itemize
3493 timeBase: Time base for block.
3496 \begin_layout Itemize
3497 baseLeft: Left volume at time base.
3500 \begin_layout Itemize
3501 baseRight: Right volume at time base
3504 \begin_layout Itemize
3505 blockNo: Sequence number of block filled.
3508 \begin_layout Itemize
3509 samples: Number of samples in block
3512 \begin_layout Itemize
3513 sampleTiming: Number of nanoseconds since last sample
3516 \begin_layout Itemize
3517 sampleLeft: Left channel samples
3520 \begin_layout Itemize
3521 sampleRight: Right channel samples
3524 \begin_layout Subsection
3525 Interface org.jpc.emulator.SoundOutputDevice
3528 \begin_layout Standard
3529 Implementing this interface signals that module has audio output channels.
3532 \begin_layout Subsubsection
3533 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3536 \begin_layout Standard
3537 Return the number of sound channels module has.
3540 \begin_layout Subsubsection
3541 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3544 \begin_layout Standard
3545 This is called once per sound channel requested giving precreated sound
3549 \begin_layout Subsection
3550 Class org.jpc.emulator.PC method getSoundOut(String)
3553 \begin_layout Standard
3554 Get sound output with specified name.
3557 \begin_layout Section
3558 Advanced: Writing event targets
3561 \begin_layout Standard
3562 Whereas output connectors are the way output is dispatched, input is dispatched
3564 Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3567 \begin_layout Standard
3568 Event targets also provode methods which then encode events and dispatch
3569 them forward (without doing anything else) to event recorder.
3570 Also, event targets may have methods for obtaining state.
3573 \begin_layout Subsection
3574 Interface org.jpc.emulator.EventDispatchTarget
3577 \begin_layout Standard
3578 Interface that marks class capable of receiving events.
3581 \begin_layout Subsubsection
3582 Method setEventRecorder(EventRecorder)
3585 \begin_layout Standard
3586 Set the event recorder input events are sent to.
3589 \begin_layout Subsubsection
3590 Method startEventCheck()
3593 \begin_layout Standard
3594 Signals target to reset all state related to event checking and state feedback.
3595 This may be called at any time in order to reinitialialize event checking/feedb
3599 \begin_layout Subsubsection
3600 Method doEvent(long, String[], int) throws IOException
3603 \begin_layout Standard
3604 Event dispatch handler.
3605 The first argument is event time, second is parameters and third is what
3607 If target doesn't like the event, throw IOException.
3608 Following types (the integer parameter) are used:
3611 \begin_layout LyX-Code
3612 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3615 \begin_layout LyX-Code
3616 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3617 for reinitialization
3620 \begin_layout LyX-Code
3621 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3624 \begin_layout LyX-Code
3625 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3629 \begin_layout Subsubsection
3630 Method endEventCheock()
3633 \begin_layout Standard
3634 End event reinitialization.
3638 \begin_layout Subsubsection
3639 Method getEventTimeLowBound(long, String[]) throws IOException
3642 \begin_layout Standard
3643 Return the time value that's the earliest possiblity for this event to occur.
3644 Returning any time in past (including -1) causes event to fire as soon
3646 The long parameter gives the current scheduled time for event.
3649 \begin_layout Section
3653 \begin_layout Standard
3654 Modules are various extensions that run inside emulator core.
3655 As such, they affect sync.
3656 Modules must implement interface org.jpc.emulator.HardwareComponent (they
3657 are hardware components) and must be dumpable.
3658 Additionally, they need either constructor <init>() or <init>(String).
3659 The first is if no parameters are passed, the second is for case where
3660 parameters are passed.
3663 \begin_layout Standard
3664 Aside of the constructors, modules need to obey the ordinary conventions
3665 for hardware components.
3666 No code outside modules needs to know that module exists.
3669 \begin_layout Section
3673 \begin_layout Standard
3674 Plugins handle various UI tasks.
3675 They need to implement interface org.jpc.Plugin.
3678 \begin_layout Subsection
3679 Interface org.jpc.pluginsbase.Plugin
3682 \begin_layout Subsubsection
3683 Method systemShutdown()
3686 \begin_layout Standard
3687 Called when emulator shuts down.
3688 Either called in dedicated thread or in thread that called emulatorShutdown().
3689 These handlers should do the bare minimum to get files on disk to consistent
3691 After these calls from all plugins have finished, emulator exits.
3692 Do not try to manipulate UI from these methods, as doing that easily leads
3696 \begin_layout Subsubsection
3697 Method reconnect(PC)
3700 \begin_layout Standard
3701 Gives new PC to connect to.
3702 Null is passed if plugin should disconnect.
3705 \begin_layout Subsubsection
3709 \begin_layout Standard
3710 Called in dedicated thread after plugin is initialized.
3713 \begin_layout Subsubsection
3717 \begin_layout Standard
3718 Called after PC has stopped.
3721 \begin_layout Subsubsection
3725 \begin_layout Standard
3726 Called before PC starts.
3729 \begin_layout Subsubsection
3730 Method notifyArguments(String[])
3733 \begin_layout Standard
3734 Pass arguments from command line.
3737 \begin_layout Subsubsection
3738 Constructor <init>(Plugins)
3741 \begin_layout Standard
3742 This constructor is used to initialize plugins that don't take parameters.
3745 \begin_layout Subsubsection
3746 Constructor <init>(Plugins, String)
3749 \begin_layout Standard
3750 This constructor is used to initialize plugins that take parameters.
3753 \begin_layout Subsection
3754 Class org.jpc.pluginsbase.Plugins
3757 \begin_layout Standard
3758 This class provodes various methods for manipulating plugins.
3761 \begin_layout Subsubsection
3762 Method isShuttingDown()
3765 \begin_layout Standard
3766 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3767 via VM exit, CTRL+C or explicitly.
3768 Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3771 \begin_layout Subsubsection
3772 Method shutdownEmulator()
3775 \begin_layout Standard
3776 Shut down and exit the emulator.
3777 All plugin shutdown functions are called in this thread.
3780 \begin_layout Subsubsection
3781 Method reconnectPC(PC)
3784 \begin_layout Standard
3785 Signal reconnectPC event to all plugins.
3788 \begin_layout Subsubsection
3792 \begin_layout Standard
3793 Signal pcStarting() event to all plugins.
3796 \begin_layout Subsubsection
3800 \begin_layout Standard
3801 Signal pcStopping() event to all plugins.
3804 \begin_layout Section
3805 Inter-plugin communication
3808 \begin_layout Subsection
3809 Receiving communications
3812 \begin_layout Standard
3813 To receive invocation/call by name 'foo-bar', declare public method named
3815 Arguments to this method can currently be String, Integer (int) or Long
3817 Last argument may be array over these types to get variable number of arguments.
3818 On call, each argument gets value from call.
3819 If last argument is array, it gets all overflowing arguments.
3820 If return type is void or method returns boolean false, call is assumed
3822 If return value is boolean true, it is assumed that there is more processing.
3825 \begin_layout Subsection
3826 void org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd, Object[]
3830 \begin_layout Standard
3831 Invoke command asynchronously, broadcasting to all plugins.
3832 Does not wait for slow commands to complete.
3833 cmd is the name to send and args are the arguments to pass.
3836 \begin_layout Subsection
3837 void org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String cmd,
3841 \begin_layout Standard
3842 Same as invokeExternalCommand, but waits for slow commands to complete.
3845 \begin_layout Subsection
3846 Object[] org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String cmd,
3850 \begin_layout Standard
3851 Similar to invokeExternalCommandSynchornous, but:
3854 \begin_layout Itemize
3855 Quits calling more plugins when it gets successful reply.
3858 \begin_layout Itemize
3862 \begin_layout Subsection
3863 void org.jpc.pluginsbase.Plugins.returnValue(Object...
3867 \begin_layout Standard
3868 Gives return value to return from call and signals that command has completed.
3871 \begin_layout Subsection
3872 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
3875 \begin_layout Standard
3876 Signals that command has completed.
3877 Only needed if there is no return value and eci_ method returned false
3881 \begin_layout Section
3882 Lua kernel programming
3885 \begin_layout Standard
3886 At startup, kernel gets its arguments in 'args' table and the script name
3887 to run in 'scriptname' string.
3888 It should enter the named script in protected mode.
3891 \begin_layout Standard
3892 The Lua VM exports numerious callbacks to kernel.
3893 The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3896 \begin_layout Itemize
3897 Always grab any functions used into local variables so nobody can mess with
3901 \begin_layout Itemize
3902 Don't use global variables in kernel (except for those passed).