QDOS+ Register conventions

EXEC and MT_CJOB

Each EXEC/MT_CJOB transient program area is activated in the state:

   (A6,A5.L)   +-------------------+
        high   | Command string    |  } If A6+A5>A7, parameters from
        address+-------------------+  }
               | .L Channel ID     |  } the jobs parent job.
               | ...               |  }
               | .L Channel ID     |  }
               +-------------------+  } (EXEC/EXEC_W leave A6+A5=A7.)
               | .? Number of      |  }
   (A7) i.e.USP|    Channel IDs    |  }
               +-------------------+
               | Stack area/       |  The jobs stack is the top
   (A6,A4.L)   | Data area         |
               +-=-=-=-=-=-=-=-=-=-+  part of the data area.
               | Code area         |
   Even address+-------------------+
               | .Bs Job Name      |  If the job name has an odd number
               | .W #chars in j.n. |
               | .W $4AFB          |  of characters, it's followed by
        low    | JMP.L start       |
   (A6) address+-------------------+  an (ignored) 'pad' character.

The stack usually runs from the top of the data area downwards, except that the various ways of loading can imply differing numbers of zeros already on the stack when the program is started.

TALENT WORKBENCH does not appear to implement the A4 and A5 conventions.

The A6 convention is of great use to circumvent the problem that instructions that store to memory may not have PC-related addresses, i.e. may not have addresses of either of the forms:

• d16(PC) or
• d8(PC,R)

EX & EW

See Toolkit II documentation.

Basic extensions

Defining extra routines

Call BP_INIT (qv) to link in the new routine(s).

1. The SuperBASIC program area can be moved at any time, so all references in the area must be A6- or A7-relative: don't save A6 or A7 except in arithmetic or address calculations: don't alter them (except A7 by PUSHes and POPs). [But can use TRAP#0 to go into supervisor mode to make following code uninteruptable - this is not a normal practice.]
2. Don't use more than 128 bytes of user stack.
3. D0.L must be returned as an error code.
4. D1-5 and A0-5 can be spoilt: DO NOT SPOIL D6 D7 A6 or A7.

...is by substitution:

1. The interpreter evaluates any expression parameters;
2. Each actual is then given a new entry at the top of the name table - if the routine is written in SuperBASIC, any missing actual gets a null entry;
3. The interpreter then swaps the new name table entries with the old entries for the actuals;
4. If the routine is written in machine code, it is CALLed with A3->NTE of first parameter in the list, and A5->[?just after] the NTE of the last parameter. [So there will be (A5-A3)/8 parameters.]
5. If a LOCal statement is found, the NTE is copied to the top of the name table, and the original NTE is replaced by an empty entry.
6. At the end of SuperBASIC routine, the parameter enties are copied back and local entries removed. The parameter NTEs and any temporary storage in the variable value area are then removed for all routines.

Use CA_GTINT (.W integer) CA_GTFP (f.p.) CA_GTSTR (string) CA_GTLIN (f.p. converted to .L integer). Each needs A3 to base of & A5 to end of the NTEs of the parameters, assumes the parameters are of the same type, and returns the # of parameters fetched, with their values on the RI stack. Separator flags are spoilt.

For unquoted strings (i.e. SuperBASIC names to be used literally - e.g. as file names) the caller of CA_GTSTR must do as follows:

1. Inspect the name to see if it is a valid set string variable.
2. If so, fetch it with CA_GTSTR;
3. otherwise, fetch the parameter's name itself from the name list, converting to string form by changing the word count from byte to word, and realigning the string if necessary.

Entries on the stack must be word-aligned. So for a string

1. the character count must be on a word boundary; and
2. odd-length strings have a final padding byte, whose value is ignored.

TOS is usually pointed to by A1. Space can be allocated by BV_CHRIX. The vectored routines for getting results to RI stack do their own space-allocation. RI stack is automatically tidied after procedures and after errors in functions.

On return from a function the returned value should be the topmost (i.e. lowest address) with nothing below it, and both (A6,A1.L) and BV_RIP(A6) pointing to it. The result type should be in D4 (1=string, 2=fp, 3=.W integer, with .L integers converted to f.p. before the RETurn).

Results can be passed back in parameters by pointing A3 to the NTE and calling BP_LET. If the actual was an expression, BP_LET doesn't give an error, and the result value is lost. The type of the result is given by the NTE, and the value on the RI stack must be in the correct form for that type.

Last updated 4th January 1999. Back to my QL home page Disclaimer