Provides Propeller specific functions. More...

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

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.

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

mode	The 8 bit clock mode
frequency	The 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

id	The COG id to initialize
code	Start address of PASM code to load.
param	PAR 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

code	Address of PASM to load
param	Value 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

a	The COG ID

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

Get a hub memory buffer containing a driver image.

Parameters

id	The 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

id	The COG driver name
param	Parameter 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

id	The COG driver name

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

Wait until system counter reaches a value.

Parameters

a	Target value

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

Wait until system counter reaches a value.

Parameters

a	Target value
b	Adjust value

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

Wait until INA equal state & mask.

Parameters

state	Target value
mask	Ignore masked 0 bits in state

#define waitpne	(	state,
		mask
	)	__builtin_propeller_waitpne((state), (mask))

Wait until INA not equal state & mask.

Parameters

state	Target value
mask	Ignore masked 0 bits in state

#define waitvid	(	colors,
		pixels
	)	__builtin_propeller_waitvid((colors), (pixels))

Wait for video generator to accept pixel info.

Parameters

colors	A long containing four byte-sized color values, each describing the four possible colors of the pixel patterns in Pixels.
pixels	The 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

func	LMM start function
par	Value of par parameter usually an address
stack	Address of user defined stack space.
stacksize	Size of user defined stack space.

Returns: COG ID allocated by the function or -1 on failure.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation