manual.lyx

   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
  17
  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
  49
  50 \begin_body
  51
  52 \begin_layout Title
  53 JPC-RR: User's manual
  54 \end_layout
  55
  56 \begin_layout Section
  57 Licence
  58 \end_layout
  59
  60 \begin_layout Standard
  61 JPC-RR is licenced under GNU GPL v2.
  62  See file
  63 \begin_inset Quotes eld
  64 \end_inset
  65
  66 LICENSE
  67 \begin_inset Quotes erd
  68 \end_inset
  69
  70
  71 \end_layout
  72
  73 \begin_layout Section
  74 Getting started
  75 \end_layout
  76
  77 \begin_layout Subsection
  78 Prerequisites
  79 \end_layout
  80
  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.
  86
  87 \end_layout
  88
  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
  94
  95 \begin_layout Standard
  96 See compile.sh.
  97  The stuff in streamtools is only needed for recording videos.
  98 \end_layout
  99
 100 \begin_layout Subsection
 101 Compiling
 102 \end_layout
 103
 104 \begin_layout Standard
 105 See compile.sh.
 106  The streamtools stuff is only needed for dumping videos.
 107 \end_layout
 108
 109 \begin_layout Subsection
 110 Getting started
 111 \end_layout
 112
 113 \begin_layout Standard
 114 First you need to get and make some important images.
 115  Obtain BIOS image, VGABIOS image and DOS boot floppy from somewhere.
 116  After starting the emulator, use File -> Import Image to import the images
 117  (ignore the error about no BIOS images being found).
 118 \end_layout
 119
 120 \begin_layout Subsection
 121 Running emulator
 122 \end_layout
 123
 124 \begin_layout Standard
 125 There is premade autoexec script called assemble.bat that has fairly reasonable
 126  defaults.
 127  To use it:
 128 \end_layout
 129
 130 \begin_layout LyX-Code
 131 java JPCApplication -library library -autoexec assemble.bat
 132 \end_layout
 133
 134 \begin_layout Standard
 135 The
 136 \begin_inset Quotes eld
 137 \end_inset
 138
 139 -library library
 140 \begin_inset Quotes erd
 141 \end_inset
 142
 143  specifies that contents of directory 'library' are to be used as library.
 144  The script pops up settings for new emulated PC (if you want to load savestate,
 145  click cancel).
 146  Select BIOS and VGABIOS for BIOS and VGABIOS image (they should be already
 147  selected), DOSfloppy for fda (boot device should be set to fda) and game
 148  image as some HD drive
 149 \end_layout
 150
 151 \begin_layout Subsection
 152 Bootup tips
 153 \end_layout
 154
 155 \begin_layout Itemize
 156 Putting the game as hdd causes boot to be bit faster.
 157 \end_layout
 158
 159 \begin_layout Itemize
 160 Some BIOS versions have
 161 \begin_inset Quotes eld
 162 \end_inset
 163
 164 press F12 to select boot device
 165 \begin_inset Quotes erd
 166 \end_inset
 167
 168 .
 169  Hit <enter> from emulated keyboard and that prompt will go away in about
 170  half emulated second (it stays several emulated seconds otherwise).
 171
 172 \end_layout
 173
 174 \begin_layout Itemize
 175 If game doesn't need lots of memory, hitting F5 to skip intialization files
 176  is fastest.
 177  If it does need more memory, run config.sys commands but not autoexec.bat.
 178
 179 \end_layout
 180
 181 \begin_layout Itemize
 182 Some DOS disks have DOSIDLE with them, don't use it as it messes badly with
 183  emulator.
 184 \end_layout
 185
 186 \begin_layout Section
 187 Making JPC-RR format images from raw images
 188 \end_layout
 189
 190 \begin_layout Standard
 191 Due to various factors, JPC-RR can't use raw image files directly but requires
 192  its own image format.
 193
 194 \end_layout
 195
 196 \begin_layout Subsection
 197 Importing images from GUI:
 198 \end_layout
 199
 200 \begin_layout Standard
 201 Use File -> Import Image to import existing directories or image files.
 202  Dialog prompting parameters will be displayed.
 203  When importing floppy images, check
 204 \begin_inset Quotes eld
 205 \end_inset
 206
 207 standard geometry
 208 \begin_inset Quotes erd
 209 \end_inset
 210
 211  if possible, that enables geometry autodetection, which is reasonable virtually
 212  all of the time it is offered.
 213 \end_layout
 214
 215 \begin_layout Subsection
 216 Notes
 217 \end_layout
 218
 219 \begin_layout Itemize
 220 If making image from directory, the names of the files must conform to FAT
 221  naming restrictions (8+3 character names, no spaces, etc).
 222  Avoid filenames with non-ASCII characters.
 223
 224 \end_layout
 225
 226 \begin_layout Itemize
 227 The DOS limit of 112 or 224 files for floppies does not apply to images
 228  created from directory trees.
 229  The minimum limit value used is 512.
 230  If even that isn't enough, the limit is automatically increased to fit
 231  all the needed directory entries.
 232 \end_layout
 233
 234 \begin_layout Itemize
 235 Making boot disks from tree does NOT work.
 236  Even if you got system boot files there, it still won't work.
 237 \end_layout
 238
 239 \begin_layout Itemize
 240 Only floppy disks and hard drives can be made from directory trees.
 241  BIOS images and CDROM images require image file.
 242 \end_layout
 243
 244 \begin_layout Itemize
 245 Avoid floppies with custom geometry (floppy geometry does affect disk ID).
 246  Disks with over 63 sectors per track don't work with DOS.
 247  Wheither disks with over 127 tracks per side work with DOS is unknown.
 248  Also avoid 1024-tracks per side HDDs.
 249 \end_layout
 250
 251 \begin_layout Itemize
 252 The geometry limits are: 2-1024 tracks per side for HDD, 1-256 tracks per
 253  side for floppy.
 254  1-63 sectors per track for HDD, 1-255 sectors per track for floppy.
 255  1-16 sides for HDD, 1 or 2 sides for floppy.
 256  This gives size limit of 65280KiB for floppy disks (but note the DOS limit!)
 257  and 516096KiB for HDDs.
 258 \end_layout
 259
 260 \begin_layout Itemize
 261 There are multiple image file contents that represent the same image.
 262  The one with smallest size is picked when creating image.
 263 \end_layout
 264
 265 \begin_layout Itemize
 266 Note: Although the IDs are 128 bits long, they are not MD5 hashes.
 267
 268 \end_layout
 269
 270 \begin_layout Subsection
 271 Importing from command line
 272 \end_layout
 273
 274 \begin_layout Standard
 275 There is tool called ImageMaker that can make JPC-RR images from raw images.
 276  Each image has format, ID an name.
 277  Format and name are specified when making image.
 278  ID is automatically calculated from format and contents.
 279  Name does not affect the ID but is purely for convience so one doesn't
 280  have to specify long image IDs manually.
 281 \end_layout
 282
 283 \begin_layout Subsubsection
 284 Syntax
 285 \end_layout
 286
 287 \begin_layout Standard
 288 The syntax for ImageMaker when making images is:
 289 \end_layout
 290
 291 \begin_layout LyX-Code
 292 $ java ImageMaker <format> [<options>...] <destination> <source> <name>
 293 \end_layout
 294
 295 \begin_layout Standard
 296 <destination> is file name for JPC-RR format image to write.
 297  <source> is either name of regular file (raw image file) or name of directory
 298  tree with files (supported for making floppy or hard disk images only).
 299  In case of directory tree, the files are layout deterministically to disk,
 300  so the ID will always be the same for given geometry and type.
 301  <name> is name to give to disk.
 302  <format> is one of:
 303 \end_layout
 304
 305 \begin_layout LyX-Code
 306 --BIOS BIOS image (note: VGABIOS is also of this type).
 307 \end_layout
 308
 309 \begin_layout LyX-Code
 310 --CDROM CD-ROM image.
 311 \end_layout
 312
 313 \begin_layout LyX-Code
 314 --HDD=cylinders,sectors,heads Hard disk with specified geometry.
 315 \end_layout
 316
 317 \begin_layout LyX-Code
 318 --floppy=tracks,sectors,sides Floppy disk with specified geometry.
 319 \end_layout
 320
 321 \begin_layout LyX-Code
 322 --floppy160 160KiB floppy (40 tracks, 8 sectors, Single sided).
 323 \end_layout
 324
 325 \begin_layout LyX-Code
 326 --floppy180 180KiB floppy (40 tracks, 9 sectors, Single sided).
 327 \end_layout
 328
 329 \begin_layout LyX-Code
 330 --floppy320 320KiB floppy (40 tracks, 8 sectors, Double sided).
 331 \end_layout
 332
 333 \begin_layout LyX-Code
 334 --floppy360 360KiB floppy (40 tracks, 9 sectors, Double sided).
 335 \end_layout
 336
 337 \begin_layout LyX-Code
 338 --floppy410 410KiB floppy (41 tracks, 10 sectors, Double sided).
 339 \end_layout
 340
 341 \begin_layout LyX-Code
 342 --floppy420 420KiB floppy (42 tracks, 10 sectors, Double sided).
 343 \end_layout
 344
 345 \begin_layout LyX-Code
 346 --floppy720 720KiB floppy (80 tracks, 9 sectors, Double sided).
 347 \end_layout
 348
 349 \begin_layout LyX-Code
 350 --floppy800 800KiB floppy (80 tracks, 10 sectors, Double sided).
 351 \end_layout
 352
 353 \begin_layout LyX-Code
 354 --floppy820 820KiB floppy (82 tracks, 10 sectors, Double sided).
 355 \end_layout
 356
 357 \begin_layout LyX-Code
 358 --floppy830 830KiB floppy (83 tracks, 10 sectors, Double sided).
 359 \end_layout
 360
 361 \begin_layout LyX-Code
 362 --floppy880 880KiB floppy (80 tracks, 11 sectors, Double sided).
 363 \end_layout
 364
 365 \begin_layout LyX-Code
 366 --floppy1040 1040KiB floppy (80 tracks, 13 sectors, Double sided).
 367 \end_layout
 368
 369 \begin_layout LyX-Code
 370 --floppy1120 1120KiB floppy (80 tracks, 14 sectors, Double sided).
 371 \end_layout
 372
 373 \begin_layout LyX-Code
 374 --floppy1200 1200KiB floppy (80 tracks, 15 sectors, Double sided).
 375 \end_layout
 376
 377 \begin_layout LyX-Code
 378 --floppy1440 1440KiB floppy (80 tracks, 18 sectors, Double sided).
 379 \end_layout
 380
 381 \begin_layout LyX-Code
 382 --floppy1476 1476KiB floppy (82 tracks, 18 sectors, Double sided).
 383 \end_layout
 384
 385 \begin_layout LyX-Code
 386 --floppy1494 1494KiB floppy (83 tracks, 18 sectors, Double sided).
 387 \end_layout
 388
 389 \begin_layout LyX-Code
 390 --floppy1600 1600KiB floppy (80 tracks, 20 sectors, Double sided).
 391 \end_layout
 392
 393 \begin_layout LyX-Code
 394 --floppy1680 1680KiB floppy (80 tracks, 21 sectors, Double sided).
 395 \end_layout
 396
 397 \begin_layout LyX-Code
 398 --floppy1722 1722KiB floppy (82 tracks, 21 sectors, Double sided).
 399 \end_layout
 400
 401 \begin_layout LyX-Code
 402 --floppy1743 1743KiB floppy (83 tracks, 21 sectors, Double sided).
 403 \end_layout
 404
 405 \begin_layout LyX-Code
 406 --floppy1760 1760KiB floppy (80 tracks, 22 sectors, Double sided).
 407 \end_layout
 408
 409 \begin_layout LyX-Code
 410 --floppy1840 1840KiB floppy (80 tracks, 23 sectors, Double sided).
 411 \end_layout
 412
 413 \begin_layout LyX-Code
 414 --floppy1920 1920KiB floppy (80 tracks, 24 sectors, Double sided).
 415 \end_layout
 416
 417 \begin_layout LyX-Code
 418 --floppy2880 2880KiB floppy (80 tracks, 36 sectors, Double sided).
 419 \end_layout
 420
 421 \begin_layout LyX-Code
 422 --floppy3120 3120KiB floppy (80 tracks, 39 sectors, Double sided).
 423 \end_layout
 424
 425 \begin_layout LyX-Code
 426 --floppy3200 3200KiB floppy (80 tracks, 40 sectors, Double sided).
 427 \end_layout
 428
 429 \begin_layout LyX-Code
 430 --floppy3520 3520KiB floppy (80 tracks, 44 sectors, Double sided).
 431 \end_layout
 432
 433 \begin_layout LyX-Code
 434 --floppy3840 3840KiB floppy (80 tracks, 48 sectors, Double sided).
 435 \end_layout
 436
 437 \begin_layout Subsubsection
 438 Other options
 439 \end_layout
 440
 441 \begin_layout LyX-Code
 442 --volumelabel=label Give specified volume label (affects ID).
 443  Only meaningful when making image out of directory tree.
 444  Default is no volume label.
 445 \end_layout
 446
 447 \begin_layout LyX-Code
 448 --timestamp=YYYYMMDDHHMMSS Give specified timestamp for files (affects ID).
 449  Only meaningful when making image out of directory tree.
 450  The default timestamp is 19900101T000000Z.
 451 \end_layout
 452
 453 \begin_layout Subsubsection
 454 Image information
 455 \end_layout
 456
 457 \begin_layout Standard
 458 When invoked as:
 459 \end_layout
 460
 461 \begin_layout LyX-Code
 462 $ java ImageMaker <imagefile>
 463 \end_layout
 464
 465 \begin_layout Standard
 466 Variety of information about image is displayed (especially for floppies/HDDs).
 467  Two important fields are calculated and claimed disk ID.
 468  They should be the same.
 469  If they are not, then the image file is corrupt (sadly, imagemaker has
 470  bugs and bugs that cause it to write corrupt images have been seen).
 471 \end_layout
 472
 473 \begin_layout Subsection
 474 Advanced: The disk ID algorithm
 475 \end_layout
 476
 477 \begin_layout Standard
 478 The disk ID is calculated as:
 479 \end_layout
 480
 481 \begin_layout LyX-Code
 482 Skein-256-128-deprecated(<typecode>|<geometry>|<image>)
 483 \end_layout
 484
 485 \begin_layout Standard
 486 Where Skein-256-128-deprecated is Skein hash function with 256-bit internal
 487  state and 128-bit output using the deprecated rotation constants (as specified
 488  in Skein hash function reference documentation versions 1.0 and 1.1).
 489  The <image> is the whole image, including parts not stored in image file.
 490  The reason for keeping using the deprecated constants are:
 491 \end_layout
 492
 493 \begin_layout Itemize
 494 Changing the constants would change the IDs, which would invalidate existing
 495  images
 496 \end_layout
 497
 498 \begin_layout Itemize
 499 This is not about cryptographic security
 500 \end_layout
 501
 502 \begin_layout Itemize
 503 The new constants don't improve security that much anyway.
 504 \end_layout
 505
 506 \begin_layout Subsubsection
 507 Floppies and HDDs
 508 \end_layout
 509
 510 \begin_layout Standard
 511 Floppies have <typecode> value 0 (single byte) and HDDs have 1 (single byte).
 512  <geometry> is as follows (this is exactly the same form as it appears in
 513  image header):
 514 \end_layout
 515
 516 \begin_layout LyX-Code
 517 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
 518 \end_layout
 519
 520 \begin_layout LyX-Code
 521 Byte 0 bits 2-5: Head count - 1.
 522 \end_layout
 523
 524 \begin_layout LyX-Code
 525 Byte 0 bits 6-7: Reserved, must be 0.
 526 \end_layout
 527
 528 \begin_layout LyX-Code
 529 Byte 1: Bits 0-7 of track count per side - 1.
 530 \end_layout
 531
 532 \begin_layout LyX-Code
 533 Byte 2: Sector count per track - 1.
 534 \end_layout
 535
 536 \begin_layout Subsubsection
 537 CD-ROM and BIOS images
 538 \end_layout
 539
 540 \begin_layout Standard
 541 CD-ROMs have <typecode> value 2 (single byte) and BIOS images have 3 (single
 542  byte).
 543  <geometry> is blank.
 544 \end_layout
 545
 546 \begin_layout Subsection
 547 Advanced: Disk Image format
 548 \end_layout
 549
 550 \begin_layout Standard
 551 The disk image consists of following parts:
 552 \end_layout
 553
 554 \begin_layout Itemize
 555 Magic
 556 \end_layout
 557
 558 \begin_layout Itemize
 559 Disk ID
 560 \end_layout
 561
 562 \begin_layout Itemize
 563 Type code
 564 \end_layout
 565
 566 \begin_layout Itemize
 567 Disk name length
 568 \end_layout
 569
 570 \begin_layout Itemize
 571 Disk name
 572 \end_layout
 573
 574 \begin_layout Itemize
 575 type-specific geometry/size data
 576 \end_layout
 577
 578 \begin_layout Itemize
 579 Actual image data
 580 \end_layout
 581
 582 \begin_layout Subsubsection
 583 Magic
 584 \end_layout
 585
 586 \begin_layout Standard
 587 Magic in disk image files is following 5 bytes:
 588 \begin_inset Quotes eld
 589 \end_inset
 590
 591 IMAGE
 592 \begin_inset Quotes erd
 593 \end_inset
 594
 595
 596 \end_layout
 597
 598 \begin_layout Subsubsection
 599 Disk ID
 600 \end_layout
 601
 602 \begin_layout Standard
 603 Disk ID is given as 16 bytes, encoding the 128-bit disk ID.
 604 \end_layout
 605
 606 \begin_layout Subsubsection
 607 Type code
 608 \end_layout
 609
 610 \begin_layout Standard
 611 Type code is single byte.
 612  0 for floppies, 1 for HDDs, 2 for CD-ROMs and 3 for BIOS images.
 613  Other values are reserved.
 614 \end_layout
 615
 616 \begin_layout Subsubsection
 617 Comment length
 618 \end_layout
 619
 620 \begin_layout Standard
 621 Disk comment length is given as two-byte big-endian value.
 622  New images should have 0 here.
 623 \end_layout
 624
 625 \begin_layout Subsubsection
 626 Disk coment
 627 \end_layout
 628
 629 \begin_layout Standard
 630 Ignored.
 631  Comment field is there for backward compatiblity.
 632  Comment length gives length of this field in bytes.
 633 \end_layout
 634
 635 \begin_layout Subsubsection
 636 Type-specific geometry/size data (floppies and HDDs)
 637 \end_layout
 638
 639 \begin_layout Standard
 640 Floppies and HDDs have 3-byte geometry data:
 641 \end_layout
 642
 643 \begin_layout LyX-Code
 644 Byte 0 bits 0-1: Bits 8-9 of track count per side - 1.
 645 \end_layout
 646
 647 \begin_layout LyX-Code
 648 Byte 0 bits 2-5: Head count - 1.
 649 \end_layout
 650
 651 \begin_layout LyX-Code
 652 Byte 0 bits 6-7: Reserved, must be 0.
 653 \end_layout
 654
 655 \begin_layout LyX-Code
 656 Byte 1: Bits 0-7 of track count per side - 1.
 657 \end_layout
 658
 659 \begin_layout LyX-Code
 660 Byte 2: Sector count per track - 1.
 661 \end_layout
 662
 663 \begin_layout Subsubsection
 664 Type specific-geometry/size data (CD-ROMs)
 665 \end_layout
 666
 667 \begin_layout Standard
 668 CD-ROMs have 4-byte big-endian sector (512 bytes!) count.
 669 \end_layout
 670
 671 \begin_layout Subsubsection
 672 Type specific-geometry/size data (BIOS images)
 673 \end_layout
 674
 675 \begin_layout Standard
 676 BIOS images have 4-byte big-endian byte (not sector or block) count.
 677 \end_layout
 678
 679 \begin_layout Subsubsection
 680 Actual image data (floppy/HDD)
 681 \end_layout
 682
 683 \begin_layout Standard
 684 Floppy or HDD imagedata consists of following subparts:
 685 \end_layout
 686
 687 \begin_layout Itemize
 688 Storage method
 689 \end_layout
 690
 691 \begin_layout Itemize
 692 Sectors present
 693 \end_layout
 694
 695 \begin_layout Itemize
 696 Image data header
 697 \end_layout
 698
 699 \begin_layout Itemize
 700 Image data
 701 \end_layout
 702
 703 \begin_layout Standard
 704 Storage method is single byte.
 705  Sectors present gives number of last nonzero sector + 1 (zero if image
 706  is all zeroes)
 707 \end_layout
 708
 709 \begin_layout Subsubsection
 710 Floppy/HDD storage method 0: Raw storage
 711 \end_layout
 712
 713 \begin_layout Standard
 714 This storage method has empty header.
 715  Image data is raw dump of first sectors present sectors.
 716 \end_layout
 717
 718 \begin_layout Subsubsection
 719 Floppy/HDD storage method 1: Sectormap
 720 \end_layout
 721
 722 \begin_layout Standard
 723 Image data header contains bitfield with just enough bytes to have one bit
 724  per present sector.
 725  The order of bits is such that number of bit corresponding to each sector
 726  in byte is sector number modulo 8 and byte number is floor of sector number
 727  divided by 8 when sector numbers are counted from zero.
 728  If bit corresponding to sector is set, then the sector is present in image
 729  data, otherwise it is absent and assumed to be all-zeroes.
 730 \end_layout
 731
 732 \begin_layout Standard
 733 Image data contains dumps of all present sectors in order of increasing
 734  sector number.
 735 \end_layout
 736
 737 \begin_layout Subsubsection
 738 Floppy/HDD storage method 2: Extent first sector zero
 739 \end_layout
 740
 741 \begin_layout Standard
 742 Image data is empty as storage-specific data is mangled with image data.
 743  The image data alternates between blocks encoding zero sectors and blocks
 744  encoding nonzero sectors.
 745  The first block encodes zero sectors.
 746
 747 \end_layout
 748
 749 \begin_layout Standard
 750 Block encoding zero sectors consist of single 1-4 byte little-endian value
 751  encoding number of sectors in block - 1.
 752  Number of bytes is determined by sectors present value.
 753  It is 1 for 1-256 sectors, 2 for 257-65536, 3 for 65537-16777216 and 4
 754  for more than 16777216.
 755  All sectors in block are filled with zeroes and are not stored.
 756 \end_layout
 757
 758 \begin_layout Standard
 759 Block encoding nonzero sectors has same block count as zero sector block
 760  but is followed by the sectors stored raw.
 761 \end_layout
 762
 763 \begin_layout Subsubsection
 764 Floppy/HDD storage method 3: Extent first sector nonzero
 765 \end_layout
 766
 767 \begin_layout Standard
 768 Same as storage method 2 but first block is nonzero sector block.
 769 \end_layout
 770
 771 \begin_layout Subsubsection
 772 Actual image data (CD-ROMs and BIOS images)
 773 \end_layout
 774
 775 \begin_layout Standard
 776 These store image data raw.
 777  The amount of data is specified by sector/byte count.
 778 \end_layout
 779
 780 \begin_layout Section
 781 Utilities
 782 \end_layout
 783
 784 \begin_layout Subsection
 785 org.jpc.utils.RAWToPNG
 786 \end_layout
 787
 788 \begin_layout Standard
 789 Invoked as:
 790 \end_layout
 791
 792 \begin_layout LyX-Code
 793 $ java org.jpc.utils.RAWToPNG <input> <outputprefix>
 794 \end_layout
 795
 796 \begin_layout Standard
 797 Reads RAW video data from <input> (may be named pipe) and dumps PNG frames
 798  received as '<outputprefix><runningcount>.png'.
 799  Also saves '<outputprefix>.timing' which contains frame timing data (each
 800  line consists of time in nanoseconds, space, and filename).
 801 \end_layout
 802
 803 \begin_layout Section
 804 The actual emulator
 805 \end_layout
 806
 807 \begin_layout Standard
 808 The actual emulator is invoked as:
 809 \end_layout
 810
 811 \begin_layout LyX-Code
 812 $ java JPCApplication <options>...
 813 \end_layout
 814
 815 \begin_layout Standard
 816 The valid options are:
 817 \end_layout
 818
 819 \begin_layout LyX-Code
 820 -library <library> Use the specified directory when searching for images
 821  (can only be specified once).
 822 \end_layout
 823
 824 \begin_layout LyX-Code
 825 -autoexec <script> Execute contents of specified file as commands when starting
 826  up.
 827 \end_layout
 828
 829 \begin_layout Subsection
 830 Command line
 831 \end_layout
 832
 833 \begin_layout Standard
 834 When emulator is started, command line comes up.
 835  Following commands are known:
 836 \end_layout
 837
 838 \begin_layout Itemize
 839 'exit': exit immediately
 840 \end_layout
 841
 842 \begin_layout Itemize
 843 'load <plugin>': Load plugin (no arguments)
 844 \end_layout
 845
 846 \begin_layout Itemize
 847 'load <plugin>(<arguments>)': load plugin with arguments.
 848 \end_layout
 849
 850 \begin_layout Itemize
 851 'command <command> [<arguments>...]': Invoke command via external command interface.
 852 \end_layout
 853
 854 \begin_layout Standard
 855 When one gets command line, its useful to load some plugins.
 856  See section about plugins.
 857  Note: Load runner plugin (PCControl/PCRunner and so) last, as some runners
 858  like to start PC immediately.
 859 \end_layout
 860
 861 \begin_layout Subsection
 862 PC settings dialog notes
 863 \end_layout
 864
 865 \begin_layout Itemize
 866 CPU divider base frequency before division is 1GHz.
 867 \end_layout
 868
 869 \begin_layout Itemize
 870 Images can be specified by name or by ID.
 871  Name is relative to library directory.
 872  If the image is in subdirectory of image directory, the directory separator
 873  is is '/' regardless of what the host OS uses.
 874 \end_layout
 875
 876 \begin_layout Itemize
 877 CD-ROM and hdc are mutually exclusive
 878 \end_layout
 879
 880 \begin_layout Itemize
 881 Modules is comma-seperated list of modules to load.
 882  To pass arguments to some modules, enclose the arguments in ().
 883  Same module can be specified twice only if parameters differ.
 884 \end_layout
 885
 886 \begin_layout Itemize
 887 FPU emulator is specified by class name.
 888  If core has built-in FPU emulator, then this should be left blank.
 889  Without core-builtin FPU emulator, blank value means
 890 \begin_inset Quotes eld
 891 \end_inset
 892
 893 no fpu
 894 \begin_inset Quotes erd
 895 \end_inset
 896
 897 .
 898 \end_layout
 899
 900 \begin_layout Itemize
 901 Setting boot device doesn't work with some BIOS versions.
 902  Those versions prompt the boot device anyway.
 903 \end_layout
 904
 905 \begin_layout Subsection
 906 Audio output channels
 907 \end_layout
 908
 909 \begin_layout Standard
 910 PC can have one or more audio output channels.
 911  The name of audio output associated with PC speaker is: 'org.jpc.emulator.peripher
 912 al.PCSpeaker-0'.
 913  Modules that have audio outputs get channel names of form <classname>-<sequenti
 914 al>, where <classname> is name of main module class and sequential is number
 915  starting from zero.
 916  Note that same module can have multiple output channels.
 917  If multiple modules of same class request audio outputs, the <sequential>
 918  values of subsequent module start where previous left off.
 919 \end_layout
 920
 921 \begin_layout Subsection
 922 Plugins
 923 \end_layout
 924
 925 \begin_layout Standard
 926 Plugins actually execute the tasks of the emulator.
 927  They can be loaded using
 928 \begin_inset Quotes eld
 929 \end_inset
 930
 931 load <plugin>
 932 \begin_inset Quotes erd
 933 \end_inset
 934
 935  or 'load <plugin>(<arguments>)
 936 \begin_inset Quotes erd
 937 \end_inset
 938
 939  from command line.
 940 \end_layout
 941
 942 \begin_layout Standard
 943 Different Plugins using the same output (like running PCMonitor and PNGDumper)
 944  should not conflict because connector output hold locking is desinged to
 945  handle multiple readers.
 946 \end_layout
 947
 948 \begin_layout Standard
 949 If no plugin used requires GUI, then the emulator can be run without having
 950  GUI available.
 951 \end_layout
 952
 953 \begin_layout Subsubsection
 954 plugin: org.jpc.plugins.PCControl
 955 \end_layout
 956
 957 \begin_layout Standard
 958 No arguments, requires and uses GUI.
 959 \end_layout
 960
 961 \begin_layout Standard
 962 Runs the PC emulator core.
 963  Has capability to start/stop emulation, breakpoint after certain time or
 964  start/end of VGA vertical retrace.
 965  Also can create, savestate and loadstate PC emulation.
 966  Memory dumping is supported.
 967
 968 \end_layout
 969
 970 \begin_layout Subsubsection
 971 plugin: org.jpc.plugins.PCRunner
 972 \end_layout
 973
 974 \begin_layout Standard
 975 Takes 'movie=<file>' as argument and optionally 'stoptime=<time>' Does not
 976  require nor use GUI.
 977 \end_layout
 978
 979 \begin_layout Standard
 980 Loads PC from savestate and just runs it.
 981  CTRL+C to quit.
 982  Also automatically quits once stoptime is reached.
 983 \end_layout
 984
 985 \begin_layout Subsubsection
 986 plugin: org.jpc.plugins.PCMonitor
 987 \end_layout
 988
 989 \begin_layout Standard
 990 No arguments, requires and uses GUI.
 991 \end_layout
 992
 993 \begin_layout Standard
 994 VGA monitor for emulated PC.
 995 \end_layout
 996
 997 \begin_layout Subsubsection
 998 plugin: org.jpc.plugins.VirtualKeyboard
 999 \end_layout
1000
1001 \begin_layout Standard
1002 No arguments, requires and uses GUI.
1003 \end_layout
1004
1005 \begin_layout Standard
1006 On-screen keyboard for emulated PC.
1007 \end_layout
1008
1009 \begin_layout Subsubsection
1010 plugin: org.jpc.plugins.PCStartStopTest
1011 \end_layout
1012
1013 \begin_layout Standard
1014 No arguments, requires and uses GUI.
1015 \end_layout
1016
1017 \begin_layout Standard
1018 Small plugin testing remote PC start/stop.
1019  Also supports sending some common keypresses.
1020 \end_layout
1021
1022 \begin_layout Subsubsection
1023 plugin: org.jpc.plugins.RAWVideoDumper
1024 \end_layout
1025
1026 \begin_layout Standard
1027 Takes 'rawoutput=<file>' as argument.
1028  Does not require nor use GUI.
1029 \end_layout
1030
1031 \begin_layout Standard
1032 Dumps all generated frames to RAW file <file>.
1033  Rawoutput is required.
1034  The raw file consists of concatenation of zlib streams.
1035  The uncompressed stream is concatenation of time skips (FFh FFh FFh FFh),
1036  each acting as time offset of 2^32-1 nanoseconds and saved frames.
1037  The saved frame has time offset in nanoseconds (big endian) as first four
1038  bytes (must be at most 2^32-2, as 2^32-1 is reserved for time skip).
1039  The next two bytes are big-endian width, next two big-endian height.
1040  Finally frame has 4 * width * height bytes of data that encodes pixels
1041  using 4 bytes per pixel, in left-to-right, up-to-down order.
1042  Byte 0 of each pixel is reserved, byte 1 is the red channel, byte 2 is
1043  green channel and byte 3 is blue channel.
1044 \end_layout
1045
1046 \begin_layout Standard
1047 Dumping to pipe is supported.
1048 \end_layout
1049
1050 \begin_layout Subsubsection
1051 plugin: org.jpc.plugins.RAWAudioDumper
1052 \end_layout
1053
1054 \begin_layout Standard
1055 Takes 'src=<name of audio output channel>', 'file=<output-filename>' and
1056  'offset=<offset>' as arguments, separated by ','.
1057  Does not require nor use GUI.
1058 \end_layout
1059
1060 \begin_layout Standard
1061 Dumps output from specified audio output channel (src, mandatory) to RAW-format
1062  file (file, mandatory).
1063  The resulting file consists of records, 4 or 8 bytes each.
1064  4 byte record consists of 0xFF 0xFF 0xFF 0xFF and means to increase next
1065  time delta by
1066 \begin_inset Formula $2^{32}-1$
1067 \end_inset
1068
1069 ns.
1070  Otherwise record is 8 bytes.
1071  Each 8 byte record has three fields.
1072  First 4 byte unsinged big endian timedelta value (in nanoseconds, must
1073  be smaller than
1074 \begin_inset Formula $2^{32}-1$
1075 \end_inset
1076
1077 ), then 2 byte signed big endian new left channel volume, then 2 byte signed
1078  big endian new right channel volume.
1079  Optionally 'offset' can be set to positive value (in nanoseconds) to delay
1080  the audio by.
1081 \end_layout
1082
1083 \begin_layout Subsubsection
1084 plugin: org.jpc.plugins.LuaPlugin
1085 \end_layout
1086
1087 \begin_layout Standard
1088 Takes 'kernel=<name of lua kernel file>', other parameters are passed to
1089  kernel, requires and uses GUI.
1090 \end_layout
1091
1092 \begin_layout Standard
1093 Lua VM for executing scripts.
1094 \end_layout
1095
1096 \begin_layout Section
1097 Modules
1098 \end_layout
1099
1100 \begin_layout Subsection
1101 org.jpc.modules.Joystick:
1102 \end_layout
1103
1104 \begin_layout Itemize
1105 Arguments: none.
1106 \end_layout
1107
1108 \begin_layout Itemize
1109 Resources: I/O port 0x201
1110 \end_layout
1111
1112 \begin_layout Standard
1113 Emulates joystick game port.
1114 \end_layout
1115
1116 \begin_layout Subsection
1117 org.jpc.modules.BasicFPU:
1118 \end_layout
1119
1120 \begin_layout Itemize
1121 Arguments: none.
1122 \end_layout
1123
1124 \begin_layout Itemize
1125 Resources: None.
1126 \end_layout
1127
1128 \begin_layout Standard
1129 Crude FPU (x87) emulator.
1130 \end_layout
1131
1132 \begin_layout Section
1133 Hacks
1134 \end_layout
1135
1136 \begin_layout Standard
1137 Hacks are saved to savestates but not movies.
1138 \end_layout
1139
1140 \begin_layout Subsection
1141 NO_FPU
1142 \end_layout
1143
1144 \begin_layout Standard
1145 Force bit 1 of physical address 0x0410 to zero, signaling that the system
1146  has no FPU.
1147  BIOS assumes system has FPU but some games use that bit to detect FPU,
1148  trying to use it if it is
1149 \begin_inset Quotes eld
1150 \end_inset
1151
1152 present
1153 \begin_inset Quotes erd
1154 \end_inset
1155
1156 .
1157  Try this if game startup hangs with lots of trying to use FPU but not present
1158  errors.
1159  Don't use if there is FPU present.
1160  Needed to get games like Blake Stone to work (FPU emulator allows it to
1161  start but causes graphical glitches).
1162 \end_layout
1163
1164 \begin_layout Subsection
1165 VGA_DRAW
1166 \end_layout
1167
1168 \begin_layout Standard
1169 Update basic VGA parameters before vretrace, not after it.
1170  Some games (e.g.
1171  Commander Keen 4) don't like if this isn't done and some games (e.g.
1172  Mario & Luigi) don't like if it is done.
1173  Wrong value manifests as jerky scrolling (scrolling back and forth and
1174  fixed statusbars move).
1175 \end_layout
1176
1177 \begin_layout Section
1178 Some error messages and explanations
1179 \end_layout
1180
1181 \begin_layout Itemize
1182 <filename> is Not a valid image file
1183 \end_layout
1184
1185 \begin_layout Itemize
1186 <filename> is not image file
1187 \end_layout
1188
1189 \begin_layout Itemize
1190 <filename> claims to be floppy with illegal geometry: <x> tracks, <y> sides
1191  and <z> sectors.
1192 \end_layout
1193
1194 \begin_layout Itemize
1195 <filename> claims to be HDD with illegal geometry: <x> tracks, <y> sides
1196  and <z> sectors.
1197 \end_layout
1198
1199 \begin_layout Itemize
1200 Can't read disk image sector map.
1201 \end_layout
1202
1203 \begin_layout Itemize
1204 Can't read disk image extent.
1205 \end_layout
1206
1207 \begin_layout Standard
1208 Code expects <filename> to be valid JPC-RR format image, but it isn't JPC-RR
1209  image at all or its corrupt.
1210 \end_layout
1211
1212 \begin_layout Itemize
1213 <filename> is image of unknown type.
1214 \end_layout
1215
1216 \begin_layout Itemize
1217 <filename> has unrecognized geometry <x> <y> <z>
1218 \end_layout
1219
1220 \begin_layout Standard
1221 Possibly corrupt image, not JPC-RR image, or JPC-RR image from future version
1222  containing something current version can't comprehend.
1223 \end_layout
1224
1225 \begin_layout Itemize
1226 Invalid format specifier <something>.
1227 \end_layout
1228
1229 \begin_layout Itemize
1230 Invalid syntax of --floppy= or --HDD= option.
1231 \end_layout
1232
1233 \begin_layout Itemize
1234 Invalid format specifier/option <something>.
1235 \end_layout
1236
1237 \begin_layout Standard
1238 Invalid option or format specifier was given.
1239  Check for typos.
1240 \end_layout
1241
1242 \begin_layout Itemize
1243 java ImageMaker [<options>...] <format> <destination> <source> <diskname>
1244 \end_layout
1245
1246 \begin_layout Standard
1247 Check syntax of command.
1248  Especially that diskname is present!
1249 \end_layout
1250
1251 \begin_layout Itemize
1252 The image has <nnn> sectors while it should have <yyy> according to selected
1253  geometry.
1254 \end_layout
1255
1256 \begin_layout Itemize
1257 Raw image file length not divisible by 512.
1258 \end_layout
1259
1260 \begin_layout Itemize
1261 Trying to read sector out of range.
1262 \end_layout
1263
1264 \begin_layout Standard
1265 The selected geometry is wrong or raw image is incomplete.
1266 \end_layout
1267
1268 \begin_layout Itemize
1269 Invalid disk name (Should not happen!).
1270 \end_layout
1271
1272 \begin_layout Itemize
1273 Invalid geometry to be written.
1274 \end_layout
1275
1276 \begin_layout Standard
1277 This is a very likely a bug in program.
1278 \end_layout
1279
1280 \begin_layout Itemize
1281 What the heck <filename> is? It's not regular file nor directory.
1282 \end_layout
1283
1284 \begin_layout Standard
1285 That sort of file can't be used as input for image making, or the file just
1286  doesn't exist.
1287 \end_layout
1288
1289 \begin_layout Itemize
1290 BIOS images can only be made out of regular files.
1291 \end_layout
1292
1293 \begin_layout Itemize
1294 CD images can only be made out of regular files.
1295 \end_layout
1296
1297 \begin_layout Standard
1298 Source image specified is not regular file, but image of that type can't
1299  be made of anything else.
1300 \end_layout
1301
1302 \begin_layout Itemize
1303 Can't read raw bios image file.
1304 \end_layout
1305
1306 \begin_layout Itemize
1307 Can't read sector <nnn> from image.
1308 \end_layout
1309
1310 \begin_layout Standard
1311 Reading the raw image file failed for some reason.
1312 \end_layout
1313
1314 \begin_layout Itemize
1315 Bad library line: "<something>".
1316  Ignored.
1317 \end_layout
1318
1319 \begin_layout Standard
1320 Syntax error in image library.
1321 \end_layout
1322
1323 \begin_layout Itemize
1324 Removing image <something> a.k.a.
1325  "<something>" as it no longer exists.
1326 \end_layout
1327
1328 \begin_layout Standard
1329 The image file no longer exists so it gets removed from library.
1330 \end_layout
1331
1332 \begin_layout Itemize
1333 Removing image <something> a.k.a.
1334  "<something>" due to <some> conflict.
1335 \end_layout
1336
1337 \begin_layout Standard
1338 Image library code killed some image from library due to some kind of conflict
1339  with image being added.
1340 \end_layout
1341
1342 \begin_layout Itemize
1343 Too much data to fit into given space.
1344 \end_layout
1345
1346 \begin_layout Standard
1347 The tree you gave contains takes just too much space to fit into disk of
1348  this size.
1349 \end_layout
1350
1351 \begin_layout Section
1352 Advanced: Savestate/movie format
1353 \end_layout
1354
1355 \begin_layout Subsection
1356 Special character classes
1357 \end_layout
1358
1359 \begin_layout Subsubsection
1360 SPACE
1361 \end_layout
1362
1363 \begin_layout Standard
1364 Following Unicode codepoints (encoded as UTF-8) are interpretted as space
1365  characters:
1366 \end_layout
1367
1368 \begin_layout Itemize
1369 Codepoints 0x20, and 0x09.
1370 \end_layout
1371
1372 \begin_layout Itemize
1373 Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
1374 \end_layout
1375
1376 \begin_layout Itemize
1377 Codepoints 0x2000-0x200A.
1378 \end_layout
1379
1380 \begin_layout Subsubsection
1381 LINEFEED
1382 \end_layout
1383
1384 \begin_layout Standard
1385 Following byte sequences are interpretted as linefeeds (line change):
1386 \end_layout
1387
1388 \begin_layout Itemize
1389 Byte 0x0A
1390 \end_layout
1391
1392 \begin_layout Itemize
1393 Byte 0x0D
1394 \end_layout
1395
1396 \begin_layout Itemize
1397 Bytes 0x0D 0x0A (interpretted as single line change, not two!)
1398 \end_layout
1399
1400 \begin_layout Itemize
1401 Bytes 0xC2 0x85 (UTF-8 for unicode control character NL)
1402 \end_layout
1403
1404 \begin_layout Subsection
1405 JRSR archive
1406 \end_layout
1407
1408 \begin_layout Standard
1409 JRSR archive format packs multiple text archive members to text archive.
1410  It does not support binary members.
1411  JRSR archives have first five or six bytes form the magic.
1412  It is
1413 \begin_inset Quotes eld
1414 \end_inset
1415
1416 JRSR
1417 \begin_inset Quotes erd
1418 \end_inset
1419
1420  followed by LINEFEED character There are four kinds of lines after that
1421  (lines are terminated by LINEFEED byte/bytes):
1422 \end_layout
1423
1424 \begin_layout Itemize
1425 Start member
1426 \end_layout
1427
1428 \begin_layout Itemize
1429 Member line
1430 \end_layout
1431
1432 \begin_layout Itemize
1433 End member
1434 \end_layout
1435
1436 \begin_layout Itemize
1437 Blank line
1438 \end_layout
1439
1440 \begin_layout Standard
1441 Sequencing rules are as follows: Start member is allowed anywhere (after
1442  magic).
1443  Member line is allowed only inside member (member started but not ended).
1444  End member is only allowed inside member.
1445  End of file is only allowed outside member.
1446  Blank line is allowed anywhere after magic.
1447 \end_layout
1448
1449 \begin_layout Subsubsection
1450 Start member
1451 \end_layout
1452
1453 \begin_layout Standard
1454 Start member line is given as
1455 \begin_inset Quotes eld
1456 \end_inset
1457
1458 !BEGIN
1459 \begin_inset Quotes erd
1460 \end_inset
1461
1462  <SPACE>+ <membername> <LINEFEED>.
1463  <SPACE>+ any number of SPACE characters at least one and <LINEFEED> is
1464  LINEFEED chacter.
1465  The member name is UTF-8 encoded and maximum allowed line length is 2048
1466  bytes (including LINEFEED, which means name is limited to 509-2040 codepoints
1467  depending on characters used).
1468  Starting member inside another implicitly ends the previous member.
1469 \end_layout
1470
1471 \begin_layout Subsubsection
1472 Member line:
1473 \end_layout
1474
1475 \begin_layout Standard
1476 Member line is given as
1477 \begin_inset Quotes eld
1478 \end_inset
1479
1480 +
1481 \begin_inset Quotes erd
1482 \end_inset
1483
1484 <content><LINEFEED>.
1485  It gives another line for member contents.
1486  <content> is passed raw to layers above (followed by line termination)
1487 \end_layout
1488
1489 \begin_layout Subsubsection
1490 End member
1491 \end_layout
1492
1493 \begin_layout Standard
1494 End member line is given as
1495 \begin_inset Quotes eld
1496 \end_inset
1497
1498 !END
1499 \begin_inset Quotes erd
1500 \end_inset
1501
1502 <LINEFEED>.
1503  It ends the current member.
1504  The following line can only be start member line or file may end.
1505 \end_layout
1506
1507 \begin_layout Subsubsection
1508 Blank line
1509 \end_layout
1510
1511 \begin_layout Standard
1512 Blank line is given as <LINEFEED>.
1513  Lines like that are ignored.
1514 \end_layout
1515
1516 \begin_layout Subsection
1517 Four-to-Five encoding
1518 \end_layout
1519
1520 \begin_layout Standard
1521 Binary members are encoded into text by so-called four-to-five encoding.
1522  This encoding can encode single byte to two, two bytes to three, three
1523  bytes to four and four bytes to five.
1524  Four-to-five encoding has five kinds of blocks.
1525  All SPACE and LINEFEED characters are completely ignored, even in middle
1526  of blocks.
1527 \end_layout
1528
1529 \begin_layout Subsubsection
1530 End stream block
1531 \end_layout
1532
1533 \begin_layout Standard
1534 End stream block is encoded as '!'.
1535  It ends the stream instantly.
1536  There is also implicit end of stream at end of input to decoding.
1537 \end_layout
1538
1539 \begin_layout Subsubsection
1540 Other four block types
1541 \end_layout
1542
1543 \begin_layout Standard
1544 Other four block types take the value to be encoded, read it as big-endian
1545  value.
1546  Then they write it as base-93 big-endian value.
1547  Then length specific constants are added to digits of that number to yield
1548  ASCII values for characters (those are stored in order):
1549 \end_layout
1550
1551 \begin_layout Standard
1552 \begin_inset Tabular
1553 <lyxtabular version="3" rows="5" columns="6">
1554 <features>
1555 <column alignment="center" valignment="top" width="0">
1556 <column alignment="center" valignment="top" width="0">
1557 <column alignment="center" valignment="top" width="0">
1558 <column alignment="center" valignment="top" width="0">
1559 <column alignment="center" valignment="top" width="0">
1560 <column alignment="center" valignment="top" width="0">
1561 <row>
1562 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1563 \begin_inset Text
1564
1565 \begin_layout Plain Layout
1566 To encode
1567 \end_layout
1568
1569 \end_inset
1570 </cell>
1571 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1572 \begin_inset Text
1573
1574 \begin_layout Plain Layout
1575 1st char.
1576 \end_layout
1577
1578 \end_inset
1579 </cell>
1580 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1581 \begin_inset Text
1582
1583 \begin_layout Plain Layout
1584 2nd char.
1585 \end_layout
1586
1587 \end_inset
1588 </cell>
1589 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1590 \begin_inset Text
1591
1592 \begin_layout Plain Layout
1593 3rd char.
1594 \end_layout
1595
1596 \end_inset
1597 </cell>
1598 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1599 \begin_inset Text
1600
1601 \begin_layout Plain Layout
1602 4th char.
1603 \end_layout
1604
1605 \end_inset
1606 </cell>
1607 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1608 \begin_inset Text
1609
1610 \begin_layout Plain Layout
1611 5th char.
1612 \end_layout
1613
1614 \end_inset
1615 </cell>
1616 </row>
1617 <row>
1618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1619 \begin_inset Text
1620
1621 \begin_layout Plain Layout
1622 1 byte
1623 \end_layout
1624
1625 \end_inset
1626 </cell>
1627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1628 \begin_inset Text
1629
1630 \begin_layout Plain Layout
1631 34
1632 \end_layout
1633
1634 \end_inset
1635 </cell>
1636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1637 \begin_inset Text
1638
1639 \begin_layout Plain Layout
1640 34
1641 \end_layout
1642
1643 \end_inset
1644 </cell>
1645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1646 \begin_inset Text
1647
1648 \begin_layout Plain Layout
1649 -
1650 \end_layout
1651
1652 \end_inset
1653 </cell>
1654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1655 \begin_inset Text
1656
1657 \begin_layout Plain Layout
1658 -
1659 \end_layout
1660
1661 \end_inset
1662 </cell>
1663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1664 \begin_inset Text
1665
1666 \begin_layout Plain Layout
1667 -
1668 \end_layout
1669
1670 \end_inset
1671 </cell>
1672 </row>
1673 <row>
1674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1675 \begin_inset Text
1676
1677 \begin_layout Plain Layout
1678 2 bytes
1679 \end_layout
1680
1681 \end_inset
1682 </cell>
1683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1684 \begin_inset Text
1685
1686 \begin_layout Plain Layout
1687 37
1688 \end_layout
1689
1690 \end_inset
1691 </cell>
1692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1693 \begin_inset Text
1694
1695 \begin_layout Plain Layout
1696 34
1697 \end_layout
1698
1699 \end_inset
1700 </cell>
1701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1702 \begin_inset Text
1703
1704 \begin_layout Plain Layout
1705 34
1706 \end_layout
1707
1708 \end_inset
1709 </cell>
1710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1711 \begin_inset Text
1712
1713 \begin_layout Plain Layout
1714 -
1715 \end_layout
1716
1717 \end_inset
1718 </cell>
1719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1720 \begin_inset Text
1721
1722 \begin_layout Plain Layout
1723 -
1724 \end_layout
1725
1726 \end_inset
1727 </cell>
1728 </row>
1729 <row>
1730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1731 \begin_inset Text
1732
1733 \begin_layout Plain Layout
1734 3 bytes
1735 \end_layout
1736
1737 \end_inset
1738 </cell>
1739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1740 \begin_inset Text
1741
1742 \begin_layout Plain Layout
1743 45
1744 \end_layout
1745
1746 \end_inset
1747 </cell>
1748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1749 \begin_inset Text
1750
1751 \begin_layout Plain Layout
1752 34
1753 \end_layout
1754
1755 \end_inset
1756 </cell>
1757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1758 \begin_inset Text
1759
1760 \begin_layout Plain Layout
1761 34
1762 \end_layout
1763
1764 \end_inset
1765 </cell>
1766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1767 \begin_inset Text
1768
1769 \begin_layout Plain Layout
1770 34
1771 \end_layout
1772
1773 \end_inset
1774 </cell>
1775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1776 \begin_inset Text
1777
1778 \begin_layout Plain Layout
1779 -
1780 \end_layout
1781
1782 \end_inset
1783 </cell>
1784 </row>
1785 <row>
1786 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1787 \begin_inset Text
1788
1789 \begin_layout Plain Layout
1790 4 bytes
1791 \end_layout
1792
1793 \end_inset
1794 </cell>
1795 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1796 \begin_inset Text
1797
1798 \begin_layout Plain Layout
1799 66
1800 \end_layout
1801
1802 \end_inset
1803 </cell>
1804 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \begin_layout Plain Layout
1808 34
1809 \end_layout
1810
1811 \end_inset
1812 </cell>
1813 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1814 \begin_inset Text
1815
1816 \begin_layout Plain Layout
1817 34
1818 \end_layout
1819
1820 \end_inset
1821 </cell>
1822 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
1823 \begin_inset Text
1824
1825 \begin_layout Plain Layout
1826 34
1827 \end_layout
1828
1829 \end_inset
1830 </cell>
1831 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
1832 \begin_inset Text
1833
1834 \begin_layout Plain Layout
1835 34
1836 \end_layout
1837
1838 \end_inset
1839 </cell>
1840 </row>
1841 </lyxtabular>
1842
1843 \end_inset
1844
1845
1846 \end_layout
1847
1848 \begin_layout Standard
1849 Blocks which encode values greater than what is possible for value of that
1850  length are fatal errors.
1851
1852 \end_layout
1853
1854 \begin_layout Subsection
1855 Line component encoing
1856 \end_layout
1857
1858 \begin_layout Standard
1859 Line component encoding sits on top of UTF-8 encoding.
1860  Line component encoding encodes non-empty 1-D array of non-empty strings
1861  into line, and thus array of those into member.
1862  Empty lines or lines that don't contain any components are ignored.
1863  Line starts with depth value of 0 and must end with depth value of zero.
1864 \end_layout
1865
1866 \begin_layout Standard
1867 Components are seperated by component separators.
1868  Empty components are ignored.
1869  Following codepoints are separators on depth 0 if not escaped:
1870 \end_layout
1871
1872 \begin_layout Itemize
1873 Codepoint of '('.
1874  The depth is read pre-increment.
1875 \end_layout
1876
1877 \begin_layout Itemize
1878 Codepoint of ')'.
1879  The depth is read post-decrement.
1880 \end_layout
1881
1882 \begin_layout Itemize
1883 Any SPACE character
1884 \end_layout
1885
1886 \begin_layout Standard
1887 The following characters are special:
1888 \end_layout
1889
1890 \begin_layout Itemize
1891 '('.
1892  Increments depth by 1 if not escaped (and appears in component).
1893 \end_layout
1894
1895 \begin_layout Itemize
1896 ')'.
1897  Decrements depth by 1 if not escaped (and appears in component).
1898  Depth going negative is an error.
1899 \end_layout
1900
1901 \begin_layout Itemize
1902 '
1903 \backslash
1904 '.
1905  Next character is interpretted as literal.
1906  Error if at end of line.
1907 \end_layout
1908
1909 \begin_layout Standard
1910 Otherwise, characters are interpretted as literals and appear in components.
1911  Depth must be zero at end of line.
1912 \end_layout
1913
1914 \begin_layout Subsection
1915 Header section:
1916 \end_layout
1917
1918 \begin_layout Standard
1919 Header section is in archive member "header".
1920  It uses line component encoding.
1921  The first component of each line is name of header, and subsequent ones
1922  are arguments.
1923  How many parameters are expected is dependent on what header it is:
1924 \end_layout
1925
1926 \begin_layout Subsubsection
1927 PROJECTID header:
1928 \end_layout
1929
1930 \begin_layout Itemize
1931 Header name: "PROJECTID"
1932 \end_layout
1933
1934 \begin_layout Itemize
1935 Components: 2
1936 \end_layout
1937
1938 \begin_layout Itemize
1939 Argument #1: <project-id-string>
1940 \end_layout
1941
1942 \begin_layout Itemize
1943 Mandatory: Yes
1944 \end_layout
1945
1946 \begin_layout Standard
1947 Gives project ID.
1948  Project ID is generated when PC is assembled and is then preserved in save
1949  states.
1950  It is used for computing rerecord counts.
1951  Emulator treats it as opaque string, the IDs it generates are formed by
1952  48 random hexadecimal digits.
1953 \end_layout
1954
1955 \begin_layout Subsubsection
1956 SAVESTATEID header:
1957 \end_layout
1958
1959 \begin_layout Itemize
1960 Header name: "SAVESTATEID"
1961 \end_layout
1962
1963 \begin_layout Itemize
1964 Components: 2
1965 \end_layout
1966
1967 \begin_layout Itemize
1968 Argument #1: <savestate-id-string>
1969 \end_layout
1970
1971 \begin_layout Itemize
1972 Mandatory: No
1973 \end_layout
1974
1975 \begin_layout Standard
1976 Gives save state ID.
1977  Each save state has its own save state ID.
1978  Treated as opaque string, but generated as 48 random hexadecimal digits.
1979  The presence of this header signals whether there is save state to be loaded.
1980  If this header is present, save state load will be attempted.
1981  If absent, save state is not to be loaded even if present (and correct
1982  savestate load would be technically impossible anyway).
1983 \end_layout
1984
1985 \begin_layout Standard
1986 The value is used to prevent loading incompatible save states in preserve
1987  event stream mode and also to find the point in event stream where one
1988  left off.
1989 \end_layout
1990
1991 \begin_layout Subsubsection
1992 RERECORDS header:
1993 \end_layout
1994
1995 \begin_layout Itemize
1996 Header name: "RERECORDS"
1997 \end_layout
1998
1999 \begin_layout Itemize
2000 Components: 2
2001 \end_layout
2002
2003 \begin_layout Itemize
2004 Argument #1: <rerecords>
2005 \end_layout
2006
2007 \begin_layout Itemize
2008 Mandatory: Yes
2009 \end_layout
2010
2011 \begin_layout Standard
2012 Gives rerecord count.
2013  PC assembly (except when loading save state) initializes current rerecord
2014  count to zero.
2015  Must be non-negative and decimal number using ASCII digit characters.
2016 \end_layout
2017
2018 \begin_layout LyX-Code
2019 On loading save state:
2020 \end_layout
2021
2022 \begin_layout LyX-Code
2023 1) If project ID matches with previous:
2024 \end_layout
2025
2026 \begin_layout LyX-Code
2027 1a) If loaded rerecord count is larger or equal to current rerecord count:
2028 \end_layout
2029
2030 \begin_layout LyX-Code
2031 1a-a) Current rerecord count is loaded rerecord count + 1.
2032 \end_layout
2033
2034 \begin_layout LyX-Code
2035 1b) Otherwise
2036 \end_layout
2037
2038 \begin_layout LyX-Code
2039 1b-a) Current rerecord count increments by 1.
2040 \end_layout
2041
2042 \begin_layout LyX-Code
2043 2) Otherwise
2044 \end_layout
2045
2046 \begin_layout LyX-Code
2047 2a) Current rerecord count is loaded rerecord count + 1.
2048 \end_layout
2049
2050 \begin_layout Standard
2051 The current rerecord count at time of save is saved to save state.
2052 \end_layout
2053
2054 \begin_layout Subsubsection
2055 AUTHORS header:
2056 \end_layout
2057
2058 \begin_layout Itemize
2059 Header name: "AUTHORS"
2060 \end_layout
2061
2062 \begin_layout Itemize
2063 Components: 2 or more
2064 \end_layout
2065
2066 \begin_layout Itemize
2067 Arguments: free form
2068 \end_layout
2069
2070 \begin_layout Itemize
2071 Mandatory: No
2072 \end_layout
2073
2074 \begin_layout Standard
2075 Gives authors of run.
2076  Each argument gives one author.
2077  May be present multiple times.
2078 \end_layout
2079
2080 \begin_layout Subsubsection
2081 COMMENT header:
2082 \end_layout
2083
2084 \begin_layout Itemize
2085 Header name: "COMMENT"
2086 \end_layout
2087
2088 \begin_layout Itemize
2089 Components: 2 or more
2090 \end_layout
2091
2092 \begin_layout Itemize
2093 Arguments: free form
2094 \end_layout
2095
2096 \begin_layout Itemize
2097 Mandatory: No
2098 \end_layout
2099
2100 \begin_layout Standard
2101 Various kinds of free form data.
2102  Not parsed further by emulator.
2103 \end_layout
2104
2105 \begin_layout Subsection
2106 Initialization segment:
2107 \end_layout
2108
2109 \begin_layout Standard
2110 If SAVESTATEID header isn't present (not a save state), member "initialization"
2111  gives PC initialization parameters for assembling the PC.
2112  It is present anyway even if SAVESTATEID is present (savestate).
2113 \end_layout
2114
2115 \begin_layout Standard
2116 Following parameters are used (space separates components):
2117 \end_layout
2118
2119 \begin_layout LyX-Code
2120 "BIOS" <id>
2121 \end_layout
2122
2123 \begin_layout Standard
2124 Gives Image ID of main system BIOS (mandatory)
2125 \end_layout
2126
2127 \begin_layout LyX-Code
2128 "VGABIOS" <id>
2129 \end_layout
2130
2131 \begin_layout Standard
2132 Gives Image ID of VGA BIOS (mandatory).
2133 \end_layout
2134
2135 \begin_layout LyX-Code
2136 "HDA" <id>
2137 \end_layout
2138
2139 \begin_layout Standard
2140 Gives Image ID of hda.
2141  Present only if system has hard disk hda.
2142 \end_layout
2143
2144 \begin_layout LyX-Code
2145 "HDB" <id>
2146 \end_layout
2147
2148 \begin_layout Standard
2149 Gives Image ID of hdb.
2150  Present only if system has hard disk hdb.
2151 \end_layout
2152
2153 \begin_layout LyX-Code
2154 "HDC" <id>
2155 \end_layout
2156
2157 \begin_layout Standard
2158 Gives Image ID of hdc.
2159  Present only if system has hard disk hdc.
2160 \end_layout
2161
2162 \begin_layout LyX-Code
2163 "HDD" <id>
2164 \end_layout
2165
2166 \begin_layout Standard
2167 Gives Image ID of hdd.
2168  Present only if system has hard disk hdd.
2169 \end_layout
2170
2171 \begin_layout LyX-Code
2172 "DISK" <num> <id>
2173 \end_layout
2174
2175 \begin_layout Standard
2176 Gives Image ID of disk in slot <num>.
2177  Slot number must be non-negative.
2178 \end_layout
2179
2180 \begin_layout LyX-Code
2181 \begin_inset Quotes eld
2182 \end_inset
2183
2184 DISKNAME
2185 \begin_inset Quotes erd
2186 \end_inset
2187
2188  <num> <name>
2189 \end_layout
2190
2191 \begin_layout Standard
2192 kGives image name of disk in slot <num>.
2193  Slot number must be non-negative.
2194  The slot must be previously declared using
2195 \begin_inset Quotes eld
2196 \end_inset
2197
2198 DISK
2199 \begin_inset Quotes erd
2200 \end_inset
2201
2202 .
2203 \end_layout
2204
2205 \begin_layout LyX-Code
2206 "FDA" <num>
2207 \end_layout
2208
2209 \begin_layout Standard
2210 Gives Image slot to initially put into floppy drive fda.
2211  Disk must be of floppy type.
2212  If none present, no disk is initially put there.
2213 \end_layout
2214
2215 \begin_layout LyX-Code
2216 "FDB" <num>
2217 \end_layout
2218
2219 \begin_layout Standard
2220 Gives Image slot to initially put into floppy drive fdb.
2221  Disk must be of floppy type.
2222  If none present, no disk is initially put there.
2223 \end_layout
2224
2225 \begin_layout LyX-Code
2226 "CDROM" <num>
2227 \end_layout
2228
2229 \begin_layout Standard
2230 Gives Image slot to initially put into CD-ROM drive hdc.
2231  Not allowed if hard disk hdc is present.
2232  Disk must be of CD-ROM type.
2233  If none present no disk is initially put there.
2234 \end_layout
2235
2236 \begin_layout LyX-Code
2237 "INITIALTIME" <time>
2238 \end_layout
2239
2240 \begin_layout Standard
2241 Number of milliseconds since Unix epoch to system start up time.
2242  Allowed range:
2243 \end_layout
2244
2245 \begin_layout Standard
2246 0-4102444799999.
2247  Mandatory.
2248 \end_layout
2249
2250 \begin_layout LyX-Code
2251 "CPUDIVIDER" <divider>
2252 \end_layout
2253
2254 \begin_layout Standard
2255 Set CPU frequency divider (dividing the 1GHz master clock).
2256  Allowed range is 1-256.
2257  Mandatory.
2258 \end_layout
2259
2260 \begin_layout LyX-Code
2261 "MEMORYSIZE" <pages>
2262 \end_layout
2263
2264 \begin_layout Standard
2265 Number of 4KiB pages of RAM memory.
2266  Allowed range 256-262144.
2267  Mandatory.
2268 \end_layout
2269
2270 \begin_layout LyX-Code
2271 "BOOT" <device>
2272 \end_layout
2273
2274 \begin_layout Standard
2275 Set boot device.
2276  Valid devices are "FLOPPY" (boot from fda), "HDD" (boot from hda) and "CDROM"
2277  (boot from CD).
2278 \end_layout
2279
2280 \begin_layout LyX-Code
2281 "LOADMODULEA" <module> <parameters>
2282 \end_layout
2283
2284 \begin_layout Standard
2285 Load module <module> with parameters <parameters>.
2286 \end_layout
2287
2288 \begin_layout LyX-Code
2289 "LOADMODULE" <module>
2290 \end_layout
2291
2292 \begin_layout Standard
2293 Load module <module> with no parameters
2294 \end_layout
2295
2296 \begin_layout LyX-Code
2297 \begin_inset Quotes eld
2298 \end_inset
2299
2300 FPU
2301 \begin_inset Quotes erd
2302 \end_inset
2303
2304  <fpu>
2305 \end_layout
2306
2307 \begin_layout Standard
2308 Use class <fpu> as FPU emulator.
2309 \end_layout
2310
2311 \begin_layout Subsection
2312 Event record format:
2313 \end_layout
2314
2315 \begin_layout Standard
2316 Event record is in archive member "events".
2317  It uses line component encoding.
2318  Each line gives an event.
2319  First component of each line gives time stamp.
2320  These timestamps MUST be in increasing order and all MUST be non-negative.
2321  Time stamp time unit is exactly 1 nanosecond of emulated time.
2322 \end_layout
2323
2324 \begin_layout Standard
2325 The second component of each line is name of class to dispatch to.
2326  Further components are passed as-is to event handlers.
2327
2328 \end_layout
2329
2330 \begin_layout Subsubsection
2331 Savestate event
2332 \end_layout
2333
2334 \begin_layout Itemize
2335 Dispatch to: SAVESTATE
2336 \end_layout
2337
2338 \begin_layout Itemize
2339 Argument #1: Savestate id
2340 \end_layout
2341
2342 \begin_layout Itemize
2343 Argument #2 (optional): Rerecord count at time of saving savestate
2344 \end_layout
2345
2346 \begin_layout Standard
2347 Signals that savestate has occured here.
2348  The save state IDs MUST be unique in entire event stream.
2349  The second argument to savestate (if present) is rerecord count at time
2350  of saving that savestate (useful for calulating rerecord count of movie
2351  starting from savestate).
2352  No time restrictions
2353 \end_layout
2354
2355 \begin_layout Subsubsection
2356 Option event
2357 \end_layout
2358
2359 \begin_layout Itemize
2360 Dispatch to: OPTION
2361 \end_layout
2362
2363 \begin_layout Itemize
2364 Argument #1:
2365 \begin_inset Quotes eld
2366 \end_inset
2367
2368 ABSOLUTE
2369 \begin_inset Quotes erd
2370 \end_inset
2371
2372  or
2373 \begin_inset Quotes eld
2374 \end_inset
2375
2376 RELATIVE
2377 \begin_inset Quotes erd
2378 \end_inset
2379
2380
2381 \end_layout
2382
2383 \begin_layout Standard
2384 Controls various options.
2385
2386 \begin_inset Quotes eld
2387 \end_inset
2388
2389 ABSOLUTE
2390 \begin_inset Quotes erd
2391 \end_inset
2392
2393  turns on absolute mode (default) where event timestamps are absolute.
2394
2395 \begin_inset Quotes eld
2396 \end_inset
2397
2398 RELATIVE
2399 \begin_inset Quotes erd
2400 \end_inset
2401
2402  turns on relative mode where event timestamps are relative to last event
2403  in stream.
2404  The OPTION event itself is not affected by timing change.
2405  No time restrictions
2406 \end_layout
2407
2408 \begin_layout Subsubsection
2409 Keyboard keypress/keyrelease event:
2410 \end_layout
2411
2412 \begin_layout Itemize
2413 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2414 \end_layout
2415
2416 \begin_layout Itemize
2417 Argument #1: Fixed: "KEYEDGE"
2418 \end_layout
2419
2420 \begin_layout Itemize
2421 Argument #2: Key number.
2422  Valid values are 1-83, 85-95, 129-197 and 199-223
2423 \end_layout
2424
2425 \begin_layout Standard
2426 Send key press or key release.
2427  Keys work in toggle button manner.
2428  The event time must be multiple of 66 666, and must not be less than 60
2429  * 66 666 TUs after last PAUSE event, 20 * 66 666 TUs after last KEYEDGE
2430  on key >128 and 10 * 66 666 TUs after last KEYEDGE on key <128.
2431 \end_layout
2432
2433 \begin_layout Subsubsection
2434 Pause event:
2435 \end_layout
2436
2437 \begin_layout Itemize
2438 Dispatch to: org.jpc.emulator.peripheral.Keyboard
2439 \end_layout
2440
2441 \begin_layout Itemize
2442 Argument #1: Fixed: "PAUSE"
2443 \end_layout
2444
2445 \begin_layout Standard
2446 Send pause key event.
2447  The time restrictions are identical to KEYEDGE event.
2448 \end_layout
2449
2450 \begin_layout Subsubsection
2451 Joystick button event:
2452 \end_layout
2453
2454 \begin_layout Itemize
2455 Dispatch to: org.jpc.modules.Joystick
2456 \end_layout
2457
2458 \begin_layout Itemize
2459 Argument #1:
2460 \begin_inset Quotes eld
2461 \end_inset
2462
2463 BUTTONA
2464 \begin_inset Quotes erd
2465 \end_inset
2466
2467 ,
2468 \begin_inset Quotes eld
2469 \end_inset
2470
2471 BUTTONB
2472 \begin_inset Quotes erd
2473 \end_inset
2474
2475 ,
2476 \begin_inset Quotes eld
2477 \end_inset
2478
2479 BUTTONC
2480 \begin_inset Quotes erd
2481 \end_inset
2482
2483  or
2484 \begin_inset Quotes eld
2485 \end_inset
2486
2487 BUTTOND
2488 \begin_inset Quotes erd
2489 \end_inset
2490
2491
2492 \end_layout
2493
2494 \begin_layout Itemize
2495 Argument #2:
2496 \begin_inset Quotes eld
2497 \end_inset
2498
2499 0
2500 \begin_inset Quotes erd
2501 \end_inset
2502
2503  if released,
2504 \begin_inset Quotes eld
2505 \end_inset
2506
2507 1
2508 \begin_inset Quotes erd
2509 \end_inset
2510
2511  if pressed
2512 \end_layout
2513
2514 \begin_layout Standard
2515 Send button down/up event.
2516  No time restrictions.
2517 \end_layout
2518
2519 \begin_layout Subsubsection
2520 Joystick axis event:
2521 \end_layout
2522
2523 \begin_layout Itemize
2524 Dispatch to: org.jpc.modules.Joystick
2525 \end_layout
2526
2527 \begin_layout Itemize
2528 Argument #1:
2529 \begin_inset Quotes eld
2530 \end_inset
2531
2532 AXISA
2533 \begin_inset Quotes erd
2534 \end_inset
2535
2536 ,
2537 \begin_inset Quotes eld
2538 \end_inset
2539
2540 AXISB
2541 \begin_inset Quotes erd
2542 \end_inset
2543
2544 ,
2545 \begin_inset Quotes eld
2546 \end_inset
2547
2548 AXISC
2549 \begin_inset Quotes erd
2550 \end_inset
2551
2552  or
2553 \begin_inset Quotes eld
2554 \end_inset
2555
2556 AXISD
2557 \begin_inset Quotes erd
2558 \end_inset
2559
2560
2561 \end_layout
2562
2563 \begin_layout Itemize
2564 Argument #2: Multivibrator unstable state length in ns.
2565 \end_layout
2566
2567 \begin_layout Standard
2568 Set amount of time multivibrator remains in unstable state.
2569  No time restrictions.
2570 \end_layout
2571
2572 \begin_layout Subsubsection
2573 Reboot:
2574 \end_layout
2575
2576 \begin_layout Itemize
2577 Dispatch to: org.jpc.emulator.PC$ResetButton
2578 \end_layout
2579
2580 \begin_layout Itemize
2581 No arguments
2582 \end_layout
2583
2584 \begin_layout Standard
2585 Reboots the PC.
2586 \end_layout
2587
2588 \begin_layout Subsubsection
2589 Fda disk change:
2590 \end_layout
2591
2592 \begin_layout Itemize
2593 Dispatch to: org.jpc.emulator.PC$DiskChanger
2594 \end_layout
2595
2596 \begin_layout Itemize
2597 Argument #1: Fixed: "FDA"
2598 \end_layout
2599
2600 \begin_layout Itemize
2601 Argument #2: Number of image slot to put there.
2602
2603 \end_layout
2604
2605 \begin_layout Standard
2606 The disk number MUST be -1 or valid disk number.
2607  -1 MUST NOT be used if there is no disk in floppy drive A.
2608  This event causes specified disk to be placed to FDA or FDA disk to be
2609  ejected with no replacement if disk number is -1.
2610  The specified disk if not -1 must be of floppy type.
2611  The specified disk if valid must not be in any other drive.
2612 \end_layout
2613
2614 \begin_layout Subsubsection
2615 Fdb disk change:
2616 \end_layout
2617
2618 \begin_layout Itemize
2619 Dispatch to: org.jpc.emulator.PC$DiskChanger
2620 \end_layout
2621
2622 \begin_layout Itemize
2623 Argument #1: Fixed: "FDB"
2624 \end_layout
2625
2626 \begin_layout Itemize
2627 Argument #2: Number of image slot to put there.
2628
2629 \end_layout
2630
2631 \begin_layout Standard
2632 The disk number MUST be -1 or valid disk number.
2633  -1 MUST NOT be used if there is no disk in floppy drive B.
2634  This event causes specified disk to be placed to FDB or FDB disk to be
2635  ejected with no replacement if disk number is -1.
2636  The specified disk if not -1 must be of floppy type.
2637  The specified disk if valid must not be in any other drive.
2638 \end_layout
2639
2640 \begin_layout Subsubsection
2641 Change CDROM:
2642 \end_layout
2643
2644 \begin_layout Itemize
2645 Dispatch to: org.jpc.emulator.PC$DiskChanger
2646 \end_layout
2647
2648 \begin_layout Itemize
2649 Argument #1: Fixed: "CDROM"
2650 \end_layout
2651
2652 \begin_layout Itemize
2653 Argument #2: Number of image slot to put there.
2654
2655 \end_layout
2656
2657 \begin_layout Standard
2658 The disk number MUST be -1 or valid disk number.
2659  -1 MUST NOT be used if there is no disk in CD-ROM.
2660  This event causes specified disk to be placed to CD-ROM or CD-ROM disk
2661  to be ejected with no replacement if disk number is -1.
2662  The specified disk if not -1 must be of CD-ROM type.
2663 \end_layout
2664
2665 \begin_layout Standard
2666 This event has no effect if CD-ROM is locked.
2667 \end_layout
2668
2669 \begin_layout Subsubsection
2670 Write protect floppy:
2671 \end_layout
2672
2673 \begin_layout Itemize
2674 Dispatch to: org.jpc.emulator.PC$DiskChanger
2675 \end_layout
2676
2677 \begin_layout Itemize
2678 Argument #1: Fixed: "WRITEPROTECT"
2679 \end_layout
2680
2681 \begin_layout Itemize
2682 Argument #2: Number of image slot to manipulate
2683 \end_layout
2684
2685 \begin_layout Standard
2686 Write protects specified disk.
2687  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2688 \end_layout
2689
2690 \begin_layout Subsubsection
2691 Write unprotect floppy:
2692 \end_layout
2693
2694 \begin_layout Itemize
2695 Dispatch to: org.jpc.emulator.PC$DiskChanger
2696 \end_layout
2697
2698 \begin_layout Itemize
2699 Argument #1: Fixed: "WRITEUNPROTECT"
2700 \end_layout
2701
2702 \begin_layout Itemize
2703 Argument #2: Number of image slot to manipulate
2704 \end_layout
2705
2706 \begin_layout Standard
2707 Disables write protection specified disk.
2708  The disk MUST NOT be in any drive and MUST be valid floppy-type disk.
2709 \end_layout
2710
2711 \begin_layout Subsection
2712 Diskinfo sections
2713 \end_layout
2714
2715 \begin_layout Standard
2716 Diskinfo sections are named
2717 \begin_inset Quotes eld
2718 \end_inset
2719
2720 diskinfo-
2721 \begin_inset Quotes erd
2722 \end_inset
2723
2724 <id of disk>.
2725  They use line component encoding, fieldtype being first component on each
2726  line (value being the second).
2727  Following fields are defined:
2728 \end_layout
2729
2730 \begin_layout Subsubsection
2731 TYPE
2732 \end_layout
2733
2734 \begin_layout Standard
2735 Gives type of image.
2736  Possible values are
2737 \end_layout
2738
2739 \begin_layout Itemize
2740 \begin_inset Quotes eld
2741 \end_inset
2742
2743 FLOPPY
2744 \begin_inset Quotes erd
2745 \end_inset
2746
2747  (floppy disk)
2748 \end_layout
2749
2750 \begin_layout Itemize
2751 \begin_inset Quotes eld
2752 \end_inset
2753
2754 HDD
2755 \begin_inset Quotes erd
2756 \end_inset
2757
2758  (Hard disk)
2759 \end_layout
2760
2761 \begin_layout Itemize
2762 \begin_inset Quotes eld
2763 \end_inset
2764
2765 CDROM
2766 \begin_inset Quotes erd
2767 \end_inset
2768
2769  (CD-ROM)
2770 \end_layout
2771
2772 \begin_layout Itemize
2773 \begin_inset Quotes eld
2774 \end_inset
2775
2776 BIOS
2777 \begin_inset Quotes erd
2778 \end_inset
2779
2780  (BIOS/VGABIOS image)
2781 \end_layout
2782
2783 \begin_layout Itemize
2784 \begin_inset Quotes eld
2785 \end_inset
2786
2787 UNKNOWN
2788 \begin_inset Quotes erd
2789 \end_inset
2790
2791  (what the heck is this???)
2792 \end_layout
2793
2794 \begin_layout Subsubsection
2795 ID
2796 \end_layout
2797
2798 \begin_layout Standard
2799 Gives ID of disk.
2800 \end_layout
2801
2802 \begin_layout Subsubsection
2803 IMAGELENGTH
2804 \end_layout
2805
2806 \begin_layout Standard
2807 (BIOS images only) Gives length of BIOS image
2808 \end_layout
2809
2810 \begin_layout Subsubsection
2811 IMAGEMD5
2812 \end_layout
2813
2814 \begin_layout Standard
2815 MD5 of raw disk/BIOS image without any headers or trailers.
2816 \end_layout
2817
2818 \begin_layout Subsubsection
2819 TOTALSECTORS
2820 \end_layout
2821
2822 \begin_layout Standard
2823 (FLOPPY/HDD/CDROM images only) Number of total sectors on disk.
2824 \end_layout
2825
2826 \begin_layout Subsubsection
2827 TRACKS
2828 \end_layout
2829
2830 \begin_layout Standard
2831 (FLOPPY/HDD images only) Number of tracks on disk per side (1-256 for floppy,
2832  1-1024 for HDD).
2833 \end_layout
2834
2835 \begin_layout Subsubsection
2836 SIDES
2837 \end_layout
2838
2839 \begin_layout Standard
2840 (FLOPPY/HDD images only) Number of sides on disk (1 or 2 for floppy, 1-16
2841  for HDD).
2842 \end_layout
2843
2844 \begin_layout Subsubsection
2845 SECTORS
2846 \end_layout
2847
2848 \begin_layout Standard
2849 (FLOPPY/HDD images only) Number of sectors per track (1-255 for floppy,
2850  1-63 for HDD).
2851 \end_layout
2852
2853 \begin_layout Subsubsection
2854 COMMENT
2855 \end_layout
2856
2857 \begin_layout Standard
2858 Line from image comment block.
2859  Usually give data about files image has.
2860  May or may not be present.
2861 \end_layout
2862
2863 \begin_layout Subsection
2864 Savestates
2865 \end_layout
2866
2867 \begin_layout Standard
2868 Actual savestate format is not documented here.
2869  It is close to impossible to comprehend without access to emulator source
2870  anyway.
2871 \end_layout
2872
2873 \begin_layout Section
2874 Advanced: Making class dumpable
2875 \end_layout
2876
2877 \begin_layout Standard
2878 Class is made dumpable by implementing interface org.jpc.emulator.SRDumpable
2879  and implementing method dumpSRPartial(org.jpc.emulator.SRDumper) and constructor
2880  <init>(org.jpc.emulator.SRLoader).
2881  Non-static inner classes can not be dumpable (make them static using tricks
2882  similar to what javac uses).
2883 \end_layout
2884
2885 \begin_layout Standard
2886 If dumped class has dumpable superclass, the first thing dumping function
2887  needs to do is to call dumper function of superclass and first thing loading
2888  constructor needs to do is to call loading constructor of superclass.
2889  If class has no dumpable superclass, dumper doesn't need to do anything
2890  special, while loader needs to call objectCreated(this) on SRLoader object
2891  passed as parameter.
2892
2893 \end_layout
2894
2895 \begin_layout Standard
2896 Following these fixed parts, dump all members that are part of mutable state
2897  in emulator core.
2898 \end_layout
2899
2900 \begin_layout Subsection
2901 Member dumping/loading functions
2902 \end_layout
2903
2904 \begin_layout Standard
2905 There is dumping/loading function for following (all functions dumping/loading
2906  reference types can handle null):
2907 \end_layout
2908
2909 \begin_layout Itemize
2910 boolean: SRDumper.dumpBoolean, SRLoader.loadBoolean
2911 \end_layout
2912
2913 \begin_layout Itemize
2914 byte: SRDumper.dumpByte, SRLoader.loadByte
2915 \end_layout
2916
2917 \begin_layout Itemize
2918 short: SRDumper.dumpShort, SRLoader.loadShort
2919 \end_layout
2920
2921 \begin_layout Itemize
2922 int: SRDumper.dumpInt, SRLoader.loadInt
2923 \end_layout
2924
2925 \begin_layout Itemize
2926 long: SRDumper.dumpLong, SRLoader.loadLong
2927 \end_layout
2928
2929 \begin_layout Itemize
2930 String: SRDumper.dumpString, SRLoader.loadString
2931 \end_layout
2932
2933 \begin_layout Itemize
2934 boolean[]: SRDumper.dumpArray, SRLoader.loadArrayBoolean
2935 \end_layout
2936
2937 \begin_layout Itemize
2938 byte[]: SRDumper.dumpArray, SRLoader.loadArrayByte
2939 \end_layout
2940
2941 \begin_layout Itemize
2942 short[]: SRDumper.dumpArray, SRLoader.loadArrayShort
2943 \end_layout
2944
2945 \begin_layout Itemize
2946 int[]: SRDumper.dumpArray, SRLoader.loadArrayInt
2947 \end_layout
2948
2949 \begin_layout Itemize
2950 long[]: SRDumper.dumpArray, SRLoader.loadArrayLong
2951 \end_layout
2952
2953 \begin_layout Itemize
2954 double[]: SRDumper.dumpArray, SRLoader.loadArrayDouble
2955 \end_layout
2956
2957 \begin_layout Itemize
2958 <dumpable type>: SRDumper.dumpObject, SRLoader.loadObject
2959 \end_layout
2960
2961 \begin_layout Itemize
2962 special object: SRDumper.specialObject, SRLoader.specialObject
2963 \end_layout
2964
2965 \begin_layout Subsubsection
2966 Notes:
2967 \end_layout
2968
2969 \begin_layout Itemize
2970 Dumpable objects come out as type of org.jpc.emulator.SRDumpable.
2971 \end_layout
2972
2973 \begin_layout Itemize
2974 Special objects are various static objects that don't need to be stored
2975  because they don't have mutable fields.
2976 \end_layout
2977
2978 \begin_layout Itemize
2979 Don't dump fields related to event state feedback.
2980 \end_layout
2981
2982 \begin_layout Itemize
2983 Don't dump temporary flags that are only used while PC is running.
2984  Savestate when PC is running isn't possible anyway.
2985 \end_layout
2986
2987 \begin_layout Itemize
2988 Some connectors dump fields related to connector output, some don't.
2989 \end_layout
2990
2991 \begin_layout Section
2992 Advanced: Making output connectors
2993 \end_layout
2994
2995 \begin_layout Standard
2996 Implementing interface org.jpc.emulator.DisplayController signals that this
2997  is display controller, inhibiting loading of the standard VGA display controlle
2998 r if loaded as module.
2999
3000 \end_layout
3001
3002 \begin_layout Subsection
3003 Interface org.jpc.emulator.OutputConnector
3004 \end_layout
3005
3006 \begin_layout Standard
3007 Class is made to be output connector by implementing this interface.
3008  This interface specifies the methods used for output hold locking.
3009  Class org.jpc.emulator.OutputConnectorLocking has implementations of these
3010  that are suitable for calling.
3011
3012 \end_layout
3013
3014 \begin_layout Subsubsection
3015 Method subscribeOutput(Object)
3016 \end_layout
3017
3018 \begin_layout Standard
3019 Subscribes the output, with specified object as handle.
3020 \end_layout
3021
3022 \begin_layout Subsubsection
3023 Method unsubscribeOutput(Object)
3024 \end_layout
3025
3026 \begin_layout Standard
3027 Unsubscribe the specified handle object from output.
3028 \end_layout
3029
3030 \begin_layout Subsubsection
3031 Method waitOutput(Object)
3032 \end_layout
3033
3034 \begin_layout Standard
3035 Wait for output on specified connector using specified handle object.
3036  Returns true on success, false if wait was interrupted by thread interrupt.
3037  Blocking.
3038 \end_layout
3039
3040 \begin_layout Subsubsection
3041 Method releaseOutput(Object)
3042 \end_layout
3043
3044 \begin_layout Standard
3045 Release connector from p.o.v.
3046  of given handle.
3047  Does not block.
3048 \end_layout
3049
3050 \begin_layout Subsubsection
3051 Method holdOutput()
3052 \end_layout
3053
3054 \begin_layout Standard
3055 Release threads waiting on waitOutput() and block until all subscribers
3056  have returned from waitOutput() and enteired releaseOutput().
3057 \end_layout
3058
3059 \begin_layout Subsubsection
3060 Method releaseOutputWaitAll(object)
3061 \end_layout
3062
3063 \begin_layout Standard
3064 Like releaseOutput(), but waits until all handles have released their output.
3065 \end_layout
3066
3067 \begin_layout Subsection
3068 Class org.jpc.emulator.VGADigtalOut
3069 \end_layout
3070
3071 \begin_layout Standard
3072 Class org.jpc.emulator.VGADigtalOut (already implements OutputConnector) implements
3073  VGA output connector.
3074  If module provodes output connector, it needs to implement org.jpc.emulator.Displa
3075 yController.
3076 \end_layout
3077
3078 \begin_layout Subsubsection
3079 Method getWidth()
3080 \end_layout
3081
3082 \begin_layout Standard
3083 Get width of display (watch out, can return 0).
3084 \end_layout
3085
3086 \begin_layout Subsubsection
3087 Method getHeight()
3088 \end_layout
3089
3090 \begin_layout Standard
3091 Get height of display (watch out, can return 0).
3092 \end_layout
3093
3094 \begin_layout Subsubsection
3095 Methods getDirtyXMin(), getDirtyXMax(), getDirtyYMin(), getDirtyYMax()
3096 \end_layout
3097
3098 \begin_layout Standard
3099 Returns the dirty region (region modified since last output).
3100 \end_layout
3101
3102 \begin_layout Subsubsection
3103 Method getBuffer()
3104 \end_layout
3105
3106 \begin_layout Standard
3107 Get buffer of ints, at least width * height elements (left-to-right, top-down,
3108  one value per pixel) giving pixel data.
3109  Value for each pixel is 65536 * <red-component> + 256 * <green-component>
3110  + <blue-component>.
3111 \end_layout
3112
3113 \begin_layout Subsubsection
3114 Method resizeDisplay(int _width, int _height)
3115 \end_layout
3116
3117 \begin_layout Standard
3118 Resize the display to be of specified size.
3119 \end_layout
3120
3121 \begin_layout Subsubsection
3122 Method dirtyDisplayRegion(int x, int y, int w, int h)
3123 \end_layout
3124
3125 \begin_layout Standard
3126 Mark the specified region as dirty.
3127 \end_layout
3128
3129 \begin_layout Subsubsection
3130 Method resetDirtyRegion()
3131 \end_layout
3132
3133 \begin_layout Standard
3134 Resets the dirty region to be empty.
3135 \end_layout
3136
3137 \begin_layout Subsection
3138 Class org.jpc.emulator.PC method getVideoOutput()
3139 \end_layout
3140
3141 \begin_layout Standard
3142 Get VGA output connector for PC.
3143 \end_layout
3144
3145 \begin_layout Subsection
3146 Interface org.jpc.emulator.DisplayController.
3147 \end_layout
3148
3149 \begin_layout Standard
3150 Implementing this class signals that module is VGA controller.
3151  There can be only one such module active at time and presence of such module
3152  prevents loading builtin VGA controller emulation code.
3153 \end_layout
3154
3155 \begin_layout Subsubsection
3156 Method getOutputDevice()
3157 \end_layout
3158
3159 \begin_layout Standard
3160 Get VGA output connector for this VGA device.
3161 \end_layout
3162
3163 \begin_layout Subsection
3164 Class org.jpc.emulator.SoundDigitalOut
3165 \end_layout
3166
3167 \begin_layout Standard
3168 Class org.jpc.emulator.SoundDigitalOut provodes output connector for sound.
3169  Each connector can transfer stereo signal at arbitiary sampling rate.
3170  Modules that have audio connectors need to implement interface org.jpc.emulator.So
3171 undOutputDevice, as this signals that output connectors should be created.
3172 \end_layout
3173
3174 \begin_layout Subsubsection
3175 Method addSample(long, short, short)
3176 \end_layout
3177
3178 \begin_layout Standard
3179 Add stereo sample at time given by first argument.
3180  The second and third arguments give volume on left and right channels.
3181 \end_layout
3182
3183 \begin_layout Subsubsection
3184 Method addSample(long, short)
3185 \end_layout
3186
3187 \begin_layout Standard
3188 Add mono sample at time given by first argument.
3189  The second argument give volume on both channels.
3190 \end_layout
3191
3192 \begin_layout Subsubsection
3193 Method readBlock(Block)
3194 \end_layout
3195
3196 \begin_layout Standard
3197 Reads block of output (atomic versus addSample).
3198  Block structure has following fields which are filled:
3199 \end_layout
3200
3201 \begin_layout Itemize
3202 timeBase: Time base for block.
3203 \end_layout
3204
3205 \begin_layout Itemize
3206 baseLeft: Left volume at time base.
3207 \end_layout
3208
3209 \begin_layout Itemize
3210 baseRight: Right volume at time base
3211 \end_layout
3212
3213 \begin_layout Itemize
3214 blockNo: Sequence number of block filled.
3215 \end_layout
3216
3217 \begin_layout Itemize
3218 samples: Number of samples in block
3219 \end_layout
3220
3221 \begin_layout Itemize
3222 sampleTiming: Number of nanoseconds since last sample
3223 \end_layout
3224
3225 \begin_layout Itemize
3226 sampleLeft: Left channel samples
3227 \end_layout
3228
3229 \begin_layout Itemize
3230 sampleRight: Right channel samples
3231 \end_layout
3232
3233 \begin_layout Subsection
3234 Interface org.jpc.emulator.SoundOutputDevice
3235 \end_layout
3236
3237 \begin_layout Standard
3238 Implementing this interface signals that module has audio output channels.
3239 \end_layout
3240
3241 \begin_layout Subsubsection
3242 Method org.jpc.emulator.SoundOutputDevice.requestedSoundChannels()
3243 \end_layout
3244
3245 \begin_layout Standard
3246 Return the number of sound channels module has.
3247 \end_layout
3248
3249 \begin_layout Subsubsection
3250 Method org.jpc.emulator.SoundOutputDevice.soundChannelCallback(SoundDigitalOut)
3251 \end_layout
3252
3253 \begin_layout Standard
3254 This is called once per sound channel requested giving precreated sound
3255  channel.
3256 \end_layout
3257
3258 \begin_layout Subsection
3259 Class org.jpc.emulator.PC method getSoundOut(String)
3260 \end_layout
3261
3262 \begin_layout Standard
3263 Get sound output with specified name.
3264 \end_layout
3265
3266 \begin_layout Section
3267 Advanced: Writing event targets
3268 \end_layout
3269
3270 \begin_layout Standard
3271 Whereas output connectors are the way output is dispatched, input is dispatched
3272  via event targets.
3273  Event targets need to implement interface org.jpc.emulator.EventDispatchTarget.
3274 \end_layout
3275
3276 \begin_layout Standard
3277 Event targets also provode methods which then encode events and dispatch
3278  them forward (without doing anything else) to event recorder.
3279  Also, event targets may have methods for obtaining state.
3280 \end_layout
3281
3282 \begin_layout Subsection
3283 Interface org.jpc.emulator.EventDispatchTarget
3284 \end_layout
3285
3286 \begin_layout Standard
3287 Interface that marks class capable of receiving events.
3288 \end_layout
3289
3290 \begin_layout Subsubsection
3291 Method setEventRecorder(EventRecorder)
3292 \end_layout
3293
3294 \begin_layout Standard
3295 Set the event recorder input events are sent to.
3296 \end_layout
3297
3298 \begin_layout Subsubsection
3299 Method startEventCheck()
3300 \end_layout
3301
3302 \begin_layout Standard
3303 Signals target to reset all state related to event checking and state feedback.
3304  This may be called at any time in order to reinitialialize event checking/feedb
3305 ack state.
3306 \end_layout
3307
3308 \begin_layout Subsubsection
3309 Method doEvent(long, String[], int) throws IOException
3310 \end_layout
3311
3312 \begin_layout Standard
3313 Event dispatch handler.
3314  The first argument is event time, second is parameters and third is what
3315  to do with it.
3316  If target doesn't like the event, throw IOException.
3317  Following types (the integer parameter) are used:
3318 \end_layout
3319
3320 \begin_layout LyX-Code
3321 0 (EventRecorder.EVENT_TIMED): Time has been assigned for event.
3322 \end_layout
3323
3324 \begin_layout LyX-Code
3325 1 (EventRecorder.EVENT_STATE_EFFECT_FUTURE): Future event in event replay
3326  for reinitialization
3327 \end_layout
3328
3329 \begin_layout LyX-Code
3330 2 (EventRecorder.EVENT_STATE_EFFECT): Past event in event replay reinitialization
3331 \end_layout
3332
3333 \begin_layout LyX-Code
3334 3 (EventRecorder.EVENT_EXECUTE): This event occurs now.
3335  Execute the effect.
3336 \end_layout
3337
3338 \begin_layout Subsubsection
3339 Method endEventCheock()
3340 \end_layout
3341
3342 \begin_layout Standard
3343 End event reinitialization.
3344  Usually unused.
3345 \end_layout
3346
3347 \begin_layout Subsubsection
3348 Method getEventTimeLowBound(long, String[]) throws IOException
3349 \end_layout
3350
3351 \begin_layout Standard
3352 Return the time value that's the earliest possiblity for this event to occur.
3353  Returning any time in past (including -1) causes event to fire as soon
3354  as possible.
3355  The long parameter gives the current scheduled time for event.
3356 \end_layout
3357
3358 \begin_layout Section
3359 Writing modules
3360 \end_layout
3361
3362 \begin_layout Standard
3363 Modules are various extensions that run inside emulator core.
3364  As such, they affect sync.
3365  Modules must implement interface org.jpc.emulator.HardwareComponent (they
3366  are hardware components) and must be dumpable.
3367  Additionally, they need either constructor <init>() or <init>(String).
3368  The first is if no parameters are passed, the second is for case where
3369  parameters are passed.
3370 \end_layout
3371
3372 \begin_layout Standard
3373 Aside of the constructors, modules need to obey the ordinary conventions
3374  for hardware components.
3375  No code outside modules needs to know that module exists.
3376 \end_layout
3377
3378 \begin_layout Section
3379 Writing plugins
3380 \end_layout
3381
3382 \begin_layout Standard
3383 Plugins handle various UI tasks.
3384  They need to implement interface org.jpc.Plugin.
3385 \end_layout
3386
3387 \begin_layout Subsection
3388 Interface org.jpc.pluginsbase.Plugin
3389 \end_layout
3390
3391 \begin_layout Subsubsection
3392 Method systemShutdown()
3393 \end_layout
3394
3395 \begin_layout Standard
3396 Called when emulator shuts down.
3397  Either called in dedicated thread or in thread that called emulatorShutdown().
3398  These handlers should do the bare minimum to get files on disk to consistent
3399  state.
3400  After these calls from all plugins have finished, emulator exits.
3401  Do not try to manipulate UI from these methods, as doing that easily leads
3402  into deadlock.
3403 \end_layout
3404
3405 \begin_layout Subsubsection
3406 Method reconnect(PC)
3407 \end_layout
3408
3409 \begin_layout Standard
3410 Gives new PC to connect to.
3411  Null is passed if plugin should disconnect.
3412 \end_layout
3413
3414 \begin_layout Subsubsection
3415 Method main()
3416 \end_layout
3417
3418 \begin_layout Standard
3419 Called in dedicated thread after plugin is initialized.
3420 \end_layout
3421
3422 \begin_layout Subsubsection
3423 Method pcStopping()
3424 \end_layout
3425
3426 \begin_layout Standard
3427 Called after PC has stopped.
3428 \end_layout
3429
3430 \begin_layout Subsubsection
3431 Method pcStarting()
3432 \end_layout
3433
3434 \begin_layout Standard
3435 Called before PC starts.
3436 \end_layout
3437
3438 \begin_layout Subsubsection
3439 Method notifyArguments(String[])
3440 \end_layout
3441
3442 \begin_layout Standard
3443 Pass arguments from command line.
3444 \end_layout
3445
3446 \begin_layout Subsubsection
3447 Constructor <init>(Plugins)
3448 \end_layout
3449
3450 \begin_layout Standard
3451 This constructor is used to initialize plugins that don't take parameters.
3452 \end_layout
3453
3454 \begin_layout Subsubsection
3455 Constructor <init>(Plugins, String)
3456 \end_layout
3457
3458 \begin_layout Standard
3459 This constructor is used to initialize plugins that take parameters.
3460 \end_layout
3461
3462 \begin_layout Subsection
3463 Class org.jpc.pluginsbase.Plugins
3464 \end_layout
3465
3466 \begin_layout Standard
3467 This class provodes various methods for manipulating plugins.
3468 \end_layout
3469
3470 \begin_layout Subsubsection
3471 Method isShuttingDown()
3472 \end_layout
3473
3474 \begin_layout Standard
3475 Returns true if Plugins.shutdownEmulator() has been called somehow, either
3476  via VM exit, CTRL+C or explicitly.
3477  Useful to skip cleanups involving GUI, as these are too deadlock-prone.
3478 \end_layout
3479
3480 \begin_layout Subsubsection
3481 Method shutdownEmulator()
3482 \end_layout
3483
3484 \begin_layout Standard
3485 Shut down and exit the emulator.
3486  All plugin shutdown functions are called in this thread.
3487 \end_layout
3488
3489 \begin_layout Subsubsection
3490 Method reconnectPC(PC)
3491 \end_layout
3492
3493 \begin_layout Standard
3494 Signal reconnectPC event to all plugins.
3495 \end_layout
3496
3497 \begin_layout Subsubsection
3498 Method pcStarted()
3499 \end_layout
3500
3501 \begin_layout Standard
3502 Signal pcStarting() event to all plugins.
3503 \end_layout
3504
3505 \begin_layout Subsubsection
3506 Method pcStopped()
3507 \end_layout
3508
3509 \begin_layout Standard
3510 Signal pcStopping() event to all plugins.
3511 \end_layout
3512
3513 \begin_layout Subsection
3514 Interface org.jpc.pluginsbase.ExternalCommandInterface
3515 \end_layout
3516
3517 \begin_layout Standard
3518 Implementing interface org.jpc.pluginsbase.ExternalCommandInterface signals
3519  that plugin can receive commands via external commands interface.
3520 \end_layout
3521
3522 \begin_layout Subsubsection
3523 Method invokeCommand(String cmd, String[] args)
3524 \end_layout
3525
3526 \begin_layout Standard
3527 Invoke specified command using specified arguments.
3528  Return true if event is to be shallowed, false to continue trying to pass
3529  it to more plugins.
3530 \end_layout
3531
3532 \begin_layout Section
3533 Lua kernel programming
3534 \end_layout
3535
3536 \begin_layout Standard
3537 At startup, kernel gets its arguments in 'args' table and the script name
3538  to run in 'scriptname' string.
3539  It should enter the named script in protected mode.
3540 \end_layout
3541
3542 \begin_layout Standard
3543 The Lua VM exports numerious callbacks to kernel.
3544  The kernel can then choose to omit, wrap or re-export these to Lua scripts.
3545 \end_layout
3546
3547 \begin_layout Itemize
3548 Always grab any functions used into local variables so nobody can mess with
3549  them
3550 \end_layout
3551
3552 \begin_layout Itemize
3553 Don't use global variables in kernel (except for those passed).
3554 \end_layout
3555
3556 \end_body
3557 \end_document