Article 63 of comp.sys.acorn.tech:
Newsgroups: comp.sys.acorn.tech
Path: news.uni-stuttgart.de!news.belwue.de!ira.uka.de!chx400!dxcern!dscomsa.desy.de!vxdesy.desy.de!burke
From: burke@vxdesy.desy.de
Subject: Modules
Message-ID: <1992Aug19.200810.1@vxdesy.desy.de>
Lines: 97
Sender: news@dscomsf.desy.de (USENET News System)
Nntp-Posting-Host: vxdsyc.desy.de
Organization: (DESY, Hamburg, Germany)
Date: Wed, 19 Aug 1992 20:08:10 GMT

Someone was asking for "additions" to the PRM; here are a few random comments
and questions, mostly related to modules.

  When writing a module which claims vectors, make sure you claim them again on
Service_Reset, otherwise the module will stop working. Worse, if you have
properly error-trapped finalisation code, if you try to RMReInit/RMKill it
you'll get an error from trying to release unclaimed vectors, the module will
get stuck (the workspace pointer says DEADDEAD!), and you can't get rid of it
without a hard reset. This is rather frustrating during debugging; my solution
is to keep changing the module name (you can't reload a module if an old one of
the same name refuses to die). I've sometimes ended up with several versions of
the same module, all DEADDEAD, before I've found the bug!

  Incidentally, don't forget that you can see the workspace pointer if you do
*Modules, and then use *Memory to look at it. If you have a scratch area in the
workspace you can write debugging information into it, and usually figure out
what went wrong. A bit crude, but I don't know of any interactive debuggers for
interrupt code!

  Module application code (entered from the start entry) runs in user mode,
unlike the rest of the module code which is either in SVC or IRQ mode. This has
a very important consequence, which should be written in six-foot-high letters
of fire: *THERE* *IS* *NO* *STACK* (bangs head against nearest wall :-). If you
want a stack you have to point R13 somewhere useful yourself.

  I have the following situation: the module workspace contains pointers to
other blocks allocated by OS_Module Claim. Question: what happens on RMTidy?
Answer: apparently, if you do nothing it's all OK (presumably RMA blocks which
aren't module workspace don't get moved). Is this guaranteed to be safe? What
else could you do, apart from refusing to be tidied?

  Another one from experience: if you have wimp code that starts up on
Service_WimpStart, you have to be very careful if you do a Wimp_CloseDown
without calling Wimp_Poll, as you tend to get stuck in an infinite loop (the
Desktop module keeps trying to re-start you). Either make sure you always call
Wimp_Poll at least once, or keep a flag that you've started and shut down
again.

  It appears that the "command tail" pointer passed to OS_Module Enter must
be valid, even if your code makes no use of it, as something in the OS seems
to dereference it (not sure why). If you're unlucky this results in an address
exception.

  I think that all the "command tail" pointers passed to your code point to the
first non-space character of the tail, or to a control character if there is no
tail. This isn't made entirely clear, however. I'm also not clear what is
passed as the command tail if you RMRun a module; does the same pointer
go to both the initialisation and the start code? The description of the start
entry says that it points to the environment string including the file name.
Is this really true? It presumably can't be if you start with OS_Module Enter,
which is the normal case, and I suspect it isn't for RMRun either.

  The PRM seems a bit inconsistent on the subject of interrupts in SWIs. In the
bit near the beginning on SWIs it says that although interrupts (IRQ) are
disabled on entering the SWI handler, the IRQ mode is immediately restored to
what it was when the SWI was called. This appears to be true (the code is right
at the beginning of the SWI handler). However, in the documentation on
providing SWIs in the module section (and nearly all SWIs are provided by
modules, after all) it says that the code is entered with IRQs disabled, but
you should enable them again if your code takes longer than [20 us?]. Is this
true? Why bother to enable IRQs and then disable them again? (and then maybe
enable them again). The "interrupts" bit of all the SWI documentation is a bit
odd; why should it say "interrupt status preserved" (which must always be
true), why does it always say "fast interrupts enabled" (I bet no SWI routines
explicitly enable FIQs), and is there any meaning to the "re-entrancy" state if
IRQs are disabled? For that matter, why bother to say that the processor is in
SVC mode?

  While on the subject of SWIs, is anyone keeping a list of SWI chunks used by
PD software like the filetypes list? Are Acorn allocating chunks for PD, or
is it still ISVs only?

  Now to the thorny subject of errors. Although there are a few places where
error codes are given (at the end of the wimp section, for example), there are
no coherent lists, and no guidance on choosing error numbers for your own code.
The documentation for SWIs also generally doesn't tell you if they can generate
errors, and if so, under what circumstances. The OS_Module documentation is a
partial exception to this, but it still doesn't tell you what the error numbers
are. Also, are registers preserved after errors? R0 obviously can't be, but are
other registers which are normally preserved still intact after an error?

  Another question is the extent to which SWIs should be error-trapped - are
they expected to validate their parameters, or just take them on faith? The
fact the I get address exceptions from OS_Module Enter, described above,
suggests the latter. On the other hand, if you try to OS_Release an unclaimed
vector you do get an error, whereas you might think it would just do nothing
and return silently. Either way, it would be nice if it were *documented*!

  That's all I can think of for now. I wonder if the RISC OS3 PRMs are any
better ...

e----><----p | Stephen Burke           | Internet: burke@vxdesy.desy.de
 H   H   1   | Gruppe FH1T (Liverpool) | DECnet:   vxdesy::burke (13313::burke)
 H   H  11   | DESY, Notkestrasse 85   | BITNET:   BURKE@DESYVAX or SB2@UKACRL
 HHHHH   1   | 2000 Hamburg 52         | JANET:    sb2@uk.ac.rl.ib
 H   H   1   | Germany                 | Phone:    + 49 40 8998 2282
 H   H 11111 | HERA, the world's largest electron microscope!