Propeller Device Specific Functions and Registers  v0.5
Provides low level access to Propeller microcontroller functions and registers.
Macros | Functions
propeller.h File Reference

Provides Propeller specific functions. More...

#include "cog.h"
#include <stdint.h>
#include <string.h>

Go to the source code of this file.

Macros

#define HUBDATA   __attribute__((section(".hub")))
 HUBDATA tells compiler to put data into HUB RAM section. This is mostly useful in XMM modes where data must be shared in hub.
#define HUBTEXT   __attribute__((section(".hubtext")))
 HUBTEXT tells compiler to put code into HUB RAM section.
#define PAR   _PAR
 Parameter register is used for sharing HUB RAM address info with the COG.
#define CNT   _CNT
 The system clock count.
#define INA   _INA
 Use to read the pins when corresponding DIRA bits are 0.
#define INB   _INB
 Unused in P8X32A.
#define OUTA   _OUTA
 Use to set output pin states when corresponding DIRA bits are 1.
#define OUTB   _OUTB
 Unused in P8X32A.
#define DIRA   _DIRA
 Use to set pins to input (0) or output (1).
#define DIRB   _DIRB
 Unused in P8X32A.
#define CTRA   _CTRA
 Counter A control register.
#define CTRB   _CTRB
 Counter B control register.
#define FRQA   _FRQA
 Counter A frequency register.
#define FRQB   _FRQB
 Counter B frequency register.
#define PHSA   _PHSA
 Counter A phase accumulation register.
#define PHSB   _PHSB
 Counter B phase accumulation register.
#define VCFG   _VCFG
 Video Configuration register can be used for other special output.
#define VSCL   _VSCL
 Video Scale register for setting pixel and frame clocks.
#define CLKFREQ   _CLKFREQ
 Returns the current clock frequency.
#define CLKMODE   _CLKMODE
 Returns the current clock mode.
#define clkset(mode, frequency)
 Set clock mode and frequency.
#define cogid()   __builtin_propeller_cogid()
 Return the id of the current cog.
#define coginit(id, code, param)
 Start a cog with a parameter.
#define cognew(code, param)   coginit(0x8, (code), (param))
 Start a new Propeller PASM COG.
#define cogstop(a)   __builtin_propeller_cogstop((a))
 Stop a COG.
#define locknew()   __builtin_propeller_locknew()
 Get a new lock.
#define lockret(lockid)   __builtin_propeller_lockret((lockid))
 Return lock to pool.
#define lockset(lockid)   __builtin_propeller_lockset((lockid))
 Set a lock.
#define lockclr(lockid)   __builtin_propeller_lockclr((lockid))
 Clear lock.
#define waitcnt(a)   __builtin_propeller_waitcnt((a),0)
 Wait until system counter reaches a value.
#define waitcnt2(a, b)   __builtin_propeller_waitcnt((a),(b))
 Wait until system counter reaches a value.
#define waitpeq(state, mask)   __builtin_propeller_waitpeq((state), (mask))
 Wait until INA equal state & mask.
#define waitpne(state, mask)   __builtin_propeller_waitpne((state), (mask))
 Wait until INA not equal state & mask.
#define waitvid(colors, pixels)   __builtin_propeller_waitvid((colors), (pixels))
 Wait for video generator to accept pixel info.
#define use_cog_driver(id)   extern uint32_t binary_##id##_dat_start[]
 Make the load symbols available for a driver.
#define get_cog_driver(id)   (binary_##id##_dat_start) \
 Get a hub memory buffer containing a driver image.
#define load_cog_driver(id, param)   cognew(binary_##id##_dat_start, (uint32_t *)(param))
 Load a COG driver.

Functions

int cogstart (void(*func)(void *), void *par, void *stack, size_t stacksize)
 Start a new propeller LMM function/thread in another COG.

Detailed Description

Provides Propeller specific functions.

Copyright (c) 2011-2012 by Parallax, Inc. MIT Licensed

Macro Definition Documentation

#define clkset (   mode,
  frequency 
)
Value:
do { \
_CLKFREQ = (frequency); \
_CLKMODE = (mode); \
__builtin_propeller_clkset(mode); \
} while(0)

Set clock mode and frequency.

This macro is used to set the run-time clock mode and frequency. The clock mode and frequency are normally configured by the loader based on the user selected board type.

Please see the Propeller Data Sheet for more clock information.

Parameters
modeThe 8 bit clock mode
frequencyThe 32 bit clock frequency
Returns
This macro will not return a value.
#define cogid ( )    __builtin_propeller_cogid()

Return the id of the current cog.

Sometimes we need to know which COG is running the program. cogid returns that value.

Returns
ID number of current COG
#define coginit (   id,
  code,
  param 
)
Value:
__builtin_propeller_coginit( \
(((uint32_t)(param) << 16) & 0xfffc0000) \
|(((uint32_t)(code) << 2) & 0x0003fff0) \
|(((id) ) & 0x0000000f) )

Start a cog with a parameter.

The fields in parameters are:

  • 31:18 = 14-bit Long address for PAR Register
  • 17:4 = 14-bit Long address of CODE to load
  • 3 = New bit
  • 2:0 = Cog ID. New bit 3 is 0.

It is important to realize that a 14 bit address means that long aligned addresses or pointers should be use. That is if you pass a value to the PAR such as 3, the value will be truncated to 0. A value 5 will be interpreted as 4.

Parameters
idThe COG id to initialize
codeStart address of PASM code to load.
paramPAR address
Returns
COG ID provided by the builtin function or -1 on failure.
#define cognew (   code,
  param 
)    coginit(0x8, (code), (param))

Start a new Propeller PASM COG.

This is use to start a COG with code compiled as PASM, AS, or COG-C. PASM can be any Spin/PASM code that is self-contained. That is, all data for initialization and mailbox use are passed via the par parameter. Changing PASM variables from SPIN code will not work with this method.

GAS and COG-C programs have similar restrictions. COG-C programs should not use any stack or variables in HUB memory that are not accessed via PAR mailbox or pointers.

Parameters
codeAddress of PASM to load
paramValue of par parameter usually an address
Returns
COG ID provided by the builtin function or -1 on failure.
#define cogstop (   a)    __builtin_propeller_cogstop((a))

Stop a COG.

Parameters
aThe COG ID
#define get_cog_driver (   id)    (binary_##id##_dat_start) \

Get a hub memory buffer containing a driver image.

Parameters
idThe COG driver name
#define HUBTEXT   __attribute__((section(".hubtext")))

HUBTEXT tells compiler to put code into HUB RAM section.

This is a GCC super-power. Put code in HUB RAM even in XMM modes. Sometimes code in XMM programs is time sensitive.

Use HUBTEXT before a function declaration to make sure code is run from HUB instead of external memory. Performance of code run from external memory is unpredictable across platforms.

#define load_cog_driver (   id,
  param 
)    cognew(binary_##id##_dat_start, (uint32_t *)(param))

Load a COG driver.

Parameters
idThe COG driver name
paramParameter to pass to the driver
Returns
the id of the COG that was loaded
#define lockclr (   lockid)    __builtin_propeller_lockclr((lockid))

Clear lock.

Parameters
lockid
#define locknew ( )    __builtin_propeller_locknew()

Get a new lock.

Returns
new lockid
#define lockret (   lockid)    __builtin_propeller_lockret((lockid))

Return lock to pool.

Parameters
lockid
#define lockset (   lockid)    __builtin_propeller_lockset((lockid))

Set a lock.

Parameters
lockid
Returns
true on success
#define use_cog_driver (   id)    extern uint32_t binary_##id##_dat_start[]

Make the load symbols available for a driver.

Parameters
idThe COG driver name
#define waitcnt (   a)    __builtin_propeller_waitcnt((a),0)

Wait until system counter reaches a value.

Parameters
aTarget value
#define waitcnt2 (   a,
 
)    __builtin_propeller_waitcnt((a),(b))

Wait until system counter reaches a value.

Parameters
aTarget value
bAdjust value
#define waitpeq (   state,
  mask 
)    __builtin_propeller_waitpeq((state), (mask))

Wait until INA equal state & mask.

Parameters
stateTarget value
maskIgnore masked 0 bits in state
#define waitpne (   state,
  mask 
)    __builtin_propeller_waitpne((state), (mask))

Wait until INA not equal state & mask.

Parameters
stateTarget value
maskIgnore masked 0 bits in state
#define waitvid (   colors,
  pixels 
)    __builtin_propeller_waitvid((colors), (pixels))

Wait for video generator to accept pixel info.

Parameters
colorsA long containing four byte-sized color values, each describing the four possible colors of the pixel patterns in Pixels.
pixelsThe next 16-pixel by 2-bit (or 32-pixel by 1-bit) pixel pattern to display.

Function Documentation

int cogstart ( void(*)(void *)  func,
void *  par,
void *  stack,
size_t  stacksize 
)

Start a new propeller LMM function/thread in another COG.

This function starts a new LMM VM kernel in a new COG with func as the start function. The stack size must be big enough to hold the struct _thread_state_t, the initial stack frame, and other stack frames used by called functions.

This function can be used instead of _start_cog_thread.

Parameters
funcLMM start function
parValue of par parameter usually an address
stackAddress of user defined stack space.
stacksizeSize of user defined stack space.
Returns
COG ID allocated by the function or -1 on failure.