@DATABASE whdload.guide @$VER:whdload.guide V0.1 22.05.96 B.Jahn @FONT helvetica.font 13 @WORDWRAP @NODE main "WHDLoad.guide" @{JCENTER} @{b}WHDLoad@{ub} (the ultimate HD-Installer for OS-Killer) send comments, bug reports, new slaves to: jah@boss.hrz.fh-zwickau.de @{" What's this ? " LINK whatfor} @{" Features " LINK feat} @{" Requirements " LINK need} @{" Installation " LINK install} @{" Options for WHDLoad " LINK opt} @{" how to install anything to HD " LINK howto} @{" Executing flow " LINK tech} @{" autodocs " SYSTEM "SYS:Utilities/Multiview autodoc/whdload.doc"} read them ! @{" Future plans " LINK future} additional tools @{" DIC * The Disk-Image-Creator " LINK dic} @{" Reloc * Relocating Executables " LINK reloc} @{" booah " LINK asm} @{" Copyright " LINK copy} @{" Disclaimer " LINK disc} @{" The Author " LINK author} @ENDNODE @NODE whatfor "What for this piece is ?!" WHDLoad is designed to easy install programs (demos,games...) which kill the operating system on harddisk. To install a program, a so called "slave" must be written. The slave is the connection between the program and WHDLoad, and coordinates the reading and writing of files. On every disk access WHDLoad will switch from the installed program to the Operating System, and after the access back. Some Example Installs are provided with this release (Gods,ChaosEngine,Powermonger,Oscar) in the directory "Examples". Some more installs are available on the @{" WWW page " LINK author}. Because the simple interface and the example sources it will be very easy for anybody to install nearly any program on harddisk. @ENDNODE @NODE feat "Features" @{JCENTER} @{B}Features of WHDLoad@{UB} startable via CLI or Workbench absolutely clear return to the OS (depends on the Slave) possibility to use "disk images" or real files variable MemSize for the program from $1000 up to $200000 intelligent allocation of the memory, partial absolute and partial independent caching of files on start-up and dynamically on runtime (LRU) caching of disk images via preload on start-up automatic decrunching of files emulation of MOVE SR,ea from User-Mode on 68010+ emulation of unsupported integer-instructions on 68060 debugging support (complete memory and register dump) WHDLoad is tested on the following machines : A1200 Blz 030/50/50 2 MBChip 4 MBFast AGA Kick 39.106 A2000 GVP 030/25/25 1 MBChip 1+4 MBFast ECS Kick 40.063(soft) A4000/030/25 2 MBChip 2+8 MBFast CV64 Kick 40.068(soft) A4000 CS 060/50 2 MBChip 28 MBFast CV64 Kick 39.106 SPARCstation-5 Solaris 2.5 uae 0.5.3 @ENDNODE @NODE need "Required is ?!" @{JCENTER} @{B}Requirements@{UB} @{b}to run installed programs :@{ub} Kickstart 2.0 (version 37+) a minimum of 1.0 MB RAM (depends on the program) @{b}to write new slaves / install programs :@{ub} know how about machinecode, assembler, amiga specific things ... an Assembler (should be able to optimize) some other tools will be useful (hexedit,disasm,...) some more MB's RAM access to various machines ('000-'060,ECS,AGA,GfxCard) for testing reasons @ENDNODE @NODE install "Installation" @{JCENTER}@{B}Installation@{UB}@{JLEFT} The easiest way to install WHDLoad, the supplied tools (DIC, Reloc) and the Examples is to use the provided Installer scripts. Important is, that the tools and WHDLoad are accessible without a path specification. Therefore the recommend place is "C:". Anyhow WHDLoad can also installed in the local directory where the program is located (notice that in the Project Icons of the Examples only "WHDLoad" is used, without any path). @ENDNODE @NODE opt "Options" @{JCENTER}@{B}Options@{UB} @{JLEFT} WHDLoad is startable via the CLI or via the Workbench (Project Icon). Options can specified via the CLI directly, via the Workbench with Tooltypes. Template: SLAVE,SURVIVERESET/S,NOTRAPHANDLER/S,PRELOAD/S,NOCACHE/S,NTSC/S,WRITEDELAY/K/N SLAVE name of the slave which should be used default: "WHDLoad.slave" SURVIVERESET/S enables reset surviving (you can quit a running program by pressing Ctrl+LCmd+RCmd) this is only in beta stadium (it works perhaps on 2MBChip only machines) more infos in the autodoc NOTRAPHANDLER/S enables original OS vector table with this WHDLoad will not catch any exceptions use this if you get strange exceptions ... Warning: if the OS tries to create an exec.Alert the machine will crash (most times) PRELOAD/S if selected WHDLoad tries to cache as far as possible files/disk images on startup this should be always enabled NOCACHE/S forbids enabling of the CPU-caches (resload_SetCACR) NTSC/S if selected WHDLoad switches to NTSC-videomode (custom.beamcon0) WRITEDELAY/K/N time in 1/50 secs that WHDLoad will wait after writing anything to disk (savegames, highscores) @ENDNODE @NODE howto "How to install" @{JCENTER} @{" general rules " LINK ht_general} @{B}the easiest case@{UB} @{" One disk trackloader without savegames " LINK ht_easy} @{B}possible problems@{UB} @{" non standard disk format " LINK ht_ndos} @{" more than one disk " LINK ht_mdisk} @{" highscores saving " LINK ht_highs} @{" savegames " LINK ht_savegames} @{" OS accesses " LINK ht_os} @{" bugs over bugs " LINK ht_bugs} @{B}tips & tricks@{UB} @{" choice between diskimages/files " LINK ht_images} @{" writing installs " LINK ht_installs} @ENDNODE @NODE ht_easy "Simple One Disk TrackLoader" @{JCENTER}@{B}How to install a simple one disk trackloader@{UB} @{JLEFT} @{JCENTER}I. Prework @{JLEFT} Make a drawer which will hold all files. Create disk image using @{" DIC " LINK dic} in this drawer. Create a #?.info file with "WHDLoad" as >Default Tool< and a Tooltype "SLAVE=#?" contain the name of the slave. (or simple copy the icon from an Example Install, and disable all tooltype except >SLAVE=<) @{JCENTER}II. The slave @{JLEFT} To write the slave we need some informations: 1. Where on disk is main executable file located ? 2. Where inside the main executable is the disk loader located ? To get these informations we first analyze the bootblock. Most times the main exe will loaded from here via exec.DoIo(). Sometimes a special trackloader stands in the bootblock. We now write a slave which will simulate the bootblock and loads the main exe from the disk image. After that we have to find the loader in the main exe. An fast way is to search for the pattern $AAAAAAAA (used by MFM decoding) with a hex-editor. Then cut the area (+/- $1000 bytes) found, disassemble it, and search the start of the routine. Understand the parameterlist. No we create some code for the slave which will patch the loader routine, that all calls to the loader will redirect to the slave, which will call WHDLoad (the parameters must be adjusted). @{JCENTER}III. The end @{JLEFT} Now create an nice Icon and all is done. @{JCENTER}DCLXVI. I know this sounds easier as it is @{JLEFT} I can't and I don't want describe all possible problems here which can occur. Sorry ! See also the other chapters one page before. @ENDNODE @NODE ht_ndos "non standard trackloader" @{JCENTER}@{B}non standard trackloader@{UB} @{JLEFT} Some programs use a very own disk format. With the result, that DIC is unable to create the disk images. So you must use the orginal loader routine. Most times this routine is located in a preloader (blocks 2-11) which will loaded from the bootblock (sometimes it is in the bootblock, further simple). So write a slave which will create the disk image using the orginal loader (patch the loader to read the required disk area and save them with reload_SaveFile). Some times the loaders are unable to read a whole disk or you will have to less memory, in this case let the install slave create smaller files (10 cyls for example). And later join them using "C:Join". @ENDNODE @NODE ht_mdisk "multiple disks" @{JCENTER}@{B}more than one disk@{UB} @{JLEFT} If the program uses more than one disk the slave must redirect the disk accesses to the appropriate image file. Sometimes this is not easy. Some programs support more than one drive, so you can use the drive number for selecting the disk. Most programs use an id on every disk to distinguish them. In this case use a variable which holds the disk number, and on every access to the disk id (determinate this by analyzing the parameters for the disk loader) increase the var (if last disk reached decrease, of course). So hopefully the loader will read the id again and again up the right disk is inserted ! Perhaps there is an request from the program that the user should insert the right disk, disable it. @ENDNODE @NODE ht_highs "highscore saving" @{JCENTER}@{B}saving highscores@{UB} @{JLEFT} Not much to say here. Use resload_SaveFile to write the appropriate memory area to the disk. If you like encrypt it a bit that not every lamer can patch it. Remember, that always a separate file must be used. So the initial read of the highscores, most times loaded by the program from a disk image, must be redirected to the highscore file. (Example Gods.slave) @ENDNODE @NODE ht_savegames "savegames" @{JCENTER}@{B}writing savegames@{UB} @{JLEFT} Savegame handling is near the same as with highscores. But you must disable the savegames from caching (remember all files which are loaded by WHDLoad are cached automatically if enough memory is available). To do this use a pattern which matches all savegames (e.g. name all savegames to "save.[0-9]" and use the pattern "save.#?"). @ENDNODE @NODE ht_os "os accesses" @{JCENTER}@{B}accesses to the operating system@{UB} @{JLEFT} At the time the slave or the program is executed absolutely no os exist nor is accessible nor makes any sense to access them ! Therefore all accesses which the program will do, must be disabled. If there are less of them, and without function (like exec.Disable() or exec.SuperState()) simple $4e71 them. If the accesses have an important function (like exec.DoIo()), redirect them to the slave and emulate them. If there are a lot of them, create an simple exec.library in an unused memory area (set $4 to this). (Example Oscar.slave emulates exec.AllocMem()) @ENDNODE @NODE ht_bugs "bugs over bugs" @{JCENTER}@{B}bugs over bugs@{UB} @{JLEFT} Not seldom the program itself contains a lot of bugs. For example if you an exception "line 1111 emulator at $cccccccc" than the program has jumped from an uninitialized pointer. If you got so a shit it may help to clear $400 - ws_BaseMemSize. @ENDNODE @NODE ht_images "diskimages or files" @{JCENTER}@{B}what's better diskimages or files@{UB} @{JLEFT} Sometimes you will have the choice to use disk images or real files. Both has advantages. The use of disk images is most time the easier and faster way to create the slave. But real files are better cacheable (if there is less memory or the memory is fragmented diskimages cannot be cached). The needed space on harddisk will also smaller with real files than with disk images. Only if there are a lot of files (more than 30) you should use disk images. @ENDNODE @NODE ht_installs "writing installs" @{JCENTER}@{B}writing installs@{UB} @{JLEFT} * If you want to distribute the slave/install, check it at least on 68000/OCS and 68060/GfxCard equipped machines. * Use an Installer script if you provide an install. (best you modify one on the provided scripts, I think they are good.) @ENDNODE @NODE ht_general "general rules" @{JCENTER}@{B}general rules@{UB} @{JLEFT} * Never modify disk images. Because, if you do so, and anybody wishes to start the program from a floppy he must only write the images back to a disk. * Never use orginal stuff from the program directly in the slave (copyright problem). * Disable all stuff which access the os. (otherwise the system will be destroyed) * Enable the Instruction Cache only if you are sure it runs on all processors. (Remember: Data Cache is senseless because the Chip memory is normally not data cacheable) * Use less memory as possible for ws_BaseMemSize. Some people have resident tags on the end of the Chip memory, so it helps to use only $1f0000 instead $200000 and WHDLoad can use absolute allocated memory. @ENDNODE @NODE tech "Technics" @{JCENTER}@{B}Executing flow@{UB} @{JLEFT} here is a typical executing sequence : USER starts WHDLoad will be loaded and started loads and checks the slave allocates required memory preloads diskimages/files (if enabled) switches os off calls the slave slave loads the main program (via calling WHDLoad) patches the program that the program will load his files via the slave patches the program to enable an exit from the program calls the main program program will do his stuff USER exits the program (for example by pressing ESC) slave will return to WHDLoad WHDLoad switches OS on frees all resources quits @ENDNODE @NODE future "Future plans" @{JCENTER} @{b}Future plans@{ub} full memory protection using MMU a real SURVIVERESET emulating of some OS functions (exec.AllocMem,exec.DoIO,...) support for nonvolatile.library (savegames) (if you want anything from these you should send me a mail, otherwise perhaps nothing of that will ever come true) @ENDNODE @NODE dic "The Disk-Image-Creator" @{b}DIC * The Disk-Image-Creator@{ub} A small tool to create disk-image-files on your harddisk, from NDOS floppy disks. @{B}Installation:@{UB} copy it to C: , or a similar place @{B}Usage:@{UB} enter directory where the images should stored type "DIC" on the Shell and press RETURN now insert the disks and follow the instructions from DIC after the last disk is read by DIC break it by pressing CTRL-C @{B}Options:@{UB} DEVICE,FD=FIRSTDISK/K/N,LD=LASTDISK/K/N DEVICE the device from which DIC will read the disks default "DF0:" example "RAD:" FD=FIRSTDISK/K/N number of first disk default "FD=1" example "FD=0" LD=LASTDISK/K/N number of last disk default "LD=999999" example "LD=3" @{B}Return code@{UB} The return code is set to 0 if all disks from "FD" up to "LD" are read successfully. Otherwise 10 is returned. @{B}Background:@{UB} DIC can read any diskgeometry, also HD's (a question from me: is there any #?.device out there which is able to read some non standard formats (trackloader) ?) if a track cannot be read, the area in the diskimage is filled with the pattern "TDIC" and DIC goes to the next track, anyway an error message will you inform about this @ENDNODE @NODE reloc "Relocating Executables" @{b}Reloc * Relocating Executables@{ub} A small tool to relocate a standard AmigaDOS Executable to an absolute address and save this as a simple data file. This is required because WHDLoad is not able to handle AmigaDOS executables. @{B}Installation:@{UB} copy it to C: , or a similar place @{B}Options:@{UB} INPUTFILE/A,OUTPUTFILE,ADR/K,QUIET/S INPUTFILE/A the executable file which should relocated must specified OUTPUTFILE the name of the file to write if not specified the source file will be overwritten ADR/K the start address for the relocated file if not specified $400 is used you can use simple expressions like these : "$5000" = "20480" = " -$Ff +-33+ 19512+$4e8" (prefix "$" for hexadecimal numbers, supported operators are "+" and "-") QUIET/S disables all output, except error messages enable this for using in conjunction with the Installer @{B}Return code@{UB} The return code is set to 0 if all went OK, otherwise to 10. @{B}Background:@{UB} the HUNK's from the executable are copied in the same order to the absolute file BSS-HUNK's are blown up to their real sizes supported are only pre 2.0 HUNK's warning: this tool is not fully tested, bugs are possible @ENDNODE @NODE asm "Assembler Output" BASM 1.131 (12-Dez-95) «Barfly Assembler (REG.)» Copyright © Ralph Schmidt 1990-95 Assembling : WHDLoad.asm PASS 1 Optimize Pass 1...633 Symbol Changes | 2 Length Failures... Optimize Pass 2...630 Symbol Changes | 2 Length Failures... Optimize Pass 3...578 Symbol Changes | 2 Length Failures... Optimize Pass 4...507 Symbol Changes | 2 Length Failures... Optimize Pass 5...475 Symbol Changes | 2 Length Failures... Optimize Pass 6...367 Symbol Changes | 2 Length Failures... Optimize Pass 7...191 Symbol Changes | 0 Length Failures... Optimize Pass 8...32 Symbol Changes | 0 Length Failures... Optimize Pass 9...0 Symbol Changes | 0 Length Failures... 17692 Lines assembled in 26.665 Seconds(39808 Lines/Min) WHDLoad.asm contains 4182 Lines. 0 Symbol(s) declared global. 0 Symbol(s) referenced external. 77 Macros(s) defined. 2410 Macros(s) called. 46 Includes added to the Cache 544 Includes found in the Cache 1 Hunk(s) created. Optimizing saved 1622 Bytes Code. 9 Optimize Passes needed. Hunk: 0 Name=`' Start:0 End:$4BDC 19420 Bytes Reloc:0 Mode:CODE Memory:PUBLIC Output : c:WHDLoad Errors: 0 Warnings: 0 Assembling Ok! No Errors found. Code type is position independent.Output file size 19456 bytes. File saved in 0.064 Seconds(301.821 KB/s). @ENDNODE @NODE copy "Copyright" WHDLoad is copyright © 1995-96 by Bert Jahn. All rights reserved. Any commercial use is only allowed with a explicit, written permission by the author. Non commercial use is free, but this "use" is limited to: duplicating the archive as a whole, executing of provided programs, reading the documentation. @ENDNODE @NODE disc "Disclaimer" THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO USE, RESULTS AND PERFORMANCE OF THE PRODUCT IS ASSUMED BY YOU AND IF THE PRODUCT SHOULD PROVE TO BE DEFECTIVE, YOU ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR OTHER REMEDIATION. UNDER NO CIRCUMSTANCES, CAN I BE HELD RESPONSIBLE FOR ANY DAMAGE CAUSED IN ANY USUAL, SPECIAL, OR ACCIDENTAL WAY OR BY THE PROGRAM PACKAGE (INCLUDING BUT NOT RESTRICTED TO: THE LOSS OF DATA OR LOSSES CAUSED BY YOU OR A THIRD PARTY OR BY USAGE OF THIS PROGRAM FOR TASKS IN OR OUTSIDE MY SPECIFIED DECLARATION OF SUITABILITY), ALSO IF THE OWNER OR A THIRD PARTY HAS BEEN POINTED AT SUCH POSSIBILITIES OF DAMAGE. @ENDNODE @NODE author The Author jah@boss.hrz.fh-zwickau.de http://www.fh-zwickau.de/~jah/whdload.html Bert Jahn Franz-Liszt-Straße 16 Rudolstadt 07407 Germany @ENDNODE