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