Parallax Propeller 2

Documentation

2021-05-18

v35 (Rev B/C silicon)

P2X8C4M64PES

LPD1941 (Rev B) or LHU2019 (Rev C)

PHILIPPINES

(not yet updated: Boot ROM)

Design Status

KNOWN SILICON BUGS^{[a][b][c][d][e]}

Intervening ALTx/AUGS/AUGD instructions between SETQ/SETQ2 and RDLONG/WRLONG/WMLONG-PTRx instructions will cancel the special-case block-size PTRx deltas. The expected number of longs will transfer, but PTRx will only be modified according to normal PTRx expression behavior:

        SETQ        #16-1                'ready to load 16 longs

        ALTD        start_reg        'alter start register (ALTD cancels block-size PTRx deltas)

        RDLONG        0,ptra++        'ptra will only be incremented by 4 (1 long), not 16*4 as anticipated!!!

Intervening ALTx instructions with an immediate #S operand, between AUGS and the AUGS' intended target instruction (which would have an immediate #S operand), will use the AUGS value, but not cancel it. So, the intended AUGS target instruction will use and cancel the AUGS value, as expected, but the intervening ALTx instruction will also use the AUGS value (if it has an immediate #S operand). To avoid problems in these circumstances, use a register for the S operand of the ALTx instruction, and not an immediate #S operand.

        AUGS        #$FFFFF123        'This AUGS is intended for the ADD instruction.

        ALTD        index,#base        'Look out! AUGS will affect #base, too. Use a register, instead.

        ADD        0-0,#$123        '#$123 will be augmented by the AUGS and cancel the AUGS.

OVERVIEW

The Propeller 2 is a microcontroller architecture consisting of 1, 2, 4, 8, or 16 identical 32-bit processors (called cogs), each with their own RAM, which connect to a common hub. The hub provides up to 1 MB of shared RAM, a CORDIC math solver, and housekeeping facilities. The architecture supports up to 64 smart I/O pins, each capable of many autonomous analog and digital functions.

The P2X8C4M64P silicon contains 8 cogs, 512 KB of hub RAM, and 64 smart I/O pins in an exposed-pad TQFP-100 package.

Design Status

KNOWN BUGS

OVERVIEW

PIN DESCRIPTIONS

MEMORIES

COGS

INSTRUCTION MODES

REGISTER EXECUTION

LOOKUP EXECUTION

HUB EXECUTION

STARTING AND STOPPING COGS

COG RAM

DIRECT ACCESS

DUAL-PURPOSE REGISTERS

SPECIAL-PURPOSE REGISTERS

LOOKUP RAM

LOAD/STORE ACCESS

STREAMER ACCESS

BYTECODE EXECUTION LOOKUP TABLE

SMART PIN DATA SOURCE

RAM SHARING BETWEEN PAIRED COGS

REGISTER INDIRECTION

BRANCH ADDRESSING

INSTRUCTION REPEATING

INSTRUCTION SKIPPING

Special SKIPF Branching Rules

BYTECODE EXECUTION

SETQ CONSIDERATIONS

PIXEL OPERATIONS

DACs

STREAMER

Immediate ⇢ LUT ⇢ Pins/DACs

Immediate ⇢ Pins/DACs

RDFAST ⇢ LUT ⇢ Pins/DACs

RDFAST ⇢ Pins/DACs

RDFAST ⇢ RGB ⇢ Pins/DACs

Pins ⇢ DACs/WRFAST

ADCs/Pins ⇢ DACs/WRFAST

DDS/Goertzel

Digital Video Output (DVI/HDMI)

COLORSPACE CONVERTER

I/O PIN TIMING

COG ATTENTION

EVENTS

Selectable Events

INTERRUPTS

DEBUG INTERRUPT

HUB

Configuration

Configuring the Clock Generator

PLL Example

Write-Protecting the Last 16KB of Hub RAM and Enabling Debug Interrupts

Configuring the Digital Filters for Smart Pins

Seeding the Xoroshiro128** PRNG

Rebooting the Chip

HUB RAM

THE "EGG BEATER" INTERFACE

FAST SEQUENTIAL FIFO INTERFACE

RANDOM ACCESS INTERFACE

FAST BLOCK MOVES

CORDIC Solver

MULTIPLY

DIVIDE

SQUARE ROOT

(X,Y) ROTATION

(X,Y) VECTORING

LOGARITHM

EXPONENT

LOCKS

Allocating Locks

Using Locks

SMART PINS

SMART PIN MODES

%00001..%00011 and not DAC_MODE = long repository

%00001 and DAC_MODE = DAC noise

%00010 and DAC_MODE = DAC 16-bit with pseudo-random dither

%00011 and DAC_MODE = DAC 16-bit with PWM dither

%00100 = pulse/cycle output

%00101 = transition output

%00110 = NCO frequency

%00111 = NCO duty

%01000 = PWM triangle

%01001 = PWM sawtooth

%01010 = PWM switch-mode power supply with voltage and current feedback

%01011 = A/B-input quadrature encoder

%01100 = Count A-input positive edges when B-input is high

%01101 = Accumulate A-input positive edges with B-input supplying increment (B=1) or decrement (B=0)

%01110 AND !Y[0] = Count A-input positive edges

%01110 AND Y[0] = Increment on A-input positive edge and decrement on B-input positive edge

%01111 AND !Y[0] = Count A-input highs

%01111 AND Y[0] = Increment on A-input high and decrement on B-input high

%10000 = Time A-input states

%10001 = Time A-input high states

%10010 AND !Y[2] = Time X A-input highs/rises/edges

%10010 AND Y[2] = Timeout on X clocks of missing A-input high/rise/edge

%10011 = For X periods, count time

%10100 = For X periods, count states

%10101 = For periods in X+ clock cycles, count time

%10110 = For periods in X+ clock cycles, count states

%10111 = For periods in X+ clock cycles, count periods

%11000 = ADC sample/filter/capture, internally clocked

%11001 = ADC sample/filter/capture, externally clocked

About SINC2 and SINC3 filtering

SINC2 Sampling Mode (%00)

SINC3 Filtering Mode (%10)

Bitstream Capturing Mode (%11)

%11010 = ADC Scope with Trigger

SCOPE Data Pipe

%11011 = USB host/device

%11100 = synchronous serial transmit

%11101 = synchronous serial receive

%11110 = asynchronous serial transmit

%11111 = asynchronous serial receive

BOOT PROCESS (needs more editing)

SERIAL LOADING PROTOCOL

Prop_Chk

Prop_Clk

PLL Example

Reset to Boot Clock Configuration

Prop_Hex

Prop_Txt

SUMMARY

Assembly Language

Boot ROM / Debug ROM

Packaging

Each cog has:

• Access to all I/O pins, plus four fast DAC output channels and four fast ADC input channels
• 512 longs of dual-port register RAM for code and fast variables
• 512 longs of dual-port lookup RAM for code, streamer lookup, and variables
• Ability to execute code directly from register RAM, lookup RAM, and hub RAM
• ~350 unique instructions for math, logic, timing, and control operations
• 2-clock execution for all math and logic instructions, including 16 x 16 multiply
• 6-clock custom-bytecode executor for interpreted languages
• Ability to stream hub RAM and/or lookup RAM to DACs and pins or HDMI modulator
• Ability to stream pins and/or ADCs to hub RAM
• Live colorspace conversion using a 3 x 3 matrix with 8-bit signed/unsigned coefficients
• Pixel blending instructions for 8:8:8:8 data
• 16 unique event trackers that can be polled and waited upon
• 3 prioritized interrupts that trigger on selectable events
• Hidden debug interrupt for single-stepping, breakpoint, and polling
• 8-level hardware stack for fastest subroutine calls/returns and push/pop operations
• Carry and Zero flag

The hub provides the cogs with:  

• Up to 1 MB of contiguous RAM in a 20-bit address space (P2X8C4M64P contains 512 KB)

• 32-bits-per-clock sequential read/write for all cogs, simultaneously
• readable and writable as bytes, words, or longs in little-endian format
• last 16KB of RAM also appears at the end of the 1MB map and is write-protectable

• 32-bit, pipelined CORDIC solver with scale-factor correction

• 32-bit x 32-bit unsigned multiply with 64-bit result
• 64-bit / 32-bit unsigned divide with 32-bit quotient and 32-bit remainder
• 64-bit → 32-bit square root
• Rotate (X32,Y32) by Theta32 → (X32,Y32)
• (Rho32,Theta32) → (X32,Y32) polar-to-cartesian
• (X32,Y32) → (Rho32,Theta32) cartesian-to-polar
• 32 → 5.27 unsigned-to-logarithm
• 5.27 → 32 logarithm-to-unsigned
• Cogs can start CORDIC operations every 1/2/4/8/16 (#cogs) clocks and get results 55 clocks later

• 16 semaphore bits with atomic read-modify-write operations
• 64-bit free-running counter which increments every clock, cleared on reset
• High-quality pseudo-random number generator (Xoroshiro128**), true-random seeded at start-up, updates every clock, provides unique data to each cog and pin
• Mechanisms for starting, polling, and stopping cogs
• 16KB boot ROM

• Loads into last 16 KB of hub RAM on boot-up
• SPI loader for automatic startup from 8-pin flash or SD card
• Serial loader for startup from host

• Hex and Base64 download protocols
• Terminal monitor invocable via "> " (greater than followed by a space) and then CTRL+D
• TAQOZ Forth invocable via "> " (greater than followed by a space) and then ESC

Each smart I/O pin has the following functions:

• 8-bit, 120-ohm (3ns) and 1k-ohm DACs with 16-bit oversampling, noise, and high/low digital modes
• Delta-sigma ADC with 5 ranges, 2 sources, and VIO/GIO calibration
• Several ADC sampling modes: automatic 2n SINC2, adjustable SINC2/SINC3, oscilloscope
• Logic, Schmitt, pin-to-pin-comparator, and 8-bit-level-comparator input modes
• 2/3/5/8-bit-unanimous input filtering with selectable sample rate
• Incorporation of inputs from relative pins, -3 to +3
• Negative or positive local feedback, with or without clocking
• Separate drive modes for high and low output: logic / 1.5 k / 15 k / 150 k / 1 mA / 100 µA / 10 µA / float
• Programmable 32-bit clock output, transition output, NCO/duty output
• Triangle/sawtooth/SMPS PWM output, 16-bit frame with 16-bit prescaler
• Quadrature decoding with 32-bit counter, both position and velocity modes
• 16 different 32-bit measurements involving one or two signals
• USB full-speed and low-speed (via odd/even pin pairs)
• Synchronous serial transmit and receive, 1 to 32 bits, up to clock/2 baud rate
• Asynchronous serial transmit and receive, 1 to 32 bits, up to clock/3 baud rate

Six different clock modes, all under software control with glitch-free switching between sources:

• Internal 20+ MHz RC oscillator, nominally 24 MHz, used as initial clock source
• Crystal oscillator with internal loading caps for 7.5 pF/15 pF crystals, can feed PLL
• Clock input, can feed PLL
• Fractional PLL with 1..64 crystal divider --> 1..1024 VCO multiplier --> optional (1..15)*2 VCO post-divider
• Internal ~20 kHz RC oscillator for low-power operation (130 µA)
• Clock can be stopped for lowest power until reset (100 µA, due to leakage)

PIN DESCRIPTIONS

MEMORIES

There are three memory regions: cog RAM, lookup RAM, and hub RAM.  Each cog has its own cog RAM and lookup RAM, while the hub RAM is shared by all cogs.

(*) 1,048,576 bytes is the maximum size supported.  However, some variants may have less available.  See the Hub Memory section below for more details.

COGS

The Propeller contains multiple processors, called "cogs".  Each cog  has its own RAM and can start, stop, and execute instructions independently of one another.  All active cogs share the same system clock, Hub RAM, and I/O pins.

Cogs employ a five-stage pipelined execution architecture.  When the execution pipeline is full, each instruction effectively takes as little as two clock cycles to execute.  If an instruction stalls for additional clock cycles, all following instructions in the pipeline are also stalled. Any instruction that is conditionally canceled will still move through the pipeline without stalling or executing, but taking two clock cycles.  Branch instructions cause the pipeline to be flushed, so the first instruction following the branch will take at least five clock cycles.

The available instruction set can be found at Parallax Propeller 2 Instruction Set.  When reading the "Encoding" column, the following table may help:

INSTRUCTION MODES

Cogs use 20-bit addresses for program counters (PC). This affords an execution space of up to 1MB.  Depending on the value of a cog's PC, an instruction will be fetched from either its register RAM, its lookup RAM, or the hub RAM.

REGISTER EXECUTION

When the PC is in the range of $00000 and $001FF, the cog is fetching instructions from cog register RAM.  This is commonly referred to as "cog execution mode."  There is no special consideration when taking branches to a cog register address.

LOOKUP EXECUTION

When the PC is in the range of $00200 and $003FF, the cog is fetching instructions from cog lookup RAM.  This is commonly referred to as "LUT execution mode."  There is no special consideration when taking branches to a cog lookup address,

HUB EXECUTION

When the PC is in the range of $00400 and $FFFFF, the cog is fetching instructions from hub RAM.  This is commonly referred to as "hub execution mode."  When executing from hub RAM, the cog employs the FIFO hardware to spool up instructions so that a stream of instructions will be available for continuous execution. Branching to a hub address takes a minimum of 13 clock cycles.  If the instruction being branched to is not long-aligned, one additional clock cycle is required. A branch must occur to get from cog to hub, since rolling from $3FF to $400 will not initiate hub execution.

While in hub execution mode, the FIFO cannot be used for anything else. So, during hub execution these instructions cannot be used:

RDFAST / WRFAST / FBLOCK

RFBYTE / RFWORD / RFLONG / RFVAR / RFVARS

WFBYTE / WFWORD / WFLONG

XINIT / XZERO / XCONT - when the streamer mode engages the FIFO

It is not possible to execute code from hub addresses $00000 through $003FF, as the cog will instead read instructions from the cog register or lookup RAM as indicated above.

STARTING AND STOPPING COGS

Any cog can start or stop any other cog, or restart or stop itself. Each of the eight cogs has a unique three-bit ID which can be used to start or stop it. It's also possible to start free (stopped or never started) cogs, without needing to know their ID's. This way, entire applications can be written which simply start free cogs, as needed, and as those cogs retire by stopping themselves or getting stopped by others, they return to the pool of free cogs and become available, again, for restarting.

The COGINIT instruction is used to start cogs:

COGINIT D/#,S/# {WC}

D/# =         %0_x_xxxx        The target cog loads its own registers $000..$1F7 from the hub,

starting at address S/#, then begins execution at register address $000.

        %1_x_xxxx        The target cog begins execution at register/LUT/hub address S/#.

        %x_0_CCCC        The target cog's ID is %CCCC.

        %x_1_xxx0        If a cog is free (stopped), then start it.

                        To know if this succeeded, D must be a register and WC must be

used. If successful, C will be cleared and D will be over-

written with the target cog's ID. Otherwise, C will be set and D will be overwritten with $F.

        %x_1_xxx1        If an even/odd cog pair is free (stopped), then start them.

To know if this succeeded, D must be a register and WC must be

used. If successful, C will be cleared and D will be over-

written with the even/lower target cog's ID. Otherwise, C will be set

and D will be overwritten with $F.

S/# = address                This value is either the hub address from which the target cog will

load from, or it is the cog/hub address from which the target cog

will begin executing at, depending on D[5]. This 32-bit value will be

written into the target cog's PTRB register.

If COGINIT is preceded by SETQ, the SETQ value will be written into the target cog's PTRA register. This is intended as a convenient means of pointing the target cog's program to some runtime data structure or passing it a 32-bit parameter. If no SETQ is used, the target cog's PTRA register will be cleared to zero.

COGINIT #1,#$100                'load and start cog 1 from $100

COGINIT #%1_0_0101,PTRA        'start cog 5 at PTRA

SETQ    ptra_val                'ptra_val will go into target cog's PTRA register

COGINIT #%0_1_0000,addr        'load and start a free cog at addr

COGINIT #%1_1_0001,addr        'start a pair of free cogs at addr (lookup RAM sharing)

COGINIT id,addr WC                '(id=$30) start a free cog at addr, C=0 and id=cog if okay

COGID   myID                        'reload and restart me at PTRB

COGINIT myID,PTRB

The COGSTOP instruction is used to stop cogs. The 4 LSB's of the D/# operand supply the target cog ID.

COGSTOP #0                        'stop cog 0

COGID   myID                        'stop me

COGSTOP myID

A cog can discover its own ID by doing a COGID instruction, which will return its ID into D[3:0], with upper bits cleared. This is useful, in case the cog wants to restart or stop itself, as shown above.

If COGID is used with WC, it will not overwrite D, but will return the status of cog D/# into C, where C=0 indicates the cog is free (stopped or never started) and C=1 indicates the cog is busy (started).

COGID   ThatCog  WC                'C=1 if ThatCog is busy

COG RAM

Each cog has a primary 512 x 32-bit dual-port RAM, which can be used in multiple ways:

• Direct/Register access
• As a source of program instructions (see COGS > INSTRUCTION MODES > REGISTER EXECUTION)

GENERAL PURPOSE REGISTERS

RAM registers $000 through $1EF are general-purpose registers for code and data usage.

DUAL-PURPOSE REGISTERS

RAM registers $1F0 through $1F7 may either be used as general-purpose registers, or may be used as special-purpose registers if their associated functions are enabled.

$1F0                RAM / IJMP3                interrupt call   address for INT3

$1F1                RAM / IRET3                interrupt return address for INT3

$1F2                RAM / IJMP2                interrupt call   address for INT2

$1F3                RAM / IRET2                interrupt return address for INT2

$1F4                RAM / IJMP1                interrupt call   address for INT1

$1F5                RAM / IRET1                interrupt return address for INT1

$1F6                RAM / PA                CALLD-imm return, CALLPA parameter, or LOC address

$1F7                RAM / PB                CALLD-imm return, CALLPB parameter, or LOC address

SPECIAL-PURPOSE REGISTERS

Each cog contains 8 special-purpose registers that are mapped into the RAM register address space from $1F8 to $1FF.  In general, when specifying an address between $1F8 and $1FF, the instruction is accessing a special-purpose register, not just the underlying RAM.

$1F8                PTRA                        pointer A to hub RAM

$1F9                PTRB                        pointer B to hub RAM

$1FA                DIRA                        output enables for P31..P0

$1FB                DIRB                        output enables for P63..P32

$1FC                OUTA                        output states for P31..P0

$1FD                OUTB                        output states for P63..P32

$1FE                INA *                        input states for P31..P0

$1FF                INB **                        input states for P63..P32

 * also debug interrupt call address

** also debug interrupt return address

LOOKUP RAM

Each cog has a secondary 512 x 32-bit dual-port RAM, which can be used in multiple  ways:

• Load/Store access
• As a source or destination for the streamer hardware
• As a lookup table for bytecode execution
• As a data source for smart pins
• As a "RAM sharing" mechanism between paired cogs
• As a source of program instructions (see COGS > INSTRUCTION MODES > LOOKUP EXECUTION)

NOTE: The term "lookup" (and "LUT", which is short for "look-up table") is due to historical usage in the original Propeller microcontroller.  This RAM can still be used in a "lookup" context, but can also be used for many other purposes, as indicated above.

LOAD/STORE ACCESS

Unlike cog RAM, the cog cannot directly use the lookup RAM in the majority of its instructions.  Instead, lookup RAM must be read into cog RAM using the RDLUT instruction and cog RAM must be written into the lookup RAM using the WRLUT instruction.  In other hardware architectures, these instructions would be synonymous with "LOAD" and "STORE" instructions, respectively.  When using the RDLUT and WRLUT instructions, the 32-bit words are addressible from $000 to $1FF.

STREAMER ACCESS

(to be completed.)

BYTECODE EXECUTION LOOKUP TABLE

(to be completed.)

RAM SHARING BETWEEN PAIRED COGS

Adjacent cogs whose ID numbers differ by only the LSB (cogs 0 and 1, 2 and 3, 4 and 5, etc.) can each allow their lookup RAMs to be written by the other cog via its local lookup RAM writes. This allows adjacent cogs to share data very quickly through their lookup RAMs.

The 'SETLUTS D/#' instruction is used to enable the lookup RAM to receive writes from the adjacent cog:

        SETLUTS #0                                'disallow writes from other cog (default)

        SETLUTS #1                                'allow writes from other cog

Lookup-RAM writes from the adjacent cog are implemented on the 2nd port of the lookup RAM. The 2nd port is also shared by the streamer in DDS/LUT modes. If an external write occurs on the same clock as a streamer read, the external write gets priority. It is not intended that external writes would be enabled at the same time the streamer is in DDS/LUT mode.

In order to find and start two adjacent cogs with which this write-sharing scheme can be used, the COGINIT instruction has a mechanism for finding an even/odd pair and then starting them both with the same parameters. It will be necessary for the program to differentiate between even and odd cogs and possibly restart one, or both, with the final, intended program. To have COGINIT find and start two adjacent cogs, use %x_1_xxx1 for the D/# operand.

To facilitate handshaking between cogs sharing lookup RAM, the SETSE1...4 instructions can be used to set up lookup RAM read and write events.

REGISTER INDIRECTION

Cog registers can be accessed indirectly most easily by using the ALTS/ALTD/ALTR instructions. These instructions sum their D[8:0] and S/#[8:0] values to compute an address that is directly substituted into the next instruction's S field, D field, or result register address (normally, this is the same as the D field). This all happens within the pipeline and does not affect the actual program code. The idea is that S/# can serve as a register base address and D can be used as an index.

Additionally, S[17:9] is always sign-extended and added to the D register for index updating. Normally, a nine-bit #address will be used for S, causing S[17:9] to be zero, so that D is unaffected:

ALTS    index^[g],#table        'set next S field to table+index

MOV     OUTA,0                'output register[table+index] to OUTA

ALTD    index,#table        'set next D field to table+index

MOV     0,INA                        'write INA to register[table+index]

ALTR    index,#table        'set next write to table+index

XOR     INA,INB                'write INA^INB to register[table+index]

For cases where base+index is not required, and a register holds the desired address, the S/# field can be omitted and it will be set to '#0' by the assembler:

ALTS    pointer                'set next S field to pointer

MOV     OUTA,0                'output register[pointer] to OUTA

ALTD    pointer                'set next D field to pointer

MOV     0,INA                        'write INA to register[pointer]

ALTR    pointer                'set next write to pointer

XOR     INA,INB                'write INA^INB to register[pointer]

For accessing bit fields that span multiple registers, there is the ALTB instruction which sums D[13:5] and S/#[8:0] values to compute an address which is substituted into the next instruction's D field. It can be used with and without S/#:

ALTB    bitindex,#base        'set next D field to base+bitindex[13:5]

BITC    0,bitindex                'write C to bit[bitindex[4:0^[h]]]

ALTB    bitindex                'set next D field to bitindex[13:5]

TESTB   0,bitindex        WC        'read bit[bitindex[4:0]] into C

There are also ALTxx instructions for facilitating nibble (4-bit), byte (8-bit), and word (16-bit) sub-addressing of registers. They modify either the S or D field, as well as the N field of their associated and subsequent nibble, byte, or word instruction. Like the other ALTx instructions, they can be used with or without S/#. Note that the associated nibble, byte, or word instruction can be a shortened-syntax alias of the full instruction, since two of its three fields will be filled in by the ALTxx instruction.

Nibble addressing:

ALTSN   index,#base                'set next D field to base+index[11:3], next N to index[2:0]

SETNIB  value                        'set nibble to value ('SETNIB S/#' = 'SETNIB 0,S/#,#0')

ALTGN   index,#base                'set next S field to base+index[11:3], next N to index[2:0]

GETNIB  value                        'get nibble into value ('GETNIB D' = 'GETNIB D,0,#0')

ALTGN   index,#base                'set next S field to base+index[11:3], next N to index[2:0]

ROLNIB  value                        'ROL nibble into value ('ROLNIB D' = 'ROLNIB D,0,#0')

Byte addressing:

ALTSB   index,#base                'set next D field to base+index[10:2], next N to index[1:0]

SETBYTE value                        'set byte to value ('SETBYTE S/#' = 'SETBYTE 0,S/#,#0')

ALTGB   index,#base                'set next S field to base+index[10:2], next N to index[1:0]

GETBYTE value                        'get byte into value ('GETBYTE D' = 'GETBYTE D,0,#0')

ALTGB   index,#base                'set next S field to base+index[10:2], next N to index[1:0]

ROLBYTE value                        'ROL byte into value ('ROLBYTE D' = 'ROLBYTE D,0,#0')

Word addressing:

ALTSW   index,#base                'set next D field to base+index[9:1], next N to index[0]

SETWORD value                        'set word to value ('SETWORD S/#' = 'SETWORD 0,S/#,#0')

ALTGW   index,#base                'set next S field to base+index[9:1], next N to index[0]

GETWORD value                        'get word into value ('GETWORD D' = 'GETWORD D,0,#0')

ALTGW   index,#base                'set next S field to base+index[9:1], next N to index[0]

ROLWORD value                        'ROL word into value ('ROLWORD D' = 'ROLWORD D,0,#0')

For more complex S field, D field, and result register substitutions, there is the ALTI instruction. ALTI actually does a few different things. First, ALTI can be used to individually increment or decrement three different nine-bit fields within a register. Second, ALTI can substitute each of those fields (before incrementing or decrementing) into the next instruction's S field, D field, or result register address, in the same way ALTS, ALTD, and ALTR do. Lastly, ALTI can substitute D[31..18] into the next instruction's upper bits [31..18] to enable full instruction substitution with a register's contents.

ALTI    D,S/#                        'modify D and/or next instruction's fields according to S/#

S/# = %rrr_ddd_sss_RRR_DDD_SSS

%rrr                Result register field D[27..19] increment/decrement masking

%ddd                D register field D[17..9] increment/decrement masking

%sss                S register field D[8..0] increment/decrement masking

%rrr/%ddd/%sss:

000 = 9 bits increment/decrement (default, full span)

001 = 8 LSBs increment/decrement (256-register looped buffer)

010 = 7 LSBs increment/decrement (128-register looped buffer)

011 = 6 LSBs increment/decrement (64-register looped buffer)

100 = 5 LSBs increment/decrement (32-register looped buffer)

101 = 4 LSBs increment/decrement (16-register looped buffer)

110 = 3 LSBs increment/decrement (8-register looped buffer)

111 = 2 LSBs increment/decrement (4-register looped buffer)

%RRR                result register / instruction modification:

000 = D[27..19] stays same, no result register substitution

001 = D[27..19] stays same, but result register writing is canceled

010 = D[27..19] decrements per %rrr, no result register substitution

011 = D[27..19] increments per %rrr, no result register substitution

100 = D[27..19] sets next instruction's result register, stays same

101 = D[31..18] substitutes into next instruction's [31..18] (execute D)

110 = D[27..19] sets next instruction's result register, decrements per %rrr

111 = D[27..19] sets next instruction's result register, increments per %rrr

%DDD                D field modification:

x0x = D[17..9] stays same

x10 = D[17..9] decrements per %ddd

x11 = D[17..9] increments per %ddd

0xx = no D field substitution

1xx = D[17..9] substitutes into next instruction's D field [17..9]

%SSS                S field modification:

x0x = D[8..0] stays same

x10 = D[8..0] decrements per %sss

x11 = D[8..0] increments per %sss

0xx = no S field substitution

1xx = D[8..0] substitutes into next instruction's S field [8..0]

Here are some examples of ALTI usage:

ALTI    ptrs,#%111_111        'set next D and S fields, increment ptrs[17:9] and ptrs[8:0]

ADD     0,0                        'add registers

ALTI    inst,#%101_100_100        'execute inst (same as 'ALTI inst')

NOP                                'NOP becomes inst

The SETS/SETD/SETR instructions allow you to write the S field, D field and instruction field of a register without affecting other bits. They copy the lower 9 bits of S/# into their respective 9-bit field within D. These instructions are useful for establishing the fields that will be used by ALTI:

SETS    D,S/#                        'set D[8:0] to S/#[8:0]

SETD    D,S/#                        'set D[17:9] to S/#[8:0]

SETR    D,S/#                        'set D[27:19] to S/#[8:0]

SETS/SETD/SETR can also be used in self-modifying cog-register code. After modifying a cog register, It is necessary to elapse two instructions before executing the modified register, due to pipelining:^[i]

SETR    inst,op                'set register[27:19] to op[8:0]

NOP                                'first spacer instruction, could be anything

NOP                                'second spacer instruction, could be anything

inst        MOV     x,y                        'operate on x using y, MOV can become AND/OR/XOR/etc.

BRANCH ADDRESSING

The following are branch instructions which use D[19:0] as an absolute address:

EEEE 1101011 CZ0 DDDDDDDDD 000101100        JMP     D

EEEE 1101011 CZ0 DDDDDDDDD 000101101        CALL    D

EEEE 1101011 CZ0 DDDDDDDDD 000101110        CALLA   D

EEEE 1101011 CZ0 DDDDDDDDD 000101111        CALLB   D

The JMPREL instruction uses D as a relative address that steps whole instructions. In cog mode, D[19:0] is added to the program counter and in hub mode, D[17:0] << 2 is added to the program counter. This instruction is unique in its ability to make a relative jump (as opposed to an absolute jump) based on a register value. If #D is used, the relative address will be a positive 9-bit value:

EEEE 1101011 00L DDDDDDDDD 000110000        JMPREL  {#}D

These next branch instructions use S[19:0] as an absolute address, or, if S is immediate, they sign-extend the 9-bit S field and use that value as a relative address that steps whole instructions (in hub mode, the value gets shifted left two bits before being added to the program counter). This means that their immediate range is -256 to +255 instructions, relative to the instruction following the branch:

EEEE 1011010 0LI DDDDDDDDD SSSSSSSSS        CALLPA  {#}D,{#}S

EEEE 1011010 1LI DDDDDDDDD SSSSSSSSS        CALLPB  {#}D,{#}S

EEEE 1011001 CZI DDDDDDDDD SSSSSSSSS        CALLD   D,{#}S

EEEE 1011011 00I DDDDDDDDD SSSSSSSSS        DJZ     D,{#}S

EEEE 1011011 01I DDDDDDDDD SSSSSSSSS        DJNZ    D,{#}S

EEEE 1011011 10I DDDDDDDDD SSSSSSSSS        DJF     D,{#}S

EEEE 1011011 11I DDDDDDDDD SSSSSSSSS        DJNF    D,{#}S

EEEE 1011100 00I DDDDDDDDD SSSSSSSSS        IJZ     D,{#}S

EEEE 1011100 01I DDDDDDDDD SSSSSSSSS        IJNZ    D,{#}S

EEEE 1011100 10I DDDDDDDDD SSSSSSSSS        TJZ     D,{#}S

EEEE 1011100 11I DDDDDDDDD SSSSSSSSS        TJNZ    D,{#}S

EEEE 1011101 00I DDDDDDDDD SSSSSSSSS        TJF     D,{#}S

EEEE 1011101 01I DDDDDDDDD SSSSSSSSS        TJNF    D,{#}S

EEEE 1011101 10I DDDDDDDDD SSSSSSSSS        TJS     D,{#}S

EEEE 1011101 11I DDDDDDDDD SSSSSSSSS        TJNS    D,{#}S

EEEE 1011110 00I DDDDDDDDD SSSSSSSSS        TJV     D,{#}S

EEEE 1011110 01I 00000VVVV SSSSSSSSS        Jevent  {#}S

EEEE 1011110 01I 00001VVVV SSSSSSSSS        JNevent {#}S

There are five branch instructions and one 'locate' instruction which involve 20-bit immediate addresses. Their addresses can be either relative to the program counter (R=1) or absolute (R=0):

EEEE 1101100 RAA AAAAAAAAA AAAAAAAAA        JMP     #{\}A

EEEE 1101101 RAA AAAAAAAAA AAAAAAAAA        CALL    #{\}A

EEEE 1101110 RAA AAAAAAAAA AAAAAAAAA        CALLA   #{\}A

EEEE 1101111 RAA AAAAAAAAA AAAAAAAAA        CALLB   #{\}A

EEEE 11100WW RAA AAAAAAAAA AAAAAAAAA        CALLD   PA/PB/PTRA/PTRB,#{\}A

EEEE 11101WW RAA AAAAAAAAA AAAAAAAAA        LOC     PA/PB/PTRA/PTRB,#{\}A

Relative addressing is convenient for relocatable code, or code which can run from either cog RAM or hub RAM. Relative addressing is the default when cog code references cog labels or hub code references hub labels. On the other hand, absolute addressing is highly recommended, and forced by the assembler, when crossing between cog and hub domains.

Absolute addressing can be forced by the use of "\" after the "#".

The "@" operator can be used before an address label to return the hub address of that label, in case it was defined under an ORG directive to generate cog code, and the label would normally return the cog address..

The cases below illustrate use of the 20-bit immediate-address instructions and "\" and "@":

        ORGH    $01000

        ORG     0       'cog code

cog     JMP     #cog    '$FD9FFFFC      cog to cog, relative

        JMP     #\cog   '$FD800000      cog to cog, force absolute

        JMP     #@cog   '$FD801000      cog to hub, always absolute

        JMP     #\@cog  '$FD801000      cog to hub, always absolute

        JMP     #hub    '$FD802000      cog to hub, always absolute

        JMP     #\hub   '$FD802000      cog to hub, always absolute

        JMP     #@hub   '$FD802000      cog to hub, always absolute

        JMP     #\@hub  '$FD802000      cog to hub, always absolute

        ORGH    $02000  'hub code

hub     JMP     #cog    '$FD800000      hub to cog, always absolute

        JMP     #\cog   '$FD800000      hub to cog, always absolute

        JMP     #@cog   '$FD9FEFF4      hub to hub, relative

        JMP     #\@cog  '$FD801000      hub to hub, force absolute

        JMP     #hub    '$FD9FFFEC      hub to hub, relative

        JMP     #\hub   '$FD802000      hub to hub, force absolute

        JMP     #@hub   '$FD9FFFE4      hub to hub, relative

        JMP     #\@hub  '$FD802000      hub to hub, force absolute

INSTRUCTION REPEATING

Single or multiple instructions can be repeated without branching delays in cog/LUT memory using the REP instruction:

REP     {#}D,{#}S                'execute {#}D[8:0] instructions {#}S[31:0] times

If D[8:0] = 0, nothing will be repeated. If D[8:0] > 0 and S[31:0] = 0 then D[8:0] instructions will be repeated indefinitely.

By changing the #1000 to #0, the DRVNOT instruction would be repeated indefinitely:

REP     #1,##1000                'toggle pin 0 1000 times (1 instruction x 1000)

DRVNOT  #0                        'output and toggle pin 0 (2 clocks per toggle)

In cases where you'd rather have the assembler keep track of the number of instructions, @label can be used:

REP     @.end,reps                'repeat instruction block 'reps' times

WFBYTE  x                        'write x to next byte in hub

ADD     x,#1                        'increment x

.end

REP works in hub memory, as well, but executes a hidden jump to get back to the top of the repeated instructions.

Any branch within the repeating instruction block will cancel REP activity. Interrupts will be ignored during REP looping.

INSTRUCTION SKIPPING

Cogs can initiate skipping sequences to selectively skip any of the next 32 instructions encountered. Skipping is accomplished by either canceling instructions as they come through the pipeline from hub or cog/LUT memory (effectively turning them into 2-clock NOP instructions) or by leaping over them in cog/LUT memory (no clock penalty). Skipping only works outside of interrupt service routines; i.e. in main code.

There are three instructions that initiate skipping:

SKIP    {#}D                'skip by cancelling instructions sequentially per D[0]..D[31]

SKIPF   {#}D                'like SKIP, but fast due to PC steps of 1..8 - cog/LUT only!

EXECF   {#}D                'jump to D[9:0] in cog/LUT and initiate SKIPF using D[31:10]

In each case, D provides a bit pattern which is used LSB-first to determine whether the next instruction is cancelled/skipped (bit=1) or executed (bit=0). The D bit pattern is initially captured and subsequently shifted right by one bit for each instruction encountered.

Within a skipping sequence, a CALL/CALLPA/CALLPB that is not skipped will execute all its nested subroutines normally, with the skipping sequence resuming after the returning RET/_RET_^[j]. This allows subroutines to be skipped or entirely executed without affecting the top-level skip sequence. As well, an interrupt service routine will execute normally during a skipping sequence, with the skipping sequence resuming upon its completion.

While SKIP-initiated skipping can take place in both hub and cog/LUT memory, SKIPF-initiated and EXECF-initiated skipping can only take place in cog/LUT memory. This is because the PC can be randomly stepped in cog/LUT memory, whereas the hub memory FIFO can only provide the next instruction, unless a full branch takes place, triggering a FIFO reload.

Here is a simplistic example of SKIP:

SKIP        #%010110        'initiate skip sequence (skip 2nd, 3rd, 5th instruction)

DRVN        #0                'drive and invert pin 0 (executes)

DRVN        #1                'drive and invert pin 1 (NOP)

DRVN        #2                'drive and invert pin 2 (NOP)

DRVN        #3                'drive and invert pin 3 (executes)

DRVN        #4                'drive and invert pin 4 (NOP)

DRVN        #5                'drive and invert pin 5 (executes)

Skipping is very useful for getting increased functionality out of an otherwise-static sequence of instructions. Consider this sequence, which contains all the instructions needed to realize 36 different address calculations:

addr                RFBYTE        m                'offset - one of these three (3 possibilities)

RFWORD        m

RFLONG        m

ADD        m,pbase        'base - one of these three (3 possibilities)

ADD        m,vbase

ADD        m,dbase

SHL        i,#1                'index - zero to two of these three (4 possibilities)

SHL        i,#2

ADD        m,i

In the above sequence, the intention is to compute an address using an offset, a base, and an optional index. There are 3 x 3 x 4, or 36, useful permutations. If you wanted to use a byte offset, pbase, and a long index, you would want to execute only these four instructions from the 'addr' sequence:

RFBYTE        m                'offset

ADD        m,pbase        'base

SHL        i,#2                'index

ADD        m,i

The skip pattern for just those four instructions would be %001_110_110. Assuming 'pat' holds that pattern, here is what the execution would look like using SKIP. Note that the 'addr' instruction sequence, shown above, follows the SKIP instruction and skipped instructions in the 'addr' sequence are now shown as NOPs:

SKIP        pat                'initiate skip sequence (%001_110_110 in this case)

addr                RFBYTE        m                'offset

NOP

NOP

ADD        m,pbase        'base

NOP

NOP

NOP                        'index

SHL        i,#2

ADD        m,i

If this code were located in cog/LUT memory, SKIPF could be used to speed things up by stepping over skipped instructions, instead of canceling them in the pipeline. Here is what the execution would look like using SKIPF:

SKIPF        pat                'initiate skip sequence (%001_110_110 in this case)

addr                RFBYTE        m                'offset

ADD        m,pbase        'base

SHL        i,#2                'index

ADD        m,i

Now things are very efficient, with no cycles being wasted on NOPs. If SKIPF is used in hub exec, it will revert to SKIP behavior, canceling instructions in the pipeline, instead of stepping over them.

Both SKIP and SKIPF can be preceded by _RET_ for an automatic branch before skipping commences:

PUSH        #addr                'point to the addr routine

_RET_        SKIPF        pat                'jump to addr and begin skipping fast using pat

The EXECF instruction performs a JMP and a SKIPF at the same time, getting a 10-bit branch address from D[9:0] and a 22-bit skip pattern from D[31:10]. Here is the heart of a simple bytecode interpreter which uses EXECF:

REP        #1,#8                'pre-stuff 8-level hardware stack with 'loop' address

PUSH        #loop                'all RETs without CALLs will branch to 'loop'

loop                RFBYTE        i                'get a bytecode

RDLUT        e,i                'lookup long in LUT

EXECF        e                'jump to e[9:0] and SKIPF e[31:10], RETs branch to 'loop'

That bytecode interpreter takes only 2+3+4, or 9, clocks to get the next bytecode, look it up, then execute that bytecode's routine in cog/LUT memory with a custom 22-bit SKIPF pattern. If that bytecode's routine is just a 2-clock instruction preceded by a _RET_, it will take 4 clocks, due to the _RET_, for a total of 13 clocks, looping. Those 13 clocks can be reduced to only 8 clocks by using XBYTE, which is explained in the next section.

While SKIPF and EXECF normally step over skipped instructions in cog/LUT memory, there are some circumstances where they must cancel an instruction, instead, since it is already in the pipeline:

1. The first instruction is being skipped after the SKIPF/EXECF instruction (the LSB of the skip pattern is '1')
2. The 8th instruction in a row is being skipped (only 7 instructions can be stepped over at once)

 Each of these cancellations results in a 2-clock NOP instruction.

SKIP is fully compatible with REP, since SKIP only cancels instructions, allowing REP to maintain accurate instruction counts.

SKIPF would only work with REP if all SKIPF patterns resulted in the same instruction counts, which REP would have to be initiated with, as opposed to just length-of-code.

Special SKIPF Branching Rules

Within SKIPF sequences where CALL/CALLPA/CALLPB are used to execute subroutines in which skipping will be suspended until after RET, all CALL/CALLPA/CALLPB immediate (#) branch addresses must be absolute in cases where the instruction after the CALL/CALLPA/CALLPB might be skipped. This is not possible for CALLPA/CALLPB but CALL can use '#\address' syntax to achieve absolute immediate addressing. CALL/CALLPA/CALLPB can all use registers as branch addresses, since they are absolute.

For non-CALL\CALLPA\CALLPB branches within SKIPF sequences, SKIPF will work through all immediate-relative branches, which are the default for immediate branches within cog/LUT memory. If an absolute-address branch is being used (#\label, register, or RET, for example), you must not skip the first instruction after the branch. This is not a problem with immediate-relative branches, however, since the variable PC stepping works to advantage, by landing the PC at the first instruction of interest at, or beyond, the branch address.

BYTECODE EXECUTION (XBYTE)

Cogs can execute custom bytecodes from hub RAM using XBYTE. XBYTE is like a phantom instruction and it executes on a hardware stack return (RET/_RET_) to $1FF. Such a return does not pop the stack, so that each additional RET/_RET_ causes another bytecode to be fetched and executed. This process has a total overhead of only 6 clocks, excluding the bytecode routine. The bytecode routine could be as short as a single 2-clock instruction with a _RET_ prefix, making the total XBYTE loop take only 8 clocks.

XBYTE performs the following steps to make a complete bytecode executor:

The bytecode translation table in LUT memory must consist of long data which EXECF would use, where the 10 LSBs are an address to jump to in cog/LUT RAM and the 22 MSBs are a SKIPF pattern to be applied.

Starting XBYTE and establishing its operating mode is done all at once by a  '_RET_ SETQ {#}D' instruction, with the top of the hardware stack holding $1FF.

Additional '_RET_ SETQ {#}D' instructions can be executed to alter the XBYTE mode for subsequent bytecodes.

To alter the XBYTE mode for the next bytecode, only, a '_RET_ SETQ2 {#}D' instruction can be executed. This is useful for engaging singular bytecodes from alternate sets, without having to restore the original XBYTE mode afterwards                .

The %ABBBB00xF setting allows sets of 16 bytecodes, which would use identical LUT values, to be represented by a single LUT value, effectively compressing blocks of 16 LUT values into single LUT values. This is useful when the bytecode, which is always written to PA, is used as an operand within the bytecode routine.

The %F bit of the SETQ/SETQ2 {#}D value enables C and Z to receive bits 1 and 0 of the index field of the bytecode. This is useful for having the flags differentiate behavior within a bytecode routine, especially in cases of conditional looping, where a SKIPF pattern would have been insufficient, on its own:

To start executing bytecodes, use the following instruction sequence, but with the appropriate SETQ operand:

        PUSH    #$1FF                'push #$1FF onto the hardware stack

_RET_   SETQ    #$100                '256-long EXECF table at LUT $100, start XBYTE

While developing XBYTE code, you may want to single-step the bytecode execution, in order to inspect what is happening. To do this, you must simulate normal XBYTE operation using a small program. Below is an example of how to do this for the simplest case of the full-8-bit mode which doesn't write the LSBs of the LUT address to C and Z.

SETQ CONSIDERATIONS

The SETQ and SETQ2 instructions write to the Q register and are intended to precede a companion instruction. The value written to the Q register by SETQ/SETQ2 will persist until any of these events occur:

• XORO32 executes - Q is set to the XORO32 result.
• RDLUT executes - Q is set to the data read from the lookup RAM.
• GETXACC executes - Q is set to the Goertzel sine accumulator value.
• CRCNIB executes - Q gets shifted left by four bits.
• COGINIT/QDIV/QFRAC/QROTATE executes without a preceding SETQ instruction - Q is set to zero.

CRCNIB is the only instruction which both inputs Q and outputs Q, requiring it to not be disrupted between the initial SETQ and subsequent CRCNIB(s). For that reason, CRCNIB sequences should be protected from interrupts by STALLI/ALLOWI instructions or by being placed within a REP block, which is automatically shielded from interrupts, including non-stallable debug interrupts.

It is possible to retrieve the current Q value by the following sequence:

MOV        qval,#0                'reset qval

MUXQ        qval,##$FFFFFFFF        'for each '1' bit in Q, set the same bit in qval

SETQ/SETQ2 shields the next instruction from interruption to prevent an interrupt service routine from inadvertently altering Q before the intended instruction can utilize its value.

PIXEL OPERATIONS

Each cog has a pixel mixer which can combine one pixel with another pixel in many different ways. A pixel consists of four byte fields within a 32-bit cog register. Pixel operations occur between each pair of D and S bytes, and they take seven clock cycles to complete:

ADDPIX  D,S/#                        'add bytes with saturation

MULPIX  D,S/#                        'multiply bytes ($FF = 1.0)

BLNPIX  D,S/#                        'alpha-blend bytes according to SETPIV value

MIXPIX  D,S/#                        'mix bytes according to SETPIX/SETPIV value

There are two pixel mixer setup instructions:

SETPIV  D/#                        'set blend factor V[7:0] to D/#[7:0]

SETPIX  D/#                        'set MIXPIX mode M[5:0] to D/#[5:0]

When a pixel mixer instruction executes, a sum-of-products-with-saturation computation is performed on each D and S byte pair:

        D[31:24] = ((D[31:24] * DMIX + S[31:24] * SMIX + $FF) >> 8) max $FF

        D[23:16] = ((D[23:16] * DMIX + S[23:16] * SMIX + $FF) >> 8) max $FF

        D[15:08] = ((D[15:08] * DMIX + S[15:08] * SMIX + $FF) >> 8) max $FF

        D[07:00] = ((D[07:00] * DMIX + S[07:00] * SMIX + $FF) >> 8) max $FF

Here are the DMIX and SMIX terms, according to each instruction:

DACs

Each cog outputs four 8-bit DAC channels that can directly drive the DACs within the pins. For this to work, the pins of interest will need to be configured for DAC-channel output.

        DAC0 can drive the DAC's of all pins numbered %XXXX00.

        DAC1 can drive the DAC's of all pins numbered %XXXX01.

        DAC2 can drive the DAC's of all pins numbered %XXXX10.

        DAC3 can drive the DAC's of all pins numbered %XXXX11.

The background state of these four 8-bit channels can be established by SETDACS:

SETDACS D/#                - Write bytes 3/2/1/0 of D/# to DAC3/DAC2/DAC1/DAC0

The DAC values established by SETDACS will be constantly output, except at times when the streamer and/or colorspace converter override them.

STREAMER

Each cog has a streamer which can automatically output timed state sequences to pins and DACs. It can also capture pin and ADC readings to hub RAM and perform Goertzel computations from smart pins configured as ADC's.

There are five instructions directly associated with the streamer:

SETXFRQ D/#                - Set NCO frequency

XINIT   D/#,S/#        - Issue command immediately, zeroing phase

XZERO   D/#,S/#        - Issue command on final NCO rollover (waits), zeroing phase

XCONT   D/#,S/#        - Issue command on final NCO rollover (waits), continuing phase

GETXACC D                - Get Goertzel X into D and Y into next S, clear X and Y

The streamer uses a numerically-controlled oscillator (NCO) to time its operation. On every clock while the streamer is active, it adds a 32-bit frequency value into a 32-bit phase accumulator, while masking the MSB of the original phase. The NCO can be understood as such:

phase = (phase & $7FFF_FFFF) + frequency

The MSB of the resultant phase value indicates NCO rollover and is used as a trigger to advance the state of the streamer. This is true for every mode except DDS/Goertzel, in which case the streamer runs continuously.

The frequency of the streamer's NCO rollover is set by the 'SETXFRQ D/#' instruction, where D/# expresses a fractional 0-to-1 multiplier for the system clock, which value must be multiplied by $8000_0000. Here are some system clock multipliers and the D/# values that realize them:

1                $8000_0000  (default value on cog start)

1 / 2                 $4000_0000

1 / 3                $2AAA_AAAA+1 *

1 / 4                $2000_0000

1 / 5                $1999_9999+1 *

1 / 6                $1555_5555+1 *

1 / 7                $1249_2492+1 *

1 / 8                $1000_0000

* For fractions with remainders, the computed D/# value should be incremented, in order to produce proper initial rollover behavior.

The NCO frequency may also be set/changed via a 'SETQ D/#' instruction immediately preceding an XINIT/XZERO/XCONT instruction. When the streamer command executes, the new frequency will be set during the first clock of the command. If no SETQ is used before the instruction, the frequency will remain the same when the command executes.

The streamer may be activated by a command from an XINIT/XZERO/XCONT instruction. For these instructions, D/# expresses the streamer mode and duration, while S/# supplies various data, or is ignored, depending upon the mode expressed in D/#.

There is a single-level command buffer in the streamer, enabling you to give it two initial commands before it makes you wait for the first command to finish before accepting another. This command buffer enables you to coordinate streamer activity with smart pin activity. By executing an XINIT and then an XCONT, you get time during the XINIT command to instantiate a smart pin to perform some operation which will then correlate with the queued XCONT command. Think of tossing a ball up gently, so that you can then hit it with a bat.

For the XINIT/XZERO/XCONT instructions, D/#[31:16] conveys the command, while D/#[15:0] conveys the number of NCO rollovers that the command will be active for. S/# is used to select sub-modes for some commands:

D/#[31:16]

Mode DACs Pins Misc   S/#      Description                      Pins     DAC Channels $X3_X2_X1_X0           .

                               Immediate ⇢ LUT ⇢ Pins/DACs

0000 dddd eppp bbbb   <long>   imm -> 32 x 1-bit LUT            32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0001 dddd eppp bbbb   <long>   imm -> 16 x 2-bit LUT            32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0010 dddd eppp bbbb   <long>   imm ->  8 x 4-bit LUT            32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0011 dddd eppp bbbb   <long>   imm ->  4 x 8-bit LUT            32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               Immediate ⇢ Pins/DACs

0100 dddd eppp pppa   <long>   imm 32 x 1  ->  1-pin + 1-DAC1    1 out   %00000000_00000000_00000000_aaaaaaaa

0101 dddd eppp pp0a   <long>   imm 16 x 2  ->  2-pin + 2-DAC1    2 out   %00000000_00000000_bbbbbbbb_aaaaaaaa

0101 dddd eppp pp1a   <long>   imm 16 x 2  ->  2-pin + 1-DAC2    2 out   %00000000_00000000_00000000_babababa

0110 dddd eppp p00a   <long>   imm  8 x 4  ->  4-pin + 4-DAC1    4 out   %dddddddd_cccccccc_bbbbbbbb_aaaaaaaa

0110 dddd eppp p01a   <long>   imm  8 x 4  ->  4-pin + 2-DAC2    4 out   %00000000_00000000_dcdcdcdc_babababa

0110 dddd eppp p10a   <long>   imm  8 x 4  ->  4-pin + 1-DAC4    4 out   %00000000_00000000_00000000_dcbadcba

0110 dddd eppp 0110   <long>   imm  4 x 8  ->  8-pin + 4-DAC2    8 out   %hghghghg_fefefefe_dcdcdcdc_babababa

0110 dddd eppp 0111   <long>   imm  4 x 8  ->  8-pin + 2-DAC4    8 out   %00000000_00000000_hgfehgfe_dcbadcba

0110 dddd eppp 1110   <long>   imm  4 x 8  ->  8-pin + 1-DAC8    8 out   %00000000_00000000_00000000_hgfedcba

0110 dddd eppp 1111   <long>   imm  2 x 16 -> 16-pin + 4-DAC4   16 out   %ponmponm_lkjilkji_hgfehgfe_dcbadcba

0111 dddd eppp 0000   <long>   imm  2 x 16 -> 16-pin + 2-DAC8   16 out   %00000000_00000000_ponmlkji_hgfedcba

0111 dddd eppp 0001   <long>   imm  1 x 32 -> 32-pin + 4-DAC8   32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               RDFAST ⇢ LUT ⇢ Pins/DACs

0111 dddd eppp 001a   bbbb     RFLONG -> 32 x 1-bit LUT         32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0111 dddd eppp 010a   bbbb     RFLONG -> 16 x 2-bit LUT         32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0111 dddd eppp 011a   bbbb     RFLONG ->  8 x 4-bit LUT         32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

0111 dddd eppp 1000   bbbb     RFLONG ->  4 x 8-bit LUT         32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               RDFAST ⇢ Pins/DACs

1000 dddd eppp pppa   -    1/8 RFBYTE ->  1-pin + 1-DAC1         1 out   %00000000_00000000_00000000_aaaaaaaa

1001 dddd eppp pp0a   -    1/4 RFBYTE ->  2-pin + 2-DAC1         2 out   %00000000_00000000_bbbbbbbb_aaaaaaaa

1001 dddd eppp pp1a   -    1/4 RFBYTE ->  2-pin + 1-DAC2         2 out   %00000000_00000000_00000000_babababa

1010 dddd eppp p00a   -    1/2 RFBYTE ->  4-pin + 4-DAC1         4 out   %dddddddd_cccccccc_bbbbbbbb_aaaaaaaa

1010 dddd eppp p01a   -    1/2 RFBYTE ->  4-pin + 2-DAC2         4 out   %00000000_00000000_dcdcdcdc_babababa

1010 dddd eppp p10a   -    1/2 RFBYTE ->  4-pin + 1-DAC4         4 out   %00000000_00000000_00000000_dcbadcba

1010 dddd eppp 0110   -        RFBYTE ->  8-pin + 4-DAC2         8 out   %hghghghg_fefefefe_dcdcdcdc_babababa

1010 dddd eppp 0111   -        RFBYTE ->  8-pin + 2-DAC4         8 out   %00000000_00000000_hgfehgfe_dcbadcba

1010 dddd eppp 1110   -        RFBYTE ->  8-pin + 1-DAC8         8 out   %00000000_00000000_00000000_hgfedcba

1010 dddd eppp 1111   -        RFWORD -> 16-pin + 4-DAC4        16 out   %ponmponm_lkjilkji_hgfehgfe_dcbadcba

1011 dddd eppp 0000   -        RFWORD -> 16-pin + 2-DAC8        16 out   %00000000_00000000_ponmlkji_hgfedcba

1011 dddd eppp 0001   -        RFLONG -> 32-pin + 4-DAC8        32 out   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               RDFAST ⇢ RGB ⇢ Pins/DACs

1011 dddd eppp 0010   rgb      RFBYTE -> 24-pin + LUMA8         32 out   %rrrrrrrr_gggggggg_bbbbbbbb_00000000

1011 dddd eppp 0011   -        RFBYTE -> 24-pin + RGBI8         32 out   %rrrrrrrr_gggggggg_bbbbbbbb_00000000

1011 dddd eppp 0100   -        RFBYTE -> 24-pin + RGB8  (3:3:2) 32 out   %rrrrrrrr_gggggggg_bbbbbbbb_00000000

1011 dddd eppp 0101   -        RFWORD -> 24-pin + RGB16 (5:6:5) 32 out   %rrrrrrrr_gggggggg_bbbbbbbb_00000000

1011 dddd eppp 0110   -        RFLONG -> 24-pin + RGB24 (8:8:8) 32 out   %rrrrrrrr_gggggggg_bbbbbbbb_00000000

                               Pins ⇢ DACs/WRFAST

1100 dddd wppp pppa   -         1-pin -> 1-DAC1 + 1/8 WFBYTE     1 in    %00000000_00000000_00000000_aaaaaaaa

1101 dddd wppp pp0a   -         2-pin -> 2-DAC1 + 1/4 WFBYTE     2 in    %00000000_00000000_bbbbbbbb_aaaaaaaa

1101 dddd wppp pp1a   -         2-pin -> 1-DAC2 + 1/4 WFBYTE     2 in    %00000000_00000000_00000000_babababa

1110 dddd wppp p00a   -         4-pin -> 4-DAC1 + 1/2 WFBYTE     4 in    %dddddddd_cccccccc_bbbbbbbb_aaaaaaaa

1110 dddd wppp p01a   -         4-pin -> 2-DAC2 + 1/2 WFBYTE     4 in    %00000000_00000000_dcdcdcdc_babababa

1110 dddd wppp p10a   -         4-pin -> 1-DAC4 + 1/2 WFBYTE     4 in    %00000000_00000000_00000000_dcbadcba

1110 dddd wppp 0110   -         8-pin -> 4-DAC2 + WFBYTE         8 in    %hghghghg_fefefefe_dcdcdcdc_babababa

1110 dddd wppp 0111   -         8-pin -> 2-DAC4 + WFBYTE         8 in    %00000000_00000000_hgfehgfe_dcbadcba

1110 dddd wppp 1110   -         8-pin -> 1-DAC8 + WFBYTE         8 in    %00000000_00000000_00000000_hgfedcba

1110 dddd wppp 1111   -        16-pin -> 4-DAC4 + WFWORD        16 in    %ponmponm_lkjilkji_hgfehgfe_dcbadcba

1111 dddd wppp 0000   -        16-pin -> 2-DAC8 + WFWORD        16 in    %00000000_00000000_ponmlkji_hgfedcba

1111 dddd wppp 0001   -        32-pin -> 4-DAC8 + WFLONG        32 in    %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               ADCs/Pins ⇢ DACs/WRFAST

1111 dddd w--- 0010   ss           1-ADC8 -> 1-DAC8 + WFBYTE     8 in    %00000000_00000000_00000000_hgfedcba

1111 dddd wppp 0011   ss   1-ADC8 + 8-pin -> 2-DAC8 + WFWORD    16 in    %00000000_00000000_ponmlkji_hgfedcba

1111 dddd w--- 0100   s-           2-ADC8 -> 2-DAC8 + WFWORD    16 in    %00000000_00000000_ponmlkji_hgfedcba

1111 dddd wppp 0101   s-  2-ADC8 + 16-pin -> 4-DAC8 + WFLONG    32 in    %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

1111 dddd w--- 0110   --           4-ADC8 -> 4-DAC8 + WFLONG    32 in    %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

                               DDS/Goertzel

1111 dddd 0ppp p111   <config>     DDS/Goertzel LUT SINC1 *   4 in ADC   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

1111 dddd 1ppp p111   <config>     DDS/Goertzel LUT SINC2 *   4 in ADC   %PONMLKJI_HGFEDCBA_ponmlkji_hgfedcba

Each of these modes requires explanation, but there are some overlapping matters that can be covered first.

The 16-bit D[15:0] field expresses an initial counter value which will be decremented on each subsequent NCO rollover, with each rollover causing new streamer data to be output or input. When the counter equals 1 and the NCO is rolling over for the last time for the current command, a new command may be seamlessly begun by a buffered XZERO/XCONT instruction. If no XZERO/XCONT instruction is buffered, the counter goes to 0. When the counter reaches 0, or is set to 0, streamer operation stops and all streamer DAC overrides and streamer pin outputs cease.

By setting the D[15:0] count to its maximal value of $FFFF, a streamer command will run perpetually.

XINIT (re)starts the streamer, no matter what state it is in. 'XINIT #0,#0' will always stop the streamer immediately. XSTOP (no operands) is an alias for 'XINIT #0,#0'.

XZERO and XCONT are used to maintain seamless streamer I/O, from command to command. They wait for the prior command's last clock cycle. If the streamer count has already run down to 0, there is no waiting. Also, if the prior command used $FFFF for its initial count, in which case the streamer is running perpetually without decrementing its counter, a new XZERO/XCONT command will only wait for the next NCO rollover, at which point the streamer will begin executing the new command.

XZERO clears out the phase accumulator when it executes. This clearing is desirable when, say, pixels are being output at 1/3 Fclk and and you don't want a 1-clock delay (glitch) every ~30 seconds, due to imperfect fractions like %5555_5555 = ~1/3. In such a case, it would be good to use XZERO to initiate the horizontal sync pulse, while using XCONT everywhere else. It may also be desirable to increment such frequency values by 1, so that the initial NCO rollover occurs on the Nth clock, and not on the Nth+1 clock.

XCONT is like XZERO, but does not affect the phase accumulator. XCONT is useful in cases where NCO phase and frequency should be strictly maintained and streamer activity should ride along with it.

The streamer has four DAC output channels, X0, X1, X2 and X3, which can selectively override the four SETDACS values on a per-DAC basis. To bring out the data as a voltage on a pin, that pin must be set to DAC mode with the COGID embedded, via WRPIN, and DIR must be set high.

The %dddd field in D[27:24] selects which streamer DAC channels will override which SETDACS values during active streamer operation. In the table below, "--" indicates no-override and "!" indicates one's-complement:

             DAC Channel

    dddd     3   2   1   0      description                                          .

    0000     --  --  --  --     no streamer DAC output

    0001     X0  X0  X0  X0     output X0 on all four DAC channels

    0010     --  --  X0  X0     output X0 on DAC channels 1 and 0

    0011     X0  X0  --  --     output X0 on DAC channels 3 and 2

    0100     --  --  --  X0     output X0 on DAC channel 0

    0101     --  --  X0  --     output X0 on DAC channel 1

    0110     --  X0  --  --     output X0 on DAC channel 2

    0111     X0  --  --  --     output X0 on DAC channel 3

    1000    !X0  X0 !X0  X0     output X0 diff pairs on all four DAC channels

    1001     --  -- !X0  X0     output X0 diff pairs on DAC channels 1 and 0

    1010    !X0  X0  --  --     output X0 diff pairs on DAC channels 3 and 2

    1011     X1  X0  X1  X0     output X1, X0 pairs on all four DAC channels

    1100     --  --  X1  X0     output X1, X0 on DAC channels 1 and 0

    1101     X1  X0  --  --     output X1, X0 on DAC channels 3 and 2

    1110    !X1  X1 !X0  X0     output X1, X0 diff pairs on all four DAC channels

    1111     X3  X2  X1  X0     output X3, X2, X1, X0 on all four DAC channels

Modes which can output to pins OR the streamer pin-output bus with {OUTB, OUTA} to produce the final 64 pin output states on each clock for the cog. For these modes, %e in D[23] must be '1' to enable pin output.

Modes which input from pins read {INB, INA} and can optionally write the pin data to hub RAM. For these modes, %w in D[23] must be '1' to enable automatic WFBYTE/WFWORD/WFLONG operations.

In every mode^[l], the three %ppp bits in D[22:20] select the pin group, in 8-pin increments, which will be used as outputs or inputs, for up to 32-pin transfers. The selection wraps around:

         %ppp : 000 = select pins 31..0

                001 = select pins 39..8

                010 = select pins 47..16

                011 = select pins 55..24

                100 = select pins 63..32

                101 = select pins 7..0, 63..40

                110 = select pins 15..0, 63..48

                111 = select pins 23..0, 63..56

For modes which involve less than 8 pins, lower-order %p bit(s) in D[19:19..17] are used to further resolve the pin number(s)^[m].

Modes which shift data use bits bottom-first, by default. Some of these modes have the %a bit in D[16] to reorder the data sequence within the individual bytes to top-first when %a = 1^[n].

For RDFAST modes, it is necessary to do a RDFAST sometime beforehand, to ensure that the hub RAM FIFO is ready to deliver data.

For WRFAST modes, it is necessary to do a WRFAST sometime beforehand, to ensure that the hub RAM FIFO is ready to receive data.

Immediate ⇢ LUT ⇢ Pins/DACs

S/# supplies 32 bits of data which form a set of 1/2/4/8-bit values that are shifted by 1/2/4/8 bits on each subsequent NCO rollover, with the last value repeating. Each value gets used as an offset address into lookup RAM, with the %bbbb bits in D[19:16] furnishing the base address of %bbbb00000. The resulting 32 bits of data read from lookup RAM (at %bbbb00000 + 1/2/4/8-bit value) are output.

Immediate ⇢ Pins/DACs

S/# supplies 32 bits of data which form a set of 1/2/4/8/16-bit values that are shifted by 1/2/4/8/16/32 bits on each subsequent NCO rollover, with the last value repeating. Each value is output in sequence.

RDFAST ⇢ LUT ⇢ Pins/DACs

Automatic RFLONG operations are done to read 32 bits at a time from hub RAM. The data are treated as a set of 1/2/4/8-bit values that are shifted by 1/2/4/8 bits on each subsequent NCO rollover, with the last value triggering a new RFLONG. Each value gets used as an offset address into lookup RAM, with the %bbbb bits in S[3:0] furnishing the base address of %bbbb00000. The resultant 32 bits of data read from lookup RAM (at %bbbb00000 + 1/2/4/8-bit value) are output.

RDFAST ⇢ Pins/DACs

Automatic RFBYTE/RFWORD/RFLONG operations are done to read 8/16/32 bits at a time from hub RAM. The data are treated as a set of 1/2/4/8/16/32-bit values that are shifted by 1/2/4/8/16/32 bits on each subsequent NCO rollover, with the last value triggering a new RFBYTE/RFWORD/RFLONG. Each value is output in sequence.

RDFAST ⇢ RGB ⇢ Pins/DACs

RFBYTE/RFWORD/RFLONG operations, done initially and on each subsequent NCO rollover, read 8/16/32-bit pixel values from hub RAM. The pixel values P[31/15/7:0] are translated into {R[7:0], G[7:0], B[7:0], 8'b0} values and output to X3, X2, X1, and X0.

LUMA8 mode uses three bits in S[2:0] as colors and the 8-bit pixels as luminance values:

RGBI8 mode uses the top three bits of the 8-bit pixel values as colors and the bottom 5 bits as luminance values:

RGB8 mode uses the top three bits of the 8-bit pixel values for red, the next three for green, and the last two for blue:

RGB16 mode uses the top five bits of the 16-bit pixel values for red, the next six for green, and the last five for blue:

RGB24 mode uses the top three bytes of the 32-bit pixel values for red, green, and blue:

Pins ⇢ DACs/WRFAST

Initially, and on each subsequent NCO rollover, 1/2/4/8/16/32 pins are read from {INB, INA} and X3, X2, X1, and X0 are updated using the read data. If the %w bit in D[23] is high, WFBYTE/WFWORD/WFLONG operations will be done automatically to record the pin data. In the case of 1/2/4-pin modes, a WFBYTE will be done each time 8 bits of pin data accrue.

ADCs/Pins ⇢ DACs/WRFAST

This mode captures SCOPE channel data, along with optional pin data from {INB, INA}.

It will be necessary to use the SETSCP instruction beforehand to select the block of four pins which will feed the four 8-bit SCOPE channels. Any pins, within that block of four, that will be used as the ADC8 input(s) for this mode, must be put into "ADC sample" or "ADC scope" smart pin mode and enabled.

For the 1-ADC8 modes, where one of four SCOPE channels will be captured, the %ss bits in S[1:0] select the channel.

For the 2-ADC8 modes, where two of four SCOPE channels will be captured, the %s bit in S[1] selects the upper two or lower two channels.

For the 4-ADC8 mode, all four SCOPE channels will be captured.

For modes which also capture pin data, the lower 8 or 16 pins of the 32 pins selected by the %ppp bits in D[22:20] will be captured and placed into the lower half of the word/long, while the one or two SCOPE channels will be placed into the upper half.

Initially, and on each subsequent NCO rollover, SCOPE channel data and optional pin data are read and X3, X2, X1, and X0 are updated. If the %w bit in D[23] is high, WFBYTE/WFWORD/WFLONG operations will be done automatically to record the ADC and optional pin data.

DDS/Goertzel

This mode is unique, in that it outputs and inputs on every clock in which the command is active. Its purpose is to perform direct digital synthesis (DDS) on up to four DAC channels and/or to perform simultaneous Goertzel analysis on up to four ADC bit streams summed together.

On each clock, the upper bits of the NCO are used as an index to read a long containing four signed bytes from lookup RAM. The four bytes are output to X3, X2, X1, and X0 with their MSBs inverted, so that they may drive the unsigned DACs. The top two bytes from lookup RAM are also used as sine and cosine inputs to the Goertzel analyzer, where they are each multiplied by the sum of up to four ADC bitstreams and then separately accumulated.

Goertzel analysis can be thought of as a single slice of a Fourier transform, in which energy of a single frequency is measured amid potential noise for some number of NCO cycles. Goertzel analysis returns sine and cosine accumulations which can be converted into polar coordinates using the QVECTOR instruction, yielding power and phase information.

By incorporating DDS output with simultaneous Goertzel input, many interactive real-world measurements can be made to determine things like time-of-flight and resonance.

The four-pin input block is selected by the %pppp bits in D/#[22:19], where %pppp*4 is the base pin. One to four of these pins should be configured for ADC mode, so that their IN signals are raw delta-sigma bit streams, with no smart pin mode selected. For IN bitstream summation, '0' values are treated as -1 and '1' values are treated as +1. For cases of two or four input channels summed together, the sum is always even, so it is shifted right by one bit to conserve multiplication and accumulator resources.

S[19:0] supplies a 20-bit value which is used to configure the DDS/Goertzel mode. S[19:16] selects which of the four input pins are to be inverted, allowing for both addition and subtraction of particular input channels, while S[15:12] selects which of the four pins are to be included in the summation:

        S[19:12]                Effect

%xxxx_xxx0        Base pin +0 is ignored

%xxx0_xxx1        Base pin +0 is summed                (0 ⇢ -1, 1 ⇢ +1)

%xxx1_xxx1        Base pin +0 is inverted and summed   (0 ⇢ +1, 1 ⇢ -1)

%xxxx_xx0x        Base pin +1 is ignored

%xx0x_xx1x        Base pin +1 is summed

%xx1x_xx1x        Base pin +1 is inverted and summed

%xxxx_x0xx        Base pin +2 is ignored

%x0xx_x1xx        Base pin +2 is summed

%x1xx_x1xx        Base pin +2 is inverted and summed

%xxxx_0xxx        Base pin +3 is ignored

%0xxx_1xxx        Base pin +3 is summed

%1xxx_1xxx        Base pin +3 is inverted and summed

S[11:0] selects how much and what part of the lookup RAM will be used, along with an offset:

S[11:0]                        Loop Size        NCO Bits        LUT Range

%000_TTTTTTTTT        512                30..22                %000000000..%111111111

%001_ATTTTTTTT        256                30..23                %A00000000..%A11111111

%010_AATTTTTTT        128                30..24                %AA0000000..%AA1111111

%011_AAATTTTTT        64                30..25                %AAA000000..%AAA111111

%100_AAAATTTTT        32                30..26                %AAAA00000..%AAAA11111

%101_AAAAATTTT        16                30..27                %AAAAA0000..%AAAAA1111

%110_AAAAAATTT        8                30..28                %AAAAAA000..%AAAAAA111

%111_AAAAAAATT        4                30..29                %AAAAAAA00..%AAAAAAA11

On each clock, the lookup RAM is read at the 9-bit location bound by the %A bits, with the lower bits being the sum of the %T bits and the topmost NCO bits. This allows you to set bounded areas within the LUT and to shift or modulate the phase of playback.

The 8-bit sine (byte 3) and cosine (byte 2) values from the lookup RAM will each be multiplied by the bitstream sum (an integer from -3 to +3) and then added into their respective 32-bit accumulators.

After some number of complete NCO cycles, both accumulators can be simultaneously captured into holding registers and cleared using the GETXACC instruction. GETXACC writes the captured cosine accumulation into D and places the captured sine accumulation into the next instruction's S value. Subsequent GETXACC instructions will return the same values until a new streamer command executes.

D[23] selects between SINC1 and SINC2 accumulation modes:

D[23]        Mode                Accumulations (SIN_ACC/COS_ACC are read and cleared by GETXACC)

%0        SINC1                SIN_MUL = bitstream_sum * lookup_sin

                        COS_MUL = bitstream_sum * lookup_cos

                        SIN_ACC += SIN_MUL

                        COS_ACC += COS_MUL

%1        SINC2                SIN_MUL += bitstream_sum * lookup_sin

                        COS_MUL += bitstream_sum * lookup_cos

                        SIN_ACC += SIN_MUL

                        COS_ACC += COS_MUL

The program below demonstrates both SINC1 and SINC2 modes in a looped Goertzel measurement of 100 cycles of 1MHz, taking 100us per measurement. The 4th line of the program must be changed to "sinc2 = 1" to select SINC2 mode:

In the pictures that follow, you can see the program's DAC output pin while a function generator drives a 0-3.3V frequency-swept sine wave into the ADC input pin, going from 950-1050KHz over 12ms, while the program measures the energy level at 1MHz:

You can see that SINC2 mode has a higher Q than SINC1 mode. Due to rapid (X,Y) accumulator growth, SINC2 may require the sine/cosine table to be reduced in amplitude to avoid (X,Y) accumulator overflow. This was done in the example program above, where it was reduced from ±127 for SINC1 to ±10 for SINC2.

NOTE ABOUT GOERTZEL SINC2 MODE (2024.12.16)

It has just been discovered that the Goertzel SINC2 mode generates periodic problematic GETXACC readings when the number of iterations in a Goertzel cycle varies, due to SETXFREQ's D being a non-power-of-two value. The example code above was modified so that the clock frequency is now 256 MHz, instead of 250 MHz, so that the 1MHz being listened to will always take 256 clocks per Goertzel cycle. This causes the double-integrating accumulators in SINC2 mode to always have the same number of iterations before a GETXACC instruction executes and captures the double accumulations. Being off by a single clock cycle will corrupt the current and next samples.

Digital Video Output (DVI/HDMI)

The streamer can serialize its internal 32 pin output data P[31:0] into 8-pin/10-bit digital video format, where the 32-pin output becomes $000000xx with $xx being a reversible pattern of RED, GRN, BLU, and CLK differential pairs.

The SETCMOD instruction is used to write bits 8:7 of the CMOD register to set digital video mode:

Eight-bit red, green, and blue pixel data are encoded into 10-bit TMDS patterns for transmission, while control data, such as horizontal and vertical syncs, are transmitted literally. P[1] in the internal pin output data selects whether data will be TMDS-encoded or sent out literally:

Digital video output mode requires that the P2 clock frequency be 10x the pixel rate. For standard-compliant 640x480 digital video, which has a pixel rate of 25MHz, the P2 chip should be clocked at 250MHz.

The NCO frequency must be set to 1/10 of the main clock using the value $0CCCCCCC+1, where the +1 forces initial NCO rollover on the 10th clock.

The following program displays a 16bpp image in 640x480 HDMI mode:

COLORSPACE CONVERTER

Each cog has a colorspace converter which can perform ongoing matrix transformations and modulation of the cog's 8-bit DAC channels. The colorspace converter is intended primarily for baseband video modulation, but it can also be used as a general-purpose RF modulator.

The colorspace converter is configured via the following instructions:

SETCY   {#}D                - Set colorspace converter CY parameter to D[31:0]

SETCI   {#}D                - Set colorspace converter CI parameter to D[31:0]

SETCQ   {#}D                - Set colorspace converter CQ parameter to D[31:0]

SETCFRQ {#}D                - Set colorspace converter CFRQ parameter to D[31:0]

SETCMOD {#}D                - Set colorspace converter CMOD parameter to D[8:0]

It is intended that DAC3/DAC2/DAC1 serve as R/G/B channels. On each clock, new matrix and modulation calculations are performed through a pipeline. There is a group delay of five clocks from DAC-channel inputs to outputs when the colorspace converter is in use.

For the following signed multiply-accumulate computations, CMOD[4] determines whether the CY/CI/CQ terms will be sign-extended (CMOD[4] = 1) or zero-extended (CMOD[4] = 0). If zero-extended, using 128 for a CY/CI/CQ term will result in no attenuation of the related DAC term:

Y[7:0]                = (DAC3 * CY[31:24] + DAC2 * CY[23:16] + DAC1 * CY[15:8]) / 128

I[7:0]                = (DAC3 * CI[31:24] + DAC2 * CI[23:16] + DAC1 * CI[15:8]) / 128

Q[7:0]                = (DAC3 * CQ[31:24] + DAC2 * CQ[23:16] + DAC1 * CQ[15:8]) / 128

The modulator works by subtracting CFRQ from PHS on each clock cycle, in order to get a clockwise angle rotation in the upper bits of PHS. PHS[31:24] is then used to rotate the coordinate pair (I, Q). The rotated Q coordinate becomes IQ. Because a 5-stage CORDIC rotator is used to perform the rotation, IQ gets scaled by 1.646. When using the modulator, this scaling will need to be taken into account when computing your CI/CQ terms, in order to avoid IQ overflow:

PHS[31:0]        = PHS[31:0] - CFRQ[31:0]

IQ[7:0]        = Q of (I,Q) after being rotated by PHS and multiplied by 1.646

The formula for computing CFRQ for a desired modulation frequency is: $1_0000_0000 * desired_frequency / clock_frequency. For example, if you wanted 3.579545 MHz and your clock frequency was 80 MHz, you would compute: $1_0000_0000 * 3_579_545 / 80_000_000 = $0B74_5CFE, which you would set using the SETCFRQ instruction.

The preliminary output terms are computed as follows:

FY[7:0]        = CY[7:0] + (DAC0 & {8{CMOD[3]}}) + Y[7:0]        (VGA R / HDTV Y)

FI[7:0]        = CI[7:0] + (DAC0 & {8{CMOD[2]}}) + I[7:0]        (VGA G / HDTV Pb)

FQ[7:0]        = CQ[7:0] + (DAC0 & {8{CMOD[1]}}) + Q[7:0]        (VGA B / HDTV Pr)

FS[7:0]        = {8{DAC0[0] ^ CMOD[0]}}                                (VGA H-Sync)

FIQ[7:0]        = CQ[7:0] + IQ[7:0]                                        (Chroma)

FYS[7:0]        = DAC0[1]        ?        8'b0                                (1x = Luma Sync)

                : DAC0[0]        ?        CI[7:0]                        (01 = Luma Blank/Burst)

                                :        CY[7:0] + Y[7:0]                (00 = Luma Visible)

FYC[7:0]        = FYS[7:0] + IQ[7:0]                                (Composite Luma+Chroma)

The final output terms are selected by CMOD[6:5]:

I/O PIN TIMING

I/O pins are controlled by cogs via the following cog registers:

        DIRA        - output enable bits for P0..P31 (active high)

        DIRB        - output enable bits for P32..P63 (active high)

        OUTA        - output state bits for P0..P31 (corresponding DIRA bit must be high to enable output)

        OUTB        - output state bits for P32..P63 (corresponding DIRB bit must be high to enable output)

I/O pins are read by cogs via the following cog registers:

        INA        - input state bits for P0..P31

        INB        - input state bits for P32..P63

Aside from general-purpose instructions which may operate on DIRA/DIRB/OUTA/OUTB, there are special pin instructions which operate on singular bits within these registers:

        DIRL/DIRH/DIRC/DIRNC/DIRZ/DIRNZ/DIRRND/DIRNOT {#}D                - affect pin D bit in DIRx

        OUTL/OUTH/OUTC/OUTNC/OUTZ/OUTNZ/OUTRND/OUTNOT {#}D        - affect pin D bit in OUTx

        FLTL/FLTH/FLTC/FLTNC/FLTZ/FLTNZ/FLTRND/FLTNOT {#}D                - affect pin D bit in OUTx, clear bit in DIRx

        DRVL/DRVH/DRVC/DRVNC/DRVZ/DRVNZ/DRVRND/DRVNOT {#}D        - affect pin D bit in OUTx, set bit in DIRx

As well, aside from general-purpose instructions which may read INA/INB, there are special pin instructions which can read singular bits within these registers:

        TESTP {#}D WC/WZ/ANDC/ANDZ/ORC/ORZ/XORC/XORZ                - read pin D bit in INx and affect C or Z

        TESTPN {#}D WC/WZ/ANDC/ANDZ/ORC/ORZ/XORC/XORZ                - read pin D bit in !INx and affect C or Z

When a DIRx/OUTx bit is changed by any instruction, it takes THREE additional clocks after the instruction before the pin starts transitioning to the new state. Here this delay is demonstrated using DRVH:

                 ____0     ____1     ____2     ____3     ____4     ____5    

Clock:          /    \____/    \____/    \____/    \____/    \____/    \____/

DIRA:           |         |  DIRA-->|   REG-->|   REG-->|   REG-->| P0 DRIV |

OUTA:           |         |  OUTA-->|   REG-->|   REG-->|   REG-->| P0 HIGH |

                |                   |

Instruction:    | DRVH #0           |                                        

When an INx register is read by an instruction, it will reflect the state of the pins registered THREE clocks before the start of the instruction. Here this delay is demonstrated using TESTB:

                 ____0     ____1     ____2     ____3     ____4     ____5    

Clock:          /    \____/    \____/    \____/    \____/    \____/    \____/

INA:            | P0 IN-->|   REG-->|   REG-->|   REG-->|   ALU-->|   C/Z-->|

                                                        |                   |

Instruction:                                            | TESTB INA,#0      |

When a TESTP/TESTPN instruction is used to read a pin, the value read will reflect the state of the pin registered TWO clocks before the start of the instruction. So, TESTP/TESTPN get fresher INx data than is available via the INx registers:

                 ____0     ____1     ____2     ____3     ____4    

Clock:          /    \____/    \____/    \____/    \____/    \____/

INA:            | P0 IN-->|   REG-->|   REG-->|   REG-->|   C/Z-->|

                                              |                   |

Instruction:                                  | TESTP #0          |

COG ATTENTION

Each cog can request the attention of other cogs by using the COGATN instruction:

COGATN  D/#                                        'get attention of cog(s), 2 clocks

The D/# operand supplies a 16-bit value in which bits 0..15 represent cogs 0..15. For each set bit, the corresponding c^[o]og will be strobed, causing an 'attention' event for POLLATN/WAITATN and interrupt use. The 16 attention strobe outputs from all cogs are OR'd together to form a composite set of 16 strobes, from which each cog receives its particular strobe.

COGATN  #%0000_0000_1111_0000                'request attention of cogs 4..7

POLLATN WC                                        'has attention been requested?

WAITATN                                        'wait for attention request

JATN    S/#                                        'jump to S/# if attention requested

JNATN   S/#                                        'jump to S/# if attention not requested

In cases where multiple cogs may be requesting the attention of a single cog, some messaging structure may need to be implemented in hub RAM, in order to differentiate requests. In the main intended use case, the cog that is receiving an attention request knows which other cog is strobing it and how it is to respond.

EVENTS

Cogs monitor and track 16 different background events, numbered 0..15:

• Event 0 = An interrupt occurred
• Event 1 = CT passed CT1 (CT is the lower 32-bits of the free-running 64-bit global counter)
• Event 2 = CT passed CT2
• Event 3 = CT passed CT3
• Event 4 = Selectable event 1 occurred
• Event 5 = Selectable event 2 occurred
• Event 6 = Selectable event 3 occurred
• Event 7 = Selectable event 4 occurred
• Event 8 = A pattern match or mismatch occurred on either INA or INB
• Event 9 = Hub FIFO block-wrap occurred - a new start address and block count were loaded
• Event 10 = Streamer command buffer is empty - it's ready to accept a new command
• Event 11 = Streamer finished - it ran out of commands, now idle
• Event 12 = Streamer NCO rollover occurred
• Event 13 = Streamer read lookup RAM location $1FF
• Event 14 = Attention was requested by another cog or other cogs
• Event 15 = GETQX/GETQY executed without any CORDIC results available

Events are tracked and can be polled, waited for, and used as interrupt sources.

Before explaining the details, consider the event-related instructions.

First are the POLLxxx instructions which simultaneously return their event-occurred flag into C and/or Z, and clear their event-occurred flag (unless it's being set again by the event sensor):

                                                                        Interrupt source (0=off):

POLLINT        Poll the interrupt-occurred event flag                        -

POLLCT1        Poll the CT-passed-CT1 event flag                                1

POLLCT2        Poll the CT-passed-CT2 event flag                                2

POLLCT3        Poll the CT-passed-CT3 event flag                                3

POLLSE1        Poll the selectable-event-1 event flag                        4

POLLSE2        Poll the selectable-event-2 event flag                        5

POLLSE3        Poll the selectable-event-3 event flag                        6

POLLSE4        Poll the selectable-event-4 event flag                        7

POLLPAT        Poll the pin-pattern-detected event flag                        8

POLLFBW        Poll the hub-FIFO-interface-block-wrap event flag                9

POLLXMT        Poll the streamer-empty event flag                                10

POLLXFI        Poll the streamer-finished event flag                                11

POLLXRO        Poll the streamer-NCO-rollover event flag                        12

POLLXRL        Poll the streamer-lookup-RAM-$1FF-read event flag                13

POLLATN        poll the attention-requested event flag                        14

POLLQMT        Poll the CORDIC-read-but-no-results event flag                15

Next are the WAITxxx instructions, which will wait for their event-occurred flag to be set (in case it's not, already) and then clear their event-occurred flag (unless it's being set again by the event sensor), before resuming.

By doing a SETQ right before one of these instructions, you can supply a future CT target value which will be used to end the wait prematurely, in case the event-occurred flag never went high before the CT target was reached. When using SETQ with 'WAITxxx WC', C will be set if the timeout occurred before the event; otherwise, C will be cleared.

WAITINT        Wait for an interrupt to occur, stalls the cog to save power

WAITCT1        Wait for the CT-passed-CT1 event flag

WAITCT2        Wait for the CT-passed-CT2 event flag

WAITCT3        Wait for the CT-passed-CT3 event flag

WAITSE1        Wait for the selectable-event-1 event flag

WAITSE2        Wait for the selectable-event-2 event flag

WAITSE3        Wait for the selectable-event-3 event flag

WAITSE4        Wait for the selectable-event-4 event flag

WAITPAT        Wait for the pin-pattern-detected event flag

WAITFBW        Wait for the hub-FIFO-interface-block-wrap event flag

WAITXMT        Wait for the streamer-empty event flag

WAITXFI        Wait for the streamer-finished event flag

WAITXRO        Wait for the streamer-NCO-rollover event flag

WAITXRL        Wait for the streamer-lookup-RAM-$1FF-read event flag

WAITATN        Wait for the attention-requested event flag

There's no 'WAITQMT' because the event could not happen while waiting.

Last are the 'Jxxx/JNxxx S/#' instructions, which each jump to S/# if their event-occurred flag is set (Jxxx) or clear (JNxxx). Whether or not a branch occurs, the event-occurred flag will be cleared, unless it's being set again by the event sensor.

JINT/JNINT        Jump to S/# if the interrupt-occurred event flag is set/clear

JCT1/JNCT1        Jump to S/# if the CT-passed-CT1 event flag is set/clear

JCT2/JNCT2        Jump to S/# if the CT-passed-CT2 event flag is set/clear

JCT3/JNCT3         Jump to S/# if the CT-passed-CT3 event flag is set/clear

JSE1/JNSE1        Jump to S/# if the selectable-event-1 event flag is set/clear

JSE2/JNSE2        Jump to S/# if the selectable-event-2 event flag is set/clear

JSE3/JNSE3        Jump to S/# if the selectable-event-3 event flag is set/clear

JSE4/JNSE4        Jump to S/# if the selectable-event-4 event flag is set/clear

JPAT/JNPAT        Jump to S/# if the pin-pattern-detected event flag is set/clear

JFBW/JNFBW        Jump to S/# if the hub-FIFO-interface-block-wrap event flag is set/clear

JXMT/JNXMT        Jump to S/# if the streamer-empty event flag is set/clear

JXFI/JNXFI        Jump to S/# if the streamer-finished event flag is set/clear

JXRO/JNXRO        Jump to S/# if the streamer-NCO-rollover event flag is set/clear

JXRL/JNXRL        Jump to S/# if the streamer-lookup-RAM-$1FF-read event flag is set/clear

JATN/JNATN        Jump to S/# if the attention-requested event flag is set/clear

JQMT/JNQMT        Jump to S/# if the CORDIC-read-but-no-results event flag is set/clear

Here are detailed descriptions of each event flag. Understand that the 'set' events can also be used as interrupt sources (except in the case of the first flag which is set when an interrupt occurs):

POLLINT/WAITINT event flag

• Cleared on cog start.
• Set whenever interrupt 1, 2, or 3 occurs (debug interrupts are ignored).
• Also cleared on POLLINT/WAITINT/JINT/JNINT.

POLLCT1/WAITCT1 event flag

• Cleared on ADDCT1.
• Set whenever CT passes the result of the ADDCT1 (MSB of CT minus CT1 is 0).
• Also cleared on POLLCT1/WAITCT1/JCT1/JNCT1.

POLLCT2/WAITCT2 event flag

• Cleared on ADDCT2.
• Set whenever CT passes the result of the ADDCT2 (MSB of CT minus CT2 is 0).
• Also cleared on POLLCT2/WAITCT2/JCT2/JNCT2.

POLLCT3/WAITCT3 event flag

• Cleared on ADDCT3.
• Set whenever CT passes the result of the ADDCT3 (MSB of CT minus CT3 is 0).
• Also cleared on POLLCT3/WAITCT3/JCT3/JNCT3.

POLLPAT/WAITPAT event flag

• Cleared on SETPAT
• Set whenever (INA & D) != S after 'SETPAT D/#,S/#' with C=0 and Z=0.
• Set whenever (INA & D) == S after 'SETPAT D/#,S/#' with C=0 and Z=1.
• Set whenever (INB & D) != S after 'SETPAT D/#,S/#' with C=1 and Z=0.
• Set whenever (INB & D) == S after 'SETPAT D/#,S/#' with C=1 and Z=1.
• Also cleared on POLLPAT/WAITPAT/JPAT/JNPAT.

POLLFBW/WAITFBW event flag

• Cleared on RDFAST/WRFAST/FBLOCK.
• Set whenever the hub RAM FIFO interface exhausts its block count and reloads its 'block count' and 'start address'.
• Also cleared on POLLFBW/WAITFBW/JFBW/JNFBW.

POLLXMT/WAITXMT event flag

• Cleared on XINIT/XZERO/XCONT.
• Set whenever the streamer is ready for a new command.
• Also cleared on POLLXMT/WAITXMT/JXMT/JNXMT.

POLLXFI/WAITXFI event flag

• Cleared on XINIT/XZERO/XCONT.
• Set whenever the streamer runs out of commands.
• Also cleared on POLLXFI/WAITXFI/JXFI/JNXFI.

POLLXRO/WAITXRO event flag

• Cleared on XINIT/XZERO/XCONT.
• Set whenever the the streamer NCO rolls over.
• Also cleared on POLLXRO/WAITXRO/JXRO/JNXRO.

POLLXRL/WAITXRL event flag

• Cleared on cog start.
• Set whenever location $1FF of the lookup RAM is read by the streamer.
• Also cleared on POLLXRL/WAITXRL/JXRL/JNXRL.

POLLATN/WAITATN event flag

• Cleared on cog start.
• Set whenever any cogs request attention.
• Also cleared on POLLATN/WAITATN/JATN/JNATN.

POLLQMT event flag

• Cleared on cog start.
• Set whenever GETQX/GETQY executes without any CORDIC results available or in progress.
• Also cleared on POLLQMT/WAITQMT/JQMT/JNQMT.

Example:        ADDCT1/WAITCT1

'ADDCT1 D,S/#' must be used to establish a CT target. This is done by first using 'GETCT D' to get the current CT value into a register, and then using ADDCT1 to add into that register, thereby making a future CT target, which, when passed, will trigger the CT-passed-CT1 event and set the related event flag.

        GETCT   x               'get initial CT

        ADDCT1  x,#500          'make initial CT1 target

 .loop  WAITCT1                 'wait for CT to pass CT1 target

        ADDCT1  x,#500          'update CT1 target

        DRVNOT  #0              'toggle P0

        JMP     #.loop          'loop to the WAITCT1

It doesn't matter what register is used to keep track of the CT1 target. Whenever ADDCT1 executes, S/# is added into D, and the result gets copied into a dedicated CT1 target register that is compared to CT on every clock. When CT passes the CT1 target, the event flag is set. ADDCT1 clears the CT-passed-CT1 event flag to help with initialization and cycling.

Selectable Events

Each cog can track up to four selectable pin, LUT, or hub lock events.  This is accomplished by using the SETSEn instruction, where "n" is 1, 2, 3, or 4.  In order for user code to detect the occurrence of the selected event, the following options are available:

• The matched WAITSEn instruction will block until the event occurs
• The matched POLLSEn instruction will check for the event without blocking
• The matched JSEn and JNSEn branch instructions will branch according to the polled event state
• As an interrupt (see INTERRUPTS)

Each selected event is set or cleared according to the following rules:

• SEn is set whenever the configured event occurs.
• SEn is cleared on matched POLLSEn / WAITSEn / JSEn / JNSEn.
• SEn is cleared when matched  'SETSEn D/#' is called.

SETSEn D/# accepts the following configuration values:

%000_00_00AA = this cog reads LUT address %1111111AA

%000_00_01AA = this cog writes LUT address %1111111AA

%000_00_10AA = odd/even companion cog reads LUT address %1111111AA

%000_00_11AA = odd/even companion cog writes LUT address %1111111AA

%000_01_LLLL = hub lock %LLLL rises

%000_10_LLLL = hub lock %LLLL falls

%000_11_LLLL = hub lock %LLLL changes

%001_PPPPPP = INA/INB bit of pin %PPPPPP rises

%010_PPPPPP = INA/INB bit of pin %PPPPPP falls

%011_PPPPPP = INA/INB bit of pin %PPPPPP changes

%10x_PPPPPP = INA/INB bit of pin %PPPPPP is low

%11x_PPPPPP = INA/INB bit of pin %PPPPPP is high

INTERRUPTS

Each cog has three interrupts: INT1, INT2, and INT3.

INT1 has the highest priority and can interrupt INT2 and INT3.

INT2 has the middle priority and can interrupt INT3.

INT3 has the lowest priority and can only interrupt non-interrupt code.

The STALLI instruction can be used to hold off INT1, INT2 and INT3 interrupt branches indefinitely, while the ALLOWI instruction allows those interrupt branches to occur. Critical blocks of code can, therefore, be protected from interruption by beginning with STALLI and ending with ALLOWI.

There are 16 interrupt event sources, selected by a 4-bit pattern:

        0        <off>, default on cog start for INT1/INT2/INT3 event sources

        1        CT-passed-CT1, established by ADDCT1

        2        CT-passed-CT2, established by ADDCT2

        3        CT-passed-CT3, established by ADDCT3

        4        SE1 event occurred, established by SETSE1

        5        SE2 event occurred, established by SETSE2

        6        SE3 event occurred, established by SETSE3

        7        SE4 event occurred, established by SETSE4

        8        Pin pattern match or mismatch occurred, established by SETPAT

        9        Hub RAM FIFO interface wrapped and reloaded, established by RDFAST/WRFAST/FBLOCK

        10        Streamer is ready for another command, established by XINIT/XZERO/ZCONT

        11        Streamer ran out of commands, established by XINIT/XZERO/ZCONT

        12        Streamer NCO rolled over, established by XINIT/XZERO/XCONT

        13        Streamer read location $1FF of lookup RAM

        14        Attention requested by other cog(s)

        15        GETQX/GETQY executed without any CORDIC results available or in progress

To set up an interrupt, you need to first point its IJMP register to your interrupt service routine (ISR). When the interrupt occurs, it will jump to where the IJMP register points and simultaneously store the C/Z flags and return address into the adjacent IRET register:

$1F0                RAM / IJMP3                interrupt call   address for INT3

$1F1                RAM / IRET3                interrupt return address for INT3

$1F2                RAM / IJMP2                interrupt call   address for INT2

$1F3                RAM / IRET2                interrupt return address for INT2

$1F4                RAM / IJMP1                interrupt call   address for INT1

$1F5                RAM / IRET1                interrupt return address for INT1

When your ISR is done, it can do a RETIx instruction to return to the interrupted code. The RETIx instructions are actually CALLD instructions:

RETI1                           =       CALLD   INB,IRET1    WCZ

RETI2                           =       CALLD   INB,IRET2    WCZ

RETI3                           =       CALLD   INB,IRET3    WCZ

The CALLD with D = <any register>, S = IRETx, and WCZ, signals the cog that the interrupt is complete. This causes the cog to clear its internal interrupt-busy flag for that interrupt, so that another interrupt can occur. INB (read-only) is used as D for RETIx instructions to effectively make the CALLD into a JMP back to the interrupted code.

Instead of using RETIx, though, you could use RESIx to have your ISR resume at the next instruction when the next interrupt occurs:

RESI1                           =       CALLD   IJMP1,IRET1    WCZ

RESI2                           =       CALLD   IJMP2,IRET2    WCZ

RESI3                           =       CALLD   IJMP3,IRET3    WCZ

Once you've got the IJMPx register configured to point to your ISR, you can enable the interrupt. This is done using the SETINTx instruction:

        SETINT1 D/#        Set INT1 event to 0..15 (see table above)

        SETINT2 D/#        Set INT2 event to 0..15 (see table above)

        SETINT3 D/#        Set INT3 event to 0..15 (see table above)

Interrupts may be forced in software by the TRGINTx instructions:

        TRGINT1        Trigger INT1

        TRGINT2        Trigger INT2

        TRGINT3        Trigger INT3

Interrupts that have been triggered and are waiting to branch may be nixed in software by the NIXINTx instructions. These instructions are only useful in main code after STALLI executes or in an ISR which needs to stop a lower-level interrupt from executing after the current ISR exits:

        NIXINT1                Nix INT1

        NIXINT2                Nix INT2

        NIXINT3                Nix INT3

Interrupts can be stalled or allowed using the following instructions:

        ALLOWI                Allow any stalled and future interrupt branches to occur indefinitely (default mode on cog start)

        STALLI                Stall interrupt branches indefinitely until ALLOWI executes

When an interrupt event occurs, certain conditions must be met during execution before the interrupt branch can happen:

• ALTxx / CRCNIB / SCA / SCAS / GETCT+WC / GETXACC / SETQ / SETQ2 / XORO32 / XBYTE must not be executing
• AUGS must not be executing or waiting for a S/# instruction
• AUGD must not be executing or waiting for a D/# instruction
• REP must not be executing or active
• STALLI must not be executing or active
• The cog must not be stalled in any WAITx instruction

Once these conditions are all met, any pending interrupt is allowed to branch, with priority given to INT1, then INT2, and then INT3.

Interrupt branches are realized, internally, by inserting a 'CALLD IRETx,IJMPx WCZ' into the instruction pipeline while holding the program counter at its current value, so that the interrupt later returns to the address saved in IRETx.

Interrupts loop through these three states:

1. Waiting for interrupt event
2. Waiting for interrupt branch
3. Executing interrupt service routine

During states 2 and 3, any intervening interrupt events at the same priority level are ignored. When state 1 is returned to, a new interrupt event will be waited for.

Example:        Using INT1 as a CT1 interrupt

        org

start   mov     ijmp1,#isr1      'set int1 vector

        setint1 #1               'set int1 for ct-passed-ct1 event

        getct   ct1              'set initial ct1 target

        addct1  ct1,#50

                                 'main program, gets interrupted

loop    drvnot  #0               'toggle p0

        jmp     #loop            'loop

                                 'int1 isr, runs once every 50 clocks

isr1    drvnot  #1               'toggle p1

        addct1  ct1,#50          'update ct1 target

        reti1                            'return to main program

ct1     res                      'reserve long for ct1

DEBUG INTERRUPT

In addition to the three visible interrupts, there is a fourth "hidden" interrupt that has priority over all the others. It is the debug interrupt, and it is inaccessible to normal cog programs.

Debug interrupts are enabled on a per-cog basis via HUBSET. Each debug-enabled cog will generate a debug interrupt on (re)start from each COGINIT exercised upon it. Within that initial debug ISR and within each subsequent debug ISR, multiple trigger conditions may be set for the next debug interrupt. If no trigger conditions are set before the debug ISR ends, no more debug interrupts will occur until the cog is restarted from another COGINIT.

The last 16KB of hub RAM, which is also mapped to $FC000..$FFFFF, gets partially used as a buffer area for saving and restoring cog registers during debug ISR's. The initial debug ISR routines are also stored in this upper RAM. Once initialized with debug ISR code, this upper hub RAM can be write-protected, in which case it is mapped only to $FC000..$FFFFF and it is only writable from within debug ISR's.

Each cog has an execute-only ROM in cog registers $1F8..$1FF which contains special debug-ISR-entry and -exit routines. These tiny routines perform seamless register-load and register-restore operations for your debugger program, which must be realized entirely within debug ISR's.

During a debug ISR, INA and INB, normally read-only input-pin registers, become readable/writable RAM registers named IJMP0 and IRET0, and are used by the debug interrupt as jump and return addresses. On COGINIT, IJMP0 is initialized to $1F8 which is the debug-ISR-entry routine's address.

When a debug interrupt occurs with IJMP0 pointing to $1F8, the following sequence happens:

• Cog registers $000 to $00F are saved to hub RAM starting at ($FF800 + !CogNumber << 7), or %1111_1111_1ccc_c000_0000, where %cccc = !CogNumber.

• Cog registers $000 to $00F are loaded from hub RAM starting at ($FF840 + !CogNumber << 7), or %1111_1111_1ccc_c100_0000, where %cccc = !CogNumber.

• A "JMP #$000" executes to run the 16-instruction debugger program that was just loaded into registers $000 to $00F.

Your 16-instruction debugger program will likely want to determine if this debug interrupt was due to a COGINIT, in which case the debugger will probably want to note that a new program is now running in this cog. Depending on what the debugger must do next, it is likely that it will need to save more registers to the upper hub RAM and then load in more code from the upper hub RAM to facilitate more complex operations than the initial 16-instruction ISR can achieve. The ISR may then need to perform some communication between itself and a host system which may be serving as the debugger's user interface. It may be necessary to employ a LOCK to time-share P2-to-host communication channels among cogs, likely on P63 (serial Rx) and P62 (serial Tx). This scenario is somewhat hypothetical, but illustrates the design intent behind the debug interrupt mechanism.

When your debug ISR is complete, you can do a 'JMP #$1FD' to execute the debug-ISR-exit routine which does the following:

• Original cog registers $000 to $00F are restored from hub RAM starting at ($FF800 + !CogNumber << 7), or %1111_1111_1ccc_c000_0000, where %cccc = !CogNumber.

• A "RETI0" executes to return to the interrupted cog program.

Here is a table of the hub RAM locations used by each cog for register save/restore and ISR images during the debug interrupt when the register ROM routines are used for ISR entry and exit:

Though the first debug interrupt upon cog (re)start will always use the debug-ISR-entry routine at $1F8, you may redirect IJMP0 during any debug ISR to point elsewhere for use by subsequent debug interrupts. This would mean that you would lose the initial register-saving function provided by the small ROM starting at $1F8, so you would have to use some cog registers for debugger-state storage that don't interfere with the cog program that is being debugged. If no register saving/restoring or host communications are required, your debug ISR may execute very quickly.

What terminates a debug interrupt is not only RETI0 (CALLD INB,INB WCZ), but any D-register variant (CALLD anyreg,INB WCZ). For example RESI0 (CALLD INA,INB WCZ) may be used to resume next time from where this debug ISR left off, but this would imply that you are not using the debug-ISR-entry and -exit routines in the cog-register ROM and have, instead, permanently located debugger code into some cog registers, so that your debugger program is already present at the start of the debug interrupt.

This debug interrupt scheme was designed to operate stealthily, without any cooperation from the cog program being debugged. All control has been placed within the debug ISR. This isolation from normal programming is intended to prevent, or at least discourage, programmers from making any aspect of the debug interrupt system part of their application, thereby rendering the debug interrupt compromised as a standard debugging mechanism. Also, by executing the ISR strictly in cog register space, this scheme does not interfere with the hub FIFO state, which would be impossible to reconstruct if disturbed by hub execution within the debug ISR.

Below are the instructions which are used in the debugging mechanism:

BRK D/#

During normal program execution, the BRK instruction is used to generate a debug interrupt with an 8-bit code which can be read within the debug ISR. The BRK instruction interrupt must be enabled from within a prior debug ISR for this to work. Regardless of the execution condition, the BRK instruction will trigger a debug interrupt, if enabled. The execution condition only gates the writing of the 8-bit code:

  D/# = %BBBBBBBB: 8-bit BRK code

During a debug ISR, the BRK instruction operates differently and is used to establish the next debug interrupt condition(s). It is also used to select INA/INB, instead of the IJMP0/IRET0 registers exposed during the ISR, so that the pins' inputs states may be read:

  D/# = %aaaaaaaaaaaaaaaaeeee_LKJIHGFEDCBA

    %aaaaaaaaaaaaaaaaeeee: 20-bit breakpoint address or 4-bit event code (%eeee)

    %L: 1 = map INA/INB normally, 0 = map IJMP0/IRET0 at INA/INB (default during ISR) *

    %K: 1 = enable interrupt on breakpoint address match

    %J: 1 = enable interrupt on event %eeee

    %I: 1 = enable interrupt on asynchronous breakpoint (via COGBRK on another cog)

    %H: 1 = enable interrupt on INT3 ISR entry

    %G: 1 = enable interrupt on INT2 ISR entry

    %F: 1 = enable interrupt on INT1 ISR entry

    %E: 1 = enable interrupt on BRK instruction

    %D: 1 = enable interrupt on INT3 ISR code (single step)

    %C: 1 = enable interrupt on INT2 ISR code (single step)

    %B: 1 = enable interrupt on INT1 ISR code (single step)

    %A: 1 = enable interrupt on non-ISR code  (single step)

    * If set to 1 by the debug ISR, %L must be reset to 0 before exiting the debug ISR, so

      that the RETI0 instruction is able to see IJMP0 and IRET0.

On debug ISR entry, bits L to A are cleared to '0'. If a subsequent debug interrupt is desired, a BRK instruction must be executed before exiting the debug ISR, in order to establish the next breakpoint condition(s).

COGBRK D/#

The COGBRK instruction can trigger an asynchronous breakpoint in another cog. For this to work, the cog executing the COGBRK instruction must be in its own debug ISR and the other cog must have its asynchronous breakpoint interrupt enabled:

  D/# = %CCCC: the cog in which to trigger an asynchronous breakpoint

GETBRK D WCZ

During normal program execution, GETBRK with WCZ returns various data about the cog's internal status:

  C = 1 if STALLI mode or 0 if ALLOWI mode (established by STALLI/ALLOWI)

  Z = 1 if cog started in hubexec or 0 if cog started in cogexec

  D[31:23] = 0

  D[22] = 1 if colorspace converter is active

  D[21] = 1 if streamer is active

  D[20] = 1 if WRFAST mode or 0 if RDFAST mode

  D[19:16] = INT3 selector, established by SETINT3

  D[15:12] = INT2 selector, established by SETINT2

  D[11:08] = INT1 selector, established by SETINT1

  D[07:06] = INT3 state: %0x = idle, %10 = interrupt pending, %11 = ISR executing

  D[05:04] = INT2 state: %0x = idle, %10 = interrupt pending, %11 = ISR executing

  D[03:02] = INT1 state: %0x = idle, %10 = interrupt pending, %11 = ISR executing

  D[01] = 1 if STALLI mode or 0 if ALLOWI mode (established by STALLI/ALLOWI)

  D[00] = 1 if cog started in hubexec or 0 if cog started in cogexec

During a debug ISR, GETBRK with WCZ returns additional data that is useful to a debugger:

  C = 1 if debug interrupt was from a COGINIT, indicating that the cog was (re)started

  D[31:24] = 8-bit break code from the last 'BRK #/D' during normal execution

  D[23] = 1 if debug interrupt was from a COGINIT, indicating that the cog was (re)started

GETBRK D WC

GETBRK with WC always returns the following:

  C = LSB of SKIP/SKIPF/EXECF/XBYTE pattern

  D[31:28] = 4-bit CALL depth since SKIP/SKIPF/EXECF/XBYTE (skipping suspended if not %0000)

  D[27] = 1 if SKIP mode or 0 if SKIPF/EXECF/XBYTE mode

  D[26] = 1 if LUT sharing enabled (established by SETLUTS)

  D[25] = 1 if top of stack = $001FF, indicating XBYTE will execute on next _RET_/RET

  D[24:16] = 9-bit XBYTE mode, established by '_RET_ SETQ/SETQ2' when top of stack = $001FF

  D[15:00] = 16 event-trap flags

     D[15] = GETQX/GETQY executed without prior CORDIC command

     D[14] = attention requested by cog(s)

     D[13] = streamer read location $1FF of lookup RAM

     D[12] = streamer NCO rolled over

     D[11] = streamer finished, now idle

     D[10] = streamer ready to accept new command

     D[09] = hub RAM FIFO interface loaded block count and start address

     D[08] = pin pattern match occurred

     D[07] = SE4 event occurred

     D[06] = SE3 event occurred

     D[05] = SE2 event occurred

     D[04] = SE1 event occurred

     D[03] = CT-passed-CT1

     D[02] = CT-passed-CT2

     D[01] = CT-passed-CT3

     D[00] = INT1, INT2, or INT3 occurred

GETBRK D WZ

GETBRK with WZ always returns the following:

  Z = 1 if no SKIP/SKIPF/EXECF/XBYTE pattern queued (D = 0) or 1 if pattern queued (D <> 0)

  D = 32-bit SKIP/SKIPF/EXECF/XBYTE pattern, used LSB-first to skip instructions in main code

HUB

Configuration

The hub contains several global circuits which are configured using the HUBSET instruction. HUBSET uses a single D operand to both select the circuit to be configured and to provide the configuration data:

        HUBSET  {#}D     - Configure global circuit selected by MSBs

        %0000_xxxE_DDDD_DDMM_MMMM_MMMM_PPPP_CCSS     Set clock generator mode

        %0001_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx     Hard reset, reboots chip

        %0010_xxxx_xxxx_xxLW_DDDD_DDDD_DDDD_DDDD     Set write-protect and debug enables

        %0100_xxxx_xxxx_xxxx_xxxx_xxxR_RLLT_TTTT     Set filter R to length L and tap T

        %1DDD_DDDD_DDDD_DDDD_DDDD_DDDD_DDDD_DDDD     Seed Xoroshiro128** PRNG with D

Configuring the Clock Generator

The Prop2 can generate its system clock in several different ways.

There are two separate internal RC clock oscillators that can be used, a 20MHz+ (RCFAST) and a ~20kHz (RCSLOW). The 20MHz+ oscillator is designed to always run at least 20MHz, worst-case, in order to accommodate 2M baud serial loading during boot. The ~20kHz oscillator is intended for low-power operation.

The XI and XO pins can also be used for clocking, with XI being an input and XO being a crystal-feedback output for 10MHz-20MHz crystals. Internal loading caps can also be enabled on XI and XO for crystal impedance matching.

If the XI pin is used as a clock input or crystal oscillator input, its frequency can be modified through an internal phase-locked loop (PLL). The PLL divides the XI pin frequency from 1 to 64, then multiplies the resulting frequency from 1 to 1024 in the VCO. The VCO frequency can be used directly, or divided by 2, 4, 6, ...30, to get the final PLL clock frequency which can be used as the system clock.

The clock configuration setting consists of 25 bits. The four LSBs are all that are needed to switch among clock sources and select all but the PLL settings.

        HUBSET  ##%0000_000E_DDDD_DDMM_MMMM_MMMM_PPPP_CCSS     'set clock mode

The tables below explain the various bit fields within the HUBSET operand:

WARNING: Incorrectly switching away from the PLL setting (%SS = %11 and %CC <> %00) with %PPPP = %1111 can cause a clock glitch which will hang the P2 chip until a reset occurs.  In order to safely switch away, always start by switching to an internal RC oscillator (%SS = %00 or %01), while maintaining the %PPPP = %1111 and %CC settings.

PLL Example

The PLL's VCO is designed to run between 100 MHz and 200 MHz and should be kept within that range.

Let's say you have a 20 MHz crystal attached to XI and XO and you want to run the Prop2 at 148.5 MHz. You could divide the crystal by 40 (%DDDDDD = 39) to get a 500 kHz reference, then multiply that by 297 (%MMMMMMMMMM = 296) in the VCO to get 148.5 MHz. You would set %PPPP to %1111 to use the VCO output directly. The configuration value would be %1_100111_0100101000_1111_10_11. The last two 2-bit fields select 15pf crystal mode and the PLL. In order to realize this clock setting, though, it must be done over a few steps:

        HUBSET  #$F0                                'set 20 MHz+ (RCFAST) mode

        HUBSET  ##%1_100111_0100101000_1111_10_00   'enable crystal+PLL, stay in RCFAST mode

        WAITX   ##20_000_000/100                    'wait ~10ms for crystal+PLL to stabilize

        HUBSET  ##%1_100111_0100101000_1111_10_11   'now switch to PLL running at 148.5 MHz

The clock selector controlled by the %SS bits has a deglitching circuit which waits for a positive edge on the old clock source before disengaging, holding its output high, and then waiting for a positive edge on the new clock source before switching over to it. It is necessary to select mode %00 or %01 while waiting for the crystal and/or PLL to settle into operation, before switching over to either.

Write-Protecting the Last 16KB of Hub RAM and Enabling Debug Interrupts

        HUBSET  {#}D                    'set write-protect and enable debug interrupts

    {#}D = %0010_xxxx_xxxx_xxLW_DDDD_DDDD_DDDD_DDDD

    %L:  Lock W and D bit settings until next reset

             0 = establish W and D bit settings and allow subsequent modification

             1 = establish W and D bit settings and disallow subsequent modification

    %W:  Write-protect last 16KB of hub RAM

             0 = Last 16KB of hub RAM can be read and written at both its normal range

                 and at $FC000..$FFFFF (default)

             1 = Last 16KB of hub RAM disappears from its normal range and is write-

                 protected at $FC000..$FFFFF, except from within debug ISR's

    %D:  Debug interrupt enables for cogs 15..0, respectively

             0 = Debug interrupt is disabled for cog n (default)

             1 = Debug interrupt is enabled for cog n

Examples:

        HUBSET  ##$2000_0001    'enable debug interrupt for cog 0

        HUBSET  ##$2001_FFFF    'enable debug interrupts for cogs 15..0

                                '..and write-protect the last 16KB of hub RAM

        HUBSET  ##$2003_00FF    'enable debug interrupts for cogs 7..0

                                '..and write-protect the last 16KB of hub RAM

                                '..and disallow subsequent changes to this scheme

See the DEBUG INTERRUPT section to learn how debug interrupts work.

Configuring the Digital Filters for Smart Pins

There are four global digital filter settings which can be used by each smart pin to low-pass filter its incoming pin states.

Each filter setting includes a filter length and a timing tap. The filter length is 2, 3, 5, or 8 flipflops, selected by values 0..3. The flipflops shift pin state data at the timing tap rate and must be unanimously high or low to change the filter output to high or low. The timing tap is one of the lower 32 bits of CT (the free-running 64-bit global counter), selected by values 0..31. Each time the selected tap transitions, the current pin state is shifted into the flipflops and if the flipflops are all in agreement, the filter output goes to that state. The filter will be reflected in the INA/INB bits if no smart pin mode is selected, or the filter states will be used by the smart pin mode as its inputs.

The D operand selects both the filter to configure and the data to configure it with:

        HUBSET  ##$4000_0000 + Length<<5 + Tap      'set filt0

        HUBSET  ##$4000_0080 + Length<<5 + Tap      'set filt1

        HUBSET  ##$4000_0100 + Length<<5 + Tap      'set filt2

        HUBSET  ##$4000_0180 + Length<<5 + Tap      'set filt3

"Length" is 0..3 for 2, 3, 5, or 8 flipflops.

"Tap" is 0..31 for every single clock, every 2nd clock, every 4th clock,... every 2,147,483,648th clock.

The filters are set to the following defaults on reset:

Seeding the Xoroshiro128** PRNG

To seed 32 bits of state data into the 128-bit PRNG, use HUBSET with the MSB of D set. This will write {1'b1, D[30:0]} into 32 bits of the PRNG, affecting 1/4th of its total state. The 1'b1 bit ensures that the overall state will not go to zero. Because the PRNG's 128 state bits rotate, shift, and XOR against each other, they are thoroughly spread around within a few clocks, so seeding from a fixed set of 32 bits should not pose a limitation on seeding quality.

After reset, the boot ROM uses HUBSET to seed the Xoroshiro128** PRNG fifty times, each time with 31 bits of thermal noise gleaned from pin 63 while in ADC calibration mode. This establishes a very random seed which the PRNG iterates from, thereafter. There is no need to do this again, but here is how you would do it if 'x' contained a seed value:

        SETB    x,#31   'set the MSB of x to make a PRNG seed command

        HUBSET  x       'seed 32 bits of the Xoroshiro128** state

The Xoroshiro128** PRNG iterates on every clock, generating 64 fresh bits which get spread among all cogs and smart pins. Each cog receives a unique set of 32 different bits, in a scrambled arrangement with some bits inverted, from the 64-bit pool. Each smart pin receives a similarly-unique set of 8 different bits. Cogs can sample these bits using the GETRND instruction and directly apply them using the BITRND and DRVRND instructions. Smart pins utilize their 8 bits as noise sources for DAC dithering and noise output.

Rebooting the Chip

HUBSET can be used to reset and reboot the chip:

        HUBSET  ##$1000_0000    'generate an internal reset pulse to reboot

HUB RAM

The globally-accessible hub RAM can be read and written as bytes, words, and longs, in little-endian format. Hub addresses are always byte-oriented. There are no special alignment rules for words and longs in hub RAM. Cogs can read and write bytes, words, and longs at any hub address, as well as execute instruction longs from any hub address starting at $400  (see COGS > INSTRUCTION MODES > HUB EXECUTION).

On hub RAM implementations of less than the full 1MB, the last 16KB of hub RAM is normally addressable at both its normal address range, as well as at $FC000..$FFFFF. This provides a stable address space for the 16KB of internal ROM which gets cached into the last 16KB of hub RAM on startup. This upper 16KB mapping is also used by the cog debugging scheme.

The last 16KB of RAM can be hidden from its normal address range and made read-only at $FC000..$FFFFF. This is useful for making the last 16KB of RAM persistent, like ROM. It is also how debugging is realized, as the RAM mapped to $FC000..$FFFFF can still be written to from within debug interrupt service routines, permitting the otherwise-protected RAM to be used as debugger-application space and cog-register swap buffers for debug interrupts.

See the HUBSET instruction definition for setting up write-protection.

Here are the hub memory maps for the various FPGA boards currently being supported during development. The "W" column represents write-protection status, set by HUBSET, for the last 16KB of hub RAM:

THE COG -to- HUB RAM INTERFACE

Hub RAM is comprised of 32-bit-wide single-port RAMs with byte-level write controls. For each cog, there is one of these RAMs, but it is multiplexed among all cogs. Let's call these separate RAMs "slices". Each RAM slice holds every single/2nd/4th/8th/16th (depending on number of cogs) set of 4 bytes in the composite hub RAM. At every clock, each cog can access the "next" RAM slice, allowing for continuously-ascending bidirectional streaming of 32 bits per clock between the composite hub RAM and each cog.

When a cog wants to read or write the hub RAM, it must wait up to #cogs-1 clocks to access the initial RAM slice of interest. Once that occurs, subsequent slices can be accessed on every clock, thereafter, for continuous reading or writing of 32-bit longs.

To smooth out data flow for less than 32-bits-per-clock between hub RAM and the cog, each cog has a hub FIFO interface which can be set for hub-RAM-read or hub-RAM-write operation. This FIFO interface allows hub RAM to be either sequentially read or sequentially written in any combination of bytes, words, or longs, at any rate, up to one long per clock. No matter the transfer frequency or the word size, the FIFO will ensure that the cog's reads or writes are all properly conducted from or to the composite hub RAM.

Cogs can access hub RAM either via the sequential FIFO interface, or by waiting for RAM slices of interest, while yielding to the FIFO. If the FIFO is not busy, which is soon the case if data is not being read from or written to it, random accesses will have full opportunity to access the composite hub RAM.

There are three ways the hub FIFO interface can be used, and it can only be used for one of these at a time:

• Hub execution (when the PC is $00400..$FFFFF)
• Streamer usage (background transfers from hub RAM → pins/DACs, or from pins/ADCs → hub RAM)
• Software usage (fast sequential-reading or sequential-writing instructions)