Spin Tutorial Quick Review Summary
If you are just trying to verify something you learned in this Tutorial but don't remember just where it was, you can quickly browse through each lesson's Quick Review here:
- The Propeller is programmed using two custom-designed languages: Spin and Propeller Assembly.
- Spin is a high-level, object-based language interpreted at run time.
- Propeller Assembly is a low-level, optimized assembly language which is executed directly at run time.
- Objects are programs that:
- are self-contained.
- perform a specific task.
- may be reused by many applications.
- Well-written objects from one developer can easily be used by other developers and applications.
- A Propeller Object:
- consists of two or more lines of Spin code and possibly Propeller Assembly code.
- is stored on the computer as a file with a “.spin” extension.
- may use one or more other objects to build a sophisticated application.
- Propeller Applications:
- consist of one or more objects.
- are compiled binary streams containing executable code and data.
- are run by the Propeller chip in one or more cogs (processors) as directed by the application.
- The topmost object in a compiled application is called the “Top Object File.”
- Applications are downloaded to either Propeller RAM only or RAM and EEPROM.
- Those in RAM will not survive power cycling or resetting the Propeller chip.
- Those in EEPROM are loaded into RAM on boot-up in approximately 1½ seconds.
- To download the current object to:
- RAM only: press F10 or select Run → Compile Current → Load RAM + Run.
- RAM + EEPROM: press F11 or select Run → Compile Current → Load EEPROM + Run.
- Spin language:
- Method means “procedure” or “routine.”
- PUB Symbol declares a public method called Symbol. Every object must contain at least one public (PUB) method.
- DIRA is the direction register for I/O pins 0-31. Each bit sets the corresponding I/O pin’s direction to input (0) or output (1).
- OUTA is the output state register for I/O pins 0-31. Each bit sets the corresponding I/O pin’s output state to low (0) or high (1).
- Registers can use indexes, like [16], to access individual bits within them.
- ~~ following a register/variable sets its bit(s) high.
- ! preceding a value/register/variable sets its bit(s) opposite their current state.
- REPEAT creates a loop structure.
- WAITCNT creates a delay
- Indention at the start of lines:
- indicates they belong to the preceding structure; it is required for lines following conditional or loop commands (like REPEAT). (Indenting is optional after block indicators, such as PUB.)
- Ctrl+I toggles visible block-group “structure” indicators on and off.
- The Propeller has eight identical processors, called cogs.
- Any number of cogs can be running or halted at any time as directed by the application.
- Each cog can run independent or cooperative tasks.
- At boot-up, Cog 0 runs the Spin Interpreter to execute the main memory-based Spin application.
- Spin language:
- Organized in blocks that have distinct purposes.
- CON - Defines global constants.
- VAR - Defines global variables.
- OBJ - Defines object references.
- PUB - Defines a public method.
- PRI - Defines a private method.
- DAT - Defines data, buffers, and assembly code.
- Block designators must be in column 1 of a line.
- Each block type can occur multiple times and can be arranged in any order.
- The very first PUB block in the very first object is the Propeller Application’s starting point.
- Underscores “_” in constants denote logical groupings, like thousands in decimal numbers.
- Types of comments:
- Code comments; visible in source code only. Great for notes to developers regarding function of specific code.
- '... –Single-line; starts at apostrophe and continues to end of line.
- {...} –Multi-line; starts and ends with single curly braces.
- Document comments; visible in source code and documentation view. Great for object documentation. Can even include schematics, timing diagrams and other special symbols.
- ''... –Single-line; starts at double-apostrophe and continues to end of line.
- {{...}} –Multi-line; starts and ends with double-curly braces.
- Spin language:
- Methods:
- To call methods in the same object, usemethod where method is the method’s name.
- Methods automatically exit, returning to their caller, when they run out of code to execute.
- When an application’s first method exits, the application and the cog it is running in terminate.
- Parameter Lists:
- Methods declare parameters in the form: method(param1, param2, etc.)
- Parameters are long-sized, local variables that are accessible from within the method only.
- They can be modified within the method but any corresponding variables used in the call are left unaffected.
- REPEAT command:
- Infinite loop: repeat
- Finite loop: repeat expression where expression evaluates to the desired number of loops to iterate through.
- Arrays:
- Arrays are defined with the form symbol [count] where symbol is the array’s symbolic name and count is the number of elements in the array.
- COGNEW command:
- Activates another cog (processor) to run either Spin or Propeller Assembly code.
- Allows for true parallel processing.
- Requires an address to reserve run-time stack space for Spin code.
- The Symbol Address operator (@) returns the address of the variable following it.
- Spin language:
- Methods:
- To call methods in another object, use object . method where object is the object’s symbolic name (given to it in the OBJ block) and method is the method’s name within that other object.
- Public (PUB) methods are an object’s interface; other objects call its public methods.
- Object View
- Illustrates the structure of the most recent successfully compiled application.
- Pointing the mouse at displayed objects displays hints about them.
- Left-clicking a displayed object either opens it up or makes it the active edit tab.
- Right-clicking a displayed object opens or switches to it in Documentation view.
- Compile Current – (F8 through F11) - compiles starting from the current object (active edit tab).
- Compile Top – (Ctrl+F8 through Ctrl+F11) - compiles starting from the Top Object File.
- Top Object File:
- Appears with a bold name in the edit tab and File List.
- Can be designated by one of the following (and compiled via Compile Top operation):
- Right-click object's edit tab and select “Top Object File,” or
- Right-click object in the File List and select “Top Object File,” or
- Choose File → Select Top Object File… menu and select object from browser, or
- Press Ctrl+T and select object from browser.
- Objects don't have to be open to be compiled; they may be compiled as the result of another object’s compilation or as the result of a Compile Top operation.
- Objects:
- Have no direct relationship with cogs.
- Should call interface methods “Start” and “Stop” if they affect other cogs.
- Should call interface method “Init” if it needs initialization.
- Spin language:
- Variables defined in variable blocks are global to the object so modifications by one method are visible by other methods.
- Booleans:
- FALSE = 0
- TRUE = -1; any non-zero (≠0) value is True for Boolean comparisons.
- Compound expressions can include intermediate assignments.
- Operators:
- “Pre”/“Post” operators perform their duty before/after the variable’s value is used by the expression.
- Assignment ‘:=’ is similar to equal ‘=’ in other languages. It sets the symbol to the left of the operator equal to the value of the symbol or expression to the right of the operator.
- Post-Clear ‘~’ clears the variable preceding it to zero (0).
- Pre-Decrement ‘- -’ decrements the variable following it, giving the expression the result.
- Is Greater Than ‘>’ returns True if value on left-side is greater than that of right-side.
- Limit Minimum ‘#>’ returns the greater of either the value on its left or its right.
- Methods:
- Always return a long value (4 bytes) whether or not one is specified.
- Contain a built-in local variable, RESULT, that holds its return value.
- Return values are declared by following the method’s name and parameters with a colon (:) and a descriptive return value name.
- COGNEW returns the ID (0 to 7) of cog started; -1 if none.
- COGSTOP deactivates a cog by ID.
- IF is a conditional structure that executes the indented block of code following it if the conditional statement is true.
- REPEAT’s conditional, one-to-many form: REPEAT WHILE Condition executes at least once and continue while Condition is true.
- The Propeller Tool bolds matching parentheses pairs surrounding the cursor.
- Applications:
- Use unique symbols, or elements of an array, for each distinct object in use.
- Use one copy of an object’s code and one or more copies of its global variables.
- Objects:
- An object array may be created in object blocks similar to a variable array in variable blocks.
- An object’s lifetime is static, consuming a specific, static amount of memory regardless of whether or not it is active. This eliminates the possibility of fragmented memory during normal run-time use and ensures deterministic behavior in real-time systems.
- Spin language:
- REPEAT command:
- Finite, counted loop: REPEAT Variable FROM Start TO Finish where Variable is the variable to use as the counter and Start and Finish indicate the range.
- The QUIT command works inside REPEAT loops only and causes the loop to terminate immediately.
- I/O registers (DIRx, OUTx, and INx) may use the form reg[a..b] to affect multiple contiguous pins; where reg is the register (DIRx, OUTx, or INx) and a and b are I/O pin numbers.
- I/O pins are set to outputs only while a cog that set them that way remains active.
- Compile and View Info: F8 key (or select Run → Compile Current → View Info).
- Clock:
- The internal clock has two speeds, slow (≈ 20 kHz) and fast (≈ 12 MHz).
- To specify clock settings for an application, the top object file sets values for one or more special constants: _CLKMODE, _CLKFREQ and _XINFREQ.
- Whenever external crystals or clocks are used, either _XINFREQ or _CLKFREQ must be specified in addition to _CLKMODE.
- _CLKMODE specifies the clock mode: internal/external, oscillator gain, PLL settings, etc.
- _XINFREQ specifies the frequency coming into the XI pin (Crystal Input pin.
- _CLKFREQ specifies the System Clock frequency.
- Use the internal clock for convenience where accuracy doesn’t matter. Use an external clock for accuracy or when the phase-locked loop (PLL) is needed.
- Timing:
- Subordinate objects can’t rely on a specific, hard-coded time-base since applications which use them may change the clock frequency.
- Use the CLKFREQ command to get the current System Clock frequency in Hertz for timing calculations.
- Propeller Library:
- Is a folder automatically created by the Propeller Tool installer.
- Contains Parallax-made Propeller objects that perform useful functions.
- The “Propeller Library” item in the Recent Folders list allows for quick access.
- Work and Library Folders:
- The Object View’s folder icons indicate the object’s location.
- Objects with yellow folders are in the “work” folder.
- Objects with blue folders are in the “library” folder.
- Every application is composed entirely of files from as many as two folders; the work folder and/or the library folder.
- Spin Language:
- The pipe symbol ‘|’ on method declaration lines declares a list of local variables for the method.
- The STRING directive creates a zero-terminated string and returns its address.
- The # symbol forms an Object-Constant reference used to access constants defined in other objects.
- The TRUNC directive truncates floating-point constants to integers.
- Integers and Real Numbers:
- Integers are directly supported both in constants and in run-time expressions.
- Real numbers, in floating-point format, are directly supported in constants and are indirectly supported at run time by special library objects.
- In many cases, expressions involving real numbers can be solved without using floating-point values and methods.
- The Status Bar displays compile information about the source item nearest to the cursor. This includes CON/DAT block symbol’s size/address and PUB/PRI/DAT block’s size.