New Lua functions
[jpcrr.git] / manual.lyx
blob6715420f83e6608d143690c982e9d7a2a2313261
1 #LyX 1.6.5 created this file. For more info see http://www.lyx.org/
2 \lyxformat 345
3 \begin_document
4 \begin_header
5 \textclass article
6 \use_default_options true
7 \language finnish
8 \inputencoding auto
9 \font_roman default
10 \font_sans default
11 \font_typewriter default
12 \font_default_family default
13 \font_sc false
14 \font_osf false
15 \font_sf_scale 100
16 \font_tt_scale 100
18 \graphics default
19 \paperfontsize default
20 \spacing single
21 \use_hyperref false
22 \papersize default
23 \use_geometry true
24 \use_amsmath 1
25 \use_esint 1
26 \cite_engine basic
27 \use_bibtopic false
28 \paperorientation portrait
29 \leftmargin 2cm
30 \topmargin 2cm
31 \rightmargin 1cm
32 \bottommargin 2cm
33 \headheight 1cm
34 \headsep 1cm
35 \footskip 1cm
36 \secnumdepth 3
37 \tocdepth 3
38 \paragraph_separation indent
39 \defskip medskip
40 \quotes_language english
41 \papercolumns 1
42 \papersides 1
43 \paperpagestyle default
44 \tracking_changes false
45 \output_changes false
46 \author "" 
47 \author "" 
48 \end_header
50 \begin_body
52 \begin_layout Title
53 JPC-RR: User's manual
54 \end_layout
56 \begin_layout Section
57 Licence
58 \end_layout
60 \begin_layout Standard
61 JPC-RR is licenced under GNU GPL v2.
62  See file 
63 \begin_inset Quotes eld
64 \end_inset
66 LICENSE
67 \begin_inset Quotes erd
68 \end_inset
71 \end_layout
73 \begin_layout Section
74 Getting started
75 \end_layout
77 \begin_layout Subsection
78 Prerequisites
79 \end_layout
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
84  also work).
85  Note: JRE is not enough.
87 \end_layout
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).
93 \end_layout
95 \begin_layout Subsection
96 Compiling
97 \end_layout
99 \begin_layout Standard
100 See compile.sh or compile.bat.
101  The streamtools stuff is only needed for dumping videos.
102 \end_layout
104 \begin_layout Subsection
105 Getting started
106 \end_layout
108 \begin_layout Standard
109 First you need to get and make some important images.
110  Obtain BIOS image, VGABIOS image and DOS boot floppy from somewhere.
111  After starting the emulator, use Drives -> Import Image to import the images
112  (ignore the error about no BIOS images being found).
113 \end_layout
115 \begin_layout Subsection
116 Running emulator
117 \end_layout
119 \begin_layout Standard
120 There is premade autoexec script called assemble.jpcrrinit that has fairly
121  reasonable defaults.
122  To use it:
123 \end_layout
125 \begin_layout LyX-Code
126 java JPCApplication -library library -autoexec assemble.jpcrrinit
127 \end_layout
129 \begin_layout Standard
130 The 
131 \begin_inset Quotes eld
132 \end_inset
134 -library library
135 \begin_inset Quotes erd
136 \end_inset
138  specifies that contents of directory 'library' are to be used as library.
139  The script pops up settings for new emulated PC (if you want to load savestate,
140  click cancel).
141  Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
142  selected), DOSfloppy for fda (boot device should be set to fda) and game
143  image as some HD drive 
144 \end_layout
146 \begin_layout Subsection
147 Bootup tips
148 \end_layout
150 \begin_layout Itemize
151 Putting the game as hdd (the fourth hard disk slot) causes boot to be bit
152  faster.
153 \end_layout
155 \begin_layout Itemize
156 Some BIOS versions have 
157 \begin_inset Quotes eld
158 \end_inset
160 press F12 to select boot device
161 \begin_inset Quotes erd
162 \end_inset
165  Hit <enter> from emulated keyboard and that prompt will go away in about
166  half emulated second (it stays several emulated seconds otherwise).
168 \end_layout
170 \begin_layout Itemize
171 If game doesn't need lots of memory, hitting F5 to skip intialization files
172  is fastest.
173  If it does need more memory, run config.sys commands but not autoexec.bat.
175 \end_layout
177 \begin_layout Itemize
178 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
179  emulator.
180 \end_layout
182 \begin_layout Section
183 Making JPC-RR format images from raw images
184 \end_layout
186 \begin_layout Standard
187 Due to various factors, JPC-RR can't use raw image files directly but requires
188  its own image format.
190 \end_layout
192 \begin_layout Subsection
193 Importing images from GUI:
194 \end_layout
196 \begin_layout Standard
197 Use Drives -> Import Image to import existing directories or image files.
198  Dialog prompting parameters will be displayed.
199  When importing floppy images, check 
200 \begin_inset Quotes eld
201 \end_inset
203 standard geometry
204 \begin_inset Quotes erd
205 \end_inset
207  if possible, that enables geometry autodetection, which is reasonable virtually
208  all of the time it is offered.
209 \end_layout
211 \begin_layout Subsection
212 Notes
213 \end_layout
215 \begin_layout Itemize
216 If making image from directory, the names of the files must conform to FAT
217  naming restrictions (8+3 character names, no spaces, etc).
218  Avoid filenames with non-ASCII characters.
220 \end_layout
222 \begin_layout Itemize
223 The DOS limit of 112 or 224 files for floppies does not apply to images
224  created from directory trees.
225  The minimum limit value used is 512.
226  If even that isn't enough, the limit is automatically increased to fit
227  all the needed directory entries.
228 \end_layout
230 \begin_layout Itemize
231 Making boot disks from tree does NOT work.
232  Even if you got system boot files there, it still won't work.
233 \end_layout
235 \begin_layout Itemize
236 Only floppy disks and hard drives can be made from directory trees.
237  BIOS images and CDROM images require image file.
238 \end_layout
240 \begin_layout Itemize
241 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
242  Disks with over 63 sectors per track don't work with DOS.
243  Wheither disks with over 127 tracks per side work with DOS is unknown.
244  Also avoid 1024-tracks per side HDDs.
245 \end_layout
247 \begin_layout Itemize
248 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
249  side for floppy.
250  1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
251  1-16 sides for HDD, 1 or 2 sides for floppy.
252  This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
253  and 516096KiB for HDDs.
254 \end_layout
256 \begin_layout Itemize
257 There are multiple image file contents that represent the same image.
258  The one with smallest size is picked when creating image.
259 \end_layout
261 \begin_layout Itemize
262 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
264 \end_layout
266 \begin_layout Subsection
267 Importing from command line
268 \end_layout
270 \begin_layout Standard
271 There is tool called ImageMaker that can make JPC-RR images from raw images.
272  Each image has format, ID an name.
273  Format and name are specified when making image.
274  ID is automatically calculated from format and contents.
275  Name does not affect the ID but is purely for convience so one doesn't
276  have to specify long image IDs manually.
277 \end_layout
279 \begin_layout Subsubsection
280 Syntax
281 \end_layout
283 \begin_layout Standard
284 The syntax for ImageMaker when making images is:
285 \end_layout
287 \begin_layout LyX-Code
288 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
289 \end_layout
291 \begin_layout Standard
292 <destination> is file name for JPC-RR format image to write.
293  <source> is either name of regular file (raw image file) or name of directory
294  tree with files (supported for making floppy or hard disk images only).
295  In case of directory tree, the files are layout deterministically to disk,
296  so the ID will always be the same for given geometry and type.
297  <name> is name to give to disk.
298  <format> is one of:
299 \end_layout
301 \begin_layout LyX-Code
302 --BIOS BIOS image (note: VGABIOS is also of this type).
303 \end_layout
305 \begin_layout LyX-Code
306 --CDROM CD-ROM image.
307 \end_layout
309 \begin_layout LyX-Code
310 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
311 \end_layout
313 \begin_layout LyX-Code
314 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
315 \end_layout
317 \begin_layout LyX-Code
318 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
319 \end_layout
321 \begin_layout LyX-Code
322 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
323 \end_layout
325 \begin_layout LyX-Code
326 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
327 \end_layout
329 \begin_layout LyX-Code
330 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
331 \end_layout
333 \begin_layout LyX-Code
334 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
335 \end_layout
337 \begin_layout LyX-Code
338 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
339 \end_layout
341 \begin_layout LyX-Code
342 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
343 \end_layout
345 \begin_layout LyX-Code
346 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
347 \end_layout
349 \begin_layout LyX-Code
350 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
351 \end_layout
353 \begin_layout LyX-Code
354 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
355 \end_layout
357 \begin_layout LyX-Code
358 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
359 \end_layout
361 \begin_layout LyX-Code
362 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
363 \end_layout
365 \begin_layout LyX-Code
366 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
367 \end_layout
369 \begin_layout LyX-Code
370 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
371 \end_layout
373 \begin_layout LyX-Code
374 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
375 \end_layout
377 \begin_layout LyX-Code
378 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
379 \end_layout
381 \begin_layout LyX-Code
382 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
383 \end_layout
385 \begin_layout LyX-Code
386 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
387 \end_layout
389 \begin_layout LyX-Code
390 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
391 \end_layout
393 \begin_layout LyX-Code
394 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
395 \end_layout
397 \begin_layout LyX-Code
398 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
399 \end_layout
401 \begin_layout LyX-Code
402 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
403 \end_layout
405 \begin_layout LyX-Code
406 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
407 \end_layout
409 \begin_layout LyX-Code
410 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
411 \end_layout
413 \begin_layout LyX-Code
414 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
415 \end_layout
417 \begin_layout LyX-Code
418 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
419 \end_layout
421 \begin_layout LyX-Code
422 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
423 \end_layout
425 \begin_layout LyX-Code
426 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
427 \end_layout
429 \begin_layout LyX-Code
430 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
431 \end_layout
433 \begin_layout Subsubsection
434 Other options
435 \end_layout
437 \begin_layout LyX-Code
438 --volumelabel=label Give specified volume label (affects ID).
439  Only meaningful when making image out of directory tree.
440  Default is no volume label.
441 \end_layout
443 \begin_layout LyX-Code
444 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
445  Only meaningful when making image out of directory tree.
446  The default timestamp is 19900101T000000Z.
447 \end_layout
449 \begin_layout Subsubsection
450 Image information
451 \end_layout
453 \begin_layout Standard
454 When invoked as:
455 \end_layout
457 \begin_layout LyX-Code
458 $ java ImageMaker <imagefile>
459 \end_layout
461 \begin_layout Standard
462 Variety of information about image is displayed (especially for floppies/HDDs).
463  Two important fields are calculated and claimed disk ID.
464  They should be the same.
465  If they are not, then the image file is corrupt (sadly, imagemaker has
466  bugs and bugs that cause it to write corrupt images have been seen).
467 \end_layout
469 \begin_layout Subsection
470 Advanced: The disk ID algorithm
471 \end_layout
473 \begin_layout Standard
474 The disk ID is calculated as:
475 \end_layout
477 \begin_layout LyX-Code
478 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
479 \end_layout
481 \begin_layout Standard
482 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
483  state and 128-bit output using the deprecated rotation constants (as specified
484  in Skein hash function reference documentation versions 1.0 and 1.1).
485  The <image> is the whole image, including parts not stored in image file.
486  The reason for keeping using the deprecated constants are:
487 \end_layout
489 \begin_layout Itemize
490 Changing the constants would change the IDs, which would invalidate existing
491  images
492 \end_layout
494 \begin_layout Itemize
495 This is not about cryptographic security
496 \end_layout
498 \begin_layout Itemize
499 The new constants don't improve security that much anyway.
500 \end_layout
502 \begin_layout Subsubsection
503 Floppies and HDDs
504 \end_layout
506 \begin_layout Standard
507 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
508  <geometry> is as follows (this is exactly the same form as it appears in
509  image header):
510 \end_layout
512 \begin_layout LyX-Code
513 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
514 \end_layout
516 \begin_layout LyX-Code
517 Byte 0 bits 2-5: Head count - 1.
518 \end_layout
520 \begin_layout LyX-Code
521 Byte 0 bits 6-7: Reserved, must be 0.
522 \end_layout
524 \begin_layout LyX-Code
525 Byte 1: Bits 0-7 of track count per side - 1.
526 \end_layout
528 \begin_layout LyX-Code
529 Byte 2: Sector count per track - 1.
530 \end_layout
532 \begin_layout Subsubsection
533 CD-ROM and BIOS images
534 \end_layout
536 \begin_layout Standard
537 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
538  byte).
539  <geometry> is blank.
540 \end_layout
542 \begin_layout Subsection
543 Advanced: Disk Image format
544 \end_layout
546 \begin_layout Standard
547 The disk image consists of following parts, concatenated in this order without
548  padding:
549 \end_layout
551 \begin_layout Itemize
552 Magic
553 \end_layout
555 \begin_layout Itemize
556 Disk ID
557 \end_layout
559 \begin_layout Itemize
560 Type code
561 \end_layout
563 \begin_layout Itemize
564 Disk name length
565 \end_layout
567 \begin_layout Itemize
568 Disk name
569 \end_layout
571 \begin_layout Itemize
572 type-specific geometry/size data
573 \end_layout
575 \begin_layout Itemize
576 Actual image data
577 \end_layout
579 \begin_layout Itemize
580 Comments
581 \end_layout
583 \begin_layout Subsubsection
584 Magic
585 \end_layout
587 \begin_layout Standard
588 Magic in disk image files is following 5 bytes: 
589 \begin_inset Quotes eld
590 \end_inset
592 IMAGE
593 \begin_inset Quotes erd
594 \end_inset
597 \end_layout
599 \begin_layout Subsubsection
600 Disk ID
601 \end_layout
603 \begin_layout Standard
604 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
605 \end_layout
607 \begin_layout Subsubsection
608 Type code
609 \end_layout
611 \begin_layout Standard
612 Type code is single byte.
613  0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
614  Other values are reserved.
615 \end_layout
617 \begin_layout Subsubsection
618 Disk name length
619 \end_layout
621 \begin_layout Standard
622 Obsolete.
623  Disk name length is given as two-byte big-endian value.
624  New images should have 0 here.
625 \end_layout
627 \begin_layout Subsubsection
628 Disk name
629 \end_layout
631 \begin_layout Standard
632 Ignored.
633  Name field is there for backward compatiblity.
634  Disk name length gives length of this field in bytes.
635 \end_layout
637 \begin_layout Subsubsection
638 Type-specific geometry/size data (floppies and HDDs)
639 \end_layout
641 \begin_layout Standard
642 Floppies and HDDs have 3-byte geometry data:
643 \end_layout
645 \begin_layout LyX-Code
646 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
647 \end_layout
649 \begin_layout LyX-Code
650 Byte 0 bits 2-5: Head count - 1.
651 \end_layout
653 \begin_layout LyX-Code
654 Byte 0 bits 6-7: Reserved, must be 0.
655 \end_layout
657 \begin_layout LyX-Code
658 Byte 1: Bits 0-7 of track count per side - 1.
659 \end_layout
661 \begin_layout LyX-Code
662 Byte 2: Sector count per track - 1.
663 \end_layout
665 \begin_layout Subsubsection
666 Type specific-geometry/size data (CD-ROMs)
667 \end_layout
669 \begin_layout Standard
670 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
671 \end_layout
673 \begin_layout Subsubsection
674 Type specific-geometry/size data (BIOS images)
675 \end_layout
677 \begin_layout Standard
678 BIOS images have 4-byte big-endian byte (not sector or block) count.
679 \end_layout
681 \begin_layout Subsubsection
682 Actual image data (floppy/HDD)
683 \end_layout
685 \begin_layout Standard
686 Floppy or HDD imagedata consists of following subparts:
687 \end_layout
689 \begin_layout Itemize
690 Storage method
691 \end_layout
693 \begin_layout Itemize
694 Sectors present
695 \end_layout
697 \begin_layout Itemize
698 Image data header
699 \end_layout
701 \begin_layout Itemize
702 Image data
703 \end_layout
705 \begin_layout Standard
706 Storage method is single byte.
707  Sectors present gives number of last nonzero sector + 1 (zero if image
708  is all zeroes)
709 \end_layout
711 \begin_layout Subsubsection
712 Floppy/HDD storage method 0: Raw storage
713 \end_layout
715 \begin_layout Standard
716 This storage method has empty header.
717  Image data is raw dump of first sectors present sectors.
718 \end_layout
720 \begin_layout Subsubsection
721 Floppy/HDD storage method 1: Sectormap
722 \end_layout
724 \begin_layout Standard
725 Image data header contains bitfield with just enough bytes to have one bit
726  per present sector.
727  The order of bits is such that number of bit corresponding to each sector
728  in byte is sector number modulo 8 and byte number is floor of sector number
729  divided by 8 when sector numbers are counted from zero.
730  If bit corresponding to sector is set, then the sector is present in image
731  data, otherwise it is absent and assumed to be all-zeroes.
732 \end_layout
734 \begin_layout Standard
735 Image data contains dumps of all present sectors in order of increasing
736  sector number.
737 \end_layout
739 \begin_layout Subsubsection
740 Floppy/HDD storage method 2: Extent first sector zero
741 \end_layout
743 \begin_layout Standard
744 Image data is empty as storage-specific data is mangled with image data.
745  The image data alternates between blocks encoding zero sectors and blocks
746  encoding nonzero sectors.
747  The first block encodes zero sectors.
749 \end_layout
751 \begin_layout Standard
752 Block encoding zero sectors consist of single 1-4 byte little-endian value
753  encoding number of sectors in block - 1.
754  Number of bytes is determined by sectors present value.
755  It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
756  for more than 16777216.
757  All sectors in block are filled with zeroes and are not stored.
758 \end_layout
760 \begin_layout Standard
761 Block encoding nonzero sectors has same block count as zero sector block
762  but is followed by the sectors stored raw.
763 \end_layout
765 \begin_layout Subsubsection
766 Floppy/HDD storage method 3: Extent first sector nonzero
767 \end_layout
769 \begin_layout Standard
770 Same as storage method 2 but first block is nonzero sector block.
771 \end_layout
773 \begin_layout Subsubsection
774 Actual image data (CD-ROMs and BIOS images)
775 \end_layout
777 \begin_layout Standard
778 These store image data raw.
779  The amount of data is specified by sector/byte count.
780 \end_layout
782 \begin_layout Subsubsection
783 Comments
784 \end_layout
786 \begin_layout Standard
787 Comments are given as list of strings, with UTF-8 encoded strings following
788  2-octet big-endian length.
789  Comment list is terminated by entry with length 0 (0x00 0x00).
790  Comments are optional and may be absent.
791 \end_layout
793 \begin_layout Section
794 The actual emulator
795 \end_layout
797 \begin_layout Standard
798 The actual emulator is invoked as:
799 \end_layout
801 \begin_layout LyX-Code
802 $ java JPCApplication <options>...
803 \end_layout
805 \begin_layout Standard
806 The valid options are:
807 \end_layout
809 \begin_layout LyX-Code
810 -library <library> Use the specified directory when searching for images
811  (can only be specified once).
812 \end_layout
814 \begin_layout LyX-Code
815 -autoexec <script> Execute contents of specified file as commands when starting
816  up.
817 \end_layout
819 \begin_layout LyX-Code
820 -norenames Copy&Delete files instead of renaming.
821  Mainly meant for debugging copy&delte code.
822 \end_layout
824 \begin_layout Standard
825 If no arguments are given, defaults of library 'disklibrary' and autoexec
826  file of 'assemble.jpcrrinit' are used.
827 \end_layout
829 \begin_layout Subsection
830 Command line
831 \end_layout
833 \begin_layout Standard
834 When emulator is started, command line comes up.
835  Following commands are known:
836 \end_layout
838 \begin_layout Itemize
839 'exit': exit immediately
840 \end_layout
842 \begin_layout Itemize
843 'load <plugin>': Load plugin (no arguments)
844 \end_layout
846 \begin_layout Itemize
847 'load <plugin>(<arguments>)': load plugin with arguments.
848 \end_layout
850 \begin_layout Itemize
851 'command <command> [<arguments>...]': Invoke command via external command interface.
852 \end_layout
854 \begin_layout Itemize
855 'call<command> [<arguments>...]': Invoke command via external command interface
856  and print return values.
857 \end_layout
859 \begin_layout Standard
860 When one gets command line, its useful to load some plugins.
861  See section about plugins.
862  Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
863  like to start PC immediately.
864 \end_layout
866 \begin_layout Subsection
867 PC settings dialog notes
868 \end_layout
870 \begin_layout Itemize
871 CPU divider base frequency before division is 1GHz.
872 \end_layout
874 \begin_layout Itemize
875 Images can be specified by name or by ID.
876  Name is relative to library directory.
877  If the image is in subdirectory of image directory, the directory separator
878  is is '/' regardless of what the host OS uses.
879 \end_layout
881 \begin_layout Itemize
882 CD-ROM and hdc are mutually exclusive
883 \end_layout
885 \begin_layout Itemize
886 Modules is comma-seperated list of modules to load.
887  To pass arguments to some modules, enclose the arguments in ().
888  Same module can be specified twice only if parameters differ.
889 \end_layout
891 \begin_layout Itemize
892 Setting boot device doesn't work with some BIOS versions.
893  Those versions prompt the boot device anyway.
894 \end_layout
896 \begin_layout Subsection
897 Audio output channels
898 \end_layout
900 \begin_layout Standard
901 PC can have one or more audio output channels.
902  The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
903 al.PCSpeaker-0'.
904  Modules that have audio outputs get channel names of form <classname>-<sequenti
905 al>, where <classname> is name of main module class and sequential is number
906  starting from zero.
907  Note that same module can have multiple output channels.
908  If multiple modules of same class request audio outputs, the <sequential>
909  values of subsequent module start where previous left off.
910 \end_layout
912 \begin_layout Subsection
913 Plugins
914 \end_layout
916 \begin_layout Standard
917 Plugins actually execute the tasks of the emulator.
918  They can be loaded using 
919 \begin_inset Quotes eld
920 \end_inset
922 load <plugin>
923 \begin_inset Quotes erd
924 \end_inset
926  or 'load <plugin>(<arguments>)
927 \begin_inset Quotes erd
928 \end_inset
930  from command line.
931 \end_layout
933 \begin_layout Standard
934 Different Plugins using the same output (like running PCMonitor and RAWVideoDump
935 er) should not conflict because connector output hold locking is desinged
936  to handle multiple readers.
937 \end_layout
939 \begin_layout Standard
940 If no plugin used requires GUI, then the emulator can be run without having
941  GUI available.
942 \end_layout
944 \begin_layout Subsubsection
945 plugin: org.jpc.plugins.PCControl
946 \end_layout
948 \begin_layout Standard
949 Takes optionally 'extramenu=<file>' and 'uncompressedsave=1', requires and
950  uses GUI.
951 \end_layout
953 \begin_layout Standard
954 Runs the PC emulator core.
955  Has capability to start/stop emulation, breakpoint after certain time or
956  start/end of VGA vertical retrace.
957  Also can create, savestate and loadstate PC emulation.
958  Memory dumping is supported.
960 \end_layout
962 \begin_layout Standard
963 'extramenu=<file>' causes Plugin to load extra menu entries from <file>.
964  'uncompressedsave=1' causes savestates to be written uncompressed (useful
965  if they are stored in VCS supporting delta compression).
966 \end_layout
968 \begin_layout Subsubsection
969 plugin: org.jpc.plugins.PCRunner
970 \end_layout
972 \begin_layout Standard
973 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
974  require nor use GUI.
975 \end_layout
977 \begin_layout Standard
978 Loads PC from savestate and just runs it.
979  CTRL+C to quit.
980  Also automatically quits once stoptime is reached.
981 \end_layout
983 \begin_layout Subsubsection
984 plugin: org.jpc.plugins.PCMonitor
985 \end_layout
987 \begin_layout Standard
988 No arguments, requires and uses GUI.
989 \end_layout
991 \begin_layout Standard
992 VGA monitor for emulated PC.
993 \end_layout
995 \begin_layout Subsubsection
996 plugin: org.jpc.plugins.VirtualKeyboard
997 \end_layout
999 \begin_layout Standard
1000 No arguments, requires and uses GUI.
1001 \end_layout
1003 \begin_layout Standard
1004 On-screen keyboard for emulated PC.
1005 \end_layout
1007 \begin_layout Subsubsection
1008 plugin: org.jpc.plugins.PCStartStopTest
1009 \end_layout
1011 \begin_layout Standard
1012 No arguments, requires and uses GUI.
1013 \end_layout
1015 \begin_layout Standard
1016 Small plugin testing remote PC start/stop.
1017  Also supports sending some common keypresses.
1018 \end_layout
1020 \begin_layout Subsubsection
1021 plugin: org.jpc.plugins.RAWVideoDumper
1022 \end_layout
1024 \begin_layout Standard
1025 Takes 'rawoutput=<file>' as argument.
1026  Does not require nor use GUI.
1027 \end_layout
1029 \begin_layout Standard
1030 Dumps all generated frames to RAW file <file>.
1031  Rawoutput is required.
1032  The raw file consists of concatenation of zlib streams.
1033  The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1034  each acting as time offset of 2^32-1 nanoseconds and saved frames.
1035  The saved frame has time offset in nanoseconds (big endian) as first four
1036  bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1037  The next two bytes are big-endian width, next two big-endian height.
1038  Finally frame has 4 * width * height bytes of data that encodes pixels
1039  using 4 bytes per pixel, in left-to-right, up-to-down order.
1040  Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1041  green channel and byte 3 is blue channel.
1042 \end_layout
1044 \begin_layout Standard
1045 Dumping to pipe is supported.
1046 \end_layout
1048 \begin_layout Subsubsection
1049 plugin: org.jpc.plugins.RAWAudioDumper
1050 \end_layout
1052 \begin_layout Standard
1053 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1054  'offset=<offset>' as arguments, separated by ','.
1055  Does not require nor use GUI.
1056 \end_layout
1058 \begin_layout Standard
1059 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1060  file (file, mandatory).
1061  The resulting file consists of records, 4 or 8 bytes each.
1062  4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1063  time delta by 
1064 \begin_inset Formula $2^{32}-1$
1065 \end_inset
1068  Otherwise record is 8 bytes.
1069  Each 8 byte record has three fields.
1070  First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1071  be smaller than 
1072 \begin_inset Formula $2^{32}-1$
1073 \end_inset
1075 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1076  big endian new right channel volume.
1077  Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1078  the audio by.
1079 \end_layout
1081 \begin_layout Subsubsection
1082 plugin: org.jpc.plugins.LuaPlugin
1083 \end_layout
1085 \begin_layout Standard
1086 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1087  kernel, requires and uses GUI.
1088 \end_layout
1090 \begin_layout Standard
1091 Lua VM for executing scripts.
1092 \end_layout
1094 \begin_layout Subsubsection
1095 plugin: org.jpc.plugins.JoystickInput
1096 \end_layout
1098 \begin_layout Standard
1099 No parameters.
1100  Displays window for sending joystick input.
1101 \end_layout
1103 \begin_layout Section
1104 Modules
1105 \end_layout
1107 \begin_layout Subsection
1108 org.jpc.modules.Joystick:
1109 \end_layout
1111 \begin_layout Itemize
1112 Arguments: none.
1113 \end_layout
1115 \begin_layout Itemize
1116 Resources: I/O port 0x201
1117 \end_layout
1119 \begin_layout Standard
1120 Emulates joystick game port.
1121 \end_layout
1123 \begin_layout Subsection
1124 org.jpc.modules.SoundCard
1125 \end_layout
1127 \begin_layout Itemize
1128 Arguments: Optional resources specification
1129 \end_layout
1131 \begin_layout Itemize
1132 Resources (defaults): I/O port 0x220-0x22F, IRQ 5, DMA 1, DMA 5
1133 \end_layout
1135 \begin_layout Standard
1136 Emulates Sound card.
1137 \end_layout
1139 \begin_layout Subsection
1140 org.jpc.modules.FMCard
1141 \end_layout
1143 \begin_layout Itemize
1144 Arguments: Optional resources specification
1145 \end_layout
1147 \begin_layout Itemize
1148 Resources (defaults): I/O port 0x338-0x33B
1149 \end_layout
1151 \begin_layout Standard
1152 Emulates FM card.
1153 \end_layout
1155 \begin_layout Subsection
1156 org.jpc.modules.BasicFPU:
1157 \end_layout
1159 \begin_layout Itemize
1160 Arguments: none.
1161 \end_layout
1163 \begin_layout Itemize
1164 Resources: None.
1165 \end_layout
1167 \begin_layout Standard
1168 Crude FPU (x87) emulator.
1169 \end_layout
1171 \begin_layout Section
1172 Hacks
1173 \end_layout
1175 \begin_layout Standard
1176 Hacks are saved to savestates but not movies.
1177 \end_layout
1179 \begin_layout Subsection
1180 NO_FPU
1181 \end_layout
1183 \begin_layout Standard
1184 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1185  has no FPU.
1186  BIOS assumes system has FPU but some games use that bit to detect FPU,
1187  trying to use it if it is 
1188 \begin_inset Quotes eld
1189 \end_inset
1191 present
1192 \begin_inset Quotes erd
1193 \end_inset
1196  Try this if game startup hangs with lots of trying to use FPU but not present
1197  errors.
1198  Don't use if there is FPU present.
1199  Needed to get games like Blake Stone / Wolfenstein 3-D to work (FPU emulator
1200  allows it to start but causes graphical glitches).
1201 \end_layout
1203 \begin_layout Subsection
1204 VGA_DRAW
1205 \end_layout
1207 \begin_layout Standard
1208 Update basic VGA parameters before vretrace, not after it.
1209  Some games (e.g.
1210  Commander Keen 4) don't like if this isn't done and some games (e.g.
1211  Mario & Luigi) don't like if it is done.
1212  Wrong value manifests as jerky scrolling (scrolling back and forth and
1213  fixed statusbars move).
1214 \end_layout
1216 \begin_layout Section
1217 Some error messages and explanations
1218 \end_layout
1220 \begin_layout Itemize
1221 <filename> is Not a valid image file
1222 \end_layout
1224 \begin_layout Itemize
1225 <filename> is not image file
1226 \end_layout
1228 \begin_layout Itemize
1229 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1230  and <z> sectors.
1231 \end_layout
1233 \begin_layout Itemize
1234 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1235  and <z> sectors.
1236 \end_layout
1238 \begin_layout Itemize
1239 Can't read disk image sector map.
1240 \end_layout
1242 \begin_layout Itemize
1243 Can't read disk image extent.
1244 \end_layout
1246 \begin_layout Standard
1247 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1248  image at all or its corrupt.
1249 \end_layout
1251 \begin_layout Itemize
1252 <filename> is image of unknown type.
1253 \end_layout
1255 \begin_layout Itemize
1256 <filename> has unrecognized geometry <x> <y> <z>
1257 \end_layout
1259 \begin_layout Standard
1260 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1261  containing something current version can't comprehend.
1262 \end_layout
1264 \begin_layout Itemize
1265 Invalid format specifier <something>.
1266 \end_layout
1268 \begin_layout Itemize
1269 Invalid syntax of --floppy= or --HDD= option.
1270 \end_layout
1272 \begin_layout Itemize
1273 Invalid format specifier/option <something>.
1274 \end_layout
1276 \begin_layout Standard
1277 Invalid option or format specifier was given.
1278  Check for typos.
1279 \end_layout
1281 \begin_layout Itemize
1282 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1283 \end_layout
1285 \begin_layout Standard
1286 Check syntax of command.
1287  Especially that diskname is present!
1288 \end_layout
1290 \begin_layout Itemize
1291 The image has <nnn> sectors while it should have <yyy> according to selected
1292  geometry.
1293 \end_layout
1295 \begin_layout Itemize
1296 Raw image file length not divisible by 512.
1297 \end_layout
1299 \begin_layout Itemize
1300 Trying to read sector out of range.
1301 \end_layout
1303 \begin_layout Standard
1304 The selected geometry is wrong or raw image is incomplete.
1305 \end_layout
1307 \begin_layout Itemize
1308 Invalid disk name (Should not happen!).
1309 \end_layout
1311 \begin_layout Itemize
1312 Invalid geometry to be written.
1313 \end_layout
1315 \begin_layout Standard
1316 This is a very likely a bug in program.
1317 \end_layout
1319 \begin_layout Itemize
1320 What the heck <filename> is? It's not regular file nor directory.
1321 \end_layout
1323 \begin_layout Standard
1324 That sort of file can't be used as input for image making, or the file just
1325  doesn't exist.
1326 \end_layout
1328 \begin_layout Itemize
1329 BIOS images can only be made out of regular files.
1330 \end_layout
1332 \begin_layout Itemize
1333 CD images can only be made out of regular files.
1334 \end_layout
1336 \begin_layout Standard
1337 Source image specified is not regular file, but image of that type can't
1338  be made of anything else.
1339 \end_layout
1341 \begin_layout Itemize
1342 Can't read raw bios image file.
1343 \end_layout
1345 \begin_layout Itemize
1346 Can't read sector <nnn> from image.
1347 \end_layout
1349 \begin_layout Standard
1350 Reading the raw image file failed for some reason.
1351 \end_layout
1353 \begin_layout Itemize
1354 Bad library line: "<something>".
1355  Ignored.
1356 \end_layout
1358 \begin_layout Standard
1359 Syntax error in image library.
1360 \end_layout
1362 \begin_layout Itemize
1363 Removing image <something> a.k.a.
1364  "<something>" as it no longer exists.
1365 \end_layout
1367 \begin_layout Standard
1368 The image file no longer exists so it gets removed from library.
1369 \end_layout
1371 \begin_layout Itemize
1372 Removing image <something> a.k.a.
1373  "<something>" due to <some> conflict.
1374 \end_layout
1376 \begin_layout Standard
1377 Image library code killed some image from library due to some kind of conflict
1378  with image being added.
1379 \end_layout
1381 \begin_layout Itemize
1382 Too much data to fit into given space.
1383 \end_layout
1385 \begin_layout Standard
1386 The tree you gave contains takes just too much space to fit into disk of
1387  this size.
1388 \end_layout
1390 \begin_layout Section
1391 Advanced: Savestate/movie format
1392 \end_layout
1394 \begin_layout Subsection
1395 Special character classes
1396 \end_layout
1398 \begin_layout Subsubsection
1399 SPACE
1400 \end_layout
1402 \begin_layout Standard
1403 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1404  characters:
1405 \end_layout
1407 \begin_layout Itemize
1408 Codepoints 0x20, and 0x09.
1409 \end_layout
1411 \begin_layout Itemize
1412 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1413 \end_layout
1415 \begin_layout Itemize
1416 Codepoints 0x2000-0x200A.
1417 \end_layout
1419 \begin_layout Subsubsection
1420 LINEFEED
1421 \end_layout
1423 \begin_layout Standard
1424 Following byte sequences are interpretted as linefeeds (line change):
1425 \end_layout
1427 \begin_layout Itemize
1428 Byte 0x0A (UTF-8 encoded codepoint 0x0A)
1429 \end_layout
1431 \begin_layout Itemize
1432 Byte 0x0D (UTF-8 encoded codepoint 0x0D)
1433 \end_layout
1435 \begin_layout Itemize
1436 Byte 0x1C (UTF-8 encoded codepoint 0x1C)
1437 \end_layout
1439 \begin_layout Itemize
1440 Byte 0x1D (UTF-8 encoded codepoint 0x1D)
1441 \end_layout
1443 \begin_layout Itemize
1444 Byte 0x1E (UTF-8 encoded codepoint 0x1E)
1445 \end_layout
1447 \begin_layout Itemize
1448 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL, codepoint 0x85)
1449 \end_layout
1451 \begin_layout Itemize
1452 Bytes 0xE2 0x80 0xA9 (UTF-8 encoded codepoint 0x2029)
1453 \end_layout
1455 \begin_layout Subsection
1456 JRSR archive
1457 \end_layout
1459 \begin_layout Standard
1460 JRSR archive format packs multiple text archive members to text archive.
1461  It does not support binary members.
1462  JRSR archives have first five or six bytes form the magic.
1463  It is 
1464 \begin_inset Quotes eld
1465 \end_inset
1467 JRSR
1468 \begin_inset Quotes erd
1469 \end_inset
1471  followed by LINEFEED character There are four kinds of lines after that
1472  (lines are terminated by LINEFEED byte/bytes):
1473 \end_layout
1475 \begin_layout Itemize
1476 Start member
1477 \end_layout
1479 \begin_layout Itemize
1480 Member line
1481 \end_layout
1483 \begin_layout Itemize
1484 End member
1485 \end_layout
1487 \begin_layout Itemize
1488 Blank line
1489 \end_layout
1491 \begin_layout Standard
1492 Sequencing rules are as follows: Start member is allowed anywhere (after
1493  magic).
1494  Member line is allowed only inside member (member started but not ended).
1495  End member is only allowed inside member.
1496  End of file is only allowed outside member.
1497  Blank line is allowed anywhere after magic.
1498 \end_layout
1500 \begin_layout Subsubsection
1501 Start member
1502 \end_layout
1504 \begin_layout Standard
1505 Start member line is given as 
1506 \begin_inset Quotes eld
1507 \end_inset
1509 !BEGIN
1510 \begin_inset Quotes erd
1511 \end_inset
1513  <SPACE>+ <membername> <LINEFEED>.
1514  <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1515  LINEFEED chacter.
1516  The member name is UTF-8 encoded and maximum allowed line length is 2048
1517  bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1518  depending on characters used).
1519  Starting member inside another implicitly ends the previous member.
1520 \end_layout
1522 \begin_layout Subsubsection
1523 Member line:
1524 \end_layout
1526 \begin_layout Standard
1527 Member line is given as 
1528 \begin_inset Quotes eld
1529 \end_inset
1532 \begin_inset Quotes erd
1533 \end_inset
1535 <content><LINEFEED>.
1536  It gives another line for member contents.
1537  <content> is passed raw to layers above (followed by line termination)
1538 \end_layout
1540 \begin_layout Subsubsection
1541 End member
1542 \end_layout
1544 \begin_layout Standard
1545 End member line is given as 
1546 \begin_inset Quotes eld
1547 \end_inset
1549 !END
1550 \begin_inset Quotes erd
1551 \end_inset
1553 <LINEFEED>.
1554  It ends the current member.
1555  The following line can only be start member line or file may end.
1556 \end_layout
1558 \begin_layout Subsubsection
1559 Blank line
1560 \end_layout
1562 \begin_layout Standard
1563 Blank line is given as <LINEFEED>.
1564  Lines like that are ignored.
1565 \end_layout
1567 \begin_layout Subsection
1568 Four-to-Five encoding
1569 \end_layout
1571 \begin_layout Standard
1572 Binary members are encoded into text by so-called four-to-five encoding.
1573  This encoding can encode single byte to two, two bytes to three, three
1574  bytes to four and four bytes to five.
1575  Four-to-five encoding has five kinds of blocks.
1576  All SPACE and LINEFEED characters are completely ignored, even in middle
1577  of blocks.
1578 \end_layout
1580 \begin_layout Subsubsection
1581 End stream block
1582 \end_layout
1584 \begin_layout Standard
1585 End stream block is encoded as '!'.
1586  It ends the stream instantly.
1587  There is also implicit end of stream at end of input to decoding.
1588 \end_layout
1590 \begin_layout Subsubsection
1591 Other four block types
1592 \end_layout
1594 \begin_layout Standard
1595 Other four block types take the value to be encoded, read it as big-endian
1596  value.
1597  Then they write it as base-93 big-endian value.
1598  Then length specific constants are added to digits of that number to yield
1599  ASCII values for characters (those are stored in order):
1600 \end_layout
1602 \begin_layout Standard
1603 \begin_inset Tabular
1604 <lyxtabular version="3" rows="5" columns="6">
1605 <features>
1606 <column alignment="center" valignment="top" width="0">
1607 <column alignment="center" valignment="top" width="0">
1608 <column alignment="center" valignment="top" width="0">
1609 <column alignment="center" valignment="top" width="0">
1610 <column alignment="center" valignment="top" width="0">
1611 <column alignment="center" valignment="top" width="0">
1612 <row>
1613 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1614 \begin_inset Text
1616 \begin_layout Plain Layout
1617 To encode
1618 \end_layout
1620 \end_inset
1621 </cell>
1622 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1623 \begin_inset Text
1625 \begin_layout Plain Layout
1626 1st char.
1627 \end_layout
1629 \end_inset
1630 </cell>
1631 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1632 \begin_inset Text
1634 \begin_layout Plain Layout
1635 2nd char.
1636 \end_layout
1638 \end_inset
1639 </cell>
1640 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1641 \begin_inset Text
1643 \begin_layout Plain Layout
1644 3rd char.
1645 \end_layout
1647 \end_inset
1648 </cell>
1649 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1650 \begin_inset Text
1652 \begin_layout Plain Layout
1653 4th char.
1654 \end_layout
1656 \end_inset
1657 </cell>
1658 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1659 \begin_inset Text
1661 \begin_layout Plain Layout
1662 5th char.
1663 \end_layout
1665 \end_inset
1666 </cell>
1667 </row>
1668 <row>
1669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1670 \begin_inset Text
1672 \begin_layout Plain Layout
1673 1 byte
1674 \end_layout
1676 \end_inset
1677 </cell>
1678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1679 \begin_inset Text
1681 \begin_layout Plain Layout
1683 \end_layout
1685 \end_inset
1686 </cell>
1687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1688 \begin_inset Text
1690 \begin_layout Plain Layout
1692 \end_layout
1694 \end_inset
1695 </cell>
1696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1697 \begin_inset Text
1699 \begin_layout Plain Layout
1701 \end_layout
1703 \end_inset
1704 </cell>
1705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1706 \begin_inset Text
1708 \begin_layout Plain Layout
1710 \end_layout
1712 \end_inset
1713 </cell>
1714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1715 \begin_inset Text
1717 \begin_layout Plain Layout
1719 \end_layout
1721 \end_inset
1722 </cell>
1723 </row>
1724 <row>
1725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1726 \begin_inset Text
1728 \begin_layout Plain Layout
1729 2 bytes
1730 \end_layout
1732 \end_inset
1733 </cell>
1734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1735 \begin_inset Text
1737 \begin_layout Plain Layout
1739 \end_layout
1741 \end_inset
1742 </cell>
1743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1744 \begin_inset Text
1746 \begin_layout Plain Layout
1748 \end_layout
1750 \end_inset
1751 </cell>
1752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1753 \begin_inset Text
1755 \begin_layout Plain Layout
1757 \end_layout
1759 \end_inset
1760 </cell>
1761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1762 \begin_inset Text
1764 \begin_layout Plain Layout
1766 \end_layout
1768 \end_inset
1769 </cell>
1770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1771 \begin_inset Text
1773 \begin_layout Plain Layout
1775 \end_layout
1777 \end_inset
1778 </cell>
1779 </row>
1780 <row>
1781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1782 \begin_inset Text
1784 \begin_layout Plain Layout
1785 3 bytes
1786 \end_layout
1788 \end_inset
1789 </cell>
1790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1791 \begin_inset Text
1793 \begin_layout Plain Layout
1795 \end_layout
1797 \end_inset
1798 </cell>
1799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1800 \begin_inset Text
1802 \begin_layout Plain Layout
1804 \end_layout
1806 \end_inset
1807 </cell>
1808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1809 \begin_inset Text
1811 \begin_layout Plain Layout
1813 \end_layout
1815 \end_inset
1816 </cell>
1817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1818 \begin_inset Text
1820 \begin_layout Plain Layout
1822 \end_layout
1824 \end_inset
1825 </cell>
1826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1827 \begin_inset Text
1829 \begin_layout Plain Layout
1831 \end_layout
1833 \end_inset
1834 </cell>
1835 </row>
1836 <row>
1837 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1838 \begin_inset Text
1840 \begin_layout Plain Layout
1841 4 bytes
1842 \end_layout
1844 \end_inset
1845 </cell>
1846 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1847 \begin_inset Text
1849 \begin_layout Plain Layout
1851 \end_layout
1853 \end_inset
1854 </cell>
1855 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1856 \begin_inset Text
1858 \begin_layout Plain Layout
1860 \end_layout
1862 \end_inset
1863 </cell>
1864 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1865 \begin_inset Text
1867 \begin_layout Plain Layout
1869 \end_layout
1871 \end_inset
1872 </cell>
1873 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1874 \begin_inset Text
1876 \begin_layout Plain Layout
1878 \end_layout
1880 \end_inset
1881 </cell>
1882 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1883 \begin_inset Text
1885 \begin_layout Plain Layout
1887 \end_layout
1889 \end_inset
1890 </cell>
1891 </row>
1892 </lyxtabular>
1894 \end_inset
1897 \end_layout
1899 \begin_layout Standard
1900 Blocks which encode values greater than what is possible for value of that
1901  length are fatal errors.
1903 \end_layout
1905 \begin_layout Subsection
1906 Line component encoing
1907 \end_layout
1909 \begin_layout Standard
1910 Line component encoding sits on top of UTF-8 encoding.
1911  Line component encoding encodes non-empty 1-D array of non-empty strings
1912  into line, and thus array of those into member.
1913  Empty lines or lines that don't contain any components are ignored.
1914  Line starts with depth value of 0 and must end with depth value of zero.
1915 \end_layout
1917 \begin_layout Standard
1918 Components are seperated by component separators.
1919  Empty components are ignored.
1920  Following codepoints are separators on depth 0 if not escaped:
1921 \end_layout
1923 \begin_layout Itemize
1924 Codepoint of '('.
1925  The depth is read pre-increment.
1926 \end_layout
1928 \begin_layout Itemize
1929 Codepoint of ')'.
1930  The depth is read post-decrement.
1931 \end_layout
1933 \begin_layout Itemize
1934 Any SPACE character
1935 \end_layout
1937 \begin_layout Standard
1938 The following characters are special:
1939 \end_layout
1941 \begin_layout Itemize
1942 '('.
1943  Increments depth by 1 if not escaped (and appears in component).
1944 \end_layout
1946 \begin_layout Itemize
1947 ')'.
1948  Decrements depth by 1 if not escaped (and appears in component).
1949  Depth going negative is an error.
1950 \end_layout
1952 \begin_layout Itemize
1954 \backslash
1956  Next character is interpretted as literal.
1957  Error if at end of line.
1958 \end_layout
1960 \begin_layout Standard
1961 Otherwise, characters are interpretted as literals and appear in components.
1962  Depth must be zero at end of line.
1963 \end_layout
1965 \begin_layout Subsection
1966 Header section:
1967 \end_layout
1969 \begin_layout Standard
1970 Header section is in archive member "header".
1971  It uses line component encoding.
1972  The first component of each line is name of header, and subsequent ones
1973  are arguments.
1974  How many parameters are expected is dependent on what header it is:
1975 \end_layout
1977 \begin_layout Subsubsection
1978 PROJECTID header:
1979 \end_layout
1981 \begin_layout Itemize
1982 Header name: "PROJECTID"
1983 \end_layout
1985 \begin_layout Itemize
1986 Components: 2
1987 \end_layout
1989 \begin_layout Itemize
1990 Argument #1: <project-id-string>
1991 \end_layout
1993 \begin_layout Itemize
1994 Mandatory: Yes
1995 \end_layout
1997 \begin_layout Standard
1998 Gives project ID.
1999  Project ID is generated when PC is assembled and is then preserved in save
2000  states.
2001  It is used for computing rerecord counts.
2002  Emulator treats it as opaque string, the IDs it generates are formed by
2003  48 random hexadecimal digits.
2004 \end_layout
2006 \begin_layout Subsubsection
2007 SAVESTATEID header:
2008 \end_layout
2010 \begin_layout Itemize
2011 Header name: "SAVESTATEID"
2012 \end_layout
2014 \begin_layout Itemize
2015 Components: 2
2016 \end_layout
2018 \begin_layout Itemize
2019 Argument #1: <savestate-id-string>
2020 \end_layout
2022 \begin_layout Itemize
2023 Mandatory: No
2024 \end_layout
2026 \begin_layout Standard
2027 Gives save state ID.
2028  Each save state has its own save state ID.
2029  Treated as opaque string, but generated as 48 random hexadecimal digits.
2030  The presence of this header signals whether there is save state to be loaded.
2031  If this header is present, save state load will be attempted.
2032  If absent, save state is not to be loaded even if present (and correct
2033  savestate load would be technically impossible anyway).
2034 \end_layout
2036 \begin_layout Standard
2037 The value is used to prevent loading incompatible save states in preserve
2038  event stream mode and also to find the point in event stream where one
2039  left off.
2040 \end_layout
2042 \begin_layout Subsubsection
2043 RERECORDS header:
2044 \end_layout
2046 \begin_layout Itemize
2047 Header name: "RERECORDS"
2048 \end_layout
2050 \begin_layout Itemize
2051 Components: 2
2052 \end_layout
2054 \begin_layout Itemize
2055 Argument #1: <rerecords>
2056 \end_layout
2058 \begin_layout Itemize
2059 Mandatory: Yes
2060 \end_layout
2062 \begin_layout Standard
2063 Gives rerecord count.
2064  PC assembly (except when loading save state) initializes current rerecord
2065  count to zero.
2066  Must be non-negative and decimal number using ASCII digit characters.
2067 \end_layout
2069 \begin_layout LyX-Code
2070 On loading save state:
2071 \end_layout
2073 \begin_layout LyX-Code
2074 1) If project ID matches with previous:
2075 \end_layout
2077 \begin_layout LyX-Code
2078 1a) If loaded rerecord count is larger or equal to current rerecord count:
2079 \end_layout
2081 \begin_layout LyX-Code
2082 1a-a) Current rerecord count is loaded rerecord count + 1.
2083 \end_layout
2085 \begin_layout LyX-Code
2086 1b) Otherwise
2087 \end_layout
2089 \begin_layout LyX-Code
2090 1b-a) Current rerecord count increments by 1.
2091 \end_layout
2093 \begin_layout LyX-Code
2094 2) Otherwise
2095 \end_layout
2097 \begin_layout LyX-Code
2098 2a) Current rerecord count is loaded rerecord count + 1.
2099 \end_layout
2101 \begin_layout Standard
2102 The current rerecord count at time of save is saved to save state.
2103 \end_layout
2105 \begin_layout Subsubsection
2106 AUTHORS header:
2107 \end_layout
2109 \begin_layout Itemize
2110 Header name: "AUTHORS"
2111 \end_layout
2113 \begin_layout Itemize
2114 Components: 2 or more
2115 \end_layout
2117 \begin_layout Itemize
2118 Arguments: free form
2119 \end_layout
2121 \begin_layout Itemize
2122 Mandatory: No
2123 \end_layout
2125 \begin_layout Standard
2126 Gives authors of run.
2127  Each argument gives one author.
2128  May be present multiple times.
2129 \end_layout
2131 \begin_layout Subsubsection
2132 COMMENT header:
2133 \end_layout
2135 \begin_layout Itemize
2136 Header name: "COMMENT"
2137 \end_layout
2139 \begin_layout Itemize
2140 Components: 2 or more
2141 \end_layout
2143 \begin_layout Itemize
2144 Arguments: free form
2145 \end_layout
2147 \begin_layout Itemize
2148 Mandatory: No
2149 \end_layout
2151 \begin_layout Standard
2152 Various kinds of free form data.
2153  Not parsed further by emulator.
2154 \end_layout
2156 \begin_layout Subsection
2157 Initialization segment:
2158 \end_layout
2160 \begin_layout Standard
2161 If SAVESTATEID header isn't present (not a save state), member "initialization"
2162  gives PC initialization parameters for assembling the PC.
2163  It is present anyway even if SAVESTATEID is present (savestate).
2164 \end_layout
2166 \begin_layout Standard
2167 Following parameters are used (space separates components):
2168 \end_layout
2170 \begin_layout LyX-Code
2171 "BIOS" <id>
2172 \end_layout
2174 \begin_layout Standard
2175 Gives Image ID of main system BIOS (mandatory)
2176 \end_layout
2178 \begin_layout LyX-Code
2179 "VGABIOS" <id>
2180 \end_layout
2182 \begin_layout Standard
2183 Gives Image ID of VGA BIOS (mandatory).
2184 \end_layout
2186 \begin_layout LyX-Code
2187 "HDA" <id>
2188 \end_layout
2190 \begin_layout Standard
2191 Gives Image ID of hda.
2192  Present only if system has hard disk hda.
2193 \end_layout
2195 \begin_layout LyX-Code
2196 "HDB" <id>
2197 \end_layout
2199 \begin_layout Standard
2200 Gives Image ID of hdb.
2201  Present only if system has hard disk hdb.
2202 \end_layout
2204 \begin_layout LyX-Code
2205 "HDC" <id>
2206 \end_layout
2208 \begin_layout Standard
2209 Gives Image ID of hdc.
2210  Present only if system has hard disk hdc.
2211 \end_layout
2213 \begin_layout LyX-Code
2214 "HDD" <id>
2215 \end_layout
2217 \begin_layout Standard
2218 Gives Image ID of hdd.
2219  Present only if system has hard disk hdd.
2220 \end_layout
2222 \begin_layout LyX-Code
2223 "DISK" <num> <id>
2224 \end_layout
2226 \begin_layout Standard
2227 Gives Image ID of disk in slot <num>.
2228  Slot number must be non-negative.
2229 \end_layout
2231 \begin_layout LyX-Code
2232 \begin_inset Quotes eld
2233 \end_inset
2235 DISKNAME
2236 \begin_inset Quotes erd
2237 \end_inset
2239  <num> <name>
2240 \end_layout
2242 \begin_layout Standard
2243 kGives image name of disk in slot <num>.
2244  Slot number must be non-negative.
2245  The slot must be previously declared using 
2246 \begin_inset Quotes eld
2247 \end_inset
2249 DISK
2250 \begin_inset Quotes erd
2251 \end_inset
2254 \end_layout
2256 \begin_layout LyX-Code
2257 "FDA" <num>
2258 \end_layout
2260 \begin_layout Standard
2261 Gives Image slot to initially put into floppy drive fda.
2262  Disk must be of floppy type.
2263  If none present, no disk is initially put there.
2264 \end_layout
2266 \begin_layout LyX-Code
2267 "FDB" <num>
2268 \end_layout
2270 \begin_layout Standard
2271 Gives Image slot to initially put into floppy drive fdb.
2272  Disk must be of floppy type.
2273  If none present, no disk is initially put there.
2274 \end_layout
2276 \begin_layout LyX-Code
2277 "CDROM" <num>
2278 \end_layout
2280 \begin_layout Standard
2281 Gives Image slot to initially put into CD-ROM drive hdc.
2282  Not allowed if hard disk hdc is present.
2283  Disk must be of CD-ROM type.
2284  If none present no disk is initially put there.
2285 \end_layout
2287 \begin_layout LyX-Code
2288 "INITIALTIME" <time>
2289 \end_layout
2291 \begin_layout Standard
2292 Number of milliseconds since Unix epoch to system start up time.
2293  Allowed range:
2294 \end_layout
2296 \begin_layout Standard
2297 0-4102444799999.
2298  Mandatory.
2299 \end_layout
2301 \begin_layout LyX-Code
2302 "CPUDIVIDER" <divider>
2303 \end_layout
2305 \begin_layout Standard
2306 Set CPU frequency divider (dividing the 1GHz master clock).
2307  Allowed range is 1-256.
2308  Mandatory.
2309 \end_layout
2311 \begin_layout LyX-Code
2312 "MEMORYSIZE" <pages>
2313 \end_layout
2315 \begin_layout Standard
2316 Number of 4KiB pages of RAM memory.
2317  Allowed range 256-262144.
2318  Mandatory.
2319 \end_layout
2321 \begin_layout LyX-Code
2322 "BOOT" <device>
2323 \end_layout
2325 \begin_layout Standard
2326 Set boot device.
2327  Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2328  (boot from CD).
2329 \end_layout
2331 \begin_layout LyX-Code
2332 "LOADMODULEA" <module> <parameters>
2333 \end_layout
2335 \begin_layout Standard
2336 Load module <module> with parameters <parameters>.
2337 \end_layout
2339 \begin_layout LyX-Code
2340 "LOADMODULE" <module>
2341 \end_layout
2343 \begin_layout Standard
2344 Load module <module> with no parameters
2345 \end_layout
2347 \begin_layout LyX-Code
2348 \begin_inset Quotes eld
2349 \end_inset
2352 \begin_inset Quotes erd
2353 \end_inset
2355  <fpu>
2356 \end_layout
2358 \begin_layout Standard
2359 Use class <fpu> as FPU emulator.
2360 \end_layout
2362 \begin_layout LyX-Code
2363 \begin_inset Quotes eld
2364 \end_inset
2366 IOPORTDELAY
2367 \begin_inset Quotes erd
2368 \end_inset
2371 \end_layout
2373 \begin_layout Standard
2374 Use I/O port delay emulation (each I/O port read/write takes 666ns).
2375 \end_layout
2377 \begin_layout LyX-Code
2378 \begin_inset Quotes eld
2379 \end_inset
2381 VGAHRETRACE
2382 \begin_inset Quotes erd
2383 \end_inset
2386 \end_layout
2388 \begin_layout Standard
2389 Emulate VGA horizontal retrace.
2390 \end_layout
2392 \begin_layout Subsection
2393 Event record format:
2394 \end_layout
2396 \begin_layout Standard
2397 Event record is in archive member "events".
2398  It uses line component encoding.
2399  Each line gives an event.
2400  First component of each line gives time stamp.
2401  These timestamps MUST be in increasing order and all MUST be non-negative.
2402  Time stamp time unit is exactly 1 nanosecond of emulated time.
2403 \end_layout
2405 \begin_layout Standard
2406 The second component of each line is name of class to dispatch to.
2407  Further components are passed as-is to event handlers.
2408  Classes with names consisting only of uppercase A-Z and 0-9 are special
2409  and reserved.
2410  It is error to encounter unknown such special class.
2411 \end_layout
2413 \begin_layout Subsubsection
2414 Savestate event
2415 \end_layout
2417 \begin_layout Itemize
2418 Dispatch to: SAVESTATE
2419 \end_layout
2421 \begin_layout Itemize
2422 Argument #1: Savestate id
2423 \end_layout
2425 \begin_layout Itemize
2426 Argument #2 (optional): Rerecord count at time of saving savestate
2427 \end_layout
2429 \begin_layout Standard
2430 Signals that savestate has occured here.
2431  The save state IDs MUST be unique in entire event stream.
2432  The second argument to savestate (if present) is rerecord count at time
2433  of saving that savestate (useful for calulating rerecord count of movie
2434  starting from savestate).
2435  No time restrictions
2436 \end_layout
2438 \begin_layout Subsubsection
2439 Option event
2440 \end_layout
2442 \begin_layout Itemize
2443 Dispatch to: OPTION
2444 \end_layout
2446 \begin_layout Itemize
2447 Argument #1: 
2448 \begin_inset Quotes eld
2449 \end_inset
2451 ABSOLUTE
2452 \begin_inset Quotes erd
2453 \end_inset
2455  or 
2456 \begin_inset Quotes eld
2457 \end_inset
2459 RELATIVE
2460 \begin_inset Quotes erd
2461 \end_inset
2464 \end_layout
2466 \begin_layout Standard
2467 Controls various options.
2469 \begin_inset Quotes eld
2470 \end_inset
2472 ABSOLUTE
2473 \begin_inset Quotes erd
2474 \end_inset
2476  turns on absolute mode (default) where event timestamps are absolute.
2478 \begin_inset Quotes eld
2479 \end_inset
2481 RELATIVE
2482 \begin_inset Quotes erd
2483 \end_inset
2485  turns on relative mode where event timestamps are relative to last event
2486  in stream.
2487  The OPTION event itself is not affected by timing change.
2488  No time restrictions.
2489  Unknown arguments are errors.
2490 \end_layout
2492 \begin_layout Subsubsection
2493 Keyboard keypress/keyrelease event:
2494 \end_layout
2496 \begin_layout Itemize
2497 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2498 \end_layout
2500 \begin_layout Itemize
2501 Argument #1: Fixed: "KEYEDGE"
2502 \end_layout
2504 \begin_layout Itemize
2505 Argument #2: Key number.
2506  Valid values are 1-83, 85-95, 129-197 and 199-223
2507 \end_layout
2509 \begin_layout Standard
2510 Send key press or key release.
2511  Keys work in toggle button manner.
2512  The event time must be multiple of 66 666, and must not be less than 60
2513  * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2514  on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2515 \end_layout
2517 \begin_layout Subsubsection
2518 Pause event:
2519 \end_layout
2521 \begin_layout Itemize
2522 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2523 \end_layout
2525 \begin_layout Itemize
2526 Argument #1: Fixed: "PAUSE"
2527 \end_layout
2529 \begin_layout Standard
2530 Send pause key event.
2531  The time restrictions are identical to KEYEDGE event.
2532 \end_layout
2534 \begin_layout Subsubsection
2535 Mouse button event:
2536 \end_layout
2538 \begin_layout Itemize
2539 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2540 \end_layout
2542 \begin_layout Itemize
2543 Argument #1: Fixed: "MOUSEBUTTON"
2544 \end_layout
2546 \begin_layout Itemize
2547 Argument #2: Number of button to release or press (0-4)
2548 \end_layout
2550 \begin_layout Standard
2551 Presses or releases the designated mouse button.
2552 \end_layout
2554 \begin_layout Subsubsection
2555 X mouse motion event:
2556 \end_layout
2558 \begin_layout Itemize
2559 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2560 \end_layout
2562 \begin_layout Itemize
2563 Argument #1: Fixed: "XMOUSEMOTION"
2564 \end_layout
2566 \begin_layout Itemize
2567 Argument #2: Number of units to move (-255 - 255)
2568 \end_layout
2570 \begin_layout Standard
2571 Move the mouse in X direction by specified amount.
2572  Positive is right.
2573 \end_layout
2575 \begin_layout Subsubsection
2576 Y mouse motion event:
2577 \end_layout
2579 \begin_layout Itemize
2580 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2581 \end_layout
2583 \begin_layout Itemize
2584 Argument #1: Fixed: "YMOUSEMOTION"
2585 \end_layout
2587 \begin_layout Itemize
2588 Argument #2: Number of units to move (-255 - 255)
2589 \end_layout
2591 \begin_layout Standard
2592 Move the mouse in Y direction by specified amount.
2593  Positive is up.
2594 \end_layout
2596 \begin_layout Subsubsection
2597 Z mouse motion event:
2598 \end_layout
2600 \begin_layout Itemize
2601 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2602 \end_layout
2604 \begin_layout Itemize
2605 Argument #1: Fixed: "ZMOUSEMOTION"
2606 \end_layout
2608 \begin_layout Itemize
2609 Argument #2: Number of units to move (-7 - 7)
2610 \end_layout
2612 \begin_layout Standard
2613 Move the mouse in Z direction (scrollwheel) by specified amount.
2614 \end_layout
2616 \begin_layout Subsubsection
2617 Joystick button event:
2618 \end_layout
2620 \begin_layout Itemize
2621 Dispatch to: org.jpc.modules.Joystick
2622 \end_layout
2624 \begin_layout Itemize
2625 Argument #1: 
2626 \begin_inset Quotes eld
2627 \end_inset
2629 BUTTONA
2630 \begin_inset Quotes erd
2631 \end_inset
2634 \begin_inset Quotes eld
2635 \end_inset
2637 BUTTONB
2638 \begin_inset Quotes erd
2639 \end_inset
2642 \begin_inset Quotes eld
2643 \end_inset
2645 BUTTONC
2646 \begin_inset Quotes erd
2647 \end_inset
2649  or 
2650 \begin_inset Quotes eld
2651 \end_inset
2653 BUTTOND
2654 \begin_inset Quotes erd
2655 \end_inset
2658 \end_layout
2660 \begin_layout Itemize
2661 Argument #2: 
2662 \begin_inset Quotes eld
2663 \end_inset
2666 \begin_inset Quotes erd
2667 \end_inset
2669  if released, 
2670 \begin_inset Quotes eld
2671 \end_inset
2674 \begin_inset Quotes erd
2675 \end_inset
2677  if pressed
2678 \end_layout
2680 \begin_layout Standard
2681 Send button down/up event.
2682  No time restrictions.
2683 \end_layout
2685 \begin_layout Subsubsection
2686 Joystick axis event:
2687 \end_layout
2689 \begin_layout Itemize
2690 Dispatch to: org.jpc.modules.Joystick
2691 \end_layout
2693 \begin_layout Itemize
2694 Argument #1: 
2695 \begin_inset Quotes eld
2696 \end_inset
2698 AXISA
2699 \begin_inset Quotes erd
2700 \end_inset
2703 \begin_inset Quotes eld
2704 \end_inset
2706 AXISB
2707 \begin_inset Quotes erd
2708 \end_inset
2711 \begin_inset Quotes eld
2712 \end_inset
2714 AXISC
2715 \begin_inset Quotes erd
2716 \end_inset
2718  or 
2719 \begin_inset Quotes eld
2720 \end_inset
2722 AXISD
2723 \begin_inset Quotes erd
2724 \end_inset
2727 \end_layout
2729 \begin_layout Itemize
2730 Argument #2: Multivibrator unstable state length in ns.
2731 \end_layout
2733 \begin_layout Standard
2734 Set amount of time multivibrator remains in unstable state.
2735  No time restrictions.
2736 \end_layout
2738 \begin_layout Subsubsection
2739 Reboot:
2740 \end_layout
2742 \begin_layout Itemize
2743 Dispatch to: org.jpc.emulator.PC$ResetButton
2744 \end_layout
2746 \begin_layout Itemize
2747 No arguments
2748 \end_layout
2750 \begin_layout Standard
2751 Reboots the PC.
2752 \end_layout
2754 \begin_layout Subsubsection
2755 Fda disk change:
2756 \end_layout
2758 \begin_layout Itemize
2759 Dispatch to: org.jpc.emulator.PC$DiskChanger
2760 \end_layout
2762 \begin_layout Itemize
2763 Argument #1: Fixed: "FDA"
2764 \end_layout
2766 \begin_layout Itemize
2767 Argument #2: Number of image slot to put there.
2769 \end_layout
2771 \begin_layout Standard
2772 The disk number MUST be -1 or valid disk number.
2773  -1 MUST NOT be used if there is no disk in floppy drive A.
2774  This event causes specified disk to be placed to FDA or FDA disk to be
2775  ejected with no replacement if disk number is -1.
2776  The specified disk if not -1 must be of floppy type.
2777  The specified disk if valid must not be in any other drive.
2778 \end_layout
2780 \begin_layout Subsubsection
2781 Fdb disk change:
2782 \end_layout
2784 \begin_layout Itemize
2785 Dispatch to: org.jpc.emulator.PC$DiskChanger
2786 \end_layout
2788 \begin_layout Itemize
2789 Argument #1: Fixed: "FDB"
2790 \end_layout
2792 \begin_layout Itemize
2793 Argument #2: Number of image slot to put there.
2795 \end_layout
2797 \begin_layout Standard
2798 The disk number MUST be -1 or valid disk number.
2799  -1 MUST NOT be used if there is no disk in floppy drive B.
2800  This event causes specified disk to be placed to FDB or FDB disk to be
2801  ejected with no replacement if disk number is -1.
2802  The specified disk if not -1 must be of floppy type.
2803  The specified disk if valid must not be in any other drive.
2804 \end_layout
2806 \begin_layout Subsubsection
2807 Change CDROM:
2808 \end_layout
2810 \begin_layout Itemize
2811 Dispatch to: org.jpc.emulator.PC$DiskChanger
2812 \end_layout
2814 \begin_layout Itemize
2815 Argument #1: Fixed: "CDROM"
2816 \end_layout
2818 \begin_layout Itemize
2819 Argument #2: Number of image slot to put there.
2821 \end_layout
2823 \begin_layout Standard
2824 The disk number MUST be -1 or valid disk number.
2825  -1 MUST NOT be used if there is no disk in CD-ROM.
2826  This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2827  to be ejected with no replacement if disk number is -1.
2828  The specified disk if not -1 must be of CD-ROM type.
2829 \end_layout
2831 \begin_layout Standard
2832 This event has no effect if CD-ROM is locked.
2833 \end_layout
2835 \begin_layout Subsubsection
2836 Write protect floppy:
2837 \end_layout
2839 \begin_layout Itemize
2840 Dispatch to: org.jpc.emulator.PC$DiskChanger
2841 \end_layout
2843 \begin_layout Itemize
2844 Argument #1: Fixed: "WRITEPROTECT"
2845 \end_layout
2847 \begin_layout Itemize
2848 Argument #2: Number of image slot to manipulate 
2849 \end_layout
2851 \begin_layout Standard
2852 Write protects specified disk.
2853  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2854 \end_layout
2856 \begin_layout Subsubsection
2857 Write unprotect floppy:
2858 \end_layout
2860 \begin_layout Itemize
2861 Dispatch to: org.jpc.emulator.PC$DiskChanger
2862 \end_layout
2864 \begin_layout Itemize
2865 Argument #1: Fixed: "WRITEUNPROTECT"
2866 \end_layout
2868 \begin_layout Itemize
2869 Argument #2: Number of image slot to manipulate 
2870 \end_layout
2872 \begin_layout Standard
2873 Disables write protection specified disk.
2874  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2875 \end_layout
2877 \begin_layout Subsection
2878 Diskinfo sections
2879 \end_layout
2881 \begin_layout Standard
2882 Diskinfo sections are named 
2883 \begin_inset Quotes eld
2884 \end_inset
2886 diskinfo-
2887 \begin_inset Quotes erd
2888 \end_inset
2890 <id of disk>.
2891  They use line component encoding, fieldtype being first component on each
2892  line (value being the second).
2893  Following fields are defined:
2894 \end_layout
2896 \begin_layout Subsubsection
2897 TYPE
2898 \end_layout
2900 \begin_layout Standard
2901 Gives type of image.
2902  Possible values are
2903 \end_layout
2905 \begin_layout Itemize
2906 \begin_inset Quotes eld
2907 \end_inset
2909 FLOPPY
2910 \begin_inset Quotes erd
2911 \end_inset
2913  (floppy disk)
2914 \end_layout
2916 \begin_layout Itemize
2917 \begin_inset Quotes eld
2918 \end_inset
2921 \begin_inset Quotes erd
2922 \end_inset
2924  (Hard disk)
2925 \end_layout
2927 \begin_layout Itemize
2928 \begin_inset Quotes eld
2929 \end_inset
2931 CDROM
2932 \begin_inset Quotes erd
2933 \end_inset
2935  (CD-ROM)
2936 \end_layout
2938 \begin_layout Itemize
2939 \begin_inset Quotes eld
2940 \end_inset
2942 BIOS
2943 \begin_inset Quotes erd
2944 \end_inset
2946  (BIOS/VGABIOS image)
2947 \end_layout
2949 \begin_layout Itemize
2950 \begin_inset Quotes eld
2951 \end_inset
2953 UNKNOWN
2954 \begin_inset Quotes erd
2955 \end_inset
2957  (what the heck is this???)
2958 \end_layout
2960 \begin_layout Subsubsection
2962 \end_layout
2964 \begin_layout Standard
2965 Gives ID of disk.
2966 \end_layout
2968 \begin_layout Subsubsection
2969 IMAGELENGTH
2970 \end_layout
2972 \begin_layout Standard
2973 (BIOS images only) Gives length of BIOS image
2974 \end_layout
2976 \begin_layout Subsubsection
2977 IMAGEMD5
2978 \end_layout
2980 \begin_layout Standard
2981 MD5 of raw disk/BIOS image without any headers or trailers.
2982 \end_layout
2984 \begin_layout Subsubsection
2985 TOTALSECTORS
2986 \end_layout
2988 \begin_layout Standard
2989 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
2990 \end_layout
2992 \begin_layout Subsubsection
2993 TRACKS
2994 \end_layout
2996 \begin_layout Standard
2997 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
2998  1-1024 for HDD).
2999 \end_layout
3001 \begin_layout Subsubsection
3002 SIDES
3003 \end_layout
3005 \begin_layout Standard
3006 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
3007  for HDD).
3008 \end_layout
3010 \begin_layout Subsubsection
3011 SECTORS
3012 \end_layout
3014 \begin_layout Standard
3015 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
3016  1-63 for HDD).
3017 \end_layout
3019 \begin_layout Subsubsection
3020 COMMENT
3021 \end_layout
3023 \begin_layout Standard
3024 Line from image comment block.
3025  Usually give data about files image has.
3026  May or may not be present (multiple times)
3027 \end_layout
3029 \begin_layout Subsection
3030 Output info
3031 \end_layout
3033 \begin_layout Standard
3034 Output info is stored in section 
3035 \begin_inset Quotes eld
3036 \end_inset
3038 output-info
3039 \begin_inset Quotes erd
3040 \end_inset
3043  Its relatively new, so it might not be present (then the contents have
3044  to be guessed based on modules present).
3045  Each line gives information about one output, first field being the type
3046  of output.
3047 \end_layout
3049 \begin_layout Subsubsection
3050 Video output
3051 \end_layout
3053 \begin_layout Standard
3054 For video output, there are no parameters so line is just 
3055 \begin_inset Quotes eld
3056 \end_inset
3058 VIDEO
3059 \begin_inset Quotes erd
3060 \end_inset
3062  (one component).
3063 \end_layout
3065 \begin_layout Subsubsection
3066 Audio output
3067 \end_layout
3069 \begin_layout Standard
3070 For audio output, the only parameter is name of output, so first component
3071  is 
3072 \begin_inset Quotes eld
3073 \end_inset
3075 AUDIO
3076 \begin_inset Quotes erd
3077 \end_inset
3079  and second component is name of audio output.
3080 \end_layout
3082 \begin_layout Subsection
3083 Savestates
3084 \end_layout
3086 \begin_layout Standard
3087 Actual savestate format is not documented here.
3088  It is close to impossible to comprehend without access to emulator source
3089  anyway.
3090 \end_layout
3092 \begin_layout Section
3093 Advanced: Making class dumpable
3094 \end_layout
3096 \begin_layout Standard
3097 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
3098  and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
3099  <init>(org.jpc.emulator.SRLoader).
3100  Non-static inner classes can not be dumpable (make them static using tricks
3101  similar to what javac uses).
3102 \end_layout
3104 \begin_layout Standard
3105 If dumped class has dumpable superclass, the first thing dumping function
3106  needs to do is to call dumper function of superclass and first thing loading
3107  constructor needs to do is to call loading constructor of superclass.
3108  If class has no dumpable superclass, dumper doesn't need to do anything
3109  special, while loader needs to call objectCreated(this) on SRLoader object
3110  passed as parameter.
3112 \end_layout
3114 \begin_layout Standard
3115 Following these fixed parts, dump all members that are part of mutable state
3116  in emulator core.
3117 \end_layout
3119 \begin_layout Subsection
3120 Member dumping/loading functions
3121 \end_layout
3123 \begin_layout Standard
3124 There is dumping/loading function for following (all functions dumping/loading
3125  reference types can handle null):
3126 \end_layout
3128 \begin_layout Itemize
3129 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
3130 \end_layout
3132 \begin_layout Itemize
3133 byte: SRDumper.dumpByte, SRLoader.loadByte
3134 \end_layout
3136 \begin_layout Itemize
3137 short: SRDumper.dumpShort, SRLoader.loadShort
3138 \end_layout
3140 \begin_layout Itemize
3141 int: SRDumper.dumpInt, SRLoader.loadInt
3142 \end_layout
3144 \begin_layout Itemize
3145 long: SRDumper.dumpLong, SRLoader.loadLong
3146 \end_layout
3148 \begin_layout Itemize
3149 String: SRDumper.dumpString, SRLoader.loadString
3150 \end_layout
3152 \begin_layout Itemize
3153 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
3154 \end_layout
3156 \begin_layout Itemize
3157 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
3158 \end_layout
3160 \begin_layout Itemize
3161 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
3162 \end_layout
3164 \begin_layout Itemize
3165 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
3166 \end_layout
3168 \begin_layout Itemize
3169 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
3170 \end_layout
3172 \begin_layout Itemize
3173 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
3174 \end_layout
3176 \begin_layout Itemize
3177 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
3178 \end_layout
3180 \begin_layout Itemize
3181 special object: SRDumper.specialObject, SRLoader.specialObject
3182 \end_layout
3184 \begin_layout Subsubsection
3185 Notes:
3186 \end_layout
3188 \begin_layout Itemize
3189 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
3190 \end_layout
3192 \begin_layout Itemize
3193 Special objects are various static objects that don't need to be stored
3194  because they don't have mutable fields.
3195 \end_layout
3197 \begin_layout Itemize
3198 Don't dump fields related to event state feedback.
3199 \end_layout
3201 \begin_layout Itemize
3202 Don't dump temporary flags that are only used while PC is running.
3203  Savestate when PC is running isn't possible anyway.
3204 \end_layout
3206 \begin_layout Itemize
3207 Some connectors dump fields related to connector output, some don't.
3208 \end_layout
3210 \begin_layout Section
3211 Advanced: Making output connectors
3212 \end_layout
3214 \begin_layout Standard
3215 Implementing interface org.jpc.emulator.DisplayController signals that this
3216  is display controller, inhibiting loading of the standard VGA display controlle
3217 r if loaded as module.
3219 \end_layout
3221 \begin_layout Subsection
3222 Interface org.jpc.emulator.OutputConnector
3223 \end_layout
3225 \begin_layout Standard
3226 Class is made to be output connector by implementing this interface.
3227  This interface specifies the methods used for output hold locking.
3228  Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3229  that are suitable for calling.
3231 \end_layout
3233 \begin_layout Subsubsection
3234 Method subscribeOutput(Object)
3235 \end_layout
3237 \begin_layout Standard
3238 Subscribes the output, with specified object as handle.
3239 \end_layout
3241 \begin_layout Subsubsection
3242 Method unsubscribeOutput(Object)
3243 \end_layout
3245 \begin_layout Standard
3246 Unsubscribe the specified handle object from output.
3247 \end_layout
3249 \begin_layout Subsubsection
3250 Method waitOutput(Object)
3251 \end_layout
3253 \begin_layout Standard
3254 Wait for output on specified connector using specified handle object.
3255  Returns true on success, false if wait was interrupted by thread interrupt.
3256  Blocking.
3257 \end_layout
3259 \begin_layout Subsubsection
3260 Method releaseOutput(Object)
3261 \end_layout
3263 \begin_layout Standard
3264 Release connector from p.o.v.
3265  of given handle.
3266  Does not block.
3267 \end_layout
3269 \begin_layout Subsubsection
3270 Method holdOutput()
3271 \end_layout
3273 \begin_layout Standard
3274 Release threads waiting on waitOutput() and block until all subscribers
3275  have returned from waitOutput() and enteired releaseOutput().
3276 \end_layout
3278 \begin_layout Subsubsection
3279 Method releaseOutputWaitAll(object)
3280 \end_layout
3282 \begin_layout Standard
3283 Like releaseOutput(), but waits until all handles have released their output.
3284 \end_layout
3286 \begin_layout Subsection
3287 Class org.jpc.emulator.VGADigtalOut
3288 \end_layout
3290 \begin_layout Standard
3291 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3292  VGA output connector.
3293  If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3294 yController.
3295 \end_layout
3297 \begin_layout Subsubsection
3298 Method getWidth()
3299 \end_layout
3301 \begin_layout Standard
3302 Get width of display (watch out, can return 0).
3303 \end_layout
3305 \begin_layout Subsubsection
3306 Method getHeight()
3307 \end_layout
3309 \begin_layout Standard
3310 Get height of display (watch out, can return 0).
3311 \end_layout
3313 \begin_layout Subsubsection
3314 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3315 \end_layout
3317 \begin_layout Standard
3318 Returns the dirty region (region modified since last output).
3319 \end_layout
3321 \begin_layout Subsubsection
3322 Method getBuffer()
3323 \end_layout
3325 \begin_layout Standard
3326 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3327  one value per pixel) giving pixel data.
3328  Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3329  + <blue-component>.
3330 \end_layout
3332 \begin_layout Subsubsection
3333 Method resizeDisplay(int _width, int _height)
3334 \end_layout
3336 \begin_layout Standard
3337 Resize the display to be of specified size.
3338 \end_layout
3340 \begin_layout Subsubsection
3341 Method dirtyDisplayRegion(int x, int y, int w, int h)
3342 \end_layout
3344 \begin_layout Standard
3345 Mark the specified region as dirty.
3346 \end_layout
3348 \begin_layout Subsubsection
3349 Method resetDirtyRegion()
3350 \end_layout
3352 \begin_layout Standard
3353 Resets the dirty region to be empty.
3354 \end_layout
3356 \begin_layout Subsection
3357 Class org.jpc.emulator.PC method getVideoOutput()
3358 \end_layout
3360 \begin_layout Standard
3361 Get VGA output connector for PC.
3362 \end_layout
3364 \begin_layout Subsection
3365 Interface org.jpc.emulator.DisplayController.
3366 \end_layout
3368 \begin_layout Standard
3369 Implementing this class signals that module is VGA controller.
3370  There can be only one such module active at time and presence of such module
3371  prevents loading builtin VGA controller emulation code.
3372 \end_layout
3374 \begin_layout Subsubsection
3375 Method getOutputDevice()
3376 \end_layout
3378 \begin_layout Standard
3379 Get VGA output connector for this VGA device.
3380 \end_layout
3382 \begin_layout Subsection
3383 Class org.jpc.emulator.SoundDigitalOut
3384 \end_layout
3386 \begin_layout Standard
3387 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3388  Each connector can transfer stereo signal at arbitiary sampling rate.
3389  Modules that have audio connectors need to implement interface org.jpc.emulator.So
3390 undOutputDevice, as this signals that output connectors should be created.
3391 \end_layout
3393 \begin_layout Subsubsection
3394 Method addSample(long, short, short)
3395 \end_layout
3397 \begin_layout Standard
3398 Add stereo sample at time given by first argument.
3399  The second and third arguments give volume on left and right channels.
3400 \end_layout
3402 \begin_layout Subsubsection
3403 Method addSample(long, short)
3404 \end_layout
3406 \begin_layout Standard
3407 Add mono sample at time given by first argument.
3408  The second argument give volume on both channels.
3409 \end_layout
3411 \begin_layout Subsubsection
3412 Method readBlock(Block)
3413 \end_layout
3415 \begin_layout Standard
3416 Reads block of output (atomic versus addSample).
3417  Block structure has following fields which are filled:
3418 \end_layout
3420 \begin_layout Itemize
3421 timeBase: Time base for block.
3422 \end_layout
3424 \begin_layout Itemize
3425 baseLeft: Left volume at time base.
3426 \end_layout
3428 \begin_layout Itemize
3429 baseRight: Right volume at time base
3430 \end_layout
3432 \begin_layout Itemize
3433 blockNo: Sequence number of block filled.
3434 \end_layout
3436 \begin_layout Itemize
3437 samples: Number of samples in block
3438 \end_layout
3440 \begin_layout Itemize
3441 sampleTiming: Number of nanoseconds since last sample
3442 \end_layout
3444 \begin_layout Itemize
3445 sampleLeft: Left channel samples
3446 \end_layout
3448 \begin_layout Itemize
3449 sampleRight: Right channel samples
3450 \end_layout
3452 \begin_layout Subsection
3453 Interface org.jpc.emulator.SoundOutputDevice
3454 \end_layout
3456 \begin_layout Standard
3457 Implementing this interface signals that module has audio output channels.
3458 \end_layout
3460 \begin_layout Subsubsection
3461 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3462 \end_layout
3464 \begin_layout Standard
3465 Return the number of sound channels module has.
3466 \end_layout
3468 \begin_layout Subsubsection
3469 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3470 \end_layout
3472 \begin_layout Standard
3473 This is called once per sound channel requested giving precreated sound
3474  channel.
3475 \end_layout
3477 \begin_layout Subsection
3478 Class org.jpc.emulator.PC method getSoundOut(String)
3479 \end_layout
3481 \begin_layout Standard
3482 Get sound output with specified name.
3483 \end_layout
3485 \begin_layout Section
3486 Advanced: Writing event targets
3487 \end_layout
3489 \begin_layout Standard
3490 Whereas output connectors are the way output is dispatched, input is dispatched
3491  via event targets.
3492  Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3493 \end_layout
3495 \begin_layout Standard
3496 Event targets also provode methods which then encode events and dispatch
3497  them forward (without doing anything else) to event recorder.
3498  Also, event targets may have methods for obtaining state.
3499 \end_layout
3501 \begin_layout Subsection
3502 Interface org.jpc.emulator.EventDispatchTarget
3503 \end_layout
3505 \begin_layout Standard
3506 Interface that marks class capable of receiving events.
3507 \end_layout
3509 \begin_layout Subsubsection
3510 Method setEventRecorder(EventRecorder)
3511 \end_layout
3513 \begin_layout Standard
3514 Set the event recorder input events are sent to.
3515 \end_layout
3517 \begin_layout Subsubsection
3518 Method startEventCheck()
3519 \end_layout
3521 \begin_layout Standard
3522 Signals target to reset all state related to event checking and state feedback.
3523  This may be called at any time in order to reinitialialize event checking/feedb
3524 ack state.
3525 \end_layout
3527 \begin_layout Subsubsection
3528 Method doEvent(long, String[], int) throws IOException
3529 \end_layout
3531 \begin_layout Standard
3532 Event dispatch handler.
3533  The first argument is event time, second is parameters and third is what
3534  to do with it.
3535  If target doesn't like the event, throw IOException.
3536  Following types (the integer parameter) are used:
3537 \end_layout
3539 \begin_layout LyX-Code
3540 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3541 \end_layout
3543 \begin_layout LyX-Code
3544 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3545  for reinitialization
3546 \end_layout
3548 \begin_layout LyX-Code
3549 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3550 \end_layout
3552 \begin_layout LyX-Code
3553 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3554  Execute the effect.
3555 \end_layout
3557 \begin_layout Subsubsection
3558 Method endEventCheock()
3559 \end_layout
3561 \begin_layout Standard
3562 End event reinitialization.
3563  Usually unused.
3564 \end_layout
3566 \begin_layout Subsubsection
3567 Method getEventTimeLowBound(long, String[]) throws IOException
3568 \end_layout
3570 \begin_layout Standard
3571 Return the time value that's the earliest possiblity for this event to occur.
3572  Returning any time in past (including -1) causes event to fire as soon
3573  as possible.
3574  The long parameter gives the current scheduled time for event.
3575 \end_layout
3577 \begin_layout Section
3578 Writing modules
3579 \end_layout
3581 \begin_layout Standard
3582 Modules are various extensions that run inside emulator core.
3583  As such, they affect sync.
3584  Modules must implement interface org.jpc.emulator.HardwareComponent (they
3585  are hardware components) and must be dumpable.
3586  Additionally, they need either constructor <init>() or <init>(String).
3587  The first is if no parameters are passed, the second is for case where
3588  parameters are passed.
3589 \end_layout
3591 \begin_layout Standard
3592 Aside of the constructors, modules need to obey the ordinary conventions
3593  for hardware components.
3594  No code outside modules needs to know that module exists.
3595 \end_layout
3597 \begin_layout Section
3598 Writing plugins
3599 \end_layout
3601 \begin_layout Standard
3602 Plugins handle various UI tasks.
3603  They need to implement interface org.jpc.Plugin.
3604 \end_layout
3606 \begin_layout Subsection
3607 Interface org.jpc.pluginsbase.Plugin
3608 \end_layout
3610 \begin_layout Subsubsection
3611 Method systemShutdown()
3612 \end_layout
3614 \begin_layout Standard
3615 Called when emulator shuts down.
3616  Either called in dedicated thread or in thread that called emulatorShutdown().
3617  These handlers should do the bare minimum to get files on disk to consistent
3618  state.
3619  After these calls from all plugins have finished, emulator exits.
3620  Do not try to manipulate UI from these methods, as doing that easily leads
3621  into deadlock.
3622 \end_layout
3624 \begin_layout Subsubsection
3625 Method reconnect(PC) 
3626 \end_layout
3628 \begin_layout Standard
3629 Gives new PC to connect to.
3630  Null is passed if plugin should disconnect.
3631 \end_layout
3633 \begin_layout Subsubsection
3634 Method main()
3635 \end_layout
3637 \begin_layout Standard
3638 Called in dedicated thread after plugin is initialized.
3639 \end_layout
3641 \begin_layout Subsubsection
3642 Method pcStopping()
3643 \end_layout
3645 \begin_layout Standard
3646 Called after PC has stopped.
3647 \end_layout
3649 \begin_layout Subsubsection
3650 Method pcStarting()
3651 \end_layout
3653 \begin_layout Standard
3654 Called before PC starts.
3655 \end_layout
3657 \begin_layout Subsubsection
3658 Method notifyArguments(String[])
3659 \end_layout
3661 \begin_layout Standard
3662 Pass arguments from command line.
3663 \end_layout
3665 \begin_layout Subsubsection
3666 Constructor <init>(Plugins)
3667 \end_layout
3669 \begin_layout Standard
3670 This constructor is used to initialize plugins that don't take parameters.
3671 \end_layout
3673 \begin_layout Subsubsection
3674 Constructor <init>(Plugins, String)
3675 \end_layout
3677 \begin_layout Standard
3678 This constructor is used to initialize plugins that take parameters.
3679 \end_layout
3681 \begin_layout Subsection
3682 Class org.jpc.pluginsbase.Plugins
3683 \end_layout
3685 \begin_layout Standard
3686 This class provodes various methods for manipulating plugins.
3687 \end_layout
3689 \begin_layout Subsubsection
3690 Method isShuttingDown()
3691 \end_layout
3693 \begin_layout Standard
3694 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3695  via VM exit, CTRL+C or explicitly.
3696  Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3697 \end_layout
3699 \begin_layout Subsubsection
3700 Method shutdownEmulator()
3701 \end_layout
3703 \begin_layout Standard
3704 Shut down and exit the emulator.
3705  All plugin shutdown functions are called in this thread.
3706 \end_layout
3708 \begin_layout Subsubsection
3709 Method reconnectPC(PC)
3710 \end_layout
3712 \begin_layout Standard
3713 Signal reconnectPC event to all plugins.
3714 \end_layout
3716 \begin_layout Subsubsection
3717 Method pcStarted()
3718 \end_layout
3720 \begin_layout Standard
3721 Signal pcStarting() event to all plugins.
3722 \end_layout
3724 \begin_layout Subsubsection
3725 Method pcStopped()
3726 \end_layout
3728 \begin_layout Standard
3729 Signal pcStopping() event to all plugins.
3730 \end_layout
3732 \begin_layout Section
3733 Inter-plugin communication
3734 \end_layout
3736 \begin_layout Subsection
3737 Receiving communications
3738 \end_layout
3740 \begin_layout Standard
3741 To receive invocation/call by name 'foo-bar', declare public method named
3742  'eci_foo_bar'.
3743  Arguments to this method can currently be String, Integer (int) or Long
3744  (long).
3745  Last argument may be array over these types to get variable number of arguments.
3746  On call, each argument gets value from call.
3747  If last argument is array, it gets all overflowing arguments.
3748  If return type is void or method returns boolean false, call is assumed
3749  to have completed.
3750  If return value is boolean true, it is assumed that there is more processing.
3751 \end_layout
3753 \begin_layout Subsection
3754 void org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd, Object[]
3755  args) 
3756 \end_layout
3758 \begin_layout Standard
3759 Invoke command asynchronously, broadcasting to all plugins.
3760  Does not wait for slow commands to complete.
3761  cmd is the name to send and args are the arguments to pass.
3762 \end_layout
3764 \begin_layout Subsection
3765 void org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String cmd,
3766  Object[] args) 
3767 \end_layout
3769 \begin_layout Standard
3770 Same as invokeExternalCommand, but waits for slow commands to complete.
3771 \end_layout
3773 \begin_layout Subsection
3774 Object[] org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String cmd,
3775  Object[] args) 
3776 \end_layout
3778 \begin_layout Standard
3779 Similar to invokeExternalCommandSynchornous, but:
3780 \end_layout
3782 \begin_layout Itemize
3783 Quits calling more plugins when it gets successful reply.
3784 \end_layout
3786 \begin_layout Itemize
3787 Returns said reply
3788 \end_layout
3790 \begin_layout Subsection
3791 void org.jpc.pluginsbase.Plugins.returnValue(Object...
3792  ret)
3793 \end_layout
3795 \begin_layout Standard
3796 Gives return value to return from call and signals that command has completed.
3797 \end_layout
3799 \begin_layout Subsection
3800 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
3801 \end_layout
3803 \begin_layout Standard
3804 Signals that command has completed.
3805  Only needed if there is no return value and eci_ method returned false
3806  (not done yet).
3807 \end_layout
3809 \begin_layout Section
3810 Lua kernel programming
3811 \end_layout
3813 \begin_layout Standard
3814 At startup, kernel gets its arguments in 'args' table and the script name
3815  to run in 'scriptname' string.
3816  It should enter the named script in protected mode.
3817 \end_layout
3819 \begin_layout Standard
3820 The Lua VM exports numerious callbacks to kernel.
3821  The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3822 \end_layout
3824 \begin_layout Itemize
3825 Always grab any functions used into local variables so nobody can mess with
3826  them
3827 \end_layout
3829 \begin_layout Itemize
3830 Don't use global variables in kernel (except for those passed).
3831 \end_layout
3833 \end_body
3834 \end_document