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 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 -library <library> Use the specified directory when searching for images
811 (can only be specified once).
814 \begin_layout LyX-Code
815 -autoexec <script> Execute contents of specified file as commands when starting
819 \begin_layout LyX-Code
820 -norenames Copy&Delete files instead of renaming.
821 Mainly meant for debugging copy&delte code.
824 \begin_layout Standard
825 If no arguments are given, defaults of library 'disklibrary' and autoexec
826 file of 'assemble.jpcrrinit' are used.
829 \begin_layout Subsection
833 \begin_layout Standard
834 When emulator is started, command line comes up.
835 Following commands are known:
838 \begin_layout Itemize
839 'exit': exit immediately
842 \begin_layout Itemize
843 'load <plugin>': Load plugin (no arguments)
846 \begin_layout Itemize
847 'load <plugin>(<arguments>)': load plugin with arguments.
850 \begin_layout Itemize
851 'command <command> [<arguments>...]': Invoke command via external command interface.
854 \begin_layout Itemize
855 'call<command> [<arguments>...]': Invoke command via external command interface
856 and print return values.
859 \begin_layout Standard
860 When one gets command line, its useful to load some plugins.
861 See section about plugins.
862 Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
863 like to start PC immediately.
866 \begin_layout Subsection
867 PC settings dialog notes
870 \begin_layout Itemize
871 CPU divider base frequency before division is 1GHz.
874 \begin_layout Itemize
875 Images can be specified by name or by ID.
876 Name is relative to library directory.
877 If the image is in subdirectory of image directory, the directory separator
878 is is '/' regardless of what the host OS uses.
881 \begin_layout Itemize
882 CD-ROM and hdc are mutually exclusive
885 \begin_layout Itemize
886 Modules is comma-seperated list of modules to load.
887 To pass arguments to some modules, enclose the arguments in ().
888 Same module can be specified twice only if parameters differ.
891 \begin_layout Itemize
892 Setting boot device doesn't work with some BIOS versions.
893 Those versions prompt the boot device anyway.
896 \begin_layout Subsection
897 Audio output channels
900 \begin_layout Standard
901 PC can have one or more audio output channels.
902 The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
904 Modules that have audio outputs get channel names of form <classname>-<sequenti
905 al>, where <classname> is name of main module class and sequential is number
907 Note that same module can have multiple output channels.
908 If multiple modules of same class request audio outputs, the <sequential>
909 values of subsequent module start where previous left off.
912 \begin_layout Subsection
916 \begin_layout Standard
917 Plugins actually execute the tasks of the emulator.
918 They can be loaded using
919 \begin_inset Quotes eld
923 \begin_inset Quotes erd
926 or 'load <plugin>(<arguments>)
927 \begin_inset Quotes erd
933 \begin_layout Standard
934 Different Plugins using the same output (like running PCMonitor and RAWVideoDump
935 er) should not conflict because connector output hold locking is desinged
936 to handle multiple readers.
939 \begin_layout Standard
940 If no plugin used requires GUI, then the emulator can be run without having
944 \begin_layout Subsubsection
945 plugin: org.jpc.plugins.PCControl
948 \begin_layout Standard
949 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1', requires and
953 \begin_layout Standard
954 Runs the PC emulator core.
955 Has capability to start/stop emulation, breakpoint after certain time or
956 start/end of VGA vertical retrace.
957 Also can create, savestate and loadstate PC emulation.
958 Memory dumping is supported.
962 \begin_layout Standard
963 'extramenu=<file>' causes Plugin to load extra menu entries from <file>.
964 'uncompressedsave=1' causes savestates to be written uncompressed (useful
965 if they are stored in VCS supporting delta compression).
968 \begin_layout Subsubsection
969 plugin: org.jpc.plugins.PCRunner
972 \begin_layout Standard
973 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
977 \begin_layout Standard
978 Loads PC from savestate and just runs it.
980 Also automatically quits once stoptime is reached.
983 \begin_layout Subsubsection
984 plugin: org.jpc.plugins.PCMonitor
987 \begin_layout Standard
988 No arguments, requires and uses GUI.
991 \begin_layout Standard
992 VGA monitor for emulated PC.
995 \begin_layout Subsubsection
996 plugin: org.jpc.plugins.VirtualKeyboard
999 \begin_layout Standard
1000 No arguments, requires and uses GUI.
1003 \begin_layout Standard
1004 On-screen keyboard for emulated PC.
1007 \begin_layout Subsubsection
1008 plugin: org.jpc.plugins.PCStartStopTest
1011 \begin_layout Standard
1012 No arguments, requires and uses GUI.
1015 \begin_layout Standard
1016 Small plugin testing remote PC start/stop.
1017 Also supports sending some common keypresses.
1020 \begin_layout Subsubsection
1021 plugin: org.jpc.plugins.RAWVideoDumper
1024 \begin_layout Standard
1025 Takes 'rawoutput=<file>' as argument.
1026 Does not require nor use GUI.
1029 \begin_layout Standard
1030 Dumps all generated frames to RAW file <file>.
1031 Rawoutput is required.
1032 The raw file consists of concatenation of zlib streams.
1033 The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1034 each acting as time offset of 2^32-1 nanoseconds and saved frames.
1035 The saved frame has time offset in nanoseconds (big endian) as first four
1036 bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1037 The next two bytes are big-endian width, next two big-endian height.
1038 Finally frame has 4 * width * height bytes of data that encodes pixels
1039 using 4 bytes per pixel, in left-to-right, up-to-down order.
1040 Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1041 green channel and byte 3 is blue channel.
1044 \begin_layout Standard
1045 Dumping to pipe is supported.
1048 \begin_layout Subsubsection
1049 plugin: org.jpc.plugins.RAWAudioDumper
1052 \begin_layout Standard
1053 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1054 'offset=<offset>' as arguments, separated by ','.
1055 Does not require nor use GUI.
1058 \begin_layout Standard
1059 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1060 file (file, mandatory).
1061 The resulting file consists of records, 4 or 8 bytes each.
1062 4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1064 \begin_inset Formula $2^{32}-1$
1068 Otherwise record is 8 bytes.
1069 Each 8 byte record has three fields.
1070 First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1072 \begin_inset Formula $2^{32}-1$
1075 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1076 big endian new right channel volume.
1077 Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1081 \begin_layout Subsubsection
1082 plugin: org.jpc.plugins.LuaPlugin
1085 \begin_layout Standard
1086 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1087 kernel, requires and uses GUI.
1090 \begin_layout Standard
1091 Lua VM for executing scripts.
1094 \begin_layout Subsubsection
1095 plugin: org.jpc.plugins.JoystickInput
1098 \begin_layout Standard
1100 Displays window for sending joystick input.
1103 \begin_layout Section
1107 \begin_layout Subsection
1108 org.jpc.modules.Joystick:
1111 \begin_layout Itemize
1115 \begin_layout Itemize
1116 Resources: I/O port 0x201
1119 \begin_layout Standard
1120 Emulates joystick game port.
1123 \begin_layout Subsection
1124 org.jpc.modules.SoundCard
1127 \begin_layout Itemize
1128 Arguments: Optional resources specification
1131 \begin_layout Itemize
1132 Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
1135 \begin_layout Standard
1136 Emulates Sound card.
1139 \begin_layout Subsection
1140 org.jpc.modules.FMCard
1143 \begin_layout Itemize
1144 Arguments: Optional resources specification
1147 \begin_layout Itemize
1148 Resources (defaults): I/O port 0x338-0x33B
1151 \begin_layout Standard
1155 \begin_layout Subsection
1156 org.jpc.modules.BasicFPU:
1159 \begin_layout Itemize
1163 \begin_layout Itemize
1167 \begin_layout Standard
1168 Crude FPU (x87) emulator.
1171 \begin_layout Section
1175 \begin_layout Standard
1176 Hacks are saved to savestates but not movies.
1179 \begin_layout Subsection
1183 \begin_layout Standard
1184 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1186 BIOS assumes system has FPU but some games use that bit to detect FPU,
1187 trying to use it if it is
1188 \begin_inset Quotes eld
1192 \begin_inset Quotes erd
1196 Try this if game startup hangs with lots of trying to use FPU but not present
1198 Don't use if there is FPU present.
1199 Needed to get games like Blake Stone / Wolfenstein 3-D to work (FPU emulator
1200 allows it to start but causes graphical glitches).
1203 \begin_layout Subsection
1207 \begin_layout Standard
1208 Update basic VGA parameters before vretrace, not after it.
1210 Commander Keen 4) don't like if this isn't done and some games (e.g.
1211 Mario & Luigi) don't like if it is done.
1212 Wrong value manifests as jerky scrolling (scrolling back and forth and
1213 fixed statusbars move).
1216 \begin_layout Section
1217 Some error messages and explanations
1220 \begin_layout Itemize
1221 <filename> is Not a valid image file
1224 \begin_layout Itemize
1225 <filename> is not image file
1228 \begin_layout Itemize
1229 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1233 \begin_layout Itemize
1234 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1238 \begin_layout Itemize
1239 Can't read disk image sector map.
1242 \begin_layout Itemize
1243 Can't read disk image extent.
1246 \begin_layout Standard
1247 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1248 image at all or its corrupt.
1251 \begin_layout Itemize
1252 <filename> is image of unknown type.
1255 \begin_layout Itemize
1256 <filename> has unrecognized geometry <x> <y> <z>
1259 \begin_layout Standard
1260 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1261 containing something current version can't comprehend.
1264 \begin_layout Itemize
1265 Invalid format specifier <something>.
1268 \begin_layout Itemize
1269 Invalid syntax of --floppy= or --HDD= option.
1272 \begin_layout Itemize
1273 Invalid format specifier/option <something>.
1276 \begin_layout Standard
1277 Invalid option or format specifier was given.
1281 \begin_layout Itemize
1282 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1285 \begin_layout Standard
1286 Check syntax of command.
1287 Especially that diskname is present!
1290 \begin_layout Itemize
1291 The image has <nnn> sectors while it should have <yyy> according to selected
1295 \begin_layout Itemize
1296 Raw image file length not divisible by 512.
1299 \begin_layout Itemize
1300 Trying to read sector out of range.
1303 \begin_layout Standard
1304 The selected geometry is wrong or raw image is incomplete.
1307 \begin_layout Itemize
1308 Invalid disk name (Should not happen!).
1311 \begin_layout Itemize
1312 Invalid geometry to be written.
1315 \begin_layout Standard
1316 This is a very likely a bug in program.
1319 \begin_layout Itemize
1320 What the heck <filename> is? It's not regular file nor directory.
1323 \begin_layout Standard
1324 That sort of file can't be used as input for image making, or the file just
1328 \begin_layout Itemize
1329 BIOS images can only be made out of regular files.
1332 \begin_layout Itemize
1333 CD images can only be made out of regular files.
1336 \begin_layout Standard
1337 Source image specified is not regular file, but image of that type can't
1338 be made of anything else.
1341 \begin_layout Itemize
1342 Can't read raw bios image file.
1345 \begin_layout Itemize
1346 Can't read sector <nnn> from image.
1349 \begin_layout Standard
1350 Reading the raw image file failed for some reason.
1353 \begin_layout Itemize
1354 Bad library line: "<something>".
1358 \begin_layout Standard
1359 Syntax error in image library.
1362 \begin_layout Itemize
1363 Removing image <something> a.k.a.
1364 "<something>" as it no longer exists.
1367 \begin_layout Standard
1368 The image file no longer exists so it gets removed from library.
1371 \begin_layout Itemize
1372 Removing image <something> a.k.a.
1373 "<something>" due to <some> conflict.
1376 \begin_layout Standard
1377 Image library code killed some image from library due to some kind of conflict
1378 with image being added.
1381 \begin_layout Itemize
1382 Too much data to fit into given space.
1385 \begin_layout Standard
1386 The tree you gave contains takes just too much space to fit into disk of
1390 \begin_layout Section
1391 Advanced: Savestate/movie format
1394 \begin_layout Subsection
1395 Special character classes
1398 \begin_layout Subsubsection
1402 \begin_layout Standard
1403 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1407 \begin_layout Itemize
1408 Codepoints 0x20, and 0x09.
1411 \begin_layout Itemize
1412 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1415 \begin_layout Itemize
1416 Codepoints 0x2000-0x200A.
1419 \begin_layout Subsubsection
1423 \begin_layout Standard
1424 Following byte sequences are interpretted as linefeeds (line change):
1427 \begin_layout Itemize
1428 Byte 0x0A (UTF-8 encoded codepoint 0x0A)
1431 \begin_layout Itemize
1432 Byte 0x0D (UTF-8 encoded codepoint 0x0D)
1435 \begin_layout Itemize
1436 Byte 0x1C (UTF-8 encoded codepoint 0x1C)
1439 \begin_layout Itemize
1440 Byte 0x1D (UTF-8 encoded codepoint 0x1D)
1443 \begin_layout Itemize
1444 Byte 0x1E (UTF-8 encoded codepoint 0x1E)
1447 \begin_layout Itemize
1448 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL, codepoint 0x85)
1451 \begin_layout Itemize
1452 Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
1455 \begin_layout Subsection
1459 \begin_layout Standard
1460 JRSR archive format packs multiple text archive members to text archive.
1461 It does not support binary members.
1462 JRSR archives have first five or six bytes form the magic.
1464 \begin_inset Quotes eld
1468 \begin_inset Quotes erd
1471 followed by LINEFEED character There are four kinds of lines after that
1472 (lines are terminated by LINEFEED byte/bytes):
1475 \begin_layout Itemize
1479 \begin_layout Itemize
1483 \begin_layout Itemize
1487 \begin_layout Itemize
1491 \begin_layout Standard
1492 Sequencing rules are as follows: Start member is allowed anywhere (after
1494 Member line is allowed only inside member (member started but not ended).
1495 End member is only allowed inside member.
1496 End of file is only allowed outside member.
1497 Blank line is allowed anywhere after magic.
1500 \begin_layout Subsubsection
1504 \begin_layout Standard
1505 Start member line is given as
1506 \begin_inset Quotes eld
1510 \begin_inset Quotes erd
1513 <SPACE>+ <membername> <LINEFEED>.
1514 <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1516 The member name is UTF-8 encoded and maximum allowed line length is 2048
1517 bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1518 depending on characters used).
1519 Starting member inside another implicitly ends the previous member.
1522 \begin_layout Subsubsection
1526 \begin_layout Standard
1527 Member line is given as
1528 \begin_inset Quotes eld
1532 \begin_inset Quotes erd
1535 <content><LINEFEED>.
1536 It gives another line for member contents.
1537 <content> is passed raw to layers above (followed by line termination)
1540 \begin_layout Subsubsection
1544 \begin_layout Standard
1545 End member line is given as
1546 \begin_inset Quotes eld
1550 \begin_inset Quotes erd
1554 It ends the current member.
1555 The following line can only be start member line or file may end.
1558 \begin_layout Subsubsection
1562 \begin_layout Standard
1563 Blank line is given as <LINEFEED>.
1564 Lines like that are ignored.
1567 \begin_layout Subsection
1568 Four-to-Five encoding
1571 \begin_layout Standard
1572 Binary members are encoded into text by so-called four-to-five encoding.
1573 This encoding can encode single byte to two, two bytes to three, three
1574 bytes to four and four bytes to five.
1575 Four-to-five encoding has five kinds of blocks.
1576 All SPACE and LINEFEED characters are completely ignored, even in middle
1580 \begin_layout Subsubsection
1584 \begin_layout Standard
1585 End stream block is encoded as '!'.
1586 It ends the stream instantly.
1587 There is also implicit end of stream at end of input to decoding.
1590 \begin_layout Subsubsection
1591 Other four block types
1594 \begin_layout Standard
1595 Other four block types take the value to be encoded, read it as big-endian
1597 Then they write it as base-93 big-endian value.
1598 Then length specific constants are added to digits of that number to yield
1599 ASCII values for characters (those are stored in order):
1602 \begin_layout Standard
1603 \begin_inset Tabular
1604 <lyxtabular version="3" rows="5" columns="6">
1606 <column alignment="center" valignment="top" width="0">
1607 <column alignment="center" valignment="top" width="0">
1608 <column alignment="center" valignment="top" width="0">
1609 <column alignment="center" valignment="top" width="0">
1610 <column alignment="center" valignment="top" width="0">
1611 <column alignment="center" valignment="top" width="0">
1613 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1616 \begin_layout Plain Layout
1622 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1625 \begin_layout Plain Layout
1631 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1634 \begin_layout Plain Layout
1640 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1643 \begin_layout Plain Layout
1649 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1652 \begin_layout Plain Layout
1658 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1661 \begin_layout Plain Layout
1669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1672 \begin_layout Plain Layout
1678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1681 \begin_layout Plain Layout
1687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1690 \begin_layout Plain Layout
1696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1699 \begin_layout Plain Layout
1705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1708 \begin_layout Plain Layout
1714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1717 \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" usebox="none">
1737 \begin_layout Plain Layout
1743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1746 \begin_layout Plain Layout
1752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1755 \begin_layout Plain Layout
1761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1764 \begin_layout Plain Layout
1770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1773 \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" usebox="none">
1793 \begin_layout Plain Layout
1799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1802 \begin_layout Plain Layout
1808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1811 \begin_layout Plain Layout
1817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1820 \begin_layout Plain Layout
1826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1829 \begin_layout Plain Layout
1837 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1840 \begin_layout Plain Layout
1846 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1849 \begin_layout Plain Layout
1855 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1858 \begin_layout Plain Layout
1864 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1867 \begin_layout Plain Layout
1873 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1876 \begin_layout Plain Layout
1882 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1885 \begin_layout Plain Layout
1899 \begin_layout Standard
1900 Blocks which encode values greater than what is possible for value of that
1901 length are fatal errors.
1905 \begin_layout Subsection
1906 Line component encoing
1909 \begin_layout Standard
1910 Line component encoding sits on top of UTF-8 encoding.
1911 Line component encoding encodes non-empty 1-D array of non-empty strings
1912 into line, and thus array of those into member.
1913 Empty lines or lines that don't contain any components are ignored.
1914 Line starts with depth value of 0 and must end with depth value of zero.
1917 \begin_layout Standard
1918 Components are seperated by component separators.
1919 Empty components are ignored.
1920 Following codepoints are separators on depth 0 if not escaped:
1923 \begin_layout Itemize
1925 The depth is read pre-increment.
1928 \begin_layout Itemize
1930 The depth is read post-decrement.
1933 \begin_layout Itemize
1937 \begin_layout Standard
1938 The following characters are special:
1941 \begin_layout Itemize
1943 Increments depth by 1 if not escaped (and appears in component).
1946 \begin_layout Itemize
1948 Decrements depth by 1 if not escaped (and appears in component).
1949 Depth going negative is an error.
1952 \begin_layout Itemize
1956 Next character is interpretted as literal.
1957 Error if at end of line.
1960 \begin_layout Standard
1961 Otherwise, characters are interpretted as literals and appear in components.
1962 Depth must be zero at end of line.
1965 \begin_layout Subsection
1969 \begin_layout Standard
1970 Header section is in archive member "header".
1971 It uses line component encoding.
1972 The first component of each line is name of header, and subsequent ones
1974 How many parameters are expected is dependent on what header it is:
1977 \begin_layout Subsubsection
1981 \begin_layout Itemize
1982 Header name: "PROJECTID"
1985 \begin_layout Itemize
1989 \begin_layout Itemize
1990 Argument #1: <project-id-string>
1993 \begin_layout Itemize
1997 \begin_layout Standard
1999 Project ID is generated when PC is assembled and is then preserved in save
2001 It is used for computing rerecord counts.
2002 Emulator treats it as opaque string, the IDs it generates are formed by
2003 48 random hexadecimal digits.
2006 \begin_layout Subsubsection
2010 \begin_layout Itemize
2011 Header name: "SAVESTATEID"
2014 \begin_layout Itemize
2018 \begin_layout Itemize
2019 Argument #1: <savestate-id-string>
2022 \begin_layout Itemize
2026 \begin_layout Standard
2027 Gives save state ID.
2028 Each save state has its own save state ID.
2029 Treated as opaque string, but generated as 48 random hexadecimal digits.
2030 The presence of this header signals whether there is save state to be loaded.
2031 If this header is present, save state load will be attempted.
2032 If absent, save state is not to be loaded even if present (and correct
2033 savestate load would be technically impossible anyway).
2036 \begin_layout Standard
2037 The value is used to prevent loading incompatible save states in preserve
2038 event stream mode and also to find the point in event stream where one
2042 \begin_layout Subsubsection
2046 \begin_layout Itemize
2047 Header name: "RERECORDS"
2050 \begin_layout Itemize
2054 \begin_layout Itemize
2055 Argument #1: <rerecords>
2058 \begin_layout Itemize
2062 \begin_layout Standard
2063 Gives rerecord count.
2064 PC assembly (except when loading save state) initializes current rerecord
2066 Must be non-negative and decimal number using ASCII digit characters.
2069 \begin_layout LyX-Code
2070 On loading save state:
2073 \begin_layout LyX-Code
2074 1) If project ID matches with previous:
2077 \begin_layout LyX-Code
2078 1a) If loaded rerecord count is larger or equal to current rerecord count:
2081 \begin_layout LyX-Code
2082 1a-a) Current rerecord count is loaded rerecord count + 1.
2085 \begin_layout LyX-Code
2089 \begin_layout LyX-Code
2090 1b-a) Current rerecord count increments by 1.
2093 \begin_layout LyX-Code
2097 \begin_layout LyX-Code
2098 2a) Current rerecord count is loaded rerecord count + 1.
2101 \begin_layout Standard
2102 The current rerecord count at time of save is saved to save state.
2105 \begin_layout Subsubsection
2109 \begin_layout Itemize
2110 Header name: "AUTHORS"
2113 \begin_layout Itemize
2114 Components: 2 or more
2117 \begin_layout Itemize
2118 Arguments: free form
2121 \begin_layout Itemize
2125 \begin_layout Standard
2126 Gives authors of run.
2127 Each argument gives one author.
2128 May be present multiple times.
2131 \begin_layout Subsubsection
2135 \begin_layout Itemize
2136 Header name: "COMMENT"
2139 \begin_layout Itemize
2140 Components: 2 or more
2143 \begin_layout Itemize
2144 Arguments: free form
2147 \begin_layout Itemize
2151 \begin_layout Standard
2152 Various kinds of free form data.
2153 Not parsed further by emulator.
2156 \begin_layout Subsection
2157 Initialization segment:
2160 \begin_layout Standard
2161 If SAVESTATEID header isn't present (not a save state), member "initialization"
2162 gives PC initialization parameters for assembling the PC.
2163 It is present anyway even if SAVESTATEID is present (savestate).
2166 \begin_layout Standard
2167 Following parameters are used (space separates components):
2170 \begin_layout LyX-Code
2174 \begin_layout Standard
2175 Gives Image ID of main system BIOS (mandatory)
2178 \begin_layout LyX-Code
2182 \begin_layout Standard
2183 Gives Image ID of VGA BIOS (mandatory).
2186 \begin_layout LyX-Code
2190 \begin_layout Standard
2191 Gives Image ID of hda.
2192 Present only if system has hard disk hda.
2195 \begin_layout LyX-Code
2199 \begin_layout Standard
2200 Gives Image ID of hdb.
2201 Present only if system has hard disk hdb.
2204 \begin_layout LyX-Code
2208 \begin_layout Standard
2209 Gives Image ID of hdc.
2210 Present only if system has hard disk hdc.
2213 \begin_layout LyX-Code
2217 \begin_layout Standard
2218 Gives Image ID of hdd.
2219 Present only if system has hard disk hdd.
2222 \begin_layout LyX-Code
2226 \begin_layout Standard
2227 Gives Image ID of disk in slot <num>.
2228 Slot number must be non-negative.
2231 \begin_layout LyX-Code
2232 \begin_inset Quotes eld
2236 \begin_inset Quotes erd
2242 \begin_layout Standard
2243 kGives image name of disk in slot <num>.
2244 Slot number must be non-negative.
2245 The slot must be previously declared using
2246 \begin_inset Quotes eld
2250 \begin_inset Quotes erd
2256 \begin_layout LyX-Code
2260 \begin_layout Standard
2261 Gives Image slot to initially put into floppy drive fda.
2262 Disk must be of floppy type.
2263 If none present, no disk is initially put there.
2266 \begin_layout LyX-Code
2270 \begin_layout Standard
2271 Gives Image slot to initially put into floppy drive fdb.
2272 Disk must be of floppy type.
2273 If none present, no disk is initially put there.
2276 \begin_layout LyX-Code
2280 \begin_layout Standard
2281 Gives Image slot to initially put into CD-ROM drive hdc.
2282 Not allowed if hard disk hdc is present.
2283 Disk must be of CD-ROM type.
2284 If none present no disk is initially put there.
2287 \begin_layout LyX-Code
2288 "INITIALTIME" <time>
2291 \begin_layout Standard
2292 Number of milliseconds since Unix epoch to system start up time.
2296 \begin_layout Standard
2301 \begin_layout LyX-Code
2302 "CPUDIVIDER" <divider>
2305 \begin_layout Standard
2306 Set CPU frequency divider (dividing the 1GHz master clock).
2307 Allowed range is 1-256.
2311 \begin_layout LyX-Code
2312 "MEMORYSIZE" <pages>
2315 \begin_layout Standard
2316 Number of 4KiB pages of RAM memory.
2317 Allowed range 256-262144.
2321 \begin_layout LyX-Code
2325 \begin_layout Standard
2327 Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2331 \begin_layout LyX-Code
2332 "LOADMODULEA" <module> <parameters>
2335 \begin_layout Standard
2336 Load module <module> with parameters <parameters>.
2339 \begin_layout LyX-Code
2340 "LOADMODULE" <module>
2343 \begin_layout Standard
2344 Load module <module> with no parameters
2347 \begin_layout LyX-Code
2348 \begin_inset Quotes eld
2352 \begin_inset Quotes erd
2358 \begin_layout Standard
2359 Use class <fpu> as FPU emulator.
2362 \begin_layout LyX-Code
2363 \begin_inset Quotes eld
2367 \begin_inset Quotes erd
2373 \begin_layout Standard
2374 Use I/O port delay emulation (each I/O port read/write takes 666ns).
2377 \begin_layout LyX-Code
2378 \begin_inset Quotes eld
2382 \begin_inset Quotes erd
2388 \begin_layout Standard
2389 Emulate VGA horizontal retrace.
2392 \begin_layout Subsection
2393 Event record format:
2396 \begin_layout Standard
2397 Event record is in archive member "events".
2398 It uses line component encoding.
2399 Each line gives an event.
2400 First component of each line gives time stamp.
2401 These timestamps MUST be in increasing order and all MUST be non-negative.
2402 Time stamp time unit is exactly 1 nanosecond of emulated time.
2405 \begin_layout Standard
2406 The second component of each line is name of class to dispatch to.
2407 Further components are passed as-is to event handlers.
2408 Classes with names consisting only of uppercase A-Z and 0-9 are special
2410 It is error to encounter unknown such special class.
2413 \begin_layout Subsubsection
2417 \begin_layout Itemize
2418 Dispatch to: SAVESTATE
2421 \begin_layout Itemize
2422 Argument #1: Savestate id
2425 \begin_layout Itemize
2426 Argument #2 (optional): Rerecord count at time of saving savestate
2429 \begin_layout Standard
2430 Signals that savestate has occured here.
2431 The save state IDs MUST be unique in entire event stream.
2432 The second argument to savestate (if present) is rerecord count at time
2433 of saving that savestate (useful for calulating rerecord count of movie
2434 starting from savestate).
2435 No time restrictions
2438 \begin_layout Subsubsection
2442 \begin_layout Itemize
2446 \begin_layout Itemize
2448 \begin_inset Quotes eld
2452 \begin_inset Quotes erd
2456 \begin_inset Quotes eld
2460 \begin_inset Quotes erd
2466 \begin_layout Standard
2467 Controls various options.
2469 \begin_inset Quotes eld
2473 \begin_inset Quotes erd
2476 turns on absolute mode (default) where event timestamps are absolute.
2478 \begin_inset Quotes eld
2482 \begin_inset Quotes erd
2485 turns on relative mode where event timestamps are relative to last event
2487 The OPTION event itself is not affected by timing change.
2488 No time restrictions.
2489 Unknown arguments are errors.
2492 \begin_layout Subsubsection
2493 Keyboard keypress/keyrelease event:
2496 \begin_layout Itemize
2497 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2500 \begin_layout Itemize
2501 Argument #1: Fixed: "KEYEDGE"
2504 \begin_layout Itemize
2505 Argument #2: Key number.
2506 Valid values are 1-83, 85-95, 129-197 and 199-223
2509 \begin_layout Standard
2510 Send key press or key release.
2511 Keys work in toggle button manner.
2512 The event time must be multiple of 66 666, and must not be less than 60
2513 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2514 on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2517 \begin_layout Subsubsection
2521 \begin_layout Itemize
2522 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2525 \begin_layout Itemize
2526 Argument #1: Fixed: "PAUSE"
2529 \begin_layout Standard
2530 Send pause key event.
2531 The time restrictions are identical to KEYEDGE event.
2534 \begin_layout Subsubsection
2538 \begin_layout Itemize
2539 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2542 \begin_layout Itemize
2543 Argument #1: Fixed: "MOUSEBUTTON"
2546 \begin_layout Itemize
2547 Argument #2: Number of button to release or press (0-4)
2550 \begin_layout Standard
2551 Presses or releases the designated mouse button.
2554 \begin_layout Subsubsection
2555 X mouse motion event:
2558 \begin_layout Itemize
2559 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2562 \begin_layout Itemize
2563 Argument #1: Fixed: "XMOUSEMOTION"
2566 \begin_layout Itemize
2567 Argument #2: Number of units to move (-255 - 255)
2570 \begin_layout Standard
2571 Move the mouse in X direction by specified amount.
2575 \begin_layout Subsubsection
2576 Y mouse motion event:
2579 \begin_layout Itemize
2580 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2583 \begin_layout Itemize
2584 Argument #1: Fixed: "YMOUSEMOTION"
2587 \begin_layout Itemize
2588 Argument #2: Number of units to move (-255 - 255)
2591 \begin_layout Standard
2592 Move the mouse in Y direction by specified amount.
2596 \begin_layout Subsubsection
2597 Z mouse motion event:
2600 \begin_layout Itemize
2601 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2604 \begin_layout Itemize
2605 Argument #1: Fixed: "ZMOUSEMOTION"
2608 \begin_layout Itemize
2609 Argument #2: Number of units to move (-7 - 7)
2612 \begin_layout Standard
2613 Move the mouse in Z direction (scrollwheel) by specified amount.
2616 \begin_layout Subsubsection
2617 Joystick button event:
2620 \begin_layout Itemize
2621 Dispatch to: org.jpc.modules.Joystick
2624 \begin_layout Itemize
2626 \begin_inset Quotes eld
2630 \begin_inset Quotes erd
2634 \begin_inset Quotes eld
2638 \begin_inset Quotes erd
2642 \begin_inset Quotes eld
2646 \begin_inset Quotes erd
2650 \begin_inset Quotes eld
2654 \begin_inset Quotes erd
2660 \begin_layout Itemize
2662 \begin_inset Quotes eld
2666 \begin_inset Quotes erd
2670 \begin_inset Quotes eld
2674 \begin_inset Quotes erd
2680 \begin_layout Standard
2681 Send button down/up event.
2682 No time restrictions.
2685 \begin_layout Subsubsection
2686 Joystick axis event:
2689 \begin_layout Itemize
2690 Dispatch to: org.jpc.modules.Joystick
2693 \begin_layout Itemize
2695 \begin_inset Quotes eld
2699 \begin_inset Quotes erd
2703 \begin_inset Quotes eld
2707 \begin_inset Quotes erd
2711 \begin_inset Quotes eld
2715 \begin_inset Quotes erd
2719 \begin_inset Quotes eld
2723 \begin_inset Quotes erd
2729 \begin_layout Itemize
2730 Argument #2: Multivibrator unstable state length in ns.
2733 \begin_layout Standard
2734 Set amount of time multivibrator remains in unstable state.
2735 No time restrictions.
2738 \begin_layout Subsubsection
2742 \begin_layout Itemize
2743 Dispatch to: org.jpc.emulator.PC$ResetButton
2746 \begin_layout Itemize
2750 \begin_layout Standard
2754 \begin_layout Subsubsection
2758 \begin_layout Itemize
2759 Dispatch to: org.jpc.emulator.PC$DiskChanger
2762 \begin_layout Itemize
2763 Argument #1: Fixed: "FDA"
2766 \begin_layout Itemize
2767 Argument #2: Number of image slot to put there.
2771 \begin_layout Standard
2772 The disk number MUST be -1 or valid disk number.
2773 -1 MUST NOT be used if there is no disk in floppy drive A.
2774 This event causes specified disk to be placed to FDA or FDA disk to be
2775 ejected with no replacement if disk number is -1.
2776 The specified disk if not -1 must be of floppy type.
2777 The specified disk if valid must not be in any other drive.
2780 \begin_layout Subsubsection
2784 \begin_layout Itemize
2785 Dispatch to: org.jpc.emulator.PC$DiskChanger
2788 \begin_layout Itemize
2789 Argument #1: Fixed: "FDB"
2792 \begin_layout Itemize
2793 Argument #2: Number of image slot to put there.
2797 \begin_layout Standard
2798 The disk number MUST be -1 or valid disk number.
2799 -1 MUST NOT be used if there is no disk in floppy drive B.
2800 This event causes specified disk to be placed to FDB or FDB disk to be
2801 ejected with no replacement if disk number is -1.
2802 The specified disk if not -1 must be of floppy type.
2803 The specified disk if valid must not be in any other drive.
2806 \begin_layout Subsubsection
2810 \begin_layout Itemize
2811 Dispatch to: org.jpc.emulator.PC$DiskChanger
2814 \begin_layout Itemize
2815 Argument #1: Fixed: "CDROM"
2818 \begin_layout Itemize
2819 Argument #2: Number of image slot to put there.
2823 \begin_layout Standard
2824 The disk number MUST be -1 or valid disk number.
2825 -1 MUST NOT be used if there is no disk in CD-ROM.
2826 This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2827 to be ejected with no replacement if disk number is -1.
2828 The specified disk if not -1 must be of CD-ROM type.
2831 \begin_layout Standard
2832 This event has no effect if CD-ROM is locked.
2835 \begin_layout Subsubsection
2836 Write protect floppy:
2839 \begin_layout Itemize
2840 Dispatch to: org.jpc.emulator.PC$DiskChanger
2843 \begin_layout Itemize
2844 Argument #1: Fixed: "WRITEPROTECT"
2847 \begin_layout Itemize
2848 Argument #2: Number of image slot to manipulate
2851 \begin_layout Standard
2852 Write protects specified disk.
2853 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2856 \begin_layout Subsubsection
2857 Write unprotect floppy:
2860 \begin_layout Itemize
2861 Dispatch to: org.jpc.emulator.PC$DiskChanger
2864 \begin_layout Itemize
2865 Argument #1: Fixed: "WRITEUNPROTECT"
2868 \begin_layout Itemize
2869 Argument #2: Number of image slot to manipulate
2872 \begin_layout Standard
2873 Disables write protection specified disk.
2874 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2877 \begin_layout Subsection
2881 \begin_layout Standard
2882 Diskinfo sections are named
2883 \begin_inset Quotes eld
2887 \begin_inset Quotes erd
2891 They use line component encoding, fieldtype being first component on each
2892 line (value being the second).
2893 Following fields are defined:
2896 \begin_layout Subsubsection
2900 \begin_layout Standard
2901 Gives type of image.
2905 \begin_layout Itemize
2906 \begin_inset Quotes eld
2910 \begin_inset Quotes erd
2916 \begin_layout Itemize
2917 \begin_inset Quotes eld
2921 \begin_inset Quotes erd
2927 \begin_layout Itemize
2928 \begin_inset Quotes eld
2932 \begin_inset Quotes erd
2938 \begin_layout Itemize
2939 \begin_inset Quotes eld
2943 \begin_inset Quotes erd
2946 (BIOS/VGABIOS image)
2949 \begin_layout Itemize
2950 \begin_inset Quotes eld
2954 \begin_inset Quotes erd
2957 (what the heck is this???)
2960 \begin_layout Subsubsection
2964 \begin_layout Standard
2968 \begin_layout Subsubsection
2972 \begin_layout Standard
2973 (BIOS images only) Gives length of BIOS image
2976 \begin_layout Subsubsection
2980 \begin_layout Standard
2981 MD5 of raw disk/BIOS image without any headers or trailers.
2984 \begin_layout Subsubsection
2988 \begin_layout Standard
2989 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
2992 \begin_layout Subsubsection
2996 \begin_layout Standard
2997 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
3001 \begin_layout Subsubsection
3005 \begin_layout Standard
3006 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
3010 \begin_layout Subsubsection
3014 \begin_layout Standard
3015 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
3019 \begin_layout Subsubsection
3023 \begin_layout Standard
3024 Line from image comment block.
3025 Usually give data about files image has.
3026 May or may not be present (multiple times)
3029 \begin_layout Subsection
3033 \begin_layout Standard
3034 Output info is stored in section
3035 \begin_inset Quotes eld
3039 \begin_inset Quotes erd
3043 Its relatively new, so it might not be present (then the contents have
3044 to be guessed based on modules present).
3045 Each line gives information about one output, first field being the type
3049 \begin_layout Subsubsection
3053 \begin_layout Standard
3054 For video output, there are no parameters so line is just
3055 \begin_inset Quotes eld
3059 \begin_inset Quotes erd
3065 \begin_layout Subsubsection
3069 \begin_layout Standard
3070 For audio output, the only parameter is name of output, so first component
3072 \begin_inset Quotes eld
3076 \begin_inset Quotes erd
3079 and second component is name of audio output.
3082 \begin_layout Subsection
3086 \begin_layout Standard
3087 Actual savestate format is not documented here.
3088 It is close to impossible to comprehend without access to emulator source
3092 \begin_layout Section
3093 Advanced: Making class dumpable
3096 \begin_layout Standard
3097 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
3098 and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
3099 <init>(org.jpc.emulator.SRLoader).
3100 Non-static inner classes can not be dumpable (make them static using tricks
3101 similar to what javac uses).
3104 \begin_layout Standard
3105 If dumped class has dumpable superclass, the first thing dumping function
3106 needs to do is to call dumper function of superclass and first thing loading
3107 constructor needs to do is to call loading constructor of superclass.
3108 If class has no dumpable superclass, dumper doesn't need to do anything
3109 special, while loader needs to call objectCreated(this) on SRLoader object
3110 passed as parameter.
3114 \begin_layout Standard
3115 Following these fixed parts, dump all members that are part of mutable state
3119 \begin_layout Subsection
3120 Member dumping/loading functions
3123 \begin_layout Standard
3124 There is dumping/loading function for following (all functions dumping/loading
3125 reference types can handle null):
3128 \begin_layout Itemize
3129 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
3132 \begin_layout Itemize
3133 byte: SRDumper.dumpByte, SRLoader.loadByte
3136 \begin_layout Itemize
3137 short: SRDumper.dumpShort, SRLoader.loadShort
3140 \begin_layout Itemize
3141 int: SRDumper.dumpInt, SRLoader.loadInt
3144 \begin_layout Itemize
3145 long: SRDumper.dumpLong, SRLoader.loadLong
3148 \begin_layout Itemize
3149 String: SRDumper.dumpString, SRLoader.loadString
3152 \begin_layout Itemize
3153 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
3156 \begin_layout Itemize
3157 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
3160 \begin_layout Itemize
3161 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
3164 \begin_layout Itemize
3165 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
3168 \begin_layout Itemize
3169 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
3172 \begin_layout Itemize
3173 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
3176 \begin_layout Itemize
3177 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
3180 \begin_layout Itemize
3181 special object: SRDumper.specialObject, SRLoader.specialObject
3184 \begin_layout Subsubsection
3188 \begin_layout Itemize
3189 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
3192 \begin_layout Itemize
3193 Special objects are various static objects that don't need to be stored
3194 because they don't have mutable fields.
3197 \begin_layout Itemize
3198 Don't dump fields related to event state feedback.
3201 \begin_layout Itemize
3202 Don't dump temporary flags that are only used while PC is running.
3203 Savestate when PC is running isn't possible anyway.
3206 \begin_layout Itemize
3207 Some connectors dump fields related to connector output, some don't.
3210 \begin_layout Section
3211 Advanced: Making output connectors
3214 \begin_layout Standard
3215 Implementing interface org.jpc.emulator.DisplayController signals that this
3216 is display controller, inhibiting loading of the standard VGA display controlle
3217 r if loaded as module.
3221 \begin_layout Subsection
3222 Interface org.jpc.emulator.OutputConnector
3225 \begin_layout Standard
3226 Class is made to be output connector by implementing this interface.
3227 This interface specifies the methods used for output hold locking.
3228 Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3229 that are suitable for calling.
3233 \begin_layout Subsubsection
3234 Method subscribeOutput(Object)
3237 \begin_layout Standard
3238 Subscribes the output, with specified object as handle.
3241 \begin_layout Subsubsection
3242 Method unsubscribeOutput(Object)
3245 \begin_layout Standard
3246 Unsubscribe the specified handle object from output.
3249 \begin_layout Subsubsection
3250 Method waitOutput(Object)
3253 \begin_layout Standard
3254 Wait for output on specified connector using specified handle object.
3255 Returns true on success, false if wait was interrupted by thread interrupt.
3259 \begin_layout Subsubsection
3260 Method releaseOutput(Object)
3263 \begin_layout Standard
3264 Release connector from p.o.v.
3269 \begin_layout Subsubsection
3273 \begin_layout Standard
3274 Release threads waiting on waitOutput() and block until all subscribers
3275 have returned from waitOutput() and enteired releaseOutput().
3278 \begin_layout Subsubsection
3279 Method releaseOutputWaitAll(object)
3282 \begin_layout Standard
3283 Like releaseOutput(), but waits until all handles have released their output.
3286 \begin_layout Subsection
3287 Class org.jpc.emulator.VGADigtalOut
3290 \begin_layout Standard
3291 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3292 VGA output connector.
3293 If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3297 \begin_layout Subsubsection
3301 \begin_layout Standard
3302 Get width of display (watch out, can return 0).
3305 \begin_layout Subsubsection
3309 \begin_layout Standard
3310 Get height of display (watch out, can return 0).
3313 \begin_layout Subsubsection
3314 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3317 \begin_layout Standard
3318 Returns the dirty region (region modified since last output).
3321 \begin_layout Subsubsection
3325 \begin_layout Standard
3326 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3327 one value per pixel) giving pixel data.
3328 Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3332 \begin_layout Subsubsection
3333 Method resizeDisplay(int _width, int _height)
3336 \begin_layout Standard
3337 Resize the display to be of specified size.
3340 \begin_layout Subsubsection
3341 Method dirtyDisplayRegion(int x, int y, int w, int h)
3344 \begin_layout Standard
3345 Mark the specified region as dirty.
3348 \begin_layout Subsubsection
3349 Method resetDirtyRegion()
3352 \begin_layout Standard
3353 Resets the dirty region to be empty.
3356 \begin_layout Subsection
3357 Class org.jpc.emulator.PC method getVideoOutput()
3360 \begin_layout Standard
3361 Get VGA output connector for PC.
3364 \begin_layout Subsection
3365 Interface org.jpc.emulator.DisplayController.
3368 \begin_layout Standard
3369 Implementing this class signals that module is VGA controller.
3370 There can be only one such module active at time and presence of such module
3371 prevents loading builtin VGA controller emulation code.
3374 \begin_layout Subsubsection
3375 Method getOutputDevice()
3378 \begin_layout Standard
3379 Get VGA output connector for this VGA device.
3382 \begin_layout Subsection
3383 Class org.jpc.emulator.SoundDigitalOut
3386 \begin_layout Standard
3387 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3388 Each connector can transfer stereo signal at arbitiary sampling rate.
3389 Modules that have audio connectors need to implement interface org.jpc.emulator.So
3390 undOutputDevice, as this signals that output connectors should be created.
3393 \begin_layout Subsubsection
3394 Method addSample(long, short, short)
3397 \begin_layout Standard
3398 Add stereo sample at time given by first argument.
3399 The second and third arguments give volume on left and right channels.
3402 \begin_layout Subsubsection
3403 Method addSample(long, short)
3406 \begin_layout Standard
3407 Add mono sample at time given by first argument.
3408 The second argument give volume on both channels.
3411 \begin_layout Subsubsection
3412 Method readBlock(Block)
3415 \begin_layout Standard
3416 Reads block of output (atomic versus addSample).
3417 Block structure has following fields which are filled:
3420 \begin_layout Itemize
3421 timeBase: Time base for block.
3424 \begin_layout Itemize
3425 baseLeft: Left volume at time base.
3428 \begin_layout Itemize
3429 baseRight: Right volume at time base
3432 \begin_layout Itemize
3433 blockNo: Sequence number of block filled.
3436 \begin_layout Itemize
3437 samples: Number of samples in block
3440 \begin_layout Itemize
3441 sampleTiming: Number of nanoseconds since last sample
3444 \begin_layout Itemize
3445 sampleLeft: Left channel samples
3448 \begin_layout Itemize
3449 sampleRight: Right channel samples
3452 \begin_layout Subsection
3453 Interface org.jpc.emulator.SoundOutputDevice
3456 \begin_layout Standard
3457 Implementing this interface signals that module has audio output channels.
3460 \begin_layout Subsubsection
3461 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3464 \begin_layout Standard
3465 Return the number of sound channels module has.
3468 \begin_layout Subsubsection
3469 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3472 \begin_layout Standard
3473 This is called once per sound channel requested giving precreated sound
3477 \begin_layout Subsection
3478 Class org.jpc.emulator.PC method getSoundOut(String)
3481 \begin_layout Standard
3482 Get sound output with specified name.
3485 \begin_layout Section
3486 Advanced: Writing event targets
3489 \begin_layout Standard
3490 Whereas output connectors are the way output is dispatched, input is dispatched
3492 Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3495 \begin_layout Standard
3496 Event targets also provode methods which then encode events and dispatch
3497 them forward (without doing anything else) to event recorder.
3498 Also, event targets may have methods for obtaining state.
3501 \begin_layout Subsection
3502 Interface org.jpc.emulator.EventDispatchTarget
3505 \begin_layout Standard
3506 Interface that marks class capable of receiving events.
3509 \begin_layout Subsubsection
3510 Method setEventRecorder(EventRecorder)
3513 \begin_layout Standard
3514 Set the event recorder input events are sent to.
3517 \begin_layout Subsubsection
3518 Method startEventCheck()
3521 \begin_layout Standard
3522 Signals target to reset all state related to event checking and state feedback.
3523 This may be called at any time in order to reinitialialize event checking/feedb
3527 \begin_layout Subsubsection
3528 Method doEvent(long, String[], int) throws IOException
3531 \begin_layout Standard
3532 Event dispatch handler.
3533 The first argument is event time, second is parameters and third is what
3535 If target doesn't like the event, throw IOException.
3536 Following types (the integer parameter) are used:
3539 \begin_layout LyX-Code
3540 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3543 \begin_layout LyX-Code
3544 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3545 for reinitialization
3548 \begin_layout LyX-Code
3549 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3552 \begin_layout LyX-Code
3553 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3557 \begin_layout Subsubsection
3558 Method endEventCheock()
3561 \begin_layout Standard
3562 End event reinitialization.
3566 \begin_layout Subsubsection
3567 Method getEventTimeLowBound(long, String[]) throws IOException
3570 \begin_layout Standard
3571 Return the time value that's the earliest possiblity for this event to occur.
3572 Returning any time in past (including -1) causes event to fire as soon
3574 The long parameter gives the current scheduled time for event.
3577 \begin_layout Section
3581 \begin_layout Standard
3582 Modules are various extensions that run inside emulator core.
3583 As such, they affect sync.
3584 Modules must implement interface org.jpc.emulator.HardwareComponent (they
3585 are hardware components) and must be dumpable.
3586 Additionally, they need either constructor <init>() or <init>(String).
3587 The first is if no parameters are passed, the second is for case where
3588 parameters are passed.
3591 \begin_layout Standard
3592 Aside of the constructors, modules need to obey the ordinary conventions
3593 for hardware components.
3594 No code outside modules needs to know that module exists.
3597 \begin_layout Section
3601 \begin_layout Standard
3602 Plugins handle various UI tasks.
3603 They need to implement interface org.jpc.Plugin.
3606 \begin_layout Subsection
3607 Interface org.jpc.pluginsbase.Plugin
3610 \begin_layout Subsubsection
3611 Method systemShutdown()
3614 \begin_layout Standard
3615 Called when emulator shuts down.
3616 Either called in dedicated thread or in thread that called emulatorShutdown().
3617 These handlers should do the bare minimum to get files on disk to consistent
3619 After these calls from all plugins have finished, emulator exits.
3620 Do not try to manipulate UI from these methods, as doing that easily leads
3624 \begin_layout Subsubsection
3625 Method reconnect(PC)
3628 \begin_layout Standard
3629 Gives new PC to connect to.
3630 Null is passed if plugin should disconnect.
3633 \begin_layout Subsubsection
3637 \begin_layout Standard
3638 Called in dedicated thread after plugin is initialized.
3641 \begin_layout Subsubsection
3645 \begin_layout Standard
3646 Called after PC has stopped.
3649 \begin_layout Subsubsection
3653 \begin_layout Standard
3654 Called before PC starts.
3657 \begin_layout Subsubsection
3658 Method notifyArguments(String[])
3661 \begin_layout Standard
3662 Pass arguments from command line.
3665 \begin_layout Subsubsection
3666 Constructor <init>(Plugins)
3669 \begin_layout Standard
3670 This constructor is used to initialize plugins that don't take parameters.
3673 \begin_layout Subsubsection
3674 Constructor <init>(Plugins, String)
3677 \begin_layout Standard
3678 This constructor is used to initialize plugins that take parameters.
3681 \begin_layout Subsection
3682 Class org.jpc.pluginsbase.Plugins
3685 \begin_layout Standard
3686 This class provodes various methods for manipulating plugins.
3689 \begin_layout Subsubsection
3690 Method isShuttingDown()
3693 \begin_layout Standard
3694 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3695 via VM exit, CTRL+C or explicitly.
3696 Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3699 \begin_layout Subsubsection
3700 Method shutdownEmulator()
3703 \begin_layout Standard
3704 Shut down and exit the emulator.
3705 All plugin shutdown functions are called in this thread.
3708 \begin_layout Subsubsection
3709 Method reconnectPC(PC)
3712 \begin_layout Standard
3713 Signal reconnectPC event to all plugins.
3716 \begin_layout Subsubsection
3720 \begin_layout Standard
3721 Signal pcStarting() event to all plugins.
3724 \begin_layout Subsubsection
3728 \begin_layout Standard
3729 Signal pcStopping() event to all plugins.
3732 \begin_layout Section
3733 Inter-plugin communication
3736 \begin_layout Subsection
3737 Receiving communications
3740 \begin_layout Standard
3741 To receive invocation/call by name 'foo-bar', declare public method named
3743 Arguments to this method can currently be String, Integer (int) or Long
3745 Last argument may be array over these types to get variable number of arguments.
3746 On call, each argument gets value from call.
3747 If last argument is array, it gets all overflowing arguments.
3748 If return type is void or method returns boolean false, call is assumed
3750 If return value is boolean true, it is assumed that there is more processing.
3753 \begin_layout Subsection
3754 void org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd, Object[]
3758 \begin_layout Standard
3759 Invoke command asynchronously, broadcasting to all plugins.
3760 Does not wait for slow commands to complete.
3761 cmd is the name to send and args are the arguments to pass.
3764 \begin_layout Subsection
3765 void org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String cmd,
3769 \begin_layout Standard
3770 Same as invokeExternalCommand, but waits for slow commands to complete.
3773 \begin_layout Subsection
3774 Object[] org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String cmd,
3778 \begin_layout Standard
3779 Similar to invokeExternalCommandSynchornous, but:
3782 \begin_layout Itemize
3783 Quits calling more plugins when it gets successful reply.
3786 \begin_layout Itemize
3790 \begin_layout Subsection
3791 void org.jpc.pluginsbase.Plugins.returnValue(Object...
3795 \begin_layout Standard
3796 Gives return value to return from call and signals that command has completed.
3799 \begin_layout Subsection
3800 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
3803 \begin_layout Standard
3804 Signals that command has completed.
3805 Only needed if there is no return value and eci_ method returned false
3809 \begin_layout Section
3810 Lua kernel programming
3813 \begin_layout Standard
3814 At startup, kernel gets its arguments in 'args' table and the script name
3815 to run in 'scriptname' string.
3816 It should enter the named script in protected mode.
3819 \begin_layout Standard
3820 The Lua VM exports numerious callbacks to kernel.
3821 The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3824 \begin_layout Itemize
3825 Always grab any functions used into local variables so nobody can mess with
3829 \begin_layout Itemize
3830 Don't use global variables in kernel (except for those passed).