PropWare  3.0.0.229
C++ objects and CMake build system for Parallax Propeller
Macros | Functions
propeller.h File Reference

Provides Propeller specific functions. More...

#include "cog.h"
#include <stdint.h>
#include <string.h>
#include <sys/thread.h>
#include "propeller1.h"
+ Include dependency graph for propeller.h:
+ This graph shows which files directly or indirectly include this file:

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. More...
 
#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. More...
 
#define cogid()   __builtin_propeller_cogid()
 Return the id of the current cog. More...
 
#define cognew(code, param)   coginit(0x8, (code), (param))
 Start a new Propeller PASM COG. More...
 
#define cogstop(a)   __builtin_propeller_cogstop((a))
 Stop a COG. More...
 
#define EXTRA_STACK_BYTES   (16 + sizeof(_thread_state_t))
 
#define EXTRA_STACK_LONGS   (EXTRA_STACK_BYTES / 4)
 
#define locknew()   __builtin_propeller_locknew()
 Get a new lock from the pool of Propeller hardware locks. More...
 
#define lockret(lockid)   __builtin_propeller_lockret((lockid))
 Return lock to pool. More...
 
#define lockset(lockid)   __builtin_propeller_lockset((lockid))
 Set a lock. More...
 
#define lockclr(lockid)   __builtin_propeller_lockclr((lockid))
 Clear lock. More...
 
#define waitcnt(a)   __builtin_propeller_waitcnt((a),0)
 Wait until system counter reaches a value. More...
 
#define waitcnt2(a, b)   __builtin_propeller_waitcnt((a),(b))
 Wait until system counter reaches a value. More...
 
#define waitpeq(state, mask)   __builtin_propeller_waitpeq((state), (mask))
 Wait until INA equal state & mask. More...
 
#define waitpne(state, mask)   __builtin_propeller_waitpne((state), (mask))
 Wait until INA not equal state & mask. More...
 
#define waitvid(colors, pixels)   __builtin_propeller_waitvid((colors), (pixels))
 Wait for video generator to accept pixel info. More...
 
#define use_cog_driver(id)   extern uint32_t binary_##id##_dat_start[]
 Make the load symbols available for a driver. More...
 
#define get_cog_driver(id)   (binary_##id##_dat_start) \
 Get a hub memory buffer containing a driver image. More...
 
#define load_cog_driver(id, param)   cognew(binary_##id##_dat_start, (uint32_t *)(param))
 Load a COG driver. More...
 

Functions

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

Detailed Description

Provides Propeller specific functions.

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

Definition in file propeller.h.

Macro Definition Documentation

◆ clkset

#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.

Definition at line 63 of file propeller.h.

◆ cogid

#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
Examples
Runnable_Demo.cpp, and SynchronousPrinter_Demo.cpp.

Definition at line 76 of file propeller.h.

◆ cognew

#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.
Examples
BufferedUART_Demo.cpp, and Cogc_Demo.cpp.

Definition at line 94 of file propeller.h.

◆ cogstop

#define cogstop (   a)    __builtin_propeller_cogstop((a))

Stop a COG.

Parameters
aThe COG ID

Definition at line 100 of file propeller.h.

◆ EXTRA_STACK_BYTES

#define EXTRA_STACK_BYTES   (16 + sizeof(_thread_state_t))

EXTRA_STACK_BYTES is the number of additional bytes you need for a stack passed to cogstart beyond what is actually needed by the function being started.

Definition at line 112 of file propeller.h.

◆ EXTRA_STACK_LONGS

#define EXTRA_STACK_LONGS   (EXTRA_STACK_BYTES / 4)

EXTRA_STACK_LONGS is the number of additional longs you need for a stack passed to cogstart beyond what is actually needed by the function being started.

Definition at line 120 of file propeller.h.

◆ get_cog_driver

#define get_cog_driver (   id)    (binary_##id##_dat_start) \

Get a hub memory buffer containing a driver image.

Parameters
idThe COG driver name

Definition at line 327 of file propeller.h.

◆ HUBTEXT

#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.

Definition at line 43 of file propeller.h.

◆ load_cog_driver

#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

Definition at line 335 of file propeller.h.

◆ lockclr

#define lockclr (   lockid)    __builtin_propeller_lockclr((lockid))

Clear lock.

Warning
This function does not precisely follow the Spin semantics described in the Propeller Manual. In particular, it does not return a value.
Parameters
lockid(0 through 7, int type)

Definition at line 170 of file propeller.h.

◆ locknew

#define locknew ( )    __builtin_propeller_locknew()

Get a new lock from the pool of Propeller hardware locks.

Note
this function follows the Spin semantics described in the Propeller Manual.
Warning
The lock my be in either the set or cleared state: a new lock is not guarenteed to be cleared.
Returns
new lockid (0 through 7) on success, -1 on failure (result is int type)
Examples
BufferedUART_Demo.cpp.

Definition at line 147 of file propeller.h.

◆ lockret

#define lockret (   lockid)    __builtin_propeller_lockret((lockid))

Return lock to pool.

Note
this function follows the Spin semantics described in the Propeller Manual.
Warning
The lock is returned in it's current state (set or cleared).
Parameters
lockid(0 through 7, int type)

Definition at line 155 of file propeller.h.

◆ lockset

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

Set a lock.

Note
this function follows the Spin semantics described in the Propeller Manual.
Parameters
lockid(0 through 7, int type)
Returns
int with the previous state of the lock: -1 (0xFFFFFFFF) when the previous state was set, 0 when the previous state was not set.

Definition at line 163 of file propeller.h.

◆ use_cog_driver

#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

Definition at line 321 of file propeller.h.

◆ waitcnt

#define waitcnt (   a)    __builtin_propeller_waitcnt((a),0)

◆ waitcnt2

#define waitcnt2 (   a,
 
)    __builtin_propeller_waitcnt((a),(b))

Wait until system counter reaches a value.

Parameters
aTarget value
bAdjust value
Examples
ADXL345_Demo.cpp, L3G_Demo.cpp, MultiCogBlinky_Demo.cpp, and SynchronousPrinter_Demo.cpp.

Definition at line 183 of file propeller.h.

◆ waitpeq

#define waitpeq (   state,
  mask 
)    __builtin_propeller_waitpeq((state), (mask))

Wait until INA equal state & mask.

Parameters
stateTarget value
maskIgnore masked 0 bits in state

Definition at line 190 of file propeller.h.

◆ waitpne

#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

Definition at line 197 of file propeller.h.

◆ waitvid

#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.

Definition at line 205 of file propeller.h.

Function Documentation

◆ cogstart()

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.
+ Here is the caller graph for this function: