Instruction: Start or restart a cog, optionally by ID, to run Propeller Assembly or Spin code.

COGINIT Destination

Result: Optionally, the started/restarted cog's ID (0-7) is written to Destination.

Destination (d-field) is the register containing startup information for the target cog and optionally becomes the destination of the started cog's ID if a new cog is started.

Opcode Table:

–INSTR– ZCRI –CON– –DEST– –SRC–	Z Result	C Result	Result	Clocks
000011 0001 1111 ddddddddd ------010	ID = 0	No Cog Free	Not Written	8..23

Concise Truth Table:

In					Out
Destination¹	Source²	Z	C	Effects	Destination³	Z	C
$0000_0000; 0	%0_00000010; 2	-	-	wr wz wc	$0000_0000; 04	1	0
$0000_0001; 1	%0_00000010; 2	-	-	wr wz wc	$0000_0001; 14	0	0
$0000_0008; 8	%0_00000010; 2	-	-	wr wz wc	$0000_0000; 05	1	0
$0000_0008; 8	%0_00000010; 2	-	-	wr wz wc	$1; 1 .. $7; 75	0	0
$0000_0008; 8	%0_00000010; 2	-	-	wr wz wc	$0000_0007; 75	0	1

¹ Destination In must be a PAR value (bits 31:18), an assembly code address (bits 17:4), and a new cog / cog ID indicator (bits 3:0).
² Source is automatically set to immediate value 2 by the assembler to indicate that this is the COGINIT hub instruction.
³ Destination is not written unless the WR effect is given.
⁴ When Destination In indicates to start a specific cog, Destination Out (written Destination) indicates that cog's ID; it is always started or restarted.
⁵ When Destination In indicates to start a new (next available) cog, Destination Out (written Destination) indicates the ID of the cog that was started, or 7 (with C set) if no cog available.

Explanation

The COGINIT instruction behaves similar to two Spin commands, COGNEW and COGINIT, put together. Propeller Assembly's COGINIT instruction can be used to start a new cog or restart an active cog. The Destination register has four fields that determine which cog is started, where its program begins in main memory, and what its PAR register will contain. The table below describes these fields.

Destination Register Fields
31:18	17:4	3	2:0
14-bit Long address for PAR Register	14-bit Long address of code to load	New	Cog ID

The first field, bits 31:18, will be written to the started cog's PAR register bits 15:2. This is 14 bits total that are intended to be the upper bits of a 16-bit long address. Similar to the Parameter field of Spin's version of COGINIT, this first field of Destination is used to pass the 14-bit address of an agreed-upon memory location or structure to the started cog.

The second field, bits 17:4, holds the upper 14-bits of a 16-bit long address pointing to the desired assembly program to load into the cog. Cog registers $000 through $1EF will be loaded sequentially starting at this address, the special purpose registers will be cleared to zero (0), and the cog will start executing the code at register $000.

The third field, bit 3, should be set (1) if a new cog should be started, or cleared (0) if a specific cog should be started or restarted.

If the third field bit is set (1), the Hub will start the next available (lowest-numbered inactive) cog and return that cog's ID in Destination (if the WR effect is specified).

If the third field bit is clear (0), the Hub will start or restart the cog identified by Destination's fourth field, bits 2:0.

If the WZ effect is specified, the Z flag will be set (1) if the cog ID returned is 0. If the WC effect is specified, the C flag will be set (1) if no cog was available. If the WR effect is specified, Destination is written with the ID of the cog that the Hub started, or would have started, if you let it pick one.

It is not practical to launch Spin code from a user's Propeller Assembly code; we recommend launching only assembly code with this instruction.

COGINIT is a hub instruction. Hub instructions require 8 to 23 clock cycles to execute depending on the relation between the cog's hub access window and the instruction's moment of execution. See Hub for more information.