The Structure of Propeller Assembly

Every Propeller Object consists of Spin code plus optional assembly code and data. An object's Spin code provides it with structure, consisting of special-purpose blocks. Data and Propeller Assembly code are located in the DAT block; see DAT.

Spin code is executed from Main RAM by a cog running the Spin Interpreter, however, Propeller Assembly code is executed directly from within a cog itself. Because of this nature, Propeller Assembly code and any data belonging to it must be loaded (in its entirety) into a cog in order to execute it. In this way, both assembly code and data are treated the same during the cog loading process.

Here's an example Propeller object. Its Spin code in the PUB block, Main, launches another cog to run the DAT block's Propeller Assembly routine, Toggle.

{{ AssemblyToggle.spin }} 

CON
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000 
 
PUB Main
{Launch cog to toggle P16 endlessly} 

  cognew(@Toggle, 0)                 'Launch new cog 
 
DAT
{Toggle P16}
             org     0               'Begin at Cog RAM addr 0
Toggle       mov     dira, Pin       'Set Pin to output
             mov     Time, cnt       'Calculate delay time
             add     Time, #9        'Set minimum delay here
:loop        waitcnt Time, Delay     'Wait
             xor     outa, Pin       'Toggle Pin
             jmp     #:loop          'Loop endlessly 

Pin    long  |< 16                   'Pin number
Delay  long  6_000_000               'Clock cycles to delay
Time         res 1                   'System Counter Workspace 

When the Main method's COGNEW command is executed, a new cog begins filling its Cog RAM with 496 consecutive longs from Main Memory, starting with the instruction at the address of Toggle. Afterwards, the new cog initializes its special purpose registers and begins executing the code starting at Cog RAM register 0.

Both assembly and data may be intermixed within this DAT block but care should be taken to arrange it such that all critical elements are loaded into the cog in the proper order for execution. It is recommended to write it in the following order: 1) assembly code, 2) initialized symbolic data (i.e.: LONGs), 3) reserved symbolic memory (i.e.: RESs). This causes the cog to load up the assembly code first, followed immediately by initialized data, and any application data after that, whether or not it is required by the code. See the sections discussing ORG, RES, and DAT for more information.