Propeller Manual Version 1.
WARRANTY Parallax Inc. warrants its products against defects in materials and workmanship for a period of 90 days from receipt of product. If you discover a defect, Parallax Inc. will, at its option, repair or replace the merchandise, or refund the purchase price. Before returning the product to Parallax, call for a Return Merchandise Authorization (RMA) number. Write the RMA number on the outside of the box used to return the merchandise to Parallax.
DISCLAIMER OF LIABILITY Parallax Inc. is not responsible for special, incidental, or consequential damages resulting from any breach of warranty, or under any legal theory, including lost profits, downtime, goodwill, damage to or replacement of equipment or property, or any costs of recovering, reprogramming, or reproducing any data stored in or used with Parallax products. Parallax Inc.
Table of Contents PREFACE ............................................................................................................................... 11 CHAPTER 1 : INTRODUCING THE PROPELLER CHIP....................................................... 13 CONCEPT ............................................................................................................................. 13 PACKAGE TYPES .......................................................................................................
Table of Contents Syntax Symbols ..............................................................................................................44 SPIN LANGUAGE ELEMENTS ...................................................................................................45 Symbol Rules ..................................................................................................................45 Value Representations..........................................................................................
Table of Contents NEXT................................................................................................................................... 140 OBJ..................................................................................................................................... 141 OPERATORS ....................................................................................................................... 143 OUTA, OUTB ....................................................................
Table of Contents Cog Control ...................................................................................................................243 Process Control ............................................................................................................243 Conditions .....................................................................................................................243 Flow Control ..........................................................................................
Table of Contents HUBOP ................................................................................................................................. 294 IF_X (CONDITIONS)............................................................................................................. 295 INA, INB ............................................................................................................................ 297 JMP..................................................................................
Table of Contents ROL .....................................................................................................................................344 ROR .....................................................................................................................................345 SAR .....................................................................................................................................346 SHL ...................................................................
Preface Preface Thank you for purchasing a Propeller chip. You will be spinning your own programs in no time! Propeller chips are incredibly capable multiprocessor microcontrollers; the much-anticipated result of over eight years of the intense efforts of Chip Gracey and the entire Parallax Engineering Team. This book is intended to be a reference guide to Propeller chips and their native programming languages, Spin and Propeller Assembly.
Preface Additional important changes include: • An additional Propeller Assembly instruction was added; TESTN (see page 347) • The following sections were rewritten for clarity: o o o o o o o o o o o • ADDSX on page 262 ADDX on page 264 CALL on page 268 CMPSX on page 277 CMPX on page 280 JMPRET on page 300 ORG on page 328 RES on page 339 RET on page 342 SUBSX on page 352 SUBX on page 354 Extensive enhancements to the following sections were made to provide detail on previously undocumented features: o
1: Introducing the Propeller Chip Chapter 1: Introducing the Propeller Chip This chapter describes the Propeller chip hardware. To fully understand and use the Propeller effectively, it’s important to first understand its hardware architecture. This chapter presents the details of the hardware such as package types, package sizes, pin descriptions, and functions.
Introducing the Propeller Chip Package Types The Propeller chip is available in the package types shown here. P8X32A-D40 P8X32A-Q44 44-pin LQFP 40-pin DIP P8X32A-M44 44-pin QFN Page 14 · Propeller Manual v1.
1: Introducing the Propeller Chip Pin Descriptions Table 1-1: Pin Descriptions Pin Name Direction Description General purpose I/O Port A. Can source/sink 40 mA each at 3.3 VDC. Logic threshold is ≈ ½ VDD; 1.65 VDC @ 3.3 VDC. The pins shown below have a special purpose upon power-up/reset but are general purpose I/O afterwards. P28 - I2C SCL connection to optional, external EEPROM. P29 - I2C SDA connection to optional, external EEPROM. P30 - Serial Tx to host. P31 - Serial Rx from host.
Introducing the Propeller Chip Specifications Table 1-2: Specifications Model P8X32A Power Requirements 3.3 volts DC. (Max current draw must be limited to 300 mA).
1: Introducing the Propeller Chip Hardware Connections Figure 1-1 shows an example wiring diagram that provides host and EEPROM access to the Propeller chip. In this example the host access is achieved through the Propeller Plug device (a USB to TTL serial converter). Figure 1-1: Example wiring diagram that allows for programming the Propeller chip and an external 32 Kbyte EEPROM, and running the Propeller with an external crystal. Propeller Manual v1.
Introducing the Propeller Chip Boot Up Procedure Upon power-up (+ 100 ms), RESn low-to-high, or software reset: 1. The Propeller chip starts its internal clock in slow mode (≈ 20 kHz), delays for 50 ms (reset delay), switches the internal clock to fast mode (≈ 12 MHz), and then loads and runs the built-in Boot Loader program in the first processor (Cog 0). 2. The Boot Loader performs one or more of the following tasks, in order: a. Detects communication from a host, such as a PC, on pins P30 and P31.
1: Introducing the Propeller Chip many cogs are running at any given time. All of this is variable at run time, as controlled by the application, including the internal clock speed. Shutdown Procedure When the Propeller goes into shutdown mode, the internal clock is stopped causing all cogs to halt and all I/O pins are set to input direction (high impedance). Shutdown mode is triggered by one of the three following events: 1) VDD falling below the brown-out threshold (≈2.
Introducing the Propeller Chip Block Diagram Figure 1-2: Propeller Chip Block Diagram Page 20 · Propeller Manual v1.
1: Introducing the Propeller Chip Cog and Hub interaction is critical to the Propeller chip. The Hub controls which cog can access mutually exclusive resources, such as Main RAM/ROM, configuration registers, etc. The Hub gives exclusive access to every cog one at a time in a “round robin” fashion, regardless of how many cogs are running, in order to keep timing deterministic. Propeller Manual v1.
Introducing the Propeller Chip Shared Resources There are two types of shared resources in the Propeller: 1) common, and 2) mutually exclusive. Common resources can be accessed at any time by any number of cogs. Mutually exclusive resources can also be accessed by all cogs, but only by one cog at a time. The common resources are the I/O pins and the System Counter. All other shared resources are mutually exclusive by nature and access to them is controlled by the Hub. See the Hub section on page 24.
1: Introducing the Propeller Chip Each cog has its own RAM, called Cog RAM, which contains 512 registers of 32 bits each. The Cog RAM is all general purpose RAM except for the last 16 registers, which are special purpose registers, as described in Table 1-3. The Cog RAM is used for executable code, data, variables, and the last 16 locations serve as interfaces to the System Counter, I/O pins, and local cog peripherals.
Introducing the Propeller Chip Each Special Purpose Register may be accessed via: 1) its physical register address (Propeller Assembly), 2) its predefined name (Spin or Propeller Assembly), or 3) the register array variable (SPR) with an index of 0 to 15 (Spin).
1: Introducing the Propeller Chip Figure 1-3: Cog-Hub Interaction – Best Case Scenario Figure 1-4 shows the worst-case scenario; the hub instruction was ready on the cycle right after the start of Cog 0’s access window; it just barely missed it. The cog waits until the next hub access window (15 cycles later) then the hub instruction executes (7 cycles) for a total of 22 cycles for that hub instruction.
Introducing the Propeller Chip I/O Pins The Propeller has 32 I/O pins, 28 of which are entirely general purpose. Four I/O pins (28 31) have a special purpose at Boot Up and are available for general purpose use afterwards; see the Boot Up Procedure section on page 18. After boot up, any I/O pins can be used by any cogs at any time since I/O pins are one of the common resources.
1: Introducing the Propeller Chip Table 1-4: I/O Sharing Examples Bit 12 of Cogs’ I/O Direction Register Bit 12 of Cogs’ I/O Output Register State of I/O Pin P12 Rule Followed Cog ID 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 Example 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Input A Example 2 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Output Low B Example 3 1 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 Output High C Example 4 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 Output Low B Example 5 1 1 0 0 0 0 0 0 0 1 0 0 0 0 0 0 Output Hi
Introducing the Propeller Chip CLK Register The CLK register is the System Clock configuration control; it determines the source of and the characteristics for the System Clock. More precisely, the CLK register configures the RC Oscillator, Clock PLL, Crystal Oscillator, and Clock Selector circuits. (See Figure 1-2: Propeller Chip Block Diagram on page 20.
1: Introducing the Propeller Chip Table 1-7: CLK Register PLLENA (Bit 6) Bit Effect 0 Disables the PLL circuit. The RCFAST and RCSLOW settings of the _CLKMODE declaration configure PLLENA this way. 1 Enables the PLL circuit. Each of the PLLxx settings of the _CLKMODE declaration configures PLLENA this way at compile time. The Clock PLL internally multiplies the XIN pin frequency by 16. OSCENA must also be ‘1’ to propagate the XIN signal to the Clock PLL.
Introducing the Propeller Chip Table 1-10: CLK Register CLKSELx (Bits 2:0) CLKSELx _CLKMODE Setting Master Clock Source Notes 2 1 0 0 0 0 RCFAST ~12 MHz Internal No external parts. May range from 8 MHz to 20 MHz. 0 0 1 RCSLOW ~20 kHz Internal Very low power. No external parts. May range from 13 kHz to 33 kHz. 0 1 0 XINPUT XIN OSC 0 1 1 XTALx and PLL1X XIN x 1 OSC+PLL OSCENA and PLLENA must be '1'. 1 0 0 XTALx and PLL2X XIN x 2 OSC+PLL OSCENA and PLLENA must be '1'.
1: Introducing the Propeller Chip ROM. The 32 KB of Main RAM is general purpose and is the destination of a Propeller Application either downloaded from a host or uploaded from the external 32 KB EEPROM. The 32 KB of Main ROM contains all the code and data resources vital to the Propeller chip’s function: character definitions, log, anti-log and sine tables, and the Boot Loader and Spin Interpreter. The Main Memory organization is shown in Figure 1-5.
Introducing the Propeller Chip Main ROM The second half of Main Memory is all ROM. This space is used for character definitions, math functions, and the Boot Loader and Spin Interpreter. Character Definitions The first half of ROM is dedicated to a set of 256 character definitions. Each character definition is 16 pixels wide by 32 pixels tall. These character definitions can be used for video displays, graphical LCD's, printing, etc.
1: Introducing the Propeller Chip The character pairs are merged row-by-row such that each character's 16 horizontal pixels are spaced apart and interleaved with their neighbors' so that the even character takes bits 0, 2, 4, ...30, and the odd character takes bits 1, 3, 5, ...31. The leftmost pixels are in the lowest bits, while the rightmost pixels are in the highest bits, as shown in Figure 1-7. This forms a long (4 bytes) for each row of pixels in the character pair.
Introducing the Propeller Chip can include schematics, timing diagrams and other diagrams right in the source code for your application. Log and Anti-Log Tables The log and anti-log tables are useful for converting values between their number form and exponent form. When numbers are encoded into exponent form, simple math operations take on more complex effects. For example ‘add’ and ‘subtract’ become ‘multiply’ and ‘divide.’ ‘Shift left’ becomes ‘square’ and ‘shift right’ becomes 'square-root.
2: Spin Language Reference Chapter 2: Spin Language Reference This chapter describes all elements of the Propeller chip’s Spin language and is best used as a reference for individual elements of the Spin language. For a tutorial on the use of the language refer to the Spin Language Tutorial in the Propeller Tool’s on-line help, then return here for more details. The Spin Language Reference is divided into three sections: 1) The Structure of the Propeller Objects.
Spin Language Reference Structure of Propeller Objects/Spin Each Propeller object is a Spin file that has an inherent structure consisting of up to six different special-purpose blocks: CON, VAR, OBJ, PUB, PRI, and DAT. These blocks are shown below (in the order that they typically appear in objects) along with the set of elements usable within each. For detailed examples of the object (Spin) structure and usage, refer to the Propeller Programming Tutorial in the Propeller Tool Help.
2: Spin Language Reference PUB/PRI: Public and Private method blocks define Spin routines (pages 182/181).
Spin Language Reference Categorical Listing of Propeller Spin Language Elements marked with a superscript “a” are also available in Propeller Assembly. Block Designators CON Declare constant block; p 84. VAR Declare variable block; p 210. OBJ Declare object reference block; p 141. PUB Declare public method block; p 182. PRI Declare private method block; p 181. DAT Declare data block; p 99.
2: Spin Language Reference PLL8X PLL16X Constant for _CLKMODE: external frequency times 8; p 68. Constant for _CLKMODE: external frequency times 16; p 68. Cog Control COGIDa COGNEW COGINITa COGSTOPa REBOOT Current cog’s ID (0-7); p 75. Start the next available cog; p 78. Start, or restart, a cog by ID; p 76. Stop a cog by ID; p 83. Reset the Propeller chip; p 187. Process Control LOCKNEWa LOCKRETa LOCKCLRa LOCKSETa WAITCNTa WAITPEQa WAITPNEa WAITVIDa Check out a new lock; p 122.
Spin Language Reference REPEAT ...FROM ...TO ...STEP ...UNTIL ...WHILE Execute block of code repetitively an infinite or finite number of times with optional loop counter, intervals, exit and continue conditions; p 188. NEXT QUIT RETURN ABORT Skip rest of REPEAT block and jump to next loop iteration; p 140. Exit from REPEAT loop; p 186. Exit PUB/PRI with normal status and optional return value; p 196. Exit PUB/PRI with abort status and optional return value; p 47.
2: Spin Language Reference Directives STRING CONSTANT FLOAT ROUND TRUNC FILE Declare in-line string expression; resolved at compile time; p 205. Declare in-line constant expression; resolved at compile time; p 91. Declare floating-point expression; resolved at compile time; p 108. Round compile-time floating-point expression to integer; p 198. Truncate compile-time floating-point expression at decimal; p 209. Import data from an external file; p 107.
Spin Language Reference Constants TRUEa FALSEa POSXa NEGXa PIa Logical true: -1 ($FFFFFFFF); p 93. Logical false: 0 ($00000000) ; p 93. Maximum positive integer: 2,147,483,647 ($7FFFFFFF); p 93. Maximum negative integer: -2,147,483,648 ($80000000); p 93. Floating-point value for PI: ~3.141593 ($40490FDB); p 93. Variable RESULT Default result variable for PUB/PRI methods; p 194. Unary Operators + -++ ^^ || ~ ~~ ? |< >| ! NOT @ @@ Positive (+X); unary form of Add; p 150.
2: Spin Language Reference Binary Operators NOTE: All right-column operators are assignment operators. = := + * ** / // #> <# ~> << >> <-> >< & | ^ AND OR == <> < > =< => --and---and---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or---or-- = := += -= *= **= /= //= #>= <#= ~>= <<= >>= <-= ->= ><= &= |= ^= AND= OR= === <>= <= >= =<= =>= Constant assignment (CON blocks); p 148. Variable assignment (PUB/PRI blocks); p 149. Add; p 149.
Spin Language Reference Syntax Symbols % %% $ " _ # . .. : | \ , ( ) [ ] { } {{ }} ' '' Binary number indicator, as in %1010; p 207. Quaternary number indicator, as in %%2130; p 207. Hexadecimal indicator, as in $1AF or assembly 'here' indicator; p 207. String designator "Hello"; p 207. Group delimiter in constant values, or underscore in symbols; p 207. Object-Constant reference: obj#constant; p 207. Object-Method reference: obj.method(param) or decimal point; p 207. Range indicator, as in 0..7; p 207.
2: Spin Language Reference Spin Language Elements The remainder of this chapter describes the elements of the Spin Language, shown above, in alphabetical order. A few elements are explained within the context of others for clarity; use the page references from the categorical listing, above, to find those discussions. Many elements are available both in Spin and Propeller Assembly.
Spin Language Reference Syntax Definitions In addition to detailed descriptions, the following pages contain syntax definitions for many elements that describe, in short terms, all the options of that element. The syntax definitions use special symbols to indicate when and how certain element features are to be used. BOLDCAPS Items in bold uppercase should be typed in as shown. Bold Italics Items in bold italics should be replaced by user text; symbols, operators, expressions, etc. . .. : | \ [ ] (
2: Spin Language Reference – ABORT ABORT Command: Exit from PUB/PRI method using abort status with optional return Value. ((PUB ┆ PRI)) ABORT 〈Value〉 Returns: Either the current RESULT value, or Value if provided. • Value is an optional expression whose value is to be returned, with abort status, from the PUB or PRI method. Explanation ABORT is one of two commands (ABORT and RETURN) that terminate a PUB or PRI method’s execution.
ABORT – Spin Language Reference and more methods are returned from (via RETURN or by reaching the end of the method) the call stack gets shorter. This is called “pushing” onto the stack and “popping” off of the stack, respectively. The RETURN command pops the most recent data off the call stack to facilitate returning to the immediate caller; the one who directly called the method that just returned.
2: Spin Language Reference – ABORT The type of exit that MayAbort actually used, ABORT or RETURN, is not automatically known by the trapping call; it may have just happened to be the destination of a RETURN command. Therefore, the code must be written in a way to detect which type was used.
ABORT – Spin Language Reference The above example shows three methods of various logical levels, Main (“high-level”), Move (“mid-level”) and DriveMotors (“low-level”). The high-level method, Main, is the decision maker of the application; deciding how to respond to events like sensor activations and motor movements. The mid-level method, Move, is responsible for moving the robot a short distance.
2: Spin Language Reference – BYTE BYTE Designator: Declare byte-sized symbol, byte aligned/sized data, or read/write a byte of main memory. VAR BYTE Symbol 〈[Count]〉 DAT 〈Symbol〉 BYTE Data 〈[Count]〉 ((PUB ┆ PRI)) BYTE [BaseAddress] 〈[Offset]〉 ((PUB ┆ PRI)) Symbol.BYTE 〈[Offset]〉 • • • • • Symbol is the desired name for the variable (Syntax 1) or data block (Syntax 2) or is the existing name of the variable (Syntax 4).
BYTE – Spin Language Reference Range of Byte Memory that is byte-sized (8 bits) can contain a value that is one of 28 possible combinations of bits (i.e., one of 256 combinations). This gives byte-sized values a range of 0 to 255. Since the Spin language performs all mathematic operations using 32-bit signed math, any byte-sized values will be internally treated as positive long-sized values. However, the actual numeric value contained within a byte is subject to how a computer and user interpret it.
2: Spin Language Reference – BYTE optional symbol preceding it, which can be used for later reference (See DAT, page 99). For example: DAT MyData MyString byte byte 64, $AA, 55 "Hello",0 'Byte-aligned and byte-sized data 'A string of bytes (characters) The above example declares two data symbols, MyData and MyString. Each data symbol points to the start of byte-aligned and byte-sized data in main memory. MyData’s values, in main memory, are 64, $AA and 55, respectively.
BYTE – Spin Language Reference following it at $1B. Note that the starting address ($18) is arbitrary and is likely to change as the code is modified or the object itself is included in another application.
2: Spin Language Reference – BYTE An Alternative Memory Reference There is yet another way to access the data from the code example above; you could reference the data symbols directly.
BYTE – Spin Language Reference LongVar.byte[2] := 75 LongVar.byte[3] := 100 'Set third byte of LongVar to 75 'Set fourth byte of LongVar to 100 This example accesses the byte-sized components of both WordVar and LongVar, individually. The comments indicate what each line is doing. At the end of the Main method, WordVar will equal 25,600 and LongVar will equal 1,682,649,625. The same techniques can be used to reference byte-sized components of word-sized or longsized data symbols.
2: Spin Language Reference – BYTEFILL BYTEFILL Command: Fill bytes of main memory with a value. ((PUB ┆ PRI)) BYTEFILL (StartAddress, Value, Count ) • • • StartAddress is an expression indicating the location of the first byte of memory to fill with Value. Value is an expression indicating the value to fill bytes with. Count is an expression indicating the number of bytes to fill, starting with StartAddress.
BYTEMOVE – Spin Language Reference BYTEMOVE Command: Copy bytes from one region to another in main memory. ((PUB ┆ PRI)) BYTEMOVE (DestAddress, SrcAddress, Count ) • DestAddress is an expression specifying the main memory location to copy the first • SrcAddress is an expression specifying the main memory location of the first byte of • source to copy. Count is an expression indicating the number of bytes of the source to copy to the destination. byte of source to.
2: Spin Language Reference – CASE CASE Command: Compare expression against matching expression(s) and execute code block if match found. ((PUB ┆ PRI)) CASE CaseExpression MatchExpression : Statement(s) 〈 MatchExpression : Statement(s) 〉 〈 OTHER : Statement(s) 〉 • • • CaseExpression is the expression to compare. MatchExpression is a singular or comma-delimited set of value- and/or range- expressions, to compare CaseExpression against. Each MatchExpression must be followed by a colon (:).
CASE – Spin Language Reference you can press Ctrl + I to turn on block-group indicators. Pressing Ctrl + I again will disable that feature. See the Propeller Tool Help for a complete list of shortcut keys. Using CASE CASE is handy where one of many actions needs to be performed depending on the value of an expression. The following example assumes A, X and Y are variables defined earlier. case X+Y 10, 15: !outa[0] A*2 : !outa[1] 30..
2: Spin Language Reference – CASE expression that is a match has its block of code executed; no further expressions are tested after that. This means that if we had rearranged the 25 and 20..30 lines, so that the range of 20..30 is checked first, we’d have a bug in our code. We did this below: case X+Y 10, 15: !outa[0] 20..
CHIPVER – Spin Language Reference CHIPVER Command: Get the Propeller chip’s version number. ((PUB ┆ PRI)) CHIPVER Returns: Version number of the Propeller chip. Explanation The CHIPVER command reads and returns the version number of the Propeller chip. For example: V := chipver This example sets V to the version number of the Propeller chip, 1 in this case.
2: Spin Language Reference – CLKFREQ CLKFREQ Command: Current System Clock frequency; the frequency at which each cog is running. ((PUB ┆ PRI)) CLKFREQ Returns: Current System Clock frequency, in Hz. Explanation The value returned by CLKFREQ is the actual System Clock frequency as determined by the current clock mode (oscillator type, gain, and PLL settings) and the external XI pin frequency, if any. Objects use CLKFREQ to determine the proper time delays for time-sensitive operations.
CLKFREQ – Spin Language Reference CLKFREQ vs. _CLKFREQ CLKFREQ is related to, but not the same as, _CLKFREQ. CLKFREQ is command that returns the current System Clock frequency whereas _CLKFREQ is an application-defined constant that contains the application’s System Clock frequency at startup. In other words, CLKFREQ is the current clock frequency and _CLKFREQ is the original clock frequency; they both may happen to be the same value but they certainly can be different. Page 64 · Propeller Manual v1.
2: Spin Language Reference – _CLKFREQ _CLKFREQ Constant: Pre-defined, one-time settable constant for specifying the System Clock frequency. CON _CLKFREQ = Expression • Expression is an integer expression that indicates the System Clock frequency upon application start-up. Explanation _CLKFREQ specifies the System Clock frequency for start-up. It is a pre-defined constant symbol whose value is determined by the top object file of an application.
_CLKFREQ – Spin Language Reference CON _CLKMODE = XTAL2 _CLKFREQ = 10_000_000 These two declarations set the clock mode for an external medium-speed crystal, no Clock PLL multiplier, and a System Clock frequency of 10 MHz. The _XINFREQ value is automatically set to 10 MHz, as well, because of these declarations. _CLKFREQ vs CLKFREQ _CLKFREQ is related to, but not the same as, CLKFREQ.
2: Spin Language Reference – CLKMODE CLKMODE Command: Current clock mode setting. ((PUB ┆ PRI)) CLKMODE Returns: Current clock mode. Explanation The clock mode setting is the byte-sized value, determined by the application at compile time, from the CLK register. See CLK Register, page 28, for explanation of the possible settings. For example: Mode := clkmode This statement can be used to set a variable, Mode, to the current clock mode setting.
_CLKMODE – Spin Language Reference _CLKMODE Constant: Pre-defined, one-time settable constant for specifying application-level clock mode settings. CON _CLKMODE = Expression • Expression is an integer expression made up of one or two Clock Mode Setting Constants shown in Table 2-3. This will be the clock mode upon application start-up. Explanation _CLKMODE is used to specify the desired nature of the System Clock.
2: Spin Language Reference – _CLKMODE Table 2-4: Valid Clock Mode Expressions and CLK Register Values Valid Expression CLK Register Value RCFAST 0_0_0_00_000 RCSLOW 0_0_0_00_001 XINPUT 0_0_1_00_010 XTAL1 XTAL2 XTAL3 0_0_1_01_010 0_0_1_10_010 0_0_1_11_010 XINPUT XINPUT XINPUT XINPUT XINPUT + + + + + PLL1X PLL2X PLL4X PLL8X PLL16X 0_1_1_00_011 0_1_1_00_100 0_1_1_00_101 0_1_1_00_110 0_1_1_00_111 Valid Expression CLK Register Value XTAL1 XTAL1 XTAL1 XTAL1 XTAL1 XTAL2 XTAL2 XTAL2 XTAL2 XTAL2 + +
_CLKMODE – Spin Language Reference multiplied by 16 (the Clock PLL always multiplies by 16) but the 8x bit result would be used; the System Clock would be 4 MHz * 8 = 32 MHz. CON _CLKMODE = XINPUT + PLL2X This sets the clock mode for an external clock-oscillator, connected to XI only, and enables the Clock PLL circuit and sets the System Clock to use the 2x result. If an external clockoscillator pack of 8 MHz was attached to XI, the System clock would run at 16 MHz; that’s 8 MHz * 2.
2: Spin Language Reference – CLKSET CLKSET Command: Set both the clock mode and System Clock frequency at run time. ((PUB ┆ PRI)) CLKSET (Mode, Frequency) • Mode is an integer expression that will be written to the CLK register to change the • Frequency is an integer expression that indicates the resulting System Clock clock mode. frequency. Explanation One of the most powerful features of the Propeller chip is the ability to change the clock behavior at run time.
CLKSET – Spin Language Reference current state, either off or on. See the Clock object in the Propeller Library for clock modification and timing methods. NOTE: It takes approximately 75 µs for the Propeller Chip to perform the clock source switching action. Page 72 · Propeller Manual v1.
2: Spin Language Reference – CNT CNT Register: System Counter register. ((PUB ┆ PRI)) CNT Returns: Current 32-bit System Counter value. Explanation The CNT register contains the current value in the global 32-bit System Counter. The System Counter serves as the central time reference for all cogs; it increments its 32-bit value once every System Clock cycle. Upon power-up/reset, the System Counter starts with an arbitrary value and counts upwards from there, incrementing with every System Clock cycle.
CNT – Spin Language Reference PUB Toggle | TimeBase, OneMS dira[0]~~ OneMS := clkfreq / 1000 TimeBase := cnt repeat waitcnt(TimeBase += OneMS) !outa[0] 'Set P0 to output 'Calculate cycles per 1 millisecond 'Get current count 'Loop endlessly ' Wait to start of next millisecond ' Toggle P0 Here, I/O pin 0 is set to output. Then the local variable OneMS is set equal to the current System Clock frequency divided by 1000; i.e., the number of System Clock cycles per 1 millisecond of time.
2: Spin Language Reference – COGID COGID Command: Current cog’s ID number (0-7). ((PUB ┆ PRI)) COGID Returns: The current cog’s ID (0-7). Explanation The value returned by COGID is the ID of the cog that executed the command. Normally, the actual cog that code is running in does not matter, however, for some objects it might be important to keep track of it.
COGINIT – Spin Language Reference COGINIT Command: Start or restart a cog by ID to run Spin code or Propeller Assembly code. ((PUB ┆ PRI)) COGINIT (CogID, SpinMethod 〈(ParameterList)〉, StackPointer ) ((PUB ┆ PRI)) COGINIT (CogID, AsmAddress, Parameter ) • CogID is the ID (0 – 7) of the cog to start, or restart. A CogID above 7 results in the • SpinMethod is the PUB or PRI Spin method that the affected cog should run. next available cog being started (if possible).
2: Spin Language Reference – COGINIT frame in the specified stack space before launching the cog. Relaunching a cog with a COGINIT command specifying the same stack space that it is currently using will likely cause the new stack frame image to be clobbered before the cog is restarted. To prevent this from happening, first perform a COGSTOP on that cog, followed by the desired COGINIT.
COGNEW – Spin Language Reference COGNEW 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.
2: Spin Language Reference – COGNEW Spin Code (Syntax 1) To run a Spin method in another cog, the COGNEW command needs the method name, its parameters, and a pointer to some stack space.
COGNEW – Spin Language Reference The Need for Stack Space A cog executing Spin code, unlike one executing Propeller Assembly code, needs some temporary workspace, called “stack space,” to hold operational data such as call stacks, parameters and intermediate expression results. Without this, sophisticated features such as method calls, result values, and complex expressions would not be possible without severe limitations.
2: Spin Language Reference – COGNEW If Method is determined to be code that is truly important to run in another cog, rather than write code like the example above, SomeObject should instead be rewritten similar to the example below.
COGNEW – Spin Language Reference Loop Delay Time waitcnt xor jmp res res Time, outa, #Loop Delay #1 'Wait for 1/4 second 'toggle pin 'loop back 1 1 The COGNEW instruction, in the Main method above, tells the Propeller chip to launch the Toggle assembly code into a new cog. The Propeller then finds an available cog and copies 496 longs of the DAT block’s content, starting at Toggle, into the cog’s RAM.
2: Spin Language Reference – COGSTOP COGSTOP Command: Stop cog by its ID. ((PUB ┆ PRI)) COGSTOP (CogID ) • CogID is the ID (0 – 7) of the cog to stop. Explanation COGSTOP stops a cog whose ID is CogID and places that cog into a dormant state. In the dormant state, the cog ceases to receive System Clock pulses so that power consumption is greatly reduced. To stop a cog, issue the COGSTOP command with the ID of the cog to stop.
CON – Spin Language Reference CON Designator: Declare a Constant Block. CON Symbol = Expression 〈(( ,┆ )) Symbol = Expression〉… CON #Expression (( ,┆ )) Symbol 〈[Offset]〉 〈(( ,┆ )) Symbol 〈[Offset]〉 〉… CON Symbol 〈[Offset]〉 〈(( ,┆ )) Symbol 〈[Offset]〉 〉… • • • Symbol is the desired name for the constant. Expression is any valid integer, or floating-point, constant algebraic expression. Expression can include other constant symbols as long as they were defined previously.
2: Spin Language Reference – CON Common Constant Declarations (Syntax 1) The most common forms of constant declarations begin with CON on a line by itself followed by one or more declarations. CON must start in column 1 (the leftmost column) of the line it is on and we recommend the lines following be indented by at least one space. The expressions can be combinations of numbers, operators, parentheses, and quoted characters. See Operators, page 143, for examples of expressions.
CON – Spin Language Reference value is a floating-point value; the expression must either be a single floating-point value or be made up entirely of floating-point values (no integers). Floating-point values must be written as: 1) decimal digits followed by a decimal point and at least one more decimal digit, 2) decimal digits followed by “e” (for exponent) and an integer exponent value, or, 3) a combination of 1 and 2. The following are examples of valid constants: 0.5 floating-point value 1.
2: Spin Language Reference – CON For run-time floating-point operations, the FloatMath, FloatString, Float32, and Float32Full objects provide math functions compatible with single-precision numbers. See FLOAT on page 108, ROUND on page 198, TRUNC on page 209, and the FloatMath, FloatString, Float32, and Float32Full objects for more information. T Enumerations (Syntax 2 and 3) Constant Blocks can also declare enumerated constant symbols.
CON – Spin Language Reference cases, the values themselves don’t usually matter; all that matters is that they are each assigned a unique number. Defining enumerated values like this has the advantages of insuring that the assigned values are unique and contiguous within the group.
2: Spin Language Reference – CON Here, RunTest and RunVerbose are 1 and 2, respectively, and RunBrief and RunFull are 5 and 6, respectively. While this feature may be handy, to maintain good programming practices it should only be used in rare cases. A more recommended way to achieve the previous example’s result is to include the optional Offset field.
CON – Spin Language Reference Example: OBJ Num : "Numbers" PUB SomeRoutine Format := Num#DEC 'Set Format to Number's Decimal constant Here an object, “Numbers,” is declared as the symbol Num. Later, a method refers to numbers’ DEC constant with Num#DEC. Num is the object reference, # indicates we need to access that object’s constants, and DEC is the constant within the object we need.
2: Spin Language Reference – CONSTANT CONSTANT Directive: Declare in-line constant expression to be completely resolved at compile time. ((PUB ┆ PRI)) CONSTANT (ConstantExpression ) Returns: Resolved value of constant expression. • ConstantExpression is the desired constant expression. Explanation The CON block may be used to create constants from expressions that are referenced from multiple places in code, but there are occasions when a constant expression is needed for temporary, one-time purposes.
CONSTANT – Spin Language Reference CON X = 500 Y = 2500 PUB Blink !outa[0] waitcnt(constant(X+200) + cnt) 'exp w/compile & run-time parts !outa[0] waitcnt(constant((X+Y)/2) + cnt)'exp w/compile & run-time parts The above two examples do exactly the same thing: their Blink methods toggle P0, wait for X+200 cycles, toggle P0 again and wait for (X+Y)/2 cycles before returning.
2: Spin Language Reference – Constants (pre-defined) Constants (pre-defined) The following constants are pre-defined by the compiler: TRUE Logical true: -1 ($FFFFFFFF) FALSE Logical false: 0 ($00000000) POSX Maximum positive integer: 2,147,483,647 ($7FFFFFFF) NEGX Maximum negative integer: -2,147,483,648 ($80000000) PI Floating-point value for PI: ≈ 3.
Constants (pre-defined) – Spin Language Reference POSX and NEGX POSX and NEGX are typically used for comparison purposes or as a flag for a specific event: if Z > NEGX —or— PUB FindListItem(Item) : Index Index := NEGX 'Default to "not found" response if - Index := PI PI can be used for floating-point calculations, either floating-point constants or floating-point variable values using the FloatMath
2: Spin Language Reference – CTRA, CTRB CTRA, CTRB Register: Counter A and Counter B Control Registers. ((PUB ┆ PRI)) CTRA ((PUB ┆ PRI)) CTRB Returns: Current value of Counter A or Counter B Control Register, if used as a source variable. Explanation CTRA and CTRB are two of six registers (CTRA, CTRB, FRQA, FRQB, PHSA, and PHSB) that affect the behavior of a cog’s Counter Modules. Each cog has two identical counter modules (A and B) that can perform many repetitive tasks.
CTRA, CTRB – Spin Language Reference state machine. Since the counter’s update period may be brief (12.5 ns at 80 MHz), very dynamic signal generation and measurement is possible. Control Register Fields The CTRA and CTRB registers each contain four fields shown in the table below. Table 2-5: CTRA and CTRB Registers 31 - 30..26 CTRMODE 25..23 PLLDIV 22..15 - 14..9 BPIN 8..6 - 5..0 APIN APIN The APIN field of CTRA selects a primary I/O pin for that counter. May be ignored if not used.
2: Spin Language Reference – CTRA, CTRB CTRMODE The CTRMODE field of CTRA and CTRB selects one of 32 operating modes, shown in Table 2-7, for the corresponding Counter A or Counter B. In Propeller Assembly, the CTRMODE field can conveniently be written, along with PLLDIV, using the MOVI instruction. The modes %00001 through %00011 cause FRQx-to-PHSx, accumulation to occur every clock cycle. This creates a numerically controlled oscillator (NCO) in PHSx[31], which feeds the PLLx's reference input.
CTRA, CTRB – Spin Language Reference Table 2-7: Counter Modes (CTRMODE Field Values) CTRMODE Accumulate Description APIN Output* FRQx to PHSx BPIN Output* %00000 Counter disabled (off) 0 (never) 0 (none) 0 (none) %00001 %00010 %00011 PLL internal (video mode) PLL single-ended PLL differential 1 (always) 1 1 0 PLLx PLLx 0 0 !PLLx %00100 %00101 NCO single-ended NCO differential 1 1 PHSx[31] PHSx[31] 0 !PHSx[31] %00110 %00111 DUTY single-ended DUTY differential 1 1 PHSx-Carry PHSx-Carry
2: Spin Language Reference – DAT DAT Designator: Declare a Data Block. DAT 〈Symbol〉 Alignment 〈Size〉 〈Data〉 〈[Count ]〉 〈, 〈Size〉 Data 〈[Count ]〉〉… DAT 〈Symbol〉 〈Condition〉 Instruction Operands 〈Effect(s)〉 • • • • • • • • • Symbol is an optional name for the data, reserved space, or instruction that follows. Alignment is the desired alignment and default size (BYTE, WORD, or LONG) of the data elements that follow.
DAT – Spin Language Reference Declaring Data(Syntax 1) Data is declared with a specific alignment and size (BYTE, WORD, or LONG) to indicate how it should be stored in memory. The location where data is actually stored depends on the structure of the object and the application it is compiled into since data is included as part of the compiled code.
2: Spin Language Reference – DAT You may have noticed that the value 75000 was specified as a word-sized one. The number 75000 in hexadecimal is $124F8, but since that’s larger than a word, only the lowest word ($24F8) of the value was stored. This resulted in word 6 (bytes 12 and 13) containing $F8 and $24, and word 7 (bytes 14 and 15) containing $00 and $00 due to the padding for the following long-aligned values.
DAT – Spin Language Reference This example creates a data table called MyData that consists of bytes $FF, 25 and %1010. The public method, GetData, reads the first byte of MyData from main memory and stores it in its local variable, Temp. You can also use the BYTE, WORD, and LONG declarations to read main memory locations.
2: Spin Language Reference – DAT Delay Time res res 1 1 When a Propeller Application initially boots up, only Spin code is executed. At any time, however, that Spin code can choose to launch assembly code into a cog of its own. The COGNEW (page 78) and COGINIT (page 76) commands are used for this purpose. The following Spin code example launches the Toggle assembly code shown above.
DIRA, DIRB – Spin Language Reference DIRA, DIRB Register: Direction Register for 32-bit Ports A and B. ((PUB ┆ PRI)) DIRA 〈[Pin(s)]〉 ((PUB ┆ PRI)) DIRB 〈[Pin(s)]〉 (Reserved for future use) Returns: Current value of direction bits for I/O Pin(s) in Ports A or B, if used as a source variable. • Pin(s) is an optional expression, or a range-expression, that specifies the I/O pin, or pins, to access in Port A (0-31) or Port B (32-63). If given as a single expression, only the pin specified is accessed.
2: Spin Language Reference – DIRA, DIRB This configuration can easily be described in the following simple rules: A. A pin is an input only of no active cog sets it to an output. B. A pin is an output if any active cog sets it to an output. If a cog is disabled, its direction register is treated as if were cleared to 0, causing it to exert no influence on I/O pin directions and states.
DIRA, DIRB – Spin Language Reference The DIRA register supports a special form of expression, called a range-expression, which allows you to affect a group of I/O pins at once, without affecting others outside the specified range. To affect multiple, contiguous I/O pins at once, use a range expression (like x..y) in the Pin(s) field. DIRA[5..3]~~ 'Set DIRA bits 5 through 3 (P5-P3 to output) This sets P5, P4 and P3 to outputs; all other bits of DIRA remain in their previous state.
2: Spin Language Reference – FILE FILE Directive: Import external file as data. DAT FILE "FileName" • FileName is the name, without extension, of the desired data file. Upon compile, a file with this name is searched for in the editor tabs, the working directory and the library directory. FileName can contain any valid filename characters; disallowed characters are \, /, :, *, ?, ", <, >, and |.
FLOAT – Spin Language Reference FLOAT Directive: Convert an integer constant expression to a compile-time floating-point value. ((CON ┆ VAR ┆ OBJ ┆ PUB ┆ PRI ┆ DAT)) FLOAT (IntegerConstant ) Returns: Resolved value of integer constant expression as a floating-point number. • IntegerConstant is the desired integer constant expression to be used as a constant floating-point value. Explanation FLOAT is one of three directives (FLOAT, ROUND and TRUNC) used for floating-point constant expressions.
2: Spin Language Reference – FLOAT Here, Two is defined as an integer constant and Ratio appears to be defined as a floating-point constant. This causes an error on the Ratio line because, for floating-point constant expressions, every value within the expression must be a floating-point value; you cannot mix integer and floating-point values like Ratio = 2 / 5.0.
_FREE – Spin Language Reference _FREE Constant: Pre-defined, one-time settable constant for specifying the size of an application’s free space. CON _FREE = Expression • Expression is an integer expression that indicates the number of longs to reserve for free space. Explanation _FREE is a pre-defined, one-time settable optional constant that specifies the required free memory space of an application.
2: Spin Language Reference – FRQA, FRQB FRQA, FRQB Register: Counter A and Counter B frequency registers. ((PUB ┆ PRI)) FRQA ((PUB ┆ PRI)) FRQB Returns: Current value of Counter A or Counter B Frequency Register, if used as a source variable. Explanation FRQA and FRQB are two of six registers (CTRA, CTRB, FRQA, FRQB, PHSA, and PHSB) that affect the behavior of a cog’s Counter Modules. Each cog has two identical counter modules (A and B) that can perform many repetitive tasks.
IF – Spin Language Reference IF Command: Test condition(s) and execute a block of code if valid (positive logic). ((PUB ┆ PRI)) IF Condition(s) IfStatement(s) 〈 ELSEIF Condition(s) ElseIfStatement(s) 〉… 〈 ELSEIFNOT Condition(s) ElseIfNotStatement(s) 〉… 〈 ELSE ElseStatement(s) 〉 • • • • • Condition(s) is one or more Boolean expressions to test. IfStatement(s) is a block of one or more lines of code to execute when the IF’s Condition(s) is true.
2: Spin Language Reference – IF Indention is Critical IMPORTANT: Indention is critical. The Spin language relies on indention (of one space or more) on lines following conditional commands to determine if they belong to that command or not. To have the Propeller Tool indicate these logically grouped blocks of code on-screen, you can press Ctrl + I to turn on block-group indicators. Pressing Ctrl + I again will disable that feature. See the Propeller Tool Help for a complete list of shortcut keys.
IF – Spin Language Reference if X > 10 AND X < 100 'If X greater than 10 and less than 100 This IF statement would be true if, and only if, X is greater than 10 and X is also less than 100. In other words, it’s true if X is in the range 11 to 99. Sometimes statements like these can be a little difficult to read. To make it easier to read, parentheses can be used to group each subcondition, such as with the following.
2: Spin Language Reference – IF !outa[1] 'Toggle P1 Here, if X is greater than 100, I/O pin 0 is toggled, otherwise, if X equals 90, I/O pin 1 is toggled, and if neither of those conditions were true, neither P0 nor P1 is toggled.
IF – Spin Language Reference We did this below: if X > 100 !outa[0] elseif X > 50 !outa[2] elseif X == 90 !outa[1] 'If X is greater than 100 'Toggle P0 'Else If X > 50 'Toggle P2 'Else If X = 90 <-- ERROR, ABOVE COND.
2: Spin Language Reference – IFNOT IFNOT Command: Test condition(s) and execute a block of code if valid (negative logic). ((PUB ┆ PRI)) IFNOT Condition(s) IfNotStatement(s) 〈 ELSEIF Condition(s) ElseIfStatement(s) 〉… 〈 ELSEIFNOT Condition(s) ElseIfNotStatement(s) 〉… 〈 ELSE ElseStatement(s) 〉 • • Condition(s) is one or more Boolean expressions to test. IfNotStatement(s) is a block of one or more lines of code to execute when the IFNOT’s T • Condition(s) is false.
INA, INB – Spin Language Reference INA, INB Register: Input Registers for 32-bit Ports A and B. ((PUB ┆ PRI)) INA 〈[Pin(s)]〉 ((PUB ┆ PRI)) INB 〈[Pin(s)]〉 (Reserved for future use) Returns: Current state of I/O Pin(s) for Port A or B. • Pin(s) is an optional expression, or a range-expression, that specifies the I/O pin, or pins, to access in Port A (0-31) or Port B (32-63). If given as a single expression, only the pin specified is accessed.
2: Spin Language Reference – INA, INB Note because of the “wired-OR” nature of the I/O pins, no electrical contention between cogs is possible, yet they can all still access I/O pins simultaneously. It is up to the application developer to ensure that no two cogs cause logical contention on the same I/O pin during run time. Since all cogs share all I/O pins, a cog could use INA to read pins it is using as well as the pins that are in use by one or more other cogs.
LOCKCLR – Spin Language Reference LOCKCLR Command: Clear lock to false and get its previous state. ((PUB ┆ PRI)) LOCKCLR ( ID ) Returns: Previous state of lock (TRUE or FALSE). • ID is the ID (0 – 7) of the lock to clear to false. Explanation LOCKCLR is one of four lock commands (LOCKNEW, LOCKRET, LOCKSET, and LOCKCLR) used to manage resources that are user-defined and deemed mutually exclusive. LOCKCLR clears lock ID to FALSE and retrieves the previous state of that lock (TRUE or FALSE).
2: Spin Language Reference – LOCKCLR condition “until not lockset…” is true, meaning we have “locked the resource” and the first repeat loop ends. The second REPEAT loop in each method reads or writes the resource, via the long[Idx] and LocalData[Idx] statements. The last line of each method, lockclr(SemID), clears the resource’s associated lock to FALSE, logically unlocking or releasing the resource for others to use. See LOCKNEW, page 122; LOCKRET, page 125; and LOCKSET, page 126 for more information.
LOCKNEW – Spin Language Reference LOCKNEW Command: Check out a new lock and get its ID. ((PUB ┆ PRI)) LOCKNEW Returns: ID (0-7) of the lock checked out, or -1 if none were available. Explanation LOCKNEW is one of four lock commands (LOCKNEW, LOCKRET, LOCKSET, and LOCKCLR) used to manage resources that are user-defined and deemed mutually exclusive. LOCKNEW checks out a unique lock, from the Hub, and retrieves the ID of that lock. If no locks were available, LOCKNEW returns -1.
2: Spin Language Reference – LOCKNEW Using LOCKNEW A user-defined, mutually exclusive resource should be initially set up by a cog, then that same cog should use LOCKNEW to check out a unique lock in which to manage that resource and pass the ID of that lock to any other cogs that require it.
LOCKNEW – Spin Language Reference • If a resource is no longer needed, or becomes non-exclusive, the associated lock should be returned to the lock pool via LOCKRET(SemID). Usually this is done by the same cog that checked out the lock originally. Applications should be written such that locks are not accessed with LOCKSET or LOCKCLR unless they are currently checked out. Note that user-defined resources are not actually locked by either the Hub or the checked-out lock.
2: Spin Language Reference – LOCKRET LOCKRET Command: Release lock back to lock pool, making it available for future LOCKNEW requests. ((PUB ┆ PRI)) LOCKRET ( ID ) • ID is the ID (0 – 7) of the lock to return to the lock pool. Explanation LOCKRET is one of four lock commands (LOCKNEW, LOCKRET, LOCKSET, and LOCKCLR) used to manage resources that are user-defined and deemed mutually exclusive.
LOCKSET – Spin Language Reference LOCKSET Command: Set lock to true and get its previous state. ((PUB ┆ PRI)) LOCKSET ( ID ) Returns: Previous state of lock (TRUE or FALSE). • ID is the ID (0 – 7) of the lock to set to TRUE. Explanation LOCKSET is one of four lock commands (LOCKNEW, LOCKRET, LOCKSET, and LOCKCLR) used to manage resources that are user-defined and deemed mutually exclusive. LOCKSET sets lock ID to TRUE and retrieves the previous state of that lock (TRUE or FALSE).
2: Spin Language Reference – LOCKSET condition “until not lockset…” is true, meaning we have “locked the resource” and the first REPEAT loop ends. The second REPEAT loop in each method reads or writes the resource, via the long[Idx] and LocalData[Idx] statements. The last line of each method, lockclr(SemID), clears the resource’s associated lock to FALSE, logically unlocking or releasing the resource for others to use. T See LOCKNEW, page 122; LOCKRET, page 125; and LOCKCLR, page 120 for more information.
LONG – Spin Language Reference LONG Designator: Declare long-sized symbol, long aligned/sized data, or read/write a long of main memory. VAR LONG Symbol 〈[Count ]〉 DAT 〈Symbol〉 LONG Data 〈[Count]〉 ((PUB ┆ PRI)) LONG [BaseAddress] 〈[Offset ]〉 • • • • • Symbol is the desired name for the variable (Syntax 1) or data block (Syntax 2).
2: Spin Language Reference – LONG Long Variable Declaration (Syntax 1) In VAR blocks, syntax 1 of LONG is used to declare global, symbolic variables that are either long-sized, or are any array of longs. For example: VAR long long Temp List[25] 'Temp is a long (2 words, 4 bytes) 'List is a long array The above example declares two variables (symbols), Temp and List. Temp is simply a single, long-sized variable.
LONG – Spin Language Reference contains $44, $55, $99, $FF, 232 and 3, 0 and 0 since the data is stored in little-endian format. Note: MyList could have been defined as word-aligned, long-sized data if the “byte” reference were replaced with “word”. This data is compiled into the object and resulting application as part of the executable code section and may be accessed using the read/write form, syntax 3, of LONG (see below).
2: Spin Language Reference – LONG Long Address — (Long Offset) — [Long Symbol] — $18 (0) [MyData] Data as longs — Data as bytes — 0 Byte Address (Byte Offset) [Byte Symbol] — — — $18 (-8) 640,000 196 9 $19 (-7) $1A (-6) 0 $1B (-5) $24 (3) $20 (2) $1C (1) $BB50 $FF995544 $50 $BB $00 $00 $44 $55 $99 $FF 232 $1C (-4) $1D (-3) $1E (-2) $1F (-1) $20 $21 (0) (1) [MyList] $22 (2) $23 (3) $24 (4) 1,000 3 0 $25 (5) $26 (6) 0 $27 (7) Figure 2-2: Main Memory Long-Sized Data Structure and Add
LONG – Spin Language Reference and longs relate to each other, but it may prove problematic when thinking of multiple items of a single size, like longs. For this reason, the LONG designator has a very handy feature to facilitate addressing from a long-centric perspective. Its BaseAddress field when combined with the optional Offset field operates in a base-aware fashion. Imagine accessing longs of memory from a known starting point (the BaseAddress).
2: Spin Language Reference – LONG Referring back to the example code above Figure 2-2 you might expect these two statements to read the first and second longs of MyList; $FF995544 and 1000, respectively. Instead, it reads the first and second “bytes” of MyList, $44 and $55, respectively. What happened? Unlike MyData, the MyList entry is defined in the code as byte-sized and byte-aligned data.
LONGFILL – Spin Language Reference LONGFILL Command: Fill longs of main memory with a value. ((PUB ┆ PRI)) LONGFILL(StartAddress, Value, Count ) • StartAddress is an expression indicating the location of the first long of memory to fill • • Value is an expression indicating the value to fill longs with. Count is an expression indicating the number of longs to fill, starting with with Value. StartAddress.
2: Spin Language Reference – LONGMOVE LONGMOVE Command: Copy longs from one region to another in main memory. ((PUB ┆ PRI)) LONGMOVE (DestAddress, SrcAddress, Count ) • DestAddress is an expression specifying the main memory location to copy the first • SrcAddress is an expression specifying the main memory location of the first long of • source to copy. Count is an expression indicating the number of longs of the source to copy to the destination. long of source to.
LOOKDOWN, LOOKDOWNZ – Spin Language Reference LOOKDOWN, LOOKDOWNZ Command: Get the index of a value in a list. ((PUB ┆ PRI)) LOOKDOWN ( Value : ExpressionList ) ((PUB ┆ PRI)) LOOKDOWNZ ( Value : ExpressionList ) Returns: One-based index position (LOOKDOWN) or a zero-based index position (LOOKDOWNZ) of Value in ExpressionList, or 0 if Value not found. • • Value is an expression indicating the value to find in ExpressionList. ExpressionList is a comma-separated list of expressions.
2: Spin Language Reference – LOOKDOWN, LOOKDOWNZ The GetIndex method in this example uses LOOKDOWN to find Value and returns the index where it was found in the ExpressionList, or 0 if not found. The ShowList method calls GetIndex repeatedly with different values and prints the resulting index on a display. Assuming Print is a method that displays a value, this example will print 1, 2, 3, 4, 5, 6 and 7 on a display.
LOOKUP, LOOKUPZ – Spin Language Reference LOOKUP, LOOKUPZ Command: Get value from an indexed position within a list. ((PUB ┆ PRI)) LOOKUP ( Index : ExpressionList ) ((PUB ┆ PRI)) LOOKUPZ ( Index : ExpressionList ) Returns: Value at the one-based Index position (LOOKUP) or zero-based Index position (LOOKUPZ) of ExpressionList, or 0 if out-of-range. • • Index is an expression indicating the position of the desired value in ExpressionList. For LOOKUP, Index is one-based (1..N).
2: Spin Language Reference – LOOKUP, LOOKUPZ If LOOKUPZ is used, the list is zero-based (0..N-1) instead of one-based; an Index of 0 returns 25, Index of 1 returns 300, etc. If Index is out of range 0 is returned. So, for LOOKUP, if the REPEAT statement went from 0 to 8, instead of 1 to 7, this example would print 0, 25, 300, 2510, 163, 17, 8000, 3 and 0 on a display. Propeller Manual v1.
NEXT – Spin Language Reference NEXT Command: Skip remaining statements of REPEAT loop and continue with the next loop iteration. ((PUB ┆ PRI)) NEXT Explanation NEXTis one of two commands (NEXT and QUIT) that affect REPEAT loops. NEXT causes any further statements in the REPEAT loop to be skipped and the next iteration of the loop to be started thereafter.
2: Spin Language Reference – OBJ OBJ Designator: Declare an Object Block. OBJ Symbol 〈[Count]〉: "ObjectName" 〈 Symbol 〈[Count]〉: "ObjectName"〉… • • • Symbol is the desired name for the object symbol. Count is an optional expression, enclosed in brackets, that indicates this is an array of objects, with Count number of elements. When later referencing these elements, they begin with element 0 and end with element Count-1. ObjectName is the filename, without extension, of the desired object.
OBJ – Spin Language Reference Method reference symbol (a period ‘.’) and finally the name of the method to call. Num.ToStr, for instance, calls the Numbers object’s public ToStr method. Term.Str calls the TV_Terminal’s public Str method. In this case the Num.ToStr has two parameters, in parentheses, and Term.Str has one parameter. Also notice that the second parameter of the Num.ToStr call is Num#DEC. The # symbol is the Object-Constant reference symbol; it gives access to an object’s constants.
2: Spin Language Reference – Operators Operators The Propeller chip features a powerful set of math and logic operators. A subset of these operators is supported by the Propeller Assembly language; however, since the Spin language has a use for every form of operator supported by the Propeller, this section describes every operator in detail. Please see the Operators section on page 325 for a list of operators available in Propeller Assembly.
Operators – Spin Language Reference Table 2-9: Math and Logic Operators Assignment Constant Expressions1 Is Operator Description, Page Number Usage Unary Integer Float n/a1 Constant assignment (CON blocks only), 148 always n/a1 = n/a1 Variable assignment (PUB/PRI blocks only), 149 always n/a1 := 9 9 Add, 149 + += 9 9 9 never Positive (+X); unary form of Add, 150 + 9 9 Subtract, 150 -= 9 9 9 if solo Negate (-X); unary form of Subtract, 150 9 always Pre-decrement (--X) or post-decrement (X--), 151 -9 always P
2: Spin Language Reference – Operators Table 2-10: Operator Precedence Levels Level Notes Highest (0) 1 2 3 4 5 6 7 8 9 10 11 Lowest (12) Unary Unary Unary Operators --, ++, ~, ~~, ?, @, @@ +, -, ^^, ||, |<, >|, ! ->, <-, >>, <<, ~>, >< & |, ^ *, **, /, // +, #>, <# <, >, <>, ==, =<, => NOT AND OR =, :=, all other assignments Operator Names Inc/Decrement, Clear, Set, Random, Symbol/Object Address Positive, Negate, Square Root, Absolute, Decode, Encode, Bitwise NOT Rotate Right/Left, Shift Right/Left,
Operators – Spin Language Reference Here are assignment operator examples: Count++ Data >>= 3 ' ' ' ' (Unary) evaluate Count + 1 and write result to Count (Binary) shift Data right 3 bits and write result to Data Binary operators have special forms that end in equal ‘=’ to make them assignment operators. Unary operators do not have a special assignment form; some always assign while others assign only in special situations. See Table 2-9 above and the operator’s explanation, for more information.
2: Spin Language Reference – Operators ...to be equal to 49; that is, 8 * 4 = 32, 6 / 2 = 3, and 20 + 32 – 3 = 49. If you wish the expression to be evaluated differently, use parentheses to enclose the necessary portions of the expression. For example: X = (20 + 8) * 4 – 6 / 2 This will evaluate the expression in parentheses first, the 20 + 8, causing the expression to now result in 109, instead of 49. Table 2-10 indicates each operator’s level of precedence from highest (level 0) to lowest (level 12).
Operators – Spin Language Reference The remaining pages of this section further explain each math and logic operator shown in Table 2-9 in the same order shown. Constant Assignment ‘=’ The Constant Assignment operator is used only within CON blocks, to declare compile-time constants. For example, CON _xinfreq = 4096000 WakeUp = %00110000 This code sets the symbol _xinfreq to 4,096,000 and the symbol WakeUp to %00110000.
2: Spin Language Reference – Operators The above code creates three floating-point constants. OneHalf is equal to 0.5, Ratio is equal to 0.4 and Miles is equal to 1,000,000. Note that if Ratio were defined as 2 / 5 instead of 2.0 / 5.0, the expression would be treated as an integer constant and the result would be an integer constant equal to 0.
Operators – Spin Language Reference Add has an assignment form, +=, that uses the variable to its left as both the first operand and the result destination. For example: X += 10 'Short form of X := X + 10 Here, the value of X is added to 10 and the result is stored back in X. The assignment form of Add may also be used within expressions for intermediate results; see Intermediate Assignments, page 147.
2: Spin Language Reference – Operators This would negate the value of A and store the result back to A. Decrement, pre- or post- ‘- -’ The Decrement operator is a special, immediate operator that decrements a variable by one and assigns the new value to that same variable. It can only be used in run-time variable expressions. Decrement has two forms, pre-decrement and post-decrement, depending on which side of the variable it appears on.
Operators – Spin Language Reference Increment, pre- or post- ‘+ +’ The Increment operator is a special, immediate operator that increments a variable by one and assigns the new value to that same variable. It can only be used in run-time variable expressions. Increment has two forms, pre-increment and post-increment, depending on which side of the variable it appears on. The pre-increment form appears to the left of a variable and the post-increment form appears to the right of a variable.
2: Spin Language Reference – Operators Multiply, Return Low ‘*’, ‘*=’ This operator is also called Multiply-Low, or simply Multiply. It can be used in both variable and constant expressions. When used with variable expressions or integer constant expressions, Multiply Low multiplies two values together and returns the lower 32 bits of the 64-bit result.
Operators – Spin Language Reference Divide ‘/’, ‘/=’ Divide can be used in both variable and constant expressions. When used with variable expressions or integer constant expressions, it divides one value by another and returns the 32-bit integer result. When used with floating-point constant expressions, it divides one value by another and returns the 32-bit single-precision floating-point result.
2: Spin Language Reference – Operators Limit Minimum ‘#>’, ‘#>=’ The Limit Minimum operator compares two values and returns the highest value. Limit Minimum can be used in both variable and constant expressions. Example: X := Y - 5 #> 100 The above example subtracts 5 from Y and limits the result to a minimum value to 100. If Y is 120 then 120 – 5 = 115; it is greater than 100 so X is set to 115. If Y is 102 then 102 – 5 = 97; it is less than 100 so X is set to 100 instead.
Operators – Spin Language Reference Square Root ‘^^’ The Square Root operator returns the square root of a value. Square Root can be used in both variable and constant expressions. When used with variable expressions or integer constant expressions, Square Root returns the 32-bit truncated integer result. When used with floating-point constant expressions, Square Root returns the 32-bit single-precision floatingpoint result.
2: Spin Language Reference – Operators Y := ~X + 25 The Sign-Extend 7 operator in this example extends the sign of the value, X in this case, from bit 7 up to bit 31. A 32-bit signed integer is stored in twos-complement form and the most significant bit (31) indicates the sign of the value (positive or negative). There may be times where calculations on simple data result in byte-sized values that should be treated as a signed integer in the range of -128 to +127.
Operators – Spin Language Reference times where calculations on simple data result in word-sized values that should be treated as a signed integer in the range of -32768 to +32767. When you need to perform further calculations with those word-sized values, use the Sign-Extend 15 operator to convert the number into the proper 32-bit signed integer form. In the above example, assume X represents the value -300, which in 16-bit twos-complement form is actually the value 65,236 (%11111110 11010100).
2: Spin Language Reference – Operators Here, the value of X is shifted right 2 bits, maintaining the sign, and the result is stored back in X. The assignment form of Shift Arithmetic Right may also be used within expressions for intermediate results; see Intermediate Assignments, page 147. Random ‘?’ The Random operator is a special, immediate operator that uses a variable’s value as a seed to create a pseudo random number and assigns that number to the same variable.
Operators – Spin Language Reference Bitwise Decode ‘|<’ The Bitwise Decode operator decodes a value (0 – 31) into a 32-bit long value with a single bit set high corresponding to the bit position of the original value. Bitwise Decode can be used in variable and integer constant expressions, but not in floating-point constant expressions. Example: Pin := |
2: Spin Language Reference – Operators Bitwise Shift Left ‘<<’, ‘<<=’ The Bitwise Shift Left operator shifts the bits of the first operand left by the number of bits indicated in the second operand. The original MSBs (leftmost bits) drop off and the new LSBs (rightmost bits) are set to zero. Bitwise Shift Left can be used in both variable and integer constant expressions, but not in floating-point constant expressions. Example: X := Y << 2 If Y started out as: %10000000 01110000 11111111 00110101 ...
Operators – Spin Language Reference Since the nature of binary is base-2, shifting a value right is like performing an integer divide of that value by powers of two, 2b, where b is the number of bits shifted. Bitwise Shift Right has an assignment form, >>=, that uses the variable to its left as both the first operand and the result destination. For example, X >>= 2 'Short form of X := X >> 2 Here, the value of X is shifted right two bits and is stored back in X.
2: Spin Language Reference – Operators X := Y -> 5 If Y started out as: %10000000 01110000 11111111 00110101 ...the Bitwise Rotate Right operator would rotate that value right by five bits, moving the original five LSBs to the five new MSBs, and setting X to: %10101100 00000011 10000111 11111001 Bitwise Rotate Right has an assignment form, ->=, that uses the variable to its left as both the first operand and the result destination.
Operators – Spin Language Reference Here, the eight LSBs of the value of X are reversed, all other bits are set to zero and the result is stored back in X. The assignment form of Bitwise Reverse may also be used within expressions for intermediate results; see Intermediate Assignments, page 147. Note that specifying 0 as the number of bits to reverse is the same as specifying 32.
2: Spin Language Reference – Operators Bitwise OR ‘|’, ‘|=’ The Bitwise OR operator performs a bitwise OR of the bits of the first operand with the bits of the second operand. Bitwise OR can be used in both variable and integer constant expressions, but not in floating-point constant expressions.
Operators – Spin Language Reference Table 2-13: Bitwise XOR Truth Table Bit States Result 0 0 0 0 1 1 1 0 1 1 1 0 Example: X := %00101100 ^ %00001111 The above example XORs %00101100 with %00001111 and writes the result, %00100011, to X. Bitwise XOR has an assignment form, ^=, that uses the variable to its left as both the first operand and the result destination. For example, X ^= $F 'Short form of X := X ^ $F Here, the value of X is XORed with $F and the result is stored back in X.
2: Spin Language Reference – Operators The above example NOTs %00101100 and writes the result, %11010011, to X. Bitwise NOT becomes an assignment operator when it is the sole operator to the left of a variable on a line by itself. For example: !Flag This would store the inverted value Flag back into Flag. Be careful not to get Bitwise NOT ‘!’confused with Boolean NOT ‘NOT’. Bitwise NOT is for bit manipulation while Boolean NOT is for comparison purposes (see page 168).
Operators – Spin Language Reference Be careful not to get Boolean AND ‘AND’ confused with Bitwise AND ‘&’. Boolean AND is for comparison purposes while Bitwise AND is for bit manipulation (see page 164). Boolean OR ‘OR’, ‘OR=’ The Boolean OR ‘OR’ operator compares two operands and returns TRUE (-1) if either value is TRUE (non-zero), or returns FALSE (0) if both operands are FALSE (0). Boolean OR can be used in both variable and constant expressions.
2: Spin Language Reference – Operators The above example returns the Boolean opposite of Y; TRUE (-1) if Y is zero, or FALSE (0) if Y is non-zero. During the comparison, it promotes the value of Y to -1 if it is non-zero, making any value, other than 0, a -1, so that the comparison becomes: “If NOT true” or “If NOT false” Quite often this operator is used in combination with other comparison operators, such as in the following example.
Operators – Spin Language Reference Here, X is compared with Y, and if they are equal, X is set to TRUE (-1), otherwise X is set to FALSE (0). The assignment form of Is Equal may also be used within expressions for intermediate results; see Intermediate Assignments, page 147. Boolean Is Not Equal ‘<>’, ‘<>=’ The Boolean operator Is Not Equal compares two operands and returns True (-1) if the values are not the same, or returns FALSE (0), otherwise.
2: Spin Language Reference – Operators Here, the Is Less Than operator returns TRUE if Y is less than 32. Is Less Than has an assignment form, <=, that uses the variable to its left as both the first operand and the result destination. For example, X <= Y 'Short form of X := X < Y Here, X is compared with Y, and if X is less than Y, X is set to TRUE (-1), otherwise X is set to FALSE (0).
Operators – Spin Language Reference The above example compares the value of Y with the value of Z and sets X to either: TRUE (-1) if Y is equal to or less than the value of Z, or FALSE (0) if Y is greater than the value of Z. This operator is often used in conditional expressions, such as in the following example. IF (Y =< 75) Here, the Is Equal or Less operator returns TRUE if Y is equal to or less than 75.
2: Spin Language Reference – Operators Symbol Address ‘@’ The Symbol Address operator returns the address of the symbol following it. Symbol Address can be used in variable and integer constant expressions, but not in floating-point constant expressions. Example: BYTE[@Str] := "A" In the above example, the Symbol Address operator returns the address of the Str symbol, which is then used by the BYTE memory array reference to store the character "A" at that address.
Operators – Spin Language Reference At run time we can access those strings directly, using @Str1, @Str2, and @Str3, but accessing them indirectly is troublesome because each string is of a different length; making it difficult to use any of them as a base for indirect address calculations.
2: Spin Language Reference – OUTA, OUTB OUTA, OUTB Register: Output registers for 32-bit Ports A and B. ((PUB ┆ PRI)) OUTA 〈[Pin(s)]〉 ((PUB ┆ PRI)) OUTB 〈[Pin(s)]〉 (Reserved for future use) Returns: Current value of output Pin(s) for Port A or B, if used as a source variable. • Pin(s) is an optional expression, or a range-expression, that specifies the I/O pin, or pins, to access in Port A (0-31) or Port B (32-63). If given as a single expression, only the pin specified is accessed.
OUTA, OUTB – Spin Language Reference Note that each cog’s output states are made up of the OR’d states of its internal I/O hardware (Output Register, Video Generator, etc.) and that is all AND’d with its Direction Register’s states. An I/O pin actually outputs low or high, as specified by the cog’s output states, if, and only if, that pin’s bit in that same cog’s direction register (DIRA) is high (1). Otherwise, that cog specifies the pin to be an input and its output state is ignored.
2: Spin Language Reference – OUTA, OUTB The first line in the code above sets I/O pin 10 to output. The second line clears P10’s output latch bit, making P10 output low (ground). The third line sets P10’s output latch bit, making P10 output high (VDD). In Spin, the OUTA register supports a special form of expression, called a range-expression, which allows you to affect a group of I/O pins at once, without affecting others outside the specified range.
PAR – Spin Language Reference PAR Register: Cog Boot Parameter register. ((PUB ┆ PRI)) PAR Returns: Address value passed during launch of assembly code with COGINIT or COGNEW. Explanation The PAR register contains the address value passed into the Parameter field of a COGINIT or COGNEW command; see COGINIT, page 76 and COGNEW, page 78. The PAR register’s contents are used by Propeller Assembly code to locate and operate on memory shared between Spin code and assembly code.
2: Spin Language Reference – PAR In the example above, the Main method launches the Process assembly routine into a new cog with COGNEW. The second parameter of COGNEW is used by Main to pass the address of a variable, Shared. The assembly routine, Process, retrieves that address value from its PAR register and stores it locally in Mem. Then it performs some task, updating its local ValReg register (created at the end of the DAT block) and finally updates the Shared variable via wrlong ValReg, Mem.
PHSA, PHSB – Spin Language Reference PHSA, PHSB Register: Counter A and Counter B Phase Registers. ((PUB ┆ PRI)) PHSA ((PUB ┆ PRI)) PHSB Returns: Current value of Counter A or Counter B Phase Register, if used as a source variable. Explanation PHSA and PHSB are two of six registers (CTRA, CTRB, FRQA, FRQB, PHSA, and PHSB) that affect the behavior of a cog’s Counter Modules. Each cog has two identical counter modules (A and B) that can perform many repetitive tasks.
2: Spin Language Reference – PRI PRI Designator: Declare a Private Method Block. ((PUB ┆ PRI)) PRI Name 〈(Param 〈, Param〉…)〉 〈:RValue〉 〈| LocalVar 〈[Count]〉〉 〈,LocalVar 〈[Count]〉〉… SourceCodeStatements • • • • • • Name is the desired name for the private method. Param is a parameter name (optional). Methods can contain zero or more comma- delimited parameters, enclosed in parentheses. Param must be globally unique, but other methods may also use the same symbol name.
PUB – Spin Language Reference PUB Designator: Declare a Public Method Block. ((PUB ┆ PRI)) PUB Name 〈(Param 〈,Param〉…)〉 〈:RValue〉 〈| LocalVar 〈[Count ]〉〉 〈,LocalVar 〈[Count ]〉〉… SourceCodeStatements • • • • • • Name is the desired name for the public method. Param is a parameter name (optional). Methods can contain zero or more comma- delimited parameters, enclosed in parentheses. Param must be globally unique, but other methods may also use the same symbol name.
2: Spin Language Reference – PUB Public Method Declaration Public Method declarations begin with PUB, in column 1 of a line, followed a unique name and an optional set of parameters, a result variable, and local variables.
PUB – Spin Language Reference Parameters and Local Variables Parameters and local variables are all longs (four bytes). In fact, parameters are really just variables that are initialized to the corresponding values specified by the caller of the method. Local variables, however, are not initialized; they contain random data whenever the method is called. All parameters are passed into a method by value, not by reference, so any changes to the parameters themselves are not reflected outside of the method.
2: Spin Language Reference – PUB there is no way to pass them to a method by value; doing so would result in the method receiving only the first character. Even if a method does not need to modify a string, or other logical array, the array in question still needs to be passed by reference because there are multiple elements to be accessed.
QUIT – Spin Language Reference QUIT Command: Exit from REPEAT loop immediately. T ((PUB ┆ PRI)) QUIT Explanation QUIT is one of two commands (NEXT and QUIT) that affect REPEAT loops. QUIT causes a REPEAT loop to terminate immediately. T T Using QUIT QUIT is typically used as an exception case, in a conditional statement, in REPEAT loops to terminate the loop prematurely.
2: Spin Language Reference – REBOOT REBOOT Command: Reset the Propeller chip. ((PUB ┆ PRI)) REBOOT Explanation This is a software controlled reset, but acts like just like a hardware reset via the RESn pin. Use REBOOT if you want to reset the Propeller chip to its power-up state. All the same hardware-based, power-up/reset delays, as well as the boot-up processes, are applied as if the Propeller had been reset via the RESn pin or a power cycle. T Propeller Manual v1.
REPEAT – Spin Language Reference REPEAT Command: Execute code block repetitively. ((PUB ┆ PRI)) REPEAT 〈Count〉 Statement(s) ((PUB ┆ PRI)) REPEAT Variable FROM Start TO Finish 〈STEP Delta〉 Statement(s) ((PUB ┆ PRI)) REPEAT (( UNTIL┆ WHILE )) Condition(s) Statement(s) ((PUB ┆ PRI)) REPEAT Statement(s) ((UNTIL┆ WHILE)) Condition(s) • • • • • • Count is an optional expression indicating the finite number of times to execute Statement(s).
2: Spin Language Reference – REPEAT • Condition(s) is one or more Boolean expression(s) used by syntax 3 and 4 to continue or terminate the loop. When preceded by UNTIL, Condition(s) terminates the loop when true. When preceded by WHILE, Conditions(s) terminates the loop when FALSE. Explanation REPEAT is the very flexible looping structure for Spin code. It can be used to create any type of loop, including: infinite, finite, with/without loop counter, and conditional zero-tomany/one-to-many loops.
REPEAT – Spin Language Reference Simple Finite Loops (Syntax 1) Most loops are finite in nature; they execute a limited number of iterations only. The simplest form is syntax 1 with the Count field included. For example: repeat 10 !outa[25] byte[$7000]++ 'Repeat 10 times 'Toggle P25 'Increment RAM location $7000 The above code toggles P25 ten times, then increments the value in RAM location $7000.
2: Spin Language Reference – REPEAT The REPEAT command automatically determines whether the range suggested by Start and Finish is increasing or decreasing. Since the above example used 0 to 9, the range is an increasing range; adjusting Index by +1 every time.
REPEAT – Spin Language Reference byte[$7000][Index]++ 'Increment even RAM $7000 to $7008 Here, REPEAT loops five times, with Index set to 0, 2, 4, 6, and 8, respectively. This code effectively increments every other RAM location (the even numbered locations) from $7000 to $7008 and terminates with Index equaling 10.
2: Spin Language Reference – REPEAT After the 10th iteration of the loop, X equals 10, making the condition while X < 10 false and the loop terminates. This loop is said to use “positive” logic because it continues “WHILE” a condition is true. It could also be written with “negative” logic using UNTIL, instead.
RESULT – Spin Language Reference RESULT Variable: The return value variable for methods. ((PUB ┆ PRI)) RESULT Explanation The RESULT variable is a pre-defined local variable for each PUB and PRI method. RESULT holds the method’s return value; the value passed back to the caller of the method, when the method is terminated. T When a public or private method is called, its built-in RESULT variable is initialized to zero (0).
2: Spin Language Reference – RESULT also used “result := …” to set the return value since either statement affects the method’s return value. Either the RESULT variable, or the alias provided for it, may be modified multiple times within the method before exiting since they both affect RESULT and only the last value of RESULT will be used upon exiting. T Propeller Manual v1.
RETURN – Spin Language Reference RETURN Command: Exit from PUB/PRI method with optional return Value. ((PUB ┆ PRI)) RETURN 〈Value〉 Returns: Either the current RESULT value, or Value if provided. • Value is an optional expression whose value is to be returned from the PUB or PRI method. Explanation RETURN is one of two commands (ABORT and RETURN) that terminate a PUB or PRI method’s execution.
2: Spin Language Reference – RETURN Using RETURN The following example demonstrates two uses DisplayDivByZeroError is a method defined elsewhere. PUB Add(Num1, Num2) Result := Num1 + Num2 return PUB Divide(Dividend, Divisor) if Divisor == 0 DisplayDivByZeroError return 0 return Dividend / Divisor of RETURN.
ROUND – Spin Language Reference ROUND Directive: Round a floating-point constant to the nearest integer. ((CON ┆ VAR ┆ OBJ ┆ PUB ┆ PRI ┆ DAT)) ROUND ( FloatConstant ) Returns: Nearest integer to original floating-point constant value. • FloatConstant is the floating-point constant expression to be rounded to the nearest integer. Explanation ROUND is one of three directives (FLOAT, ROUND and TRUNC) used for floating-point constant expressions.
2: Spin Language Reference – ROUND a 1-bit sign, an 8-bit exponent, and a 23-bit mantissa (the fractional part). This provides approximately 7.2 significant decimal digits. Floating-point constant expressions can be defined and used for many compile-time purposes, but for run-time floating-point operations, the FloatMath and FloatString objects provide math functions compatible with single-precision numbers.
SPR – Spin Language Reference SPR Register: Special Purpose Register array; provides indirect access to cog’s special registers. ((PUB ┆ PRI)) SPR [Index] Returns: Value in special purpose register at Index. • Index is an expression that specifies the index (0-15) of the special purpose register to access (PAR through VSCL). Explanation SPR is an array of the 16 special purpose registers in the cog. Element 0 is the PAR register and element 15 is the VSCL register. See Table 2-15 below.
2: Spin Language Reference – SPR Using SPR SPR can be used like any other long-sized array. The following assumes Temp is a variable defined elsewhere. spr[4] := %11001010 Temp := spr[2] 'Set outa register 'Get ina value This example sets the OUTA register (index 4 of SPR) to %11001010 and then sets Temp equal to the INA register (index 2 of SPR). Propeller Manual v1.
_STACK – Spin Language Reference _STACK Constant: Pre-defined, one-time settable constant for specifying the size of an application’s stack space. CON _STACK = Expression • Expression is an integer expression that indicates the number of longs to reserve for stack space. Explanation _STACK is a pre-defined, one-time settable optional constant that specifies the required stack space of an application.
2: Spin Language Reference – STRCOMP STRCOMP Command: Compare two strings for equality. ((PUB ┆ PRI)) STRCOMP (StringAddress1, StringAddress2 ) Returns: TRUE if both strings are equal, FALSE otherwise. • • StringAddress1 is an expression specifying the starting address of the first string to compare. StringAddress2 is an expression specifying the starting address of the second string to compare. Explanation STRCOMP is one of two commands (STRCOMP and STRSIZE) that retrieve information about a string.
STRCOMP – Spin Language Reference Zero-Terminated Strings The STRCOMP command requires the strings being compared to be zero-terminated; a byte equal to 0 must immediately follow each string. This practice is quite common and is recommended since most string-handling methods rely on zero terminators. Page 204 · Propeller Manual v1.
2: Spin Language Reference – STRING STRING Directive: Declare in-line string constant and get its address. ((PUB ┆ PRI)) STRING (StringExpression ) Returns: Address of in-line string constant. • StringExpression is the desired string expression to be used for temporary, in-line purposes.
STRSIZE – Spin Language Reference STRSIZE Command: Get size of string. ((PUB ┆ PRI)) STRSIZE ( StringAddress ) Returns: Size (in bytes) of zero-terminated string. • StringAddress is an expression specifying the starting address of the string to measure. Explanation STRSIZE is one of two commands (STRCOMP and STRSIZE) that retrieve information about a string. STRSIZE measures the length of a string at StringAddress, in bytes, up to, but not including, a zero-termination byte.
2: Spin Language Reference – Symbols Symbols The symbols in Table 2-16 below serve one or more special purposes in Spin code. For Propeller Assembly symbols, see Symbols, page 360. Each symbol’s purpose is described briefly with references to other sections that describe it directly or use it in examples. Table 2-16: Symbols Symbol Purpose(s) % Binary indicator: used to indicate that a value is being expressed in binary (base-2). See Value Representations on page 45.
Symbols – Spin Language Reference Table 2-16: Symbols (continued) Symbol Purpose(s) 1) Return value separator: appears immediately before a symbolic return value on a PUB or PRI declaration. See PUB on page 182, PRI on page 181, and RESULT on page 194. Object assignment: appears in an object reference declaration in an OBJ block. See OBJ, page 141. Case statement separator: appears immediately after the match expressions in a CASE structure. See CASE, page 59. T : 2) 3) | \ 1) 2) Local variable separa
2: Spin Language Reference – TRUNC TRUNC Directive: Remove, “truncate,” the fractional portion from a floating-point constant. ((CON ┆ VAR ┆ OBJ ┆ PUB ┆ PRI ┆ DAT)) TRUNC ( FloatConstant ) Returns: Integer that is the given floating-point constant value truncated at the decimal point. • FloatConstant is the floating-point constant expression to be truncated to an integer. Explanation TRUNC is one of three directives (FLOAT, ROUND and TRUNC) used for floating-point constant expressions.
VAR – Spin Language Reference VAR Designator: Declare a Variable Block. VAR Size Symbol 〈[Count ]〉 〈 Size Symbol 〈 [Count ]〉〉... VAR Size Symbol 〈[Count ]〉 〈 , Symbol 〈 [Count ]〉〉... • • • Size is the desired size of the variable, BYTE, WORD or LONG. Symbol is the desired name for the variable. Count is an optional expression, enclosed in brackets, that indicates this is an array variable, with Count number of elements; each being of size byte, word or long.
2: Spin Language Reference – VAR PUB SomeMethod Code := 60000 LargeNumber := Code * 250 GetString(@Str) if Str[0] == "A" Notice that Code and LargeNumber are used directly by expressions. The Str reference in the GetString method’s parameter list looks different; it has an @, the Symbol Address operator, preceding it. This is because our fictitious GetString method needs to write back to the Str variable.
VAR – Spin Language Reference Organization of Variables During compilation of an object, all declarations in its collective VAR blocks are grouped together by type. The variables in RAM are arranged with all the longs first, followed by all words, and finally by all bytes. This is done so that RAM space is allocated efficiently without unnecessary gaps. Keep this in mind when writing code that accesses variables indirectly based on relative positions to each other.
2: Spin Language Reference – VCFG VCFG Register: Video Configuration Register. ((PUB ┆ PRI)) VCFG Returns: Current value of cog’s Video Configuration Register, if used as a source variable. Explanation VCFG is one of two registers (VCFG and VSCL) that affect the behavior of a cog’s Video Generator. Each cog has a video generator module that facilitates transmitting video image data at a constant rate. The VCFG register contains the configuration settings of the video generator, as shown in Table 2-17.
VCFG – Spin Language Reference CMode The CMode (color mode) field selects two or four color mode. 0 = two-color mode; pixel data is 32 bits by 1 bit and only colors 0 or 1 are used. 1 = four-color mode; pixel data is 16 bits by 2 bits, and colors 0 through 3 are used. Chroma1 The Chroma1 (broadcast chroma) bit enables or disables chroma (color) on the broadcast signal. 0 = disabled, 1 = enabled. Chroma0 The Chroma0 (baseband chroma) bit enables or disables chroma (color) on the baseband signal.
2: Spin Language Reference – VCFG VGroup The VGroup (video output pin group) field selects which group of eight I/O pins to output video on. Table 2-20: The VGroup Field VGroup 000 001 010 011 100-111 Pin Group Group 0: P7..P0 Group 1: P15..P8 Group 2: P23..P16 Group 3: P31..P24 VPins The VPins (video output pins) field is a mask applied to the pins of VGroup that indicates which pins to output video signals on.
VCSL – Spin Language Reference VSCL Register: Video Scale Register. ((PUB ┆ PRI)) VSCL Returns: Current value of cog’s Video Scale Register, if used as a source variable. Explanation VSCL is one of two registers (VCFG and VSCL) that affect the behavior of a cog’s Video Generator. Each cog has a video generator module that facilitates transmitting video image data at a constant rate. The VSCL register sets the rate at which video data is generated. Table 2-22: VSCL Register 31..20 − VSCL Bits 19..
2: Spin Language Reference – VSCL This sets the video scale register for 160 PixelClocks and 2,560 FrameClocks (for a 16-pixel by 2-bit color frame). Of course, the actual rate at which pixels clock out depends on the frequency of PLLA in combination with this scale factor. Propeller Manual v1.
WAITCNT – Spin Language Reference WAITCNT Command: Pause a cog’s execution temporarily. ((PUB ┆ PRI)) WAITCNT ( Value ) • Value is the desired 32-bit System Counter value to wait for. Explanation WAITCNT, “Wait for System Counter,” is one of four wait commands (WAITCNT, WAITPEQ, WAITPNE, and WAITVID) used to pause execution of a cog until a condition is met. WAITCNT pauses the cog until the global System Counter equals Value.
2: Spin Language Reference – WAITCNT This code toggles the state of I/O pin P0 and waits for 50,000 system clock cycles before repeating the loop again. Remember, the Value parameter must be the desired 32-bit value to match against the System Clock’s value. Since the System Clock is a global resource that changes every clock cycle, to delay for a certain number of cycles from “now” we need a value that is added to the current System Counter value.
WAITCNT – Spin Language Reference Figure 2-3: Fixed Delay Timing Figure 2-3 shows the output of our previous example, the fixed delay example. Notice how the I/O pin P0 toggles roughly every 10 milliseconds, but not exactly? In fact, there’s a cumulative error that makes successive state changes further and further out-of-sync in relation to our start time, 0 ms. The delay is 10 ms in length, but the error occurs because that delay doesn’t compensate for the length of the rest of the loop.
2: Spin Language Reference – WAITCNT the overhead time consumed by the loop statements: repeat, !outa[0] and waitcnt. The resulting output looks like Figure 2-4. Figure 2-4: Synchronized Delay Timing Using the synchronized delay method, our output signal is always perfectly aligned to the time base plus a multiple of our interval. This will work as long as the time base (an external crystal) is accurate and the overhead in the loop does not exceed the time interval itself.
WAITPEQ – Spin Language Reference WAITPEQ Command: Pause a cog’s execution until I/O pin(s) match designated state(s). ((PUB ┆ PRI)) WAITPEQ (State, Mask, Port ) • • • State is the logic state(s) to compare the pin(s) against. It is a 32-bit value that indicates the high or low states of up to 32 I/O pins. State is compared against either (INA & Mask), or (INB & Mask), depending on Port. Mask is the desired pin(s) to monitor.
2: Spin Language Reference – WAITPEQ Using Variable Pin Numbers For Propeller objects, quite often it is necessary to monitor a single pin whose pin number is specified outside the object itself. An easy way to translate that pin number into the proper 32-bit State and Mask value is by using the Bitwise Decode operator “|<” (See 160 for more information).
WAITPNE – Spin Language Reference WAITPNE Command: Pause a cog’s execution until I/O pin(s) do not match designated state(s). ((PUB ┆ PRI)) WAITPNE (State, Mask, Port ) • • • State is the logic state(s) to compare the pins against. It is a 32-bit value that indicates the high or low states of up to 32 I/O pins. State is compared against either (INA & Mask), or (INB & Mask), depending on Port. Mask is the desired pin(s) to monitor.
2: Spin Language Reference – WAITVID WAITVID Command: Pause a cog’s execution until its Video Generator is available to take pixel data. ((PUB ┆ PRI)) WAITVID (Colors, Pixels ) • • Colors is a long containing four byte-sized color values, each describing the four possible colors of the pixel patterns in Pixels. Pixels is the next 16-pixel by 2-bit (or 32-pixel by 1-bit) pixel pattern to display.
WAITVID – Spin Language Reference Pixels describes the pixel pattern to display, either 16 pixels or 32 pixels depending on the color-depth configuration of the Video Generator. Review the TV and VGA objects for examples of how WAITVID is used. Make sure to start the cog’s Video Generator module and Counter A before executing the WAITVID command or it will wait forever. See VCFG on page 213, VSCL on page 216, and CTRA, CTRB on page 95. Page 226 · Propeller Manual v1.
2: Spin Language Reference – WORD WORD Designator: Declare word-sized symbol, word aligned/sized data, or read/write a word of main memory. VAR WORD Symbol 〈[Count ]〉 DAT 〈Symbol〉 WORD Data 〈[Count]〉 ((PUB ┆ PRI)) WORD [BaseAddress] 〈[Offset ]〉 ((PUB ┆ PRI)) Symbol.WORD 〈[Offset ]〉 • • • • • Symbol is the desired name for the variable (Syntax 1) or data block (Syntax 2) or is the existing name of the variable (Syntax 4).
WORD – Spin Language Reference Range of Word Memory that is word-sized (16 bits) can contain a value that is one of 216 possible combinations of bits (i.e., one of 65,536 combinations). This gives word-sized values a range of 0 to 65,535. Since the Spin language performs all mathematic operations using 32-bit signed math, any word-sized values will be internally treated as positive long-sized values.
2: Spin Language Reference – WORD Word Data Declaration (Syntax 2) In DAT blocks, syntax 2 of WORD is used to declare word-aligned, and/or word-sized data that is compiled as constant values in main memory. DAT blocks allow this declaration to have an optional symbol preceding it, which can be used for later reference. See DAT, page 99.
WORD – Spin Language Reference DAT MyData MyList word byte 640, $AAAA, 5_500 word $FF99, word 1_000 'Word-sized/aligned data 'Byte-sized/aligned word data In this example, the DAT block (bottom of code) places its data in memory as shown in Figure 2-5. The first data element of MyData is placed at memory address $18. The last data element of MyData is placed at memory address $1C, with the first element of MyList immediately following it at $1E.
2: Spin Language Reference – WORD Addressing Main Memory As Figure 2-5 suggests, main memory is really just a set of contiguous bytes (see “data as bytes” row) that can also be read as words (2-byte pairs) when done properly. In fact, the above example shows that even the addresses are calculated in terms of bytes. This concept is a consistent theme for any commands that use addresses.
WORD – Spin Language Reference Temp := MyData[1] Temp := MyData[2] So why wouldn’t you just use direct symbol references all the time? Consider the following case: Temp := MyList[0] Temp := MyList[1] Referring back to the example code above Figure 2-5, you might expect these two statements to read the first and second words of MyList; $FF99 and 1000, respectively. Instead, it reads the first and second “bytes” of MyList, $99 and $FF, respectively.
2: Spin Language Reference – WORD Accessing Words of Larger-Sized Symbols (Syntax 4) In PUB and PRI blocks, syntax 4 of WORD is used to read or write word-sized components of long-sized variables. For example: VAR long LongVar PUB Main LongVar.word := 65000 LongVar.word[0] := 65000 LongVar.word[1] := 1 'Set first word of LongVar to 65000 'Same as above 'Set second word of LongVar to 1 This example accesses the word-sized components of LongVar, individually.
WORDFILL – Spin Language Reference WORDFILL Command: Fill words of main memory with a value. ((PUB ┆ PRI)) WORDFILL (StartAddress, Value, Count ) • • • StartAddress is an expression indicating the location of the first word of memory to fill with Value. Value is an expression indicating the value to fill words with. Count is an expression indicating the number of words to fill, starting with StartAddress.
2: Spin Language Reference – WORDMOVE WORDMOVE Command: Copy words from one region to another in main memory. ((PUB ┆ PRI)) WORDMOVE (DestAddress, SrcAddress, Count ) • DestAddress is an expression specifying the main memory location to copy the first • SrcAddress is an expression specifying the main memory location of the first word of • source to copy. Count is an expression indicating the number of words of the source to copy to the destination. word of source to.
_XINFREQ – Spin Language Reference _XINFREQ Constant: Pre-defined, one-time settable constant for specifying the external crystal frequency. CON _XINFREQ = Expression • Expression is an integer expression that indicates the external crystal frequency; the frequency on the XI pin. This value is used for application start-up. Explanation _XINFREQ specifies the external crystal frequency, which is used along with the clock mode to determine the System Clock frequency at start-up.
2: Spin Language Reference – _XINFREQ CON _CLKMODE = XTAL2 _XINFREQ = 10_000_000 These two declarations set the clock mode for an external medium-speed crystal, no Clock PLL multiplier, and an external crystal frequency of 10 MHz. The _CLKFREQ value, and thus the System Clock frequency, is automatically set to 10 MHz, as well, because of these declarations. Propeller Manual v1.
Assembly Language Reference Chapter 3: Assembly Language Reference This chapter describes all elements of the Propeller chip’s Assembly language and is best used as a reference for individual elements of the assembly language. Many instructions have corresponding Spin commands so referring to the Spin Language Reference is also recommended. The Assembly Language Reference is divided into three main sections: 1) The Structure of Propeller Assembly.
3: Assembly Language Reference 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. T {{ AssemblyToggle.
Assembly Language Reference application data after that, whether or not it is required by the code. See the sections discussing ORG (page 328), RES (page 339), and DAT (page 99) for more information. T Cog Memory Cog RAM is similar to Main RAM in the following ways: • Each can contain program instruction(s) and/or data. • Each can be modified at run-time (example: variables occupy RAM locations). Cog RAM is different from Main RAM in the following ways: • Cog RAM is smaller and faster than Main RAM.
3: Assembly Language Reference add add X Y long long X, #25 X, Y 'Add 25 to X 'Add Y to X 50 10 The first instruction adds the literal value 25 to the value stored in the register X. The second instruction adds the value stored in register Y to the value stored in the register X. In both cases, the result of the addition is stored back into register X. The last two lines define data symbols X and Y as long values 50 and 10, respectively.
Assembly Language Reference Global and Local Labels To give names to special routines, Propeller Assembly code can make use of two types of labels: global and local. Global labels look just like other symbols and follow the same rules as symbols; they begin with an underscore ‘_’ or a letter and are followed by more letters, underscores, and/or numbers. See Symbol Rules, page 45, for more information.
3: Assembly Language Reference Categorical Listing of Propeller Assembly Language Directives ORG FIT RES Adjust compile-time cog address pointer; p 328. Validate that previous instructions/data fit entirely in cog; p 292. Reserve next long(s) for symbol; p 338. Configuration CLKSETs Set clock mode at run time; p 271. Cog Control COGIDs COGINITs COGSTOPs Get current cog’s ID; p 283. Start, or restart, a cog by ID; p 284. Stop a cog by ID; p 286.
Assembly Language Reference IF_B IF_AE IF_BE IF_C IF_NC IF_Z IF_NZ IF_C_EQ_Z IF_C_NE_Z IF_C_AND_Z IF_C_AND_NZ IF_NC_AND_Z IF_NC_AND_NZ IF_C_OR_Z IF_C_OR_NZ IF_NC_OR_Z IF_NC_OR_NZ IF_Z_EQ_C IF_Z_NE_C IF_Z_AND_C IF_Z_AND_NC IF_NZ_AND_C IF_NZ_AND_NC IF_Z_OR_C IF_Z_OR_NC IF_NZ_OR_C IF_NZ_OR_NC If below (C = 1); p 296. If above or equal (C = 0); p 296. If below or equal (C | Z = 1); p 296. If C set; p 296. If C clear; p 296. If Z set; p296. If Z clear; p 296. If C equal to Z; p 296. If C not equal to Z; p 296.
3: Assembly Language Reference Flow Control CALL DJNZ JMP JMPRET TJNZ TJZ RET Jump to address with intention to return to next instruction; p 268. Decrement value and jump to address if not zero; p 290. Jump to address unconditionally; p 298. Jump to address with intention to “return” to another address; p 300. Test value and jump to address if not zero; p 362. Test value and jump to address if zero; p 365. Return to stored address; p 342. Effects NR WR WC WZ No result (don’t write result); p 291.
Assembly Language Reference NEGNZ MIN MINS MAX MAXS ADD ADDABS ADDS ADDX ADDSX SUB SUBABS SUBS SUBX SUBSX SUMC SUMNC SUMZ SUMNZ MUL MULS AND ANDN OR XOR ONES ENC RCL RCR REV ROL Get a value, or its additive inverse, based on !Z; p 322. Limit minimum of unsigned value to another unsigned value; p 309. Limit minimum of signed value to another signed value; p 310. Limit maximum of unsigned value to another unsigned value; p 307. Limit maximum of signed value to another signed value; p 308.
3: Assembly Language Reference ROR SHL SHR SAR CMP CMPS CMPX CMPSX CMPSUB TEST TESTN MOV MOVS MOVD MOVI MUXC MUXNC MUXZ MUXNZ HUBOP NOP Rotate value right by specified number of bits; p 345. Shift value left by specified number of bits; p 347. Shift value right by specified number of bits; p 348. Shift value arithmetically right by specified number of bits; p 346. Compare two unsigned values; p 272. Compare two signed values; p 274. Compare two unsigned values plus C; p 280.
Assembly Language Reference Registers DIRAs DIRBs INAs INBs OUTAs OUTBs CNTs CTRAs CTRBs FRQAs FRQBs PHSAs PHSBs VCFGs VSCLs PARs Direction Register for 32-bit port A; p 338. Direction Register for 32-bit port B (future use); p 338. Input Register for 32-bit port A (read only); p 338. Input Register for 32-bit port B (read only) (future use); p 338. Output Register for 32-bit port A; p 338. Output Register for 32-bit port B (future use); p 338. 32-bit System Counter Register (read only); p 338.
3: Assembly Language Reference Binary Operators NOTE: All operators shown are constant expression operators. + Add; p 326. Subtract; p 326. * Multiply and return lower 32 bits (signed); p 326. ** Multiply and return upper 32 bits (signed); p 326. / Divide and return quotient (signed); p 326. // Divide and return remainder (signed); p 326. #> Limit minimum (signed); p 326. <# Limit maximum (signed); p 326. ~> Shift arithmetic right; p 326. << Bitwise: Shift left; p 326. >> Bitwise: Shift right; p 326.
Assembly Language Reference Assembly Language Elements Syntax Definitions In addition to detailed descriptions, the following pages contain syntax definitions for many elements that describe, in short terms, all the options of that element. The syntax definitions use special symbols to indicate when and how certain element features are to be used. BOLDCAPS Items in bold uppercase should be typed in exactly as shown.
3: Assembly Language Reference flag, and to write, or not write, the instruction’s result value to the destination register, respectively. See Effects on page 291 for more information. Since every instruction can include these three optional fields (Label, Condition, and Effects), for simplicity those common fields are intentionally left out of the instruction’s syntax description. So, when you read a syntax description such as this: WAITCNT Target, 〈#〉 Delta ...
Assembly Language Reference are set (1) if the instruction was specified with a WZ and/or WC effect. See Effects on page 291. The R bit’s default state depends on the type of instruction, but is also affected if the instruction was specified with the WR or NR effect. The I field’s default state depends on the type of instruction and is affected by the inclusion, or lack of, the literal indicator (#) in the instruction’s source field.
3: Assembly Language Reference ADDS Truth Table: In Destination Source Z C Effects $FFFF_FFFF; -1 $FFFF_FFFF; -1 $0000_0001; $0000_0002; 1 2 - - wz wc $0000_0001; $0000_0001; $FFFF_FFFF; -1 $FFFF_FFFE; -2 - - wz wc $0000_0001; $0000_0002; 1 2 - - wz wc $FFFF_FFFF; -1 $FFFF_FFFE; -2 - - wz wc $7FFF_FFFE; $7FFF_FFFE; 1 1 2,147,483,646 2,147,483,646 $8000_0001; -2,147,483,647 $8000_0001; -2,147,483,647 wz wc wz wc wz wc wz wc Out Destination $0000_0000; $0000_0001; Z C 0 1 1 0 0
Assembly Language Reference Z Result C Result Result Clocks ABS Instruction D, S -INSTR- ZCRI -CON- 101010 001i 1111 ddddddddd sssssssss -DEST- Result = 0 S[31] Written 4 ABSNEG D, S 101011 001i 1111 ddddddddd sssssssss Result = 0 S[31] Written 4 ADD D, S 100000 001i 1111 ddddddddd sssssssss D+S=0 Unsigned Carry Written 4 ADDABS D, S 100010 001i 1111 ddddddddd sssssssss D + |S| = 0 Unsigned Carry 3 Written 4 ADDS D, S 110100 001i 1111 ddddddddd sssssssss D+S=0 Signed Ov
3: Assembly Language Reference Instruction -INSTR- ZCRI -CON- -DEST- -SRC- Z Result C Result Result Clocks NEGC D, S 101100 001i 1111 ddddddddd sssssssss Result = 0 S[31] Written 4 NEGNC D, S 101101 001i 1111 ddddddddd sssssssss Result = 0 S[31] Written 4 NEGNZ D, S 101111 001i 1111 ddddddddd sssssssss Result = 0 S[31] Written 4 NEGZ D, S 101110 001i 1111 ddddddddd sssssssss Result = 0 S[31] Written 4 ------ ---- 0000 --------- --------- --- --- --- 4 NOP OR D, S 0
Assembly Language Reference Notes for Master Table Note 1: Clock Cycles for Hub Instructions Hub instructions require 7 to 22 clock cycles to execute depending on the relation between the cog’s hub access window and the instruction’s moment of execution. The Hub provides a hub access window to each cog every 16 clocks. Because each cog runs independently of the Hub, it must sync to the Hub when executing a hub instruction.
3: Assembly Language Reference – ABS ABS Instruction: Get the absolute value of a number. ABS AValue, 〈#〉 SValue Result: Absolute SValue is stored in AValue. • • AValue (d-field) is the register in which to write the absolute of SValue. SValue (s-field) is a register or a 9-bit literal whose absolute value will be written to AValue.
ABSNEG – Assembly Language Reference ABSNEG Instruction: Get the negative of a number’s absolute value. ABSNEG NValue, 〈#〉 SValue Result: Absolute negative of SValue is stored in NValue. • NValue (d-field) is the register in which to write the negative of SValue’s absolute • SValue (s-field) is a register or a 9-bit literal whose absolute negative value will be value. written to NValue.
3: Assembly Language Reference – ADD ADD Instruction: Add two unsigned values. ADD Value1, 〈#〉 Value2 Result: Sum of unsigned Value1 and unsigned Value2 is stored in Value1. • • Value1 (d-field) is the register containing the value to add to Value2 and is the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value is added into Value1.
ADDABS – Assembly Language Reference ADDABS Instruction: Add an absolute value to another value. ADDABS Value, 〈#〉 SValue Result: Sum of Value and absolute of signed SValue is stored in Value. • • Value (d-field) is the register containing the value to add to the absolute of SValue and is the destination in which to write the result. SValue (s-field) is a register or a 9-bit literal whose absolute value is added into Value.
3: Assembly Language Reference – ADDS ADDS Instruction: Add two signed values. ADDS SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and signed SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to add to SValue2 and is the • SValue2 (s-field) is a register or a 9-bit literal whose value is added into SValue1. destination in which to write the result.
ADDSX – Assembly Language Reference ADDSX Instruction: Add two signed values plus C. ADDSX SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and signed SValue2 plus C flag is stored in SValue1. • SValue1 (d-field) is the register containing the value to add to SValue2 plus C, and is • SValue2 (s-field) is a register or a 9-bit literal whose value plus C is added into the destination in which to write the result. SValue1.
3: Assembly Language Reference – ADDSX In a signed multi-long operation, the first instruction is unsigned (ex: ADD), any middle instructions are unsigned, extended (ex: ADDX), and the last instruction is signed, extended (ex: ADDSX). Make sure to use the WC, and optionally WZ, effect on the leading ADD and ADDX instructions.
ADDX – Assembly Language Reference ADDX Instruction: Add two unsigned values plus C. ADDX Value1, 〈#〉 Value2 Result: Sum of unsigned Value1 and unsigned Value2 plus C flag is stored in Value1. • • Value1 (d-field) is the register containing the value to add to Value2 plus C, and is the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value plus C is added into Value1.
3: Assembly Language Reference – ADDX After executing the above, the double-long (64-bit) result is in the long registers XHigh:XLow. If XHigh:XLow started out as $0000_0000:FFFF_FFFF (4,294,967,295) and YHigh:YLow was $0000_0000:0000_0001 (1) the result in XHigh:XLow would be $0000_0001:0000_0000 (4,294,967,296). This is demonstrated below.
AND – Assembly Language Reference AND Instruction: Bitwise AND two values. AND Value1, 〈#〉 Value2 Result: Value1 AND Value2 is stored in Value1. • • Value1 (d-field) is the register containing the value to bitwise AND with Value2 and is the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value is bitwise ANDed with Value1.
3: Assembly Language Reference – ANDN ANDN Instruction: Bitwise AND a value with the NOT of another. ANDN Value1, 〈#〉 Value2 Result: Value1 AND !Value2 is stored in Value1. • • Value1 (d-field) is the register containing the value to bitwise AND with !Value2 and is the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value is inverted (bitwise NOT) and bitwise ANDed with Value1.
CALL – Assembly Language Reference CALL Instruction: Jump to address with intention to return to next instruction. CALL #Symbol Result: PC + 1 is written to the s-field of the register indicated by the d-field. • Symbol (s-field) is a 9-bit literal whose value is the address to jump to. This field must contain a DAT symbol specified as a literal (#symbol) and the corresponding code should eventually execute a RET instruction labeled with the same symbol plus a suffix of “_ret” (Symbol_ret RET).
3: Assembly Language Reference – CALL instruction is really just a JMP instruction without a hard-coded destination address, and this run-time action provides it with the “return” address to jump back to. After storing the return address, CALL jumps to the destination address; Symbol. The diagram below uses a short program example to demonstrate the CALL instruction’s runtime behavior; the store operation (left) and the jump-execute-return operation (right).
CALL – Assembly Language Reference This nature of the CALL instruction dictates the following: • The referenced routine must have only one RET instruction associated with it. If a routine needs more than one exit point, make one of those exit points the RET instruction and make all other exit points branch (i.e., JMP) to that RET instruction. • The referenced routine can not be recursive. Making a nested call to the routine will overwrite the return address of the previous call.
3: Assembly Language Reference – CLKSET CLKSET Instruction: Set the clock mode at run time. CLKSET Mode • Mode (d-field) is the register containing the 8-bit pattern to write to the CLK register. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0001 1111 ddddddddd ------000 Z Result --- C Result --- Result Not Written Clocks 7..
CMP – Assembly Language Reference CMP Instruction: Compare two unsigned values. CMP Value1, 〈#〉 Value2 Result: Optionally, equality and greater/lesser status is written to the Z and C flags. • • Value1 (d-field) is the register containing the value to compare with that of Value2. Value2 (s-field) is a register or a 9-bit literal whose value is compared with Value1.
3: Assembly Language Reference – CMP If the WZ effect is specified, the Z flag is set (1) if Value1 equals Value2. If the WC effect is specified, the C flag is set (1) if Value1 is less than Value2. The result is not written unless the WR effect is specified. If WR is specified, CMP becomes exactly like a SUB instruction. To compare unsigned, multi-long values, use CMP followed by CMPX. See CMPX on page 280 for more information.. Propeller Manual v1.
CMPS – Assembly Language Reference CMPS Instruction: Compare two signed values. CMPS SValue1, 〈#〉 SValue2 Result: Optionally, equality and greater/lesser status is written to the Z and C flags. • • SValue1 (d-field) is the register containing the value to compare with that of SValue2. SValue2 (s-field) is a register or a 9-bit literal whose value is compared with SValue1.
3: Assembly Language Reference – CMPS Explanation CMPS (Compare Signed) compares the signed values of SValue1 and SValue2. The Z and C flags, if written, indicate the relative equal, and greater or lesser relationship between the two. If the WZ effect is specified, the Z flag is set (1) if SValue1 equals SValue2. If the WC effect is specified, the C flag is set (1) if SValue1 is less than SValue2. To compare signed, multi-long values, instead of using CMPS, use CMP, possibly CMPX, and finally CMPSX.
CMPSUB – Assembly Language Reference CMPSUB Instruction: Compare two unsigned values and subtract the second if it is lesser or equal. CMPSUB Value1, 〈#〉 Value2 Result: Optionally, Value1 = Value1 – Value2, and Z and C flags = comparison results. • • Value1 (d-field) is the register containing the value to compare with that of Value2 and is the destination in which to write the result if a subtraction is performed.
3: Assembly Language Reference – CMPSX CMPSX Instruction: Compare two signed values plus C. CMPSX SValue1, 〈#〉 SValue2 Result: Optionally, equality and greater/lesser status is written to the Z and C flags. • • SValue1 (d-field) is the register containing the value to compare with that of SValue2. SValue2 (s-field) is a register or a 9-bit literal whose value is compared with SValue1.
CMPSX – Assembly Language Reference The C flag result of CMPSX (Compare Signed, Extended) may differ from CMPX (Compare Unsigned, Extended) where the “interpreted sign” of Source and Destination are opposite. The first example in the second group, above, shows that CMPSX sets C because signed $8000_0000 (-2,147,483,648) is less than signed $7FFF_FFFF (2,147,483,647). CMPX, however, would have cleared C because unsigned $8000_0000 (2,147,483,648) is not less than unsigned $7FFF_FFFF (2,147,483,647).
3: Assembly Language Reference – CMPSX A signed triple-long (96-bit) comparison would look similar but with a CMPX instruction inserted between the CMP and CMPSX instructions: cmp cmpx cmpsx XLow, YLow XMid, YMid XHigh, YHigh wc wz wc wz wc wz 'Compare low longs; save C and Z 'Compare middle longs; save C and Z 'Compare high longs; save C and Z For CMPSX, if the WZ effect is specified, the Z flag is set (1) if Z was previously set and SValue1 equals SValue2 + C (use WC and WZ on preceding CMP and CMPX
CMPX – Assembly Language Reference CMPX Instruction: Compare two unsigned values plus C. CMPX Value1, 〈#〉 Value2 Result: Optionally, equality and greater/lesser status is written to the Z and C flags. • • Value1 (d-field) is the register containing the value to compare with that of Value2. Value2 (s-field) is a register or a 9-bit literal whose value is compared with Value1.
3: Assembly Language Reference – CMPX 4 The C flag result of CMPX (Compare Unsigned, Extended) may differ from CMPSX (Compare Signed, Extended) where the “interpreted sign” of Source and Destination are opposite. The first example in the second group, above, shows that CMPX clears C because unsigned $8000_0000 (2,147,483,648) is not less than unsigned $7FFF_FFFF (2,147,483,647). CMPSX, however, would have set C because signed $8000_0000 ( 2,147,483,648) is less than signed $7FFF_FFFF (2,147,483,647).
CNT – Assembly Language Reference CNT Register: System Counter register. DAT 〈Label〉 〈Condition〉 Instruction DestOperand, CNT 〈Effects〉 • • • Label is an optional statement label. See Common Syntax Elements, page 250. Condition is an optional execution condition. See Common Syntax Elements, page 250. Instruction is the desired assembly instruction. CNT is a read-only register and thus • should only be used in the instruction’s source operand.
3: Assembly Language Reference – COGID COGID Instruction: Get current cog’s ID. COGID Destination Result: The current cog’s ID (0-7) is written to Destination. • Destination (d-field) is the register to write the cog’s ID into. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0011 1111 ddddddddd ------001 Z Result ID = 0 C Result 0 Result Written Clocks 7..
COGINIT – Assembly Language Reference COGINIT 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.
3: Assembly Language Reference – COGINIT Table 3-1: 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.
COGSTOP – Assembly Language Reference COGSTOP Instruction: Start a cog by its ID. COGSTOP CogID • CogID (d-field) is the register containing the ID (0 – 7) of the cog to stop. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0001 1111 ddddddddd ------011 Z Result Stopped ID = 0 C Result No Cog Free Result Not Written Clocks 7..
3: Assembly Language Reference – Conditions (IF_x) Conditions ( IF_x ) Every Propeller Assembly instruction has an optional “condition” field that is used to dynamically determine whether or not it executes when it is reached at run time. The basic syntax for Propeller Assembly instructions is: 〈Label〉 〈Condition〉 Instruction Operands 〈Effects〉 The optional Condition field can contain one of 32 conditions (see IF_x (Conditions), page 295) and defaults to IF_ALWAYS when no condition is specified.
CTRA, CTRB – Assembly Language Reference CTRA, CTRB Register: Counter A and Counter B control registers. DAT 〈Label〉 〈Condition〉 Instruction CTRA, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, CTRA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction CTRB, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, CTRB 〈Effects〉 Result: Optionally, the counter control register is updated. • • • • • Label is an optional statement label. See Common Syntax Elements, page 250.
3: Assembly Language Reference – DIRA, DIRB DIRA, DIRB Register: Direction registers for 32-bit ports A and B. DAT 〈Label〉 〈Condition〉 Instruction DIRA, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, DIRA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DIRB, SrcOperand 〈Effects〉 (Reserved for future use) DAT 〈Label〉 〈Condition〉 Instruction DestOperand, DIRB 〈Effects〉 (Reserved for future use) Result: Optionally, the direction register is updated.
DJNZ – Assembly Language Reference DJNZ Instruction: Decrement value and jump to address if not zero. DJNZ Value, 〈#〉 Address Result: Value-1 is written to Value. • • Value (d-field) is the register to decrement and test. Address (s-field) is the register or a 9-bit literal whose value is the address to jump to when the decremented Value is not zero.
3: Assembly Language Reference – Effects (WC, WZ, WR, NR) Effects ( WC, WZ, WR, NR ) Every Propeller Assembly instruction has an optional “effects” field that causes it to modify a flag or register when it executes. The basic syntax for Propeller Assembly instructions is: 〈Label〉 〈Condition〉 Instruction Operands 〈Effects〉 The optional Effects field can contain one or more of the four items shown below.
FIT – Assembly Language Reference FIT Directive: Validate that previous instructions/data fit entirely below a specific address. FIT 〈Address〉 Result: Compile-time error if previous instructions/data exceed Address-1. • Address is an optional Cog RAM address (0-$1F0) for which prior assembly code should not reach. If Address is not given, the value $1F0 is used (the address of the first special purpose register).
3: Assembly Language Reference – FRQA, FRQB FRQA, FRQB Register: Counter A and Counter B frequency registers. DAT 〈Label〉 〈Condition〉 Instruction FRQA, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, FRQA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction FRQB, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, FRQB 〈Effects〉 Result: Optionally, the counter frequency register is updated. • • • • • Label is an optional statement label.
HUBOP – Assembly Language Reference HUBOP Instruction: Perform a hub operation. HUBOP Destination, 〈#〉 Operation Result: Varies depending on the operation performed. • • Destination (d-field) is the register containing a value to use in the Operation. Operation (s-field) is a register or a 3-bit literal that indicates the hub operation to perform. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 000i 1111 ddddddddd sssssssss Z Result Result = 0 C Result --- Result Not Written Clocks 7..
3: Assembly Language Reference – IF_x (Conditions) IF_x (Conditions) Every Propeller Assembly instruction has an optional “condition” field that is used to dynamically determine whether or not it executes when it is reached at run time. The basic syntax for Propeller Assembly instructions is: 〈Label〉 〈Condition〉 Instruction Operands 〈Effects〉 The optional Condition field can contain one of 32 conditions (see Table 3-3) and defaults to IF_ALWAYS when no condition is specified.
IF_x (Conditions) – Assembly Language Reference Table 3-3: Conditions Condition IF_ALWAYS IF_NEVER IF_E IF_NE IF_A IF_B IF_AE IF_BE IF_C IF_NC IF_Z IF_NZ IF_C_EQ_Z IF_C_NE_Z IF_C_AND_Z IF_C_AND_NZ IF_NC_AND_Z IF_NC_AND_NZ IF_C_OR_Z IF_C_OR_NZ IF_NC_OR_Z IF_NC_OR_NZ IF_Z_EQ_C IF_Z_NE_C IF_Z_AND_C IF_Z_AND_NC IF_NZ_AND_C IF_NZ_AND_NC IF_Z_OR_C IF_Z_OR_NC IF_NZ_OR_C IF_NZ_OR_NC Instruction Executes Value always never if equal (Z = 1) if not equal (Z = 0) if above (!C & !Z = 1) if below (C = 1) if above or
3: Assembly Language Reference – INA, INB INA, INB Register: Input registers for 32-bit ports A and B. DAT 〈Label〉 〈Condition〉 Instruction DestOperand, INA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, INB 〈Effects〉 (Reserved for future use) • • • Label is an optional statement label. See Common Syntax Elements, page 250. Condition is an optional execution condition. See Common Syntax Elements, page 250. Instruction is the desired assembly instruction.
JMP – Assembly Language Reference JMP Instruction: Jump to address. JMP 〈#〉 Address • Address (s-field) is the register or a 9-bit literal whose value is the address to jump to.
3: Assembly Language Reference – JMP Toggle mov xor jmp dira, Pin outa, Pin #$-1 'Set I/O pin to output 'Toggle I/O pin's state 'Loop back endlessly The last instruction, JMP #$-1, causes execution to jump back to the second-to-last instruction (i.e., ‘here’ minus 1). Propeller Manual v1.
JMPRET – Assembly Language Reference JMPRET Instruction: Jump to address with intention to “return” to another address. JMPRET RetInstAddr, 〈#〉 DestAddress Result: PC + 1 is written to the s-field of the register indicated by the d-field. • • RetInstAddr (d-field) is the register in which to store the return address (PC + 1); often it is the address of an appropriate RET or JMP instruction executed by the DestAddress routine.
3: Assembly Language Reference – JMPRET stored, the DestAddress routine is executed, and finally control returns to the instruction following the JMPRET. See CALL on page 268 for more information. When used a little differently, the JMPRET instruction can aid in single-process multi-tasking. This is done by defining a set of registers to hold various destination and return addresses and specifying those registers for the RetInstAddr and DestAddress fields.
JMPRET – Assembly Language Reference address indicated by Task2. Since we initialized Task2 to point to SecondTask, the second task will now be executed. SecondTask performs some operations denoted by “…” and reaches another JMPRET instruction, jmpret Task2,Task1. Note that this is similar to FirstTask’s JMPRET instruction except the order of Task1 and Task2 is reversed.
3: Assembly Language Reference – LOCKCLR LOCKCLR Instruction: Clear lock to false and get its previous state. LOCKCLR ID Result: Optionally, previous state of lock is written to C flag. • ID (d-field) is the register containing the ID (0 – 7) of the lock to clear. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0001 1111 ddddddddd ------111 Z Result ID = 0 C Result Prior Lock State Result Not Written Clocks 7..
LOCKNEW – Assembly Language Reference LOCKNEW Instruction: Check out a new lock and get its ID. LOCKNEW NewID Result: The new lock’s ID (0-7) is written to NewID. • NewID (d-field) is the register where the newly checked-out lock’s ID is written. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0011 1111 ddddddddd ------100 Z Result ID = 0 C Result No Lock Free Result Written Clocks 7..
3: Assembly Language Reference – LOCKRET LOCKRET Instruction: Release lock back for future “new lock” requests. LOCKRET ID • ID (d-field) is the register containing the ID (0 – 7) of the lock to return to the lock pool. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0001 1111 ddddddddd ------101 Z Result ID = 0 C Result No Lock Free Result Not Written Clocks 7..
LOCKSET – Assembly Language Reference LOCKSET Instruction: Set lock to true and get its previous state. LOCKSET ID Result: Optionally, previous state of lock is written to C flag. • ID (d-field) is the register containing the ID (0 – 7) of the lock to set. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000011 0001 1111 ddddddddd ------110 Z Result ID = 0 C Result Prior Lock State Result Not Written Clocks 7..
3: Assembly Language Reference – MAX MAX Instruction: Limit maximum of unsigned value to another unsigned value. MAX Value1, 〈#〉 Value2 Result: Lesser of unsigned Value1 and unsigned Value2 is stored in Value1. • Value1 (d-field) is the register containing the value to compare against Value2 and is • the destination in which to write the lesser of the two. Value2 (s-field) is a register or a 9-bit literal whose value is compared against Value1.
MAXS – Assembly Language Reference MAXS Instruction: Limit maximum of signed value to another signed value. MAXS SValue1, 〈#〉 SValue2 Result: Lesser of signed SValue1 and signed SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to compare against SValue2 and • SValue2 (s-field) is a register or a 9-bit literal whose value is compared against is the destination in which to write the lesser of the two. SValue1.
3: Assembly Language Reference – MIN MIN Instruction: Limit minimum of unsigned value to another unsigned value. MIN Value1, 〈#〉 Value2 Result: Greater of unsigned Value1 and unsigned Value2 is stored in Value1. • • Value1 (d-field) is the register containing the value to compare against Value2 and is the destination in which to write the greater of the two. Value2 (s-field) is a register or a 9-bit literal whose value is compared against Value1.
MINS – Assembly Language Reference MINS Instruction: Limit minimum of signed value to another signed value. MINS SValue1, 〈#〉 SValue2 Result: Greater of signed SValue1 and signed SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to compare against SValue2 and • SValue2 (s-field) is a register or a 9-bit literal whose value is compared against is the destination in which to write the greater of the two. SValue1.
3: Assembly Language Reference – MOV MOV Instruction: Set a register to a value. MOV Destination, 〈#〉 Value Result: Value is stored in Destination. • • Destination (d-field) is the register in which to store Value. Value (s-field) is a register or a 9-bit literal whose value is stored into Destination.
MOVD – Assembly Language Reference MOVD Instruction: Set a register’s destination field to a value. MOVD Destination, 〈#〉 Value Result: Value is stored in Destination’s d-field (bits 17..9). • Destination (d-field) is the register whose destination field (bits 17..9) is set to Value’s • Value (s-field) is a register or a 9-bit literal whose value is stored into Destination’s d- value. field.
3: Assembly Language Reference – MOVI MOVI Instruction: Set a register’s instruction and effects fields to a value. MOVI Destination, 〈#〉 Value Result: Value is stored in Destination’s i-field and effects-field (bits 31..23). • Destination (d-field) is the register whose instruction and effects fields (bits 31..23) are • Value (s-field) is a register or a 9-bit literal whose value is stored into Destination’s set to Value’s value. instruction and effects field.
MOVS – Assembly Language Reference MOVS Instruction: Set a register’s source field to a value. MOVS Destination, 〈#〉 Value Result: Value is stored in Destination’ s-field (bits 8..0). • Destination (d-field) is the register whose source field (bits 8..0) is set to Value’s • Value (s-field) is a register or a 9-bit literal whose value is stored into Destination’s value. source field.
3: Assembly Language Reference – MUXC MUXC Instruction: Set discrete bits of a value to the state of C. MUXC Destination, 〈#〉 Mask Result: Destination’s bits, indicated by Mask, are set to the state of C. • • Destination (d-field) is the register whose bits described by Mask are affected by C. Mask (s-field) is a register or a 9-bit literal whose value contains high (1) bits for every bit in Destination to set to the C flag’s state.
MUXNC – Assembly Language Reference MUXNC Instruction: Set discrete bits of a value to the state of !C. MUXNC Destination, 〈#〉 Mask Result: Destination’s bits, indicated by Mask, are set to the state of !C. • • Destination (d-field) is the register whose bits described by Mask are affected by !C. Mask (s-field) is a register or a 9-bit literal whose value contains high (1) bits for every bit in Destination to set to the inverse of the C flag’s state.
3: Assembly Language Reference – MUXNZ MUXNZ Instruction: Set discrete bits of a value to the state of !Z. MUXNZ Destination, 〈#〉 Mask Result: Destination’s bits, indicated by Mask, are set to the state of !Z. • • Destination (d-field) is the register whose bits described by Mask are affected by !Z. Mask (s-field) is a register or a 9-bit literal whose value contains high (1) bits for every bit in Destination to set to the inverse of the Z flag’s state.
MUXZ – Assembly Language Reference MUXZ Instruction: Set discrete bits of a value to the state of Z. MUXZ Destination, 〈#〉 Mask Result: Destination’s bits, indicated by Mask, are set to the state of Z. • • Destination (d-field) is the register whose bits described by Mask are affected by Z. Mask (s-field) is a register or a 9-bit literal whose value contains high (1) bits for every bit in Destination to set to the Z flag’s state.
3: Assembly Language Reference – NEG NEG Instruction: Get the negative of a number. NEG NValue, 〈#〉 SValue Result: –SValue is stored in NValue. • • NValue (d-field) is the register in which to write the negative of SValue. SValue (s-field) is a register or a 9-bit literal whose negative value will be written to NValue.
NEGC – Assembly Language Reference NEGC Instruction: Get a value, or its additive inverse, based on C. NEGC RValue, 〈#〉 Value Result: Value or –Value is stored in RValue. • • RValue (d-field) is the register in which to write Value or –Value. Value (s-field) is a register or a 9-bit literal whose value (if C = 0) or additive inverse value (if C = 1) will be written to RValue.
3: Assembly Language Reference – NEGNC NEGNC Instruction: Get a value, or its additive inverse, based on !C. NEGNC RValue, 〈#〉 Value Result: –Value or Value is stored in RValue. • • RValue (d-field) is the register in which to write –Value or Value. Value (s-field) is a register or a 9-bit literal whose additive inverse value (if C = 0) or value (if C = 1) will be written to RValue.
NEGNZ – Assembly Language Reference NEGNZ Instruction: Get a value, or its additive inverse, based on !Z. NEGNZ RValue, 〈#〉 Value Result: –Value or Value is stored in RValue. • • RValue (d-field) is the register in which to write –Value or Value. Value (s-field) is a register or a 9-bit literal whose additive inverse value (if Z = 0) or value (if Z = 1) will be written to RValue.
3: Assembly Language Reference – NEGZ NEGZ Instruction: Get a value, or its additive inverse, based on Z. NEGZ RValue, 〈#〉 Value Result: Value or –Value is stored in RValue. • • RValue (d-field) is the register in which to write Value or –Value. Value (s-field) is a register or a 9-bit literal whose value (if Z = 0) or additive inverse value (if Z = 1) will be written to RValue.
NOP – Assembly Language Reference NOP Instruction: No operation, just elapse four clock cycles. NOP Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– ------ ---- 0000 --------- --------- Z Result --- C Result --- Result --- Clocks 4 Concise Truth Table: (Not specified because NOP performs no action.) Explanation NOP performs no operation but consumes 4 clock cycles. NOP has its –CON– field set to all zeros, the NEVER condition; effectively, every instruction with a NEVER condition is a NOP instruction.
3: Assembly Language Reference – NR NR Effect: Prevent assembly instruction from writing a result. 〈Label〉 〈Condition〉 Instruction Operands NR Result: Instruction’s destination register is left unaffected. • • • • Label is an optional statement label. See Common Syntax Elements on page 250. Condition is an optional execution condition. See Common Syntax Elements on page 250. Instruction is the desired assembly instruction. Operands is zero, one, or two operands as required by the Instruction.
Operators – Assembly Language Reference Operators Propeller Assembly code can contain expressions using any operators that are allowed in constant expressions. Table 3-4 summarizes all the operators allowed in Propeller Assembly code. Please refer to the Spin Language Reference Operators section on page 143 for detailed descriptions of their functions; page numbers are given in the table.
3: Assembly Language Reference – OR OR Instruction: Bitwise OR two values. OR Value1, 〈#〉 Value2 Result: Value1 OR Value2 is stored in Value1. • Value1 (d-field) is the register containing the value to bitwise OR with Value2 and is • the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value is bitwise ORed with Value1.
ORG – Assembly Language Reference ORG Directive: Adjust compile-time assembly pointer. ORG 〈Address〉 • Address is an optional Cog RAM address (0-495) to assemble the following assembly code with. If Address is not given, the value 0 is used. 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.
3: Assembly Language Reference – ORG 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).
OUTA, OUTB – Assembly Language Reference OUTA, OUTB Register: Output registers for 32-bit ports A and B. DAT 〈Label〉 〈Condition〉 Instruction OUTA, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, OUTA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction OUTB, SrcOperand 〈Effects〉 (Reserved for future use) DAT 〈Label〉 〈Condition〉 Instruction DestOperand, OUTB 〈Effects〉 (Reserved for future use) Result: Optionally, the output register is updated.
3: Assembly Language Reference – PAR PAR Register: Cog boot parameter register. DAT 〈Label〉 〈Condition〉 Instruction DestOperand, PAR 〈Effects〉 • • • Label is an optional statement label. See Common Syntax Elements, page 250. Condition is an optional execution condition. See Common Syntax Elements, page 250. Instruction is the desired assembly instruction. PAR is a read-only register and thus • should only be used in the instruction’s source operand.
PHSA, PHSB – Assembly Language Reference PHSA, PHSB Register: Counter A and Counter B phase registers. DAT 〈Label〉 〈Condition〉 Instruction PHSA, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, PHSA 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction PHSB, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, PHSB 〈Effects〉 Result: Optionally, the counter phase register is updated. • • • • • Label is an optional statement label. See Common Syntax Elements, page 250.
3: Assembly Language Reference – RCL RCL Instruction: Rotate C left into value by specified number of bits. RCL Value, 〈#〉 Bits Result: Value has Bits copies of C rotated left into it. • • Value (d-field) is the register in which to rotate C leftwards. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits of Value to rotate C leftwards into.
RCR – Assembly Language Reference RCR Instruction: Rotate C right into value by specified number of bits. RCR Value, 〈#〉 Bits Result: Value has Bits copies of C rotated right into it. • • Value (d-field) is the register in which to rotate C rightwards. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits of Value to rotate C rightwards into.
3: Assembly Language Reference – RDBYTE RDBYTE Instruction: Read byte of main memory. RDBYTE Value, 〈#〉 Address Result: Zero-extended byte is stored in Value. • • Value (d-field) is the register to store the zero-extended byte value into. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to read from. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000000 001i 1111 ddddddddd sssssssss Z Result Result = 0 C Result --- Result Written Clocks 7..
RDLONG – Assembly Language Reference RDLONG Instruction: Read long of main memory. RDLONG Value, 〈#〉 Address Result: Long is stored in Value. • • Value (d-field) is the register to store the long value into. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to read from. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000010 001i 1111 ddddddddd sssssssss Z Result Result = 0 C Result --- Result Written Clocks 7..
3: Assembly Language Reference – RDWORD RDWORD Instruction: Read word of main memory. RDWORD Value, 〈#〉 Address Result: Zero-extended word is stored in Value. • • Value (d-field) is the register to store the zero-extended word value into. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to read from. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000001 001i 1111 ddddddddd sssssssss Z Result Result = 0 C Result --- Result Written Clocks 7..
Registers – Assembly Language Reference Registers Each cog contains 16 special purpose registers for accessing I/O pins, the built-in counters and video generator, and the parameter passed at the moment the cog is launched. All of these registers are explained in the Spin Language Reference and most of the information applies to both Spin and Propeller Assembly.
3: Assembly Language Reference – RES RES Directive: Reserve next long(s) for symbol. 〈Symbol〉 RES 〈Count〉 • • Symbol is an optional name for the reserved long in Cog RAM. Count is the optional number of longs to reserve for Symbol. If not specified, RES reserves one long. Explanation The RES (reserve) directive effectively reserves one or more longs of Cog RAM by incrementing the compile-time assembly pointer by Count.
RES – Assembly Language Reference Symbol Address Instruction/Data AsmCode 0 1 2 3 4 5 6 mov Time, cnt add Time, Delay waitcnt Time, Delay nop jmp #:Loop 6_000_000 ? :Loop Delay Time RES simply increments the compile-time assembly pointer that affects further symbol references (Cog RAM); it does not consume space in the object (Main RAM). This distinction is important in how it impacts the object code, initialized symbols, and affects runtime operation.
3: Assembly Language Reference – RES :Loop Time Delay RES long waitcnt Time, Delay nop jmp #:Loop 'Wait for time window 'Do something useful 'Loop endlessly 1 6_000_000 'Time window workspace 'Time window size This example would be launched into a cog as follows: Symbol Address Instruction/Data AsmCode 0 1 2 3 4 5 6 mov Time, cnt add Time, Delay waitcnt Time, Delay nop jmp #:Loop 6_000_000 ? :Loop Time Delay Notice how Time and Delay are reversed with respect to the previous example but their
RET – Assembly Language Reference RET Instruction: Return to previously recorded address.
3: Assembly Language Reference – REV REV Instruction: Reverse LSBs of value and zero-extend. REV Value, 〈#〉 Bits Result: Value has lower 32 - Bits of its LSBs reversed and upper bits cleared. • • Value (d-field) is the register containing the value whose bits are reversed. Bits (s-field) is a register or a 5-bit literal whose value subtracted from 32, (32 - Bits), is the number of Value’s LSBs to reverse. The upper Bits MSBs of Value are cleared.
ROL – Assembly Language Reference ROL Instruction: Rotate value left by specified number of bits. ROL Value, 〈#〉 Bits Result: Value is rotated left by Bits. • • Value (d-field) is the register to rotate left. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits to rotate left.
3: Assembly Language Reference – ROR ROR Instruction: Rotate value right by specified number of bits. ROR Value, 〈#〉 Bits Result: Value is rotated right by Bits. • • Value (d-field) is the register to rotate right. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits to rotate right.
SAR – Assembly Language Reference SAR Instruction: Shift value arithmetically right by specified number of bits. SAR Value, 〈#〉 Bits Result: Value is shifted arithmetically right by Bits. • • Value (d-field) is the register to shift arithmetically right. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits to shift arithmetically right.
3: Assembly Language Reference – SHL SHL Instruction: Shift value left by specified number of bits. SHL Value, 〈#〉 Bits Result: Value is shifted left by Bits. • • Value (d-field) is the register to shift left. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits to shift left.
SHR – Assembly Language Reference SHR Instruction: Shift value right by specified number of bits. SHR Value, 〈#〉 Bits Result: Value is shifted right by Bits. • • Value (d-field) is the register to shift right. Bits (s-field) is a register or a 5-bit literal whose value is the number of bits to shift right.
3: Assembly Language Reference – SUB SUB Instruction: Subtract two unsigned values. SUB Value1, 〈#〉 Value2 Result: Difference of unsigned Value1 and unsigned Value2 is stored in Value1. • Value1 (d-field) is the register containing the value to subtract Value2 from, and is the • destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value is subtracted from Value1.
SUBABS – Assembly Language Reference SUBABS Instruction: Subtract an absolute value from another value. SUBABS Value, 〈#〉 SValue Result: Difference of Value and absolute of signed SValue is stored in Value. • Value (d-field) is the register containing the value to subtract the absolute of SValue • from, and is the destination in which to write the result. SValue (s-field) is a register or a 9-bit literal whose absolute value is subtracted from Value.
3: Assembly Language Reference – SUBS SUBS Instruction: Subtract two signed values. SUBS SValue1, 〈#〉 SValue2 Result: Difference of signed SValue1 and signed SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to subtract SValue2 from, and is • SValue2 (s-field) is a register or a 9-bit literal whose value is subtracted from SValue1. the destination in which to write the result.
SUBSX – Assembly Language Reference SUBSX Instruction: Subtract signed value plus C from another signed value. SUBSX SValue1, 〈#〉 SValue2 Result: Difference of signed SValue1, and signed SValue2 plus C flag, is stored in SValue1. • • SValue1 (d-field) is the register containing the value to subtract SValue2 plus C from, and is the destination in which to write the result. SValue2 (s-field) is a register or a 9-bit literal whose value plus C is subtracted from SValue1.
3: Assembly Language Reference – SUBSX (ex: SUBSX). Make sure to use the WC, and optionally WZ, effect on the leading SUB and SUBX instructions. For example, a signed double-long (64-bit) subtraction may look like this: sub subsx XLow, YLow XHigh, YHigh wc wz 'Subtract low longs; save C and Z 'Subtract high longs After executing the above, the double-long (64-bit) result is in the long registers XHigh:XLow.
SUBX – Assembly Language Reference SUBX Instruction: Subtract unsigned value plus C from another unsigned value. SUBX Value1, 〈#〉 Value2 Result: Difference of unsigned Value1, and unsigned Value2 plus C flag, is stored in Value1. • • Value1 (d-field) is the register containing the value to subtract Value2 plus C from, and is the destination in which to write the result. Value2 (s-field) is a register or a 9-bit literal whose value plus C is subtracted from Value1.
3: Assembly Language Reference – SUBX For example, an unsigned double-long (64-bit) subtraction may look like this: sub subx XLow, YLow XHigh, YHigh wc wz 'Subtract low longs; save C and Z 'Subtract high longs After executing the above, the double-long (64-bit) result is in the long registers XHigh:XLow. If XHigh:XLow started out as $0000_0001:0000_0000 (4,294,967,296) and YHigh:YLow was $0000_0000:0000_0001 (1) the result in XHigh:XLow would be $0000_0000:FFFF_FFFF (4,294,967,295).
SUMC – Assembly Language Reference SUMC Instruction: Sum a signed value with another whose sign is inverted depending on C. SUMC SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and ±SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to sum with either –SValue2 or • SValue2 (s-field) is a register or a 9-bit literal whose value is sign-affected by C and SValue2, and is the destination in which to write the result. summed into SValue1.
3: Assembly Language Reference – SUMNC SUMNC Instruction: Sum a signed value with another whose sign is inverted depending on !C. SUMNC SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and ±SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to sum with either SValue2 or • SValue2 (s-field) is a register or a 9-bit literal whose value is sign-affected by !C and -SValue2, and is the destination in which to write the result. summed into SValue1.
SUMNZ – Assembly Language Reference SUMNZ Instruction: Sum a signed value with another whose sign is inverted depending on !Z. SUMNZ SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and ±SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to sum with either SValue2 or • -SValue2, and is the destination in which to write the result. SValue2 (s-field) is a register or a 9-bit literal whose value is sign-affected by !Z and summed into SValue1.
3: Assembly Language Reference – SUMZ SUMZ Instruction: Sum a signed value with another whose sign is inverted depending on Z. SUMZ SValue1, 〈#〉 SValue2 Result: Sum of signed SValue1 and ±SValue2 is stored in SValue1. • SValue1 (d-field) is the register containing the value to sum with either –SValue2 or • SValue2 (s-field) is a register or a 9-bit literal whose value is sign-affected by Z and SValue2, and is the destination in which to write the result. summed into SValue1.
Symbols – Assembly Language Reference Symbols The symbols in Table 3-6 below serve one or more special purposes in Propeller Assembly code. For Spin symbols, see Symbols on page 207. Each symbol’s purpose is described briefly with references to other sections that describe it directly or use it in examples. Table 3-6: Symbols Symbol Purpose(s) % Binary indicator: used to indicate that a value is being expressed in binary (base-2). See Value Representations on page 45.
3: Assembly Language Reference – Symbols Table 3-6: Symbols (continued) Symbol Purpose(s) : Assembly local label indicator: appears immediately before a local label. See Global and Local Labels on page 242. , List delimiter: used to separate items in lists. See the DAT section’s Declaring Data(Syntax 1) on page 100. ' Code comment designator: used to enter single-line code comments (non-compiled text) for code viewing purposes. See “Using the Propeller Tool” in the software’s Help file.
TEST – Assembly Language Reference TEST Instruction: Bitwise AND two values to affect flags only. TEST Value1, 〈#〉 Value2 Result: Optionally, zero-result and parity of result is written to the Z and C flags. • • Value1 (d-field) is the register containing the value to bitwise AND with Value2. Value2 (s-field) is a register or a 9-bit literal whose value is bitwise ANDed with Value1.
3: Assembly Language Reference – TESTN TESTN Instruction: Bitwise AND a value with the NOT of another to affect flags only. TESTN Value1, 〈#〉 Value2 Result: Optionally, zero-result and parity of result is written to the Z and C flags. • • Value1 (d-field) is the register containing the value to bitwise AND with !Value2. Value2 (s-field) is a register or a 9-bit literal whose value is inverted (bitwise NOT) and bitwise ANDed with Value1.
TJNZ – Assembly Language Reference TJNZ Instruction: Test value and jump to address if not zero. TJNZ Value, 〈#〉 Address • • Value (d-field) is the register to test. Address (s-field) is the register or a 9-bit literal whose value is the address to jump to when Value contains a non-zero number.
3: Assembly Language Reference – TJZ TJZ Instruction: Test value and jump to address if zero. TJZ Value, 〈#〉 Address • • Value (d-field) is the register to test. Address (s-field) is the register or a 9-bit literal whose value is the address to jump to when Value contains zero.
VCFG – Assembly Language Reference VCFG Register: Video configuration register. DAT 〈Label〉 〈Condition〉 Instruction VCFG, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, VCFG 〈Effects〉 • • • Label is an optional statement label. See Common Syntax Elements, page 250. Condition is an optional execution condition. See Common Syntax Elements, page 250. Instruction is the desired assembly instruction.
3: Assembly Language Reference – VSCL VSCL Register: Video scale register DAT 〈Label〉 〈Condition〉 Instruction VSCL, SrcOperand 〈Effects〉 DAT 〈Label〉 〈Condition〉 Instruction DestOperand, VSCL 〈Effects〉 • • • Label is an optional statement label. See Common Syntax Elements, page 250. Condition is an optional execution condition. See Common Syntax Elements, page 250. Instruction is the desired assembly instruction.
WAITCNT – Assembly Language Reference WAITCNT Instruction: Pause a cog’s execution temporarily. WAITCNT Target, 〈#〉 Delta Result: Target + Delta is stored in Target. • Target (d-field) is the register with the target value to compare against the System Counter (CNT). When the System Counter has reached Target’s value, Delta is added to Target and execution continues at the next instruction.
3: Assembly Language Reference – WAITPEQ WAITPEQ Instruction: Pause a cog’s execution until I/O pin(s) match designated state(s). WAITPEQ State, 〈#〉 Mask • State (d-field) is the register with the target state(s) to compare against INx ANDed • Mask (s-field) is the register or a 9-bit literal whose value is bitwise ANDed with INx with Mask. before the comparison with State.
WAITPNE – Assembly Language Reference WAITPNE Instruction: Pause a cog’s execution until I/O pin(s) do not match designated state(s). WAITPNE State, 〈#〉 Mask • State (d-field) is the register with the target state(s) to compare against INx ANDed • Mask (s-field) is the register or a 9-bit literal whose value is bitwise ANDed with INx with Mask. before the comparison with State.
3: Assembly Language Reference – WAITVID WAITVID Instruction: Pause a cog’s execution until its Video Generator is available to take pixel data. WAITVID Colors, 〈#〉 Pixels • • Colors (d-field) is the register with four byte-sized color values, each describing the four possible colors of the pixel patterns in Pixels. Pixels (s-field) is the register or a 9-bit literal whose value is the next 16-pixel by 2-bit (or 32-pixel by 1-bit) pixel pattern to display.
WC – Assembly Language Reference WC Effect: Cause assembly instruction to modify the C flag. 〈Label〉 〈Condition〉 Instruction Operands WC Result: C flag is updated with status from the Instruction‘s execution. • • • • Label is an optional statement label. See Common Syntax Elements on page 250. Condition is an optional execution condition. See Common Syntax Elements on page 250. Instruction is the desired assembly instruction. Operands is zero, one, or two operands as required by the Instruction.
3: Assembly Language Reference – WR WR Effect: Cause assembly instruction to write a result. 〈Label〉 〈Condition〉 Instruction Operands WR Result: Instruction’s destination register is changed to the result value. • • • • Label is an optional statement label. See Common Syntax Elements on page 250. Condition is an optional execution condition. See Common Syntax Elements on page 250. Instruction is the desired assembly instruction. Operands is zero, one, or two operands as required by the Instruction.
WRBYTE – Assembly Language Reference WRBYTE Instruction: Write a byte to main memory. WRBYTE Value, 〈#〉 Address • • Value (d-field) is the register containing the 8-bit value to write to main memory. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to write to. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000000 000i 1111 ddddddddd sssssssss Z Result --- C Result --- Result Not Written Clocks 7..
3: Assembly Language Reference – WRLONG WRLONG Instruction: Write a long to main memory. WRLONG Value, 〈#〉 Address • • Value (d-field) is the register containing the 32-bit value to write to main memory. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to write to. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000010 000i 1111 ddddddddd sssssssss Z Result --- C Result --- Result Not Written Clocks 7..
WRWORD – Assembly Language Reference WRWORD Instruction: Write a word to main memory. WRWORD Value, 〈#〉 Address • • Value (d-field) is the register containing the 16-bit value to write to main memory. Address (s-field) is a register or a 9-bit literal whose value is the main memory address to write to. Opcode Table: –INSTR– ZCRI –CON– –DEST– –SRC– 000001 000i 1111 ddddddddd sssssssss Z Result --- C Result --- Result Not Written Clocks 7..
3: Assembly Language Reference – WZ WZ Effect: Cause assembly instruction to modify the Z flag. 〈Label〉 〈Condition〉 Instruction Operands WZ Result: Z flag is updated with status from the Instruction‘s execution. • • • • Label is an optional statement label. See Common Syntax Elements on page 250. Condition is an optional execution condition. See Common Syntax Elements on page 250. Instruction is the desired assembly instruction. Operands is zero, one, or two operands as required by the Instruction.
XOR – Assembly Language Reference XOR Instruction: Bitwise XOR two values. XOR Value1, 〈#〉 Value2 Result: Value1 XOR Value2 is stored in Value1. • Value1 (d-field) is the register containing the value to bitwise XOR with Value2 and is • Value2 (s-field) is a register or a 9-bit literal whose value is bitwise XORed with the destination in which to write the result. Value1.
Appendix A: Reserved Word List Appendix A: Reserved Word List These words are always reserved, whether programming in Spin or Propeller Assembly.
Appendix B: Math Samples and Function Tables Appendix B: Math Samples and Function Tables Multiplication, Division, and Square Root Multiplication, division, and square root can be computed by using add, subtract, and shift instructions. Here is an unsigned multiplier routine that multiplies two 16-bit values to yield a 32-bit product: '' Multiply x[15..0] by y[15..0] ' on exit, product in y[31..0] ' multiply shl x,#16 mov t,#16 shr y,#1 :loop if_c add y,x rcr y,#1 djnz t,#:loop multiply_ret ret (y[31..
Appendix B: Math Samples and Function Tables Like the multiplier routine, this divider routine could be recoded with a sequence of 16 CMPSUB + RCL instruction pairs to get rid of the DJNZ and cut execution time by ~1/3. By making such changes, speed can often be gained at the expense of code size. Here is a square-root routine that uses the CMPSUB instruction: ' ' Compute square-root of y[31..0] into x[15..
Appendix B: Math Samples and Function Tables form is quite natural and efficient, as it lends a ‘linear’ simplicity to what is actually logarithmic. The code examples given below use each tables’ samples verbatim. Higher resolution could be achieved by linearly interpolating between table samples, since the slope change is very slight from sample to sample. The cost, though, would be larger code and lower execution speed.
Appendix B: Math Samples and Function Tables if_z if_z if_z test muxnz shl test muxnz shl test muxnz shl num,num2 exp,exp2 num,#4 num,num1 exp,exp1 num,#2 num,num0 exp,exp0 num,#1 wz shr num,#30-11 'justify sub-leading bits as word and add rdword or num,table_mask num,table_log num,num exp,num 'isolate table offset bits 'add log table address 'read fractional portion of exponent 'combine fractional & integer portions wz wz offset numexp_ret ret '91..
Appendix B: Math Samples and Function Tables Anti-Log Table ($D000-$DFFF) The anti-log table contains data used to convert base-2 exponents into unsigned numbers. The anti-log table is comprised of 2,048 unsigned words which are each the lower 16-bits of a 17-bit mantissa (the 17th bit is implied and must be set separately). To use this table, shift the top 11 bits of the exponent fraction (bits 15..5) into bits 11..1 and isolate. Add $D000 for the anti-log table base.
Appendix B: Math Samples and Function Tables Sine Table ($E000-$F001) The sine table provides 2,049 unsigned 16-bit sine samples spanning from 0° to 90°, inclusively (0.0439° resolution). A small amount of assembly code can mirror and flip the sine table samples to create a fullcycle sine/cosine lookup routine that has 13-bit angle resolution and 17-bit sample resolution: ' Get sine/cosine ' ' quadrant: 1 2 3 4 ' angle: $0000..$07FF $0800..$0FFF $1000..$17FF $1800..$1FFF ' table index: $0000..$07FF $0800..
Index Index _ _CLKFREQ (spin), 65–66 _CLKMODE (spin), 68–70 _FREE (spin), 110 _STACK (spin), 202 _XINFREQ (spin), 236–37 A Abort Status, 47 Trap, 48, 208 ABORT (spin), 47–50 ABS (asm), 257 ABSNEG (asm), 258 Absolute Negative 'ABSNEG', 258 Absolute Value ‘||’, 156 Absolute Value 'ABS', 257 Access collisions, 122 ADC, 95 ADD (asm), 259 Add ‘+’, ‘+=’, 149 ADDABS (asm), 260 Address ‘@’, 173 Address Plus Symbol ‘@@’, 173 Addressing main memory, 54, 131, 231 Addressing, optimized, 185, 212 ADDS (asm), 261 ADDSX
Index Flow control, 245, 268, 290, 298, 300, 342, 364, 365 FRQA, FRQB, 293, 338 Global label, 242 Here indicator, $, 360 Hub instructions, 256 HUBOP, 294 IF_x (conditions), 295 INA, INB, 297, 338 INSTR field, 251 Instruction field, 250 JMP, 298–99 JMPRET, 300–302 Label field, 250 Launching into a cog, 77, 81, 103 Literal indicator, #, 240, 241, 360 Local label, 242 Local label indicator, :, 242, 361 LOCKCLR, 303 LOCKNEW, 304 LOCKRET, 305 LOCKSET, 306 Main memory access, 245, 335, 336, 337, 374, 375, 376 Mas
Index WAITPEQ, 369 WAITPNE, 370 WAITVID, 371 WC, 372 WR, 373 WRBYTE, 374 WRLONG, 375 WRWORD, 376 WZ, 377 XOR, 378 ZCRI field, 251 Assignment Constant ‘=’, 148 Intermediate, 147 Variable ‘:=’, 149 Assignment / normal operators, 145 B Bases, numerical, 45 Binary / Unary operators, 145 Binary indicator, %, 207, 360 Binary operators (asm), 249 Binary operators (spin), 43 Bitwise operators AND ‘&’, ‘&=’, 164 AND Truth Table (table), 164 Decode ‘|<’, 160 Encode ‘>|’, 160 NOT ‘!’, 166 NOT Truth Table (table), 166
Index CLKSET (spin), 71–72 Clock Configuring, 28, 67 Frequency, 63, 65, 71 Frequency range, 29 Mode, 28, 31, 67, 68 Mode Setting Constants (table), 68, 69 PLL, 22, 28, 65 Sources, 22 System, 22 CMP (asm), 272–73 CMPS (asm), 274–75 CMPSUB (asm), 276 CMPSX (asm), 277–79 CMPX (asm), 280–81 CNT (asm), 23, 282, 338 CNT (spin), 23, 73–74, 200 Cog Assembly pointer, 328 Boot parameter register, 178, 331 Control (asm), 243, 283, 284, 286 Control (spin), 39, 75, 76, 78, 83, 187 First instruction address, 23, 239 ID,
Index Fixed, 218 Fixed (figure), 220, 230 Synchronized, 219 Synchronized (figure), 221 Delimiter, _, 207, 360 DEST field (asm), 251 Digital-to-analog conversion, 95 DIP, 14 DIRA, DIRB (asm), 23, 289, 338 DIRA, DIRB (spin), 23, 104–6, 200 Direction register, 104–6, 289 Direction states, 23 Directives (asm), 243, 292, 328, 339 Directives (spin), 41, 91, 107, 108, 198, 205, 209 Discussion forum, 11 Divide ‘/’, ‘/=’, 154 DJNZ (asm), 290 Dual commands, 103 Duty-cycle measurement, 95 E Editor’s Note, 11 EEPROM,
Index I I/O pins, 26 Direction, 104–6, 289 Inputs, 118–19, 297 Outputs, 175–77, 330 Rules, 105, 176 I/O pins (spec), 15, 16 I/O Sharing Examples (table), 27 ID of cog, 75, 283 IEEE-754, 109 IF (spin), 112–16 IF_x (asm) (conditions), 295 IFNOT (spin), 117 Import external file, 107 INA, INB (asm), 23, 297, 338 INA, INB (spin), 23, 118–19, 200 Increment, pre- or post- ‘+ +’, 152 Indention, 59, 113, 189 Infinite loops, 189 Initial clock mode, 68 Initial frequency, 65 Input register, 118–19, 297 Input states, 23
Index LQFP, 14 LSB, 159 M Main memory, 30 Main memory access (asm), 245, 335, 336, 337, 374, 375, 376 Main Memory Map (figure), 31 Main RAM, 23, 31 Main RAM/ROM (spec), 16 Main ROM, 23, 32 Master clock frequency, 28, 31 Math function tables, 380 Math/Logic Operators (table), 144 MAX (asm), 307 Maximum, Limit ‘<#’, ‘<#=’, 155 MAXS (asm), 308 Memory Access (asm), 245, 335, 336, 337, 374, 375, 376 Access (spin), 40, 51, 57, 58, 128, 134, 135, 136, 138, 203, 206, 227, 234, 235 Addressing Main RAM, 54, 131, 231
Index Operator attributes, 143 Operator Precedence Levels (table), 145 Operators, 143–74, 326 - - (Decrement, pre- or post-), 151 - (Negate), 150 ! (Bitwise NOT), 166 #>, #>= (Limit Minimum), 155 &, &= (Bitwise AND), 164 **, **= (Multiply, Return High), 153 *, *= (Multiply, Return Low), 153 -, -= (Subtract), 150 /, /= (Divide), 154 //, //= (Modulus), 154 := (Variable Assignment), 149 ? (Random), 159 @ (Symbol Address), 173 @@ (Object Address Plus Symbol), 173 ^, ^= (Bitwise XOR), 165 ^^ (Square Root), 156 |
Index Power requirements (spec), 16 Power up, 18 Precedence level, 143, 146 Pre-Decrement ‘- -’, 151 Pre-Increment ‘+ +’, 152 PRI (spin), 181 Private method block, 181 Process Control (asm), 243, 303, 304, 305, 306, 368, 369, 370, 371 Process control (spin), 39, 120, 122, 125, 126, 218, 222, 224, 225 Processors (cogs), 22 Programming connections, 17 Programming pins, 15 Propeller Application Defined, 18 Propeller Assembly.
Index DIRA, DIRB (asm), 23, 289, 338 DIRA, DIRB (spin), 23, 104–6 FRQA, FRQB (asm), 23, 293, 338 FRQA, FRQB (spin), 23, 111 INA, INB (asm), 23, 297, 338 INA, INB (spin), 23, 118–19 OUTA, OUTB (asm), 23, 330, 338 OUTA, OUTB (spin), 23, 175–77 PAR (asm), 23, 331, 338 PAR (spin), 23, 178–79 PHSA, PHSB (asm), 23, 332, 338 PHSA, PHSB (spin), 23, 180 Read-only, 23, 73–74, 118–19, 178–79, 282, 297, 331 VCFG (asm), 23, 338, 366 VCFG (spin), 23, 213–15 VSCL (asm), 23, 338, 367 VSCL (spin), 23, 216–17 Registers, spec
Index AND, 113 Binary operators, 43 Block designators, 38, 84, 99, 141, 181, 182, 210 BYTE, 51–56 BYTEFILL, 57 BYTEMOVE, 58 CASE, 59–61 Categorical listing, 38 CHIPVER, 62 CLKFREQ, 63–64 CLKMODE, 67 CLKSET, 71–72 CNT, 73–74 Cog control, 39, 75, 76, 78, 83, 187 COGID, 75 COGINIT, 76–77 COGNEW, 78–82 CON, 84–90 Configuration, 38, 62, 63, 65, 67, 68, 71, 94, 110, 202, 236 CONSTANT, 91–92 Constants (pre-defined), 93–94 CTRA, CTRB, 95–98 DAT, 99–103 DIRA, DIRB, 104–6 Directives, 41, 91, 107, 108, 198, 205, 209 D
Index WAITPEQ, 222–23 WAITPNE, 224 WAITVID, 225–26 WHILE, 189, 192 WORD, 227–33 WORDFILL, 234 WORDMOVE, 235 XINPUT, 93, 94 XTAL1, 93, 94 XTAL2, 93, 94 XTAL3, 93, 94 Spin, structure of, 36 SPR (spin), 200–201 Square Root ‘^^’, 156 SRC field (asm), 251 Stack space, 76, 80 Starting a new cog, 76, 78, 284 Starting address (cog), 23, 239 Start-up clock frequency, 65 STEP (spin), 188, 191 Stopping a cog, 83, 286 STRCOMP (spin), 203–4 STRING (spin), 205 String comparison, 203 String constant, 205 String size, 206
Index ->, ->= (Bitwise Rotate Right), 162 >, >= (Boolean Is Greater Than), 171 >| (Bitwise Encode), 160 ><, ><= (Bitwise Reverse), 163 >>, >>= (Bitwise Shift Right), 161 AND, AND= (Boolean AND), 167 NOT (Boolean), 168 OR, OR= (Boolean OR), 168 Symbols (table), 207–8, 207–8, 207–8 Synchronized delay, 219 Synchronized Delay Timing (figure), 221 Syntax definitions (asm), 250 Syntax definitions (spin), 46 System Clock, 22, 65, 71 System Clock frequency, 63 System Clock speed (spec), 16 System Clock Tick vs.
Index Video configuration register, 23, 213, 366 Video scale register, 23, 216, 367 VSCL (asm), 23, 338, 367 VSCL (spin), 23, 200, 216–17 VSCL Register (table), 216 W WAITCNT (asm), 368 WAITCNT (spin), 218–21 Waiting for transitions, 223 WAITPEQ (asm), 369 WAITPEQ (spin), 222–23 WAITPNE (asm), 370 WAITPNE (spin), 224 WAITVID (asm), 371 WAITVID (spin), 225–26 Warranty, 2 WC (asm), 372 WHILE (spin), 189, 192 Wired-OR, 105, 119, 176 Word Aligned, 100 Data declaration, 229 Memory type, 16, 227 Of larger symbol
