bst tools User Manual v 0.03 23 Apr 2010
Contents
1. 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 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 4 2 Getting started wire VIRIDIAN Consulting 4 2 3 Serial port configuration Windows and OSX users MUST install the2. 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 A X 12 6 5 7 Seven 7 9 Addr 0018 38 48 Constant 1 Bytes 48 S00000048 72 Addr 001A 65 Variable Operation Local Offset 1 Write 6 3 Oc Fold Constants 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 X 2 constants This can pack large constants in a word of code quite neatly however when encoding 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
3. Cmd on OSX 4 3 2 Ctrl Space Sub object details 4 LCD 10X2 BIT Once a file has been successfully compiled using 35 num _Simple_Numbers aa A any of the F8 gt F11 options F9 is the quickest its 38 39 ty symbol table becomes available in the editor until 42 rf Object media raid3 Viridian Work Prop Projects a S 7 lies the file is modified bst has the ability to display the 42 Servo 43 PUB start basepin export table of sub object by pressing Ctrl Space 44 pub main Aa arin 45 ec vailue Pi H H Ge e hexvalue digits while the symbol is selected with the mouse In the k PUB t i k H LA gi BEE bux cetcolors colorptr i fore back example shown we clicked between the t and the d n Le di 5 d harpa v to make sure the cursor was in on the word and 1 St 52 Mg pressed Ctrl Space The export table pops up to 53 text s 54 Led start display the available functions in the object 4 3 3 Context menu Select Files Directory J OAI HR Slop Poe oertzel demo Ed l E A van Boat E Hu T f 1 gt Bicdzusb 2 Stop TV driver rees a cog LcD Interface 4 7 if cou LEbran 48 cogstop cog 1 DB PropBasic 4 9 b SpinStart 58 stuff 51 EDAT Open Object under Cursor b Test Project aen Ee ET 54 ae af a af ae af a of ae of af oft af af af af af af af aa O E PEN 54 Assembly languag
4. 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 7 Anatomy dei VIRIDIAN Consulting 7 Anatomy of a list file Lets look at a basic spin program and its associated list file test spin CON _clkmode xtall pll16x _xinfreq 5 000 000 OBJ Blink Blink VAR long Fred byte Ada Jean May PUB Start X X 1 Blink Go Ada Jean blink spin PUB Go Y Y 1 Compilation brad bkmac proptest bstc ls 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 Loadi
5. 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 03 23 Apr 2010 Page27 Copyright Brad Campbell Viridian Consulting 2010 7 Anatomy of a list file 7 1 1 2 Object header VIRIDIAN Consulting Object test EE Base is 0010 00000408 1032 004C4B40 5000000 Constant _clkmode Constant _xinfreq VBASE 0000 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 displayed 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 000 Result Local Variable DBASE 0004 X 13 X 1 Addr QQ1C 36 Constant 2 00000001 Addr 001D 65 Variable Operation Local Offset 1 Write 14 Blink Go Addr 001E Hl Drop Anchor Addr QQ1F 06 02 01 Call Obj Sub 2 1 15 Ada Jean Addr 0022 88 05 Memory Op Byte VBASE READ Address 0005 Addr 0024 89 04 Memory Op Byte VBASE WR
6. Chip on device d H Load Ram and run 1 Load EEProm and shutdown 2 Load EEProm and run w 012 Error Warning level Errors only 1 Error Warning 2 Error Warning Information Default 0 q Be silent except for GCC style errors and warnings y 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 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 1 Lines of Code in 0 001 Seconds 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 p1 lLoad the program to an attached EEPROM and halt p2 Load the program
7. IDE Preferences Tab Stops PropBasic Q Save as UTF8 Tab key behaviour RG C Save Before Compile QO Standard Tabs Go to Line Timed recovery save 5 Si Save interval in minutes O Smart Tabs b Parallax Tabs oo Compile 8 s Tab Size Default 8 1 Compile Information iddress Compile and Load Ram New file template directory iture Compile and Load EEPROM Browse Assign Prop eller L SFFFF IES Fold all blocks 1 1 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 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 43Usingbst TT VIRIDIAN Consulting 4 3 Using bst 4 3 1 Ctrl Shift l U Block indenting TV IFI VV xs kA Tt OI VUpPVOD AT 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 1 and un indented using Ctrl Shift U Each press results in a change of 2 54 led start 55 Chase Start ER tw etart 1 E spaces forwards or back
8. 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 it 4 2 Getting started wire VIRIDIAN Consulting 4 2 4 Multi port configuration One Propeller per editor tab lf 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 by default Editor Paths Fonts and Colours
9. bst is implied 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 5 1 define and friends bst has a very basic conditional pre processor built into the tokeniser This allows the conditional compilation 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 NOTE All pre processor statements must begin at the start of a line Column 0 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
10. code and the convenience of the displayed adjacent code headers 9 DAT EVAR a EOBJ Epub main X PUB Boot SD copy AI Get_Temperi n PARI DS1307 den H PRI tempout va lee Select files direcotry Cut Go to Line cd dec val led pute 7 Compile if val amp 1 Compile Information led purer Compile and Load Ram led pute Compile and Load EEPROM Assign Propeller extout val led dec v al Fold all blocks ied pute Wegageegeggemg led str r Unfold all blocks WI poll serial i h AI Get Char line val Fe EPRI Get Decimal line val start end i EPRI parse line line i j k p pi L 387 EPRI StrCat Y x IL bst manual _ 0 03 23 Apr 2010 Page 16 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 Copyright Brad Campbell Viridian Consulting 2010 44 The List Window VIRIDIAN Consulting 44 The List Window Just as the list file output in bstc Is presents a compilers eye view of the genera
11. AGES 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
12. ITE 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 03 23 Apr 2010 Page 28 Copyright Brad Campbell Viridian Consulting 2010 8 Warranty Statement VIRIDIAN 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 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 DAM
13. Y oer 29 bst_manual_0 03 23 Apr 2010 1 Introduction 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 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 bst_manual_ 0 03 23 Apr 2010 Page 1 Copyright Brad Campbell Viridian Consulting 2010 2 bsti Command Line Loader VAN Consulting 2 bstl Command Line Loader bstl was developed initially as a test for the cross platform toolchain and to experiment with different algorithms for loading the Propeller chip The program on
14. 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 compile 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 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 Warning The Propeller Tool will compile the operator as valid code in a SPIN method however it will give a result far from what you want it to do 5 3 Bytecode advanced Have you seen the generated SPIN bytecode in the list files and though Gee I d like to be a
15. bet tools S a User Manual v0 03 23 Apr 2010 Copyright Brad Campbell Viridian Consulting 2010 VIRIDIAN Consulting Table of Contents TAT ale CON EE Sa E pmecu ann ceeeaaessaied saaeeatesonesteaoaateeasacaseedesnaaccs 1 2 psi Command LING OA di ce eo pa ae ee 2 3 bstc Command LL mneCGompiler iii sense 3 SR TE A E E A E S 3 Sele 0 Loading a ele WEE 4 3 1 2 b Saving a Propeller binary to dek 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 advanced 5 3 1 6 d Specify the serial port to use to load a Propeller 6 3 1 7 D Define a pre processor symbol advanced 6 3 1 8 f Download at double speed 6 3 1 9 l Generate compiler list ies 7 OC MEMO VARY IH A EE 7 31 11 0 COMPO Fe MC EIERE ea ee a T 31 12 CO eiedlwl le leet en 7 3 1 13 VV Error WEIT 8 3 1 14 q Be vewy vewy qwiet I m hunting Wabbits 8 3 1 15 v Display version information 8 DOS ne ET e 9 4 1 the main NOIRS O32 e 9 e Na NS DICO Te E accede cereodee anaes 10 4 1 1 1 Configuring the Directory Tree 10 e AN k FIE 21 te 8 EE 10 Be Mi WIN AR a 11 4 2 Getting started with DSt ei on 12 4 2 1 Compiler Search EE 12 e EE 12 4 29 ella POF CONIOUFAON 2 eee enr seed etes ro 13 4 2 4 Multi port configuration One Prop
16. ble 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 Ke ee Ae Bytecode 38 9D 61 List Spin Block Fred with Parameters and 1 Extra Stack Longs Method 1 PUB Fred X Local Parameter DBASE 0 Result Local Variable DBASE 0004 X 2 X 12 Addr 0018 38 C Constant 1 Bytes OC S0O000000C 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 Write Addr 001E 32 Return 6 Compiler optimisation options 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 y
17. e Propeller 4 7 Under the bonnet hood 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 camsoft 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
18. e T Save All 55 aaf af af af af a aF aF aF aF aF aF ak aF aH aF ak aF H AD8803 spin cp Close 57 Close All ADC spin 58 Close all but Current Clock spin 59 SE COILREAD spin 60 Entry 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 4 3 Using bst VIRIDIAN Consulting 4 3 4 Context menu Open Object Under Cursor 35 num Simple Nun 36 Chase Chase 00l af ow One _wire F 38 Fee 39 sd Open Object under Cursor ato 40 rf Save SPI 41 TX Save All B_ SF 4 Ser ENK 43 Close RS 44 pub n Close All La al 4 3 5 Code Folding Code folding is a neat addition to any source editor when working on large source files It enables individual 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 methods to be worked on without the clutter of nearby source
19. e 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 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 SE New Q Save as UTF8 Tab ke
20. eller per editor tab 14 A o USNE be 15 4 3 1 Ctrl Shift l U Block indenting cece ecccceeeeceececeeeeeeeeeaeeeseeeseaeeseusesseeeeeeaees 15 4 3 2 Ctrl Space Sub object details 15 4 3 3 Context menu Select Files Directory secccseeeceece ees eeseeeeeseeseeeaeeaees 15 4 3 4 Context menu Open Object Under Cursor 16 e ono COCOON i a a ie ee ee 16 AA TG ES CNE sane E E E EEE 17 AD TNG PC E 18 46 The Serial EE ln ee na 19 4 7 Urider the DONMET MOO E 20 4 7 1 Persistent Configuration Files 20 AT 2 INCCOVGLY PS a ne dede ae EE 20 5 SPIN Language EXCNSIONS 2 nsc cesse ass e ass e a rE scene een ec 22 e OUI GING a dE 22 5 2 The absolute address operaior 22 bst manual 0 03 23 Apr 2010 VIRIDIAN Consulting 9 9 Bytecode advanced E 23 6 Compiler optimisation options sisi 24 6 1 Oa Enable all optimisations 24 6 2 OD Bigger ConstaNlS aserra REE E SANEERATAAN REE REAR 24 AE FOC e e E ON E CC 24 6 4 Og Generic safe opimtsatons 25 6 5 Or Remove unused SPIN metbodeiobiechs 25 OO EE OL ER at le a EE E E E 25 6 7 Ox Non Parallax compatible extensions 25 PATIO OA SR sascee cncse steers anger eee eceneneesanend etonenusence aataceqeconeosenenssancumeey eeneeeeteae 26 ees D Wee en Ee 27 Tae tee Op NC AOG sascdece acre cetcecacensececerananeee E vecneussauensaeesecs 28 PS Wie nft Lee D 28 CAT EE E a ee eee 29 Oe DECAN r Or N r o E onan senceieuassepeecsteesouct 29 02 CMAOT EAD
21. erbosity of the compilers output There are three levels 0 1 2 e W0 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 4 bst The GUIIDE VIRIDIAN Consulting 4 bst The GUI IDE bst is a full featured GUI IDE that tries to include all the basic requireme
22. 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 Ports we currently know about Editor Paths Fonts and Colours IDE Preferences Tab Stops PropBasic i i aoe Q Save as UTF8 Tab key behaviour dev ttyUSB1 Q Save Before Compile O Standard Tabs idevittyS3 _Rescan 5 Save interval in minutes O Smart Tabs IdevittyS2 m ds arte jdevittyS1 Port Select W i port per edit tab e E Tab Size Default 8 idevittyS0 Manual Re open last active project on startup Auto New file template directo i R Find Prop Port we will use to try and talk to Propeller dev ttyUSB1 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
23. irectory 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 4 1 The main workspace VIRIDIAN 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 Copyright Brad Campbell Viridian Consulting 2010 bst manual _ 0 03 23 Apr 2010 Page 11 4 2 Getting started wire 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 Search Paths Compiler Preferences SEU Compiler Searchpaths media 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
24. ly has one 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 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 Test mode Undocumented h Show this help 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 EE 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 c
25. ng Object Blink Program size is 9 longs Compiled 11 Lines of Code in 0 005 Seconds 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 7 Anatomy ofa listie VIRIDIAN 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 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
26. nts 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 Be Eit comple projet Pol viem Hehe Tiha apn ADCTESTspin Bas 20 _Onveerspm CREME O0L spin Debug PC spin Derebngard Op epp DS13070b spin CSLI spin EECenhg spin Ernbad Tirer binary Flash_Debug_Leds spin 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 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 Directory Tree Unlike the Propeller Tool which displays every available storage device connected to the system and dynamically adds and removes them as filesystems c
27. ome 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 IDE Preferences Tab Stops PropBasic Directory Tree Root Paths Add Remove Root Home home brad Add Prop media raid3 Viridian Work Prop Projects Remove Pascal home brad devel fpc Projects Pascal Alter home brad devel fpc Projects Pascal SIDE bst ap Work media 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 will refresh with your updated preferences 4 1 2 File Selector Box The file selector displays the filtered contents of the directory selected in the D
28. our 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 preceeded by a negative operator So FFFABCD would be represented as 1 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 your code that have compressible constant expressions will be folded down to the smallest possible size during the compilation process Con Seven 7 PUB Fred X A 12 6 5 Seven 9 Without Oc A A 12 6 5 Seven 9 Addr 0018 38 OC Constant 1 Bytes OC S0O000000C 12 Addr 001A 38 06 Constant 1 Bytes 06 S00000006 6 Addr 001C F4 Math Op Addr 001D 38 05 Constant 1 Bytes 05
29. ry 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 desired 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 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 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 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 u
30. save to occur while other activity is taking place Tab key behaviour Standard Tabs Smart Tabs Parallax Tabs CT Allow an individual port per edit tab a 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 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 5 SPIN Language Extensions VIRIDIAN Consulting 5 SPIN Language Extensions NOTE bst uses the bstc compiler internally so where bstc is mentioned
31. ses a fixed bit packing scheme bstc uses a dense packing scheme based on one devised by hippy 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 81 Usage 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 Sec
32. ted source bst includes a separate List Window vols View Help d Errors Ctrl Shift E d_001 spin Tv spin TV_Text spin Status Bar d Line Numbers Ctrl Shift L d Changed Lines Compiled Listing Serial Terminal Variable DBASE Wun Y tocar Variable DBASE C ss 33 EX 2522 25252252 52525 5 5 5 34 LCD 45 servopos 1000 35 NUM Addr 0048 39 03 ER Constant 2 Bytes 03 E8 36 Chaliagde 0048 4D Variable Operation Global 37 ow Boot_SD 38 tN lAddr 4c irop inde Try 39 Sd Addr QQ4D 05 02 Call Sub 2 40 rf 149 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 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 03 23Apr2010 Page17 Copyright Brad Campbell Viridian Consulting 2010 45 The Project File VIRIDIAN Consulting 4 5 The Project File 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 ar
33. tion 7 for 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 proptest bstc o john b ls test spin Brads Spin Tool Compiler v 15 4 pre1Q Copyright 2008 2009 2010 All rights reserved Compiled for i386 Linux at 22 00 43 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 proptest 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 81 Usage VIRIDIAN Consulting 3 1 13 W Error Warning levels This option controls the v
34. 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 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 proptest 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 81 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 Paralla
35. urrent 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 bstc Options Filenamel spin a Create Propeller object archive zipfile D Write binary file 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 Double download baud rate h Display this help information 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 Cc Fold Constants 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
36. x 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 code 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 S 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 1 1319 zip test spin brad bkmac proptest unzip t test bstc archive 100420 1 1319 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 1 1319 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 bina
37. y behaviour Q Save Before Compile QO Standard Tabs Timed recovery save fs Save interval in minutes Smart Tabs Configure Ports Parallax Tabs CT Allons agit tab iM Re open last active project on startup es Tab Size Default 8 4 6 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 RAW form 3 View Help Errors Ctrlt Shit E d Status Bar d Line Numbers Ctri Shift L d Changed Lines bet Terminal dev ttyUSBO ormat Port Communicate Terminal Hex Input Output m EI x Compiler Listing 28 DATA 60 102 102 60 102 102 60 0 60 102 10 62 6 6 60 4 89 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 th
Download Pdf Manuals
Related Search