1 #LyX 1.6.5 created this file. For more info see http://www.lyx.org/
6 \use_default_options true
11 \font_typewriter default
12 \font_default_family default
19 \paperfontsize default
28 \paperorientation portrait
38 \paragraph_separation indent
40 \quotes_language english
43 \paperpagestyle default
44 \tracking_changes false
60 \begin_layout Standard
61 JPC-RR is licenced under GNU GPL v2.
63 \begin_inset Quotes eld
67 \begin_inset Quotes erd
77 \begin_layout Subsection
81 \begin_layout Standard
82 To get started, you need BIOS image, VGABIOS image and DOS boot floppy and
83 JDK for Java 6 standard edition (later versions should they appear should
85 Note: JRE is not enough.
89 \begin_layout Standard
90 Note that to play back recorded movies, you need exact same version of BIOS
91 image, VGABIOS image and DOS boot floppy as was used when making the movie
92 (in addition to exact same versions of other needed media).
95 \begin_layout Standard
97 The stuff in streamtools is only needed for recording videos.
100 \begin_layout Subsection
104 \begin_layout Standard
106 The streamtools stuff is only needed for dumping videos.
109 \begin_layout Subsection
113 \begin_layout Standard
114 First you need to get and make some important images.
115 Obtain BIOS image, VGABIOS image and DOS boot floppy from somewhere.
116 After starting the emulator, use File -> Import Image to import the images
117 (ignore the error about no BIOS images being found).
120 \begin_layout Subsection
124 \begin_layout Standard
125 There is premade autoexec script called assemble.bat that has fairly reasonable
130 \begin_layout LyX-Code
131 java JPCApplication -library library -autoexec assemble.bat
134 \begin_layout Standard
136 \begin_inset Quotes eld
140 \begin_inset Quotes erd
143 specifies that contents of directory 'library' are to be used as library.
144 The script pops up settings for new emulated PC (if you want to load savestate,
146 Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
147 selected), DOSfloppy for fda (boot device should be set to fda) and game
148 image as some HD drive
151 \begin_layout Subsection
155 \begin_layout Itemize
156 Putting the game as hdd causes boot to be bit faster.
159 \begin_layout Itemize
160 Some BIOS versions have
161 \begin_inset Quotes eld
164 press F12 to select boot device
165 \begin_inset Quotes erd
169 Hit <enter> from emulated keyboard and that prompt will go away in about
170 half emulated second (it stays several emulated seconds otherwise).
174 \begin_layout Itemize
175 If game doesn't need lots of memory, hitting F5 to skip intialization files
177 If it does need more memory, run config.sys commands but not autoexec.bat.
181 \begin_layout Itemize
182 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
186 \begin_layout Section
187 Making JPC-RR format images from raw images
190 \begin_layout Standard
191 Due to various factors, JPC-RR can't use raw image files directly but requires
192 its own image format.
196 \begin_layout Subsection
197 Importing images from GUI:
200 \begin_layout Standard
201 Use File -> Import Image to import existing directories or image files.
202 Dialog prompting parameters will be displayed.
203 When importing floppy images, check
204 \begin_inset Quotes eld
208 \begin_inset Quotes erd
211 if possible, that enables geometry autodetection, which is reasonable virtually
212 all of the time it is offered.
215 \begin_layout Subsection
219 \begin_layout Itemize
220 If making image from directory, the names of the files must conform to FAT
221 naming restrictions (8+3 character names, no spaces, etc).
222 Avoid filenames with non-ASCII characters.
226 \begin_layout Itemize
227 The DOS limit of 112 or 224 files for floppies does not apply to images
228 created from directory trees.
229 The minimum limit value used is 512.
230 If even that isn't enough, the limit is automatically increased to fit
231 all the needed directory entries.
234 \begin_layout Itemize
235 Making boot disks from tree does NOT work.
236 Even if you got system boot files there, it still won't work.
239 \begin_layout Itemize
240 Only floppy disks and hard drives can be made from directory trees.
241 BIOS images and CDROM images require image file.
244 \begin_layout Itemize
245 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
246 Disks with over 63 sectors per track don't work with DOS.
247 Wheither disks with over 127 tracks per side work with DOS is unknown.
248 Also avoid 1024-tracks per side HDDs.
251 \begin_layout Itemize
252 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
254 1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
255 1-16 sides for HDD, 1 or 2 sides for floppy.
256 This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
257 and 516096KiB for HDDs.
260 \begin_layout Itemize
261 There are multiple image file contents that represent the same image.
262 The one with smallest size is picked when creating image.
265 \begin_layout Itemize
266 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
270 \begin_layout Subsection
271 Importing from command line
274 \begin_layout Standard
275 There is tool called ImageMaker that can make JPC-RR images from raw images.
276 Each image has format, ID an name.
277 Format and name are specified when making image.
278 ID is automatically calculated from format and contents.
279 Name does not affect the ID but is purely for convience so one doesn't
280 have to specify long image IDs manually.
283 \begin_layout Subsubsection
287 \begin_layout Standard
288 The syntax for ImageMaker when making images is:
291 \begin_layout LyX-Code
292 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
295 \begin_layout Standard
296 <destination> is file name for JPC-RR format image to write.
297 <source> is either name of regular file (raw image file) or name of directory
298 tree with files (supported for making floppy or hard disk images only).
299 In case of directory tree, the files are layout deterministically to disk,
300 so the ID will always be the same for given geometry and type.
301 <name> is name to give to disk.
305 \begin_layout LyX-Code
306 --BIOS BIOS image (note: VGABIOS is also of this type).
309 \begin_layout LyX-Code
310 --CDROM CD-ROM image.
313 \begin_layout LyX-Code
314 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
317 \begin_layout LyX-Code
318 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
321 \begin_layout LyX-Code
322 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
325 \begin_layout LyX-Code
326 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
329 \begin_layout LyX-Code
330 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
333 \begin_layout LyX-Code
334 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
337 \begin_layout LyX-Code
338 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
341 \begin_layout LyX-Code
342 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
345 \begin_layout LyX-Code
346 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
349 \begin_layout LyX-Code
350 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
353 \begin_layout LyX-Code
354 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
357 \begin_layout LyX-Code
358 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
361 \begin_layout LyX-Code
362 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
365 \begin_layout LyX-Code
366 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
369 \begin_layout LyX-Code
370 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
373 \begin_layout LyX-Code
374 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
377 \begin_layout LyX-Code
378 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
381 \begin_layout LyX-Code
382 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
385 \begin_layout LyX-Code
386 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
389 \begin_layout LyX-Code
390 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
393 \begin_layout LyX-Code
394 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
397 \begin_layout LyX-Code
398 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
401 \begin_layout LyX-Code
402 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
405 \begin_layout LyX-Code
406 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
409 \begin_layout LyX-Code
410 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
413 \begin_layout LyX-Code
414 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
417 \begin_layout LyX-Code
418 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
421 \begin_layout LyX-Code
422 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
425 \begin_layout LyX-Code
426 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
429 \begin_layout LyX-Code
430 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
433 \begin_layout LyX-Code
434 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
437 \begin_layout Subsubsection
441 \begin_layout LyX-Code
442 --volumelabel=label Give specified volume label (affects ID).
443 Only meaningful when making image out of directory tree.
444 Default is no volume label.
447 \begin_layout LyX-Code
448 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
449 Only meaningful when making image out of directory tree.
450 The default timestamp is 19900101T000000Z.
453 \begin_layout Subsubsection
457 \begin_layout Standard
461 \begin_layout LyX-Code
462 $ java ImageMaker <imagefile>
465 \begin_layout Standard
466 Variety of information about image is displayed (especially for floppies/HDDs).
467 Two important fields are calculated and claimed disk ID.
468 They should be the same.
469 If they are not, then the image file is corrupt (sadly, imagemaker has
470 bugs and bugs that cause it to write corrupt images have been seen).
473 \begin_layout Subsection
474 Advanced: The disk ID algorithm
477 \begin_layout Standard
478 The disk ID is calculated as:
481 \begin_layout LyX-Code
482 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
485 \begin_layout Standard
486 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
487 state and 128-bit output using the deprecated rotation constants (as specified
488 in Skein hash function reference documentation versions 1.0 and 1.1).
489 The <image> is the whole image, including parts not stored in image file.
490 The reason for keeping using the deprecated constants are:
493 \begin_layout Itemize
494 Changing the constants would change the IDs, which would invalidate existing
498 \begin_layout Itemize
499 This is not about cryptographic security
502 \begin_layout Itemize
503 The new constants don't improve security that much anyway.
506 \begin_layout Subsubsection
510 \begin_layout Standard
511 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
512 <geometry> is as follows (this is exactly the same form as it appears in
516 \begin_layout LyX-Code
517 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
520 \begin_layout LyX-Code
521 Byte 0 bits 2-5: Head count - 1.
524 \begin_layout LyX-Code
525 Byte 0 bits 6-7: Reserved, must be 0.
528 \begin_layout LyX-Code
529 Byte 1: Bits 0-7 of track count per side - 1.
532 \begin_layout LyX-Code
533 Byte 2: Sector count per track - 1.
536 \begin_layout Subsubsection
537 CD-ROM and BIOS images
540 \begin_layout Standard
541 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
546 \begin_layout Subsection
547 Advanced: Disk Image format
550 \begin_layout Standard
551 The disk image consists of following parts:
554 \begin_layout Itemize
558 \begin_layout Itemize
562 \begin_layout Itemize
566 \begin_layout Itemize
570 \begin_layout Itemize
574 \begin_layout Itemize
575 type-specific geometry/size data
578 \begin_layout Itemize
582 \begin_layout Subsubsection
586 \begin_layout Standard
587 Magic in disk image files is following 5 bytes:
588 \begin_inset Quotes eld
592 \begin_inset Quotes erd
598 \begin_layout Subsubsection
602 \begin_layout Standard
603 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
606 \begin_layout Subsubsection
610 \begin_layout Standard
611 Type code is single byte.
612 0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
613 Other values are reserved.
616 \begin_layout Subsubsection
620 \begin_layout Standard
621 Disk comment length is given as two-byte big-endian value.
622 New images should have 0 here.
625 \begin_layout Subsubsection
629 \begin_layout Standard
631 Comment field is there for backward compatiblity.
632 Comment length gives length of this field in bytes.
635 \begin_layout Subsubsection
636 Type-specific geometry/size data (floppies and HDDs)
639 \begin_layout Standard
640 Floppies and HDDs have 3-byte geometry data:
643 \begin_layout LyX-Code
644 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
647 \begin_layout LyX-Code
648 Byte 0 bits 2-5: Head count - 1.
651 \begin_layout LyX-Code
652 Byte 0 bits 6-7: Reserved, must be 0.
655 \begin_layout LyX-Code
656 Byte 1: Bits 0-7 of track count per side - 1.
659 \begin_layout LyX-Code
660 Byte 2: Sector count per track - 1.
663 \begin_layout Subsubsection
664 Type specific-geometry/size data (CD-ROMs)
667 \begin_layout Standard
668 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
671 \begin_layout Subsubsection
672 Type specific-geometry/size data (BIOS images)
675 \begin_layout Standard
676 BIOS images have 4-byte big-endian byte (not sector or block) count.
679 \begin_layout Subsubsection
680 Actual image data (floppy/HDD)
683 \begin_layout Standard
684 Floppy or HDD imagedata consists of following subparts:
687 \begin_layout Itemize
691 \begin_layout Itemize
695 \begin_layout Itemize
699 \begin_layout Itemize
703 \begin_layout Standard
704 Storage method is single byte.
705 Sectors present gives number of last nonzero sector + 1 (zero if image
709 \begin_layout Subsubsection
710 Floppy/HDD storage method 0: Raw storage
713 \begin_layout Standard
714 This storage method has empty header.
715 Image data is raw dump of first sectors present sectors.
718 \begin_layout Subsubsection
719 Floppy/HDD storage method 1: Sectormap
722 \begin_layout Standard
723 Image data header contains bitfield with just enough bytes to have one bit
725 The order of bits is such that number of bit corresponding to each sector
726 in byte is sector number modulo 8 and byte number is floor of sector number
727 divided by 8 when sector numbers are counted from zero.
728 If bit corresponding to sector is set, then the sector is present in image
729 data, otherwise it is absent and assumed to be all-zeroes.
732 \begin_layout Standard
733 Image data contains dumps of all present sectors in order of increasing
737 \begin_layout Subsubsection
738 Floppy/HDD storage method 2: Extent first sector zero
741 \begin_layout Standard
742 Image data is empty as storage-specific data is mangled with image data.
743 The image data alternates between blocks encoding zero sectors and blocks
744 encoding nonzero sectors.
745 The first block encodes zero sectors.
749 \begin_layout Standard
750 Block encoding zero sectors consist of single 1-4 byte little-endian value
751 encoding number of sectors in block - 1.
752 Number of bytes is determined by sectors present value.
753 It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
754 for more than 16777216.
755 All sectors in block are filled with zeroes and are not stored.
758 \begin_layout Standard
759 Block encoding nonzero sectors has same block count as zero sector block
760 but is followed by the sectors stored raw.
763 \begin_layout Subsubsection
764 Floppy/HDD storage method 3: Extent first sector nonzero
767 \begin_layout Standard
768 Same as storage method 2 but first block is nonzero sector block.
771 \begin_layout Subsubsection
772 Actual image data (CD-ROMs and BIOS images)
775 \begin_layout Standard
776 These store image data raw.
777 The amount of data is specified by sector/byte count.
780 \begin_layout Section
784 \begin_layout Subsection
785 org.jpc.utils.RAWToPNG
788 \begin_layout Standard
792 \begin_layout LyX-Code
793 $ java org.jpc.utils.RAWToPNG <input> <outputprefix>
796 \begin_layout Standard
797 Reads RAW video data from <input> (may be named pipe) and dumps PNG frames
798 received as '<outputprefix><runningcount>.png'.
799 Also saves '<outputprefix>.timing' which contains frame timing data (each
800 line consists of time in nanoseconds, space, and filename).
803 \begin_layout Section
807 \begin_layout Standard
808 The actual emulator is invoked as:
811 \begin_layout LyX-Code
812 $ java JPCApplication <options>...
815 \begin_layout Standard
816 The valid options are:
819 \begin_layout LyX-Code
820 -library <library> Use the specified directory when searching for images
821 (can only be specified once).
824 \begin_layout LyX-Code
825 -autoexec <script> Execute contents of specified file as commands when starting
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 Standard
855 When one gets command line, its useful to load some plugins.
856 See section about plugins.
857 Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
858 like to start PC immediately.
861 \begin_layout Subsection
862 PC settings dialog notes
865 \begin_layout Itemize
866 CPU divider base frequency before division is 1GHz.
869 \begin_layout Itemize
870 Images can be specified by name or by ID.
871 Name is relative to library directory.
872 If the image is in subdirectory of image directory, the directory separator
873 is is '/' regardless of what the host OS uses.
876 \begin_layout Itemize
877 CD-ROM and hdc are mutually exclusive
880 \begin_layout Itemize
881 Modules is comma-seperated list of modules to load.
882 To pass arguments to some modules, enclose the arguments in ().
883 Same module can be specified twice only if parameters differ.
886 \begin_layout Itemize
887 FPU emulator is specified by class name.
888 If core has built-in FPU emulator, then this should be left blank.
889 Without core-builtin FPU emulator, blank value means
890 \begin_inset Quotes eld
894 \begin_inset Quotes erd
900 \begin_layout Itemize
901 Setting boot device doesn't work with some BIOS versions.
902 Those versions prompt the boot device anyway.
905 \begin_layout Subsection
906 Audio output channels
909 \begin_layout Standard
910 PC can have one or more audio output channels.
911 The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
913 Modules that have audio outputs get channel names of form <classname>-<sequenti
914 al>, where <classname> is name of main module class and sequential is number
916 Note that same module can have multiple output channels.
917 If multiple modules of same class request audio outputs, the <sequential>
918 values of subsequent module start where previous left off.
921 \begin_layout Subsection
925 \begin_layout Standard
926 Plugins actually execute the tasks of the emulator.
927 They can be loaded using
928 \begin_inset Quotes eld
932 \begin_inset Quotes erd
935 or 'load <plugin>(<arguments>)
936 \begin_inset Quotes erd
942 \begin_layout Standard
943 Different Plugins using the same output (like running PCMonitor and PNGDumper)
944 should not conflict because connector output hold locking is desinged to
945 handle multiple readers.
948 \begin_layout Standard
949 If no plugin used requires GUI, then the emulator can be run without having
953 \begin_layout Subsubsection
954 plugin: org.jpc.plugins.PCControl
957 \begin_layout Standard
958 No arguments, requires and uses GUI.
961 \begin_layout Standard
962 Runs the PC emulator core.
963 Has capability to start/stop emulation, breakpoint after certain time or
964 start/end of VGA vertical retrace.
965 Also can create, savestate and loadstate PC emulation.
966 Memory dumping is supported.
970 \begin_layout Subsubsection
971 plugin: org.jpc.plugins.PCRunner
974 \begin_layout Standard
975 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
979 \begin_layout Standard
980 Loads PC from savestate and just runs it.
982 Also automatically quits once stoptime is reached.
985 \begin_layout Subsubsection
986 plugin: org.jpc.plugins.PCMonitor
989 \begin_layout Standard
990 No arguments, requires and uses GUI.
993 \begin_layout Standard
994 VGA monitor for emulated PC.
997 \begin_layout Subsubsection
998 plugin: org.jpc.plugins.VirtualKeyboard
1001 \begin_layout Standard
1002 No arguments, requires and uses GUI.
1005 \begin_layout Standard
1006 On-screen keyboard for emulated PC.
1009 \begin_layout Subsubsection
1010 plugin: org.jpc.plugins.PCStartStopTest
1013 \begin_layout Standard
1014 No arguments, requires and uses GUI.
1017 \begin_layout Standard
1018 Small plugin testing remote PC start/stop.
1019 Also supports sending some common keypresses.
1022 \begin_layout Subsubsection
1023 plugin: org.jpc.plugins.RAWVideoDumper
1026 \begin_layout Standard
1027 Takes 'rawoutput=<file>' as argument.
1028 Does not require nor use GUI.
1031 \begin_layout Standard
1032 Dumps all generated frames to RAW file <file>.
1033 Rawoutput is required.
1034 The raw file consists of concatenation of zlib streams.
1035 The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1036 each acting as time offset of 2^32-1 nanoseconds and saved frames.
1037 The saved frame has time offset in nanoseconds (big endian) as first four
1038 bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1039 The next two bytes are big-endian width, next two big-endian height.
1040 Finally frame has 4 * width * height bytes of data that encodes pixels
1041 using 4 bytes per pixel, in left-to-right, up-to-down order.
1042 Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1043 green channel and byte 3 is blue channel.
1046 \begin_layout Standard
1047 Dumping to pipe is supported.
1050 \begin_layout Subsubsection
1051 plugin: org.jpc.plugins.RAWAudioDumper
1054 \begin_layout Standard
1055 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1056 'offset=<offset>' as arguments, separated by ','.
1057 Does not require nor use GUI.
1060 \begin_layout Standard
1061 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1062 file (file, mandatory).
1063 The resulting file consists of records, 4 or 8 bytes each.
1064 4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1066 \begin_inset Formula $2^{32}-1$
1070 Otherwise record is 8 bytes.
1071 Each 8 byte record has three fields.
1072 First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1074 \begin_inset Formula $2^{32}-1$
1077 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1078 big endian new right channel volume.
1079 Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1083 \begin_layout Subsubsection
1084 plugin: org.jpc.plugins.LuaPlugin
1087 \begin_layout Standard
1088 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1089 kernel, requires and uses GUI.
1092 \begin_layout Standard
1093 Lua VM for executing scripts.
1096 \begin_layout Section
1100 \begin_layout Subsection
1101 org.jpc.modules.Joystick:
1104 \begin_layout Itemize
1108 \begin_layout Itemize
1109 Resources: I/O port 0x201
1112 \begin_layout Standard
1113 Emulates joystick game port.
1116 \begin_layout Subsection
1117 org.jpc.modules.BasicFPU:
1120 \begin_layout Itemize
1124 \begin_layout Itemize
1128 \begin_layout Standard
1129 Crude FPU (x87) emulator.
1132 \begin_layout Section
1136 \begin_layout Standard
1137 Hacks are saved to savestates but not movies.
1140 \begin_layout Subsection
1144 \begin_layout Standard
1145 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1147 BIOS assumes system has FPU but some games use that bit to detect FPU,
1148 trying to use it if it is
1149 \begin_inset Quotes eld
1153 \begin_inset Quotes erd
1157 Try this if game startup hangs with lots of trying to use FPU but not present
1159 Don't use if there is FPU present.
1160 Needed to get games like Blake Stone to work (FPU emulator allows it to
1161 start but causes graphical glitches).
1164 \begin_layout Subsection
1168 \begin_layout Standard
1169 Update basic VGA parameters before vretrace, not after it.
1171 Commander Keen 4) don't like if this isn't done and some games (e.g.
1172 Mario & Luigi) don't like if it is done.
1173 Wrong value manifests as jerky scrolling (scrolling back and forth and
1174 fixed statusbars move).
1177 \begin_layout Section
1178 Some error messages and explanations
1181 \begin_layout Itemize
1182 <filename> is Not a valid image file
1185 \begin_layout Itemize
1186 <filename> is not image file
1189 \begin_layout Itemize
1190 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1194 \begin_layout Itemize
1195 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1199 \begin_layout Itemize
1200 Can't read disk image sector map.
1203 \begin_layout Itemize
1204 Can't read disk image extent.
1207 \begin_layout Standard
1208 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1209 image at all or its corrupt.
1212 \begin_layout Itemize
1213 <filename> is image of unknown type.
1216 \begin_layout Itemize
1217 <filename> has unrecognized geometry <x> <y> <z>
1220 \begin_layout Standard
1221 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1222 containing something current version can't comprehend.
1225 \begin_layout Itemize
1226 Invalid format specifier <something>.
1229 \begin_layout Itemize
1230 Invalid syntax of --floppy= or --HDD= option.
1233 \begin_layout Itemize
1234 Invalid format specifier/option <something>.
1237 \begin_layout Standard
1238 Invalid option or format specifier was given.
1242 \begin_layout Itemize
1243 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1246 \begin_layout Standard
1247 Check syntax of command.
1248 Especially that diskname is present!
1251 \begin_layout Itemize
1252 The image has <nnn> sectors while it should have <yyy> according to selected
1256 \begin_layout Itemize
1257 Raw image file length not divisible by 512.
1260 \begin_layout Itemize
1261 Trying to read sector out of range.
1264 \begin_layout Standard
1265 The selected geometry is wrong or raw image is incomplete.
1268 \begin_layout Itemize
1269 Invalid disk name (Should not happen!).
1272 \begin_layout Itemize
1273 Invalid geometry to be written.
1276 \begin_layout Standard
1277 This is a very likely a bug in program.
1280 \begin_layout Itemize
1281 What the heck <filename> is? It's not regular file nor directory.
1284 \begin_layout Standard
1285 That sort of file can't be used as input for image making, or the file just
1289 \begin_layout Itemize
1290 BIOS images can only be made out of regular files.
1293 \begin_layout Itemize
1294 CD images can only be made out of regular files.
1297 \begin_layout Standard
1298 Source image specified is not regular file, but image of that type can't
1299 be made of anything else.
1302 \begin_layout Itemize
1303 Can't read raw bios image file.
1306 \begin_layout Itemize
1307 Can't read sector <nnn> from image.
1310 \begin_layout Standard
1311 Reading the raw image file failed for some reason.
1314 \begin_layout Itemize
1315 Bad library line: "<something>".
1319 \begin_layout Standard
1320 Syntax error in image library.
1323 \begin_layout Itemize
1324 Removing image <something> a.k.a.
1325 "<something>" as it no longer exists.
1328 \begin_layout Standard
1329 The image file no longer exists so it gets removed from library.
1332 \begin_layout Itemize
1333 Removing image <something> a.k.a.
1334 "<something>" due to <some> conflict.
1337 \begin_layout Standard
1338 Image library code killed some image from library due to some kind of conflict
1339 with image being added.
1342 \begin_layout Itemize
1343 Too much data to fit into given space.
1346 \begin_layout Standard
1347 The tree you gave contains takes just too much space to fit into disk of
1351 \begin_layout Section
1352 Advanced: Savestate/movie format
1355 \begin_layout Subsection
1356 Special character classes
1359 \begin_layout Subsubsection
1363 \begin_layout Standard
1364 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1368 \begin_layout Itemize
1369 Codepoints 0x20, and 0x09.
1372 \begin_layout Itemize
1373 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1376 \begin_layout Itemize
1377 Codepoints 0x2000-0x200A.
1380 \begin_layout Subsubsection
1384 \begin_layout Standard
1385 Following byte sequences are interpretted as linefeeds (line change):
1388 \begin_layout Itemize
1392 \begin_layout Itemize
1396 \begin_layout Itemize
1397 Bytes 0x0D 0x0A (interpretted as single line change, not two!)
1400 \begin_layout Itemize
1401 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL)
1404 \begin_layout Subsection
1408 \begin_layout Standard
1409 JRSR archive format packs multiple text archive members to text archive.
1410 It does not support binary members.
1411 JRSR archives have first five or six bytes form the magic.
1413 \begin_inset Quotes eld
1417 \begin_inset Quotes erd
1420 followed by LINEFEED character There are four kinds of lines after that
1421 (lines are terminated by LINEFEED byte/bytes):
1424 \begin_layout Itemize
1428 \begin_layout Itemize
1432 \begin_layout Itemize
1436 \begin_layout Itemize
1440 \begin_layout Standard
1441 Sequencing rules are as follows: Start member is allowed anywhere (after
1443 Member line is allowed only inside member (member started but not ended).
1444 End member is only allowed inside member.
1445 End of file is only allowed outside member.
1446 Blank line is allowed anywhere after magic.
1449 \begin_layout Subsubsection
1453 \begin_layout Standard
1454 Start member line is given as
1455 \begin_inset Quotes eld
1459 \begin_inset Quotes erd
1462 <SPACE>+ <membername> <LINEFEED>.
1463 <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1465 The member name is UTF-8 encoded and maximum allowed line length is 2048
1466 bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1467 depending on characters used).
1468 Starting member inside another implicitly ends the previous member.
1471 \begin_layout Subsubsection
1475 \begin_layout Standard
1476 Member line is given as
1477 \begin_inset Quotes eld
1481 \begin_inset Quotes erd
1484 <content><LINEFEED>.
1485 It gives another line for member contents.
1486 <content> is passed raw to layers above (followed by line termination)
1489 \begin_layout Subsubsection
1493 \begin_layout Standard
1494 End member line is given as
1495 \begin_inset Quotes eld
1499 \begin_inset Quotes erd
1503 It ends the current member.
1504 The following line can only be start member line or file may end.
1507 \begin_layout Subsubsection
1511 \begin_layout Standard
1512 Blank line is given as <LINEFEED>.
1513 Lines like that are ignored.
1516 \begin_layout Subsection
1517 Four-to-Five encoding
1520 \begin_layout Standard
1521 Binary members are encoded into text by so-called four-to-five encoding.
1522 This encoding can encode single byte to two, two bytes to three, three
1523 bytes to four and four bytes to five.
1524 Four-to-five encoding has five kinds of blocks.
1525 All SPACE and LINEFEED characters are completely ignored, even in middle
1529 \begin_layout Subsubsection
1533 \begin_layout Standard
1534 End stream block is encoded as '!'.
1535 It ends the stream instantly.
1536 There is also implicit end of stream at end of input to decoding.
1539 \begin_layout Subsubsection
1540 Other four block types
1543 \begin_layout Standard
1544 Other four block types take the value to be encoded, read it as big-endian
1546 Then they write it as base-93 big-endian value.
1547 Then length specific constants are added to digits of that number to yield
1548 ASCII values for characters (those are stored in order):
1551 \begin_layout Standard
1552 \begin_inset Tabular
1553 <lyxtabular version="3" rows="5" columns="6">
1555 <column alignment="center" valignment="top" width="0">
1556 <column alignment="center" valignment="top" width="0">
1557 <column alignment="center" valignment="top" width="0">
1558 <column alignment="center" valignment="top" width="0">
1559 <column alignment="center" valignment="top" width="0">
1560 <column alignment="center" valignment="top" width="0">
1562 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1565 \begin_layout Plain Layout
1571 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1574 \begin_layout Plain Layout
1580 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1583 \begin_layout Plain Layout
1589 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1592 \begin_layout Plain Layout
1598 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1601 \begin_layout Plain Layout
1607 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1610 \begin_layout Plain Layout
1618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1621 \begin_layout Plain Layout
1627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1630 \begin_layout Plain Layout
1636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1639 \begin_layout Plain Layout
1645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1648 \begin_layout Plain Layout
1654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1657 \begin_layout Plain Layout
1663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1666 \begin_layout Plain Layout
1674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1677 \begin_layout Plain Layout
1683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1686 \begin_layout Plain Layout
1692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1695 \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" rightline="true" usebox="none">
1722 \begin_layout Plain Layout
1730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1733 \begin_layout Plain Layout
1739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1742 \begin_layout Plain Layout
1748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1751 \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" rightline="true" usebox="none">
1778 \begin_layout Plain Layout
1786 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1789 \begin_layout Plain Layout
1795 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1798 \begin_layout Plain Layout
1804 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1807 \begin_layout Plain Layout
1813 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1816 \begin_layout Plain Layout
1822 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1825 \begin_layout Plain Layout
1831 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1834 \begin_layout Plain Layout
1848 \begin_layout Standard
1849 Blocks which encode values greater than what is possible for value of that
1850 length are fatal errors.
1854 \begin_layout Subsection
1855 Line component encoing
1858 \begin_layout Standard
1859 Line component encoding sits on top of UTF-8 encoding.
1860 Line component encoding encodes non-empty 1-D array of non-empty strings
1861 into line, and thus array of those into member.
1862 Empty lines or lines that don't contain any components are ignored.
1863 Line starts with depth value of 0 and must end with depth value of zero.
1866 \begin_layout Standard
1867 Components are seperated by component separators.
1868 Empty components are ignored.
1869 Following codepoints are separators on depth 0 if not escaped:
1872 \begin_layout Itemize
1874 The depth is read pre-increment.
1877 \begin_layout Itemize
1879 The depth is read post-decrement.
1882 \begin_layout Itemize
1886 \begin_layout Standard
1887 The following characters are special:
1890 \begin_layout Itemize
1892 Increments depth by 1 if not escaped (and appears in component).
1895 \begin_layout Itemize
1897 Decrements depth by 1 if not escaped (and appears in component).
1898 Depth going negative is an error.
1901 \begin_layout Itemize
1905 Next character is interpretted as literal.
1906 Error if at end of line.
1909 \begin_layout Standard
1910 Otherwise, characters are interpretted as literals and appear in components.
1911 Depth must be zero at end of line.
1914 \begin_layout Subsection
1918 \begin_layout Standard
1919 Header section is in archive member "header".
1920 It uses line component encoding.
1921 The first component of each line is name of header, and subsequent ones
1923 How many parameters are expected is dependent on what header it is:
1926 \begin_layout Subsubsection
1930 \begin_layout Itemize
1931 Header name: "PROJECTID"
1934 \begin_layout Itemize
1938 \begin_layout Itemize
1939 Argument #1: <project-id-string>
1942 \begin_layout Itemize
1946 \begin_layout Standard
1948 Project ID is generated when PC is assembled and is then preserved in save
1950 It is used for computing rerecord counts.
1951 Emulator treats it as opaque string, the IDs it generates are formed by
1952 48 random hexadecimal digits.
1955 \begin_layout Subsubsection
1959 \begin_layout Itemize
1960 Header name: "SAVESTATEID"
1963 \begin_layout Itemize
1967 \begin_layout Itemize
1968 Argument #1: <savestate-id-string>
1971 \begin_layout Itemize
1975 \begin_layout Standard
1976 Gives save state ID.
1977 Each save state has its own save state ID.
1978 Treated as opaque string, but generated as 48 random hexadecimal digits.
1979 The presence of this header signals whether there is save state to be loaded.
1980 If this header is present, save state load will be attempted.
1981 If absent, save state is not to be loaded even if present (and correct
1982 savestate load would be technically impossible anyway).
1985 \begin_layout Standard
1986 The value is used to prevent loading incompatible save states in preserve
1987 event stream mode and also to find the point in event stream where one
1991 \begin_layout Subsubsection
1995 \begin_layout Itemize
1996 Header name: "RERECORDS"
1999 \begin_layout Itemize
2003 \begin_layout Itemize
2004 Argument #1: <rerecords>
2007 \begin_layout Itemize
2011 \begin_layout Standard
2012 Gives rerecord count.
2013 PC assembly (except when loading save state) initializes current rerecord
2015 Must be non-negative and decimal number using ASCII digit characters.
2018 \begin_layout LyX-Code
2019 On loading save state:
2022 \begin_layout LyX-Code
2023 1) If project ID matches with previous:
2026 \begin_layout LyX-Code
2027 1a) If loaded rerecord count is larger or equal to current rerecord count:
2030 \begin_layout LyX-Code
2031 1a-a) Current rerecord count is loaded rerecord count + 1.
2034 \begin_layout LyX-Code
2038 \begin_layout LyX-Code
2039 1b-a) Current rerecord count increments by 1.
2042 \begin_layout LyX-Code
2046 \begin_layout LyX-Code
2047 2a) Current rerecord count is loaded rerecord count + 1.
2050 \begin_layout Standard
2051 The current rerecord count at time of save is saved to save state.
2054 \begin_layout Subsubsection
2058 \begin_layout Itemize
2059 Header name: "AUTHORS"
2062 \begin_layout Itemize
2063 Components: 2 or more
2066 \begin_layout Itemize
2067 Arguments: free form
2070 \begin_layout Itemize
2074 \begin_layout Standard
2075 Gives authors of run.
2076 Each argument gives one author.
2077 May be present multiple times.
2080 \begin_layout Subsubsection
2084 \begin_layout Itemize
2085 Header name: "COMMENT"
2088 \begin_layout Itemize
2089 Components: 2 or more
2092 \begin_layout Itemize
2093 Arguments: free form
2096 \begin_layout Itemize
2100 \begin_layout Standard
2101 Various kinds of free form data.
2102 Not parsed further by emulator.
2105 \begin_layout Subsection
2106 Initialization segment:
2109 \begin_layout Standard
2110 If SAVESTATEID header isn't present (not a save state), member "initialization"
2111 gives PC initialization parameters for assembling the PC.
2112 It is present anyway even if SAVESTATEID is present (savestate).
2115 \begin_layout Standard
2116 Following parameters are used (space separates components):
2119 \begin_layout LyX-Code
2123 \begin_layout Standard
2124 Gives Image ID of main system BIOS (mandatory)
2127 \begin_layout LyX-Code
2131 \begin_layout Standard
2132 Gives Image ID of VGA BIOS (mandatory).
2135 \begin_layout LyX-Code
2139 \begin_layout Standard
2140 Gives Image ID of hda.
2141 Present only if system has hard disk hda.
2144 \begin_layout LyX-Code
2148 \begin_layout Standard
2149 Gives Image ID of hdb.
2150 Present only if system has hard disk hdb.
2153 \begin_layout LyX-Code
2157 \begin_layout Standard
2158 Gives Image ID of hdc.
2159 Present only if system has hard disk hdc.
2162 \begin_layout LyX-Code
2166 \begin_layout Standard
2167 Gives Image ID of hdd.
2168 Present only if system has hard disk hdd.
2171 \begin_layout LyX-Code
2175 \begin_layout Standard
2176 Gives Image ID of disk in slot <num>.
2177 Slot number must be non-negative.
2180 \begin_layout LyX-Code
2181 \begin_inset Quotes eld
2185 \begin_inset Quotes erd
2191 \begin_layout Standard
2192 kGives image name of disk in slot <num>.
2193 Slot number must be non-negative.
2194 The slot must be previously declared using
2195 \begin_inset Quotes eld
2199 \begin_inset Quotes erd
2205 \begin_layout LyX-Code
2209 \begin_layout Standard
2210 Gives Image slot to initially put into floppy drive fda.
2211 Disk must be of floppy type.
2212 If none present, no disk is initially put there.
2215 \begin_layout LyX-Code
2219 \begin_layout Standard
2220 Gives Image slot to initially put into floppy drive fdb.
2221 Disk must be of floppy type.
2222 If none present, no disk is initially put there.
2225 \begin_layout LyX-Code
2229 \begin_layout Standard
2230 Gives Image slot to initially put into CD-ROM drive hdc.
2231 Not allowed if hard disk hdc is present.
2232 Disk must be of CD-ROM type.
2233 If none present no disk is initially put there.
2236 \begin_layout LyX-Code
2237 "INITIALTIME" <time>
2240 \begin_layout Standard
2241 Number of milliseconds since Unix epoch to system start up time.
2245 \begin_layout Standard
2250 \begin_layout LyX-Code
2251 "CPUDIVIDER" <divider>
2254 \begin_layout Standard
2255 Set CPU frequency divider (dividing the 1GHz master clock).
2256 Allowed range is 1-256.
2260 \begin_layout LyX-Code
2261 "MEMORYSIZE" <pages>
2264 \begin_layout Standard
2265 Number of 4KiB pages of RAM memory.
2266 Allowed range 256-262144.
2270 \begin_layout LyX-Code
2274 \begin_layout Standard
2276 Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2280 \begin_layout LyX-Code
2281 "LOADMODULEA" <module> <parameters>
2284 \begin_layout Standard
2285 Load module <module> with parameters <parameters>.
2288 \begin_layout LyX-Code
2289 "LOADMODULE" <module>
2292 \begin_layout Standard
2293 Load module <module> with no parameters
2296 \begin_layout LyX-Code
2297 \begin_inset Quotes eld
2301 \begin_inset Quotes erd
2307 \begin_layout Standard
2308 Use class <fpu> as FPU emulator.
2311 \begin_layout Subsection
2312 Event record format:
2315 \begin_layout Standard
2316 Event record is in archive member "events".
2317 It uses line component encoding.
2318 Each line gives an event.
2319 First component of each line gives time stamp.
2320 These timestamps MUST be in increasing order and all MUST be non-negative.
2321 Time stamp time unit is exactly 1 nanosecond of emulated time.
2324 \begin_layout Standard
2325 The second component of each line is name of class to dispatch to.
2326 Further components are passed as-is to event handlers.
2330 \begin_layout Subsubsection
2334 \begin_layout Itemize
2335 Dispatch to: SAVESTATE
2338 \begin_layout Itemize
2339 Argument #1: Savestate id
2342 \begin_layout Itemize
2343 Argument #2 (optional): Rerecord count at time of saving savestate
2346 \begin_layout Standard
2347 Signals that savestate has occured here.
2348 The save state IDs MUST be unique in entire event stream.
2349 The second argument to savestate (if present) is rerecord count at time
2350 of saving that savestate (useful for calulating rerecord count of movie
2351 starting from savestate).
2352 No time restrictions
2355 \begin_layout Subsubsection
2359 \begin_layout Itemize
2363 \begin_layout Itemize
2365 \begin_inset Quotes eld
2369 \begin_inset Quotes erd
2373 \begin_inset Quotes eld
2377 \begin_inset Quotes erd
2383 \begin_layout Standard
2384 Controls various options.
2386 \begin_inset Quotes eld
2390 \begin_inset Quotes erd
2393 turns on absolute mode (default) where event timestamps are absolute.
2395 \begin_inset Quotes eld
2399 \begin_inset Quotes erd
2402 turns on relative mode where event timestamps are relative to last event
2404 The OPTION event itself is not affected by timing change.
2405 No time restrictions
2408 \begin_layout Subsubsection
2409 Keyboard keypress/keyrelease event:
2412 \begin_layout Itemize
2413 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2416 \begin_layout Itemize
2417 Argument #1: Fixed: "KEYEDGE"
2420 \begin_layout Itemize
2421 Argument #2: Key number.
2422 Valid values are 1-83, 85-95, 129-197 and 199-223
2425 \begin_layout Standard
2426 Send key press or key release.
2427 Keys work in toggle button manner.
2428 The event time must be multiple of 66 666, and must not be less than 60
2429 * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2430 on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2433 \begin_layout Subsubsection
2437 \begin_layout Itemize
2438 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2441 \begin_layout Itemize
2442 Argument #1: Fixed: "PAUSE"
2445 \begin_layout Standard
2446 Send pause key event.
2447 The time restrictions are identical to KEYEDGE event.
2450 \begin_layout Subsubsection
2451 Joystick button event:
2454 \begin_layout Itemize
2455 Dispatch to: org.jpc.modules.Joystick
2458 \begin_layout Itemize
2460 \begin_inset Quotes eld
2464 \begin_inset Quotes erd
2468 \begin_inset Quotes eld
2472 \begin_inset Quotes erd
2476 \begin_inset Quotes eld
2480 \begin_inset Quotes erd
2484 \begin_inset Quotes eld
2488 \begin_inset Quotes erd
2494 \begin_layout Itemize
2496 \begin_inset Quotes eld
2500 \begin_inset Quotes erd
2504 \begin_inset Quotes eld
2508 \begin_inset Quotes erd
2514 \begin_layout Standard
2515 Send button down/up event.
2516 No time restrictions.
2519 \begin_layout Subsubsection
2520 Joystick axis event:
2523 \begin_layout Itemize
2524 Dispatch to: org.jpc.modules.Joystick
2527 \begin_layout Itemize
2529 \begin_inset Quotes eld
2533 \begin_inset Quotes erd
2537 \begin_inset Quotes eld
2541 \begin_inset Quotes erd
2545 \begin_inset Quotes eld
2549 \begin_inset Quotes erd
2553 \begin_inset Quotes eld
2557 \begin_inset Quotes erd
2563 \begin_layout Itemize
2564 Argument #2: Multivibrator unstable state length in ns.
2567 \begin_layout Standard
2568 Set amount of time multivibrator remains in unstable state.
2569 No time restrictions.
2572 \begin_layout Subsubsection
2576 \begin_layout Itemize
2577 Dispatch to: org.jpc.emulator.PC$ResetButton
2580 \begin_layout Itemize
2584 \begin_layout Standard
2588 \begin_layout Subsubsection
2592 \begin_layout Itemize
2593 Dispatch to: org.jpc.emulator.PC$DiskChanger
2596 \begin_layout Itemize
2597 Argument #1: Fixed: "FDA"
2600 \begin_layout Itemize
2601 Argument #2: Number of image slot to put there.
2605 \begin_layout Standard
2606 The disk number MUST be -1 or valid disk number.
2607 -1 MUST NOT be used if there is no disk in floppy drive A.
2608 This event causes specified disk to be placed to FDA or FDA disk to be
2609 ejected with no replacement if disk number is -1.
2610 The specified disk if not -1 must be of floppy type.
2611 The specified disk if valid must not be in any other drive.
2614 \begin_layout Subsubsection
2618 \begin_layout Itemize
2619 Dispatch to: org.jpc.emulator.PC$DiskChanger
2622 \begin_layout Itemize
2623 Argument #1: Fixed: "FDB"
2626 \begin_layout Itemize
2627 Argument #2: Number of image slot to put there.
2631 \begin_layout Standard
2632 The disk number MUST be -1 or valid disk number.
2633 -1 MUST NOT be used if there is no disk in floppy drive B.
2634 This event causes specified disk to be placed to FDB or FDB disk to be
2635 ejected with no replacement if disk number is -1.
2636 The specified disk if not -1 must be of floppy type.
2637 The specified disk if valid must not be in any other drive.
2640 \begin_layout Subsubsection
2644 \begin_layout Itemize
2645 Dispatch to: org.jpc.emulator.PC$DiskChanger
2648 \begin_layout Itemize
2649 Argument #1: Fixed: "CDROM"
2652 \begin_layout Itemize
2653 Argument #2: Number of image slot to put there.
2657 \begin_layout Standard
2658 The disk number MUST be -1 or valid disk number.
2659 -1 MUST NOT be used if there is no disk in CD-ROM.
2660 This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2661 to be ejected with no replacement if disk number is -1.
2662 The specified disk if not -1 must be of CD-ROM type.
2665 \begin_layout Standard
2666 This event has no effect if CD-ROM is locked.
2669 \begin_layout Subsubsection
2670 Write protect floppy:
2673 \begin_layout Itemize
2674 Dispatch to: org.jpc.emulator.PC$DiskChanger
2677 \begin_layout Itemize
2678 Argument #1: Fixed: "WRITEPROTECT"
2681 \begin_layout Itemize
2682 Argument #2: Number of image slot to manipulate
2685 \begin_layout Standard
2686 Write protects specified disk.
2687 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2690 \begin_layout Subsubsection
2691 Write unprotect floppy:
2694 \begin_layout Itemize
2695 Dispatch to: org.jpc.emulator.PC$DiskChanger
2698 \begin_layout Itemize
2699 Argument #1: Fixed: "WRITEUNPROTECT"
2702 \begin_layout Itemize
2703 Argument #2: Number of image slot to manipulate
2706 \begin_layout Standard
2707 Disables write protection specified disk.
2708 The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2711 \begin_layout Subsection
2715 \begin_layout Standard
2716 Diskinfo sections are named
2717 \begin_inset Quotes eld
2721 \begin_inset Quotes erd
2725 They use line component encoding, fieldtype being first component on each
2726 line (value being the second).
2727 Following fields are defined:
2730 \begin_layout Subsubsection
2734 \begin_layout Standard
2735 Gives type of image.
2739 \begin_layout Itemize
2740 \begin_inset Quotes eld
2744 \begin_inset Quotes erd
2750 \begin_layout Itemize
2751 \begin_inset Quotes eld
2755 \begin_inset Quotes erd
2761 \begin_layout Itemize
2762 \begin_inset Quotes eld
2766 \begin_inset Quotes erd
2772 \begin_layout Itemize
2773 \begin_inset Quotes eld
2777 \begin_inset Quotes erd
2780 (BIOS/VGABIOS image)
2783 \begin_layout Itemize
2784 \begin_inset Quotes eld
2788 \begin_inset Quotes erd
2791 (what the heck is this???)
2794 \begin_layout Subsubsection
2798 \begin_layout Standard
2802 \begin_layout Subsubsection
2806 \begin_layout Standard
2807 (BIOS images only) Gives length of BIOS image
2810 \begin_layout Subsubsection
2814 \begin_layout Standard
2815 MD5 of raw disk/BIOS image without any headers or trailers.
2818 \begin_layout Subsubsection
2822 \begin_layout Standard
2823 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
2826 \begin_layout Subsubsection
2830 \begin_layout Standard
2831 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
2835 \begin_layout Subsubsection
2839 \begin_layout Standard
2840 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
2844 \begin_layout Subsubsection
2848 \begin_layout Standard
2849 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
2853 \begin_layout Subsubsection
2857 \begin_layout Standard
2858 Line from image comment block.
2859 Usually give data about files image has.
2860 May or may not be present.
2863 \begin_layout Subsection
2867 \begin_layout Standard
2868 Actual savestate format is not documented here.
2869 It is close to impossible to comprehend without access to emulator source
2873 \begin_layout Section
2874 Advanced: Making class dumpable
2877 \begin_layout Standard
2878 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
2879 and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
2880 <init>(org.jpc.emulator.SRLoader).
2881 Non-static inner classes can not be dumpable (make them static using tricks
2882 similar to what javac uses).
2885 \begin_layout Standard
2886 If dumped class has dumpable superclass, the first thing dumping function
2887 needs to do is to call dumper function of superclass and first thing loading
2888 constructor needs to do is to call loading constructor of superclass.
2889 If class has no dumpable superclass, dumper doesn't need to do anything
2890 special, while loader needs to call objectCreated(this) on SRLoader object
2891 passed as parameter.
2895 \begin_layout Standard
2896 Following these fixed parts, dump all members that are part of mutable state
2900 \begin_layout Subsection
2901 Member dumping/loading functions
2904 \begin_layout Standard
2905 There is dumping/loading function for following (all functions dumping/loading
2906 reference types can handle null):
2909 \begin_layout Itemize
2910 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
2913 \begin_layout Itemize
2914 byte: SRDumper.dumpByte, SRLoader.loadByte
2917 \begin_layout Itemize
2918 short: SRDumper.dumpShort, SRLoader.loadShort
2921 \begin_layout Itemize
2922 int: SRDumper.dumpInt, SRLoader.loadInt
2925 \begin_layout Itemize
2926 long: SRDumper.dumpLong, SRLoader.loadLong
2929 \begin_layout Itemize
2930 String: SRDumper.dumpString, SRLoader.loadString
2933 \begin_layout Itemize
2934 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
2937 \begin_layout Itemize
2938 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
2941 \begin_layout Itemize
2942 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
2945 \begin_layout Itemize
2946 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
2949 \begin_layout Itemize
2950 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
2953 \begin_layout Itemize
2954 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
2957 \begin_layout Itemize
2958 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
2961 \begin_layout Itemize
2962 special object: SRDumper.specialObject, SRLoader.specialObject
2965 \begin_layout Subsubsection
2969 \begin_layout Itemize
2970 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
2973 \begin_layout Itemize
2974 Special objects are various static objects that don't need to be stored
2975 because they don't have mutable fields.
2978 \begin_layout Itemize
2979 Don't dump fields related to event state feedback.
2982 \begin_layout Itemize
2983 Don't dump temporary flags that are only used while PC is running.
2984 Savestate when PC is running isn't possible anyway.
2987 \begin_layout Itemize
2988 Some connectors dump fields related to connector output, some don't.
2991 \begin_layout Section
2992 Advanced: Making output connectors
2995 \begin_layout Standard
2996 Implementing interface org.jpc.emulator.DisplayController signals that this
2997 is display controller, inhibiting loading of the standard VGA display controlle
2998 r if loaded as module.
3002 \begin_layout Subsection
3003 Interface org.jpc.emulator.OutputConnector
3006 \begin_layout Standard
3007 Class is made to be output connector by implementing this interface.
3008 This interface specifies the methods used for output hold locking.
3009 Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3010 that are suitable for calling.
3014 \begin_layout Subsubsection
3015 Method subscribeOutput(Object)
3018 \begin_layout Standard
3019 Subscribes the output, with specified object as handle.
3022 \begin_layout Subsubsection
3023 Method unsubscribeOutput(Object)
3026 \begin_layout Standard
3027 Unsubscribe the specified handle object from output.
3030 \begin_layout Subsubsection
3031 Method waitOutput(Object)
3034 \begin_layout Standard
3035 Wait for output on specified connector using specified handle object.
3036 Returns true on success, false if wait was interrupted by thread interrupt.
3040 \begin_layout Subsubsection
3041 Method releaseOutput(Object)
3044 \begin_layout Standard
3045 Release connector from p.o.v.
3050 \begin_layout Subsubsection
3054 \begin_layout Standard
3055 Release threads waiting on waitOutput() and block until all subscribers
3056 have returned from waitOutput() and enteired releaseOutput().
3059 \begin_layout Subsubsection
3060 Method releaseOutputWaitAll(object)
3063 \begin_layout Standard
3064 Like releaseOutput(), but waits until all handles have released their output.
3067 \begin_layout Subsection
3068 Class org.jpc.emulator.VGADigtalOut
3071 \begin_layout Standard
3072 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3073 VGA output connector.
3074 If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3078 \begin_layout Subsubsection
3082 \begin_layout Standard
3083 Get width of display (watch out, can return 0).
3086 \begin_layout Subsubsection
3090 \begin_layout Standard
3091 Get height of display (watch out, can return 0).
3094 \begin_layout Subsubsection
3095 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3098 \begin_layout Standard
3099 Returns the dirty region (region modified since last output).
3102 \begin_layout Subsubsection
3106 \begin_layout Standard
3107 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3108 one value per pixel) giving pixel data.
3109 Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3113 \begin_layout Subsubsection
3114 Method resizeDisplay(int _width, int _height)
3117 \begin_layout Standard
3118 Resize the display to be of specified size.
3121 \begin_layout Subsubsection
3122 Method dirtyDisplayRegion(int x, int y, int w, int h)
3125 \begin_layout Standard
3126 Mark the specified region as dirty.
3129 \begin_layout Subsubsection
3130 Method resetDirtyRegion()
3133 \begin_layout Standard
3134 Resets the dirty region to be empty.
3137 \begin_layout Subsection
3138 Class org.jpc.emulator.PC method getVideoOutput()
3141 \begin_layout Standard
3142 Get VGA output connector for PC.
3145 \begin_layout Subsection
3146 Interface org.jpc.emulator.DisplayController.
3149 \begin_layout Standard
3150 Implementing this class signals that module is VGA controller.
3151 There can be only one such module active at time and presence of such module
3152 prevents loading builtin VGA controller emulation code.
3155 \begin_layout Subsubsection
3156 Method getOutputDevice()
3159 \begin_layout Standard
3160 Get VGA output connector for this VGA device.
3163 \begin_layout Subsection
3164 Class org.jpc.emulator.SoundDigitalOut
3167 \begin_layout Standard
3168 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3169 Each connector can transfer stereo signal at arbitiary sampling rate.
3170 Modules that have audio connectors need to implement interface org.jpc.emulator.So
3171 undOutputDevice, as this signals that output connectors should be created.
3174 \begin_layout Subsubsection
3175 Method addSample(long, short, short)
3178 \begin_layout Standard
3179 Add stereo sample at time given by first argument.
3180 The second and third arguments give volume on left and right channels.
3183 \begin_layout Subsubsection
3184 Method addSample(long, short)
3187 \begin_layout Standard
3188 Add mono sample at time given by first argument.
3189 The second argument give volume on both channels.
3192 \begin_layout Subsubsection
3193 Method readBlock(Block)
3196 \begin_layout Standard
3197 Reads block of output (atomic versus addSample).
3198 Block structure has following fields which are filled:
3201 \begin_layout Itemize
3202 timeBase: Time base for block.
3205 \begin_layout Itemize
3206 baseLeft: Left volume at time base.
3209 \begin_layout Itemize
3210 baseRight: Right volume at time base
3213 \begin_layout Itemize
3214 blockNo: Sequence number of block filled.
3217 \begin_layout Itemize
3218 samples: Number of samples in block
3221 \begin_layout Itemize
3222 sampleTiming: Number of nanoseconds since last sample
3225 \begin_layout Itemize
3226 sampleLeft: Left channel samples
3229 \begin_layout Itemize
3230 sampleRight: Right channel samples
3233 \begin_layout Subsection
3234 Interface org.jpc.emulator.SoundOutputDevice
3237 \begin_layout Standard
3238 Implementing this interface signals that module has audio output channels.
3241 \begin_layout Subsubsection
3242 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3245 \begin_layout Standard
3246 Return the number of sound channels module has.
3249 \begin_layout Subsubsection
3250 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3253 \begin_layout Standard
3254 This is called once per sound channel requested giving precreated sound
3258 \begin_layout Subsection
3259 Class org.jpc.emulator.PC method getSoundOut(String)
3262 \begin_layout Standard
3263 Get sound output with specified name.
3266 \begin_layout Section
3267 Advanced: Writing event targets
3270 \begin_layout Standard
3271 Whereas output connectors are the way output is dispatched, input is dispatched
3273 Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3276 \begin_layout Standard
3277 Event targets also provode methods which then encode events and dispatch
3278 them forward (without doing anything else) to event recorder.
3279 Also, event targets may have methods for obtaining state.
3282 \begin_layout Subsection
3283 Interface org.jpc.emulator.EventDispatchTarget
3286 \begin_layout Standard
3287 Interface that marks class capable of receiving events.
3290 \begin_layout Subsubsection
3291 Method setEventRecorder(EventRecorder)
3294 \begin_layout Standard
3295 Set the event recorder input events are sent to.
3298 \begin_layout Subsubsection
3299 Method startEventCheck()
3302 \begin_layout Standard
3303 Signals target to reset all state related to event checking and state feedback.
3304 This may be called at any time in order to reinitialialize event checking/feedb
3308 \begin_layout Subsubsection
3309 Method doEvent(long, String[], int) throws IOException
3312 \begin_layout Standard
3313 Event dispatch handler.
3314 The first argument is event time, second is parameters and third is what
3316 If target doesn't like the event, throw IOException.
3317 Following types (the integer parameter) are used:
3320 \begin_layout LyX-Code
3321 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3324 \begin_layout LyX-Code
3325 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3326 for reinitialization
3329 \begin_layout LyX-Code
3330 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3333 \begin_layout LyX-Code
3334 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3338 \begin_layout Subsubsection
3339 Method endEventCheock()
3342 \begin_layout Standard
3343 End event reinitialization.
3347 \begin_layout Subsubsection
3348 Method getEventTimeLowBound(long, String[]) throws IOException
3351 \begin_layout Standard
3352 Return the time value that's the earliest possiblity for this event to occur.
3353 Returning any time in past (including -1) causes event to fire as soon
3355 The long parameter gives the current scheduled time for event.
3358 \begin_layout Section
3362 \begin_layout Standard
3363 Modules are various extensions that run inside emulator core.
3364 As such, they affect sync.
3365 Modules must implement interface org.jpc.emulator.HardwareComponent (they
3366 are hardware components) and must be dumpable.
3367 Additionally, they need either constructor <init>() or <init>(String).
3368 The first is if no parameters are passed, the second is for case where
3369 parameters are passed.
3372 \begin_layout Standard
3373 Aside of the constructors, modules need to obey the ordinary conventions
3374 for hardware components.
3375 No code outside modules needs to know that module exists.
3378 \begin_layout Section
3382 \begin_layout Standard
3383 Plugins handle various UI tasks.
3384 They need to implement interface org.jpc.Plugin.
3387 \begin_layout Subsection
3388 Interface org.jpc.pluginsbase.Plugin
3391 \begin_layout Subsubsection
3392 Method systemShutdown()
3395 \begin_layout Standard
3396 Called when emulator shuts down.
3397 Either called in dedicated thread or in thread that called emulatorShutdown().
3398 These handlers should do the bare minimum to get files on disk to consistent
3400 After these calls from all plugins have finished, emulator exits.
3401 Do not try to manipulate UI from these methods, as doing that easily leads
3405 \begin_layout Subsubsection
3406 Method reconnect(PC)
3409 \begin_layout Standard
3410 Gives new PC to connect to.
3411 Null is passed if plugin should disconnect.
3414 \begin_layout Subsubsection
3418 \begin_layout Standard
3419 Called in dedicated thread after plugin is initialized.
3422 \begin_layout Subsubsection
3426 \begin_layout Standard
3427 Called after PC has stopped.
3430 \begin_layout Subsubsection
3434 \begin_layout Standard
3435 Called before PC starts.
3438 \begin_layout Subsubsection
3439 Method notifyArguments(String[])
3442 \begin_layout Standard
3443 Pass arguments from command line.
3446 \begin_layout Subsubsection
3447 Constructor <init>(Plugins)
3450 \begin_layout Standard
3451 This constructor is used to initialize plugins that don't take parameters.
3454 \begin_layout Subsubsection
3455 Constructor <init>(Plugins, String)
3458 \begin_layout Standard
3459 This constructor is used to initialize plugins that take parameters.
3462 \begin_layout Subsection
3463 Class org.jpc.pluginsbase.Plugins
3466 \begin_layout Standard
3467 This class provodes various methods for manipulating plugins.
3470 \begin_layout Subsubsection
3471 Method isShuttingDown()
3474 \begin_layout Standard
3475 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3476 via VM exit, CTRL+C or explicitly.
3477 Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3480 \begin_layout Subsubsection
3481 Method shutdownEmulator()
3484 \begin_layout Standard
3485 Shut down and exit the emulator.
3486 All plugin shutdown functions are called in this thread.
3489 \begin_layout Subsubsection
3490 Method reconnectPC(PC)
3493 \begin_layout Standard
3494 Signal reconnectPC event to all plugins.
3497 \begin_layout Subsubsection
3501 \begin_layout Standard
3502 Signal pcStarting() event to all plugins.
3505 \begin_layout Subsubsection
3509 \begin_layout Standard
3510 Signal pcStopping() event to all plugins.
3513 \begin_layout Subsection
3514 Interface org.jpc.pluginsbase.ExternalCommandInterface
3517 \begin_layout Standard
3518 Implementing interface org.jpc.pluginsbase.ExternalCommandInterface signals
3519 that plugin can receive commands via external commands interface.
3522 \begin_layout Subsubsection
3523 Method invokeCommand(String cmd, String[] args)
3526 \begin_layout Standard
3527 Invoke specified command using specified arguments.
3528 Return true if event is to be shallowed, false to continue trying to pass
3532 \begin_layout Section
3533 Lua kernel programming
3536 \begin_layout Standard
3537 At startup, kernel gets its arguments in 'args' table and the script name
3538 to run in 'scriptname' string.
3539 It should enter the named script in protected mode.
3542 \begin_layout Standard
3543 The Lua VM exports numerious callbacks to kernel.
3544 The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3547 \begin_layout Itemize
3548 Always grab any functions used into local variables so nobody can mess with
3552 \begin_layout Itemize
3553 Don't use global variables in kernel (except for those passed).