DynamiCache =========== An intelligent disk-cache for the Commodore Amiga. Copyright 1992, 1993 - Christopher A. Wolf All Rights Reserved. Programmed & Designed by: --------------------------- Christopher A. Wolf Beta-Testing & Suggestions by: -------------------------------- Rudy Amid, Henrik Andersson, Bill Coldwell, John Davis, Aaron Digulla, Kenneth Dyke, Scott Ellis, Dale Gold, Justin Lister, Holger Lubitz, Jukka Marin, Urban Mueller, Dean Ridgway, Chris Schneider, Ralph Schmidt, Mike Schwartz, Michaels Smith, Shachar Shemesh, Urban Mueller, Markus Wild FixDev code routines by: -------------------------- Shachar Shemesh Chapter I: An Introduction to DynamiCache ========================================= DynamiCache is an intelligent disk-caching program for the Amiga. DynamiCache's sophisticated caching algorithms provide a 500% to 1000% increase in the speed of most disk operations! DynamiCache's high levels of performance, configurability and ease of use are unmatched by any other disk-caching product available for the Amiga. A. Feature List --------------- A partial list of DynamiCache's features include: o DynamiCache is compatible with almost all Amiga drive types including floppy disks, hard disks, flopticals, removable cartridges (Syquest, Ricoh, Bernoulli, etc.), CD-ROMs, etc. o DynamiCache is compatible with a wide range of SCSI, SCSI-II, and IDE controllers and has been tested with controllers from Commodore, GVP, Supra, IVS, ICD and Xetec. o DynamiCache is compatible with all AmigaDos file-systems including OFS, FFS, and DCFS. DynamiCache also works with disks or partitions formatted with CrossDos or other non AmigaDos formats which use the standard device interface. o DynamiCache implements a sophisticated set-associative, line-oriented, write-through cache architecture and a least-recently-used replacement algorithm to assure maximum cache efficiency. Intelligent read-ahead techniques are used to significantly enhance performance even the very first time data is accessed. A special track-read mode is provided to give highly optimized caching performance for floppy disks. o DynamiCache features unique dynamic cache re-sizing code which automatically and continually adjusts the disk cache to use all the available memory which is not currently needed by other programs. Dynamic cache re-sizing provides the maximum effective utilization of your memory by transparently allowing memory to be dynamically shared between applications and the cache as necessary. This eliminates the need to set aside a large block of dedicated cache memory and provides superior disk performance without significantly reducing the amount of memory available to your applications! o DynamiCache can cache an unlimited number of devices (of any mixture of types) simultaneously. Caching can be enabled or disabled independently for each device in the system or even for individual hard-disk partitions. Each device or partition can have its own unique settings for attributes such as the amount of read-ahead. o DynamiCache provides an intuitive graphical user interface which allows easy adjustment of all cache parameters. The GUI is compliant with the 2.0 Style Guide and is font-sensitive. o The user's preferred cache configurations can be saved, retrieved or specified as the default to be used automatically at start-up. Intelligent defaults are provided for all cache configuration options to get the novice user up and running quickly but complete control by the advanced user is still possible. o DynamiCache provides real-time reporting of a variety of important global and per-device statistics such as current cache configuration, memory usage, number of disk accesses, number of cache hits, and cache hit ratio. o DynamiCache provides many other advanced features which make it the leader in cache technology for the Amiga. B. System Requirements & Compatibility: --------------------------------------- DynamiCache should function on any Amiga model computer running AmigaOS version 2.04 or higher. DynamiCache will work with a minimum of 1 megabyte of available RAM (CHIP or FAST) however 2 megabytes of FAST RAM is recommended. DynamiCache will take full advantage of expanded systems with faster processors, additional memory or higher OS versions. (DynamiCache has been tested under OS versions up to 3.0.) DynamiCache is compatible with any block-oriented random access storage device which uses the standard AmigaOS device interface. This includes almost any device which can be attached through your SCSI, IDE or floppy disk drive controllers. DynamiCache has been tested with SCSI controllers from Commodore, GVP, IVS, ICD, Supra and Xetec, IDE controllers from Commodore and ICD. DynamiCache cannot be used to cache streaming-tape or other sequential access storage devices or remotely-mounted network devices such as PARNET: or NFS: devices. Although extensive testing has been done, compatibility with specific drives and or controllers cannot be guaranteed. If you have doubts about the compatibility or functionality of DynamiCache in your specific system environment please look for the freely redistributable DynamiCache demo. This demo should be available through most standard PD distribution channels (User Groups, BBS, internet ftp) and will allow you to test the functionality of DynamiCache on your system. Chapter II: DynamiCache Tutorial ================================ This tutorial chapter of the manual will teach you how to install and configure DynamiCache for use on a typical system. For a more in-depth description of all the advanced features and options available to you please consult the Reference section of this manual (Chapter III). For an explanation of error messages and trouble shooting advice please consult Chapter IV. Also, check for the presence of a file titled README on the distribution disk. This file will contain any info on last minute corrections or updates that could not be included in the printed manual. This tutorial assumes that you already familiar with using the principle elements of the Amiga Workbench interface such as icons, menus, gadgets and the mouse. For remedial help on using the Amiga Workbench interface please consult the manuals which came with your computer. A. Installing DynamiCache ------------------------- Installing DynamiCache is simple - just drag the DynamiCache program icon from the distribution disk into the destination drawer. If you want DynamiCache to automatically start up every time you boot your computer, drag the DynamiCache program icon into the WBStartup drawer on your boot-disk. To start DynamiCache manually from the Workbench simply double-click on its program icon. This will bring up DynamiCache's main configuration window. You may only run one copy of DynamiCache at a time - if you attempt to start multiple copies of DynamiCache a window informing you that you can only run one copy will open and the first copy's configuration window will be popped to the front of the screen. B. Configuring the Cache ------------------------ Now that the configuration window is open you have access to a variety of gadgets which allow you to set various cache parameters. It is important to realize that whenever you use the gadgets to change the cache configuration the changes do NOT take effect until you click on the Use or Save buttons along the bottom of the configuration window! Do not click on Use or Save until all the gadgets have been set to specify the cache configuration that you wish to have installed. If while following this tutorial you get confused or wish to undo the changes you made you can reset the gadgets to their default state by choosing the Reset to Defaults option from the Edit menu. In the upper left corner of the DynamiCache configuration window you will see a recessed box with two gadgets above it labelled Cache Statistics. This area of the window is used for monitoring cache performance and should currently indicate that the cache is not activated. Below the cache statistics display is a bank of three cycle gadgets labelled Purge Scheme, Minimum Size and Maximum Size, located in the lower left quadrant of the window. These gadgets control global cache attributes. DynamiCache analyzes your system on start-up and automatically initializes these gadgets to reasonable defaults, thus it is not necessary to alter any of these settings at this time. Consult Chapter III, the reference section of this manual, for a complete explanation of their function of these gadgets. In the upper right corner of the DynamiCache configuration window is a standard scrolling list gadget displaying the names of all the devices in the system which DynamiCache recognizes as cachable devices. Next to the name of each device is the word enabled or disabled indicating if caching should be used with each device. To toggle the status of a device between cache enabled and cache disabled double-click on the device's name in the scrolling list. You can use DynamiCache with an unlimited number of devices simultaneously. However, each device which cache is enabled for must exist as a real physical drive attached to the computer - DynamiCache is not capable of caching remotely mounted network partitions or other "fake" drives (such as fake floppies created with Matt Dillon's freely-distributable FMS program) which do not physically exist on the system running DynamiCache. DynamiCache does its best to filter out uncachable devices from the list but if any such devices should appear on the list you must not enable cache for them or unpredictable behavior may occur. Each device that is selected as cachable has certain attributes associated with it which apply only to that specific device. To change the attributes of a specific device click ONCE with the left mouse button on the name of that device in the scrolling list. Under AmigaOS version 2.04 the name of the currently selected device will be displayed in a box underneath the scrolling list. Under AmigaOS version 3.0 or higher the name of the currently selected device will be highlighted. Once a device is selected the three cycle gadgets underneath the scrolling list, labelled Device Type, Read Ahead and Write cache, will change to display the attributes of the currently selected device. Remember that these gadgets always reflect the status of the device whose name is currently selected in the scrolling device list. The Device Type gadget has three choices - Hard Drive, Floppy and Removable. To ensure data integrity it is important that this attribute be set correctly for each device - DynamiCache makes a best guess about the device type for each entry but please make sure it is correct. If the device is a standard Amiga floppy this gadget should be set to Floppy. If the device uses any sort of removable media (i.e. Syquest drives, flopticals, Bernoullis etc.) the gadget should be set to Removable. Otherwise the gadget should be set to Hard Drive. Note that setting the gadget to removable may cause alterations in the device list - because of OS limitations DynamiCache cannot recognize multiple partitions on a single removable partition. Thus the name of a removable partition will be changed to reflect the driver name and unit number in use for that unit and the names of the individual partitions will be removed from the device list. Normal partition names will be restored if the setting for that device is set back to Hard-Disk. During normal disk usage patterns data is accessed in a sequential manner and performance can be improved by anticipating this and pre-fetching sequential blocks of data. The Read Ahead gadget determines how much data DynamiCache will read-ahead or pre-fetch on each access to the currently selected device. For floppy-disks this should be set to Track-Mode which makes most efficient use of the floppy disk hardware design to read entire tracks of data at one time. For removable or hard-disks Read-Ahead should NOT be set to track-mode. A good default value for Read-Ahead on removable or hard-disks is 8 Sectors although you may want to decrease this value if the partition is highly fragmented or if you do a lot of random accesses (seeks or directories for ex.) to the partition. You may want to increase this value if you do mostly sequential accesses (copies or reads for ex.) or if you have a very fast hard disk. The Write-Cache cycle gadget determines if Write-Thru caching is used or if write caching is disabled for the currently selected device. If Write-Thru caching is enabled data that is being written to disk will be copied into the cache as it is written. This will slow down writes somewhat but will greatly speed up subsequent accesses to this data since it is already in the cache. There is never any threat to the integrity of your data since write accesses are NOT delayed. Write Cache disabled will just perform a normal write - the write will not be slowed down any but if the data is subsequently accessed it will have to be re-read from disk. Write-Through caching has one other drawback - if a program writes data to disk and then attempts to verify it by reading it back the verify attempt will not be conclusive since it reflects the data in the cache and NOT necessarily the data written to disk. This appkies only to programs doing their own data verification and does not apply to the verify pass that occurs during disk formatting. DynamiCache takes special steps during disk formatting to insure that the verify accurately reflects the actual data written to the disk. Using the above information, go through and adjust the settings for EACH device that you want to cache. Once all settings are set to your satisfaction click the Use button to install the cache without saving the configuration, or click the Save button to install the cache and save the configuration. The default location to save settings files to is envarc:DynamiCache/DynamiCache.prefs. These settings will be reloaded next time you start DynamiCache or can be retrieved using the Open menu item in the Project menu. If you want to save the settings in a location other than the default you can use the Project/Save As menu item. To change the location where DynamiCache looks for default settings see the SETTINGS keyword entry in the CLI/WB parameters section of this documentation. C. Monitoring/Tuning the Cache ------------------------------ If the new cache configuration was installed without encountering any problems the DynamiCache configuration window will shrink to roughly one quarter of its former size - just large enough to display the cache statistics box and its control gadgets. The cycle gadget above and slightly to the left of the statistics display box can be used to cycle between displaying global statistics (a summary of the statistics for all devices) and displaying statistics for each individual devices. In global mode, the first line of the statistics display shows how much memory (in kilobytes) DynamiCache currently has allocated for caching. The next two lines indicate the total number of disk accesses made since the cache was started and the number of accesses where the information was already in the cache (cache hits). The final line indicates the cache hit ratio which is an indication of the general efficiency of the cache. In device specific mode all info in the statistics display relates only to the name of the device displayed in the cycle gadget above the display. The first line of the display indicates the cache parameters that are active for that device including drive type (HD = hard drive, FD = floppy drive, RD = removable drive), read ahead type (either a number of sectors or TM to indicate Track-Mode), and write cache mode (WT to indicate write-through). The next three lines indicate number of accesses, number of cache hits, and hit-ratio for that specific drive. These numbers can be used to fine tune performance on individual drives. Adjusting the read-ahead size for a specific drive can make a big difference in the cache-hit ratio for that drive. Typical hit-ratios for a drive with correctly set parameters should range from 40 - 60%. If you are getting lower ratios than that try adjusting the read-ahead setting for that drive - experimentation is the best way to achieve optimal results. Remember that changes made to the device attributes such as read-ahead mode will not take effect until Use is clicked. You can always see what cache parameters are currently active for a specific device by checking the statistics display for that device. The one remaining gadget that hasn't been explained is the Flush gadget located above and slightly to the right of the statistics display box. If Flush is pressed while the statistics display is in global mode all data that is in the cache is flushed and the global statistics display is reset. If Flush is pressed while the statistics display is displaying info for a specific device any data in the cache for that device only is flushed and the statistics for that device only are reset. This is useful if you are experimenting with different settings and wish to flush the old cache data from memory to get unbiased statistics about the performance of the device using the new cache settings. To toggle the DynamiCache window between its small statistics reporting size and its large cache configuration size use the standard Workbench zoom gadget in the window title bar. You can also close the DynamiCache window without removing the cache from the system - simply click the close gadget. To re-open the DynamiCache window you have three options: double-click on the DynamiCache program icon, use the commodities exchange program, or use the DynamiCache hotkey. The current DynamiCache hotkey is shown in the window title bar and defaults to ALT ESC. Since the close gadget only closes the window, when you really want to remove DynamiCache entirely you must use the Quit item on the Project menu or use the Remove function from Commodities Exchange. For more information about any of the options discussed here, configuring DynamiCache's defaults via command line or tool-type parameters, using the menu items or using the Commodities Exchange interface please consult the appropriate sections in the Reference portion of this manual (Chapter III). If you encountered any error messages or had problems while following the above instructions consult Chapter IV for an explanation of error messages and for trouble-shooting tips. Chapter III: DynamiCache Reference Manual ========================================= This section of the manual provides in-depth details about each aspect of DynamiCache and its functions. The info is grouped into sections about the DynamiCache GUI (window, menus, gadgets), DynamiCache start-up parameters (Workbench and CLI), and the commodities exchange options. A. Window Operations -------------------- The DynamiCache window always opens on the Workbench screen. It uses the system default non-proportional font for all text and gadgets are sized accordingly. The DynamiCache window can be in one of three different states - closed, open in small statistics mode, or open in large configuration mode. The state of the DynamiCache window is independent of the status of the DynamiCache cache installation. Clicking the window close gadget will remove the DynamiCache window from the display but will not deactivate or remove the cache itself. The window can be reopened by use of the DynamiCache hotkey (displayed in the window title bar), via commodities exchange, or by running a second copy of DynamiCache. The only effect of running DynamiCache a second time is to pop open and to the front the window belonging to the FIRST running copy of DynamiCache. Clicking the window zoom gadget toggles between the small (statistics) and large (configuration) window. Default behavior is for the window to automatically zoom to its small (statistics) state after Save, Use or Cancel were pressed in the larger configuration window. This behavior can be changed via the CLOSEAFTERUSE start-up parameter. The default window state that DynamiCache starts up in can also be controlled by the CX_POPUP start-up parameter. See the section on start-up parameters for more information. DynamiCache remembers the position of both the small and large windows when a cache configuration is saved. Loading a previously saved cache configuration will cause DynamiCache to use those positional settings when opening its windows. B. Menu Operations ------------------ DynamiCache's menus are accessible from either the statistics or the configuration window. Menu items in this section are listed in the format "menu name/item name." Project/Open: Brings up a standard ASL file-requester to allow the user to select the name of a settings file to load a configuration from. The gadgets are updated to reflect the new settings but the new cache configuration is not installed. Project/Save: Installs a new cache configuration according to the current gadget settings and if the configuration is valid saves the settings to disk. The filename the settings are saved under is the same as the filename of the file that the settings were read from or the default filename specified in the SETTINGS start-up parameter is used if the settings were not loaded from anyplace. If no SETTINGS start-up parameter was specified the default location is envarc:DynamiCache/Dynamicache.prefs. A second copy of the configuration file is also always save to env:DynamiCache/DynamiCache.prefs. Project/Save As: Performs the same behavior as Save item described above except brings up a standard ASL file-requester to let the user select the file path and name which the settings should be saved as. Project/About: Brings up a requester showing information about the DynamiCache revision number, the author and the beta-testers. Click OK to make the requester disappear. Project/Quit: First prompts the user with a requester and if the action is confirmed removes any currently installed DynamiCache configuration and exits the program. Edit/Reset to Defaults: Resets all gadgets to intelligent default settings depending on the user's system configuration. By default caching will be disabled on all devices and device specific parameters for each device will be set to generic parameters which should give acceptable performance under most situations. Although the gadgets are reset the actual cache configuration currently in use (if any) is not changed. Edit/Last Saved: If possible, resets all gadgets to the state they were in when the cache configuration was last Saved or Used. DynamiCache window is set to its small statistics display state unless this behavior has been altered via the CLOSEAFTERUSE start-up parameter. Cache/Activate: Installs a new cache configuration using the attributes specified by the current gadget settings. Cache/Flush: Resets the global statistics and flushes all data currently in the cache. Cache/Inactivate: Removes the current cache configuration from the system. All wedges into system devices are removed and all memory used by the cache is freed. The DynamiCache window is not closed. C. Gadget Operations -------------------- DynamiCache's gadgets consist of a variety of standard Intuition gadget types. Most of the gadgets are only visible in the large configuration window but not in the small statistics window. Most gadgets have keyboard equivalents which are indicated by an underscored letter in the gadget name in the window or in parenthesis following the gadget name in the following text. Gadget keyboard equivalents are activated by pressing the appropriate key without any qualifiers while the window is active. Keyboard equivalents are only active when their corresponding gadget is active and un-ghosted. On cycle or listview gadgets using the keyboard equivalent shifted and unshifted has different behavior. Unshifted key presses cause the gadget to cycle forward through its choices while shifted key presses cause the gadget to cycle in the reverse order. Minimum Cache Size (m/M): Controls the amount of dedicated cache memory that DynamiCache will allocate. Cache memory is divided into two types - dedicated and dynamic. Dedicated memory must be available to DynamiCache at cache initialization time and once allocated is never released. Once DynamiCache is started dedicated cache memory will not be available for use by any other program. A good guideline is that dedicated cache memory should be about equal to about 1/4th the amount of RAM that is normally free in your system while your system is under typical load. Upon start-up DynamiCache will attempt to adjust this gadget to what it considers a reasonable setting for your system - feel free to change it if you disagree. See also the entry for Maximum Cache size. Maximum Cache Size (x/X): Controls the maximum amount of memory - including both dedicated and dynamic cache memory that DynamiCache will allocate. Dynamic cache memory is memory that DynamiCache allocates as needed while running. If DynamiCache cannot allocate additional dynamic cache memory no error will occur - DynamiCache will just reuse existing cache memory. Dynamic cache memory will automatically be released if the memory is needed by another program. Since dynamic cache memory can be shared with other programs and transparently appears as "free" memory to them there is no real reason to limit the maximum cache size and it is strongly suggested that for best performance this gadget be left at its default setting of "All"! On systems with both FAST RAM and CHIP RAM DynamiCache will only use FAST RAM for both its dedicated and dynamic allocations. On systems with only CHIP RAM DynamiCache will use CHIP RAM. Special note: Some programs such as AdPro attempt to allocate almost all available memory when they are run. Since dynamic cache memory appears as available memory to applications it will be consumed by AdPro and will no longer be available for caching while AdPro is running. The dedicated cache memory specified by Minimum Cache Size does not appear as free and thus will not be available for consumption by AdPro. Frequent AdPro users who wish to preserve a larger cache size while AdPro is running may want to consider increasing their Minimum Cache Size. See also the entry for Minimum Cache size. Purge Scheme (p/P): Controls the algorithm which DynamiCache uses to transparently free up dynamically allocated cache memory for use by other applications when they require it. If LRU (Least Recently Used) is selected DynamiCache analyzes the cache contents and reduces cache size by discarding the least recently used data. If Random is selected DynamiCache reduces cache size indiscriminately without analyzing cache contents. The LRU option results in more efficient caching since useful data is less likely to be discarded. However this algorithm requires more processor time to execute and may noticeably slow down 68000 based systems or systems with only CHIP RAM. Thus if you have a 68000 or CHIP RAM only system it is suggested that the Purge Scheme gadget be set to Random. If you have a 68020 CPU or higher in your system it is suggested that the Purge Scheme gadget be set to LRU. (Note: DynamiCache always uses a Least Recently Used algorithm when replacing old cache date with new cache data during normal operation. This gadget only controls DynamiCache's purge behavior when it is necessary to reduce the total size of the cache.) Use: Installs a new cache configuration using the attributes specified by the current gadget settings. Same behavior as selecting Activate from the Cache menu. Save: Installs and then saves the current cache configuration. Same behavior as selecting Save from the project menu. See the entry for that menu item for more details. Cancel: Aborts the current editing session without installing or saving any new cache configuration. Depending on the presence or absence of the CLOSEAFTERUSE startup parameter Cancel will either cause the window to shrink to its small statistics display size (as if the zoom gadget was pressed) or cause the window to close (as if the close gadget was pressed). Cache Statistics (s/S): This gadget is a cycle gadget located immediately above the recessed statistics display box and controls what information will appear in that box. If this gadget is set to Global composite summary statistics about the amount of memory used, number of cache accesses total, number of cache hits total, and total hit ratio will be displayed. If this gadget is set to the name of a device statistics pertaining only to that device will be shown. The currently in-use parameters and the number of accesses, number of hits and hit ratio for that specific device will be shown. For help in interpreting the meaning of the various information shown by the statistics display please refer to Chapter III, Section D: Statistics Display. Flush (f): This gadget behaves differently depending on whether the cache statistics display is in global or device specific mode. If the display is in Global mode all data is flushed from the cache and global statistics are reset. If the display is in device specific mode only data belonging to the selected device is flushed and only the statistics for that device are reset. Device List (d/D/e): This listview gadget in the upper right quadrant displays all the cachable devices that DynamiCache finds in the system. The listview attempts to filter out devices such as network mounted partitions which are not cachable but is not always successful. The device list is updated periodically to reflect newly mounted devices. Double clicking on an entry in the device list will toggle the enabled/disabled setting of that device as indicated by the word "enabled" or "disabled" appearing next to the device name. A double click will also perform all the actions of a single click as described in the next paragraph. Pressing the keyboard equivalent "e" will also toggle the enabled status of the currently selected device as if that device had been double clicked on. Single clicking on an entry selects that entry. Under AmigaOS 2.04 the name of the selected entry will be copied into the display box beneath the scrolling list. Under AmigaOS 3.0 the name of the selected entry will be highlighted. When an entry is selected the settings for the Device Type, Read Ahead and Write Cache entries will be updated to reflect the settings associated with the selected device. Device Type (t/T): This cycle gadget is used to indicate what type of device the currently selected entry in the Device List is. Hard-Drive is the default setting and must be used to indicate that the device is a partition on a standard non-removable hard-disk. Floppy is the setting which must be used for floppy disk drives. DynamiCache is smart enough to recognize floppy drives which use trackdisk.device and will automatically set this gadget for those drives. However, you will need to set this manually for floppy-disk type devices which use a device other than trackdisk.device. Removable is the setting which must be used for all removable media drives (except floppy drives) such as CD-ROMs, Syquest 44mb or 88mb cartridge drives, Bernoulli-drives, Magneto-Optical cartridge drives etc. Because of the nature of removable media it is not possible for DynamiCache to cache individual partitions on removable media - caching must be enabled and cache parameters set for the drive as a whole. Thus when a drive is marked as removable its entry in the device list will change accordingly - the names of all partitions on that drive will be removed from the device list and replaced with a single entry with the name of the device-driver and unit number for that drive. (i.e. for a removable drive mounted as unit 6 on the scsi.device the entry would read SCSI 6). Changing the type specification back to a non-removable setting will restore the device list to its normal state. Important note: It is very important that this gadget be set properly for all devices or DynamiCache may not function properly or may not detect media-changes which could lead to corruption of your data. Read Ahead (r/R): The read-ahead gadget allows you to adjust the number of sectors of read-ahead that should be used for each device or to select a special Track-Read mode for use on floppies. Specifying a read-ahead size of None disables read-ahead caching for that device. Read-ahead is a caching technique where, when a sector of data is read in from disk, additional sectors following the requested sector are also read and copied into cache- memory. Since most data files are stored on disk in consecutive sectors it is likely that if one sector is needed the following sectors will also soon be needed. Since it is much faster to read groups of sectors all at once, and since the additional sectors will likely be needed soon anyway, read-ahead caching can provide significant performance increases. If a device contains many large files and is relatively un-fragmented a large read-ahead size will be very beneficial. If a device contains many small files or if the device is very fragmented a smaller read-ahead size will be beneficial. Larger read-ahead sizes are also more beneficial on faster devices where the read-time for additional sectors is minimal. Smaller read-ahead sizes should be used on slower devices such as CD-ROMs or Magneto-Optical drives. Experiment to find the best settings for your hardware and usage patterns but in general use the following guidelines when selecting read-ahead size and resist the temptation to select too large a value. Bigger is NOT always better in this case! 2 - 4 sectors - Good values for use on CD-ROM drives, magneto optical drives, and other devices with relatively slow transfer rates. 8 sectors - A good value for most hard-disks with moderate transfer rates, fragmentation and file sizes. Eight sectors is the default value. 16 - 64 sectors - Should only be used on hard disks with fast transfer rates, large file sizes and minimal fragmentation. Track-Mode - This setting should ONLY be used on floppy disk drives and uses a special mode where entire tracks are read in from the floppy disk at once. This is a very efficient method of reading data from floppy disks and will provide significant performance improvements but should NOT be used with hard-disks. (Note: De-fragmenting your disk-partitions with one of the many available public domain or commercial products designed for that purpose will greatly improve the performance observed when using read-ahead on those partitions. Make sure to back up all your data before de-fragmenting in case something goes wrong!) Write Cache (w/W): Selects whether write-accesses are cached or not. If None is selected write accesses will not be cached - this will make the initial write access faster but the data will not be in the cache if it needs to be accessed again. If Write-Thru is selected data will be copied into cache memory as it is being written to disk. This may slightly slow down the initial write but the data will already be in cache if it is needed again and future accesses will be much faster. In most situations Write-thru caching will provide the best general performance and should be used. Write through however will invalidate any data verification tests that a program may perform since the program will be "seeing" the data in the cache and not the data that was actually written to disk. D. Statistics Display --------------------- After caching has been activated the DynamiCache status window provides information about cache activity and effectiveness. If you want to view the status window use the hotkey or commodities exchange to pop open the DynamiCache window. Once the window is open you can use the zoomgadget to shrink the window to a smaller size where only the status display (and not the configuration gadgets) is visible. The DynamiCache status display has two different modes depending on whether the cache statistics gadget is set to Global or to the name of a specific device. Mem. Used: This line is only visible in Global mode and indicates how much memory (in kilobytes) DynamiCache is currently using as cache memory. This number will always be at least equal to the Minimum Size you set and will never exceed the Maximum Size you set but will vary dynamically within that range depending on how much memory DynamiCache requires and how much memory other programs that you run require. Parameters: This line is only visible in device specific mode and indicates the parameters that are active for the device named in the cache statistics cycle gadget. HD, FD, or RD indicate the device is a hard-drive, floppy drive or removable media drive respectively. The drive type indicator is followed by a comma and then either a number indicating the number of sectors of read-ahead that are set for the device or the letters TM indicating that Track-Mode read ahead is being used for the device. If Write-Thru caching is being used the letters WT will also be displayed. Accesses: This line tells you how many device accesses there have been since the cache was enabled. If the display is in global mode this number indicates total disk accesses for all cachable devices. If the display is in device specific mode this number indicates accesses for that device only. Cache Hits: This line tells you how many times the data being accessed was already in cache memory. If the display is in global mode this number indicates total cache hits for all cachable devices. If the display is in device specific mode this number indicates cache hits for that device only. Hit Ratio: This is a percentage showing the ratio of Cache Hits to Accesses and gives a measure of how effective the current DynamiCache configuration is on your system. If the display is in global mode this number indicates hit ratio for all cachable devices. If the display is in device specific mode this number indicates hit ratio for that device only. Cache hit ratios of 40% to 60% are normal and if you are getting less than this on your system I would suggest altering your DynamiCache configuration in an attempt to achieve better performance. The settings which are most likely to have dramatic effects on cache-hit ratio (in order of effectiveness) are Read- Ahead, Write-Thru, and Purge Scheme. Setting a read-ahead value either too large OR too small can impair cache efficiency. Enabling Write-Thru and LRU Purge Scheme will also often improve the cache hit ratio. However, optimal cache configuration varies due to system configuration and usage patterns. Therefore it is suggested that you experiment with various settings while monitoring cache hit ratio on a per device basis in order to achieve the best performance on your system. E. Commodities Exchange ----------------------- DynamiCache behaves like a commodity and is controllable through the Commodities Exchange program. To control DynamiCache in this way start the commodities exchange program and select "DynamiCache" from the scrolling list of available commodities. You will now have four options accessible via gadgets. Show Interface: Opens the DynamiCache configuration/statistics window and pops it to the front of the display. The behavior is the same as pressing the DynamiCache hotkey. Hide Interface: The behavior is the same as clicking the close-gadget on the DynamiCache window. This does NOT deactivate caching or remove DynamiCache. Active/Inactive: This cycle gadget lets you activate or deactivate caching. This behavior is the same as the Activate/Inactivate cache menu items. Remove: Removes any current cache configuration, closes the DynamiCache window, and exits DynamiCache program. The behavior is the same as the Quit menu item. F. Start-up Parameters ---------------------- DynamiCache supports a variety of start-up parameters that can be specified either as Workbench tooltypes or as command line options. As shipped, the DynamiCache icon has all possible tooltypes specified but most of them have been disabled by enclosing them in parenthesis. To use them you must remove the parenthesis and alter the parameters to suit your needs. For instructions on altering icon tooltypes consult your Workbench manuals. The keywords and syntax used for tooltype and command line parameters are the same. However, if you specify an option on the command line which contains spaces within the option you must enclose the entire option in double quotes. For example: DynamiCache "CX_POPKEY=Alt Esc" ^ | Because of this space the entire option must be enclosed in double quotes. Quoting is NOT necessary if options are specified via WorkBench tooltypes. Using the "DynamiCache ?" command from the shell will print a command template summary. The various legal parameters are: CX_POPKEY= CX_POPKEY lets you specify which hotkey sequence should be used to pop open the DynamiCache window. Consult your AmigaOS manuals for a list of valid key specifiers. The default CX_POPKEY setting is Alt Esc. CX_POPUP= If CX_POPUP=YES is set (default) the full-size DynamiCache configuration window will be opened on start-up. If CX_POPUP=SMALL is set the smaller DynamiCache statistics display window will be opened on start-up. If CX_POPUP=NO is set the DynamiCache window will NOT be opened on start-up (it can be popped open later by using of the hotkey or Commodities Exchange.) DONOTWAIT This parameter only works as a tooltype when the program is started from the WBStartup drawer. This parameter should always be specified in order for the program to start correctly from WBStartup. SETTINGS= This parameter specifies the location DynamiCache should load its configuration file from upon start-up. The default location is ENVARC:DynamiCache/DynamiCache.prefs. STARTPRI=<-128 to 127> This parameter only works as a tooltype when the program is started from the WBStartup drawer. STARTPRI specifies the order in which programs in the WBStartup drawer are started and has a permissible range from -128 to 127. Programs with a higher STARTPRI will be started BEFORE programs with a lower STARTPRI. In most cases DynamiCache should be the first thing run from your WBStartup drawer and so the default STARTPRI is set to 127. QUIET This parameter when supplied tells DynamiCache to suppress all non-error informational requesters that would appear on the screen and all non-essential shell output. QUIT If the QUIT parameter is present DynamiCache will not start up but rather will send a signal to any already running copy of DynamiCache telling that copy to exit and deactivate caching. If another copy of DynamiCache is running a window will pop-up telling you that the cache is being disabled. The presence of the QUIT parameter causes all other parameters to be ignored. RESCANDEVSTIME= This parameter specifies the interval in seconds that elapses between attempts to re-scan the device list for newly mounted devices. The default value is 30. Larger values will cause the list to be re-scanned less frequently but will reduce CPU usage. Smaller values will have the opposite effect and are not suggested. UPDATESTATSTIME= This parameter specifies the interval in seconds that elapses between updates of the DynamiCache statistics display. The default value is 2. Smaller values will have no effect. Larger values will cause the display to be updated less frequently but will reduce CPU usage. USEIMMEDIATE If the USEIMMEDIATE parameter is present DynamiCache will install the cache configuration immediately upon start-up without waiting for the user to click Use or Save in the configuration window. This is handy for starting the cache automatically at boot-time from the WBStartup drawer. The cache configuration which is loaded/installed is specified by the SETTINGS keyword or is read from the default location envarc:DynamiCache/DynamiCache.prefs if no SETTINGS keyword is specified. CLOSEAFTERUSE If the CLOSEAFTERUSE parameter is present the DynamiCache window will be automatically closed after Use, Save or Cancel options are selected. The default is for CLOSEAFTERUSE to be disabled and for the window to zoom from its full sized to small after Use, Save or Cancel are selected. Chapter IV: Trouble Shooting & Error Messages ============================================= This chapter attempts to identify and provide solutions for some common problems that you might encounter. The first section deals with problems which cause DynamiCache to function improperly but which do NOT cause an error message to be displayed. The second section deals with the meanings of the various error messages which DynamiCache may display. The third section concerns contacting technical support if you are unable to resolve your problem on your own. A. Trouble-Shooting General Problems ------------------------------------ Problem: DynamiCache is ignoring my cache configuration or is not caching the devices I tell it too even though they say "enabled" in the Device List. Solution: Remember that DynamiCache does not begin to use the configuration that is specified by gadgets and the device list the Use or Save gadgets are pressed! Thus whenever you change the gadget settings by direct manipulation or by loading a configuration from disk you MUST click Use or Save before it will take effect. The statistics display window and cycle gadget can be used to accurately view the settings that are currently in use for each device whereas the scrolling listview gadgets show the settings that will be in use next time you install a configuration by clicking Save or Use. Problem: DynamiCache crashes or locks-up when I install a new cache configuration or whenever I access a particular device. Solution: You may be trying to cache a device which DynamiCache is not compatible with. Devices which DynamiCache is not capable of caching should not even show up in the list of cachable devices but due to the great variety of devices out there this auto-filtering feature may not always eliminate all non-cachable devices. Devices which DynamiCache is not capable of caching include: ram-disks, remotely mounted network devices and non-block-oriented devices (streaming tapes for example). Caching should be disabled for any such device which appears in the device list. If there is no obvious device which is causing problems try disabling cache for all devices. The re-enable cache on one device, click Use, and test out the configuration. If everything works all right enable caching for another device and repeat until you find the problem causing device. If you are still having problems it may be that you are running another utility program which conflicts with DynamiCache. Some public domain utility programs, particularly those which modify the system in non-standard ways or which patch into the system vectors, may have bugs which conflict with DynamiCache. To eliminate the possibility that another program that you are running is interfering with DynamiCache try temporarily removing all other non-standard programs from your WBStartup drawer or User-Startup sequence and then try running DynamiCache. Even better try running DynamiCache after booting from a copy of your original "clean" Workbench disks. If DynamiCache now works then gradually experiment with reintroducing the other programs you were running to your environment until you isolate the specific program causing the problem. Problem: DynamiCache does not recognize media changes or gives me corrupt data errors when accessing my floppy or removable media disk drives. Solution: Make sure that the device type is appropriately set to indicate that the drive is a floppy or removable disk drive. Problem: My virus checking program complains that the BeginIO and AbortIO vectors of trackdisk.device have been altered whenever I install a DynamiCache configuration. Solution: Don't panic! In order to work DynamiCache MUST patch these vectors for every device that cache is enabled for. This is NOT a virus. You must tell your virus-checker to ignore DynamiCache's changes and not to restore these vectors to their previous settings. If you tell your virus checker to restore these vectors your computer may crash. If you are starting both the virus checker and DynamiCache from your WBStartup drawer you can avoid the initial virus checker complaint by starting DynamiCache before the virus checker. To do this make sure the virus checker's STARTPRI tooltype has a LOWER value than DynamiCache's. (By default DynamiCache has a STARTPRI of 127 so it is probable that the virus checker's startpri is already lower than this so nothing will need to be changed.) Problem: DynamiCache is not giving me very good hit-ratios. What should I do? Solution: Use the statistics display gadget to monitor statistics on a per-device basis and adjust the parameters for each device to obtain optimal performance. A common problem is that the Read-Ahead buffer size is set too large - try reducing the buffer size and installing the new configuration with Use/Save and see if things improve. Track-mode read-ahead should never be used with any device except floppy disks or hit-rates may suffer. Switching to LRU Purge Scheme or toggling the Write-Through status may also help improve hit rates. You may also have your Maximum Cache size set too small. Another way to improve cache hit rates is to de-fragment your hard-drive using a public-domain or commercial de-fragmentation program. If all these measures fail the problem may simply be that you do not have enough free memory in your system to effectively cache your disks. Disk caching is memory intensive even with programs like DynamiCache which make extremely effective use of the memory you do have. Problem: Should I continue to use Addbuffers? What about Commodore's Directory Caching File System under 3.0? What about other 3rd party caching software? Solution: Addbuffers, a primitive caching command supplied by Commodore, is perfectly safe to use in conjunction with DynamiCache. When both are used together they may improve directory access speeds more than either used alone would. Addbuffers ONLY works to cache directory accesses though wehre DynamiCache works with all types of accesses. When using Addbuffers in combination with DynamiCache I would suggest using no more than 50 or 100 Addbuffers per device. Note that Addbuffers caches on the filesystem level and if you have addbuffers installed on a partition and do a directory listing it is possible that the directory will be supplied from the Addbuffers cache and DC won't ever see the accesses so the access count for that device will not change. This is normal behavior so do not be alarmed by it. Commodore's Directory Caching File System (DCFS) is also safe to use with DynamiCache. Using the two together will greatly increase performance. Other caching software is NOT safe to use at the same time as DynamiCache. If two different programs are attempting to cache the same device it is likely that they will interfere with each other and either cause drastic performance decreases or crash the system. Problem: I can't get GigaMem (or other virtual memory systems) and DynamiCache to work too well together. What should I do? Solution: It is possible to use virtual memory and disk caching together if you are careful. During development DynamiCache was tested with GigaMem to ensure compatibility. There are several things you must do to make sure they work together smoothly though. First, make sure that DynamiCache is NOT in GigaMem's list of programs which can use virtual memory. Attempting to use virtual memory as disk-cache is a sure recipe for disaster. Second, try adjusting the order in which the programs are started. If they are both being started from WBStartup adjust their STARTPRI tooltypes. Usually DynamiCache should be started BEFORE GigaMem or other virtual memory systems. However, if this is not working too well you may want to experiment with starting DynamiCache after the virtual memory program. If the above steps are not enough to get the two working together you may need to disable caching on the partition which is being used as swap space by the virtual memory program. This should be a last resort though since it usually will not be necessary. Problem: I want DynamiCache to automatically start up with the configuration I specify when I boot my computer. Solution: Drag the DynamiCache icon into the WBStartUp drawer. If you want to use a settings file in a location other than the default location (ENVARC:DynamiCache/DynamiCache.prefs) make sure that the filename is specified by the SETTINGS= tooltype. If you want the cache configuration to be installed immediately upon start-up specify the USEIMMEDIATE tooltype. You can specify the window mode that DynamiCache opens in by using the cx_popup= tooltype. Problem: I double-click on the DynamiCache icon but it doesn't start up. Solution: You may have specified cx_popup=no as a tooltype in which case DynamiCache IS being loaded but the window isn't being opened. Either remove this tooltype or use the hotkey or Commodities exchange to open the window after double-clicking the icon. Problem: I closed the DynamiCache window but it didn't free up my memory and the cache is still around. Solution: Closing the DynamiCache window does not remove the cache. To remove the cache and exit the program you must use the Quit menu item or the Remove function from Commodities exchange. Problem: I want DynamiCache to remember the position of its windows and reuse that position next time I start it. Solution: Drag both windows into the positions you want them to be in and then Save the configuration and DynamiCache will remember their positions. You can specify whether the DynamiCache window opens in its small or large state by specifying the cx_popup=small or cx_popup=yes tooltypes respectively. B. DynamiCache Error Messages ----------------------------- This section indicates the various error messages. Error messages when displayed on the screen will be labelled as a Fatal Error, a Recoverable Error or a Warning. Fatal errors cannot be recovered from and cause DynamiCache to exit if possible. Recoverable error messages may be recovered from by clicking Retry or ignored if possible by clicking Cancel. Warnings inform you of abnormal situations but will not usually cause any problems. Informational messages are not error conditions but merely inform you of what actions DynamiCache is doing. They appear in small windows which will disappear automatically after five seconds without any action from the user. Informational messages can be suppressed with the QUIET tooltype. Caching late-mounted device specified in settings file: The device indicated was specified in the current settings file but which was previously not present in the system device list has been identified and that caching is about to be enabled for that device. Corrupt or invalid configuration file! The settings file you specified does not appear to be a valid DynamiCache settings file. Either the file is not actually a DynamiCache settings file or the file was corrupted somehow. DynamiCache will attempt to read as much of the file as possible and will supply default values for any unreadable data. Use the configuration window to correct the settings file and re-save it. Device not found: The specified device was not able to be opened. Either the device does not actually exist, it was improperly mounted, or it is not a cachable device. Try mounting the device or inserting media if it is a removable media device currently with no media in it. If all else fails disable caching on this device. Device specified in settings file but not currently mounted: The device indicated was specified in the current settings file but has not been found in the system device list at the time the settings file was loaded. Error creating CX structures! Check hotkey specification. The hotkey specification you gave via the CX_POPKEY keyword was not a valid hotkey specifier. Please check your Amiga Workbench manuals for info on specifying valid hotkeys. If the hotkey was specified on the command line make sure that proper quoting was used around the entire parameter if it contained any spaces. For example: "cx_popkey=alt esc" Insufficient memory for .... Memory shortage is interfering with creation of a needed structure or port. Try to free up memory and retry. Insufficient free memory for initial memory chunk! DynamiCache was not able to allocate sufficient dedicated cache memory as was specified by the minimum cache size for the current configuration. Try altering the configuration to use a smaller minimum cache size. Invalid configuration file - value out of range! The settings file you specified contains an invalid entry. Either the file is not actually a DynamiCache settings file or the file was corrupted somehow. DynamiCache will attempt to read as much of the file as possible and will supply default values for any unreadable data. Use the configuration window to correct the settings file and re-save it. Minimum Cache Size exceeds Maximum Cache size! The minimum cache size you specified was smaller than the maximum cache size you specified. DynamiCache will reset minimum and maximum cache sizes to their default values if this occurs. Patching non-standard BEGINIO/ABORTIO entry for: This informs you that you have a device driver which uses a non- standard format but that DynamiCache knows how to deal with this particular non-standard format. Complain to the manufacturer of this device driver! (If they need more technical details about exactly what is wrong with their device have them contact me.) DynamiCache will attempt to "fix" this devices for you. This requester merely notifies you that DynamiCache knows how to deal with this particular non-standard device and is making the necessary patches. Currently it is known that most ICD products will cause this warning to appear. If you should still have problems when enabling cache for a device where this requester appears please contact technical support. Be prepared to inform them exactly of all the information that appears in this requester including the exact device name and the two hexadecimal numbers. If I am to have any hope of patching DynamiCache to correctly deal with your particular non-standard device I must have the exact information which appears in this requester. Unable to create ... Memory shortage or shortage of other system resources is preventing the successful creation of a needed structure or port. Try to free up memory and retry. Unable to install jump-table. The program was not able to install its patches probably due to shortage of memory. Unable to open DynamiCache window. The program was not able to open the window due to shortage of memory. Unable to open file requester. This program was not able to open the ASL file requester probably due to shortage of memory. Unable to open settings file: The settings file which was specified via the file requester or via the SETTINGS start-up parameter was not located in the expected location. Check to make sure that your filename specification was correct and that the file actually exists. If the filename was specified as a command line parameter and contained spaces check to make sure that proper quoting was used around the entire filename. For example "SETTINGS=DH0:File Name With Spaces" Unable to patch non-standard BEGINIO/ABORTIO entry for: This indicates that you have a disk controller which uses a non- standard device format and that DynamiCache does NOT know how to deal with this particular non-standard format. Complain to the manufacturer of this device driver! (If they need more technical details about exactly what is wrong with their device have them contact me.) DynamiCache does not recognize this non-standard device and cannot fix it. Caching will not be enabled for the device. Currently there are no know devices which cause this error message. Please contact technical support and inform them exactly of all the information that appears in this requester including the exact device name and the two hexadecimal numbers. If I am to have any hope of patching DynamiCache to correctly deal with your particular non-standard device I must have the exact information which appears in this requester. Unable to save configuration file: DynamiCache encountered an error while writing the configuration file to the specified destination. Check to make sure that the destination is valid, that the disk is not full, and that write protect is disabled for that disk. C. Contacting Technical Support ------------------------------- If you have read the entire manual and are still having persistent problems please contact technical support. Please be prepared to supply your name and product registration information. Also please inform technical support of your entire system configuration including computer model, amount of memory, operating system version and information about the manufacturer, model, and revision of any peripherals you are using. Please be sure to give a complete description of the problem and the steps necessary to produce it and have an exact copy of any error messages that DynamiCache may have produced. Following these simple guidelines will make it much easier for us to help you solve your problem quickly.