PropellerImage Class Reference

The PropellerImage class encapsulates Propeller binary images. More...

#include <PropellerImage>

Public Types
enum	ImageType { Invalid, Binary, Eeprom }

Public Member Functions
	PropellerImage (QByteArray image=QByteArray(), QString filename="")
Image Validation
quint8	checksum ()
bool	checksumIsValid ()
bool	isValid ()
bool	recalculateChecksum ()
Image Information
QString	fileName ()
ImageType	imageType ()
QString	imageTypeText ()
quint32	imageSize ()
quint32	programSize ()
quint32	variableSize ()
quint32	stackSize ()
quint16	startOfCode ()
quint16	startOfVariables ()
quint16	startOfStackSpace ()
Low-Level Functions
QByteArray	data ()
void	setData (QByteArray image)
quint8	readByte (int pos)
quint16	readWord (int pos)
quint32	readLong (int pos)
void	writeByte (int pos, quint8 value)
void	writeWord (int pos, quint16 value)
void	writeLong (int pos, quint32 value)
Clock Settings
quint32	clockFrequency ()
void	setClockFrequency (quint32 frequency)
quint8	clockMode ()
QString	clockModeText ()
QString	clockModeText (quint8 value)
bool	setClockMode (quint8 value)

Detailed Description

The PropellerImage class encapsulates Propeller binary images.

• Converts between binary and EEPROM image formats
• Extract information about binaries
• Ability to customize and retarget binaries
• Can validate images for accuracy

Propeller Application Format

The Propeller Application image consists of data blocks for initialization, program, variables, and data/stack space. The first block, initialization, describes the application's startup parameters, including the position of the other blocks within the image, as shown below.

data size	address	description
long	0	Clock Frequency
byte	4	Clock Mode
byte	5	Checksum (this value causes additive checksum of bytes 0 to ImageLimit-1 to equal 0)
word	6	Start of Code pointer (must always be $0010)
word	8	Start of Variables pointer
word	10	Start of Stack Space pointer
word	12	Current Program pointer (points to first public method of object)
word	14	Current Stack Space pointer (points to first run-time usable space of stack)

What Gets Downloaded

To save time, PropellerManager does not download the entire application image. Instead, it downloads only the parts of the image from long 0 through the end of code (up to the start of variables) and then the Propeller chip itself writes zeros (0) to the rest of the RAM/EEPROM, after the end of code (up to 32 Kbytes), and inserts the initial call frame in the proper location. This effectively clears (initializes) all global variables to zero (0) and sets all available stack and free space to zero (0) as well.

Member Enumeration Documentation

enum PropellerImage::ImageType

An enumeration containing all Propeller image types that PropellerManager supports.

Enumerator
Invalid	Not a valid image file.
Binary	Program data-only image files (usually have a .binary extension)
Eeprom	Complete EEPROM images (usually have a .eeprom extension)

Constructor & Destructor Documentation

PropellerImage::PropellerImage	(	QByteArray	image = QByteArray(),
		QString	filename = ""
	)

Member Function Documentation

quint8 PropellerImage::checksum

(

)

Returns the checksum of the image.

A valid checksum has a value of zero.

bool PropellerImage::checksumIsValid

(

)

Returns whether the checksum of the image is valid.

Returns

true if valid, otherwise false.

quint32 PropellerImage::clockFrequency

(

)

Returns the current clock frequency of the image.

Returns

a 32-bit unsigned value containing the clock frequency in Hertz.

quint8 PropellerImage::clockMode

(

)

Get an 8-bit integer containing the current clock mode.

QString PropellerImage::clockModeText

(

)

Get a human-readable string of the current clock mode.

QString PropellerImage::clockModeText

(

quint8

value

)

Get a human-readable string of any known clock mode.

QByteArray PropellerImage::data

(

)

Returns the raw binary data of the image.

QString PropellerImage::fileName

(

)

Returns the filename associated with this image.

quint32 PropellerImage::imageSize

(

)

Total size of stored image file on disk.

PropellerImage::ImageType PropellerImage::imageType

(

)

Returns the ImageType of the image, or ImageType::Invalid.

QString PropellerImage::imageTypeText

(

)

Returns a human-readable string of the ImageType.

bool PropellerImage::isValid

(

)

Returns whether the image appears to be valid.

Returns

true if valid, otherwise returns false.

quint32 PropellerImage::programSize

(

)

Size of the application code. This value will be larger than the total file size for PropellerImage::Binary images.

This value is equivalent to startOfStackSpace().

quint8 PropellerImage::readByte

(

int

pos

)

Read a byte from address pos of the image.

Returns

an 8-bit unsigned value.

quint32 PropellerImage::readLong

(

int

pos

)

Read a long from address pos of the image.

Note

This function does not perform long-align on the address passed.

Returns

a 32-bit unsigned value.

quint16 PropellerImage::readWord

(

int

pos

)

Read a word from address pos of the image.

Note

This function does not perform word-align on the address passed.

Returns

a 16-bit unsigned value.

bool PropellerImage::recalculateChecksum

(

)

void PropellerImage::setClockFrequency

(

quint32

frequency

)

Sets a new clock frequency for the image.

bool PropellerImage::setClockMode

(

quint8

value

)

Sets a new clock mode for the image.

void PropellerImage::setData

(

QByteArray

data

)

Sets the raw binary data of the image.

quint32 PropellerImage::stackSize

(

)

Size in bytes of portion of image data used for stack space, or otherwise free.

quint16 PropellerImage::startOfCode

(

)

Start of Code pointer (address 0x06). This value must always be equal to $0010.

quint16 PropellerImage::startOfStackSpace

(

)

Start of Stack Space pointer (address 0x0A). Otherwise known as DBase.

quint16 PropellerImage::startOfVariables

(

)

Start of Variables pointer (address 0x08).

quint32 PropellerImage::variableSize

(

)

Returns the size in bytes of image data used for variables.

void PropellerImage::writeByte	(	int	pos,
		quint8	value
	)

Write a byte-sized value to the image at pos.

void PropellerImage::writeLong	(	int	pos,
		quint32	value
	)

Write a long-sized value to the image at pos.

Note

This function does not perform long-align on the address passed.

void PropellerImage::writeWord	(	int	pos,
		quint16	value
	)

Write a word-sized value to the image at pos.

Note

This function does not perform word-align on the address passed.