The ee-dvp-as assembler
    
                                    lordbosh
                     lordbosh@users.playstation2-linux.com   


1. Introduction

While we all have the docs for the VUs, there is [as far as i have found]
absolutely none on the assembler, ee-dvp-as, itself. This is a shame, as it has
lots of nifty features, including macros for building VIF packets automatically.
While some of this functionality has been exposed in Sony's examples, quite a
bit is missing, and there's no real info on the specifics [eg. the "update"
directive]. This doc hopes to sort that.

Note that much of the information in here has been taken directly from looking
at the source of ee-bin-as rather than from practice.


2. Directives & VIF macros

2.1 "unpack" / ".endunpack"

format:     unpack[IMRUBITS] WL, CL, UNPACKTYPE, UNPACKLOC, DATALEN

example:    unpack[u] 4,4,v4_32,0,*

IMRUBITS: "\[[imru]+\]"
    i - sets interrupt at end of processing flag
    m - sets "use write data mask" flag
    r - if set, add VIF1_TOPS register to address  [doc name = "FLG"]
    u - set for unsigned unpacking. if it's not there, then 5,8&16 bit
        values are sign-extended when they are unpacked [doc name = "USN"]

WL,CL: unsigned integer
    Describes the WL & CL fields of the VIFn_CYCLE register. These values are
    used for data length calculation. If they are equal, the data is used 
    "as-is".

UNPACKTYPE: "((s|v2|v3|v4)_(8|16|32)) | (v4_5)" 
    Describes the format of the data. See the EE user's manual, section 6.3.4 
    for more information on this.

UNPACKLOC: unsigned integer
    This is the address in VU mem to which the data should be unpacked 
    (divided by 16).

DATALEN: * or a binary filename [untested]
    The number of QWORDS of data. If this is *, the assembler calculates this
    value from the data up till the next ".endunpack" directive. If it's a
    filename [in double-quotes], the assembler loads the specified file and
    uses the length of that. I'm not sure if you'd need a ".endunpack" after
    a filename- i'd guess not.
    
        
Description

Marks the start of an UNPACK VIFcode block. The block should be ended with a
".endunpack" directive. These blocks cannot be nested (obviously).



3. Upper instruction bits

After every upper instruction, it is possible to include a set of bits that
will be set. Most commonly, this is seen with the instruction "nop[e]", which
sets the E bit to stop execution. However, there are 5 bits available to be
set, and each instruction can set any or all of these. See pp60-61 of VU Users 
Manual for more information, but the fields basically are:

I - Loads the value of the lower instruction *as a float* into the I register.
    Use the LOI pseudo-opcode to do this.
    
    Format:  <upper instr>[i] <upper operands>      LOI <immediate value>
    
    Example:  scale vector by pi  [no particular reason for pi ;)]

             NOP[i]                         LOI     3.14159
             MULi.xyz   vf02, vf01, I       NOP
    
    See VU manual p31 for more information on the I register.
        

E - Stop the current microprogram. It can be recontinued at a later time using 
    the MSCNT VIFcode.

M - [i haven't tried this, but i think...]
    Set this bit to allow an interlocked QMTC2/CTC2 to continue.

    Example: Say you have some micro code that needs extra information from the
             CPU part-way through its operation [perhaps to increase 
             parallelism]. The M bit of every VU instruction until the new data
             is required should be clear. Then, on the instruction when the new
             data is required, the VU instruction should have the M bit set. In
             the core, a QMTC2.i/CTC2.i should be executed with the new data. 
             This instruction will stall until the instruction with the set M 
             bit is reached, at which point it will be executed and operation 
             will continue.
             Like:

             CPU code:  QMTC2   a0, vf2
                        VCALLMS vu0_func
                        QMTC2.i a1, vf2

             VU code:   vu0_func:
                            NOP         NOP     ;vf02 == a0
                            NOP[m]      NOP     ;vf02 == a0
                            NOP         NOP     ;vf02 == a1
                            
             [100% untested :)]

    See VU Manual p216 for more information.
    
D - This is used for debugging to stop the VU and send an interrupt to the EE 
    core [this interrupt can be enabled/disabled by the DE bit of the FBRST 
    register].
    The T bit acts the same way, and it is recommended that the D bit is left 
    solely for the debugger, and the T bit for user debugging.

T - This is used for debugging to stop the VU and send an interrupt to the EE
    core [this interrupt can be enabled/disabled by the TE bit of the FBRST
    register].