Update manual
[jpcrr.git] / manual.lyx
blob825ffb6f317b69bba1c34873e8d7e6f622da4591
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.bat that has fairly reasonable
121  defaults.
122  To use it:
123 \end_layout
125 \begin_layout LyX-Code
126 java JPCApplication -library library -autoexec assemble.bat
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 Subsection
820 Command line
821 \end_layout
823 \begin_layout Standard
824 When emulator is started, command line comes up.
825  Following commands are known:
826 \end_layout
828 \begin_layout Itemize
829 'exit': exit immediately
830 \end_layout
832 \begin_layout Itemize
833 'load <plugin>': Load plugin (no arguments)
834 \end_layout
836 \begin_layout Itemize
837 'load <plugin>(<arguments>)': load plugin with arguments.
838 \end_layout
840 \begin_layout Itemize
841 'command <command> [<arguments>...]': Invoke command via external command interface.
842 \end_layout
844 \begin_layout Itemize
845 'call<command> [<arguments>...]': Invoke command via external command interface
846  and print return values.
847 \end_layout
849 \begin_layout Standard
850 When one gets command line, its useful to load some plugins.
851  See section about plugins.
852  Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
853  like to start PC immediately.
854 \end_layout
856 \begin_layout Subsection
857 PC settings dialog notes
858 \end_layout
860 \begin_layout Itemize
861 CPU divider base frequency before division is 1GHz.
862 \end_layout
864 \begin_layout Itemize
865 Images can be specified by name or by ID.
866  Name is relative to library directory.
867  If the image is in subdirectory of image directory, the directory separator
868  is is '/' regardless of what the host OS uses.
869 \end_layout
871 \begin_layout Itemize
872 CD-ROM and hdc are mutually exclusive
873 \end_layout
875 \begin_layout Itemize
876 Modules is comma-seperated list of modules to load.
877  To pass arguments to some modules, enclose the arguments in ().
878  Same module can be specified twice only if parameters differ.
879 \end_layout
881 \begin_layout Itemize
882 Setting boot device doesn't work with some BIOS versions.
883  Those versions prompt the boot device anyway.
884 \end_layout
886 \begin_layout Subsection
887 Audio output channels
888 \end_layout
890 \begin_layout Standard
891 PC can have one or more audio output channels.
892  The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
893 al.PCSpeaker-0'.
894  Modules that have audio outputs get channel names of form <classname>-<sequenti
895 al>, where <classname> is name of main module class and sequential is number
896  starting from zero.
897  Note that same module can have multiple output channels.
898  If multiple modules of same class request audio outputs, the <sequential>
899  values of subsequent module start where previous left off.
900 \end_layout
902 \begin_layout Subsection
903 Plugins
904 \end_layout
906 \begin_layout Standard
907 Plugins actually execute the tasks of the emulator.
908  They can be loaded using 
909 \begin_inset Quotes eld
910 \end_inset
912 load <plugin>
913 \begin_inset Quotes erd
914 \end_inset
916  or 'load <plugin>(<arguments>)
917 \begin_inset Quotes erd
918 \end_inset
920  from command line.
921 \end_layout
923 \begin_layout Standard
924 Different Plugins using the same output (like running PCMonitor and RAWVideoDump
925 er) should not conflict because connector output hold locking is desinged
926  to handle multiple readers.
927 \end_layout
929 \begin_layout Standard
930 If no plugin used requires GUI, then the emulator can be run without having
931  GUI available.
932 \end_layout
934 \begin_layout Subsubsection
935 plugin: org.jpc.plugins.PCControl
936 \end_layout
938 \begin_layout Standard
939 No arguments, requires and uses GUI.
940 \end_layout
942 \begin_layout Standard
943 Runs the PC emulator core.
944  Has capability to start/stop emulation, breakpoint after certain time or
945  start/end of VGA vertical retrace.
946  Also can create, savestate and loadstate PC emulation.
947  Memory dumping is supported.
949 \end_layout
951 \begin_layout Subsubsection
952 plugin: org.jpc.plugins.PCRunner
953 \end_layout
955 \begin_layout Standard
956 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
957  require nor use GUI.
958 \end_layout
960 \begin_layout Standard
961 Loads PC from savestate and just runs it.
962  CTRL+C to quit.
963  Also automatically quits once stoptime is reached.
964 \end_layout
966 \begin_layout Subsubsection
967 plugin: org.jpc.plugins.PCMonitor
968 \end_layout
970 \begin_layout Standard
971 No arguments, requires and uses GUI.
972 \end_layout
974 \begin_layout Standard
975 VGA monitor for emulated PC.
976 \end_layout
978 \begin_layout Subsubsection
979 plugin: org.jpc.plugins.VirtualKeyboard
980 \end_layout
982 \begin_layout Standard
983 No arguments, requires and uses GUI.
984 \end_layout
986 \begin_layout Standard
987 On-screen keyboard for emulated PC.
988 \end_layout
990 \begin_layout Subsubsection
991 plugin: org.jpc.plugins.PCStartStopTest
992 \end_layout
994 \begin_layout Standard
995 No arguments, requires and uses GUI.
996 \end_layout
998 \begin_layout Standard
999 Small plugin testing remote PC start/stop.
1000  Also supports sending some common keypresses.
1001 \end_layout
1003 \begin_layout Subsubsection
1004 plugin: org.jpc.plugins.RAWVideoDumper
1005 \end_layout
1007 \begin_layout Standard
1008 Takes 'rawoutput=<file>' as argument.
1009  Does not require nor use GUI.
1010 \end_layout
1012 \begin_layout Standard
1013 Dumps all generated frames to RAW file <file>.
1014  Rawoutput is required.
1015  The raw file consists of concatenation of zlib streams.
1016  The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1017  each acting as time offset of 2^32-1 nanoseconds and saved frames.
1018  The saved frame has time offset in nanoseconds (big endian) as first four
1019  bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1020  The next two bytes are big-endian width, next two big-endian height.
1021  Finally frame has 4 * width * height bytes of data that encodes pixels
1022  using 4 bytes per pixel, in left-to-right, up-to-down order.
1023  Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1024  green channel and byte 3 is blue channel.
1025 \end_layout
1027 \begin_layout Standard
1028 Dumping to pipe is supported.
1029 \end_layout
1031 \begin_layout Subsubsection
1032 plugin: org.jpc.plugins.RAWAudioDumper
1033 \end_layout
1035 \begin_layout Standard
1036 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1037  'offset=<offset>' as arguments, separated by ','.
1038  Does not require nor use GUI.
1039 \end_layout
1041 \begin_layout Standard
1042 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1043  file (file, mandatory).
1044  The resulting file consists of records, 4 or 8 bytes each.
1045  4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1046  time delta by 
1047 \begin_inset Formula $2^{32}-1$
1048 \end_inset
1051  Otherwise record is 8 bytes.
1052  Each 8 byte record has three fields.
1053  First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1054  be smaller than 
1055 \begin_inset Formula $2^{32}-1$
1056 \end_inset
1058 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1059  big endian new right channel volume.
1060  Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1061  the audio by.
1062 \end_layout
1064 \begin_layout Subsubsection
1065 plugin: org.jpc.plugins.LuaPlugin
1066 \end_layout
1068 \begin_layout Standard
1069 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1070  kernel, requires and uses GUI.
1071 \end_layout
1073 \begin_layout Standard
1074 Lua VM for executing scripts.
1075 \end_layout
1077 \begin_layout Subsubsection
1078 plugin: org.jpc.plugins.JoystickInput
1079 \end_layout
1081 \begin_layout Standard
1082 No parameters.
1083  Displays window for sending joystick input.
1084 \end_layout
1086 \begin_layout Section
1087 Modules
1088 \end_layout
1090 \begin_layout Subsection
1091 org.jpc.modules.Joystick:
1092 \end_layout
1094 \begin_layout Itemize
1095 Arguments: none.
1096 \end_layout
1098 \begin_layout Itemize
1099 Resources: I/O port 0x201
1100 \end_layout
1102 \begin_layout Standard
1103 Emulates joystick game port.
1104 \end_layout
1106 \begin_layout Subsection
1107 org.jpc.modules.BasicFPU:
1108 \end_layout
1110 \begin_layout Itemize
1111 Arguments: none.
1112 \end_layout
1114 \begin_layout Itemize
1115 Resources: None.
1116 \end_layout
1118 \begin_layout Standard
1119 Crude FPU (x87) emulator.
1120 \end_layout
1122 \begin_layout Section
1123 Hacks
1124 \end_layout
1126 \begin_layout Standard
1127 Hacks are saved to savestates but not movies.
1128 \end_layout
1130 \begin_layout Subsection
1131 NO_FPU
1132 \end_layout
1134 \begin_layout Standard
1135 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1136  has no FPU.
1137  BIOS assumes system has FPU but some games use that bit to detect FPU,
1138  trying to use it if it is 
1139 \begin_inset Quotes eld
1140 \end_inset
1142 present
1143 \begin_inset Quotes erd
1144 \end_inset
1147  Try this if game startup hangs with lots of trying to use FPU but not present
1148  errors.
1149  Don't use if there is FPU present.
1150  Needed to get games like Blake Stone to work (FPU emulator allows it to
1151  start but causes graphical glitches).
1152 \end_layout
1154 \begin_layout Subsection
1155 VGA_DRAW
1156 \end_layout
1158 \begin_layout Standard
1159 Update basic VGA parameters before vretrace, not after it.
1160  Some games (e.g.
1161  Commander Keen 4) don't like if this isn't done and some games (e.g.
1162  Mario & Luigi) don't like if it is done.
1163  Wrong value manifests as jerky scrolling (scrolling back and forth and
1164  fixed statusbars move).
1165 \end_layout
1167 \begin_layout Section
1168 Some error messages and explanations
1169 \end_layout
1171 \begin_layout Itemize
1172 <filename> is Not a valid image file
1173 \end_layout
1175 \begin_layout Itemize
1176 <filename> is not image file
1177 \end_layout
1179 \begin_layout Itemize
1180 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1181  and <z> sectors.
1182 \end_layout
1184 \begin_layout Itemize
1185 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1186  and <z> sectors.
1187 \end_layout
1189 \begin_layout Itemize
1190 Can't read disk image sector map.
1191 \end_layout
1193 \begin_layout Itemize
1194 Can't read disk image extent.
1195 \end_layout
1197 \begin_layout Standard
1198 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1199  image at all or its corrupt.
1200 \end_layout
1202 \begin_layout Itemize
1203 <filename> is image of unknown type.
1204 \end_layout
1206 \begin_layout Itemize
1207 <filename> has unrecognized geometry <x> <y> <z>
1208 \end_layout
1210 \begin_layout Standard
1211 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1212  containing something current version can't comprehend.
1213 \end_layout
1215 \begin_layout Itemize
1216 Invalid format specifier <something>.
1217 \end_layout
1219 \begin_layout Itemize
1220 Invalid syntax of --floppy= or --HDD= option.
1221 \end_layout
1223 \begin_layout Itemize
1224 Invalid format specifier/option <something>.
1225 \end_layout
1227 \begin_layout Standard
1228 Invalid option or format specifier was given.
1229  Check for typos.
1230 \end_layout
1232 \begin_layout Itemize
1233 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1234 \end_layout
1236 \begin_layout Standard
1237 Check syntax of command.
1238  Especially that diskname is present!
1239 \end_layout
1241 \begin_layout Itemize
1242 The image has <nnn> sectors while it should have <yyy> according to selected
1243  geometry.
1244 \end_layout
1246 \begin_layout Itemize
1247 Raw image file length not divisible by 512.
1248 \end_layout
1250 \begin_layout Itemize
1251 Trying to read sector out of range.
1252 \end_layout
1254 \begin_layout Standard
1255 The selected geometry is wrong or raw image is incomplete.
1256 \end_layout
1258 \begin_layout Itemize
1259 Invalid disk name (Should not happen!).
1260 \end_layout
1262 \begin_layout Itemize
1263 Invalid geometry to be written.
1264 \end_layout
1266 \begin_layout Standard
1267 This is a very likely a bug in program.
1268 \end_layout
1270 \begin_layout Itemize
1271 What the heck <filename> is? It's not regular file nor directory.
1272 \end_layout
1274 \begin_layout Standard
1275 That sort of file can't be used as input for image making, or the file just
1276  doesn't exist.
1277 \end_layout
1279 \begin_layout Itemize
1280 BIOS images can only be made out of regular files.
1281 \end_layout
1283 \begin_layout Itemize
1284 CD images can only be made out of regular files.
1285 \end_layout
1287 \begin_layout Standard
1288 Source image specified is not regular file, but image of that type can't
1289  be made of anything else.
1290 \end_layout
1292 \begin_layout Itemize
1293 Can't read raw bios image file.
1294 \end_layout
1296 \begin_layout Itemize
1297 Can't read sector <nnn> from image.
1298 \end_layout
1300 \begin_layout Standard
1301 Reading the raw image file failed for some reason.
1302 \end_layout
1304 \begin_layout Itemize
1305 Bad library line: "<something>".
1306  Ignored.
1307 \end_layout
1309 \begin_layout Standard
1310 Syntax error in image library.
1311 \end_layout
1313 \begin_layout Itemize
1314 Removing image <something> a.k.a.
1315  "<something>" as it no longer exists.
1316 \end_layout
1318 \begin_layout Standard
1319 The image file no longer exists so it gets removed from library.
1320 \end_layout
1322 \begin_layout Itemize
1323 Removing image <something> a.k.a.
1324  "<something>" due to <some> conflict.
1325 \end_layout
1327 \begin_layout Standard
1328 Image library code killed some image from library due to some kind of conflict
1329  with image being added.
1330 \end_layout
1332 \begin_layout Itemize
1333 Too much data to fit into given space.
1334 \end_layout
1336 \begin_layout Standard
1337 The tree you gave contains takes just too much space to fit into disk of
1338  this size.
1339 \end_layout
1341 \begin_layout Section
1342 Advanced: Savestate/movie format
1343 \end_layout
1345 \begin_layout Subsection
1346 Special character classes
1347 \end_layout
1349 \begin_layout Subsubsection
1350 SPACE
1351 \end_layout
1353 \begin_layout Standard
1354 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1355  characters:
1356 \end_layout
1358 \begin_layout Itemize
1359 Codepoints 0x20, and 0x09.
1360 \end_layout
1362 \begin_layout Itemize
1363 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1364 \end_layout
1366 \begin_layout Itemize
1367 Codepoints 0x2000-0x200A.
1368 \end_layout
1370 \begin_layout Subsubsection
1371 LINEFEED
1372 \end_layout
1374 \begin_layout Standard
1375 Following byte sequences are interpretted as linefeeds (line change):
1376 \end_layout
1378 \begin_layout Itemize
1379 Byte 0x0A
1380 \end_layout
1382 \begin_layout Itemize
1383 Byte 0x0D
1384 \end_layout
1386 \begin_layout Itemize
1387 Bytes 0x0D 0x0A (interpretted as single line change, not two!)
1388 \end_layout
1390 \begin_layout Itemize
1391 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL)
1392 \end_layout
1394 \begin_layout Subsection
1395 JRSR archive
1396 \end_layout
1398 \begin_layout Standard
1399 JRSR archive format packs multiple text archive members to text archive.
1400  It does not support binary members.
1401  JRSR archives have first five or six bytes form the magic.
1402  It is 
1403 \begin_inset Quotes eld
1404 \end_inset
1406 JRSR
1407 \begin_inset Quotes erd
1408 \end_inset
1410  followed by LINEFEED character There are four kinds of lines after that
1411  (lines are terminated by LINEFEED byte/bytes):
1412 \end_layout
1414 \begin_layout Itemize
1415 Start member
1416 \end_layout
1418 \begin_layout Itemize
1419 Member line
1420 \end_layout
1422 \begin_layout Itemize
1423 End member
1424 \end_layout
1426 \begin_layout Itemize
1427 Blank line
1428 \end_layout
1430 \begin_layout Standard
1431 Sequencing rules are as follows: Start member is allowed anywhere (after
1432  magic).
1433  Member line is allowed only inside member (member started but not ended).
1434  End member is only allowed inside member.
1435  End of file is only allowed outside member.
1436  Blank line is allowed anywhere after magic.
1437 \end_layout
1439 \begin_layout Subsubsection
1440 Start member
1441 \end_layout
1443 \begin_layout Standard
1444 Start member line is given as 
1445 \begin_inset Quotes eld
1446 \end_inset
1448 !BEGIN
1449 \begin_inset Quotes erd
1450 \end_inset
1452  <SPACE>+ <membername> <LINEFEED>.
1453  <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1454  LINEFEED chacter.
1455  The member name is UTF-8 encoded and maximum allowed line length is 2048
1456  bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1457  depending on characters used).
1458  Starting member inside another implicitly ends the previous member.
1459 \end_layout
1461 \begin_layout Subsubsection
1462 Member line:
1463 \end_layout
1465 \begin_layout Standard
1466 Member line is given as 
1467 \begin_inset Quotes eld
1468 \end_inset
1471 \begin_inset Quotes erd
1472 \end_inset
1474 <content><LINEFEED>.
1475  It gives another line for member contents.
1476  <content> is passed raw to layers above (followed by line termination)
1477 \end_layout
1479 \begin_layout Subsubsection
1480 End member
1481 \end_layout
1483 \begin_layout Standard
1484 End member line is given as 
1485 \begin_inset Quotes eld
1486 \end_inset
1488 !END
1489 \begin_inset Quotes erd
1490 \end_inset
1492 <LINEFEED>.
1493  It ends the current member.
1494  The following line can only be start member line or file may end.
1495 \end_layout
1497 \begin_layout Subsubsection
1498 Blank line
1499 \end_layout
1501 \begin_layout Standard
1502 Blank line is given as <LINEFEED>.
1503  Lines like that are ignored.
1504 \end_layout
1506 \begin_layout Subsection
1507 Four-to-Five encoding
1508 \end_layout
1510 \begin_layout Standard
1511 Binary members are encoded into text by so-called four-to-five encoding.
1512  This encoding can encode single byte to two, two bytes to three, three
1513  bytes to four and four bytes to five.
1514  Four-to-five encoding has five kinds of blocks.
1515  All SPACE and LINEFEED characters are completely ignored, even in middle
1516  of blocks.
1517 \end_layout
1519 \begin_layout Subsubsection
1520 End stream block
1521 \end_layout
1523 \begin_layout Standard
1524 End stream block is encoded as '!'.
1525  It ends the stream instantly.
1526  There is also implicit end of stream at end of input to decoding.
1527 \end_layout
1529 \begin_layout Subsubsection
1530 Other four block types
1531 \end_layout
1533 \begin_layout Standard
1534 Other four block types take the value to be encoded, read it as big-endian
1535  value.
1536  Then they write it as base-93 big-endian value.
1537  Then length specific constants are added to digits of that number to yield
1538  ASCII values for characters (those are stored in order):
1539 \end_layout
1541 \begin_layout Standard
1542 \begin_inset Tabular
1543 <lyxtabular version="3" rows="5" columns="6">
1544 <features>
1545 <column alignment="center" valignment="top" width="0">
1546 <column alignment="center" valignment="top" width="0">
1547 <column alignment="center" valignment="top" width="0">
1548 <column alignment="center" valignment="top" width="0">
1549 <column alignment="center" valignment="top" width="0">
1550 <column alignment="center" valignment="top" width="0">
1551 <row>
1552 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1553 \begin_inset Text
1555 \begin_layout Plain Layout
1556 To encode
1557 \end_layout
1559 \end_inset
1560 </cell>
1561 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1562 \begin_inset Text
1564 \begin_layout Plain Layout
1565 1st char.
1566 \end_layout
1568 \end_inset
1569 </cell>
1570 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1571 \begin_inset Text
1573 \begin_layout Plain Layout
1574 2nd char.
1575 \end_layout
1577 \end_inset
1578 </cell>
1579 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1580 \begin_inset Text
1582 \begin_layout Plain Layout
1583 3rd char.
1584 \end_layout
1586 \end_inset
1587 </cell>
1588 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1589 \begin_inset Text
1591 \begin_layout Plain Layout
1592 4th char.
1593 \end_layout
1595 \end_inset
1596 </cell>
1597 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1598 \begin_inset Text
1600 \begin_layout Plain Layout
1601 5th char.
1602 \end_layout
1604 \end_inset
1605 </cell>
1606 </row>
1607 <row>
1608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1609 \begin_inset Text
1611 \begin_layout Plain Layout
1612 1 byte
1613 \end_layout
1615 \end_inset
1616 </cell>
1617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1618 \begin_inset Text
1620 \begin_layout Plain Layout
1622 \end_layout
1624 \end_inset
1625 </cell>
1626 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1627 \begin_inset Text
1629 \begin_layout Plain Layout
1631 \end_layout
1633 \end_inset
1634 </cell>
1635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1636 \begin_inset Text
1638 \begin_layout Plain Layout
1640 \end_layout
1642 \end_inset
1643 </cell>
1644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1645 \begin_inset Text
1647 \begin_layout Plain Layout
1649 \end_layout
1651 \end_inset
1652 </cell>
1653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1654 \begin_inset Text
1656 \begin_layout Plain Layout
1658 \end_layout
1660 \end_inset
1661 </cell>
1662 </row>
1663 <row>
1664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1665 \begin_inset Text
1667 \begin_layout Plain Layout
1668 2 bytes
1669 \end_layout
1671 \end_inset
1672 </cell>
1673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1674 \begin_inset Text
1676 \begin_layout Plain Layout
1678 \end_layout
1680 \end_inset
1681 </cell>
1682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1683 \begin_inset Text
1685 \begin_layout Plain Layout
1687 \end_layout
1689 \end_inset
1690 </cell>
1691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1692 \begin_inset Text
1694 \begin_layout Plain Layout
1696 \end_layout
1698 \end_inset
1699 </cell>
1700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1701 \begin_inset Text
1703 \begin_layout Plain Layout
1705 \end_layout
1707 \end_inset
1708 </cell>
1709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1710 \begin_inset Text
1712 \begin_layout Plain Layout
1714 \end_layout
1716 \end_inset
1717 </cell>
1718 </row>
1719 <row>
1720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1721 \begin_inset Text
1723 \begin_layout Plain Layout
1724 3 bytes
1725 \end_layout
1727 \end_inset
1728 </cell>
1729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1730 \begin_inset Text
1732 \begin_layout Plain Layout
1734 \end_layout
1736 \end_inset
1737 </cell>
1738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1739 \begin_inset Text
1741 \begin_layout Plain Layout
1743 \end_layout
1745 \end_inset
1746 </cell>
1747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1748 \begin_inset Text
1750 \begin_layout Plain Layout
1752 \end_layout
1754 \end_inset
1755 </cell>
1756 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1757 \begin_inset Text
1759 \begin_layout Plain Layout
1761 \end_layout
1763 \end_inset
1764 </cell>
1765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1766 \begin_inset Text
1768 \begin_layout Plain Layout
1770 \end_layout
1772 \end_inset
1773 </cell>
1774 </row>
1775 <row>
1776 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1777 \begin_inset Text
1779 \begin_layout Plain Layout
1780 4 bytes
1781 \end_layout
1783 \end_inset
1784 </cell>
1785 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1786 \begin_inset Text
1788 \begin_layout Plain Layout
1790 \end_layout
1792 \end_inset
1793 </cell>
1794 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1795 \begin_inset Text
1797 \begin_layout Plain Layout
1799 \end_layout
1801 \end_inset
1802 </cell>
1803 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1804 \begin_inset Text
1806 \begin_layout Plain Layout
1808 \end_layout
1810 \end_inset
1811 </cell>
1812 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1813 \begin_inset Text
1815 \begin_layout Plain Layout
1817 \end_layout
1819 \end_inset
1820 </cell>
1821 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1822 \begin_inset Text
1824 \begin_layout Plain Layout
1826 \end_layout
1828 \end_inset
1829 </cell>
1830 </row>
1831 </lyxtabular>
1833 \end_inset
1836 \end_layout
1838 \begin_layout Standard
1839 Blocks which encode values greater than what is possible for value of that
1840  length are fatal errors.
1842 \end_layout
1844 \begin_layout Subsection
1845 Line component encoing
1846 \end_layout
1848 \begin_layout Standard
1849 Line component encoding sits on top of UTF-8 encoding.
1850  Line component encoding encodes non-empty 1-D array of non-empty strings
1851  into line, and thus array of those into member.
1852  Empty lines or lines that don't contain any components are ignored.
1853  Line starts with depth value of 0 and must end with depth value of zero.
1854 \end_layout
1856 \begin_layout Standard
1857 Components are seperated by component separators.
1858  Empty components are ignored.
1859  Following codepoints are separators on depth 0 if not escaped:
1860 \end_layout
1862 \begin_layout Itemize
1863 Codepoint of '('.
1864  The depth is read pre-increment.
1865 \end_layout
1867 \begin_layout Itemize
1868 Codepoint of ')'.
1869  The depth is read post-decrement.
1870 \end_layout
1872 \begin_layout Itemize
1873 Any SPACE character
1874 \end_layout
1876 \begin_layout Standard
1877 The following characters are special:
1878 \end_layout
1880 \begin_layout Itemize
1881 '('.
1882  Increments depth by 1 if not escaped (and appears in component).
1883 \end_layout
1885 \begin_layout Itemize
1886 ')'.
1887  Decrements depth by 1 if not escaped (and appears in component).
1888  Depth going negative is an error.
1889 \end_layout
1891 \begin_layout Itemize
1893 \backslash
1895  Next character is interpretted as literal.
1896  Error if at end of line.
1897 \end_layout
1899 \begin_layout Standard
1900 Otherwise, characters are interpretted as literals and appear in components.
1901  Depth must be zero at end of line.
1902 \end_layout
1904 \begin_layout Subsection
1905 Header section:
1906 \end_layout
1908 \begin_layout Standard
1909 Header section is in archive member "header".
1910  It uses line component encoding.
1911  The first component of each line is name of header, and subsequent ones
1912  are arguments.
1913  How many parameters are expected is dependent on what header it is:
1914 \end_layout
1916 \begin_layout Subsubsection
1917 PROJECTID header:
1918 \end_layout
1920 \begin_layout Itemize
1921 Header name: "PROJECTID"
1922 \end_layout
1924 \begin_layout Itemize
1925 Components: 2
1926 \end_layout
1928 \begin_layout Itemize
1929 Argument #1: <project-id-string>
1930 \end_layout
1932 \begin_layout Itemize
1933 Mandatory: Yes
1934 \end_layout
1936 \begin_layout Standard
1937 Gives project ID.
1938  Project ID is generated when PC is assembled and is then preserved in save
1939  states.
1940  It is used for computing rerecord counts.
1941  Emulator treats it as opaque string, the IDs it generates are formed by
1942  48 random hexadecimal digits.
1943 \end_layout
1945 \begin_layout Subsubsection
1946 SAVESTATEID header:
1947 \end_layout
1949 \begin_layout Itemize
1950 Header name: "SAVESTATEID"
1951 \end_layout
1953 \begin_layout Itemize
1954 Components: 2
1955 \end_layout
1957 \begin_layout Itemize
1958 Argument #1: <savestate-id-string>
1959 \end_layout
1961 \begin_layout Itemize
1962 Mandatory: No
1963 \end_layout
1965 \begin_layout Standard
1966 Gives save state ID.
1967  Each save state has its own save state ID.
1968  Treated as opaque string, but generated as 48 random hexadecimal digits.
1969  The presence of this header signals whether there is save state to be loaded.
1970  If this header is present, save state load will be attempted.
1971  If absent, save state is not to be loaded even if present (and correct
1972  savestate load would be technically impossible anyway).
1973 \end_layout
1975 \begin_layout Standard
1976 The value is used to prevent loading incompatible save states in preserve
1977  event stream mode and also to find the point in event stream where one
1978  left off.
1979 \end_layout
1981 \begin_layout Subsubsection
1982 RERECORDS header:
1983 \end_layout
1985 \begin_layout Itemize
1986 Header name: "RERECORDS"
1987 \end_layout
1989 \begin_layout Itemize
1990 Components: 2
1991 \end_layout
1993 \begin_layout Itemize
1994 Argument #1: <rerecords>
1995 \end_layout
1997 \begin_layout Itemize
1998 Mandatory: Yes
1999 \end_layout
2001 \begin_layout Standard
2002 Gives rerecord count.
2003  PC assembly (except when loading save state) initializes current rerecord
2004  count to zero.
2005  Must be non-negative and decimal number using ASCII digit characters.
2006 \end_layout
2008 \begin_layout LyX-Code
2009 On loading save state:
2010 \end_layout
2012 \begin_layout LyX-Code
2013 1) If project ID matches with previous:
2014 \end_layout
2016 \begin_layout LyX-Code
2017 1a) If loaded rerecord count is larger or equal to current rerecord count:
2018 \end_layout
2020 \begin_layout LyX-Code
2021 1a-a) Current rerecord count is loaded rerecord count + 1.
2022 \end_layout
2024 \begin_layout LyX-Code
2025 1b) Otherwise
2026 \end_layout
2028 \begin_layout LyX-Code
2029 1b-a) Current rerecord count increments by 1.
2030 \end_layout
2032 \begin_layout LyX-Code
2033 2) Otherwise
2034 \end_layout
2036 \begin_layout LyX-Code
2037 2a) Current rerecord count is loaded rerecord count + 1.
2038 \end_layout
2040 \begin_layout Standard
2041 The current rerecord count at time of save is saved to save state.
2042 \end_layout
2044 \begin_layout Subsubsection
2045 AUTHORS header:
2046 \end_layout
2048 \begin_layout Itemize
2049 Header name: "AUTHORS"
2050 \end_layout
2052 \begin_layout Itemize
2053 Components: 2 or more
2054 \end_layout
2056 \begin_layout Itemize
2057 Arguments: free form
2058 \end_layout
2060 \begin_layout Itemize
2061 Mandatory: No
2062 \end_layout
2064 \begin_layout Standard
2065 Gives authors of run.
2066  Each argument gives one author.
2067  May be present multiple times.
2068 \end_layout
2070 \begin_layout Subsubsection
2071 COMMENT header:
2072 \end_layout
2074 \begin_layout Itemize
2075 Header name: "COMMENT"
2076 \end_layout
2078 \begin_layout Itemize
2079 Components: 2 or more
2080 \end_layout
2082 \begin_layout Itemize
2083 Arguments: free form
2084 \end_layout
2086 \begin_layout Itemize
2087 Mandatory: No
2088 \end_layout
2090 \begin_layout Standard
2091 Various kinds of free form data.
2092  Not parsed further by emulator.
2093 \end_layout
2095 \begin_layout Subsection
2096 Initialization segment:
2097 \end_layout
2099 \begin_layout Standard
2100 If SAVESTATEID header isn't present (not a save state), member "initialization"
2101  gives PC initialization parameters for assembling the PC.
2102  It is present anyway even if SAVESTATEID is present (savestate).
2103 \end_layout
2105 \begin_layout Standard
2106 Following parameters are used (space separates components):
2107 \end_layout
2109 \begin_layout LyX-Code
2110 "BIOS" <id>
2111 \end_layout
2113 \begin_layout Standard
2114 Gives Image ID of main system BIOS (mandatory)
2115 \end_layout
2117 \begin_layout LyX-Code
2118 "VGABIOS" <id>
2119 \end_layout
2121 \begin_layout Standard
2122 Gives Image ID of VGA BIOS (mandatory).
2123 \end_layout
2125 \begin_layout LyX-Code
2126 "HDA" <id>
2127 \end_layout
2129 \begin_layout Standard
2130 Gives Image ID of hda.
2131  Present only if system has hard disk hda.
2132 \end_layout
2134 \begin_layout LyX-Code
2135 "HDB" <id>
2136 \end_layout
2138 \begin_layout Standard
2139 Gives Image ID of hdb.
2140  Present only if system has hard disk hdb.
2141 \end_layout
2143 \begin_layout LyX-Code
2144 "HDC" <id>
2145 \end_layout
2147 \begin_layout Standard
2148 Gives Image ID of hdc.
2149  Present only if system has hard disk hdc.
2150 \end_layout
2152 \begin_layout LyX-Code
2153 "HDD" <id>
2154 \end_layout
2156 \begin_layout Standard
2157 Gives Image ID of hdd.
2158  Present only if system has hard disk hdd.
2159 \end_layout
2161 \begin_layout LyX-Code
2162 "DISK" <num> <id>
2163 \end_layout
2165 \begin_layout Standard
2166 Gives Image ID of disk in slot <num>.
2167  Slot number must be non-negative.
2168 \end_layout
2170 \begin_layout LyX-Code
2171 \begin_inset Quotes eld
2172 \end_inset
2174 DISKNAME
2175 \begin_inset Quotes erd
2176 \end_inset
2178  <num> <name>
2179 \end_layout
2181 \begin_layout Standard
2182 kGives image name of disk in slot <num>.
2183  Slot number must be non-negative.
2184  The slot must be previously declared using 
2185 \begin_inset Quotes eld
2186 \end_inset
2188 DISK
2189 \begin_inset Quotes erd
2190 \end_inset
2193 \end_layout
2195 \begin_layout LyX-Code
2196 "FDA" <num>
2197 \end_layout
2199 \begin_layout Standard
2200 Gives Image slot to initially put into floppy drive fda.
2201  Disk must be of floppy type.
2202  If none present, no disk is initially put there.
2203 \end_layout
2205 \begin_layout LyX-Code
2206 "FDB" <num>
2207 \end_layout
2209 \begin_layout Standard
2210 Gives Image slot to initially put into floppy drive fdb.
2211  Disk must be of floppy type.
2212  If none present, no disk is initially put there.
2213 \end_layout
2215 \begin_layout LyX-Code
2216 "CDROM" <num>
2217 \end_layout
2219 \begin_layout Standard
2220 Gives Image slot to initially put into CD-ROM drive hdc.
2221  Not allowed if hard disk hdc is present.
2222  Disk must be of CD-ROM type.
2223  If none present no disk is initially put there.
2224 \end_layout
2226 \begin_layout LyX-Code
2227 "INITIALTIME" <time>
2228 \end_layout
2230 \begin_layout Standard
2231 Number of milliseconds since Unix epoch to system start up time.
2232  Allowed range:
2233 \end_layout
2235 \begin_layout Standard
2236 0-4102444799999.
2237  Mandatory.
2238 \end_layout
2240 \begin_layout LyX-Code
2241 "CPUDIVIDER" <divider>
2242 \end_layout
2244 \begin_layout Standard
2245 Set CPU frequency divider (dividing the 1GHz master clock).
2246  Allowed range is 1-256.
2247  Mandatory.
2248 \end_layout
2250 \begin_layout LyX-Code
2251 "MEMORYSIZE" <pages>
2252 \end_layout
2254 \begin_layout Standard
2255 Number of 4KiB pages of RAM memory.
2256  Allowed range 256-262144.
2257  Mandatory.
2258 \end_layout
2260 \begin_layout LyX-Code
2261 "BOOT" <device>
2262 \end_layout
2264 \begin_layout Standard
2265 Set boot device.
2266  Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2267  (boot from CD).
2268 \end_layout
2270 \begin_layout LyX-Code
2271 "LOADMODULEA" <module> <parameters>
2272 \end_layout
2274 \begin_layout Standard
2275 Load module <module> with parameters <parameters>.
2276 \end_layout
2278 \begin_layout LyX-Code
2279 "LOADMODULE" <module>
2280 \end_layout
2282 \begin_layout Standard
2283 Load module <module> with no parameters
2284 \end_layout
2286 \begin_layout LyX-Code
2287 \begin_inset Quotes eld
2288 \end_inset
2291 \begin_inset Quotes erd
2292 \end_inset
2294  <fpu>
2295 \end_layout
2297 \begin_layout Standard
2298 Use class <fpu> as FPU emulator.
2299 \end_layout
2301 \begin_layout LyX-Code
2302 \begin_inset Quotes eld
2303 \end_inset
2305 IOPORTDELAY
2306 \begin_inset Quotes erd
2307 \end_inset
2310 \end_layout
2312 \begin_layout Standard
2313 Use I/O port delay emulation (each I/O port read/write takes 666ns).
2314 \end_layout
2316 \begin_layout LyX-Code
2317 \begin_inset Quotes eld
2318 \end_inset
2320 VGAHRETRACE
2321 \begin_inset Quotes erd
2322 \end_inset
2325 \end_layout
2327 \begin_layout Standard
2328 Emulate VGA horizontal retrace.
2329 \end_layout
2331 \begin_layout Subsection
2332 Event record format:
2333 \end_layout
2335 \begin_layout Standard
2336 Event record is in archive member "events".
2337  It uses line component encoding.
2338  Each line gives an event.
2339  First component of each line gives time stamp.
2340  These timestamps MUST be in increasing order and all MUST be non-negative.
2341  Time stamp time unit is exactly 1 nanosecond of emulated time.
2342 \end_layout
2344 \begin_layout Standard
2345 The second component of each line is name of class to dispatch to.
2346  Further components are passed as-is to event handlers.
2347  Classes with names consisting only of uppercase A-Z and 0-9 are special
2348  and reserved.
2349  It is error to encounter unknown such special class.
2350 \end_layout
2352 \begin_layout Subsubsection
2353 Savestate event
2354 \end_layout
2356 \begin_layout Itemize
2357 Dispatch to: SAVESTATE
2358 \end_layout
2360 \begin_layout Itemize
2361 Argument #1: Savestate id
2362 \end_layout
2364 \begin_layout Itemize
2365 Argument #2 (optional): Rerecord count at time of saving savestate
2366 \end_layout
2368 \begin_layout Standard
2369 Signals that savestate has occured here.
2370  The save state IDs MUST be unique in entire event stream.
2371  The second argument to savestate (if present) is rerecord count at time
2372  of saving that savestate (useful for calulating rerecord count of movie
2373  starting from savestate).
2374  No time restrictions
2375 \end_layout
2377 \begin_layout Subsubsection
2378 Option event
2379 \end_layout
2381 \begin_layout Itemize
2382 Dispatch to: OPTION
2383 \end_layout
2385 \begin_layout Itemize
2386 Argument #1: 
2387 \begin_inset Quotes eld
2388 \end_inset
2390 ABSOLUTE
2391 \begin_inset Quotes erd
2392 \end_inset
2394  or 
2395 \begin_inset Quotes eld
2396 \end_inset
2398 RELATIVE
2399 \begin_inset Quotes erd
2400 \end_inset
2403 \end_layout
2405 \begin_layout Standard
2406 Controls various options.
2408 \begin_inset Quotes eld
2409 \end_inset
2411 ABSOLUTE
2412 \begin_inset Quotes erd
2413 \end_inset
2415  turns on absolute mode (default) where event timestamps are absolute.
2417 \begin_inset Quotes eld
2418 \end_inset
2420 RELATIVE
2421 \begin_inset Quotes erd
2422 \end_inset
2424  turns on relative mode where event timestamps are relative to last event
2425  in stream.
2426  The OPTION event itself is not affected by timing change.
2427  No time restrictions.
2428  Unknown arguments are errors.
2429 \end_layout
2431 \begin_layout Subsubsection
2432 Keyboard keypress/keyrelease event:
2433 \end_layout
2435 \begin_layout Itemize
2436 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2437 \end_layout
2439 \begin_layout Itemize
2440 Argument #1: Fixed: "KEYEDGE"
2441 \end_layout
2443 \begin_layout Itemize
2444 Argument #2: Key number.
2445  Valid values are 1-83, 85-95, 129-197 and 199-223
2446 \end_layout
2448 \begin_layout Standard
2449 Send key press or key release.
2450  Keys work in toggle button manner.
2451  The event time must be multiple of 66 666, and must not be less than 60
2452  * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2453  on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2454 \end_layout
2456 \begin_layout Subsubsection
2457 Pause event:
2458 \end_layout
2460 \begin_layout Itemize
2461 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2462 \end_layout
2464 \begin_layout Itemize
2465 Argument #1: Fixed: "PAUSE"
2466 \end_layout
2468 \begin_layout Standard
2469 Send pause key event.
2470  The time restrictions are identical to KEYEDGE event.
2471 \end_layout
2473 \begin_layout Subsubsection
2474 Joystick button event:
2475 \end_layout
2477 \begin_layout Itemize
2478 Dispatch to: org.jpc.modules.Joystick
2479 \end_layout
2481 \begin_layout Itemize
2482 Argument #1: 
2483 \begin_inset Quotes eld
2484 \end_inset
2486 BUTTONA
2487 \begin_inset Quotes erd
2488 \end_inset
2491 \begin_inset Quotes eld
2492 \end_inset
2494 BUTTONB
2495 \begin_inset Quotes erd
2496 \end_inset
2499 \begin_inset Quotes eld
2500 \end_inset
2502 BUTTONC
2503 \begin_inset Quotes erd
2504 \end_inset
2506  or 
2507 \begin_inset Quotes eld
2508 \end_inset
2510 BUTTOND
2511 \begin_inset Quotes erd
2512 \end_inset
2515 \end_layout
2517 \begin_layout Itemize
2518 Argument #2: 
2519 \begin_inset Quotes eld
2520 \end_inset
2523 \begin_inset Quotes erd
2524 \end_inset
2526  if released, 
2527 \begin_inset Quotes eld
2528 \end_inset
2531 \begin_inset Quotes erd
2532 \end_inset
2534  if pressed
2535 \end_layout
2537 \begin_layout Standard
2538 Send button down/up event.
2539  No time restrictions.
2540 \end_layout
2542 \begin_layout Subsubsection
2543 Joystick axis event:
2544 \end_layout
2546 \begin_layout Itemize
2547 Dispatch to: org.jpc.modules.Joystick
2548 \end_layout
2550 \begin_layout Itemize
2551 Argument #1: 
2552 \begin_inset Quotes eld
2553 \end_inset
2555 AXISA
2556 \begin_inset Quotes erd
2557 \end_inset
2560 \begin_inset Quotes eld
2561 \end_inset
2563 AXISB
2564 \begin_inset Quotes erd
2565 \end_inset
2568 \begin_inset Quotes eld
2569 \end_inset
2571 AXISC
2572 \begin_inset Quotes erd
2573 \end_inset
2575  or 
2576 \begin_inset Quotes eld
2577 \end_inset
2579 AXISD
2580 \begin_inset Quotes erd
2581 \end_inset
2584 \end_layout
2586 \begin_layout Itemize
2587 Argument #2: Multivibrator unstable state length in ns.
2588 \end_layout
2590 \begin_layout Standard
2591 Set amount of time multivibrator remains in unstable state.
2592  No time restrictions.
2593 \end_layout
2595 \begin_layout Subsubsection
2596 Reboot:
2597 \end_layout
2599 \begin_layout Itemize
2600 Dispatch to: org.jpc.emulator.PC$ResetButton
2601 \end_layout
2603 \begin_layout Itemize
2604 No arguments
2605 \end_layout
2607 \begin_layout Standard
2608 Reboots the PC.
2609 \end_layout
2611 \begin_layout Subsubsection
2612 Fda disk change:
2613 \end_layout
2615 \begin_layout Itemize
2616 Dispatch to: org.jpc.emulator.PC$DiskChanger
2617 \end_layout
2619 \begin_layout Itemize
2620 Argument #1: Fixed: "FDA"
2621 \end_layout
2623 \begin_layout Itemize
2624 Argument #2: Number of image slot to put there.
2626 \end_layout
2628 \begin_layout Standard
2629 The disk number MUST be -1 or valid disk number.
2630  -1 MUST NOT be used if there is no disk in floppy drive A.
2631  This event causes specified disk to be placed to FDA or FDA disk to be
2632  ejected with no replacement if disk number is -1.
2633  The specified disk if not -1 must be of floppy type.
2634  The specified disk if valid must not be in any other drive.
2635 \end_layout
2637 \begin_layout Subsubsection
2638 Fdb disk change:
2639 \end_layout
2641 \begin_layout Itemize
2642 Dispatch to: org.jpc.emulator.PC$DiskChanger
2643 \end_layout
2645 \begin_layout Itemize
2646 Argument #1: Fixed: "FDB"
2647 \end_layout
2649 \begin_layout Itemize
2650 Argument #2: Number of image slot to put there.
2652 \end_layout
2654 \begin_layout Standard
2655 The disk number MUST be -1 or valid disk number.
2656  -1 MUST NOT be used if there is no disk in floppy drive B.
2657  This event causes specified disk to be placed to FDB or FDB disk to be
2658  ejected with no replacement if disk number is -1.
2659  The specified disk if not -1 must be of floppy type.
2660  The specified disk if valid must not be in any other drive.
2661 \end_layout
2663 \begin_layout Subsubsection
2664 Change CDROM:
2665 \end_layout
2667 \begin_layout Itemize
2668 Dispatch to: org.jpc.emulator.PC$DiskChanger
2669 \end_layout
2671 \begin_layout Itemize
2672 Argument #1: Fixed: "CDROM"
2673 \end_layout
2675 \begin_layout Itemize
2676 Argument #2: Number of image slot to put there.
2678 \end_layout
2680 \begin_layout Standard
2681 The disk number MUST be -1 or valid disk number.
2682  -1 MUST NOT be used if there is no disk in CD-ROM.
2683  This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2684  to be ejected with no replacement if disk number is -1.
2685  The specified disk if not -1 must be of CD-ROM type.
2686 \end_layout
2688 \begin_layout Standard
2689 This event has no effect if CD-ROM is locked.
2690 \end_layout
2692 \begin_layout Subsubsection
2693 Write protect floppy:
2694 \end_layout
2696 \begin_layout Itemize
2697 Dispatch to: org.jpc.emulator.PC$DiskChanger
2698 \end_layout
2700 \begin_layout Itemize
2701 Argument #1: Fixed: "WRITEPROTECT"
2702 \end_layout
2704 \begin_layout Itemize
2705 Argument #2: Number of image slot to manipulate 
2706 \end_layout
2708 \begin_layout Standard
2709 Write protects specified disk.
2710  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2711 \end_layout
2713 \begin_layout Subsubsection
2714 Write unprotect floppy:
2715 \end_layout
2717 \begin_layout Itemize
2718 Dispatch to: org.jpc.emulator.PC$DiskChanger
2719 \end_layout
2721 \begin_layout Itemize
2722 Argument #1: Fixed: "WRITEUNPROTECT"
2723 \end_layout
2725 \begin_layout Itemize
2726 Argument #2: Number of image slot to manipulate 
2727 \end_layout
2729 \begin_layout Standard
2730 Disables write protection specified disk.
2731  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2732 \end_layout
2734 \begin_layout Subsection
2735 Diskinfo sections
2736 \end_layout
2738 \begin_layout Standard
2739 Diskinfo sections are named 
2740 \begin_inset Quotes eld
2741 \end_inset
2743 diskinfo-
2744 \begin_inset Quotes erd
2745 \end_inset
2747 <id of disk>.
2748  They use line component encoding, fieldtype being first component on each
2749  line (value being the second).
2750  Following fields are defined:
2751 \end_layout
2753 \begin_layout Subsubsection
2754 TYPE
2755 \end_layout
2757 \begin_layout Standard
2758 Gives type of image.
2759  Possible values are
2760 \end_layout
2762 \begin_layout Itemize
2763 \begin_inset Quotes eld
2764 \end_inset
2766 FLOPPY
2767 \begin_inset Quotes erd
2768 \end_inset
2770  (floppy disk)
2771 \end_layout
2773 \begin_layout Itemize
2774 \begin_inset Quotes eld
2775 \end_inset
2778 \begin_inset Quotes erd
2779 \end_inset
2781  (Hard disk)
2782 \end_layout
2784 \begin_layout Itemize
2785 \begin_inset Quotes eld
2786 \end_inset
2788 CDROM
2789 \begin_inset Quotes erd
2790 \end_inset
2792  (CD-ROM)
2793 \end_layout
2795 \begin_layout Itemize
2796 \begin_inset Quotes eld
2797 \end_inset
2799 BIOS
2800 \begin_inset Quotes erd
2801 \end_inset
2803  (BIOS/VGABIOS image)
2804 \end_layout
2806 \begin_layout Itemize
2807 \begin_inset Quotes eld
2808 \end_inset
2810 UNKNOWN
2811 \begin_inset Quotes erd
2812 \end_inset
2814  (what the heck is this???)
2815 \end_layout
2817 \begin_layout Subsubsection
2819 \end_layout
2821 \begin_layout Standard
2822 Gives ID of disk.
2823 \end_layout
2825 \begin_layout Subsubsection
2826 IMAGELENGTH
2827 \end_layout
2829 \begin_layout Standard
2830 (BIOS images only) Gives length of BIOS image
2831 \end_layout
2833 \begin_layout Subsubsection
2834 IMAGEMD5
2835 \end_layout
2837 \begin_layout Standard
2838 MD5 of raw disk/BIOS image without any headers or trailers.
2839 \end_layout
2841 \begin_layout Subsubsection
2842 TOTALSECTORS
2843 \end_layout
2845 \begin_layout Standard
2846 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
2847 \end_layout
2849 \begin_layout Subsubsection
2850 TRACKS
2851 \end_layout
2853 \begin_layout Standard
2854 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
2855  1-1024 for HDD).
2856 \end_layout
2858 \begin_layout Subsubsection
2859 SIDES
2860 \end_layout
2862 \begin_layout Standard
2863 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
2864  for HDD).
2865 \end_layout
2867 \begin_layout Subsubsection
2868 SECTORS
2869 \end_layout
2871 \begin_layout Standard
2872 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
2873  1-63 for HDD).
2874 \end_layout
2876 \begin_layout Subsubsection
2877 COMMENT
2878 \end_layout
2880 \begin_layout Standard
2881 Line from image comment block.
2882  Usually give data about files image has.
2883  May or may not be present (multiple times)
2884 \end_layout
2886 \begin_layout Subsection
2887 Savestates
2888 \end_layout
2890 \begin_layout Standard
2891 Actual savestate format is not documented here.
2892  It is close to impossible to comprehend without access to emulator source
2893  anyway.
2894 \end_layout
2896 \begin_layout Section
2897 Advanced: Making class dumpable
2898 \end_layout
2900 \begin_layout Standard
2901 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
2902  and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
2903  <init>(org.jpc.emulator.SRLoader).
2904  Non-static inner classes can not be dumpable (make them static using tricks
2905  similar to what javac uses).
2906 \end_layout
2908 \begin_layout Standard
2909 If dumped class has dumpable superclass, the first thing dumping function
2910  needs to do is to call dumper function of superclass and first thing loading
2911  constructor needs to do is to call loading constructor of superclass.
2912  If class has no dumpable superclass, dumper doesn't need to do anything
2913  special, while loader needs to call objectCreated(this) on SRLoader object
2914  passed as parameter.
2916 \end_layout
2918 \begin_layout Standard
2919 Following these fixed parts, dump all members that are part of mutable state
2920  in emulator core.
2921 \end_layout
2923 \begin_layout Subsection
2924 Member dumping/loading functions
2925 \end_layout
2927 \begin_layout Standard
2928 There is dumping/loading function for following (all functions dumping/loading
2929  reference types can handle null):
2930 \end_layout
2932 \begin_layout Itemize
2933 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
2934 \end_layout
2936 \begin_layout Itemize
2937 byte: SRDumper.dumpByte, SRLoader.loadByte
2938 \end_layout
2940 \begin_layout Itemize
2941 short: SRDumper.dumpShort, SRLoader.loadShort
2942 \end_layout
2944 \begin_layout Itemize
2945 int: SRDumper.dumpInt, SRLoader.loadInt
2946 \end_layout
2948 \begin_layout Itemize
2949 long: SRDumper.dumpLong, SRLoader.loadLong
2950 \end_layout
2952 \begin_layout Itemize
2953 String: SRDumper.dumpString, SRLoader.loadString
2954 \end_layout
2956 \begin_layout Itemize
2957 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
2958 \end_layout
2960 \begin_layout Itemize
2961 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
2962 \end_layout
2964 \begin_layout Itemize
2965 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
2966 \end_layout
2968 \begin_layout Itemize
2969 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
2970 \end_layout
2972 \begin_layout Itemize
2973 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
2974 \end_layout
2976 \begin_layout Itemize
2977 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
2978 \end_layout
2980 \begin_layout Itemize
2981 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
2982 \end_layout
2984 \begin_layout Itemize
2985 special object: SRDumper.specialObject, SRLoader.specialObject
2986 \end_layout
2988 \begin_layout Subsubsection
2989 Notes:
2990 \end_layout
2992 \begin_layout Itemize
2993 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
2994 \end_layout
2996 \begin_layout Itemize
2997 Special objects are various static objects that don't need to be stored
2998  because they don't have mutable fields.
2999 \end_layout
3001 \begin_layout Itemize
3002 Don't dump fields related to event state feedback.
3003 \end_layout
3005 \begin_layout Itemize
3006 Don't dump temporary flags that are only used while PC is running.
3007  Savestate when PC is running isn't possible anyway.
3008 \end_layout
3010 \begin_layout Itemize
3011 Some connectors dump fields related to connector output, some don't.
3012 \end_layout
3014 \begin_layout Section
3015 Advanced: Making output connectors
3016 \end_layout
3018 \begin_layout Standard
3019 Implementing interface org.jpc.emulator.DisplayController signals that this
3020  is display controller, inhibiting loading of the standard VGA display controlle
3021 r if loaded as module.
3023 \end_layout
3025 \begin_layout Subsection
3026 Interface org.jpc.emulator.OutputConnector
3027 \end_layout
3029 \begin_layout Standard
3030 Class is made to be output connector by implementing this interface.
3031  This interface specifies the methods used for output hold locking.
3032  Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3033  that are suitable for calling.
3035 \end_layout
3037 \begin_layout Subsubsection
3038 Method subscribeOutput(Object)
3039 \end_layout
3041 \begin_layout Standard
3042 Subscribes the output, with specified object as handle.
3043 \end_layout
3045 \begin_layout Subsubsection
3046 Method unsubscribeOutput(Object)
3047 \end_layout
3049 \begin_layout Standard
3050 Unsubscribe the specified handle object from output.
3051 \end_layout
3053 \begin_layout Subsubsection
3054 Method waitOutput(Object)
3055 \end_layout
3057 \begin_layout Standard
3058 Wait for output on specified connector using specified handle object.
3059  Returns true on success, false if wait was interrupted by thread interrupt.
3060  Blocking.
3061 \end_layout
3063 \begin_layout Subsubsection
3064 Method releaseOutput(Object)
3065 \end_layout
3067 \begin_layout Standard
3068 Release connector from p.o.v.
3069  of given handle.
3070  Does not block.
3071 \end_layout
3073 \begin_layout Subsubsection
3074 Method holdOutput()
3075 \end_layout
3077 \begin_layout Standard
3078 Release threads waiting on waitOutput() and block until all subscribers
3079  have returned from waitOutput() and enteired releaseOutput().
3080 \end_layout
3082 \begin_layout Subsubsection
3083 Method releaseOutputWaitAll(object)
3084 \end_layout
3086 \begin_layout Standard
3087 Like releaseOutput(), but waits until all handles have released their output.
3088 \end_layout
3090 \begin_layout Subsection
3091 Class org.jpc.emulator.VGADigtalOut
3092 \end_layout
3094 \begin_layout Standard
3095 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3096  VGA output connector.
3097  If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3098 yController.
3099 \end_layout
3101 \begin_layout Subsubsection
3102 Method getWidth()
3103 \end_layout
3105 \begin_layout Standard
3106 Get width of display (watch out, can return 0).
3107 \end_layout
3109 \begin_layout Subsubsection
3110 Method getHeight()
3111 \end_layout
3113 \begin_layout Standard
3114 Get height of display (watch out, can return 0).
3115 \end_layout
3117 \begin_layout Subsubsection
3118 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3119 \end_layout
3121 \begin_layout Standard
3122 Returns the dirty region (region modified since last output).
3123 \end_layout
3125 \begin_layout Subsubsection
3126 Method getBuffer()
3127 \end_layout
3129 \begin_layout Standard
3130 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3131  one value per pixel) giving pixel data.
3132  Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3133  + <blue-component>.
3134 \end_layout
3136 \begin_layout Subsubsection
3137 Method resizeDisplay(int _width, int _height)
3138 \end_layout
3140 \begin_layout Standard
3141 Resize the display to be of specified size.
3142 \end_layout
3144 \begin_layout Subsubsection
3145 Method dirtyDisplayRegion(int x, int y, int w, int h)
3146 \end_layout
3148 \begin_layout Standard
3149 Mark the specified region as dirty.
3150 \end_layout
3152 \begin_layout Subsubsection
3153 Method resetDirtyRegion()
3154 \end_layout
3156 \begin_layout Standard
3157 Resets the dirty region to be empty.
3158 \end_layout
3160 \begin_layout Subsection
3161 Class org.jpc.emulator.PC method getVideoOutput()
3162 \end_layout
3164 \begin_layout Standard
3165 Get VGA output connector for PC.
3166 \end_layout
3168 \begin_layout Subsection
3169 Interface org.jpc.emulator.DisplayController.
3170 \end_layout
3172 \begin_layout Standard
3173 Implementing this class signals that module is VGA controller.
3174  There can be only one such module active at time and presence of such module
3175  prevents loading builtin VGA controller emulation code.
3176 \end_layout
3178 \begin_layout Subsubsection
3179 Method getOutputDevice()
3180 \end_layout
3182 \begin_layout Standard
3183 Get VGA output connector for this VGA device.
3184 \end_layout
3186 \begin_layout Subsection
3187 Class org.jpc.emulator.SoundDigitalOut
3188 \end_layout
3190 \begin_layout Standard
3191 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3192  Each connector can transfer stereo signal at arbitiary sampling rate.
3193  Modules that have audio connectors need to implement interface org.jpc.emulator.So
3194 undOutputDevice, as this signals that output connectors should be created.
3195 \end_layout
3197 \begin_layout Subsubsection
3198 Method addSample(long, short, short)
3199 \end_layout
3201 \begin_layout Standard
3202 Add stereo sample at time given by first argument.
3203  The second and third arguments give volume on left and right channels.
3204 \end_layout
3206 \begin_layout Subsubsection
3207 Method addSample(long, short)
3208 \end_layout
3210 \begin_layout Standard
3211 Add mono sample at time given by first argument.
3212  The second argument give volume on both channels.
3213 \end_layout
3215 \begin_layout Subsubsection
3216 Method readBlock(Block)
3217 \end_layout
3219 \begin_layout Standard
3220 Reads block of output (atomic versus addSample).
3221  Block structure has following fields which are filled:
3222 \end_layout
3224 \begin_layout Itemize
3225 timeBase: Time base for block.
3226 \end_layout
3228 \begin_layout Itemize
3229 baseLeft: Left volume at time base.
3230 \end_layout
3232 \begin_layout Itemize
3233 baseRight: Right volume at time base
3234 \end_layout
3236 \begin_layout Itemize
3237 blockNo: Sequence number of block filled.
3238 \end_layout
3240 \begin_layout Itemize
3241 samples: Number of samples in block
3242 \end_layout
3244 \begin_layout Itemize
3245 sampleTiming: Number of nanoseconds since last sample
3246 \end_layout
3248 \begin_layout Itemize
3249 sampleLeft: Left channel samples
3250 \end_layout
3252 \begin_layout Itemize
3253 sampleRight: Right channel samples
3254 \end_layout
3256 \begin_layout Subsection
3257 Interface org.jpc.emulator.SoundOutputDevice
3258 \end_layout
3260 \begin_layout Standard
3261 Implementing this interface signals that module has audio output channels.
3262 \end_layout
3264 \begin_layout Subsubsection
3265 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3266 \end_layout
3268 \begin_layout Standard
3269 Return the number of sound channels module has.
3270 \end_layout
3272 \begin_layout Subsubsection
3273 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3274 \end_layout
3276 \begin_layout Standard
3277 This is called once per sound channel requested giving precreated sound
3278  channel.
3279 \end_layout
3281 \begin_layout Subsection
3282 Class org.jpc.emulator.PC method getSoundOut(String)
3283 \end_layout
3285 \begin_layout Standard
3286 Get sound output with specified name.
3287 \end_layout
3289 \begin_layout Section
3290 Advanced: Writing event targets
3291 \end_layout
3293 \begin_layout Standard
3294 Whereas output connectors are the way output is dispatched, input is dispatched
3295  via event targets.
3296  Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3297 \end_layout
3299 \begin_layout Standard
3300 Event targets also provode methods which then encode events and dispatch
3301  them forward (without doing anything else) to event recorder.
3302  Also, event targets may have methods for obtaining state.
3303 \end_layout
3305 \begin_layout Subsection
3306 Interface org.jpc.emulator.EventDispatchTarget
3307 \end_layout
3309 \begin_layout Standard
3310 Interface that marks class capable of receiving events.
3311 \end_layout
3313 \begin_layout Subsubsection
3314 Method setEventRecorder(EventRecorder)
3315 \end_layout
3317 \begin_layout Standard
3318 Set the event recorder input events are sent to.
3319 \end_layout
3321 \begin_layout Subsubsection
3322 Method startEventCheck()
3323 \end_layout
3325 \begin_layout Standard
3326 Signals target to reset all state related to event checking and state feedback.
3327  This may be called at any time in order to reinitialialize event checking/feedb
3328 ack state.
3329 \end_layout
3331 \begin_layout Subsubsection
3332 Method doEvent(long, String[], int) throws IOException
3333 \end_layout
3335 \begin_layout Standard
3336 Event dispatch handler.
3337  The first argument is event time, second is parameters and third is what
3338  to do with it.
3339  If target doesn't like the event, throw IOException.
3340  Following types (the integer parameter) are used:
3341 \end_layout
3343 \begin_layout LyX-Code
3344 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3345 \end_layout
3347 \begin_layout LyX-Code
3348 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3349  for reinitialization
3350 \end_layout
3352 \begin_layout LyX-Code
3353 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3354 \end_layout
3356 \begin_layout LyX-Code
3357 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3358  Execute the effect.
3359 \end_layout
3361 \begin_layout Subsubsection
3362 Method endEventCheock()
3363 \end_layout
3365 \begin_layout Standard
3366 End event reinitialization.
3367  Usually unused.
3368 \end_layout
3370 \begin_layout Subsubsection
3371 Method getEventTimeLowBound(long, String[]) throws IOException
3372 \end_layout
3374 \begin_layout Standard
3375 Return the time value that's the earliest possiblity for this event to occur.
3376  Returning any time in past (including -1) causes event to fire as soon
3377  as possible.
3378  The long parameter gives the current scheduled time for event.
3379 \end_layout
3381 \begin_layout Section
3382 Writing modules
3383 \end_layout
3385 \begin_layout Standard
3386 Modules are various extensions that run inside emulator core.
3387  As such, they affect sync.
3388  Modules must implement interface org.jpc.emulator.HardwareComponent (they
3389  are hardware components) and must be dumpable.
3390  Additionally, they need either constructor <init>() or <init>(String).
3391  The first is if no parameters are passed, the second is for case where
3392  parameters are passed.
3393 \end_layout
3395 \begin_layout Standard
3396 Aside of the constructors, modules need to obey the ordinary conventions
3397  for hardware components.
3398  No code outside modules needs to know that module exists.
3399 \end_layout
3401 \begin_layout Section
3402 Writing plugins
3403 \end_layout
3405 \begin_layout Standard
3406 Plugins handle various UI tasks.
3407  They need to implement interface org.jpc.Plugin.
3408 \end_layout
3410 \begin_layout Subsection
3411 Interface org.jpc.pluginsbase.Plugin
3412 \end_layout
3414 \begin_layout Subsubsection
3415 Method systemShutdown()
3416 \end_layout
3418 \begin_layout Standard
3419 Called when emulator shuts down.
3420  Either called in dedicated thread or in thread that called emulatorShutdown().
3421  These handlers should do the bare minimum to get files on disk to consistent
3422  state.
3423  After these calls from all plugins have finished, emulator exits.
3424  Do not try to manipulate UI from these methods, as doing that easily leads
3425  into deadlock.
3426 \end_layout
3428 \begin_layout Subsubsection
3429 Method reconnect(PC) 
3430 \end_layout
3432 \begin_layout Standard
3433 Gives new PC to connect to.
3434  Null is passed if plugin should disconnect.
3435 \end_layout
3437 \begin_layout Subsubsection
3438 Method main()
3439 \end_layout
3441 \begin_layout Standard
3442 Called in dedicated thread after plugin is initialized.
3443 \end_layout
3445 \begin_layout Subsubsection
3446 Method pcStopping()
3447 \end_layout
3449 \begin_layout Standard
3450 Called after PC has stopped.
3451 \end_layout
3453 \begin_layout Subsubsection
3454 Method pcStarting()
3455 \end_layout
3457 \begin_layout Standard
3458 Called before PC starts.
3459 \end_layout
3461 \begin_layout Subsubsection
3462 Method notifyArguments(String[])
3463 \end_layout
3465 \begin_layout Standard
3466 Pass arguments from command line.
3467 \end_layout
3469 \begin_layout Subsubsection
3470 Constructor <init>(Plugins)
3471 \end_layout
3473 \begin_layout Standard
3474 This constructor is used to initialize plugins that don't take parameters.
3475 \end_layout
3477 \begin_layout Subsubsection
3478 Constructor <init>(Plugins, String)
3479 \end_layout
3481 \begin_layout Standard
3482 This constructor is used to initialize plugins that take parameters.
3483 \end_layout
3485 \begin_layout Subsection
3486 Class org.jpc.pluginsbase.Plugins
3487 \end_layout
3489 \begin_layout Standard
3490 This class provodes various methods for manipulating plugins.
3491 \end_layout
3493 \begin_layout Subsubsection
3494 Method isShuttingDown()
3495 \end_layout
3497 \begin_layout Standard
3498 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3499  via VM exit, CTRL+C or explicitly.
3500  Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3501 \end_layout
3503 \begin_layout Subsubsection
3504 Method shutdownEmulator()
3505 \end_layout
3507 \begin_layout Standard
3508 Shut down and exit the emulator.
3509  All plugin shutdown functions are called in this thread.
3510 \end_layout
3512 \begin_layout Subsubsection
3513 Method reconnectPC(PC)
3514 \end_layout
3516 \begin_layout Standard
3517 Signal reconnectPC event to all plugins.
3518 \end_layout
3520 \begin_layout Subsubsection
3521 Method pcStarted()
3522 \end_layout
3524 \begin_layout Standard
3525 Signal pcStarting() event to all plugins.
3526 \end_layout
3528 \begin_layout Subsubsection
3529 Method pcStopped()
3530 \end_layout
3532 \begin_layout Standard
3533 Signal pcStopping() event to all plugins.
3534 \end_layout
3536 \begin_layout Section
3537 Inter-plugin communication
3538 \end_layout
3540 \begin_layout Subsection
3541 Receiving communications
3542 \end_layout
3544 \begin_layout Standard
3545 To receive invocation/call by name 'foo-bar', declare public method named
3546  'eci_foo_bar'.
3547  Arguments to this method can currently be String, Integer (int) or Long
3548  (long).
3549  Last argument may be array over these types to get variable number of arguments.
3550  On call, each argument gets value from call.
3551  If last argument is array, it gets all overflowing arguments.
3552  If return type is void or method returns boolean false, call is assumed
3553  to have completed.
3554  If return value is boolean true, it is assumed that there is more processing.
3555 \end_layout
3557 \begin_layout Subsection
3558 void org.jpc.pluginsbase.Plugins.invokeExternalCommand(String cmd, Object[]
3559  args) 
3560 \end_layout
3562 \begin_layout Standard
3563 Invoke command asynchronously, broadcasting to all plugins.
3564  Does not wait for slow commands to complete.
3565  cmd is the name to send and args are the arguments to pass.
3566 \end_layout
3568 \begin_layout Subsection
3569 void org.jpc.pluginsbase.Plugins.invokeExternalCommandSynchronous(String cmd,
3570  Object[] args) 
3571 \end_layout
3573 \begin_layout Standard
3574 Same as invokeExternalCommand, but waits for slow commands to complete.
3575 \end_layout
3577 \begin_layout Subsection
3578 Object[] org.jpc.pluginsbase.Plugins.invokeExternalCommandReturn(String cmd,
3579  Object[] args) 
3580 \end_layout
3582 \begin_layout Standard
3583 Similar to invokeExternalCommandSynchornous, but:
3584 \end_layout
3586 \begin_layout Itemize
3587 Quits calling more plugins when it gets successful reply.
3588 \end_layout
3590 \begin_layout Itemize
3591 Returns said reply
3592 \end_layout
3594 \begin_layout Subsection
3595 void org.jpc.pluginsbase.Plugins.returnValue(Object...
3596  ret)
3597 \end_layout
3599 \begin_layout Standard
3600 Gives return value to return from call and signals that command has completed.
3601 \end_layout
3603 \begin_layout Subsection
3604 void org.jpc.pluginsbase.Plugins.signalCommandCompletion()
3605 \end_layout
3607 \begin_layout Standard
3608 Signals that command has completed.
3609  Only needed if there is no return value and eci_ method returned false
3610  (not done yet).
3611 \end_layout
3613 \begin_layout Section
3614 Lua kernel programming
3615 \end_layout
3617 \begin_layout Standard
3618 At startup, kernel gets its arguments in 'args' table and the script name
3619  to run in 'scriptname' string.
3620  It should enter the named script in protected mode.
3621 \end_layout
3623 \begin_layout Standard
3624 The Lua VM exports numerious callbacks to kernel.
3625  The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3626 \end_layout
3628 \begin_layout Itemize
3629 Always grab any functions used into local variables so nobody can mess with
3630  them
3631 \end_layout
3633 \begin_layout Itemize
3634 Don't use global variables in kernel (except for those passed).
3635 \end_layout
3637 \end_body
3638 \end_document