;—————————————————————————————————————————————————————————
; pushparm parm1 [,parm2 [,parmN]],mode1 [,mode2 [,modeN]]
;
; This macro generates a parameter stack frame.  The frame
; consists of 1 or more 32-bit values, pushed in big-end-
; ian order (which places the LSW on the stack below the
; MSW).  Parameters are pushed from right to left; PARM1
; will be the lowest on the stack.  Below PARM1 will be a
; word value that indicates the number of words that
; were pushed, e.g.:
;
;   pushparm addr1,addr2,addr3,'f','f','f'
;
; will produce the following stack frame:
;
;   addr3 (MSW)
;   addr3 (LSW)
;   addr2 (MSW)
;   addr2 (LSW)
;   addr1 (MSW)
;   addr1 (LSW)
;   $0006 (words pushed)
;
; For each parameter in the invocation, a corresponding
; mode must be passed.  Recognized modes are:
;
;   'd'  The corresponding parameter is a direct-page
;        address from which the value to be pushed will
;        be fetched.  The resulting instruction sequence
;        will be:
;
;          PEI <parm>+2
;          PEI <parm>
;
;   'f'  The corresponding parameter is a value that is
;        to be processed as a “far” address.  The resul-
;        ting instruction sequence will be:
;
;          PEA #<parm> >> 16
;          PEA #<parm> & $FFFF
;
;   'n'  The corresponding parameter is to be processed
;        as a “near” address.  The resulting instruction
;        sequence will be:
;
;          PHK
;          PHK
;          PER <parm> & $FFFF
;
;        Note that although the execution bank is pushed
;        twice, the extra push is ignored during indi-
;        rect long addressing.  Also note that if <parm>
;        is specified as a 24- or 32-bit address, only the
;        LSW will be processed, since PER is bound to the
;        execution bank.
;
;   'r'  The corresponding parameter is assumed to be in
;        the index registers, .X = LSW & .Y = MSW.  The
;        index registers must be set to 16-bits —— there
;        is no check for this.  The corresponding parame-
;        ter is ignored, but is required for syntax rea-
;        sons.  It is recommended that it be $00 to make
;        it clear that the value being processed is being
;        passed in the registers.  Although of limited
;        value, this mode may be used multiple times.
;
;   Modes are case-insensitive; 'N' & 'n' are functionally
;   identical.
;—————————————————————————————————————————————————————————
;
pushparm   .macro ...
.tp      =@0
         .if .tp @ 2
             .error ""+@0$+": parameter & mode counts mismatch"
         .endif
         .if .tp == 0
             .error "syntax: "+@0$+" parm1 [,parm2 [,parmN]],mode1 [,mode2 [,modeN]]"
         .endif
.np      =.tp/2
.ix      .set .np
         .rept .np
.m           .= @{.ix+.np} | %00100000
             .if .m == 'd'
                 .if @.ix > $ff
                     .error ""+@0$+": 'd' mode requires direct page address parameter"
                 .endif
                 pei {@.ix}+2
                 pei @.ix
             .else
                 .if .m == 'f'
                     pea #{@.ix} >> 16
                     pea #{@.ix} & $ffff
                 .else
                     .if .m == 'n'
                         phk
                         phk
                         per {@.ix} & $ffff
                     .else
                         .if .m == 'r'
                             phy
                             phx
                         .else
                             .error ""+@0$+": mode must be 'd', 'f', 'n' or 'r'"
                         .endif
                     .endif
                 .endif
             .endif
.ix          .= .ix-1
         .endr
         pea #.np*2
         .endm

#$12 ——> $BFFF (SP)
#$AB ——> $BFFE (SP-1)

;reserve 16 bytes of workspace on the 65C816 stack
;
;   ———————————————————————————————————————————————————————————
;   In this example, it is assumed that SP == $BFFF upon entry.
;   Hex numbers in parentheses are the value of SP after the
;   operation has been performed.
;   ———————————————————————————————————————————————————————————
;
         phd                   ;save current direct page    (BFFD)
         rep #%00100000        ;select wide accumulator
         sec
         tsc                   ;SP ——> accumulator
         sbc !#16              ;reserve workspace
         tcs                   ;accumulator ——> SP          (BFED)
         inc A                 ;accumulator ++
         tcd                   ;accumulator ——> DP

         ———————————————————————————————————————————————————————————
         At this point, direct page is on the stack, starting at
         $BFEE.  An instruction such as LDA $00 will actually load
         from $BFEE, LDA $01 would be loaded from $BFEF, etc.  As
         DP (direct page pointer) is not page-aligned, there will
         be a 1 cycle penalty per access.  In practice, this penalty
         is a trivial price to pay for the convenience of being able
         to address stack content with direct-page instructions.

         Note that DP’s entry value may be fetched with LDA $10,
         which will be loaded from $BFFE.
         ———————————————————————————————————————————————————————————

;   when done, do stack housekeeping...
;
         rep #%00100000        ;just in case...
         lda $10               ;DP’s entry value
         tcd                   ;restore it
         clc
         tsc                   ;SP ——> accumulator          (BFED)
         adc !#16+2            ;discard workspace & stack copy of DP
         tcs                   ;accumulator ——> SP          (BFFF)

;===============================================================================
;
;blkread: READ FROM SCSI BLOCK DEVICE
———————————————————————————————————————————————————————————————————————
;   Invocation example: pea #buf >> 16         ;buffer pointer MSW
;                       pea #buf & $ffff       ;buffer pointer LSW
;                       pea #nblk >> 16        ;block count pointer MSW
;                       pea #nblk & $ffff      ;block count pointer LSW
;                       pea #lba >> 16         ;LBA pointer MSW
;                       pea #lba & $ffff       ;LBA pointer LSW
;                       pea #scsi_id >> 16     ;device ID pointer MSW
;                       pea #scsi_id & $ffff   ;device ID pointer LSW
;                       .IF .DEF(_SCSI_)
;                       JSL blkread
;                       .ELSE
;                       JSR blkread
;                       .ENDIF
;                       BCS ERROR
———————————————————————————————————————————————————————————————————————
;
blkread  clc                   ;assume no error
         php                   ;save machine state
         rep #m_setr | sr_bdm  ;16-bit registers & binary math
         phy
         phx
         pha
         phb
         phd
;
;—————————————————————————————————————————————————————————
;
;LOCAL DEFINITIONS
;
.maxblk  =128                  ;max blocks per transaction +1
.sfbase  .= 0                  ;base stack index (assembly-time variable)
.sfidx   .= .sfbase            ;workspace index (assembly-time variable)
;
;—————————> workspace stack frame start <—————————
;
.cdbptr  =.sfidx               ;local CDB pointer (16 bits)
.sfidx   .= .sfidx+s_ptr
.lbaflag =.sfidx               ;$8080 = 32-bit LBA (16 bits)
.sfidx   .= .sfidx+s_word
.nblks   =.sfidx               ;requested blocks (16 bits)
.sfidx   .= .sfidx+s_word
;
;—————————> workspace stack frame end <—————————
;
.s_wsf   =.sfidx-.sfbase       ;workspace size
.sfbase  .= .sfidx
;
;—————————> register stack frame start <—————————
;
.reg_dp  =.sfidx               ;DP
.sfidx   .= .sfidx+s_mpudpx
.reg_db  =.sfidx               ;DB
.sfidx   .= .sfidx+s_mpudbx
.reg_c   =.sfidx               ;.C
.sfidx   .= .sfidx+s_word
.reg_x   =.sfidx               ;.X
.sfidx   .= .sfidx+s_word
.reg_y   =.sfidx               ;.Y
.sfidx   .= .sfidx+s_word
.reg_sr  =.sfidx               ;SR
.sfidx   .= .sfidx+s_mpusrx
.reg_pc  =.sfidx               ;PC
.sfidx   .= .sfidx+s_mpupcx
         .if .def(_SCSI_)      ;if using remote calls...
.reg_pb      =.sfidx           ;PB
.sfidx       .= .sfidx+s_mpupbx
         .endif
;
;—————————> register stack frame end <—————————
;
.s_rsf   =.sfidx-.sfbase       ;register frame size
.sfbase  .= .sfidx
;
;—————————> parameter stack frame start <—————————
;
.idptr   =.sfidx               ;*SCSI_ID
.sfidx   .= .sfidx+s_dptr
.lbaptr  =.sfidx               ;*LBA
.sfidx   .= .sfidx+s_dptr
.nblkptr =.sfidx               ;*NBLK
.sfidx   .= .sfidx+s_dptr
.bufptr  =.sfidx               ;*BUF
.sfidx   .= .sfidx+s_dptr
;
;—————————> parameter stack frame end <—————————
;
.s_psf   =.sfidx-.sfbase       ;parameter frame size
;—————————————————————————————————————————————————————————
;
         pea #$00
         plb
         plb                   ;configure data bank...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-
;         As local fetches & stores are to the stack, PB
;         is set to bank $00 to avoid long addressing.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-
;
         sec
         tsc                   ;SP ——> .C
         sbc !#.s_wsf          ;allocate workspace...
         tcs                   ;for local variables
         inc                   ;point direct page to...
         tcd                   ;workspace...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;         Note that the above sequence makes the temporary
;         direct page zero-based for convenience.  Also,
;         fetches & stores from the stack copies of the
;         entry registers are possible using DP addressing,
;         e.g.:
;
;            LDA #sr_car
;            TSB .reg_sr
;
;         to set carry in the returned status register.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;
         tsc                   ;SP ——> .C
         sbc !#s_cdbg2         ;allocate space for...
         tcs                   ;local CDB...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;         The above allocates sufficient space to accommodate
;         a CDB defined for a short or long read operation.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;
         inc
         sta .cdbptr           ;local CDB pointer LSW
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-
;         The pointer MSW is implied because the CDB
;         is on the stack & hence is in bank $00.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-

          ...etc...

;   ———————————
;   COMMON EXIT
;   ———————————
;
.done    rep #m_setr | sr_car  ;16-bit registers & clear carry
         tsc                   ;SP ——> .C
         adc !#.s_wsf+s_cdbg2  ;total size of local workspace...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;         Note that .S_WSF was earlier set in the stack frame definitions
;         section.  S_CDBG2 is defined in ~/include/scsi/atomic.asm & is
;         the size of a group 2 command descriptor block.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;
         tcs                   ;.C ——> SP, expunges workspace
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;         Next, we “rebalance” the stack.  The procedure is to move the
;         the register frame up in the stack so the top of the frame is
;         immediately below the return address, then reset SP so when the
;         registers are pulled right before exit, SP+1 will be at the re-
;         turn address.
;
;         At this point in the code, .C still contains a copy of SP.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;
         adc !#.s_rsf          ;point to top of register stack frame &...
         tax                   ;set as copy source address...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;         The source is set to the top of the register frame because we
;         will be copying in reverse during stack rebalance.  .S_RSF is
;         the register frame size that was set in the stack frame def-
;         initions.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—
;
         adc !#.s_psf          ;point to top of parameter stack frame &...
         tay                   ;set as copy destination address...
;
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-
;         .S_PSF is the parameter frame size that was set in the stack
;         frame definitions.
;         —-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-—-
;
         lda !#.s_rsf-1        ;bytes to be copied -1
         mvp #0,#0             ;relocate register stack frame
         tyx                   ;adjust SP to point to...
         txs                   ;register frame -1
         pld                   ;restore machine state
         plb
         pla
         plx
         ply
         plp
         .if .def(_SCSI_)      ;if using remote calls...
             rtl
         .else
             rts
         .endif

         PER local_dp
         PLD