+++++++++++++++++++++++++ + + + S K I C K v 2.0 & 3.0 + + + + (C) SinSoft 1992 + + + + User's manual + + + +++++++++++++++++++++++++ Introduction. ============= SKick is the replacement for Kickit, ZKick and LKick kickers, intended for use on A500 or A2000 machines with OS2.0 in ROM (for instance A500+). Its task is to soft-kick any other version of kickstart into RAM. 'Any other' means also the 1.3 kickstart, which was unavailable to kick with any other kicker. KickIt and ZKick both require 1.3 ROM for operation and function of LKick from 2.0 isn't very stable. SKick is fully assembly-written program, with many facilities added. The main advantages of SKick are: - ability to relocate any kickstart image, when the relocation table is supplied into any kind of RAM (CHIP, FAST, EXP etc.) - standard operation (like Kickit etc.), when table is not available - patch function (patches kickstart image prior its start, which may correct known bugs etc.), using supplied patch file - powerful command line and Workbench interface - Graphic User Interface (GUI) - all operations during kicking are made so 'purely' as possible, all structures are exactly in the same state as if kicked from ROM - small code size (even if most powerful, SKick is the shortest from all the kickers) - relocation tables for new kickstart versions will be automatically available for registered users - loaded kickstart survives any 'soft crash' (without corrupting execbase or kickstart itself) and user reset - allows use of CoolCapture, romtags and memtags with user programs without any limitation 1. Copyright. ============= SKick and its documentation files are Copyright (C) SinSoft 1992, Prague, CSFR. =============================================================================== This archive may be freely redistributed, but only in totally unchanged state, i.e. no files can be added, deleted, modified etc. All copyright notices in the program and its documentation must remain on their places. Also '.displayme' and other files, usually with 'wonderful' ANSI graphics, so obvious at various BBS's, cannot be added. 2. Contents of the archive. =========================== This .LHA archive MUST contain following files: SKick - executable code of the program SKick.info - program icon SKick.doc - this file History.doc - development history - PLEASE READ FOR LATEST CHANGES directory Kickstarts: kick39110.A500.BETA.RTB *) kick39110.A500.BETA.PAT kick39106.A1200.RTB **) kick39106.A500.BETA.RTB *) kick39106.A500.BETA.PAT kick39046.A500.BETA.RTB *) kick39046.A500.BETA.PAT kick37175.A500.RTB **) kick36143.A3000.RTB ***) kick36143.A3000.PAT kick34005.A500.RTB kick34005.A500.PAT *) These kickstart versions are available only to official developers. **) Patch table not required to use these kickstarts. ***) This kickstart was available on SuperKickstart disk for A3000. Patch file makes usage of this kickstart on A500 possible. However, this 'historical' version of OS is obsolete and it is not recommended to use it. NOTE TO COMMODORE: Sorry CBM for a small law-break (I hope small) from my side: I'm not the official developer, but I have Your BETA releases on my drive: they came into Czechoslovakia from some pirate BBS in Germany and they are available from general Amiga population. I've never misused or abused them and I also keep in mind Your copyrights: I never redistribute them. But when I've got them, I wanted to help another people and do some useful work: All known kickers (they are PD, aren't they?) seemed to be imperfect in some aspects for me and then I realized to write my own kicker to meet all my needs and give it to all people which need it too. 3. System requirements. ======================= SKick may be operated, if the following requirements are met: - Computer: Amiga 500, 1000 or 2000 with 68000, '010 and '020 processors - Minimum 1 meg of RAM (possibly only Chip RAM, expansion RAM isn't needed when relocation is to be used) - Kickstart 2.0 in ROM (not tested with V36, because there are not machines with V36 ROM in Czechoslovakia, developed and tested under 37.175) Skick is designed to work on machines without MMU. I think they are better methods for kicking on >=68030. So these processors aren't supported by this version. If somebody will try it, it's possible that it will work; but this was never tested (there is no A3000/4000 in range of my action radius). That's all. When Your system meets all these requirements, You are able to use SKick. Of course, large amount of RAM (especially expansion RAM) will help You use non-relocatable kickstarts (they are located from $200000 obviously), but it is not necessary. NOTE: Because of a nature of 2.0 system, it is impossible to kick anything from address $c00000 exactly. The first usable address is $c40000. 1.3 system did allow this, 2.0 doesn't. It is because the system restart is more drastic than on 1.3 system. 4. Installation. ================ Installation of SKick and related files is very simple. Please follow instructions below: On Amiga 3000, there is the convention, that during cold start process, file 'DEVS:kickstart' is read into memory and run. To make the possibility to choose from several kickstarts, SKick searches kickstart images and related files on the directory DEVS:kickstarts. Your first step is to issue the command >Makedir DEVS:kickstarts from the Shell, so the appropriate subdirectory will be created on Your boot partition (usually hard disk). Your second step is to copy the auxiliary files (.RTB and .PAT) from this archive, if You wish to use them, and to add appropriate kickstart images. SKick can handle both 'exact ROM images' and files intended for Kickit and other kickers. When copying kickstart images, rename them with names of .RTB/PAT files, but without any extension; or, vice versa, rename auxiliary files according to the main file. All the files of one particular kickstart must have identical names (except extensions). WARNING: DO NOT USE ANY OF .RTB OR .PAT FILES FOR INAPPROPRIATE KICKSTART! IT WILL CAUSE ONLY DEEP SYSTEM CRASH!!! PLEASE REMEMBER, THAT ALMOST ANY KICKSTART RELEASE EXIST IN DIFFERENT VERSIONS FOR A500/A3000 ETC. PLEASE USE ONLY APPROPRIATE KICKSTART WITH APPROPRIATE AUXILIARY FILES. NOTE: I've discovered that some kickstarts with identical major version and revision numbers slightly differed. The only sure way how to identify correct kickstart is to check its checksum. This will be done automatically in future SKick releases. IMPORTANT NOTE: There are no kickstart images in this archive! Supplied files only allow to use standard 1.3 ROM image, which may be obtained from Commodore (one method : buy A3000 SuperKickstart disk, it also contains this, and use some disk tool or monitor to grab it from the disk into the file. Another method: Somebody will upgrade his A500 1.3 with a new 2.04 ROM. Because he bought old 1.3 ROM with his machine, it continues to be his ownership and may be used. There is no need to buy hardware add-on (ROM-Switches etc), and the contents of the old ROM may be copied into the file before replacement and then used. ('Backup copy')). There are also files for another kickstart versions. Some of them are available to the official developers only. I hope that SKick will help them to keep their work. It's only a dream for me to be an official developer... The third step is to copy SKick itself (with its icon) into any place where You wish to have it. Please read the following chapter for more explanation. 5. SKick usage ============== SKick may be called either from the Shell or from the Workbench. 5.1 Invocation from the Shell ============================= When invocating SKick from the Shell, following template should be used: NAME,ADR/K,FORCE/S,EXT/S,CHIP/S,FAST/S,NOEXT/S,NOREL/S,NOPATCH/S,QUIET/S,GUI/S There are two optional parameters and many switches. NAME ==== This parameter specifies the file name with full path of the kickstart to be loaded. If omitted, SKick will do nothing, until GUI is called either by its switch (GUI) or by pressing left mouse button during program run. NOTE: The full path must be always specified in this version of SKick when specifying the name. DEVS:kickstarts directory is not scanned automatically. This will change in future releases. ADR === ADR parameter allows You to specify the address for the relocatable kickstart to be loaded. The address must be entered in hex, and only the upper byte of the address is entered. It is also assumed always to be in 24-bit space. For example, when You wish to load Your kickstart image from $C80000, please specify Your wish with 'ADR C8' or 'ADR $C8', or possibly 'ADR $00C8'. NOTE: This option is only useful for special cases, like debugging etc. Normally, the fully automatic search for the appropriate place is performed and the best place for the kickstart is found. NOTE for users with 'kickstart RAM': A1000's or any other machines, having RAM from $F00000, allow loading into this location. In such case, the command SKick ADR F0 FORCE has to be used, as the kickstart RAM isn't normally accessed, and obviously it is not added to the free memory list. FORCE ===== This switch allows You to force load to the place, which is not normally contained on the memlist. It is designed to help when loading kickstart into non-autoconfiguring memory expansion board, which was not added to the system yet. This switch is not recommended for general use, as its incorrect use may cause drastic unpredictable results. EXT,CHIP,FAST ============= These 3 switches specify the kind of memory the free space will be searched for. Only one of them may be selected; when unspecified, all standard memory address ranges are scanned in the order of EXT, FAST and CHIP. NOEXT ===== This switch excludes external memory from being searched. Search is performed for FAST and CHIP memory only. This switch may be used, if user wants to have a big amount of memory in one large block. Normally, its use is not recommended, because the speed of kickstart will be decreased when multi-bitplane video modes are selected. NOREL ===== NOREL switch disables the relocation process even if the relocation table is present. Kickstart will be loaded exactly to the place it is assembled, if available. When the kickstart is assembled from $200000 and You have expansion RAM, there are no problems. Problems will occur when using normal ROM image from $f80000 or $fc0000, for example kickstart 1.3. In these cases, this switch cannot be used. NOPATCH ======= This flag suppresses the patch facility. Normally, when .PAT file is present for given kickstart, it will be opened and kickstart patched to correct known bugs. When this flag is used, patching is suppressed. NOTE: Some kickstarts may REQUIRE patching. For example, 39.46 Beta contains very serious bugs preventing it from being started without patching on most machines without 68020 or greater CPU. Standard 1.3 must be patched to allow more than 512K of CHIP RAM during reboot and to allow correct performing of user reset (CTRL-LA-RA). QUIET ===== The QUIET flag supresses all messages writen by the program. When started from Shell, it has the same effect like >NIL: redirection. When started from Workbench, program window is not opened. GUI === The GUI switch activates the GUI screen of the program. GUI may also be obtained by pressing the LMB during program run; this may be used when SKick is run from Startup-Sequence automatically. 5.2 Invocation from Workbench. ============================== Invocation of the program from Workbench is very simple: double-click on its icon and it will be performed. Using 'Information', You may specify all the Tool Types like from Shell. All switches are defined as FLAGS. One example: NAME=devs:kickstarts/kick39046 FLAGS=QUIET|EXT This definition automatically loads kickstart named kick39046, does relocation and patching, scans only EXT memory for the space and doesn't issue any screen output. 5.3 Suggested usage =================== SKick is designed to be called as the first command from the Startup-sequence, either with any name, or without it. When the name is present, SKick will load appropriate kickstart image, when running from ROM one. When the name is missing, SKick will do nothing and remain in ROM. HOWEVER: If the user is holding LMB during Skick's run, Skick will open its Graphic User Interface. It is the screen very similar to Boot Menu. There are all the kickstarts found in the DEVS:Kickstarts directory displayed and the user may choose any of them. The ROM kickstart is also displayed as one of them. They are sorted accordingly to their versions and revisions. There are only version and revision numbers displayed, not the names of disk files, with the remark (RAM) or (ROM). In the lower part of screen, there are 3 gadgets: Patching (ON/OFF), Load into (ANY RAM/CHIP RAM/FAST RAM/EXP RAM/NOT EXP RAM/) and Relocation (ON/OFF). These gadgets play the role of command line switches. Once the GUI is activated, the selection must be made (there is no CANCEL gadget in this version, may be in future ...). After the selection is made, selected kickstart is simply loaded, regardless of the actual system status (of course, when the currently running kickstart is selected, it is NOT reloaded). This is done in TWO steps, if necessary. Let's suppose that RAM kicstart is running, and we wish another RAM kickstart. Immediately, SKick will reset the machine to ROM and reboot it, but it remembers Your choice first. When started from startup-sequence, it ignores all its defaults and also the LMB, automatically loads required RAM kickstart and reboots again. When it is called now, it ignores its defaults, but LMB may be used to change kickstart using GUI. The new kickstart will remain active until next cold start (i.e. not reboot/reset) of the machine is performed. When some loaded kickstart is default and You wish to remain in ROM, after selecting it from the GUI Your select overrides the default. Even if rebooted, SKick will NOT load its default file and will remain in ROM. As an example, when we wish to beta-test version 39.110 for a long time, we put into startup-sequence this line as a first command: SKick devs:kickstarts/kick39046 QUIET This will start 39.046 kickstart immediately after system power-up. When we wish to remain in ROM or to use another kickstart, for example 34.005, it is necessary to hold LMB during boot (if we boot from HD it is only 2-3 sec after Boot Menu), and to select our choice. Until next cold start (power down, double-reset as explained below or very hard crash), the selection will remain active and SKick will not be doing anything. It is a good idea, to put the SKick icon also in some place to change kickstart, when the system is fully up and running. Suggested setting is to use the GUI switch, which will bring the menu screen automatically and in every case. NOTE: When in the Startup-sequence, in the SKick command, the name is used (i.e. some RAM kickstart is selected as a default), it is necessary to put some name to the icon too, even if any name is overriden with our choice. It is necessary because the Skick called from Workbench must know the conditions, which have its 'college' from startup-sequence. So the suggested setting for Workbench is: NAME=DUMMY (or anything else) FLAGS=GUI or only the second line if the default kickstart is ROM (no name given in startup-sequence) or the SKick command is not used in it. NOTE: The name of kickstart file is limited in length. Maximal length correctly processed by SKick is 32 characters. It is the length WITHOUT the path, only pure filename. Please accept this limitation. Longer names cause malfunction (not crash) of SKick. To force the machine to return to the ROM kickstart, very simple operation may be used. The user simply hits the reset combination (Ctrl-LeftAmiga- RightAmiga). The display will disappear from the screen. After some time from releasing reset buttons, the screen color will change to 'medium gray' (it is the FIRST color change from many others). ALso the power LED will shine fully from this moment. This is the exact time to hit the reset combination once again. Now, any reset-resistant things (all captures, memtags, romtags etc.) are off and system is performing cold start. I think that there is no need for a special program (like KillZKick), because this operation is handy and easy. 6. Theory of operation ====================== This chapter will be included only in the developer's package. 7. Troubleshooting ================== Symptom Cause Solution --------------------------------------------------------------------------- Error message from According to the According to the message SKick is displayed message Power LED blinks Many... Try a different kickstart to after kicking find the problem Kickstart does not ColdCapture Do not use programs modifying survives reboot changed, ExecBase ColdCapture and corrupting corrupted system areas Kickstart does not Crash too deep Don't crash :-) survives crash (ExecBase destroyed) Power LED blinks Kickstart checksum Possibly after a crash. repeatedly, RED failed (image Don't modify running images! screen patched/destroyed) Any other I don't know Ask me for a solution, if You can't find any (use E-mail). 8. File structures ================== 8.1 .RTB file .RTB file consist of two parts. The first part contains all the relocation offsets compressed by my own simple algorithm. It is created with a special program called RTG (relocation table generator) from specially pre-processed kickstart image. How to get this image, it is my magic and I'll never tell anybody about it. One note only: generation of 39.046 .RTB took 1 1/2 hours. (Manual work, + about 10 mins my 7MHz '010 CPU time). Second part contains BCPL relocation table and it is required for 1.3 ROM only. It was created manually, analysing dos.library, which is written in BCPL in 1.3. .RTB file is not easy to create. I don't recommend anybody to try it *without* very good knowledge of assembly language and machine code (not the same). N.B. Auxiliary tools to do such work took 1 month to develop. 8.2 .PAT file Patch file has a very simple structure. It contains pairs of longs. Every pair represents an offset from kickstart beginning (first long) and the value to patch (the second one). Bytes and words cannot be patched individually, every patch must be coded as a long, even with 3 bytes identical with original. When a longer patch is to be coded, it must be coded as a sequence of these simple patches. This stupid mechanism will be improved in next release. There is no order specified, because every patch has its own, fully coded offset. It allows simple addition of new patches to the existing file. Patch file must be ended with two longs of zeros. From revision 3.12, there may be also relocative patches coded. They differ from a standard patch by the most significant bit of offset, which is set to 1. In this case, current loading address is added to the patch value before storing it. This feature is needed for 39.110 patch. For example, to code JMP start+$7F900 patch to the address start+$100, where start is the current loa- ding address, use the sequence 000000fe XXXX4ef9 80000102 0007f900, where XXXX is original contents of ROM at address start+$fe. N.B. To create patch file, I'm using this algorithm: 1) First, I patch new values directly into the kickstart with a debugger. 2) I load another copy of kickstart into memory (my 6Megs allow this) 3) I write simple program to generate the patch file directly with debugger's assembler (I'm using Mon 1.55 by Timo Rossi, which seems to be the most powerful PD debugger known to me). This program is so simple so I never save it. 4) I save (with the debugger) the table to the disk. 9. Final words... ================= This program, its documentation and all other files contained in this archive, are (C) Copyright Pavel Troller, Jagellonska 16, 13000 Praha 3, Czechoslovakia. This package is provided as is, any warranties cannot be applied. Any usage of this program or other parts of this archive, will be done at Your own risk! If You have any suggestions, questions, criticisms or flames please feel free to write me. I'm sorry for the fact I'm very busy and I cannot reply by any other form than E-mail. Also updates, new .RTB and .PAT files may be sent only via elec- tronic media. Don't send disks, I will never return them!!! My email address is: Internet: PATROL@ACI.CVUT.CS BITNET: PATROL@CSPUNI12.BITNET And... Please excuse me for my very broken English. We learned English for many years, but practice is missing...