bst tools User Manual v 0.04 30 Apr 2010
Contents
1. 8 1 Disclaimer of Warranty THERE IS NO WARRANTY FOR THE PROGRAM TO THE EXTENT PERMITTED BY APPLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFECTIVE YOU ASSUME THE COST OF ALL NECESSARY SERVICING REPAIR OR CORRECTION 8 2 Limitation of Liability IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER BE LIABLE TO YOU FOR DAMAGES INCLUDING ANY GENERAL SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES bst manual 0 04 30 Apr 2010 Page 31 Copyright Brad Campbell Viridian Consulting 20102. Viridian Consulting 2010 4 7 Under the bonnet hood VIRIDIAN Consulting To work around an issue with a particular operating system not properly saving the recovery file before the entire OS crashed trying to access the Propellers serial port bst saves each recovery file with the new postfix It then removes the old recovery file and renames the new one This ensures that the file is properly on disk or in the filesystems journal before the old one is removed and provides an additional safety net The contents of the recovery file is relatively simple but is composed of binary streams and metadata We ve not yet had to manually parse one so the recovery mechanism seems relatively stable Copyright Brad Campbell Viridian Consulting 2010 bst_manual_0 04 30 Apr 2010 Page 22 5 SPIN Language Extensions SC IRIDIAN Consulting 5 SPIN Language Extensions Like Michael Park s homespun compiler bstc has some extensions to the reference spin language These are minor additions that are seen to enhance the usability of the language under certain circumstances however they render the source files incompatible with the Parallax Spin Compiler All of these extensions require at a minimum the Ox command line parameter to enable the Non Parallax Compatible Extension option in the compiler 5 1 define and friends bst has a very basic conditional pre processor built into the tokeniser This allows the conditional compilation
3. PUB hex value digits S PUB out c i k P wu a Rab E ege E ao example shown we clicked between the t and the ze a v to make sure the cursor was in on the word and 51 st 521 EE pressed Ctrl Space The export table pops up to 53 text s d S i 54 led start display the available functions in the object 4 3 3 Context menu Select Files Directory IE goertzel_demo ty pu Stop 4h Bivan Boat D 4 T f p Picd2usb S Stop TV driver rees a cog LcD Interface 47 if cog 48 cogstop cog 1 Bi PropBasic 49 b SpinStart 50 stuff 51 EDAT Open Object under Cursor D B Test Project ee i Thermostat AO 4 ES 54 Assembly language 1 Save All ne S 56 a AD8803 spin 56 Close S 57 Close All ADC spin h 58 Close all but Current Clock spin 59 SS COILREAD spin 60 Entry EA z Often when working on files in systems with a large quantity of library directories it s handy to be able to browse other library files in the same directory By selecting this item in a tab s context menu the directory tree is immediately taken to the location of the source file and the file selector box populated with its contents It s also handy for checking the location of sub objects that throw errors or warnings bst manual 0 04 30 Apr 2010 Page 15 Copyright Brad Campbell Viridian Consulting 2010 4 3 Using bst VIRIDIAN Consulting 4 3 4
4. of code based on symbol definitions It behaves similarly to most other conditional compilation directives in other languages but has a few important points worth noting e Defined symbols are global and therefore passed down to any source file compiled after the file in which the symbol was defined e Symbols are not allowed to contain spaces the first encounter whitespace delimits the symbol e Any text after a symbol on a pre processor line is ignored e define _am_a_symbol fred woz ere lt fred woz ere is completely ignored bstc supports define undef ifdef ifndef elseifdef elseifndef else endif as conditional statements bstc also supports info warn error to allow comments to be inserted in the list file or compilation to be halted with a user definable error message Unlike the conditional statements the info warn error lines accept any message and will continue until the end of line 5 2 The absolute address operator In SPIN methods there are the amp operators In PASM you have In all contexts they mean different things In SPIN means Give me the HUB address of that variable The interpreter does this at runtime as it only knows the absolute address when it know where it is in the Propeller This applies to global VAR Local PUB PRI and PASM DAT variables The always returns the address of that variable in the HUB In SPIN means give me the compi
5. Context menu Open Object Under Cursor 35 num Simple Nun 36 Chase Chase 001 37 ou One_wire F 38 tv 39 sd mto 40 rf Save SP 41 tx Save All B_SF 42 er 23 43 Close 2 44 pub m Close All La 4 After a successful compile and prior to the source being modified placing the cursor on the symbol of a sub object will cause the Open Object under Cursor item to be enabled in the context menu It does precisely what it says and simply opens the sub object in a new tab or selects the objects tab if it s already open 4 3 5 Ctri G Context menu Go to line In large source files it is convenient to be able to jump directly to a specific line This menu opens a small dialog to allow you to enter the desired line to jump to 4 3 6 Code Folding Code folding is a neat addition to any source editor when working on large source files It enables individual methods to be worked on without the clutter of nearby source code and the convenience of the displayed adjacent code headers 9 EDAT e 14 EVAR Select files direcotry 30 DR 44 pub main X Cut 97 PUB Boot SD copy 105 RRI Get_Temper past 11145 ARI DS1307_ den 26 P I tempout va Go to Line 26 cd dec val 26 lcd pute 1 Compile 2 f val amp 1 Compile Information 387 PRI StrCat Y X bst_manual_0 04 30 Apr 2010 e E l He pute i Compile and Load Ram 26
6. IdevittyUSB1 scan O Save Before Compile O Standard Tabs Idevittys3 ee 5 Save interval in minutes O Smart Tabs IdevittyS2 Test Parall Configure Ports JE SES IdevittyS1 Port Select aes per edit tab fa E Tab Size Default 8 devjttySO Manual Re open last active project on startup NM Auto New file template directory Find Prop rowse eege Port we will use to try and talk to Propeller devittyUSB1 The Browse button is irrelevant on Windows On Linux amp OSX it allows you to browse the filesystem looking for the port you are after nix Everything is a file Rescan will refresh the box looking for any ports that might have been added since you opened the search box ever wondered where your Prop was and realised it was not plugged in Test will attempt to connect to a Propeller on the selected port and query its version information If you have a port selected manually there is a port name in the bottom box dev ttyUSB1 above the Auto button will clear that and put bst back into auto detect mode Find Prop will try and test every detected serial port on the system sequentially until it detects a Propeller It will then leave that port manually selected You can also type the port name or direct path into the box at the bottom to manually force bst to use a certain port Generally leaving things set to auto just works If it should and it doesn t we d like to hear about i
7. It loses its source contents when closed but can be closed and opened at any time See Section 7 for a basic explanation of the contents of the list file bst manual 0 04 30 Apr 2010 Page 18 Copyright Brad Campbell Viridian Consulting 2010 48 The Project ft VIRIDIAN Consulting 4 5 The Project File A Project is simply an extended set of preferences that defines Which source files are open Where each source file is scrolled to What parts of each source file are folded Optionally Which Propeller Serial Port is assigned to each source file A project specific set of Pre Processor Symbol definitions A project specific set of compiler options A project specific set of compiler search paths Which directory the Directory Tree is pointing to When a new project file is created it simply takes all the settings from the current session Additionally to facilitate complex or special configurations you can define separate compiler search paths and compiler optimisation options in the Project Options dialog This allows you to override the global search path and options settings defined in the bst configuration The search path is overridden if there are any search paths defined in the Project Options The compiler optimisations require you to check the Override global compiler optimisations box before they take effect Opening a project file will see all tabs restored to precisely where they were when the project was
8. as a test for the cross platform toolchain and to experiment with different algorithms for loading the Propeller chip The program is dual purpose which is to take a Propeller binary binary or eeprom eeprom file as generated by the Propeller Tool and load it into a Propeller chip via a serial port or suck the program out of a Propeller chip and save it back as an eeprom file Asking bstl for its command line options will give you the following Program Usage bstl Options lt FileName gt d lt filename gt Serial device to use Default dev ttyUSB1 p 123 Program Mode 1 Ram only Default 2 Eeprom and shutdown 3 Eeprom and Run f Load at high speed t Test mode Undocumented 1 Test mode Undocumented h Show this help u Read Propellers EEPROM into file lt FileName gt WARNING will overwrite it if it exists with no prompt On Linux amp OSX it will attempt to autodetect the first USB gt Serial port as encountered when using a Parallax PropPlug or generic PL2303 converter On Win32 it will simply try COM2 If it does not find your Propeller you must tell it where it is using the d command line option The f option runs the download at twice the baud rate used by the Parallax tools This has the ability to shave 30 of the download time off when loading a large file If you suffer reliability issues using f simply leave it out to use the standard download speed Versions 0 07 Pr
9. b option allows you to save the compiled binary to disk in a Propeller Tool compatible binary format The binary file is saved by default to the same directory as the original top source file and named as the top source file brad bkmac proptest ls test spin brad bkmac proptestS bstc b test spin Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test Program size is 3 longs Compiled 2 Lines of Code in 0 001 Seconds brad bkmac proptest ls test binary test spin 31 Usage VIRIDIAN Consulting 3 1 3 e Saving a Propeller eeprom file to disk The e option allows you to save the compiled binary to disk in a Propeller Tool compatible eeprom format The eeprom file is saved by default to the same directory as the original top source file and named as the top source file The eeprom file format is simply an extended version of the binary format suitable to be loaded into an eeprom using an external programmer rather than the Propeller itself 3 1 4 a Creating a Propeller Source Archive The a option creates a zipped archive of your Propeller source files similar to the one created by the Create Archive function in the Parallax Propeller Tool There are a few caveats to the bstc version however e The tool will not properly archive source files that are pointed to by symbolic links e The source co
10. AW form 3 Mew Help o Errors Ctrl Shift E d Status Bar d Line Numbers Ctrl Shift L d Changed Lines Compiler Listing Terminal Hex Input Output ox bst Terminal dev ttyUSBO ormat Port Communicate The Serial terminal is fully integrated with bst such that there is no need to manually disconnect connect prior to downloading a propeller bst will check to see if the terminal is using the port it needs to download to and will manage the terminals connection in the background to ensure an uninterrupted download to the Propeller bst manual 0 04 30 Apr 2010 Page 20 Copyright Brad Campbell Viridian Consulting 2010 4 7 Under the bonnet fend VIRIDIAN Consulting 4 7 Under the bonnet hood What follows is some basic background information on some of the less visible parts of bst It may assist in debugging or understanding what is going on when something goes wrong 4 7 1 Persistent Configuration Files bst stores persistent configuration information on your system in a single location This is to allow configuration details specific preferences and niceties like recent files lists to persist across bst sessions On Linux the configuration resides in your home directory bst ini On OSX the configuration resides in your home directory Library Preferences bst ini On Win32 the configuration resides in the System Registry HKEY_CURRENT_USER software cams
11. N Consulting 3 1 13 W Error Warning levels This option controls the verbosity of the compilers output There are three levels 0 1 2 e WO Only display errors in the compilation e W1 Display errors and warnings generated Jmp without for example e W2 Display errors warnings and information Warnings are generated for common errors that have generated code that might not do what you want it to do Warnings can be disabled on a particular line for example using a variable for a jmp in PASM by adding an W as the start of a comment on that source line The information display can be a little overwhelming at times as it analyses your spin methods and tries to inform you of unused components that are consuming extra space Such as unused global and local variables amp unused SPIN methods For this reason it defaults to disabled and must be explicitly enabled with W2 to display its output The default error level is 0 3 1 14 q Be vewy vewy qwiet I m hunting Wabbits The q option is there for the hard core Makefile users who want the compiler to do what it does with the minimum of fuss or noise It will only report errors and attempt to report them in a fashion compatible with the output of the GNU compilers It s not as beginner friendly but it s far more concise 3 1 15 v Display version information Does precisely what it says on the tin bst manual 0 04 30 Apr 2010 Page 8 Copyright Brad Campbell Vi
12. Search Paths Compiler Preferences Search Paths Optimisations Options Compiler Searchpaths Imedia raid3 Viridian Work Prop Projects Library Add Unlike the Propeller Tool which has a single library path bst allows a list of paths to search for your Propeller Object files It is important before you start to configure at least your basic library path to allow the bst compiler to find your library objects These can be assigned in the Compiler Preferences dialog in the Tools menu The library paths are searched in logical order from top to bottom so if you have three FullDuplex spin files it will use the first one it finds 4 2 2 Fonts Each platform has a different way of managing fonts Windows users can install the Parallax Propeller Tool first This will install the Propeller font for you and you should be good to go On Windows Vista there can sometimes be an issue with the Propeller Font not being available to all users so you may have to locate it Propeller ttf and install it in the Control Panel Fonts widget manually before bst can see it OSX and Linux users must download a modified version of the Propeller font can t stress this enough the font supplied with the Parallax Propeller Tool is BROKEN on Linux and OSX If you install it by mistake it will cause all sorts of horrible things to occur that are hard to debug Please install the correct font The location of the correct font is kept
13. The object code of the test object is located at 0010 in the binary image and the object code of Blink is located at 0028 PBASE is the start of the object code for the first object to run after the Propeller starts up VBASE is where the variables anything declared in a VAR block start after all the object code DBASE is where the stack used by the SPIN interpreter starts The stack grows from low addresses to high PCURR is the address of the first piece of bytecode to execute when the Propeller boots DCURR is the initial stack pointer always 8 bytes higher than the start of the stack So in this example the first piece of bytecode in the Start method in object test resides at 001C in the hub and this is where execution will commence In the list file from here down each object is given its own separate section bst manual 0 04 30 Apr 2010 Page 29 Copyright Brad Campbell Viridian Consulting 2010 TaAnatomyofatstfie SC IRIDIAN Consulting 7 1 1 2 Object header Object test es Base is 0010 00000498 1032 004C4B40 5000000 Constant _clkmode Constant _xinfreq VBASE 000 LONG Size 0004 Variable Fred VBASE 0004 BYTE Size 0001 Variable Ada VBASE 0005 BYTE Size 0001 Variable Jean VBASE 0006 BYTE Size 0001 Variable May The object header details where the object resides any constants it contains or exports and what and where its variables are Constants are displ
14. a E 28 1 11 Keele EE 29 11 12 Object MSAD EE 30 L413 Spin RVG DEE 30 8 Warranty DURUM E 31 8 1 Disclaimer of Aramis dee GGEGeEeerb 31 8 2 Limitation of Ce EE 31 bst_manual_0 04 30 Apr 2010 uge VIRIDIAN Consulting 1 Introduction The bst tool set is a multi platform set of tools for developing with the Parallax Propeller microcontroller bst stands for Brad s Spin Tool however it is never capitalised The bst tool set currently targets and supports the following architectures and operating systems i386 linux gtk2 PowerPC darwin Mac OSX 10 4 gt 10 6 i386 darwin Mac OSX 10 4 gt 10 6 i386 Win32 Windows 95 gt Windows 7 The current tool kit consists of three parts 1 bstl The command line loader unloader 2 bstc The command line loader compiler 3 bst The fully integrated GUI IDE The latest version of the bst tools can always be found linked from http www fnarfbargle com bst html There are often development snapshots posted to http www fnarfbargle com bst snapshots The code in the snapshot directory is very much a work in progress and often represents experimental features as the development progresses It has the potential to be unstable or break badly If it breaks you do however get to keep both pieces Copyright Brad Campbell Viridian Consulting 2010 bst_manual_0 04 30 Apr 2010 Page 1 EE 2 bstl Command Line Loader Unloader bstl was developed initially
15. a basic explanation of the contents of the list file 3 1 10 L Library Path This option specifies where the compiler might search for library source files It may be specified as many times as you like to list multiple library directories The compiler will always try the same directory as the source file first then it will search the library paths in the order given for sub object files 3 1 11 o Output Filename By default all output files binary eeprom dat list are named with the same file name as the source file The o parameter allows you to specify an alternate name for the output files The following example compiles test spin into a binary named john binary rad bkmac proptestS bere o john b ls test spin Brads Spin Tool Compiler v 15 4 pre1 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 22 00 13 on 2010 04 21 Loading Object test Loading Object Blink Program size is 12 longs Compiled 16 Lines of Code in 0 035 Seconds brad bkmac proptestS ls blink spin john binary john list test spin The compiler automatically names the extension of the filename appropriately 3 1 12 O Optimisation options bstc has the ability to perform some basic optimisation on the source being compiled See Section 6 for details and function of the available options bst manual 0 04 30 Apr 2010 Page 7 Copyright Brad Campbell Viridian Consulting 2010 31 Usage VIRIDIA
16. al 0 04 30 Apr 2010 Page 25 Copyright Brad Campbell Viridian Consulting 2010 Compiler optimisation zg VIRIDIAN Consulting 6 Compiler optimisation options The Parallax compiler is a relatively straight forward compiler It simply translates what you have in your source file into object code and compiles the object code into a single binary file bstc has a few extra tweaks that can potentially save some space in the resulting memory map and maybe make your code go imperceptibly faster 6 1 Oa Enable all optimisations This option is often the only one use It simply enables all the options detailed below simultaneously 6 2 Ob Bigger Constants The Parallax compiler has a trick to save space whereby large constants can be written as smaller constants preceded by a negative operator So FFFABCD would be represented as 5432 This is a great way to save a couple of bytes here and there and makes for much more compact code however it turns out it s actually faster to just load the large value at the expense of code space It s not much of an optimisation but it s there because we can 6 3 Oc Fold Constants The Propeller Tool compiler provides a constant operator which allows the use of complex constant expressions to be folded down to it s resulting value saving space in the object and ensuring a faster run speed bstc takes this to its next logical progression and does it for you Any expressions in
17. and you can manually assign a port to a propeller On OSX and Windows this is a bit neater as OSX names its ports with the serial number of the PropPlug and Windows creates a new port for every individual serial converter it ever sees Linux simply numbers them in the order they were plugged in gurus can change that by modifying your udev rules however bst_manual_0 04 30 Apr 2010 Page 14 Copyright Brad Campbell Viridian Consulting 2010 43Usingbst oC IRIDIAN Consulting 4 3 Using bst 4 3 1 Ctrl Shift I U Block indenting v aen vur aoe yet OS ube 47 servo start The Propeller tool allows you to indent a selected block of code using the Tab Key In bst the code is indented using Ctrl Shift l and un indented using Ctrl Shift U Each press results in a change of 2 54 led start Be ss spaces forwards or back Cmd on OSX 4 3 2 Ctrl Space Sub object details sal Beer t Once a file has been successfully compiled using u 36 Chase Chase 001 8 37 ow One vire P_003 any of the F8 gt F11 options F9 is the quickest its an symbol table becomes available in the editor until 4 rf S Ze de gt 61 1 the file is modified bst has the ability to display the 42 Servo F 43 PUB start basepin export table of sub object by pressing Ctrl Space 44 Epub main PUB str stringptr 5 EL decivalue i while the symbol is selected with the mouse In the 46 servo
18. arameters and 1 Extra Stack Longs Method 1 PUB Fred X Local Parameter DBASE 0000 Result Local Variable DBASE 0004 X 2 X 12 Addr 0018 38 QC Constant 1 Bytes OC 0000000C 12 Addr 001A 65 Variable Operation Local Offset 1 Write 3 Bytecode 38 9D 61 Addr 001B 38 9D Constant 1 Bytes 9D 0000009D 157 Addr 001D 61 Variable Operation Local Offset Q Write Addr QQ1E 32 Return bst manual 0 04 30 Apr 2010 Page 24 Copyright Brad Campbell Viridian Consulting 2010 5 4 The VARX block advanced VIRIDIAN Consulting 5 4 The VARX block advanced SPIN has a quirk that from time to time seems to drive people nuts For reasons of efficiency we d guess anyway it re orders your variables as declared in a VAR block in the order declared but sorted into LONG WORD BYTE order to best preserve alignment and waste no space bstc has a nasty hack whereby you can prevent this from occurring Rather than declare a VAR block you can declare the block using VARX This will pack the variables in precisely the order you specify them in that object It will generate errors if you break the alignment rules to prevent you from generating broken code so you will have to add manual padding to the array to ensure the variables are properly aligned This is not a modification we expect to see regular use but it was more of an academic exercise to gauge the usefulness of the concept bst manu
19. ayed with their contents in HEX then brackets containing the Decimal representation If the constant is a floating point value the representation in brackets is the value in Decimal while the HEX is what is passed to the compiler 7 1 1 3 Spin Method Spin Block Start with Parameters and 1 Extra Stack Longs Method 1 PUB Start X Local Parameter DBASE 0000 Result Local Variable DBASE 0004 X 13 Xe Addr 001C 36 Constant 2 00000001 Addr 001D 65 Variable Operation Local Offset 1 Write 14 Blink Go Addr 001E O1 Drop Anchor Addr QO1F 06 02 Q1 Call Obj Sub 2 1 15 Ada Jean Addr 0022 88 5 Memory Op Byte VBASE READ Address 0005 Addr 0024 89 4 Memory Op Byte VBASE WRITE Address 0004 Addr 0026 32 Return Each SPIN method has at least one local variable the default RESULT variable The header for each SPIN method details the location and size of each declared local variable or parameter bst manual 0 04 30 Apr 2010 Page 30 Copyright Brad Campbell Viridian Consulting 2010 8 Warranty Statement SC IRIDIAN Consulting 8 Warranty Statement As much as hate to have to do this we live in a litigious society full of people ready to blame anyone else for their own stupidity Coffee is HOT people Therefore have to include the following statements If and when people resume taking responsibility for their own actions look forward to being able to remove them
20. bject archive zipfile b Write binary file E Write dat file for C Compiler Drops a lt filename dat gt file d lt device gt Device to load to Default D lt define gt Define a pre processor symbol may be used multiple times e Write eeprom file f Double download baud rate ch Display this help information l sma Generate listfile s For source code m for Machine readable Debugger style listing a standard boring listfile L lt Lib Path gt Add a library path or file holding library path s to the searchpath may be used multiple times o lt filename gt Output list eeprom binary zip Filename Defaults to input Filename without spin 0 lt options gt Optimise Binary HIGHLY EXPERIMENTAL a Enable all optmisations Be careful No really b Bigger constants should be slightly faster at the expense of code size c Fold Constants g Generic safe size optimisations for smaller faster code however not what the Parallax compiler will generate r Remove unused Spin Methods u Fold Unary Operations on Constants if it will make the code smaller x Non Parallax compatible extensions p 012 Program Chip on device d Di Load Ram and run il Load EEProm and shutdown 2 Load EEProm and run wl012 Error Warning level Errors only 1 Error Warning 2 Error Warning Information Default 0 SS Be silent except for GCC style errors and warni
21. bst tools AT 2 User Manual v 0 04 30 Apr 2010 Copyright Brad Campbell Viridian Consulting 2010 VIRIDIAN Consulting Table of Contents Nu ten eee ee meer mee eee nl tees a are vere eee Nee aa E aoa ee eee 1 2 bstl Command Line Loader Unloader 2 3 bstc Command Line Compiler neen nee nnen n nern nn nnne rnnr nrnna nnne annan annn nanmanna 3 SR EE 3 3 1 1 p Loading a Propeller sc 4 3 1 2 b Saving a Propeller binary to disk 4 3 1 3 e Saving a Propeller eeprom file to disk 5 3 1 4 a Creating a Propeller Source Archive 5 3 1 5 c Creating a DAT file for use by a C compiler ochyancecdt 5 3 1 6 d Specify the serial port to use to load a bropeller 6 3 1 7 D Define a pre processor symbol odvanced erreen 6 3 1 8 f Download at double speed 6 3 1 9 1 Generate compiler list files 7 OU CE e PPA cae Sn ne 7 alles fe ene ue Eu 7 3 112 0y Optimisation e 7 3 1 13 CVV Error Warning Eliette Edge 8 3 1 14 q Be vewy vewy qwiet I m hunting Wabbits 8 3 1 15 v Display version EIERE eneen iceneccedennncniabardedeunoniualannsieenteet 8 Abst ETH Ke EE 9 4 1 The man WY OMI ee 9 4 1 1 TING Directory JEE assassin ennuis 10 4 1 1 1 Configuring the Directory Tree 10 4 1 2 Fil Selector BOK EEN 10 4 1 3 The Tab EE 11 42 EECHELEN 12 4 2 1 Compiler Search TE 12 OT eo le 12 4 2 3 Serial po
22. constants lt FF it s much slower than a simple constant load In this instance bstc substitutes the operation with a straight constant load 6 5 Or Remove unused SPIN methods objects With this option enabled bstc iteratively removes all unused SPIN object code from your program For example when writing code often include the simple_numbers object however rarely use more than one method from that object in a program In this instance the remaining object code is simply consuming space that could otherwise be better used In addition each method or object consumes an additional 4 bytes long in the object method table By removing methods and objects that are not referenced significant space savings may be realised without having to manually strip down objects or customise library components 6 6 Ou Fold Unary Occasionally in SPIN code constants are described as negative numbers The compiler can optionally store these as the operator on the raw number If this case occurs and there is the ability to make the resulting code more compact bstc will discard the operator and negate the constant in the compiler 6 7 Ox Non Parallax compatible extensions This option must be enabled to allow bstc to parse source files that would fail the Parallax Compiler Without this option every file parsed by bstc should also compile cleanly with the original Parallax tools bst manual 0 04 30 Apr 2010 Page 27 Co
23. ctory Tree Unlike the Propeller Tool which displays every available storage device connected to the system and dynamically adds and removes them as filesystems come and go bst requires you to manually configure the directories you want to be visible There are a number of reasons it has been implemented this way but the foremost is speed bst is developed in an environment with lots of network shares over unreliable links and having the tools rescan entire directory trees at inopportune times causes significant delays By configuring manually you have precisely what you want where you want and nothing else The directory configuration is accessed from the IDE Preferences Dialog Editor Paths Fonts and Colours ne Preferences Tab Stops PropBasic Directory Tree Root Paths Add Remove Root Home home brad Add Prop Imedia raid3 Viridian Work Prop Projects move Pascal home brad devel fpc Projects Pascal Alter home brad devel fpc Projects Pascal SIDE bst ap Work 1media raid3 Viridian Work It creates different initial defaults depending on the platform it is running on To add a directory simply click Add and browse to the directory you wish to add To rename the directory as displayed in the Tree click on the name to select it for editing and change as desired To remove a directory click it to highlight and simply click Remove When you close the Preferences dialog the directory tree wi
24. d binary portion without any other processing required don t think it s ever been used however it does work If for some reason you want a binary image of only the DAT section of your top object This is the command for you bst manual 0 04 30 Apr 2010 Page 5 Copyright Brad Campbell Viridian Consulting 2010 3 1 Usage VIRIDIAN Consulting 3 1 6 d Specify the serial port to use to load a Propeller If you find the default configuration does not work for you or you have multiple Propellers connected to your machine this allows you to manually specify which port to use brad bkmac proptest bstc d dev ttyUSB1 p0 test sp Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test Program size is 3 longs Compiled 2 Lines of Code in 0 001 Seconds We found a Propeller Version 1 Propeller Load took 0 304 Seconds 3 1 7 D Define a pre processor symbol advanced Calling the code in bstc a pre processor is probably a stretch It supports basic conditional compilation only at the current time however this option allows you to specify symbols on the command line rather than inserting define in the files to be compiled 3 1 8 f Download at double speed The Propeller tool talks to the Propeller at 115 200 baud and uses a fixed bit packing scheme bstc uses a dense packing scheme based on one devised by hip
25. de must compile with no errors If the source contains errors bstc will refuse to create any output files in any case If one of your source files is pointed to by a symbolic link for example you have one object name linked to another and the spin file references the name of the link then the archive will be created however the linked file will be empty brad bkmac proptest bstc a test spin Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test Program size is 3 longs Compiled 2 Lines of Code in 0 001 Seconds brad bkmac proptest ls test binary test bstc archive 100420 171319 zip test spin brad bkmac proptestS unzip t test bstc archive 100420 171319 zip Archive test bstc archive 100420 171319 zip testing test spin OK testing _readme_ txt OK No errors detected in compressed data of test bstc archive 100420 171319 zip 3 1 5 c Creating a DAT file for use by a C compiler advanced Early in the development of C for the Propeller it was common for drivers such as TV or VGA to be compiled using the Propeller Tool The binary portion of the driver the code intended to be loaded into a COG was then manually stripped out and inserted as a binary blob to be linked into projects developed using a C compiler This option was added to allow people to compile an unmodified spin file and allow bstc to output only the desire
26. e1 or later have a new feature to read the contents of an eeprom connected to the Propeller If you ve lost your source code or simply want to upload the eeprom to preserve user settings in which case the checksum will need re calculating before you can re download you can use the u option This will connect to the Propeller and download a small program into RAM This copies the contents of the first 32k of eeprom into RAM performs a 16 bit CRC on it and then uploads the contents to the PC The PC receives the contents checks the resulting CRC and writes it out to a file as named on the command line If using the u option without a file name the whole process still occurs however there is no file written to disk This is useful for testing communications integrity bst manual 0 04 30 Apr 2010 Page 2 Copyright Brad Campbell Viridian Consulting 2010 ER ER ee 3 bstc Command Line Compiler bstc was written as a simple command line compiler to compile Propeller spin files It handles generic Propeller Tool compatible spin files and aims to generate 100 bit for bit identical binaries The command line for the compiler is significantly more complex than for the loader The current help and usage information is listed below Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Program Usage bere Options Filename spin a Create Propeller o
27. last saved Warning When you close the Project File all files in the editor are closed simultaneously A useful option is to have bst re open the project file that was open when it was closed last This provides for a nice persistent workspace where you can always pick up right where you left off This is configured in the IDE Preferences dialog Editor Paths Fonts and Colours IDE Preferences Tab Stops PropBasic o Save as UTF8 Tab key behaviour o Save Before Compile CO Standard Tabs Timed recovery save 5 B Save interval in minutes Smart Tabs Configure Ports Parallax Tabs New aye SNE W Re open last active project on startup fe E Tab Size Default 8 Browse bst manual 0 04 30 Apr 2010 Page 19 Copyright Brad Campbell Viridian Consulting 2010 46 The Serial Terminal VIRIDIAN Consulting 4 6 The Serial Terminal The serial terminal built into bst is designed as a basic debugging tool It allows communication with any devices connected to a serial port and has the ability to send and receive in either ASCII or Hexadecimal notation The serial terminal also has a separate Hex window which operates simultaneously with the ASCII window to allow easy monitoring of data coming into the system The Hex window allows the composition of Hexadecimal strings in the bottom box and sends them over the wire as composed in R
28. le time offset It s only used when referencing variables in a DAT block plus the object base address this results in the correct absolute HUB address Again its a runtime operator only bst manual 0 04 30 Apr 2010 Page 23 Copyright Brad Campbell Viridian Consulting 2010 5 2 The absolute address operator VIRIDIAN Consulting In PASM means Give me the offset of this symbol into the DAT section It is a relative value with its base as the start of the objects DAT block The operator results in a compile time constant that gives the absolute hub address of the symbol in question It s a special use symbol and it s not widely used If you know you need it you know what it is 5 3 Bytecode advanced Have you seen the generated SPIN bytecode in the list files and though Gee I d like to be able to do something funky but the compiler won t let me If so bytecode is your friend It simply inserts raw bytecode into the SPIN method It s also useful for those developing compilers debuggers de compilers or manipulation tools to be able to have complete control over the code being inserted The following code example writes 12 to the first local variable then writes 157 to the return value Local variable 0 It s perfectly valid spin and the Bytecode 38 9D 61 is the equivalent of Result 157 Code PUB Fred X X 12 Bytecode 38 9D 61 List Spin Block Fred with P
29. led pute Compile and Load EEPROM 268 Assign Propeller 270 extout val 2 lcd dec val Id all b p7 ees or Unfold all blocks 274 27 ARI poll serial i h 315 WRI Get_Char line val 319 PRI Get_Decimal line val start end 339 PRI parse_line line i j k p pi L i Code folding is tied to the display of line numbers toggled with Ctrl Shift L and is only enabled when numbering is visible Code can be folded and unfolded by clicking on the little icons next to the line numbers In addition the entire file can be folded and unfolded using the right click context menu and Ctrl U will fold all blocks in a file The folded state of each file is stored inside the optional Project File for later recall Page 16 Copyright Brad Campbell Viridian Consulting 2010 43Usingbst oC IRIDIAN Consulting 4 3 7 File gt Create Propeller Archive Creating a Propeller Archive The Propeller Tool has the ability to create a zip file containing all the source files required to build the currently opened project this includes library objects and data files bst has the ability to do the same thing with one limitation Your program must compile without error to allow an archive to be built This is a limitation that stems from the archiver implementation inside the compiler it uses the archiver built into bstc to do the dirty work The work around if you need to send someone a broken archive is t
30. ll refresh with your updated preferences 4 1 2 File Selector Box The file selector displays the filtered contents of the directory selected in the Directory Tree The filter can be adjusted using the box immediately at the base of the File Selector Box Double clicking on any of the files in the list will open them using the correct part of bst If files have been added outside of bst clicking again on the directory in the Directory Tree will cause the File Selector box to be refreshed bst manual 0 04 30 Apr 2010 Page 10 Copyright Brad Campbell Viridian Consulting 2010 17 The main workspace CC IRIDIAN Consulting 4 1 3 The Tab Bar Each open file in bst is given its own editor tab The tab selector component allows you to switch close save open and generally manipulate the files with the right click context menu Version 0 19 4 Pre12 or later also allow you to re order the tabs using the Move tab left right menu options in the context menu The red close button on the far right of the tab bar closes the currently active tab as does Ctrl W bst manual 0 04 30 Apr 2010 Page 11 Copyright Brad Campbell Viridian Consulting 2010 4 2 Getting started with bat VIRIDIAN Consulting 4 2 Getting started with bst bst requires some basic configuration prior to getting started with a project The following items are the minimum requirement to ensure your bst experience is as pain free as possible 4 2 1 Compiler
31. ngs Ey Get program version information 3 1 Usage bstc requires as a minimum the filename of the source you wish to compile brad bkmac bstc test spin Brads Spin Tool Compiler v0 15 4 pre8 5 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test Program size is 3 longs Compiled 1 Lines of Code in 0 001 Seconds bst manual 0 04 30 Apr 2010 Page 3 Copyright Brad Campbell Viridian Consulting 2010 31 Usage VIRIDIAN Consulting It will simply compile the file and tell you if you have any errors brad bkmac S bstc test spin Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test test 2 3 Error Unresolved Symbol X X 1 A Compiled 2 Lines of Code in 0 001 Seconds To do anything else useful you need to use some of the optional command line parameters 3 1 1 p Loading a Propeller There are three ways to load a program into a Propeller target These three options are specified using the command line p e p0 Load the program to Propeller RAM and run it e p1 Load the program to an attached EEPROM and halt e p2 Load the program to an attached EEPROM and run the program The options are mutually exclusive and only one may be specified at a time 3 1 2 b Saving a Propeller binary to disk The
32. o comment out the offending code to allow the project to compile The archive name is titled the same as the top object file postfixed by the time and date of the archive and it is saved automatically in the same directory as the top source file bst manual 0 04 30 Apr 2010 Page 17 Copyright Brad Campbell Viridian Consulting 2010 CRE Conse 4 4 The List Window Just as the list file output in bstc Is presents a compilers eye view of the generated source bst includes a separate List Window ools Wen Help d Errors Ctrl Shift rd_001 spin Tv spin TV text spin Status Bar d Line Numbers Ctrl Shift L Compiled Listing d Changed Lines Compiler Listing Serial Terminal Variable DBASE 0008 Y cucar Variable DBASE C ss 33 tex 5 34 LC 45 servopos 1000 35 num add 0048 39 03 ER Constant 2 Bytes 03 E8 36 Ehanade 0048 4D Variable Operation Global 37 ow Jing Boot_SD 38 th Addr avec 03 Drop Anchor Try 39 sd addr 004D 05 02 Call Sub 2 4 rf 49 sd unmount This can be opened and left open Each time a file is compiled the compiled listing is updated in this window It enables a programmer to really see what is going on under the covers and help to understand why things do what they do The list window is not docked or tied to the Main IDE window and can be moved around where convenient
33. oft bst 0 1 In the case that something does go horribly wrong it s sometimes quite helpful if you can send these files to the developer to assist in tracking down the problem If all else fails you can always delete these and start clean 4 7 2 Recovery Files bst is very much beta software and from time to time can crash with ugly error messages although less frequently these days To this end bst has a recovery save mechanism whereby the contents of any tab that is not completely saved to disk is saved into a single recovery file stream prior to each attempt at compilation Additionally there is an option in the IDE Preferences to allow a periodic recovery save to occur while other activity is taking place Editor Paths Fonts and Colours IDE Preferences Tab Stops PropBasic o Save as UTF8 Tab key behaviour O Standard Tabs O Smart Tabs Parallax Tabs gt Allow an individual port per edit tab g pl Tab Size Default 8 Re open last active project on startup New file template directory Browse Like the configuration files each platform has a different location for the recovery file On Linux bst recover On OSX Library Preferences bst recover On Win32 it s wherever your particular version of Windows wants to place your user files The file is called bst recover but you are on your own locating it bst manual 0 04 30 Apr 2010 Page 21 Copyright Brad Campbell
34. py on the Parallax Forums This increases download efficiency and therefore speed by about 25 on average The f option also doubles the baud rate to 230 400 baud This shaves approximately 30 more off the download time of large files My tests have shown it to be 100 reliable with all the hardware have to test on and so use it all the time If you experience issues with it I d like to know about it but you can always omit it and go back to the slower rate bst manual 0 04 30 Apr 2010 Page 6 Copyright Brad Campbell Viridian Consulting 2010 31 Usase VIRIDIAN Consulting 3 1 9 l Generate compiler list files It is often useful to be able to look at the generated output of a compiler in some form of human readable fashion if for no other reason than to go Ah that s why it does that List files were are a notable absence from the Parallax tools and have been sorely missed bstc was written from the ground up to generate clear concise human readable versions of compiled SPIN and PASM code to enable the programmer to understand precisely what is going on under the bonnet hood for those across the pond bstc understands three possible list file options la generates a straight compiler list file Is generates a list file with the original source lines inserted above each piece of generated code Im generates a list file with additional information to assist in being parsed by a debugger See Section 7 for
35. pyright Brad Campbell Viridian Consulting 2010 7 Anatomy of a list file 7 Anatomy of a list file Lets look at a basic spin program and its associated list file test spin CON _clkmode _xinfreq stall pll116x 5 000 000 OBJ Blink Blink VAR long Fred byte Ada Jean May PUB Start X Xec Blink Go Ada Jean blink spin PUB Go Y Voss Compilation VIRIDIAN Consulting brad bkmac proptestS bstc ls test spin Compiled for i386 Linux at 14 43 25 on 2010 04 20 Loading Object test Loading Object Blink Program size is 9 longs Compiled 11 Lines of Code in 0 005 Seconds Brads Spin Tool Compiler v 15 4 pre8 Copyright 2008 2009 2010 All rights reserved Now we have a new file test list in the same directory as the source files Let s break the list file down into pieces to see what it tells us bst_manual_0 04 30 Apr 2010 Page 28 Copyright Brad Campbell Viridian Consulting 2010 TAnatomyofatstfie SC IRIDIAN Consulting 7 1 1 1 Global header This is the global file header It details the initial parameters for the SPIN interpreter and the layout of the object files within the compiled binary Object Address 0010 Object Name test Object Address 0028 Object Name Blink Binary Image Information PBASE 0010 VBASE 0034 DBASE 0044 PCURR 001C DCURR 004C We have two objects Blink is a sub object of test
36. ridian Consulting 2010 Abst TheGUIDE CIRIDIAN Consulting 4 bst The GUI IDE bst is a full featured GUI IDE that tries to include all the basic requirements for developing a Parallax Propeller application in the one single binary It requires no installation just unzip and go Due to the nature of the platforms bst runs on there are some minor behind the scenes variations in the program with regard to system specific configuration items In this manual all configuration examples are for the Linux variant and valid for all platforms unless otherwise noted 4 1 The main workspace e Li La CogStartTimeMeasure spin CommentBug spin Commenttest 001 spin CRCI6_001 spin KE ESS SS SLSASENESSSUSREORES SSS The main bst workspace consists of 5 main areas e The Directory Tree e File Selector Box e Tab Area e Editor Space e Status Bar bst manual 0 04 30 Apr 2010 Page 9 Copyright Brad Campbell Viridian Consulting 2010 4 1 The main workspace VIRIDIAN Consulting 4 1 1 The Directory Tree The directory tree provides a representation of each root path configured in the IDE Clicking on a directory in the tree causes the filtered contents to be displayed in the File Selector Box immediately below If directories have been added or removed outside of bst while it is open a right click on the Directory Tree box will allow you to refresh the contents 4 1 1 1 Configuring the Dire
37. rt CONMONTAMONE En a On et 13 4 2 4 Multi port configuration One Propeller per editor tab 14 4S USMO DSt EE 15 4 3 1 Ctrl Shift 1 U Block indenting 8282802800 TEE EENS 15 4 3 2 Ctrl Space Sub object EC E 15 4 3 3 Context menu Select Files Directory 15 4 3 4 Context menu Open Object Under Cursor 16 4 3 5 Ctrl G Context menu Go to nMe2358sruue mianen ane 16 4 39 60 Code ONE serisinin iaioe ae aea aaaea E E E Ea aE EAEE 16 4 3 7 File gt Create Propeller Archive Creating a Propeller Archive 17 4 4 The List WV A EE 18 4 5 The Project PIS ee a A EEEE ee eee eer ee 19 4 6 The Seral Mr NOM EE 20 4 7 Under the bonnet NOOO E 21 4 7 1 Persistent Configuration FHeS 85428te ententes han tentes 21 4 12 R CONVEN ENS ES eee en 21 DSF d Nee CEET 23 bst_manual_0 04 30 Apr 2010 VIRIDIAN Consulting 5 1 de fine and PMS Si EE 23 5 2 The absolute address operator 23 5 3 e EE H e EE 24 5 4 The VAR X block AOV ACG EE 25 6 Compiler optimisation OPUOM Sins siecscnctvoasstensenicantencsancctedaapcrednatinubdoadentiarnennctelseactiloesdondaagna 26 6 1 Oa Eeler 2 Elei deeg 26 6 2 Ob Bigger IS ANS cca aietncsirteppeinedne alent due tteshneces ae sete 26 6 3 OG Fold EE 26 6 4 Og Generic safe optimisations AEN 27 6 5 Or Remove unused SPIN methods objects 27 6 6 FOU Fold UNA E 27 6 7 Ox Non Parallax compatible extensions 27 T Anatomy of
38. t bst manual 0 04 30 Apr 2010 Page 13 Copyright Brad Campbell Viridian Consulting 2010 4 2 Getting started with bst VIRIDIAN Consulting 4 2 4 Multi port configuration One Propeller per editor tab If you are developing more complex projects and have the need to write and test code for more than one Propeller at a time bst allows you to assign a Propeller to an editor tab individually To compile and download you simply select the tab you want and press F10 bst will make sure the correct Propeller is selected and loaded To enable this feature you need to make sure the option is checked in IDE Preferences it can cause some confusion so it s not enabled Editor Paths Fonts and Colours IDE Preferences by default Tab Stops PropBasic Q Save as UTF8 O Save Before Compile Timed recovery save 5 j Save interval Allow an individual port per edit tab New file template directory Tab key behaviour O Standard Tabs in minutes O Smart Tabs Parallax Tabs fe E Tab Size Default 8 Browse Go to Line ter sion compile 1 Compile Information address Compile and Load Ram ature Compile and Load EEPROM t SFFFF Fold all blocks 1 i 3 1 Unfold all blocks Then from the right click context menu inside the editor tab itself simply select Assign Propeller You are presented with the ports configuration dialog shown above
39. up to date here http propeller wikispaces com Propeller Font OSX users can install the font simply by double clicking on it and clicking the Install button Linux users have to figure out where their particular distribution installs the fonts On an Ubuntu system the are located in fonts The easy install is to copy the modified Propeller ttf there and to log out and back in again bst manual 0 04 30 Apr 2010 Page 12 Copyright Brad Campbell Viridian Consulting 2010 4 2 Getting started with bat VIRIDIAN Consulting 4 2 3 Serial port configuration Windows and OSX users MUST install the ftdi serial drivers if you are using a Parallax product like a demo board or PropPlug before any of this is going to work You need the FTDI VCP Virtual COM Port drivers Windows users will likely have them installed already if you installed the Propeller Tool first as detailed above to get the font Linux users are generally good to go out of the box you can check Ismod to see if ftdi sio is there after you plug your device in if you are unsure bst has a good go at auto detecting relevant serial ports on the systems it runs on In the event of it not picking up your serial port you can manually configure your port from the IDE Preferences dialog 7 Ports we currently know about Pe Editor Paths Fonts and Colours IDE Preferences Tab Stops PropBasic y Browse o Save as UTF8 Tab key behaviour
40. your code that have compressible constant expressions will be folded down to the smallest possible size during the compilation process Seven 7 PUB Fred X X 12 x 6 5 Seven 9 Without Oc 4 X 12 x 6 5 Seven 9 Addr 0018 38 QC Constant 1 Bytes OC 0000000C 12 Addr 001A 38 06 Constant 1 Bytes 06 Q0000006 6 Addr 001C F4 Math Op Addr 001D 38 05 Constant 1 Bytes 05 00000005 5 Addr QQ1F 37 22 Constant Mask Y 34 Decrement 00000007 7 Addr 0021 F6 Math Op Addr 0022 38 09 Constant 1 Bytes 09 00000009 9 Addr 0024 F7 Math Op Addr 0025 EC Math Op Addr 0026 65 Variable Operation Local Offset 1 Write With Oc 4 X 12 x 6 5 Seven 9 Addr 0018 38 48 Constant 1 Bytes 48 S00000048 72 Addr 001A 65 Variable Operation Local Offset 1 Write bst manual 0 04 30 Apr 2010 Page 26 Copyright Brad Campbell Viridian Consulting 2010 6 3 Oo Fold Constants SC VIRIDIAN Consulting X Constant 12 6 5 Seven 9 would achieve the same result in the Parallax Compiler 6 4 Og Generic safe optimisations Currently there is only one additional optimisation in this category Again for the purposes of much tighter code the Parallax compiler has a clever bytecode pair for encoding even X42 constants This can pack large constants in a word of code quite neatly however when encoding
Download Pdf Manuals
Related Search