WimpExtension document: Notes - 1.01 - 20-11-2004                     Doc 00
============================================================================

Intro
=====
This document contains some notes on the conversion to 32-bit clean code and
changes/corrections made afterwards.

The version of WimpExtension II that I started with was 3.47. However, some
of the other documents in this directory describe version 3.38. I'm not sure
whether a more recent version of the documentation is available anywhere. As
suggested by Jon Ribbens, I retrieved everything in one archive called
wxii.zip from the ftp/source directory on the DoggySoft site.

People comparing the contents of that archive with this one, may notice I've
copied some of the 'old docs' to the Documents directory. The reason for
that is simple: the relevant 'new docs' weren't there...


The conversion
==============
Generally speaking, 32-bitting software involves a bit more than removing
the ^ and s from instructions that load the pc. I've also changed a number
of single register LDMs to LDRs, replaced some conditional LDMs with
branches, checked the code for conditionals after BLs and SWIs, rewritten
bits of code that expected memory addresses to be positive at all times and
so on.
Some of these changes may have unexpected side effects if the calling code
assumes too much. That - unfortunately - cannot be helped...

What I haven't done is make any serious attempt to 'improve' anything.
Although I can understand most of what's happening, I just don't have the
time for that. So if something goes wrong with the 32-bit clean version in
the same way it did with 3.47 or earlier, than that's tough...

That said, I did remove a few bugs which were so obvious that leaving them
in would have been downright evil.

Caller's processor flags
~~~~~~~~~~~~~~~~~~~~~~~~
I haven't made any effort to retain the state of the flags in 26-bit mode.
In fact, I've completely ignored it - except for V, of course - unless the
description of a SWI dictated a specific result (e.g. WimpExt_Intersect).

Because of this, I've had to keep an eye on the state of the V flag
throughout all routines. I've entered comments like 'also clears V' in the
source here and there, particularly if an exit is close by. These comments
may not always be 100% accurate on their own, but they should be in case the
exit is taken.

Version code
~~~~~~~~~~~~
In the original package, the version code of the library files (the word at
offset 8) is 0. I've changed this to 1 to indicate 32-bit clean code. This
will prevent the module from loading old 26-bit libraries.


Legalese, maintenance and availability
======================================
Everything in this package remains the copyright of the original authors
(DoggySoft, generally - see F0-Libs for a quick overview).

While you can't blame them for any bugs I may have introduced during the
conversion, I'm not reponsible for any that were already there in the first
place. Anyway, you use this software at your own risk. No-one can be held
accountable for any loss or damage caused by using it or not being able
to use it.

If you find any bugs - either 'new' or 'original' - please let me know and
I'll see what I can do about them.

The current version of the package will usually be available from
http://www.aconet.org/tools .

Frank de Bruijn
November 2004
mailto:frank@aconet.org


History
=======

Main module 3.48 - 13-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The initial complete overhaul, starting from 3.47. See the source for more
information.

Main module 3.49 - 14-10-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Fixed the Syntax messages for the *WimpExt and (somewhat redundant) *X
  commands (you cannot use dictionary references in error texts).
- Removed the help entry from the command table for the *WimpExt command
  (was never used - see the 'service_help' code). Also cleaned up the
  service code a bit.
- Commented out some (apparently) faulty code from 'command_libavailable'.
- Extended the information provided by the 'WimpExt LibLoaded' command, in
  an effort to find out why sFTP will sometimes fail to run because of some
  problem with WimpExt (this was already present in 3.45, by the way...).
  Not quite there yet...
- Fixed a fix in 'swi_miscop' which hadn't been fixed though the comment
  suggested that it had.
- A large number of small optimizations.

Library 01 Misc 1.02 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 02 LinkedWindow 1.07 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Something didn't feel right about this one. The archive contained two
  versions: 0.10 dated 28-07-1994 and 1.06 dated 12-04-1996. The former was
  obviously older, but the latter had parts commented out and at least one
  weird flag check (VS after a routine that never exits with V set).
  It also had some garbled label names and couldn't possibly have been run
  successfully in the state it was in.

Library 02 LinkedWindow 1.08 - 19-11-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Reverse engineered from 1.05. As I expected, version 1.06 was broken, so
  1.07 was as well.

Library 03 ColoursMenu 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 04 Requester 1.02 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 05 FontMenu 1.01 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 06 ControlImmediate 1.03 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 07 HeapManager 1.04 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 08 DataTrans 1.01 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 09 Help 1.02 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 0A Sort 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 0B MemMove 1.03 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- This one also contained some impossible code that could never have been
  assembled before. However, the resulting code looks similar enough to that
  in the WimpExtLib file from the 3.45 archive I got hold of later, so I
  don't expect any problems.

Library 0C DrawOp 1.05 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Required the file AFPLibrary, which wasn't anywhere to be found. Removing
  the FNf(" ") from around the floating point instructions seems to have
  been all that was really needed however. That and removing the superfluous
  precision from the FIX instructions (which can never be more than single
  precision anyway, as the destination is a single ARM register).

Library 0C DrawOp 1.06 - 20-11-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The original 1.04 (and consequently 1.05) had bit 0 of the flags set,
  meaning the library could be used without being registered. Unfortunately,
  this had the effect of not clearing (or even claiming!) the workspace.
  Very nasty...

Library 0D SpriteOp 1.04 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 0E LoadTemplates 1.02 - 10-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 0F LoadRAMTemplate 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 11 IconBar 1.02 - 10-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 12 Icons 1.02 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 13 Menus 1.03 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 14 Windows 1.03 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 15 Pointer 1.01 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 16 Caret 1.03 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 17 SpritePool 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 18 3DIcons 1.03 - 12-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 1A CDAManager 1.10 - 10-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 1B DoggySoftA 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 1C DoggySoftB 0.11 - 11-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Was missing from the sources, so had to be reverse engineered.

Library 1D Slider 1.08 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Library 1E Termite
~~~~~~~~~~~~~~~~~~
- Too big and of too little (general) use, so not converted. Sorry.

Library 1F FastChars 1.01 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Assembler pseudo directives such as EQUZ, EQUP, ADRL and FILL may look
  very nice, but as they're not available in standard BBC BASIC V they're
  pretty useless in the end...

Library 20 Options 1.25 - 10-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics (apart from having the same pseudo directives as in 1F).

Library 21 MsgTrans
~~~~~~~~~~~~~~~~~~~
- Missing and nowhere to be found in assembled state either...

Library 22 Time 0.14 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Same junk as in some of the previously mentioned libraries and two very
  nasty bugs which were obviously created by copying a piece of code and
  forgetting to set the right pointers in the copy.
- Rewrote part of the adjustment routines because not preserving flags over
  BL calls made the originals less than suitable for direct conversion.

Library 23 FileType 0.09 - 07-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- No specifics.

Application ExtLibMan 1.01 - 12-09-2004
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the Library Manager, which isn't documented anywhere. Its use is
quite straightforward, so I'm not going to remedy that...
