1 #LyX 1.6.7 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 -autoexec assemble.jpcrrinit
129 \begin_layout Standard
130 The script pops up settings for new emulated PC (if you want to load savestate,
132 Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
133 selected), DOSfloppy for fda (boot device should be set to fda) and game
134 image as some HD drive
137 \begin_layout Subsection
141 \begin_layout Itemize
142 Putting the game as hdd (the fourth hard disk slot) causes boot to be bit
146 \begin_layout Itemize
147 Some BIOS versions have
148 \begin_inset Quotes eld
151 press F12 to select boot device
152 \begin_inset Quotes erd
156 Hit <enter> from emulated keyboard and that prompt will go away in about
157 half emulated second (it stays several emulated seconds otherwise).
161 \begin_layout Itemize
162 If game doesn't need lots of memory, hitting F5 to skip intialization files
164 If it does need more memory, run config.sys commands but not autoexec.bat.
168 \begin_layout Itemize
169 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
173 \begin_layout Section
174 Making JPC-RR format images from raw images
177 \begin_layout Standard
178 Due to various factors, JPC-RR can't use raw image files directly but requires
179 its own image format.
183 \begin_layout Subsection
184 Importing images from GUI:
187 \begin_layout Standard
188 Use Drives -> Import Image to import existing directories or image files.
189 Dialog prompting parameters will be displayed.
190 When importing floppy images, check
191 \begin_inset Quotes eld
195 \begin_inset Quotes erd
198 if possible, that enables geometry autodetection, which is reasonable virtually
199 all of the time it is offered.
202 \begin_layout Subsection
206 \begin_layout Itemize
207 If making image from directory, the names of the files must conform to FAT
208 naming restrictions (8+3 character names, no spaces, etc).
209 Avoid filenames with non-ASCII characters.
213 \begin_layout Itemize
214 The DOS limit of 112 or 224 files for floppies does not apply to images
215 created from directory trees.
216 The minimum limit value used is 512.
217 If even that isn't enough, the limit is automatically increased to fit
218 all the needed directory entries.
221 \begin_layout Itemize
222 Making boot disks from tree does NOT work.
223 Even if you got system boot files there, it still won't work.
226 \begin_layout Itemize
227 Only floppy disks and hard drives can be made from directory trees.
228 BIOS images and CDROM images require image file.
231 \begin_layout Itemize
232 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
233 Disks with over 63 sectors per track don't work with DOS.
234 Wheither disks with over 127 tracks per side work with DOS is unknown.
235 Also avoid 1024-tracks per side HDDs.
238 \begin_layout Itemize
239 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
241 1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
242 1-16 sides for HDD, 1 or 2 sides for floppy.
243 This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
244 and 516096KiB for HDDs.
247 \begin_layout Itemize
248 There are multiple image file contents that represent the same image.
249 The one with smallest size is picked when creating image.
252 \begin_layout Itemize
253 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
257 \begin_layout Subsection
258 Importing from command line
261 \begin_layout Standard
262 There is tool called ImageMaker that can make JPC-RR images from raw images.
263 Each image has format, ID an name.
264 Format and name are specified when making image.
265 ID is automatically calculated from format and contents.
266 Name does not affect the ID but is purely for convience so one doesn't
267 have to specify long image IDs manually.
270 \begin_layout Subsubsection
274 \begin_layout Standard
275 The syntax for ImageMaker when making images is:
278 \begin_layout LyX-Code
279 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
282 \begin_layout Standard
283 <destination> is file name for JPC-RR format image to write.
284 <source> is either name of regular file (raw image file) or name of directory
285 tree with files (supported for making floppy or hard disk images only).
286 In case of directory tree, the files are layout deterministically to disk,
287 so the ID will always be the same for given geometry and type.
288 <name> is name to give to disk.
292 \begin_layout LyX-Code
293 --BIOS BIOS image (note: VGABIOS is also of this type).
296 \begin_layout LyX-Code
297 --CDROM CD-ROM image.
300 \begin_layout LyX-Code
301 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
304 \begin_layout LyX-Code
305 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
308 \begin_layout LyX-Code
309 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
312 \begin_layout LyX-Code
313 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
316 \begin_layout LyX-Code
317 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
320 \begin_layout LyX-Code
321 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
324 \begin_layout LyX-Code
325 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
328 \begin_layout LyX-Code
329 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
332 \begin_layout LyX-Code
333 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
336 \begin_layout LyX-Code
337 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
340 \begin_layout LyX-Code
341 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
344 \begin_layout LyX-Code
345 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
348 \begin_layout LyX-Code
349 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
352 \begin_layout LyX-Code
353 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
356 \begin_layout LyX-Code
357 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
360 \begin_layout LyX-Code
361 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
364 \begin_layout LyX-Code
365 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
368 \begin_layout LyX-Code
369 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
372 \begin_layout LyX-Code
373 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
376 \begin_layout LyX-Code
377 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
380 \begin_layout LyX-Code
381 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
384 \begin_layout LyX-Code
385 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
388 \begin_layout LyX-Code
389 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
392 \begin_layout LyX-Code
393 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
396 \begin_layout LyX-Code
397 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
400 \begin_layout LyX-Code
401 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
404 \begin_layout LyX-Code
405 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
408 \begin_layout LyX-Code
409 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
412 \begin_layout LyX-Code
413 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
416 \begin_layout LyX-Code
417 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
420 \begin_layout LyX-Code
421 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
424 \begin_layout Subsubsection
428 \begin_layout LyX-Code
429 --volumelabel=label Give specified volume label (affects ID).
430 Only meaningful when making image out of directory tree.
431 Default is no volume label.
434 \begin_layout LyX-Code
435 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
436 Only meaningful when making image out of directory tree.
437 The default timestamp is 19900101T000000Z.
440 \begin_layout Subsubsection
444 \begin_layout Standard
448 \begin_layout LyX-Code
449 $ java ImageMaker <imagefile>
452 \begin_layout Standard
453 Variety of information about image is displayed (especially for floppies/HDDs).
454 Two important fields are calculated and claimed disk ID.
455 They should be the same.
456 If they are not, then the image file is corrupt (sadly, imagemaker has
457 bugs and bugs that cause it to write corrupt images have been seen).
460 \begin_layout Subsection
461 Advanced: The disk ID algorithm
464 \begin_layout Standard
465 The disk ID is calculated as:
468 \begin_layout LyX-Code
469 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
472 \begin_layout Standard
473 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
474 state and 128-bit output using the deprecated rotation constants (as specified
475 in Skein hash function reference documentation versions 1.0 and 1.1).
476 The <image> is the whole image, including parts not stored in image file.
477 The reason for keeping using the deprecated constants are:
480 \begin_layout Itemize
481 Changing the constants would change the IDs, which would invalidate existing
485 \begin_layout Itemize
486 This is not about cryptographic security
489 \begin_layout Itemize
490 The new constants don't improve security that much anyway.
493 \begin_layout Subsubsection
497 \begin_layout Standard
498 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
499 <geometry> is as follows (this is exactly the same form as it appears in
503 \begin_layout LyX-Code
504 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
507 \begin_layout LyX-Code
508 Byte 0 bits 2-5: Head count - 1.
511 \begin_layout LyX-Code
512 Byte 0 bits 6-7: Reserved, must be 0.
515 \begin_layout LyX-Code
516 Byte 1: Bits 0-7 of track count per side - 1.
519 \begin_layout LyX-Code
520 Byte 2: Sector count per track - 1.
523 \begin_layout Subsubsection
524 CD-ROM and BIOS images
527 \begin_layout Standard
528 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
533 \begin_layout Subsection
534 Advanced: Disk Image format
537 \begin_layout Standard
538 The disk image consists of following parts, concatenated in this order without
542 \begin_layout Itemize
546 \begin_layout Itemize
550 \begin_layout Itemize
554 \begin_layout Itemize
558 \begin_layout Itemize
562 \begin_layout Itemize
563 type-specific geometry/size data
566 \begin_layout Itemize
570 \begin_layout Itemize
574 \begin_layout Subsubsection
578 \begin_layout Standard
579 Magic in disk image files is following 5 bytes:
580 \begin_inset Quotes eld
584 \begin_inset Quotes erd
590 \begin_layout Subsubsection
594 \begin_layout Standard
595 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
598 \begin_layout Subsubsection
602 \begin_layout Standard
603 Type code is single byte.
604 0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
605 Other values are reserved.
608 \begin_layout Subsubsection
612 \begin_layout Standard
614 Disk name length is given as two-byte big-endian value.
615 New images should have 0 here.
618 \begin_layout Subsubsection
622 \begin_layout Standard
624 Name field is there for backward compatiblity.
625 Disk name length gives length of this field in bytes.
628 \begin_layout Subsubsection
629 Type-specific geometry/size data (floppies and HDDs)
632 \begin_layout Standard
633 Floppies and HDDs have 3-byte geometry data:
636 \begin_layout LyX-Code
637 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
640 \begin_layout LyX-Code
641 Byte 0 bits 2-5: Head count - 1.
644 \begin_layout LyX-Code
645 Byte 0 bits 6-7: Reserved, must be 0.
648 \begin_layout LyX-Code
649 Byte 1: Bits 0-7 of track count per side - 1.
652 \begin_layout LyX-Code
653 Byte 2: Sector count per track - 1.
656 \begin_layout Subsubsection
657 Type specific-geometry/size data (CD-ROMs)
660 \begin_layout Standard
661 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
664 \begin_layout Subsubsection
665 Type specific-geometry/size data (BIOS images)
668 \begin_layout Standard
669 BIOS images have 4-byte big-endian byte (not sector or block) count.
672 \begin_layout Subsubsection
673 Actual image data (floppy/HDD)
676 \begin_layout Standard
677 Floppy or HDD imagedata consists of following subparts:
680 \begin_layout Itemize
684 \begin_layout Itemize
688 \begin_layout Itemize
692 \begin_layout Itemize
696 \begin_layout Standard
697 Storage method is single byte.
698 Sectors present gives number of last nonzero sector + 1 (zero if image
702 \begin_layout Subsubsection
703 Floppy/HDD storage method 0: Raw storage
706 \begin_layout Standard
707 This storage method has empty header.
708 Image data is raw dump of first sectors present sectors.
711 \begin_layout Subsubsection
712 Floppy/HDD storage method 1: Sectormap
715 \begin_layout Standard
716 Image data header contains bitfield with just enough bytes to have one bit
718 The order of bits is such that number of bit corresponding to each sector
719 in byte is sector number modulo 8 and byte number is floor of sector number
720 divided by 8 when sector numbers are counted from zero.
721 If bit corresponding to sector is set, then the sector is present in image
722 data, otherwise it is absent and assumed to be all-zeroes.
725 \begin_layout Standard
726 Image data contains dumps of all present sectors in order of increasing
730 \begin_layout Subsubsection
731 Floppy/HDD storage method 2: Extent first sector zero
734 \begin_layout Standard
735 Image data is empty as storage-specific data is mangled with image data.
736 The image data alternates between blocks encoding zero sectors and blocks
737 encoding nonzero sectors.
738 The first block encodes zero sectors.
742 \begin_layout Standard
743 Block encoding zero sectors consist of single 1-4 byte little-endian value
744 encoding number of sectors in block - 1.
745 Number of bytes is determined by sectors present value.
746 It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
747 for more than 16777216.
748 All sectors in block are filled with zeroes and are not stored.
751 \begin_layout Standard
752 Block encoding nonzero sectors has same block count as zero sector block
753 but is followed by the sectors stored raw.
756 \begin_layout Subsubsection
757 Floppy/HDD storage method 3: Extent first sector nonzero
760 \begin_layout Standard
761 Same as storage method 2 but first block is nonzero sector block.
764 \begin_layout Subsubsection
765 Actual image data (CD-ROMs and BIOS images)
768 \begin_layout Standard
769 These store image data raw.
770 The amount of data is specified by sector/byte count.
773 \begin_layout Subsubsection
777 \begin_layout Standard
778 Comments are given as list of strings, with UTF-8 encoded strings following
779 2-octet big-endian length.
780 Comment list is terminated by entry with length 0 (0x00 0x00).
781 Comments are optional and may be absent.
784 \begin_layout Section
788 \begin_layout Standard
789 The actual emulator is invoked as:
792 \begin_layout LyX-Code
793 $ java JPCApplication <options>...
796 \begin_layout Standard
797 The valid options are:
800 \begin_layout LyX-Code
801 -autoexec <script> Execute contents of specified file as commands when starting
805 \begin_layout LyX-Code
806 -noautoexec Don't run autoexec files.
809 \begin_layout LyX-Code
810 -norenames Copy&Delete files instead of renaming.
811 Mainly meant for debugging copy&delte code.
814 \begin_layout LyX-Code
815 -imagemaker <options> Run in image maker mode (run with parameter '-imagemaker'
816 with no further parameters for help)
819 \begin_layout Standard
820 If no arguments are given, defaults of autoexec file of 'assemble.jpcrrinit'
824 \begin_layout Subsection
828 \begin_layout Standard
829 When emulator is started, command line comes up.
830 Following commands are known:
833 \begin_layout Itemize
834 'exit': exit immediately.
835 Dumps in progress are gracefully closed.
838 \begin_layout Itemize
839 'kill': Save stack traces and kill the emulator (for debugging only).
840 Any dumps in progress are likely corrupted.
843 \begin_layout Itemize
844 'library <library>': set library directory to <library>.
847 \begin_layout Itemize
848 'load <plugin>': Load plugin (no arguments)
851 \begin_layout Itemize
852 'load <plugin>(<arguments>)': load plugin with arguments.
855 \begin_layout Itemize
856 'command <command> [<arguments>...]': Invoke command via external command interface.
859 \begin_layout Itemize
860 'call<command> [<arguments>...]': Invoke command via external command interface
861 and print return values.
864 \begin_layout Itemize
865 'lsdisks [<filename>]' Print listing of all known disks.
866 If <filename> is specified, save output to specified file.
869 \begin_layout Itemize
870 'diskinfo [<filename>] <imagename>' Print Information about <imagename>
871 (can be disk name or ID).
872 If <filename> is specified, save output to specified file.
875 \begin_layout Standard
876 When one gets command line, its useful to load some plugins.
877 See section about plugins.
878 Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
879 like to start PC immediately.
882 \begin_layout Subsection
883 PC settings dialog notes
886 \begin_layout Itemize
887 CPU divider base frequency before division is 1GHz.
890 \begin_layout Itemize
891 Images can be specified by name or by ID.
892 Name is relative to library directory.
893 If the image is in subdirectory of image directory, the directory separator
894 is is '/' regardless of what the host OS uses.
897 \begin_layout Itemize
898 CD-ROM and hdc are mutually exclusive
901 \begin_layout Itemize
902 Modules is comma-seperated list of modules to load.
903 To pass arguments to some modules, enclose the arguments in ().
904 Same module can be specified twice only if parameters differ.
907 \begin_layout Itemize
908 Setting boot device doesn't work with some BIOS versions.
909 Those versions prompt the boot device anyway.
912 \begin_layout Subsection
913 Audio output channels
916 \begin_layout Standard
917 PC can have one or more audio output channels.
918 The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
920 Modules that have audio outputs get channel names of form <classname>-<sequenti
921 al>, where <classname> is name of main module class and sequential is number
923 Note that same module can have multiple output channels.
924 If multiple modules of same class request audio outputs, the <sequential>
925 values of subsequent module start where previous left off.
928 \begin_layout Subsection
932 \begin_layout Standard
933 Plugins actually execute the tasks of the emulator.
934 They can be loaded using
935 \begin_inset Quotes eld
939 \begin_inset Quotes erd
942 or 'load <plugin>(<arguments>)
943 \begin_inset Quotes erd
949 \begin_layout Standard
950 Different Plugins using the same output (like running PCMonitor and RAWVideoDump
951 er) should not conflict because connector output hold locking is desinged
952 to handle multiple readers.
955 \begin_layout Standard
956 If no plugin used requires GUI, then the emulator can be run without having
960 \begin_layout Subsubsection
961 plugin: org.jpc.plugins.PCControl
964 \begin_layout Standard
965 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1', requires and
969 \begin_layout Standard
970 Runs the PC emulator core.
971 Has capability to start/stop emulation, breakpoint after certain time or
972 start/end of VGA vertical retrace.
973 Also can create, savestate and loadstate PC emulation.
974 Memory dumping is supported.
978 \begin_layout Standard
979 'extramenu=<file>' causes Plugin to load extra menu entries from <file>.
980 'uncompressedsave=1' causes savestates to be written uncompressed (useful
981 if they are stored in VCS supporting delta compression).
984 \begin_layout Subsubsection
985 plugin: org.jpc.plugins.PCRunner
988 \begin_layout Standard
989 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
993 \begin_layout Standard
994 Loads PC from savestate and just runs it.
996 Also automatically quits once stoptime is reached.
999 \begin_layout Subsubsection
1000 plugin: org.jpc.plugins.PCMonitor
1003 \begin_layout Standard
1004 No arguments, requires and uses GUI.
1007 \begin_layout Standard
1008 VGA monitor for emulated PC.
1011 \begin_layout Subsubsection
1012 plugin: org.jpc.plugins.VirtualKeyboard
1015 \begin_layout Standard
1016 No arguments, requires and uses GUI.
1019 \begin_layout Standard
1020 On-screen keyboard for emulated PC.
1023 \begin_layout Subsubsection
1024 plugin: org.jpc.plugins.PCStartStopTest
1027 \begin_layout Standard
1028 No arguments, requires and uses GUI.
1031 \begin_layout Standard
1032 Small plugin testing remote PC start/stop.
1033 Also supports sending some common keypresses.
1036 \begin_layout Subsubsection
1037 plugin: org.jpc.plugins.RAWVideoDumper
1040 \begin_layout Standard
1041 Takes 'rawoutput=<file>' as argument.
1042 Does not require nor use GUI.
1045 \begin_layout Standard
1046 Dumps all generated frames to RAW file <file>.
1047 Rawoutput is required.
1048 The raw file consists of concatenation of zlib streams.
1049 The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1050 each acting as time offset of 2^32-1 nanoseconds and saved frames.
1051 The saved frame has time offset in nanoseconds (big endian) as first four
1052 bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1053 The next two bytes are big-endian width, next two big-endian height.
1054 Finally frame has 4 * width * height bytes of data that encodes pixels
1055 using 4 bytes per pixel, in left-to-right, up-to-down order.
1056 Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1057 green channel and byte 3 is blue channel.
1060 \begin_layout Standard
1061 Dumping to pipe is supported.
1064 \begin_layout Subsubsection
1065 plugin: org.jpc.plugins.RAWAudioDumper
1068 \begin_layout Standard
1069 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1070 'offset=<offset>' as arguments, separated by ','.
1071 Does not require nor use GUI.
1074 \begin_layout Standard
1075 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1076 file (file, mandatory).
1077 The resulting file consists of records, 4 or 8 bytes each.
1078 4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1080 \begin_inset Formula $2^{32}-1$
1084 Otherwise record is 8 bytes.
1085 Each 8 byte record has three fields.
1086 First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1088 \begin_inset Formula $2^{32}-1$
1091 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1092 big endian new right channel volume.
1093 Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1097 \begin_layout Subsubsection
1098 plugin: org.jpc.plugins.LuaPlugin
1101 \begin_layout Standard
1102 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1103 kernel, requires and uses GUI.
1106 \begin_layout Standard
1107 Lua VM for executing scripts.
1110 \begin_layout Subsubsection
1111 plugin: org.jpc.plugins.JoystickInput
1114 \begin_layout Standard
1116 Displays window for sending joystick input.
1119 \begin_layout Section
1123 \begin_layout Subsection
1124 org.jpc.modules.Joystick:
1127 \begin_layout Itemize
1131 \begin_layout Itemize
1132 Resources: I/O port 0x201
1135 \begin_layout Standard
1136 Emulates joystick game port.
1139 \begin_layout Subsection
1140 org.jpc.modules.SoundCard
1143 \begin_layout Itemize
1144 Arguments: Optional resources specification
1147 \begin_layout Itemize
1148 Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
1151 \begin_layout Standard
1152 Emulates Sound card.
1155 \begin_layout Subsection
1156 org.jpc.modules.GMIDIInterface
1159 \begin_layout Itemize
1160 Arguments: Optional resources specification
1163 \begin_layout Itemize
1164 Resources (defaults): I/O port 0x330-0x331, IRQ 9
1167 \begin_layout Standard
1168 Emulates General MIDI interface.
1171 \begin_layout Subsection
1172 org.jpc.modules.FMCard
1175 \begin_layout Itemize
1176 Arguments: Optional resources specification
1179 \begin_layout Itemize
1180 Resources (defaults): I/O port 0x338-0x33B
1183 \begin_layout Standard
1187 \begin_layout Subsection
1188 org.jpc.modules.BasicFPU:
1191 \begin_layout Itemize
1195 \begin_layout Itemize
1199 \begin_layout Standard
1200 Crude FPU (x87) emulator.
1203 \begin_layout Section
1207 \begin_layout Standard
1208 Hacks are saved to savestates but not movies.
1211 \begin_layout Subsection
1215 \begin_layout Standard
1216 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1218 BIOS assumes system has FPU but some games use that bit to detect FPU,
1219 trying to use it if it is
1220 \begin_inset Quotes eld
1224 \begin_inset Quotes erd
1228 Try this if game startup hangs with lots of trying to use FPU but not present
1230 Don't use if there is FPU present.
1231 Needed to get games like Blake Stone / Wolfenstein 3-D to work (FPU emulator
1232 allows it to start but causes graphical glitches).
1235 \begin_layout Subsection
1239 \begin_layout Standard
1240 Update basic VGA parameters before vretrace, not after it.
1242 Commander Keen 4) don't like if this isn't done and some games (e.g.
1243 Mario & Luigi) don't like if it is done.
1244 Wrong value manifests as jerky scrolling (scrolling back and forth and
1245 fixed statusbars move).
1248 \begin_layout Section
1249 Some error messages and explanations
1252 \begin_layout Itemize
1253 <filename> is Not a valid image file
1256 \begin_layout Itemize
1257 <filename> is not image file
1260 \begin_layout Itemize
1261 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1265 \begin_layout Itemize
1266 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1270 \begin_layout Itemize
1271 Can't read disk image sector map.
1274 \begin_layout Itemize
1275 Can't read disk image extent.
1278 \begin_layout Standard
1279 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1280 image at all or its corrupt.
1283 \begin_layout Itemize
1284 <filename> is image of unknown type.
1287 \begin_layout Itemize
1288 <filename> has unrecognized geometry <x> <y> <z>
1291 \begin_layout Standard
1292 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1293 containing something current version can't comprehend.
1296 \begin_layout Itemize
1297 Invalid format specifier <something>.
1300 \begin_layout Itemize
1301 Invalid syntax of --floppy= or --HDD= option.
1304 \begin_layout Itemize
1305 Invalid format specifier/option <something>.
1308 \begin_layout Standard
1309 Invalid option or format specifier was given.
1313 \begin_layout Itemize
1314 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1317 \begin_layout Standard
1318 Check syntax of command.
1319 Especially that diskname is present!
1322 \begin_layout Itemize
1323 The image has <nnn> sectors while it should have <yyy> according to selected
1327 \begin_layout Itemize
1328 Raw image file length not divisible by 512.
1331 \begin_layout Itemize
1332 Trying to read sector out of range.
1335 \begin_layout Standard
1336 The selected geometry is wrong or raw image is incomplete.
1339 \begin_layout Itemize
1340 Invalid disk name (Should not happen!).
1343 \begin_layout Itemize
1344 Invalid geometry to be written.
1347 \begin_layout Standard
1348 This is a very likely a bug in program.
1351 \begin_layout Itemize
1352 What the heck <filename> is? It's not regular file nor directory.
1355 \begin_layout Standard
1356 That sort of file can't be used as input for image making, or the file just
1360 \begin_layout Itemize
1361 BIOS images can only be made out of regular files.
1364 \begin_layout Itemize
1365 CD images can only be made out of regular files.
1368 \begin_layout Standard
1369 Source image specified is not regular file, but image of that type can't
1370 be made of anything else.
1373 \begin_layout Itemize
1374 Can't read raw bios image file.
1377 \begin_layout Itemize
1378 Can't read sector <nnn> from image.
1381 \begin_layout Standard
1382 Reading the raw image file failed for some reason.
1385 \begin_layout Itemize
1386 Bad library line: "<something>".
1390 \begin_layout Standard
1391 Syntax error in image library.
1394 \begin_layout Itemize
1395 Removing image <something> a.k.a.
1396 "<something>" as it no longer exists.
1399 \begin_layout Standard
1400 The image file no longer exists so it gets removed from library.
1403 \begin_layout Itemize
1404 Removing image <something> a.k.a.
1405 "<something>" due to <some> conflict.
1408 \begin_layout Standard
1409 Image library code killed some image from library due to some kind of conflict
1410 with image being added.
1413 \begin_layout Itemize
1414 Too much data to fit into given space.
1417 \begin_layout Standard
1418 The tree you gave contains takes just too much space to fit into disk of
1422 \begin_layout Section
1423 Advanced: Savestate/movie format
1426 \begin_layout Subsection
1427 Special character classes
1430 \begin_layout Subsubsection
1434 \begin_layout Standard
1435 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1439 \begin_layout Itemize
1440 Codepoints 0x20, and 0x09.
1443 \begin_layout Itemize
1444 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1447 \begin_layout Itemize
1448 Codepoints 0x2000-0x200A.
1451 \begin_layout Subsubsection
1455 \begin_layout Standard
1456 Following byte sequences are interpretted as linefeeds (line change):
1459 \begin_layout Itemize
1460 Byte 0x0A (UTF-8 encoded codepoint 0x0A)
1463 \begin_layout Itemize
1464 Byte 0x0D (UTF-8 encoded codepoint 0x0D)
1467 \begin_layout Itemize
1468 Byte 0x1C (UTF-8 encoded codepoint 0x1C)
1471 \begin_layout Itemize
1472 Byte 0x1D (UTF-8 encoded codepoint 0x1D)
1475 \begin_layout Itemize
1476 Byte 0x1E (UTF-8 encoded codepoint 0x1E)
1479 \begin_layout Itemize
1480 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL, codepoint 0x85)
1483 \begin_layout Itemize
1484 Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
1487 \begin_layout Subsection
1491 \begin_layout Standard
1492 JRSR archive format packs multiple text archive members to text archive.
1493 It does not support binary members.
1494 JRSR archives have first five or six bytes form the magic.
1496 \begin_inset Quotes eld
1500 \begin_inset Quotes erd
1503 followed by LINEFEED character There are four kinds of lines after that
1504 (lines are terminated by LINEFEED byte/bytes):
1507 \begin_layout Itemize
1511 \begin_layout Itemize
1515 \begin_layout Itemize
1519 \begin_layout Itemize
1523 \begin_layout Standard
1524 Sequencing rules are as follows: Start member is allowed anywhere (after
1526 Member line is allowed only inside member (member started but not ended).
1527 End member is only allowed inside member.
1528 End of file is only allowed outside member.
1529 Blank line is allowed anywhere after magic.
1532 \begin_layout Subsubsection
1536 \begin_layout Standard
1537 Start member line is given as
1538 \begin_inset Quotes eld
1542 \begin_inset Quotes erd
1545 <SPACE>+ <membername> <LINEFEED>.
1546 <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1548 The member name is UTF-8 encoded and maximum allowed line length is 2048
1549 bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1550 depending on characters used).
1551 Starting member inside another implicitly ends the previous member.
1554 \begin_layout Subsubsection
1558 \begin_layout Standard
1559 Member line is given as
1560 \begin_inset Quotes eld
1564 \begin_inset Quotes erd
1567 <content><LINEFEED>.
1568 It gives another line for member contents.
1569 <content> is passed raw to layers above (followed by line termination)
1572 \begin_layout Subsubsection
1576 \begin_layout Standard
1577 End member line is given as
1578 \begin_inset Quotes eld
1582 \begin_inset Quotes erd
1586 It ends the current member.
1587 The following line can only be start member line or file may end.
1590 \begin_layout Subsubsection
1594 \begin_layout Standard
1595 Blank line is given as <LINEFEED>.
1596 Lines like that are ignored.
1599 \begin_layout Subsection
1600 Four-to-Five encoding
1603 \begin_layout Standard
1604 Binary members are encoded into text by so-called four-to-five encoding.
1605 This encoding can encode single byte to two, two bytes to three, three
1606 bytes to four and four bytes to five.
1607 Four-to-five encoding has five kinds of blocks.
1608 All SPACE and LINEFEED characters are completely ignored, even in middle
1612 \begin_layout Subsubsection
1616 \begin_layout Standard
1617 End stream block is encoded as '!'.
1618 It ends the stream instantly.
1619 There is also implicit end of stream at end of input to decoding.
1622 \begin_layout Subsubsection
1623 Other four block types
1626 \begin_layout Standard
1627 Other four block types take the value to be encoded, read it as big-endian
1629 Then they write it as base-93 big-endian value.
1630 Then length specific constants are added to digits of that number to yield
1631 ASCII values for characters (those are stored in order):
1634 \begin_layout Standard
1635 \begin_inset Tabular
1636 <lyxtabular version="3" rows="5" columns="6">
1638 <column alignment="center" valignment="top" width="0">
1639 <column alignment="center" valignment="top" width="0">
1640 <column alignment="center" valignment="top" width="0">
1641 <column alignment="center" valignment="top" width="0">
1642 <column alignment="center" valignment="top" width="0">
1643 <column alignment="center" valignment="top" width="0">
1645 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1648 \begin_layout Plain Layout
1654 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1657 \begin_layout Plain Layout
1663 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1666 \begin_layout Plain Layout
1672 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1675 \begin_layout Plain Layout
1681 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1684 \begin_layout Plain Layout
1690 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1693 \begin_layout Plain Layout
1701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1704 \begin_layout Plain Layout
1710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1713 \begin_layout Plain Layout
1719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1722 \begin_layout Plain Layout
1728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1731 \begin_layout Plain Layout
1737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1740 \begin_layout Plain Layout
1746 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1749 \begin_layout Plain Layout
1757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1760 \begin_layout Plain Layout
1766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1769 \begin_layout Plain Layout
1775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1778 \begin_layout Plain Layout
1784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1787 \begin_layout Plain Layout
1793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1796 \begin_layout Plain Layout
1802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1805 \begin_layout Plain Layout
1813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1816 \begin_layout Plain Layout
1822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1825 \begin_layout Plain Layout
1831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1834 \begin_layout Plain Layout
1840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1843 \begin_layout Plain Layout
1849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1852 \begin_layout Plain Layout
1858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1861 \begin_layout Plain Layout
1869 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1872 \begin_layout Plain Layout
1878 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1881 \begin_layout Plain Layout
1887 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1890 \begin_layout Plain Layout
1896 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1899 \begin_layout Plain Layout
1905 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1908 \begin_layout Plain Layout
1914 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1917 \begin_layout Plain Layout
1931 \begin_layout Standard
1932 Blocks which encode values greater than what is possible for value of that
1933 length are fatal errors.
1937 \begin_layout Subsection
1938 Line component encoing
1941 \begin_layout Standard
1942 Line component encoding sits on top of UTF-8 encoding.
1943 Line component encoding encodes non-empty 1-D array of non-empty strings
1944 into line, and thus array of those into member.
1945 Empty lines or lines that don't contain any components are ignored.
1946 Line starts with depth value of 0 and must end with depth value of zero.
1949 \begin_layout Standard
1950 Components are seperated by component separators.
1951 Empty components are ignored.
1952 Following codepoints are separators on depth 0 if not escaped:
1955 \begin_layout Itemize
1957 The depth is read pre-increment.
1960 \begin_layout Itemize
1962 The depth is read post-decrement.
1965 \begin_layout Itemize
1969 \begin_layout Standard
1970 The following characters are special:
1973 \begin_layout Itemize
1975 Increments depth by 1 if not escaped (and appears in component).
1978 \begin_layout Itemize
1980 Decrements depth by 1 if not escaped (and appears in component).
1981 Depth going negative is an error.
1984 \begin_layout Itemize
1988 Next character is interpretted as literal.
1989 Error if at end of line.
1992 \begin_layout Standard
1993 Otherwise, characters are interpretted as literals and appear in components.
1994 Depth must be zero at end of line.
1997 \begin_layout Subsection
2001 \begin_layout Standard
2002 Header section is in archive member "header".
2003 It uses line component encoding.
2004 The first component of each line is name of header, and subsequent ones
2006 How many parameters are expected is dependent on what header it is:
2009 \begin_layout Subsubsection
2013 \begin_layout Itemize
2014 Header name: "PROJECTID"
2017 \begin_layout Itemize
2021 \begin_layout Itemize
2022 Argument #1: <project-id-string>
2025 \begin_layout Itemize
2029 \begin_layout Standard
2031 Project ID is generated when PC is assembled and is then preserved in save
2033 It is used for computing rerecord counts.
2034 Emulator treats it as opaque string, the IDs it generates are formed by
2035 48 random hexadecimal digits.
2038 \begin_layout Subsubsection
2042 \begin_layout Itemize
2043 Header name: "SAVESTATEID"
2046 \begin_layout Itemize
2050 \begin_layout Itemize
2051 Argument #1: <savestate-id-string>
2054 \begin_layout Itemize
2058 \begin_layout Standard
2059 Gives save state ID.
2060 Each save state has its own save state ID.
2061 Treated as opaque string, but generated as 48 random hexadecimal digits.
2062 The presence of this header signals whether there is save state to be loaded.
2063 If this header is present, save state load will be attempted.
2064 If absent, save state is not to be loaded even if present (and correct
2065 savestate load would be technically impossible anyway).
2068 \begin_layout Standard
2069 The value is used to prevent loading incompatible save states in preserve
2070 event stream mode and also to find the point in event stream where one
2074 \begin_layout Subsubsection
2078 \begin_layout Itemize
2079 Header name: "RERECORDS"
2082 \begin_layout Itemize
2086 \begin_layout Itemize
2087 Argument #1: <rerecords>
2090 \begin_layout Itemize
2094 \begin_layout Standard
2095 Gives rerecord count.
2096 PC assembly (except when loading save state) initializes current rerecord
2098 Must be non-negative and decimal number using ASCII digit characters.
2101 \begin_layout LyX-Code
2102 On loading save state:
2105 \begin_layout LyX-Code
2106 1) If project ID matches with previous:
2109 \begin_layout LyX-Code
2110 1a) If loaded rerecord count is larger or equal to current rerecord count:
2113 \begin_layout LyX-Code
2114 1a-a) Current rerecord count is loaded rerecord count + 1.
2117 \begin_layout LyX-Code
2121 \begin_layout LyX-Code
2122 1b-a) Current rerecord count increments by 1.
2125 \begin_layout LyX-Code
2129 \begin_layout LyX-Code
2130 2a) Current rerecord count is loaded rerecord count + 1.
2133 \begin_layout Standard
2134 The current rerecord count at time of save is saved to save state.
2137 \begin_layout Subsubsection
2141 \begin_layout Itemize
2142 Header name: "SYSTEM"
2145 \begin_layout Itemize
2149 \begin_layout Itemize
2150 Argument #1: <system-id-string>
2153 \begin_layout Itemize
2157 \begin_layout Standard
2158 Gives system this movie/save is for.
2159 The only currently recognized values are
2160 \begin_inset Quotes eld
2164 \begin_inset Quotes erd
2168 \begin_inset Quotes eld
2172 \begin_inset Quotes erd
2175 (if this header is absent, use default system).
2176 Invalid values trigger error on load time.
2178 \begin_inset Quotes eld
2182 \begin_inset Quotes erd
2185 should be used if INITIALSTATE headers are present to avoid earlier versions
2186 from getting confused by those.
2189 \begin_layout Subsubsection
2193 \begin_layout Itemize
2194 Header name: "AUTHORS"
2197 \begin_layout Itemize
2198 Components: 2 or more
2201 \begin_layout Itemize
2202 Arguments: free form
2205 \begin_layout Itemize
2209 \begin_layout Standard
2210 Gives authors of run.
2211 Each argument gives one author (who has full name but no nickname).
2212 May be present multiple times.
2215 \begin_layout Subsubsection
2219 \begin_layout Itemize
2220 Header name: "AUTHORNICKS"
2223 \begin_layout Itemize
2224 Components: 2 or more
2227 \begin_layout Itemize
2228 Arguments: free form
2231 \begin_layout Itemize
2235 \begin_layout Standard
2236 Gives authors of run.
2237 Each argument gives one author (who has nickname but no full name).
2238 May be present multiple times.
2241 \begin_layout Subsubsection
2245 \begin_layout Itemize
2246 Header name: "AUTHORFULL"
2249 \begin_layout Itemize
2253 \begin_layout Itemize
2254 Arguments: free form
2257 \begin_layout Itemize
2261 \begin_layout Standard
2262 Gives author of run.
2263 First argument is full name of author, and second is nickname of author.
2264 May be present multiple times.
2267 \begin_layout Subsubsection
2271 \begin_layout Itemize
2272 Header name: "COMMENT"
2275 \begin_layout Itemize
2276 Components: 2 or more
2279 \begin_layout Itemize
2280 Arguments: free form
2283 \begin_layout Itemize
2287 \begin_layout Standard
2288 Various kinds of free form data.
2289 Not parsed further by emulator.
2292 \begin_layout Subsubsection
2293 INITIALSTATE header:
2296 \begin_layout Itemize
2297 Header name: "INITIALSTATE"
2300 \begin_layout Itemize
2301 Components: 2 or more
2304 \begin_layout Itemize
2305 Arguments: Name of initial state
2308 \begin_layout Itemize
2312 \begin_layout Standard
2314 \begin_inset Quotes eld
2318 \begin_inset Quotes erd
2321 <name> is valid initial state.
2324 \begin_layout Subsection
2325 Initialization segment:
2328 \begin_layout Standard
2329 If SAVESTATEID header isn't present (not a save state), member "initialization"
2331 \begin_inset Quotes eld
2335 \begin_inset Quotes erd
2338 <name>) gives PC initialization parameters for assembling the PC.
2339 It is present anyway even if SAVESTATEID is present (savestate).
2342 \begin_layout Standard
2343 Following parameters are used (space separates components):
2346 \begin_layout LyX-Code
2350 \begin_layout Standard
2351 Gives Image ID of main system BIOS (mandatory)
2354 \begin_layout LyX-Code
2358 \begin_layout Standard
2359 Gives Image ID of VGA BIOS (mandatory).
2362 \begin_layout LyX-Code
2366 \begin_layout Standard
2367 Gives Image ID of hda.
2368 Present only if system has hard disk hda.
2371 \begin_layout LyX-Code
2375 \begin_layout Standard
2376 Gives Image ID of hdb.
2377 Present only if system has hard disk hdb.
2380 \begin_layout LyX-Code
2384 \begin_layout Standard
2385 Gives Image ID of hdc.
2386 Present only if system has hard disk hdc.
2389 \begin_layout LyX-Code
2393 \begin_layout Standard
2394 Gives Image ID of hdd.
2395 Present only if system has hard disk hdd.
2398 \begin_layout LyX-Code
2402 \begin_layout Standard
2403 Gives Image ID of disk in slot <num>.
2404 Slot number must be non-negative.
2407 \begin_layout LyX-Code
2408 \begin_inset Quotes eld
2412 \begin_inset Quotes erd
2418 \begin_layout Standard
2419 kGives image name of disk in slot <num>.
2420 Slot number must be non-negative.
2421 The slot must be previously declared using
2422 \begin_inset Quotes eld
2426 \begin_inset Quotes erd
2432 \begin_layout LyX-Code
2436 \begin_layout Standard
2437 Gives Image slot to initially put into floppy drive fda.
2438 Disk must be of floppy type.
2439 If none present, no disk is initially put there.
2442 \begin_layout LyX-Code
2446 \begin_layout Standard
2447 Gives Image slot to initially put into floppy drive fdb.
2448 Disk must be of floppy type.
2449 If none present, no disk is initially put there.
2452 \begin_layout LyX-Code
2456 \begin_layout Standard
2457 Gives Image slot to initially put into CD-ROM drive hdc.
2458 Not allowed if hard disk hdc is present.
2459 Disk must be of CD-ROM type.
2460 If none present no disk is initially put there.
2463 \begin_layout LyX-Code
2464 "INITIALTIME" <time>
2467 \begin_layout Standard
2468 Number of milliseconds since Unix epoch to system start up time.
2472 \begin_layout Standard
2477 \begin_layout LyX-Code
2478 "CPUDIVIDER" <divider>
2481 \begin_layout Standard
2482 Set CPU frequency divider (dividing the 1GHz master clock).
2483 Allowed range is 1-256.
2487 \begin_layout LyX-Code
2488 "MEMORYSIZE" <pages>
2491 \begin_layout Standard
2492 Number of 4KiB pages of RAM memory.
2493 Allowed range 256-262144.
2497 \begin_layout LyX-Code
2501 \begin_layout Standard
2503 Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2507 \begin_layout LyX-Code
2508 "LOADMODULEA" <module> <parameters>
2511 \begin_layout Standard
2512 Load module <module> with parameters <parameters>.
2515 \begin_layout LyX-Code
2516 "LOADMODULE" <module>
2519 \begin_layout Standard
2520 Load module <module> with no parameters
2523 \begin_layout LyX-Code
2524 \begin_inset Quotes eld
2528 \begin_inset Quotes erd
2534 \begin_layout Standard
2535 Use class <fpu> as FPU emulator.
2538 \begin_layout LyX-Code
2539 \begin_inset Quotes eld
2543 \begin_inset Quotes erd
2549 \begin_layout Standard
2550 Use I/O port delay emulation (each I/O port read/write takes 666ns).
2553 \begin_layout LyX-Code
2554 \begin_inset Quotes eld
2558 \begin_inset Quotes erd
2564 \begin_layout Standard
2565 Emulate VGA horizontal retrace.
2568 \begin_layout Subsection
2569 Event record format:
2572 \begin_layout Standard
2573 Event record is in archive member "events".
2574 It uses line component encoding.
2575 Each line gives an event.
2576 First component of each line gives time stamp.
2577 These timestamps MUST be in increasing order and all MUST be non-negative.
2578 Time stamp time unit is exactly 1 nanosecond of emulated time.
2581 \begin_layout Standard
2582 The second component of each line is name of class to dispatch to.
2583 Further components are passed as-is to event handlers.
2584 Classes with names consisting only of uppercase A-Z and 0-9 are special
2586 It is error to encounter unknown such special class.
2589 \begin_layout Subsubsection
2593 \begin_layout Itemize
2594 Dispatch to: SAVESTATE
2597 \begin_layout Itemize
2598 Argument #1: Savestate id
2601 \begin_layout Itemize
2602 Argument #2 (optional): Rerecord count at time of saving savestate
2605 \begin_layout Standard
2606 Signals that savestate has occured here.
2607 The save state IDs MUST be unique in entire event stream.
2608 The second argument to savestate (if present) is rerecord count at time
2609 of saving that savestate (useful for calulating rerecord count of movie
2610 starting from savestate).
2611 No time restrictions
2614 \begin_layout Subsubsection
2618 \begin_layout Itemize
2622 \begin_layout Itemize
2624 \begin_inset Quotes eld
2628 \begin_inset Quotes erd
2632 \begin_inset Quotes eld
2636 \begin_inset Quotes erd
2642 \begin_layout Standard
2643 Controls various options.
2645 \begin_inset Quotes eld
2649 \begin_inset Quotes erd
2652 turns on absolute mode (default) where event timestamps are absolute.
2654 \begin_inset Quotes eld
2658 \begin_inset Quotes erd
2661 turns on relative mode where event timestamps are relative to last event
2663 The OPTION event itself is not affected by timing change.
2664 No time restrictions.
2665 Unknown arguments are errors.
2668 \begin_layout Subsubsection
2669 Keyboard keypress/keyrelease event:
2672 \begin_layout Itemize
2673 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2676 \begin_layout Itemize
2677 Argument #1: Fixed: "KEYEDGE"
2680 \begin_layout Itemize
2681 Argument #2: Key number.
2682 Valid values are 1-83, 85-95, 129-197 and 199-223
2685 \begin_layout Standard
2686 Send key press or key release.
2687 Keys work in toggle button manner.
2688 The event time must be multiple of 66 666, and must not be less than 60
2689 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2690 on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2693 \begin_layout Subsubsection
2697 \begin_layout Itemize
2698 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2701 \begin_layout Itemize
2702 Argument #1: Fixed: "PAUSE"
2705 \begin_layout Standard
2706 Send pause key event.
2707 The time restrictions are identical to KEYEDGE event.
2710 \begin_layout Subsubsection
2714 \begin_layout Itemize
2715 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2718 \begin_layout Itemize
2719 Argument #1: Fixed: "MOUSEBUTTON"
2722 \begin_layout Itemize
2723 Argument #2: Number of button to release or press (0-4)
2726 \begin_layout Standard
2727 Presses or releases the designated mouse button.
2730 \begin_layout Subsubsection
2731 X mouse motion event:
2734 \begin_layout Itemize
2735 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2738 \begin_layout Itemize
2739 Argument #1: Fixed: "XMOUSEMOTION"
2742 \begin_layout Itemize
2743 Argument #2: Number of units to move (-255 - 255)
2746 \begin_layout Standard
2747 Move the mouse in X direction by specified amount.
2751 \begin_layout Subsubsection
2752 Y mouse motion event:
2755 \begin_layout Itemize
2756 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2759 \begin_layout Itemize
2760 Argument #1: Fixed: "YMOUSEMOTION"
2763 \begin_layout Itemize
2764 Argument #2: Number of units to move (-255 - 255)
2767 \begin_layout Standard
2768 Move the mouse in Y direction by specified amount.
2772 \begin_layout Subsubsection
2773 Z mouse motion event:
2776 \begin_layout Itemize
2777 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2780 \begin_layout Itemize
2781 Argument #1: Fixed: "ZMOUSEMOTION"
2784 \begin_layout Itemize
2785 Argument #2: Number of units to move (-7 - 7)
2788 \begin_layout Standard
2789 Move the mouse in Z direction (scrollwheel) by specified amount.
2792 \begin_layout Subsubsection
2793 Joystick button event:
2796 \begin_layout Itemize
2797 Dispatch to: org.jpc.modules.Joystick
2800 \begin_layout Itemize
2802 \begin_inset Quotes eld
2806 \begin_inset Quotes erd
2810 \begin_inset Quotes eld
2814 \begin_inset Quotes erd
2818 \begin_inset Quotes eld
2822 \begin_inset Quotes erd
2826 \begin_inset Quotes eld
2830 \begin_inset Quotes erd
2836 \begin_layout Itemize
2838 \begin_inset Quotes eld
2842 \begin_inset Quotes erd
2846 \begin_inset Quotes eld
2850 \begin_inset Quotes erd
2856 \begin_layout Standard
2857 Send button down/up event.
2858 No time restrictions.
2861 \begin_layout Subsubsection
2862 Joystick axis event:
2865 \begin_layout Itemize
2866 Dispatch to: org.jpc.modules.Joystick
2869 \begin_layout Itemize
2871 \begin_inset Quotes eld
2875 \begin_inset Quotes erd
2879 \begin_inset Quotes eld
2883 \begin_inset Quotes erd
2887 \begin_inset Quotes eld
2891 \begin_inset Quotes erd
2895 \begin_inset Quotes eld
2899 \begin_inset Quotes erd
2905 \begin_layout Itemize
2906 Argument #2: Multivibrator unstable state length in ns.
2909 \begin_layout Standard
2910 Set amount of time multivibrator remains in unstable state.
2911 No time restrictions.
2914 \begin_layout Subsubsection
2918 \begin_layout Itemize
2919 Dispatch to: org.jpc.emulator.PC$ResetButton
2922 \begin_layout Itemize
2926 \begin_layout Standard
2930 \begin_layout Subsubsection
2934 \begin_layout Itemize
2935 Dispatch to: org.jpc.emulator.PC$DiskChanger
2938 \begin_layout Itemize
2939 Argument #1: Fixed: "FDA"
2942 \begin_layout Itemize
2943 Argument #2: Number of image slot to put there.
2947 \begin_layout Standard
2948 The disk number MUST be -1 or valid disk number.
2949 -1 MUST NOT be used if there is no disk in floppy drive A.
2950 This event causes specified disk to be placed to FDA or FDA disk to be
2951 ejected with no replacement if disk number is -1.
2952 The specified disk if not -1 must be of floppy type.
2953 The specified disk if valid must not be in any other drive.
2956 \begin_layout Subsubsection
2960 \begin_layout Itemize
2961 Dispatch to: org.jpc.emulator.PC$DiskChanger
2964 \begin_layout Itemize
2965 Argument #1: Fixed: "FDB"
2968 \begin_layout Itemize
2969 Argument #2: Number of image slot to put there.
2973 \begin_layout Standard
2974 The disk number MUST be -1 or valid disk number.
2975 -1 MUST NOT be used if there is no disk in floppy drive B.
2976 This event causes specified disk to be placed to FDB or FDB disk to be
2977 ejected with no replacement if disk number is -1.
2978 The specified disk if not -1 must be of floppy type.
2979 The specified disk if valid must not be in any other drive.
2982 \begin_layout Subsubsection
2986 \begin_layout Itemize
2987 Dispatch to: org.jpc.emulator.PC$DiskChanger
2990 \begin_layout Itemize
2991 Argument #1: Fixed: "CDROM"
2994 \begin_layout Itemize
2995 Argument #2: Number of image slot to put there.
2999 \begin_layout Standard
3000 The disk number MUST be -1 or valid disk number.
3001 -1 MUST NOT be used if there is no disk in CD-ROM.
3002 This event causes specified disk to be placed to CD-ROM or CD-ROM disk
3003 to be ejected with no replacement if disk number is -1.
3004 The specified disk if not -1 must be of CD-ROM type.
3007 \begin_layout Standard
3008 This event has no effect if CD-ROM is locked.
3011 \begin_layout Subsubsection
3012 Write protect floppy:
3015 \begin_layout Itemize
3016 Dispatch to: org.jpc.emulator.PC$DiskChanger
3019 \begin_layout Itemize
3020 Argument #1: Fixed: "WRITEPROTECT"
3023 \begin_layout Itemize
3024 Argument #2: Number of image slot to manipulate
3027 \begin_layout Standard
3028 Write protects specified disk.
3029 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
3032 \begin_layout Subsubsection
3033 Write unprotect floppy:
3036 \begin_layout Itemize
3037 Dispatch to: org.jpc.emulator.PC$DiskChanger
3040 \begin_layout Itemize
3041 Argument #1: Fixed: "WRITEUNPROTECT"
3044 \begin_layout Itemize
3045 Argument #2: Number of image slot to manipulate
3048 \begin_layout Standard
3049 Disables write protection specified disk.
3050 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
3053 \begin_layout Subsection
3057 \begin_layout Standard
3058 Diskinfo sections are named
3059 \begin_inset Quotes eld
3063 \begin_inset Quotes erd
3067 They use line component encoding, fieldtype being first component on each
3068 line (value being the second).
3069 Following fields are defined:
3072 \begin_layout Subsubsection
3076 \begin_layout Standard
3077 Gives type of image.
3081 \begin_layout Itemize
3082 \begin_inset Quotes eld
3086 \begin_inset Quotes erd
3092 \begin_layout Itemize
3093 \begin_inset Quotes eld
3097 \begin_inset Quotes erd
3103 \begin_layout Itemize
3104 \begin_inset Quotes eld
3108 \begin_inset Quotes erd
3114 \begin_layout Itemize
3115 \begin_inset Quotes eld
3119 \begin_inset Quotes erd
3122 (BIOS/VGABIOS image)
3125 \begin_layout Itemize
3126 \begin_inset Quotes eld
3130 \begin_inset Quotes erd
3133 (what the heck is this???)
3136 \begin_layout Subsubsection
3140 \begin_layout Standard
3144 \begin_layout Subsubsection
3148 \begin_layout Standard
3149 (BIOS images only) Gives length of BIOS image
3152 \begin_layout Subsubsection
3156 \begin_layout Standard
3157 MD5 of raw disk/BIOS image without any headers or trailers.
3160 \begin_layout Subsubsection
3164 \begin_layout Standard
3165 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
3168 \begin_layout Subsubsection
3172 \begin_layout Standard
3173 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
3177 \begin_layout Subsubsection
3181 \begin_layout Standard
3182 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
3186 \begin_layout Subsubsection
3190 \begin_layout Standard
3191 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
3195 \begin_layout Subsubsection
3199 \begin_layout Standard
3200 Line from image comment block.
3201 Usually give data about files image has.
3202 May or may not be present (multiple times)
3205 \begin_layout Subsection
3209 \begin_layout Standard
3210 Output info is stored in section
3211 \begin_inset Quotes eld
3215 \begin_inset Quotes erd
3219 Its relatively new, so it might not be present (then the contents have
3220 to be guessed based on modules present).
3221 Each line gives information about one output, first field being the type
3225 \begin_layout Subsubsection
3229 \begin_layout Standard
3230 For video output, there are no parameters so line is just
3231 \begin_inset Quotes eld
3235 \begin_inset Quotes erd
3241 \begin_layout Subsubsection
3245 \begin_layout Standard
3246 For audio output, the only parameter is name of output, so first component
3248 \begin_inset Quotes eld
3252 \begin_inset Quotes erd
3255 and second component is name of audio output.
3258 \begin_layout Subsection
3262 \begin_layout Standard
3263 Actual savestate format is not documented here.
3264 It is close to impossible to comprehend without access to emulator source
3268 \begin_layout Section
3269 Advanced: Making class dumpable
3272 \begin_layout Standard
3273 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
3274 and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
3275 <init>(org.jpc.emulator.SRLoader).
3276 Non-static inner classes can not be dumpable (make them static using tricks
3277 similar to what javac uses).
3280 \begin_layout Standard
3281 If dumped class has dumpable superclass, the first thing dumping function
3282 needs to do is to call dumper function of superclass and first thing loading
3283 constructor needs to do is to call loading constructor of superclass.
3284 If class has no dumpable superclass, dumper doesn't need to do anything
3285 special, while loader needs to call objectCreated(this) on SRLoader object
3286 passed as parameter.
3290 \begin_layout Standard
3291 Following these fixed parts, dump all members that are part of mutable state
3295 \begin_layout Subsection
3296 Member dumping/loading functions
3299 \begin_layout Standard
3300 There is dumping/loading function for following (all functions dumping/loading
3301 reference types can handle null):
3304 \begin_layout Itemize
3305 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
3308 \begin_layout Itemize
3309 byte: SRDumper.dumpByte, SRLoader.loadByte
3312 \begin_layout Itemize
3313 short: SRDumper.dumpShort, SRLoader.loadShort
3316 \begin_layout Itemize
3317 int: SRDumper.dumpInt, SRLoader.loadInt
3320 \begin_layout Itemize
3321 long: SRDumper.dumpLong, SRLoader.loadLong
3324 \begin_layout Itemize
3325 String: SRDumper.dumpString, SRLoader.loadString
3328 \begin_layout Itemize
3329 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
3332 \begin_layout Itemize
3333 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
3336 \begin_layout Itemize
3337 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
3340 \begin_layout Itemize
3341 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
3344 \begin_layout Itemize
3345 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
3348 \begin_layout Itemize
3349 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
3352 \begin_layout Itemize
3353 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
3356 \begin_layout Itemize
3357 special object: SRDumper.specialObject, SRLoader.specialObject
3360 \begin_layout Subsubsection
3364 \begin_layout Itemize
3365 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
3368 \begin_layout Itemize
3369 Special objects are various static objects that don't need to be stored
3370 because they don't have mutable fields.
3373 \begin_layout Itemize
3374 Don't dump fields related to event state feedback.
3377 \begin_layout Itemize
3378 Don't dump temporary flags that are only used while PC is running.
3379 Savestate when PC is running isn't possible anyway.
3382 \begin_layout Itemize
3383 Some connectors dump fields related to connector output, some don't.
3386 \begin_layout Section
3387 Advanced: Writing event targets
3390 \begin_layout Standard
3391 Whereas output connectors are the way output is dispatched, input is dispatched
3393 Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3396 \begin_layout Standard
3397 Event targets also provode methods which then encode events and dispatch
3398 them forward (without doing anything else) to event recorder.
3399 Also, event targets may have methods for obtaining state.
3402 \begin_layout Subsection
3403 Interface org.jpc.emulator.EventDispatchTarget
3406 \begin_layout Standard
3407 Interface that marks class capable of receiving events.
3410 \begin_layout Subsubsection
3411 Method setEventRecorder(EventRecorder)
3414 \begin_layout Standard
3415 Set the event recorder input events are sent to.
3418 \begin_layout Subsubsection
3419 Method startEventCheck()
3422 \begin_layout Standard
3423 Signals target to reset all state related to event checking and state feedback.
3424 This may be called at any time in order to reinitialialize event checking/feedb
3428 \begin_layout Subsubsection
3429 Method doEvent(long, String[], int) throws IOException
3432 \begin_layout Standard
3433 Event dispatch handler.
3434 The first argument is event time, second is parameters and third is what
3436 If target doesn't like the event, throw IOException.
3437 Following types (the integer parameter) are used:
3440 \begin_layout LyX-Code
3441 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3444 \begin_layout LyX-Code
3445 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3446 for reinitialization
3449 \begin_layout LyX-Code
3450 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3453 \begin_layout LyX-Code
3454 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3458 \begin_layout Subsubsection
3459 Method endEventCheock()
3462 \begin_layout Standard
3463 End event reinitialization.
3467 \begin_layout Subsubsection
3468 Method getEventTimeLowBound(long, String[]) throws IOException
3471 \begin_layout Standard
3472 Return the time value that's the earliest possiblity for this event to occur.
3473 Returning any time in past (including -1) causes event to fire as soon
3475 The long parameter gives the current scheduled time for event.
3478 \begin_layout Section
3482 \begin_layout Standard
3483 Modules are various extensions that run inside emulator core.
3484 As such, they affect sync.
3485 Modules must implement interface org.jpc.emulator.HardwareComponent (they
3486 are hardware components) and must be dumpable.
3487 Additionally, they need either constructor <init>() or <init>(String).
3488 The first is if no parameters are passed, the second is for case where
3489 parameters are passed.
3492 \begin_layout Standard
3493 Aside of the constructors, modules need to obey the ordinary conventions
3494 for hardware components.
3495 No code outside modules needs to know that module exists.
3498 \begin_layout Section
3502 \begin_layout Standard
3503 Plugins handle various UI tasks.
3504 They need to implement interface org.jpc.Plugin.
3507 \begin_layout Subsection
3508 Interface org.jpc.pluginsbase.Plugin
3511 \begin_layout Subsubsection
3512 Method systemShutdown()
3515 \begin_layout Standard
3516 Called when emulator shuts down.
3517 Either called in dedicated thread or in thread that called emulatorShutdown().
3518 These handlers should do the bare minimum to get files on disk to consistent
3520 After these calls from all plugins have finished, emulator exits.
3521 Do not try to manipulate UI from these methods, as doing that easily leads
3525 \begin_layout Subsubsection
3526 Method reconnect(PC)
3529 \begin_layout Standard
3530 Gives new PC to connect to.
3531 Null is passed if plugin should disconnect.
3534 \begin_layout Subsubsection
3538 \begin_layout Standard
3539 Called in dedicated thread after plugin is initialized.
3542 \begin_layout Subsubsection
3546 \begin_layout Standard
3547 Called after PC has stopped.
3550 \begin_layout Subsubsection
3554 \begin_layout Standard
3555 Called before PC starts.
3558 \begin_layout Subsubsection
3559 Method notifyArguments(String[])
3562 \begin_layout Standard
3563 Pass arguments from command line.
3566 \begin_layout Subsubsection
3567 Constructor <init>(Plugins)
3570 \begin_layout Standard
3571 This constructor is used to initialize plugins that don't take parameters.
3574 \begin_layout Subsubsection
3575 Constructor <init>(Plugins, String)
3578 \begin_layout Standard
3579 This constructor is used to initialize plugins that take parameters.
3582 \begin_layout Subsection
3583 Class org.jpc.pluginsbase.Plugins
3586 \begin_layout Standard
3587 This class provodes various methods for manipulating plugins.
3590 \begin_layout Subsubsection
3591 Method isShuttingDown()
3594 \begin_layout Standard
3595 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3596 via VM exit, CTRL+C or explicitly.
3597 Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3600 \begin_layout Subsubsection
3601 Method shutdownEmulator()
3604 \begin_layout Standard
3605 Shut down and exit the emulator.
3606 All plugin shutdown functions are called in this thread.
3609 \begin_layout Subsubsection
3610 Method reconnectPC(PC)
3613 \begin_layout Standard
3614 Signal reconnectPC event to all plugins.
3617 \begin_layout Subsubsection
3621 \begin_layout Standard
3622 Signal pcStarting() event to all plugins.
3625 \begin_layout Subsubsection
3629 \begin_layout Standard
3630 Signal pcStopping() event to all plugins.
3633 \begin_layout Section
3634 Inter-plugin communication
3637 \begin_layout Subsection
3638 Receiving communications
3641 \begin_layout Standard
3642 To receive invocation/call by name 'foo-bar', declare public method named
3644 Arguments to this method can currently be String, Integer (int) or Long
3646 Last argument may be array over these types to get variable number of arguments.
3647 On call, each argument gets value from call.
3648 If last argument is array, it gets all overflowing arguments.
3649 If return type is void or method returns boolean false, call is assumed
3651 If return value is boolean true, it is assumed that there is more processing.
3654 \begin_layout Subsection
3655 void org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd, Object[]
3659 \begin_layout Standard
3660 Invoke command asynchronously, broadcasting to all plugins.
3661 Does not wait for slow commands to complete.
3662 cmd is the name to send and args are the arguments to pass.
3665 \begin_layout Subsection
3666 void org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String cmd,
3670 \begin_layout Standard
3671 Same as invokeExternalCommand, but waits for slow commands to complete.
3674 \begin_layout Subsection
3675 Object[] org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String cmd,
3679 \begin_layout Standard
3680 Similar to invokeExternalCommandSynchornous, but:
3683 \begin_layout Itemize
3684 Quits calling more plugins when it gets successful reply.
3687 \begin_layout Itemize
3691 \begin_layout Subsection
3692 void org.jpc.pluginsbase.Plugins.returnValue(Object...
3696 \begin_layout Standard
3697 Gives return value to return from call and signals that command has completed.
3700 \begin_layout Subsection
3701 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
3704 \begin_layout Standard
3705 Signals that command has completed.
3706 Only needed if there is no return value and eci_ method returned false
3710 \begin_layout Section
3711 Lua kernel programming
3714 \begin_layout Standard
3715 At startup, kernel gets its arguments in 'args' table and the script name
3716 to run in 'scriptname' string.
3717 It should enter the named script in protected mode.
3720 \begin_layout Standard
3721 The Lua VM exports numerious callbacks to kernel.
3722 The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3725 \begin_layout Itemize
3726 Always grab any functions used into local variables so nobody can mess with
3730 \begin_layout Itemize
3731 Don't use global variables in kernel (except for those passed).