CORDIC Coprocessor

The Propeller 2 contains a 54-stage pipelined CORDIC solver that can compute various math functions.

When a cog issues a CORDIC instruction, it must wait for its hub slot, which is 0..7 clocks away, in order to hand off the command to the CORDIC coprocessor. 55 clocks later, results will be available via the GETQX and GETQY instructions, which will wait for the results, in case they haven't arrived yet.

Because each cog's hub slot comes around every 8 clocks and the pipeline is 54 clocks long, it is possible to overlap CORDIC commands, where several commands are initially given to the coprocessor, and then results are read and another command is given, indefinitely, until, at the end, the trailing results are read. One must not have interrupts enabled during such a juggle, or enough clocks could be stolen by the interrupt service routine that one or more of the results could be overwritten before you can read them.

TODO: Reword above

If results are attempted to be read when none are available and no commands are in progress, GETQX/GETQY will only take 2 cycles and the QMT (CORDIC empty) event flag will be set.

Binary Angles

TODO explain binrads For now, see Wikipedia.

Result retrieval

Retrieves the X result from the CORDIC coprocessor into Destination. TODO: What gets written if QMT flag gets set?

If the WC or WCZ effect is specified, the C flag is set to the MSB of the X result.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the X result equals zero, or is cleared (0) if it is non-zero.

Retrieves the Y result from the CORDIC coprocessor into Destination. TODO: What gets written if QMT flag gets set?

If the WC or WCZ effect is specified, the C flag is set to the MSB of the Y result.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Y result equals zero, or is cleared (0) if it is non-zero.

Commands

QROTATE instructs the CORDIC coprocessor to rotate a signed 2D vector by the binary angle in Source. The X component of the vector is given in Destination and if QROTATE is immediately preceded by SETQ, the Q value provides the Y component (otherwise, Y=0).

When it is done, GETQX/GETQY will return the X'/Y' of the rotated vector, respectively.

Mathematically, it performs this operation:

Thus, if Q=0 (as happens when SETQ is not used), QROTATE can be used to compute sine/cosine pairs at a scale given by D. i.e.

    '' Compute sine/cosine for theta, 32 bit precision.
    QROTATE ##$7FFF_FFFF, theta
    ' Can do other stuff while waiting
    GETQX   cosine ' cosine with 32 bit precision
    GETQY   sine ' cosine with 32 bit precision

This is also the same operation as converting a polar vector (length/angle) into a carthesian(X/Y) one:

    '' Convert polar to carthesian
    QROTATE length,angle
    ' Can do other stuff while waiting
    GETQX x
    GETQY y

QROTATE instructs the CORDIC coprocessor to convert a carthesian vector (X/Y) in Destination (X) and Source (Y) into a polar vector (length/angle). When it is done, GETQX will return the angle (as a binary angle) and GETQY will return the length of the vector.

Mathematically:

QMUL instructs the CORDIC coprocessor to perform unsigned multiplication of Destination and Source. When it is done, GETQX will return the lower 32 bits of the result and GETQY will return the upper 32 bits.

Note that the lower half of a multiply result is the same regardless of wether the operation is signed or unsigned. Thus QMUL can be used for signed multiplication as-is, as long as the upper half of the result from GETQY isn't needed.

QDIV instructs the CORDIC coprocessor to perform unsigned division of Destination by Source. If QDIV is immediately preceded by SETQ, the Q value provides the upper 32 bits of a 64-bit dividend.

When it is done, GETQX will return the quotient and GETQY will return the remainder.

QFRAC instructs the CORDIC coprocessor to perform fractional division of Destination by Source. It works identically to QDIV, except that Destination is the upper 32 bits of the dividend and the optional SETQ value is the bottom 32 bits (zero if no SETQ).

TODO maybe write more here

QSQRT instructs the CORDIC coprocessor to compute the square root of the unsigned 64-bit number formed by Destination (lower half) and Source (upper half).

When it is done, GETQX will return the result, rounded down. ? TODO verify rounding. Also what happens to Y???

QLOG instructs the CORDIC coprocessor to compute the base-2 logarithm of the unsigned 32-bit number in Destination. When it is done, GETQX returns the logarithm, in 5.27 fixed-point format (i.e. the top five bits containing the whole part).

QLOG instructs the CORDIC coprocessor to compute two to the power of the 5.27 fixed-point exponent in Destination. When it is done, GETQX returns the result (TODO rounded down?).