lib/hachti/src/stack.asm

   1 * H316 SAFE SOFTWARE STACK, REV. 0.1
   2 *
   3 *
   4 * AUTHOR:
   5 *
   6 *       PHILIPP HACHTMANN, 2007
   7 *
   8 * VERSIONS:
   9 *
  10 *               0.1 - INITIAL REVISION (22.12.2007)
  11 *
  12 * PURPOSE:
  13 *
  14 *       TO PROVIDE A MULTI-PURPOSE STACK MECHANISM
  15 *       TO PROVIDE A SPECIAL-PURPOSE STACK MECHANISM FOR RECURSIVE
  16 *       PROGRAM CALLS
  17 *
  18 * THEORY OF OPERATION:
  19 *
  20 * THE STACK ROUTINES MAINTAIN AN UPWARDS GROWING STACK.
  21 * EVERY USAGE CONTEXT OF THE STACK NEEDS TO RESERVE THE SPACE FOR
  22 * ITS STACK'S DATA. THIS ENABLES THE PROGRAMMER TO CHOOSE THE STACK
  23 * SIZE AND USE MULTIPLE STACKS IN MULTIPLE PLACES INDEPENDENTLY.
  24 * ALL STACK RELATED ROUTINES TAKE A POINTER TO THE STACK'S INTERNAL
  25 * DATA AS FIRST ARGUMENT.
  26 *
  27 * THE DATA LAYOUT OF THE STACK DATA IS AS FOLLOWING:
  28 *
  29 * SIZE  OCT     '1000   SIZE OF THE STACK IN MACHINE WORDS
  30 * PTR   DAC     **      THE STACK POINTER
  31 * FILL  DAC     **      THE FILL COUNTER
  32 * OVER  DAC     OFL     OPTIONAL POINTER TO OVERFLOW ERROR ROUTINE
  33 * UNDR  DAC     UFL     OPTIONAL POINTER TO UNDERFLOW ERROR ROUTINE
  34 * STCK  BSS     '1000   THE STACK DATA
  35 *
  36 * IF CUSTOM ERROR HANDLING ROUTINES ARE NOT TO BE USED, SET THE TWO
  37 * POINTER LOCATIONS TO ZERO. THEN, INTERNAL ERROR ROUTINES WILL BE
  38 * USED. SIZE AND THE FUNCTION POINTERS HAVE TO BE INITIALISED. THE
  39 * OTHER LOCATIONS ARE INITIALISED BY THE STACK ROUTINES.
  40 *
  41 * USAGE:
  42 *
  43 * INITIALISING STACK POINTER:
  44 *
  45 *       CALL    S$INIT
  46 *       DAC     SDATA   STACK DATA
  47 *       DAC     SSIZ    DATA SIZE (NOT STACK DEPTH!!!)
  48 *       DAC     0
  49 *
  50 * PUSHING AND POPPING THE A-REGISTER FROM AND TO THE STACK:
  51 *
  52 *       CALL    S$PUSH  VALUE IN A REGISTER IS PUSHED.
  53 *       DAC     SDATA
  54 *
  55 *       CALL    $$POP  VALUE FROM STACK IS POPPED INTO A-REGISTER.
  56 *       DAC     SDATA
  57 *
  58 * PUSHING AND POPPING ARBITRARY DATA FROM AND TO THE STACK:
  59 *
  60 *       CALL    S$PUSM
  61 *       DAC     SDATA
  62 *       DAC     ADDRESS
  63 *       OCT     SIZE
  64 *
  65 *       CALL    S$POPM
  66 *       DAC     SDATA
  67 *       DAC     ADDRESS
  68 *       OCT     SIZE
  69 *
  70 *
  71 * MAKING A RECURSIVE CALL FROM FORTRAN IV TO A FORTRAN IV OR OTHER ROUTINE:
  72 *
  73 * THE ROUTINE S$CALL SAVES A SET OF LOCAL VARIABLES ONTO THE STACK.
  74 * IT ALSO SAVES THE RETURN ADDRESS AND ITS OWN PARAMETERS.
  75 * S$LLAC DOES EVERYTHING IN REVERSE ORDER.
  76 *
  77 * HERE IS AN EXAMPLE HOW TO USE THE TWO ROUTINES IN FORTRAN IV:
  78 *
  79 * C LOCAL VARIABLES I(3),A,Z TO SAVE
  80 *
  81 *       CALL S$CALL(3,I,3,A,2,Z,2)
  82 *       RETURN    <-- FOR THE RETURN ADDRESS OF THE CURRENT ROUTINE
  83 *       CALL MYROUTINE(...)
  84 *       CALL S$LLAC
  85 *
  86 * ASSEMBLER CALLING SEQUENCE:
  87 *
  88 *       JST     S$CALL
  89 *       DAC     VARNO  NO OF LOCAL VARIABLES TO SAVE ON THE STACK
  90 *       DAC     VAR1   POINTER TO FIRST VARIABLE
  91 *       DAC     SIZE1  WORD SIZE OF VARIABLE
  92 *       ...
  93 *       DAC     VARN    POINTER TO LAST VARIABLE
  94 *       DAC     SIZEN   WORD SIZE OF LAST VARIABLE
  95 *       DAC     0       FORTRAN IV COMPILER GENERATED
  96 *
  97 *       JMP*    PROC    RETURN JUMP, GENERATED BY THE "RETURN" STATEMENT
  98 *
  99 *       JST     MYROUTINE
 100 *       ...
 101 *
 102 *       JST     S$LLAC
 103 *
 104 *
 105 ********************************************************************************
 106 *
 107 *
 108 **** SYMBOL DECLARATIONS
 109 *
 110         SUBR    STACK,SBUF      JUST A LABEL FOR THE OBJECT TAPE
 111         SUBR    S$INIT,INIT     INITIALIZATION
 112         SUBR    S$PUSH,PUSH     SINGLE WORD PUSH
 113         SUBR    S$POP,POP       SINGLE WORD POP
 114         SUBR    S$PUSM,PUSM     MEMORY RANGE PUSH
 115         SUBR    S$POPM,POPM     MEMORY RANGE POP
 116         SUBR    S$PTR,SPTR      STACK POINTER ACCESS
 117         SUBR    S$CALL,CALL
 118         SUBR    S$LLAC,LLAC
 119 *
 120 *
 121 ********************************************************************************
 122 *
 123 *
 124         REL             RELOCATEABLE OBJECT
 125 *
 126 *
 127 ********************************************************************************
 128 *
 129 * *** PUSH MEMORY RANGE TO STACK
 130 *
 131 PUSM    DAC     **      ENTRY POINT TO PUSH ROUTINE
 132         STA     ATM1    SAVE A-REGISTER
 133 *
 134         LDA*    PUSM    LOAD DATA BASE
 135         IRS     PUSM
 136         STA     DPT     SAVE FOR LATER USE
 137 *
 138         LDA*    PUSM    LOAD POINTER
 139         STA     PTR     STORE TO TRANSFER POINTER
 140         IRS     PUSM    GO TO NEXT ARGUMENT
 141         LDA*    PUSM    LOAD TRANSFER SIZE
 142         IRS     PUSM    CORRECT RETURN ADDRESS
 143 *
 144         TCA             NEGATE WORD COUNT
 145         STA     CNT     STORE TO COUNTER
 146 *
 147 PULP    LDA*    PTR     GET DATA
 148         JST     PUSH    PUSH IT!
 149 DPT     DAC     **
 150 *
 151         IRS     PTR     INCREMENT POINTER
 152         IRS     CNT     INCREMENT BYTE COUNTER
 153         JMP     PULP    DO IT AGAIN!
 154 *
 155         LDA     ATM1    RESTORE A-REG
 156         JMP*    PUSM    RETURN
 157 *
 158 *
 159 ********************************************************************************
 160 *
 161 *
 162 **** POP MEMORY RANGE FROM STACK
 163 *
 164 POPM    DAC     **      ENTRY POINT TO PUSH ROUTINE
 165         STA     ATM1    SAVE A-REGISTER
 166 *
 167         LDA*    POPM    GET DATA POINTER
 168         IRS     POPM
 169         STA     DPTR    STORE FOR LATER USE
 170 *
 171         LDA*    POPM    LOAD POINTER
 172         IRS     POPM    GO TO NEXT ARGUMENT
 173         ADD*    POPM    ADD TRANSFER SIZE
 174         SUB     =1      SUBSTRACT 1 TO GET HIGH ADDRESS
 175         STA     PTR     STORE TO TRANSFER POINTER
 176         LDA*    POPM    LOAD TRANSFER SIZE
 177         IRS     POPM    CORRECT RETURN ADDRESS
 178 *
 179         TCA             NEGATE WORD COUNT
 180         STA     CNT     STORE TO COUNTER
 181 *
 182 POLP    JST     POP     POP DATA FROM THE STACK
 183 DPTR    DAC     **
 184 *
 185         STA*    PTR     STORE IT.
 186         LDA     PTR
 187         SUB     =1      DECREMENT
 188         STA     PTR     WRITE BACK
 189         IRS     CNT     INCREMENT BYTE COUNTER
 190         JMP     POLP    DO IT AGAIN!
 191 *
 192         LDA     ATM1    RESTORE A-REG
 193         JMP*    POPM    RETURN
 194 *
 195 *
 196 ********************************************************************************
 197 *
 198 *
 199 **** PUSH SINGLE WORD ONTO STACK
 200 *
 201         SUBR    PUSH
 202 PUSH    DAC     **      REAL PUSH ROUTINE - PUSH AC TO STACK.
 203 *
 204         STX     XTM     SAVE X REGISTER
 205         STA     ATM2    SAVE A REGISTER
 206 *
 207         LDX*    PUSH    LOAD INDEX REGISTER WITH DATA BASE
 208         IRS     PUSH
 209 *
 210         LDA     FILL,1  LOAD FILL SIZE
 211         CAS     SSIZ,1  COMPARE STACK SIZE
 212         NOP
 213         JST     OFLO    OVERFLOW!
 214 *
 215         LDA     ATM2
 216         STA*    SPTR,1  NO OVERFLOW, PUT DATA ONTO STACK
 217         IRS     SPTR,1  INCREMENT STACK POINTER
 218         IRS     FILL,1  INCREMENT FILL SIZE
 219 *
 220         LDX     XTM     RESTORE X REGISTER
 221         LDA     ATM2
 222         JMP*    PUSH    RETURN WITH A-REG UNALTERED.
 223 *
 224 *
 225 ********************************************************************************
 226 *
 227 *
 228 **** POP SINGLE WORD FROM STACK
 229 *
 230 POP     DAC     **      REAL POP ROUTINE - POP AC FROM STACK.
 231 *
 232         STX     XTM     SAVE X REGISTER
 233         LDX*    POP     LOAD INDEX REGISTER WITH DATA BASE
 234         IRS     POP
 235 *
 236         LDA     FILL,1  FILL SIZE
 237         SNZ
 238         JST     UFLO    NOTHING INSIDE? SKIP!
 239 *
 240         LDA     SPTR,1  LOAD STACK POINTER
 241         SUB     =1      DECREMENT IT TO LAST USED LOCATION
 242         STA     SPTR,1  SAVE IT BACK
 243         LDA     FILL,1
 244         SUB     =1
 245         STA     FILL,1  DECREMENT FILL SIZE
 246 *
 247         LDA*    SPTR,1  LOAD VALUE FROM THE STACK
 248         LDX     XTM     RESTORE INDEX REGISTER
 249         JMP*    POP     RETURN.
 250 *
 251 *
 252 ********************************************************************************
 253 *
 254 *
 255 **** INITIALIZATION
 256 *
 257 INIT    DAC     **      INITIALIZE STACK
 258         STA     ATM1
 259         STX     XTM
 260 *
 261         LDX*    INIT
 262 *
 263         LDA     VARS    SIZE OF MANAGEMENT VARIABLES
 264         ADD*    INIT    BASE ADDRESS
 265         STA     SPTR,1  SAVE TO STACK POINTER
 266         IRS     INIT
 267 *
 268         LDA*    INIT    LOAD DATA POOL SIZE POINTER
 269         STA     PTR     DEREFERENCE POINTER
 270         LDA*    PTR     LOAD DATA POOL SIZE
 271         SUB     VARS    VARIABLE SIZE
 272         STA     SSIZ,1  SAVE TO STACK DEPTH
 273 *
 274         CRA
 275         STA     FILL,1
 276 *
 277         LDA     ATM1
 278         LDX     XTM
 279         IRS     INIT
 280         IRS     INIT    FOR FORTRAN COMPATIBILITY
 281         JMP*    INIT
 282 *
 283 *
 284 ********************************************************************************
 285 *
 286 *
 287 **** ERROR HANDLING ROUTINES
 288 *
 289         SUBR    OFLO
 290 OFLO    DAC     **      STACK OVERFLOW ROUTINE
 291         LDA     OMSP    LOAD OVERFLOW MESSAGE POINTER
 292         JST     TYPE    TYPE IT OUT.
 293 *
 294         HLT             WHAT WE DO: HALT THE MACHINE.
 295         JMP     *-1     YOU CANNOT SIMPLY LEAVE THIS, IT'S SERIOUS!
 296 *
 297 *
 298 ****************************************
 299 *
 300 *
 301         SUBR    UFLO
 302 UFLO    DAC     **      STACK OVERFLOW ROUTINE
 303         LDA     UMSP    LOAD OVERFLOW MESSAGE POINTER
 304         JST     TYPE    TYPE IT OUT.
 305 *
 306         HLT             WHAT WE DO: HALT THE MACHINE.
 307         JMP     *-1     YOU CANNOT SIMPLY LEAVE THIS, IT'S SERIOUS!
 308 *
 309 *
 310 ****************************************
 311 *
 312 *
 313         SUBR    TYPE
 314 TYPE    DAC     **
 315         SKS     '104    TEST ASR READY
 316         JMP     *-1     WAIT TO BECOME READY
 317         OCP     '104    SET TO OUTPUT MODE
 318 *
 319         STA     PTR     STORE POINTER
 320 *
 321 TLOP    LDA*    PTR     TYPE LOOP
 322         SNZ             TEST FOR END
 323         JMP*    TYPE    RETURN
 324         ICA
 325         OTA     '4
 326         JMP     *-1
 327         ICA
 328         OTA     '4
 329         JMP     *-1
 330         SKS     '104    ADDITIONAL TEST FOR READY
 331         JMP     *-1
 332         IRS     PTR     NEXT WORD.
 333         JMP     TLOP
 334 *
 335 *
 336 ********************************************************************************
 337 *
 338 *
 339 ***** VARIABLES
 340 *
 341 *
 342 PTR     DEC     0       TRANSFER POINTER TO USER BUFFERS
 343 CNT     DEC     0       TRANSFER COUNTER
 344 *
 345 ATM1    DEC     0       A-REGISTER BACKUP
 346 ATM2    DEC     0       A-REGISTER BACKUP
 347 XTM     DEC     0       X-REGISTER BACKUP
 348 *
 349 *
 350 ***** CONSTANTS
 351 *
 352 VARS    DEC     3       SIZE OF VARIABLES AT BEGINNING OF DATA
 353 *
 354 SSIZ    EQU     0
 355 SPTR    EQU     1
 356 FILL    EQU     2
 357 *
 358 OMSP    DAC     OMSG            POINTER TO MESSAGE
 359 UMSP    DAC     UMSG            POINTER TO MESSAGE
 360 OMSG    OCT     '006412         CR/LF CHARACTERS
 361         BCI     16,STACK OVERFLOW, YOUR'RE SCREWED!
 362         DEC     0               TERMINATION CHARACTER
 363 UMSG    OCT     '006412         CR/LF CHARACTERS
 364         BCI     17,STACK UNDERFLOW, YOUR'RE SCREWED!
 365         DEC     0               TERMINATION CHARACTER
 366 *
 367 *
 368 ********************************************************************************
 369 *
 370 *
 371         END                     THAT'S IT.