Explanation

The ORG (origin) directive sets the Propeller Tool's assembly pointer to a new value for use in address references within the assembly code to follow. ORG typically appears as ORG 0, or just ORG, at the start of any new assembly code intended to be launched into a separate cog.

ORG only affects symbol references; it does not affect the position of assembly code in the cog itself. When assembly code is launched via a COGNEW or COGINIT command, the destination cog always loads the code into its RAM starting at address 0.

Even though assembly code is always loaded in this way, the compiler/assembler does not know which part of the code constitutes its beginning since developers are free to launch any code starting from any address.

To solve this, the assembler uses a reference point (the assembly pointer value) to calculate the absolute address of referenced symbols. Those absolute addresses are encoded into the assembly instruction's destination (d-field) or source (s-field) in place of the symbolic reference. For example:

DAT
           org     0             'Start at Cog RAM 0
Toggle     mov     dira, Pin     'Set I/O direction to output
:Loop      xor     outa, Pin     'Toggle output pin state
           jmp     #:Loop        'Loop endlessly 

Pin        long    $0000_0010    'Use I/O pin 4 ($10 or %1_0000)

The ORG statement in this example sets the assembly pointer to zero (0) so the code following it is assembled with that reference point in mind. Because of this, to the assembler the Toggle symbol is logically at Cog RAM location 0, the :Loop symbol is at Cog RAM location 1, and the Pin symbol is at Cog RAM location 3. The assembler will replace each reference to these symbols with their respective hard-coded location.

When the Toggle code is launched with COGNEW(@Toggle, 0), for example, the code will properly execute starting with Cog RAM address 0 since all symbol addresses were calculated from that point. If the ORG statement had been ORG 1 and the Toggle code was launched, it would not execute properly because the symbol addresses were calculated from the wrong reference (1 instead of 0).

A Propeller object may contain multiple instances of the ORG directive, each placed immediately before a launchable portion of assembly code. However, it is not common to use ORG with values other than zero (0) though that may be handy when creating run-time swappable portions of assembly code.