Absolutely V1.03 17 Feb 2004
----------------------------

Absolutely is a small module designed to automatically allocate the memory required for loading absolute files (&FF8), particularly ones in AIF format. This means that whenever you double-click an absolute file, you never have to worry about whether the Wimp Slot is large enough to hold the file, or whether the initilisation code in AIF files (e.g. C programs) have enough memory allocated.


Requirements
------------

In theory Absolutely should work on any version of RISC OS. However, it's currently only been tested on 3.7 and 5. The installation procedure below assumes you have a Universal Boot structure installed; users of RISC OS 4 and above should have this as default, but users of RISC OS 3 will have to check if they have the module WindowManager 3.98 or higher. If you don't have a copy then grab the Universal Boot structure from http://acorn.riscos.com/riscos/releases/UniBoot/


Installation
------------

Run SysMerge to add the module to your !System directory. Users of RISC OS 3.5 and above should find SysMerge as the 'System' item in Configure.

However for Absolutely to be useful, you'll probably want it loaded on startup, so you need to add the line 'RMLoad System:Modules.Absolutely' somewhere to the end of your !Boot.Choices.Boot.PreDesktop file (e.g. in the 'Misc' section). For RISC OS 4 and above, I believe there is a utility in Configure to simplify this task.

If the computer gives the error 'Filing system or path System: not present' next time you start your computer, then you probably don't have the Universal Boot structure installed. Once you've re-entered the desktop (by typing 'desktop') and removed the RMLoad command, either grab a copy of UniBoot from the Acorn FTP archives (see above), or just place the RMLoad line in !Boot.Choices.Boot.Desktop instead (Somewhere near the bottom should do).

The other two files (This readme and the source code) can be placed wherever you want or just discarded at will, since they aren't necessary to the running of the program.


Common error messages Absolutely can prevent
--------------------------------------------

No writeable memory at this address

  This is when RISC OS tries to load a file bigger than the Wimp Slot 'next' value. Absolutely should detect and fix this, by ensuring the Wimp Slot is at least the size of the program you are trying to load. Note that some versions of RISC OS Select have fixed this, but the following problems still remain...


Internal error: abort on data transfer at &0000807C

  This is when the initialisation code in an AIF format absolute file tries to write outside the allocated Wimp Slot for the program. Absolutely should detect and prevent this, by ensuring the Wimp Slot is at least large enough for the program to initialise; most AIF format programs should then be able to extend the Wimp Slot themselves without any problems.


Not enough memory for C library

  This one is quite rare, and only occurs if there is enough memory for an AIF file to initialise itself, but not enough memory for the Shared C Library to set up the C environment. There's no surefire fix for this (and similar errors can occur with other libraries), but Absolutely gets past everything I've tried by simply allocating 8K more space than is needed. Incidentally, I only discovered this error myself during the development of Absolutely.


Limitations
-----------

'Non-executable' AIF files won't be detected. However, I don't think these are ever used under RISC OS, and if they were then a custom loader would probably be needed anyway (Which should take care of the memory management for you).

Also, it won't work if used outside the Wimp (i.e. by choosing 'Exit' from the Task Manager). But from what I can tell the entire application space is available for use anyway, so you shouldn't have any problems loading programs. Running programs from the command line (i.e. by pressing F12), or from a taskwindow, works fine though, since you're still technically in the Wimp.

Some programs (e.g. those linked against UnixLib) use a system of moving themselves to the top of application space before running any 'child' programs. This means that Absolutely might not be able to allocate enough space for a child program, and so loading will fail. For example you will still have to ensure that GCC has a minimum of 3000K of memory allocated before running it. I haven't tested this against other libraries such as the Shared C Library, but I suspect that the same problems apply.


The techie bit
--------------

Absolutely works by sitting on the FSControlV vector, and listening out for 'Run a file' commands. Once one has been intercepted it will then check its file type (to ensure it is an absolute file), its size, and whether it is in AIF format. AIF checking follows the rules laid out in the 32bit technical documentation available from Castle at http://www.iyonix.com/32bit/32bit.shtml

Absolutely is actually a bit stricter than the documentation suggests; it also checks that the Read Only area + Read Write area + Debug area totals the file size. This is to prevent assembler files which look like AIF files from causing incorrect behaviour (e.g. trying to allocate several hundred MB's of RAM). However since compressed AIF's won't have a size matching the one suggested in the header, an additional check is made for if there is any decompression code (i.e. the first instruction is a BL).

If the file is detected as being an AIF, then the Zero Init size is added to the file size, along with 8K scratch space (This is needed by both the Shared C Library and UnixLib, and presumably several other libraries).

This total size (or just the file size itself if it's not AIF) is then checked against the current Wimp slot size, and extra memory is allocated if needed.

Should an error occur, Absolutely attempts to continue as 'nicely' as possible:
* Early errors cause Absolutely to skip all checks and the call to OS_FSControl continues as normal
* Errors after the file size has been determined (but before the AIF detection/size) cause Absolutely to try and allocate enough memory for the file itself
* Errors during or after the memory allocation phase are ignored, and OS_FSControl will continue as normal.


The legal bit
-------------

Absolutely was written by Jeffrey Lee, me@phlamethrower.co.uk
http://www.quote-egnufeb-quote-greaterthan-colon-hash-comma-underscore-at.info/

Feel free to play around with the source code. If you're planning on distributing a modified version then please let me know, since the module name is registered to me and so I should be in control of who does what with it. Assuming everything's OK, your changes would be incorporated into my version, and then released as one (Along with a suitable mention of how you've contributed, of course).

If you want to include a copy of Absolutely in one of your programs, then feel free to do so. You need not include this readme or the source code; just RMEnsure the module in your !Run file as is usual. This should remove the requirement for an explicit WimpSlot command.


History
-------

V1.03 17 Feb 2004

* Removed a naughty 26 bit only instruction which could have been causing problems for Iyonix users

V1.02b 5 Feb 2004

* Expanded the installation instructions to account for users without the Universal Boot structure

V1.02 5 Feb 2004

* Fixed a 'minor' problem in the module header where I'd neglected to include a pointer to the module flags word, and instead had included the word directly. Thanks to Gavin Wraith for spotting this out!

V1.01 4 Feb 2004

* First release
