Installer v2.02 - Developers' Toolkit ===================================== (c) Garry Lancaster, 2000 Introduction ------------ This file explains how to create .APP files that can be used with your own applications to load into Installer v1.07 and higher. It also gives more technical details on the new features provided with Installer v2.02. Files included in the Installer Toolkit are: toolkit.txt This file appmaker.bas BASIC program to create .APP files showtrace.bas BASIC program to show results of the call-tracing facility PART ONE: Creating installable applications =========================================== Application files ----------------- There are three types of files used by Installer: the application information file (extension .APP), the uninstall information file (extension .APU) and the binary images of the application's banks (extensions from .AP0 to .AP7). Full details of the structure of the .APP and .APU files are given later; for now we will concentrate on how to create the files themselves. The bank image files are the easiest to create. Each file contains a binary image of the appropriate bank. Bank 63 ($3F) is held in the file with extension .AP0, bank 62 in .AP1 etc, up to file .AP7 which contains bank 56 ($38). At their simplest, these files are 16K images of the bank contents. However, if you do not use the entire bank, then any contigious area can be used, as the offset from the bank start and the length of the area are specified in the .APP file. This saves space, and is also extremely helpful during development work; you can simply re-assemble your application and rename the .BIN file to .AP0 (or whatever), and you're ready to re-install it! APPmaker -------- This BASIC program provides a quick and easy way to create .APP files for your applications. You simply run this program, enter the name of your application (without an extension) and fill in the details required. After entering the number of banks in your application, and entering zero for the number of patches, you are asked for the first DOR address and bank. If you have included a ROM Front DOR in your top bank image, it is not necessary to specify this. The next question is "Even bank flags?". Enter through this unless any of your application's banks will be bound to segment 0, thus requiring to be located in an even bank. If any are, calculate the byte value by setting a bit for each file requiring an even bank. For example, if the .AP1 and .AP2 files need even banks, set bits 1 and 2, giving a value of 2+4=6. Next you are asked for the offest and length of each bank image. Simply press ENTER through these if you are using full 16K images. Patches ------- A facility is also included for Installer to patch application files; this is provided so that applications written to run in specific bank configurations (and not using the generic $3F-based notation) can be modified for installation in RAM. Naturally, you will not need to use this for your own applications! For each patch, you enter the bank and offset of the byte to be patched. The value to be patched in can be either an absolute value (0-255), a bank value (converted on installation from a $3F based value to an absolute bank number), or both (ie a bank value plus an absolute value). Structure of .APP files ----------------------- All .APP files are at least 40 bytes long, with patched files containing an extra 6 bytes per patch. Bytes Use ----- --- 0-1 File identifier ($5AA5) 2 Number of banks (1-8) 3 Number of patches (1-255) 4-6 Pointer to first DOR (if 0,0,0 then ROM Front DOR used) 7 Flags for required even banks 8-9 Offset of .AP0 file 10-11 Length of .AP0 file 12-13 Offset of .AP1 file 14-15 Length of .AP1 file 16-17 Offset of .AP2 file 18-19 Length of .AP2 file 20-21 Offset of .AP3 file 22-23 Length of .AP3 file 24-25 Offset of .AP4 file 26-27 Length of .AP4 file 28-29 Offset of .AP5 file 30-31 Length of .AP5 file 32-33 Offset of .AP6 file 34-35 Length of .AP6 file 36-37 Offset of .AP7 file 38-39 Length of .AP7 file Then, optionally for each patch: 0 Bank 1-2 Offset 3 Flags: bit 0=use absolute value, bit 1=use bank value 4 Absolute value 5 Bank value Structure of .APU files ----------------------- All .APU files are 40 bytes long. Bytes Use ----- --- 0-1 File identifier ($4BB4) 2 Slot application is installed in (1-3) 3 Number of banks used (1-8) 4-11 Absolute bank numbers, relative to slot start 12-39 unused Known Issues ------------ I have only come across one problem using Installer so far. This occurs when uninstalling the Assembler Workbench application (a 128K image); after doing this, attempting to enter an application like Diary or PipeDream causes the menu to appear, but then the Z88 freezes. A soft reset then seems to clear the current RAM slot of all files. This problem does not occur with any other applications I have tried (none of them being 128K, though), nor if you install and uninstall the Workbench in the same session of Installer. This leads me to believe that the problem is not with Installer itself, but with OZ. Any further information on this problem (particularly under what other circumstances it occurs) would be gratefully received. In the meantime, please test all applications for this issue, before releasing them to the outside world! PART TWO: Installer v2.02 Advanced Features =========================================== Introduction ------------ With v2.02, many new features have been introduced into Installer (and its companion, Bootstrap), most of a rather technical nature and of little interest to the casual user. Therefore, descriptions of most of the new commands have been moved to this file. To fully understand this documentation, you will need a knowledge of the Packages system; full details of this can be found on the Z88 Forever! website. Package Handling ---------------- Three new menu options have been added to assist in the handling of packages: "List packages", "Deregister packages" and "Register all packages". List packages ------------- This option does exactly what it says, showing details of all the packages that have been installed, in the following format, with the built-in Packages package as an example: ID Name & version [slot]: bytes / handles / package resources $0F Packages v1.11 [2]: 512 / 1 / 0 In this example, the ID of the package (as specified in the programmers' documentation) is listed together with the name and version, followed by the slot number that the package is installed in (slot 2, in this case). After this are the resources used by the package: 512 bytes and 1 OZ handle in this case. The third value shows the resources allocated by this package to other applications & packages; the documentation for each package gives a more precise definition for this, and it may be unused (as in the case of "Packages"). If a package was present on a card which has been removed from the Z88, the list will display only the ID number of the package, together with a message indicating which slot it was removed from. Deregister packages ------------------- This option will uninstall any packages that it can. It's essential to do this before uninstalling RAM applications from the same slot, and also useful to determine whether a particular package is in use by any application or not. The built-in "Packages" package can never be deregistered. Register all packages --------------------- Finally, this option will search the Z88 for all available packages and register them if possible. You can "deregister packages" and then use this option to ensure that the most up-to-date version of each package present in the Z88 is installed. Special Features ---------------- The "Feature info" option shows which of the special features provided by Installer and Bootstrap are currently enabled. It also indicates how many interrupts have been registered by packages and processes (a maximum of 5 can be installed at any time). You can turn off or re-enable both OZ call substitution & interrupt chain handling by using the appropriate commands. This is not recommended for normal use, but is provided to make debugging applications using these features slightly less fraught... Call Tracing ------------ This feature allows you to determine exactly which calls are being processed by the Z88, by logging them to a file (:ram.-/oztrace.dat) which can later be interrogated by the showtrace.bas BASIC program. Several things should be noted here: * Only calls made with the CALL_OZ macro will be logged; specifically, CALL_FP & CALL_PKG calls will *not* be traced, and neither will the special calls OZ_DI, OZ_EI and OZ_BUFF * The :ram.-/oztrace.dat file will grow at an alarming rate, so don't leave tracing enabled for very long * Only top-level calls (made by the application itself, not sub-calls which might be used in the process of performing the main call) are logged * The exception to the above is in the error-handling system, so you will notice a lot of GN_ESP calls You can trace either the entire Z88 (regardless of application), or a single application process. Popdowns can't be traced as a single process, as its necessary to pre-empt the process to turn tracing on; however, you can do a global trace which will include activity from all popdowns you use. To trace all OZ call activity, enter Installer and use the <>TRALL command. Turn off tracing again later with the <>TROFF command. To trace a single application process, enter the application you want to trace, then enter Installer directly with the shortcut key (ie []ZI) and use the <>TRONE option. The name of the process being traced (the name from the "Your Ref" column in the Index) will be displayed. Turn off tracing again later with the <>TROFF command. The ShowTrace Program --------------------- After tracing, you can display the results using the supplied showtrace.bas program. This is very simple to use, and displays each OZ call that was performed together with the address of the call within your application, and the entry parameters (all the main registers). The program is designed to output the details to a text file (captured with []+S) so it doesn't pause during display; you can do this by pressing any key to stop the display, and then press SPACE to continue again. History ======= v2.02 Second public release, with Packages v1.11. When installing rst8 code, also ensures handler code uptodate. v2.01 Uninstall can't produce huge ROM sizes anymore. Purge now zeroises front DOR. Uninstall/purge now don't occur if packages active in slot. v2.00 Version change v1.15 Added SlowMo facility. Register all packages command added. v1.14 More minor alterations v1.13 Minor alterations v1.12 More bugfixes v1.11 Bugfixes v1.10 Added feature list to the menu. Now displaying process reference for traced process. v1.09 Initial support for tracing, call substitution & interrupt chains. v1.08 Added package-handling facilities, with List & deregister options. Automatically installs package-handling if required. No longer exits on every error message. v1.07 First public release. Added reserved bank facility, and option to force selection of even banks. v1.06 Added check for active applications before uninstalling. v1.05 Menu front-end implemented. Protection after resets delegated to Bootstrap (v1.01) v1.04 Can now install applications up to 128K (from 32K). v1.03 Uninstall all & extra validation routines added. v1.02 Bugfix: protection after reset wasn't working. v1.01 Bugfixes. Patches & small images now catered for. v1.00 First version. Comments ======== If you need further information or have any other comments or suggestions, please contact me via the Z88 Forever! website. Garry Lancaster, 13th March 2000