modcode.html

关于ARM汇编的非常好的教程

  <tr>
    <td> &amp;20
    <td> <a href="#swihandler">SWI handler code (<i>optional</i>)</a>

  <tr>
    <td> &amp;24
    <td> <a href="#switable">SWI decoding table (<i>optional</i>)</a>

  <tr>
    <td> &amp;28
    <td> <a href="#swicode">SWI decoding code (<i>optional</i>)</a>

  <tr>
    <td> &amp;2C
    <td> <a href="#messages">Messages file name (<i>optional</i>)</a>

  <tr>
    <td> &amp;2C
    <td> <a href="#flags">Module flags (<i>optional</i>)</a>

</table>

All modules <i>must</i> have the first seven fields. However, if they are not required then
the offset may be zero.<br>
The title string should <i>not</i> be zero. If it is, RISC OS will call the module
&quot;&lt;Untitled&gt;&quot;, and it will not be possible to reference the module.<br>
The SWI handler fields are optional, and are only used if they contain values that are
considered to be 'sensible' for the SWI handler use (ie, number is divisible by four, etc).
<p>&nbsp;<p>


This is an example of the header fields for FPEmulator version 4.14 (02/10/2000), as viewed in
!Zap:
<table bgcolor="#000000" width="100%" cellpadding=0 border=0 cellspacing=0>
  <tr><td> <b><code><font color="#FFFF00">00000000 :</font><font color="#FF0000"> 0000 :</font><font color="#FFAA00"> 00000000 :</font><font color="#00FF00"> Start offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000004 :</font><font color="#CCCCCC"> &#172;</font><font color="#FF0000">B00 :</font><font color="#FFAA00"> 000002AC :</font><font color="#00FF00"> Initialisation offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000008 :</font><font color="#CCCCCC"> &#156;</font><font color="#FF0000">C00 :</font><font color="#FFAA00"> 0000039C :</font><font color="#00FF00"> Finalisation offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">0000000C :</font><font color="#CCCCCC"> &#224;</font><font color="#FF0000">C00 :</font><font color="#FFAA00"> 000003E0 :</font><font color="#00FF00"> Service call handler offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000010 :</font><font color="#CCCCCC"> 8</font><font color="#FF0000">000 :</font><font color="#FFAA00"> 00000038 :</font><font color="#00FF00"> Title string offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000014 :</font><font color="#CCCCCC"> xu</font><font color="#FF0000">00 :</font><font color="#FFAA00"> 00007578 :</font><font color="#00FF00"> Help string offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000018 :</font><font color="#FF0000"> 0000 :</font><font color="#FFAA00"> 00000000 :</font><font color="#00FF00"> Help and command keyword table offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">0000001C :</font><font color="#CCCCCC"> &#128;</font><font color="#FF0000">DD0 :</font><font color="#FFAA00"> 00040480 :</font><font color="#00FF00"> SWI chunk base number</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000020 :</font><font color="#CCCCCC"> &#208;</font><font color="#FF0000">000 :</font><font color="#FFAA00"> 000000D0 :</font><font color="#00FF00"> SWI handler code offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000024 :</font><font color="#CCCCCC"> 8</font><font color="#FF0000">000 :</font><font color="#FFAA00"> 00000038 :</font><font color="#00FF00"> SWI decoding table offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">00000028 :</font><font color="#FF0000"> 0000 :</font><font color="#FFAA00"> 00000000 :</font><font color="#00FF00"> SWI decoding code offset</font></code></b>
  <tr><td> <b><code><font color="#FFFF00">0000002C :</font><font color="#FF0000"> 0000 :</font><font color="#FFAA00"> 00000000 :</font><font color="#00FF00"> Messages filename offset</font></code></b>
</table>
<p>&nbsp;<p>


<a name="start"></a>
<h2>Start code</h2>

This is used by OS_Module with Run or Enter codes.
<p>

<pre>  On entry:
    R0  = pointer to command string, including module name
    R12 = private word for the currently preferred instantiation

  On exit:
    Exit using OS_Exit, or by starting another application
    without having set up an exit handler.

  Processor status:
    IRQ is enabled on entry.
    FIQ is enabled.
    Processor is in USR mode.

  Re-entrancy:
    Entry point is not re-entrant.

  32-bit issues:
    Unchanged; flag preservation not required,
    only V is examined on exit
</pre>

This is the offset to code to call if the module is to be entered as the current application.
An offset of zero implies the code cannot be started this way (ie, it is purely a service
module, filing system, et cetera).
<p>

The field need not actually be an offset. If it cannot be interpreted as such, then calling
Run will actually execute what is assumed to be an instruction. This allows applications to
have a branch at this position to allow them to be run directly, ie for testing.
<p>

This is called by the <code>*RMRun</code> command.
<p>

One would assume that the Run field is mostly outdated. Way back when, Acorn thought that
all major pieces of software should be implemented as modules. Now, the current thinking is
a standard application written in C or another suitable high level language (suitable,
unfortunately, doesn't include BASIC - which is fair enough when considering DTP programs or
web browsers, as the interpretation does put a speed penalty on BASIC programs, not to
mention the lack of <i>struct</i>s and other nicities).
<p>

Whenever a module is entered in this way, it becomes the preferred instantiation.
<p>&nbsp;<p>


<a name="init"></a>
<h2>Initialisation code</h2>

This is used by OS_Module to initialise the module.
<p>

<pre>  On entry:
    R10 = environment string (command tail)
    R11 = where module has come from:
                      0 - Loaded from filing system (ie, *RMLoad)
             &gt;&30000000 - Loaded from podule (R11 is podule base address)
           Other values - Reincarnated, &lt;R11&gt; other incarnations exist
    R12 = Pointer to private word (if non-zero, implies reinitialisation)
    R13 = Supervisor stack

  On exit:
    Must preserve processor mode and interrupt state.
    R0 - R6, R12, R14 and flags (except V) can be corrupted.
    R7 - R11 and R13 must be preserved.
    Use R14 to return (ie, MOV PC,R14).

  Processor status:
    IRQ and FIQ are enabled.
    Processor is in SVC mode.

  Re-entrancy:
    Entry point is not re-entrant.

  32-bit issues:
    Undefined, would assume flag preservation not required.
</pre>

This is called when module loaded, or after an RMA 'tidy'. It is defined that a module will
not be called via any other entry point until after the initialisation code has been called.
Therefore, you should, here, set up sufficient (ie, claim workspace) to make it safe to call any
of the other entry points.<br>
Note that during initialisation, your module is not on the active modules list. If you need to
call your own SWIs, you must set up the expected environment and branch to the entry point
directly...or otherwise branch directly to the appropriate sections of code. Whichever you find
easiest to deal with.
<p>

The PRM says:<br>
&quot;<i>An offset of zero means the module does not need any initialisation. The operating
system does not provide any default actions.</i>&quot;<br>
It is difficult to follow exactly what &quot;An offset&quot; is referring to. My guess is the
contents of R10.
<p>

If the module is being re-entered after an RMTidy, the private word may be non-zero. This is the
contents of the private word prior to finalisation, relocated (if necessary) by the operating
system.
<p>

Typically, you'd claim workspace and set the private word to point to it. Otherwise, you
would link on to vectors or declare yourself if necessary (ie, a filing system).
<p>

A module can refuse to initialise. If an error is generated (set R0 to indicate the error
and return with V set), the operating system will automatically remove the module from the
RMA.
<p>&nbsp;<p>


<a name="fini"></a>
<h2>Finalisation code</h2>

Used for reinitialising, deleting, tidying, clearing, and also when a module of the same
name is loaded the old one is killed.

<pre>  On entry:
    R10 = Fatality indicator
            0 - non-fatal finalisation
            1 - fatal finalisation
    R11 = 'dynamic' incarnation number.
    R12 = Private word, for this instantiation.
    R13 = Supervisor stack.

  On exit:
    Must preserve processor mode and interrupt state.
    R0 - R6, R12, R14 and flags can be corrupted.
    R7 - R11 and R13 must be preserved.
    Use R14 to return (ie, MOV PC,R14).

  Processor status:
    IRQ is not altered.
    FIQ is enabled.
    Processor is in SVC mode.

  Re-entrancy:
    Entry point is not re-entrant.

  32-bit issues:
    Unchanged; flag preservation not required,
    only V is examined on exit
</pre>

You should <i>not</i> enable interrupts if they are off unless you can cope with being
entered via the service call handler at that stage.
<p>

If the call is fatal, the workspace will be freed and the workspace pointer is set to zero.
If the call is non-fatal (ie, a tidy), then the workspace/pointer will be relocated -
assuming they were allocated with OS_Module's Claim.
<p>

If the module generates an error, it remains in the RMA and is assumed to be initialised. The
only way to remove a module in this state is via a module killer utility, or hard-reset.
<p>

If you are refusing to die, set R0 and return with V set.<br>
Somehow, this behaviour is different to that of the above paragraph. The PRMs <i>could</i> have
been clearer on this.
<p>

The module is 'de-linked' during a finalisation call. You should not call your own SWIs or
commands.
<p>

If there is no finalisation entry, workspace is freed (if pointer is non-zero) and the
module is quit by the operating system.
<p>

R11 contains the dynamic instantitation number. It is called this because it is the position of
the instantiation in the instantiation list. However, position in the chain can vary, and the
length of the instantiation list can also change. In other words, this is pretty useless really.
<br>By the way, I've used the word <i>instantiation</i> five times in this paragraph!
<p>&nbsp;<p>


<a name="svccl"></a>
<h2>Service call handler</h2>

The service call handler is used to deal with service calls (<i>duh</i>!).
<p>

<pre>  On entry:
    R1  = Service number.
    R12 = Private word, for this instantiation.
    R13 = Supervisor stack.

  On exit:
    R1 can be zero to claim service.
    R0, R2-R8 may be used to pass back a result, depending
      upon service call. Registers must not be corrupted
      unless they are returning values.
    R12 may be corrupted.
    Other constraints depend upon the service.
    Use R14 to return.

  Processor status:
    IRQ is not altered.
    FIQ is enabled.
    Processor is in SVC or IRQ mode (depending on service).

  Re-entrancy:
    Entry point may be re-entered by RISC OS. You must be
    able to handle this.

  32-bit issues:
    Unchanged; flags ignored on exit
</pre>

This allows service calls to be recognised and dealt with. An offset of zero implies that
the module is not interested in service calls.
<p>

You can:
<ul>
  <li> Claim the service<br>
       Set R1 to zero before exiting.
 
  <li> Deal with the service, and pass it on<br>
       Restore registers before exiting.

  <li> Ignore the service<br>
       Simply return, registers unaltered.
</ul>
<p>

It is important that you reject unwanted service calls as quickly as possible. The PRM gives
the following example (which, note, is NOT 32-bit compliant, but can be made so fairly easily):
<pre><font size = 2>
.service_call_handler
  TEQ     R1, #Service_&lt;1&gt;
  TEQNE   R1, #Service_&lt;2&gt;
  TEQNE   R1, #Service_&lt;3&gt;
  MOVNES  PC, R14                  ; reject unrecognised asap

  STMFD   R13!, { <i>registers</i>, R14 }
  LDR     R12, [R12]               ; if workspace pointer required

  TEQ     R1, #Service_&lt;3&gt;         ; find out which we've got
  BEQ     svc_3
  TEQ     R1, #Service_&lt;2&gt;
  BEQ     svc_2

.svc_1
  code to handle service call 1    ; if not 3 or 2, must be 1
  LDMFD   R13!, { <i>registers</i>, PC }^ ; and return
                                     <font color="red">(not 32-bit friendly)</font>
.svc_2
  code to handle service call 2
  LDMFD   R13!, { <i>registers</i>, PC }^ ; and return
                                     <font color="red">(not 32-bit friendly)</font>
.svc_3
  code to handle service call 3
  LDMFD   R13!, { <i>registers</i>, PC }^ ; and return
                                     <font color="red">(not 32-bit friendly)</font>
</font></pre>

You may be able to change the <code>LDMFD R13!, { ... }^</code> to a 32-bit friendly version.
Refer to the documentation for the service call required to see if flags should be preserved.
<p>

Some service calls indicate errors by setting registers on exit (the V set convention cannot be
used). Others (like unknown OS_Byte) can either claim it (no error will be given) or ignore it
(error will be given if nothing claims it). Thus, if you wish to provide things like unknown
OS_Bytes and generate errors for stuff like invalid parameters, you should use the OS_Byte vector
instead.
<p>

Only R0-R8 can be passed to a service call.
<p>&nbsp;<p> 


<a name="title"></a>
<h2>Title string</h2>

Used by OS_Module for referring to the module by name, and printed by the
<code>*Modules</code> command.<br>
It is a null terminated string which should be fairly short, yet descriptive. You should
follow the system convention for module names (ie, &quot;WindowManager&quot;,
&quot;SharedCLibrary&quot;, &quot;Debugger&quot;).
<p>&nbsp;<p>


<a name="help"></a>
<h2>Help string</h2>

This is a null terminated string printed by <code>*Help</code> before any information from
the module, for example <code>*Help Modules</code> or <code>*Help &lt;modulename&gt;</code>.
<br>
The string should not contain any control characters, save space and tab (which will tab to
the next multiple of eight column).<br>
The format should be:<br>
<code>&lt;modulename&gt;[&lt;TAB&gt;(if necessary)]v.vv (DD MMM YYYY)</code><br>
For example:
<pre>IDEFS           1.11e (20 Oct 1999)
ROM Patches     2.02 (24-Feb-97)
IDEFSFiler      1.09 (07 May 1998)
MyProtection    0.01 (19 Apr 1999)
Extended assem  1.77 (01 Mar 1998)