Documentation‎ > ‎

Propeller Loader

The Propeller Loader (propeller-load) is a command line program used to load programs generated by the PropellerGCC toolchain into a Propeller board. It loads over a serial connection from a PC running Windows, Mac OS X, or Linux. It can also load Spin binary programs generated by programs like the Propeller Tool or BST. 

For a friendly introduction to the propeller-load utility, take a look at the tutorial.

To download an elf file to your Propeller, simply use

user@desktop:~$ propeller-load -r main.elf

This will download the code to the first found Propeller chip and start it running. To download to EEPROM, use

user@desktop:~$ propeller-load -r -e main.elf

If you want a terminal as well add the -t flag.

The full help message for propeller-load is

user@desktop:~$ propeller-load
usage: propeller-load
         [ -b <type> ]     select target board (default is 'default:default')
         [ -p <port> ]     serial port (default is to auto-detect the port)
         [ -P ]            list available serial ports
         [ -I <path> ]     add a directory to the include path
         [ -D var=value ]  define a board configuration variable
         [ -e ]            write the program into EEPROM
         [ -r ]            run the program after loading
         [ -g ]            set up the program for debugging after loading
         [ -s ]            write a spin .binary file for use with the Propeller Tool
         [ -x ]            write a .pex binary file for use with the SD loader or SD cache
         [ -l ]            write a program to the sd card and use the SD loader
         [ -z ]            write a program to the sd card and use the SD cache
         [ -f ]            write a file to the SD card
         [ -t ]            enter terminal mode after running the program
         [ -t<baud> ]      enter terminal mode with a different baud rate
         [ -q ]            quit on the exit sequence (0xff, 0x00, status)
         [ -v ]            verbose output
         [ -S ]            slow down the loader by adding 5 microseconds delay
         [ -S<n> ]         slow down the loader by adding <n> microseconds delay
         [ -? ]            display a usage message and exit
         <name>            elf or spin binary file to load

Target board type can be either a single identifier like 'propboe' in which case the subtype
defaults to 'default' or it can be of the form <type>:<subtype> like 'c3:ram'.

Variables that can be set with -D are:
  clkfreq clkmode baudrate reset rxpin txpin tvpin
  cache-driver cache-size cache-param1 cache-param2
  sd-driver sdspi-do sdspi-clk sdspi-di sdspi-cs
  sdspi-clr sdspi-inc sdspi-start sdspi-width spdspi-addr
  sdspi-config1 sdspi-config2 eeprom-first

Value expressions for -D can include:
  rcfast rcslow xinput xtal1 xtal2 xtal3 pll1x pll2x pll4x pll8x pll16x k m mhz true false
  an integer or two operands with a binary operator + - * / % & | or unary + or -
  all operators have the same precedence

The -b option defaults to the value of the environment variable PROPELLER_LOAD_BOARD.
The -p option defaults to the value of the environment variable PROPELLER_LOAD_PORT
if it is set. If not the port will be auto-detected.

The 'sd loader' loads AUTORUN.PEX from an SD card into external memory.
It requires a board with either external RAM or ROM.

The 'sd cache' arranges to run AUTORUN.PEX directly from the SD card.
It can be used on any board with an SD card slot.

Board Configuration Files

When you use the -b command line option and you keep on getting the error:

error: can't find board configuration 'my_board.cfg'

You should try again without the .cfg extension.

Variable Patching

You can use propeller-load to "patch" in variables. This allows you to wait until runtime for variable values, and is particularly useful for assigning pin numbers. See the attached documentation for details.

One point that is missing is that your variables cannot be declared "const". If you do, then the compiler may optimize them out and the loader won't patch them.

You should declare your variables like:

const int _cfg_mypin = -1;

(i.e. without the const).

Please see the attached document for the complete description and use of the Propeller Loader.
David Betz,
Jun 14, 2012, 6:30 PM