OSHeap_Resize Should Have R3 as Output.

[Tony van der Hoff]

On 5 Nov 2001, in message <f2f9a0d44a.kbracey at kbracey.cam.pace.co.uk>,
Kevin Bracey <kevin.bracey at pace.co.uk> wrote:

> In message <200111032244.WAA05203 at inputplus.demon.co.uk>
>           Ralph Corderoy <ralph at inputplus.demon.co.uk> wrote:
> 
> > OSLib's entry doesn't match the PRM WRT R3.
> > 
> >     SWI OSHeap_Resize =
> >        (  NUMBER &1D,
> >           ENTRY
> >           (  R0 # 5 "Extends or shrinks a heap (PRM 1-375)",
> >              R1 = .Ref .Data: heap,
> >              R3 = .Int: size_increase
> >           )
> >        );
> > 
> >     OS_Heap 5 (SWI &1D)
> > 
> >     Extend or shrink heap
> > 
> >     On entry
> >         R0 = 5 (reason code)
> >         R1 = pointer to heap
> >         R3 = required size change in bytes (signed integer)
> > 
> >     On exit
> >         R0, R1 preserved
> >         R3 preserved, or amount of bytes heap shrunk by if requested
> >         shrink failed
> > 
> >     Use
> >         This updates the heap size information to take account of the
> >         new size. If the heap cannot shrink as far as requested -
> >         because of data that has already been allocated - it will
> >         shrink as far as possible, set R3 to the amount by which it
> >         shrank, and return an error.
> > 
> > Is this a bug or a sign of my unfamiliarity with OSLib's ways.
> > 
> 
> OSLib veneers won't update any return registers in the event of an error,
> which is unfortunate for SWIs like OS_Heap 5 or OS_ChangeDynamicArea. I'd
> imagine this is why R3 return has been omitted.
> 
It is. For your purposes, it wouldn't do any harm to declare R3 as an exit
register, but this would not be in line with OSLib's conventions (it's
"preserved", so doesn't need a declaration). It would be potentially
confusing to a user who expected from the stronghelp manual to get a return
value if the SWI returned an error.

In the overwhelming majority of cases an error return from a SWI indicates
that all bets are off. It wouldn't have been unreasonable for the OS to
return the shrunk amount in R3 in any case, without throwing an error, and
expect the client to make the comparison, but that's not what was done.  We
had to patch round this for OS_ReadVarVal, and I guess we could do something
similar here, if there was demand for it. It would be possible to define new
veneers, say OSHeap_ResizeReturnAmount, and OS_ChangeDynamicAreaReturnAmount,
which could interpret any error return, and if appropriate, then return R3
with V clear, and R0 preserved, as if no error occurred.

Is this worth doing?

-- 
Tony van der Hoff         | MailTo:tony at mk-net.demon.co.uk
                          | MailTo:avanderhoff at iee.org
Buckinghamshire, England  | http:www.mk-net.demon.co.uk