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

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.