COGNEW

Owned by Brett Weir
Last updated: Oct 10, 2014 by DK Nguyen
2 min read

Command: Start the next available cog to run Spin code or Propeller Assembly code.

((PUB ┆ PRI))
  COGNEW (SpinMethod < (ParameterList) >, StackPointer )

((PUB ┆ PRI))
  COGNEW (AsmAddress, Parameter )

Returns: The ID of the newly started cog (0-7) if successful, or -1 otherwise.

  • SpinMethod is the PUB or PRI Spin method that the new cog should run. Optionally, it can be followed by a parameter list enclosed in parentheses.
  • ParameterList is an optional, comma-delimited list of one or more parameters for SpinMethod. It must be included only if SpinMethod requires parameters.
  • StackPointer is a pointer to memory, such as a long array, reserved for stack space for the new cog. The new cog uses this space to store temporary data during further calls and expression evaluations. If insufficient space is allocated, either the application will fail to run or it will run with strange results.
  • AsmAddress is the address of a Propeller Assembly routine, usually from a DAT block.
  • Parameter is used to optionally pass a value to the new cog. This value ends up in the new cog's read-only Cog Boot Parameter (PAR) register. Parameter can be used to pass a either a single 14-bit value or the address of a block of memory to be used by the assembly routine. Parameter is required by COGNEW, but if not needed for your routine, simply set it to an innocuous value like zero (0).

Explanation

COGNEW starts a new cog and runs either a Spin method or a Propeller Assembly routine within it. For Spin methods, the new cog's RAM is loaded with the Spin Interpreter from the Main ROM, which then fetches and executes the Spin code tokens from the application image in Main RAM. For Propeller Assembly, the targeted assembly code itself is loaded from the application image in Main RAM into the cog's RAM for execution.

If the launch is successful, COGNEW returns the ID of the newly started cog. If there were no more cogs available, COGNEW returns -1. COGNEW works exactly like COGINIT with two exceptions:

  1. It launches code into the next available cog
  2. It returns the ID of the cog that it started, if any.

Unless otherwise noted, content on this site is licensed under the
Creative Commons Attribution-ShareAlike 4.0 International License.