@database "VirtualMem Documentation" @author "Kalle Sandström" @$VER: VirtualMem.guide 1.2 (7.8.97) @(c) "Kalle Sandström 1996,1997" @toc main @node main "VirtualMem Documentation" VirtualMem Documentation (c) 1996,1997 by @{"Kalle Sandström" link author} 1. @{"Copyrights & Disclaimer" link legalstuff} Legal B.S. 2. @{"Distribution " link distribution} Distribution 3. @{"Information " link information} What it is 4. @{"Installation " link installation} How to install 5. @{"Support programs " link programs} Support programs 6. @{"Developer information " link devinfo} if(youcode)readit(); 7. @{"Future plans " link futureplans} What's going to come 8. @{"Bug list " link buglist} Bugs: probably infinite 9. @{"History " link history} History 10. @{"The author " link author} That's me! @endnode @node programs "Support programs" There are some VirtualMem support programs in the Support/ directory. @{"virtpatch " link virtpatch} AllocMem/-Vec patch @{"vstat " link vstat} Statistics @endnode @node virtpatch "VirtualMem patch" "virtpatch" patches the exec.library function AllocMem() to attempt to free some memory for non-virtualmem.library applications. If you have a harddrive, you should install it. Without virtpatch, VirtualMem will not swap memory objects to disk. @endnode @node vstat "VirtualMem statistics" "vstat" is a small program that prints some information from VirtualMem to stdout (the console window). Example: Bytes Objects Paged 0 0 Locked 0 0 Total 24011 1 Maybe I'll write a stat program to output into an intuition window as well, see @{"plans" link futureplans} for more info. @endnode @node history "History" V1 (1.0): (14.9.1996 -> 23.9.1996) The very 1st release. Loads of bugs. V2 (1.1): (25.9.1996 -> 13.11.1996) Localised vstat. Only finnish catalogs for now... Added AutoAdjustPri(). Fixed virtpatch to actually page stuff out. Some room for improvements, though. Fixed the list-reading routines. That should have fixed those funny lockups... Added a memory object priority demo program. GetVMemInfo() now only reads some numbers instead of calculating them from a list. Fixed a whole load of other bugs & problems, including the GCC inline file... It finally works well now. V3 (1.1b): (13.11.1996 -> 16.11.1996) There were some horrible bugs in the previous release, for example virtpatch didn't leave enough memory for intuition to resize windows, etc. Now virtpatch checks after each memory allocation if there's >100K free and if not, frees some. V4 (1.2): (16.11.1996 -> 7.8.1997) Added MultiUser support & VMEMF_PROTECT. Minor corrections etc. in the documentation and C headers. The library in 1.1b wasn't optimised. This one is. Changed MakeVMem(): Now just CreateVMem()s an object and copies the data. Accepts MKVM_VECMEMORY for AllocVec()ed memory... @endnode @node buglist "Bug list" There are no bugs I know of for now. However, if you notice any, contact @{" me " link author} about it, since the releases before 1.1b were practically FULL of undesirable little "features" such as lockups. @endnode @node futureplans "Plans for the future" I intend to keep on developing VirtualMem as suggestions arrive. Here's a (short) list of features to come: - Memory compression using XPK. - Saving of compressed memory blocks. This should be a major speedup on floppy-only systems. - A not-saving version for floppy-only systems. - Mapping of CHIP ram to FAST ram. - A swapwatcher program to replace @{"vstat" link vstat}. - A preferences program to control the maximum swap size. Send your own ideas to @{" me " link author} and I'll see what I can do... @endnode @node information "Information" VirtualMem is a shared library that allows programs to use virtual memory without any special hardware (like a Memory Management Unit, MMU). In effect, this means that programs can use more RAM than the computer really has. However, nothing comes for free. Obviously, there's a speed penalty for tasks using VirtualMem, especially when memory is low. A disk cache can help a lot with this as it can speed disk accesses up quite a bit. See also @{"future plans" link futureplans} for more information. Requirements: - An Amiga or compatible computer with Kickstart 2.0 (V36) or newer. - A hard disk. Though VirtualMem can be used with a floppy system, it won't be nice as floppy disks are soooo slow. If you're upgrading from a previously installed version of VirtualMem, please read the update @{"history" link history} section. @endnode @node devinfo "Developer information" The distributed archive contains the files needed for using virtualmem.library in your programs. There are, for now, files for GCC, Amiga E and m68k Assembler (There is also the .fd file just in case you use a programming environment with a program that can convert those). If you convert these files to some other environment or notice any bugs in the existing ones, feel quite free to contact @{" me " link author} about it so that I can add them to the next version. 1. @{"Usage " link devusage} How-to 2. @{"Tips " link devtips} Writing them well 3. @{"Notes " link devnotes} Notes @endnode @node devnotes "Notes" * When you specify the MEMF_PUBLIC bit with CreateVMem(), virtualmem.library will still keep paging the memory block out (if unlocked), but when it's locked, a "real" virtual memory software (such as VMM or GigaMem) will not. If you want to prevent virtualmem.library from paging your memory object out, set the VMEMM_DONOTPAGE flag. * The PriorityDemo program in the Examples/ directory is only a demonstration of what VirtualMem can do. In real life, you probably should RemoveVMem() the memory objects as soon as they become unnecessary. * There are some quick macros in the Include/libraries/virtualmem.i file for assembly programmers... Makes locking & unlocking a bit less painful. * In previous versions of VirtualMem there was a huge (security) bug if VirtualMem was being used on a MultiUser system. VirtualMem would save the memory block paged out by the task that required the memory, possibly giving ownership of the swapfile to some other user preventing the original task from accessing the memory. The support for MultiUser & multiuser.library has removed this bug. If you want to protect a memory object from being read from the VMEM: directory or being locked by tasks other than yours, set the VMEMF_PROTECT bit of the memory object. @endnode @node devtips "How to write good VirtualMem programs" Here's a tiny guide about using VirtualMem efficiently. It will grow in future releases. 1. Lock as little as possible. The less you lock, the less likely it is that all of the real RAM in the system gets exhausted. 2. Create several memory objects for very large data items. If, for example, you are processing the Jargon File, size around 1.2 MB, and keeping one huge memory block instead of, say, one of 12 or 24, you are hogging a great big chunk of memory keeping the whole ~1.2M locked. 3. Don't create lots of very small memory objects. The virtualmem.library keeps a list of all memory blocks that are been created and thus needs to allocate some real ram to store swap file names, a Node structure, etc. Look into libraries/virtualmem.#? for more information. 4. Make unused memory areas memory objects. MakeVMem() can create a memory object out of some ram received from, for example, powerpacker.library. 5. Use AutoAdjustPri() and ChangeVMemPri() efficiently. After unlocking an AutoAdjustPri()ed memory object, give it a low priority (around -50 or so) if you aren't going to use it for a while. @endnode @node devusage "How to write VirtualMem programs" Usually, your non-VirtualMem code would look like this (in pseudocode): START SubProgram AllocMem(...) SomeFunction(...) TimeConsumingFunction(...) SomeOtherFunction(...) FreeMem(...) END To use VirtualMem, you only have to make some slight modifications to your programs. The same code, using VirtualMem, can be written like this: START SubProgram CreateVMem(...) LockVMem(...) SomeFunction(...) UnlockVMem(...) TimeConsumingFunction(...) LockVMem(...) SomeOtherFunction(...) UnlockVMem(...) RemoveVMem(...) END The locking and unlocking functions do not cost many cycles if the requested memory block is in real memory. @endnode @node installation "How to install VirtualMem" There is, for now, no Installer script as every programmer keeps his include/header/module/whatever in different directories... The manual installation is fairly simple, however. 1. copy Libs/virtualmem.library to Libs: 2. copy Support/#? to C: (or add a path command to your user-startup) 3. copy the contents of the Catalogs/ directory into LOCALE: 4. open your favourite text editor and add the following lines to your s:user-startup file: ---cut here--- assign VMem: ;(To the directory you want the swap files to go to. ; See also @{"Where to put the swap files" link swapdir}.) Delete VMem:#?.swp Run NIL: C:virtpatch ---cut here, too--- 5. copy prefs/virtualmem#? to sys:prefs/ 5. Reboot or run virtpatch. 6. Developers should copy the necessary include/header/library/whatever files they need to the appropriate directories. Note that there aren't any pragmas/#? files for SAS/C or .lib files for DICE. I'm happy to accept any stuff that would make VirtualMem usable from other developement environments into the next version. @endnode @node swapdir "Where do I assign VMEM: to?" The best place for the swap files is in the partition that you have the most room left on. Do not try to assign it to: * RAM: as this will probably cause VirtualMem to deadlock and leave you clicking on lots of "Ram disk is full"-requesters... * Any sort of a compressing disk handler etc. because most transparent disk compressors require some temporary memory for compression. @endnode @node distribution "Distribution" VirtualMem is giftware. That is, if you use it in your own programs or just simply like it, you should send me a gift, such as a postcard of a pretty sight of your country, an E- or SnailMail letter in which you express your praise or something nice anyway. Use your imagination. You can distribute VirtualMem as long as these conditions are met: a. The archive is distributed in its original LHA form. All the PGP signatures must be included unchanged (PGP public key available from @{" me " link author}) You should not modify or remove this documentation or any other files in the archive. b. (Disk) Magazines may not distribute VirtualMem on their coverdisks, CD-ROMs, or on any other accompanying media without the WRITTEN permission from @{"Kalle Sandström" link author}. Don't worry though, I'll probably let you include it for free. c. PD/SW libraries must not charge more that 10 finnish marks(about $2) for the disk VirtualMem is distributed on. d. VirtualMem can be included in any of the future AmiNet or Fish CD-ROMs for absolutely free. e. If the name has to be reduced down to 8+3 characters (damn those PCs), it should be ViMem??.LHA, the ?:s being the version number. Developers that use VirtualMem in their programs are allowed to include virtualmem.library and @{"virtpatch" link virtpatch} along with the program files. However, the documentation should contain the VirtualMem.Readme file and a "this program uses VirtualMem" text somewhere. Of course, I would like a free full copy of the software, but that's not absolutely mandatory. @endnode @node author "The author" VirtualMem was developed with the following computer equipment: An A1200 with 2/8 MB of RAM, 80MB IDE 2,5" harddisk (and since 15.11.1996, a 210MB IDE 3,5" HD), an external disk drive and Kickstart 3.1 (V40). VirtualMem was programmed in 98% C using the GNU C compiler versions 2.7.0 and 2.7.2.1. libinit.o from libnix 0.8 and 1.1 were used to create the library in the first place. Flexcat (by Jochen Wiedmann) was used to generate the locale code for vstat. My address is currently like this: (Snailmail) Kalle Sandström Laajasuontie 16-18 C25 00320 Helsinki Finland Europe (E-mail) psilon@xgw.fi Bug reports, suggestions, donations etc. are gladly accepted, but do keep in mind that I'm just a human being :-) @endnode @node legalstuff "Copyrights & Disclaimer" The VirtualMem documentation, the system library and all files that are in the VirtualMem/ directory are (c) 1996,1997 by @{"Kalle Sandström" link author}. MultiUser and multiuser.library are (c) by Geert Uytterhoeven. This software is provided "as is", this means that by installing VirtualMem, the user accepts FULL responsibility for any damage or loss, mental or physical, that might occur through its use or the inability to use it. Thus, Kalle Sandström can NOT be held responsible. If the laws of your country state that I am responsible no matter what, you are NOT allowed to use NOR distribute VirtualMem. @endnode