Editing BoostC tiny Wiki

== Introduction ==

This is the very beginning of a Wiki for BoostC.  Its organization will probably change a lot in the near future ( if we can get the free labor required ).  It may move to the SourceBoost site if they want to host it.  Since BoostC is proprietary it may be inappropriate for it to grow too big here unless we can find some explicit support for it.  For now here it is.  Much of this material applies to compilers other than BoostC and to environments other than PICs embedded systems.  Major sections will probably be split into seperate pages.  [http://www.sourceboost.com/ SourceBoost Homepage]

== BoostC Wiki Contents ==

In addition to this page see:

===[[BoostC from the Forum]]===  
Quickly review a year's worth ( or more ) of the forum for the most useful posts.

===[[A Really Basic Guide to the PIC Microprocessor and BoostC]]===

This is about as simple as it gets, does not assume much hardware knowledge either.

===Go to [[PIC Links]]===
Go to and search ( page search not google ) on "BoostC". There are projects, tips, tutorials..... 
=== [[BoostC Inline Functions]] ===
=== [[How the BoostC Compiler Works]] ===


=== [[BoostC Explaining Dot H Files]] === 		
=== [[BoostC Wiki Help Needed]] === 


=== and even more comming soon.....===

== Tips/Tricks/Gotchas ==

=== Watch out for set-bit! ===

The function set-bit() is almost right, but it should be set_bit().  This and similar errors are subtraction, and the result is error messages ( how about a sample ) that are not very helpful.

=== Rebuild It === 

Sometimes I have been able to get rid of odd errors by forcing a rebuild by erasing all but the project file and the .c and .h files.  The manual suggests that  Ctrl+F7 or Ctrl+build command do pretty much the same thing.

=== Subroutine Signatures === 

Often we have several versions of a subroutine with different signatures ( set and type of call arguments ) Try to check that you are calling the version you want.  Casting may help.

=== Flakey Stack === 

If a program is flakey, partarcularly after working in earlier versions you may have run out of stack space for the call return stack.  

To help you tell look at all the linker messages.  Also open the code window and look at the call tree ( View -> Code Bar -> Call Tree ), see anything in red?

The fix:

* Move the function inline in the code ( if only called once or if small )
* Declare as an inline function.
* Use the linker options to add a software stack.

=== Bad Options ===

Check you options, target should be right.  Recently I had a problem with the Compiler location option.  It seems to be a option of the project ( which makes sense if you want different projects to behave differently ) not the ide installation, so especially if you got the project from someone else check it.  For me a bad compiler location made the build take forever and do nothing; the compiler gave a useful error message.

=== Types and Booleans ===

This may be standard C or just BoostC, but type checking is not as strict as languages like Java.  Especially be careful of the idea that booleans and numbers are interchangable.  Especially do not think that 0 is false and 1 is true.  You can count on 0 being false ( I think )  I have seen test_bit evaluate to 64.

=== Read Before Write Problems ===

[[Read before write]]

=== BootLoader Madness ===

Had a program, programmed with a programmer, worked fine.  Added a bootloader, bootloaded the program, NG.  Why why why!

Some hints, the fuses are inherited from the bootloader, your program cannot change, but that is not what got me.  I did not use, set, or enable interrupts.  This defult worked fine, but the bootloader apparently did not leave the settings in the default condition.  My fix, added an interrupt handler which did nothing, but even more important turned the global interrupts off at the very beginning of my program.  Not all bootloaders may behave in this way, but if you have a problem, consider the above.  See also:  [[PIC Programmers, In Circuit Programming and BootLoaders]]

=== Include the Library ===

Normally the compiler will find the library file needed, but if you get messages that functions are not found include the library that contains them, see the .h file with the same name for the library function.  This has been know to work with the EEProm Library.  Choose the right one, for the 18F or 16F if there is a choice.

=== How to use PIC registers as C variables === 

BoostC compiler can map C variables on specific addresses. This becomes handly when one wants to use PIC registers as C variables. For example PIC CCPR1L and CCPR1H are a consecutively addressed register pair.

  volatile unsigned short ccpr1 @ 0xFBE; //declare a 16 bit variable that is located at address 0xFBE, just where CCPR1 registers start
  //Now this variable can be used in C cone
  ccpr1 = 0x2400; //for example assign 0x2400 to it what writes 0x00 into CCPR1L and 0x24 into CCPR1H 

== Standard C Issues ==

==== Use a Lint Program ====
Has anyone configured one for BoostC?

==== Read This ====
[http://en.wikipedia.org/wiki/C_Traps_and_Pitfalls C Traps and Pitfalls From Wikipedia, the free encyclopedia]  Note that there is a free download or a longer ( for purchase ) book.

=== Good Practices ===

Opinions may differ!

===== Put a good header in the program =====

I keep refining my, see one of my projects like [[PIC Stepper Motor Demonstration and Test Project]]  or an page with a version of the header [[A C Program Header Example]].

===== Avoid Shortcuts =====

For example I always use braces with an if statement, there is less chance of error if someone adds a line:

 if ( isTrue ) {
    ix ++;
 }

Use full declarations:

  unsigned char ix;
 
     //not
 
  char ix;

The reader, and perhaps even the programmer may not remember the default or remember it correctly


Use parenthesis not operation conventions:

  c    = a + ( b * c ) 
 
     //not
 
  c    = a + b * c

In the good "old days" of the PDP-11 where large memory was measured in killobytes it was necessary to conserve memory -- even at the source code level.  In the 21st century environment of gigabyte memories it's no longer necessary to conserve bytes at the expense of readability and clarity.  Many programmers (particularly the old grumpy ones) take pride in saving a few bytes -- but mostly its a tradition thing except where the shortcuts save a bit of program run time.  ....but then there might be a reason why they call it 'code'.

Keep in mind that the following two sections are not equal. While the first looks neater at the source code level, it generates many times(!) more (redundant) machine instructions than the second form.


    bit LED1_TRIS        @ TRISB.5;
    bit LED2_TRIS        @ TRISB.6;
    bit LED3_TRIS        @ TRISB.4;
    
    LED1_TRIS = LED2_TRIS = LED3_TRIS = 0; // make output
‎

Writing it this way, generates smaller and faster code:

    bit LED1_TRIS        @ TRISB.5;
    bit LED2_TRIS        @ TRISB.6;
    bit LED3_TRIS        @ TRISB.4;
    
    // make output
    LED1_TRIS = 0;
    LED2_TRIS = 0;
    LED3_TRIS = 0;

==== Read This ====

[http://www.csd.uoc.gr/~hy255/reading/cstyle.pdf  Recommended C Style and Coding Standards] from Bell Labs

== How to pages ==

[[Index of sample code pages]] showing sample code, showing the various ways tricky, or not so tricky issues have been tackled

== Optimization ==

As a general rule it has been observed that many programmers spend too much time on optimization and that often the compiler can do a better job than the programmer.  Often readability of the code suffers for "optimizations" that do not really optimize anything.  That said, it is worthwhile to optimize the algorithm.  C does not know the purpose of the code, the programmer should, the compiler can only optimize the code in doing what you said, not what you want.


=== Questions ===
Questions:

*Is shifting better than multiplying/dividing by poweres of 2?

*does if( intcon & (1<<T0IF) ) work better than test_bit( intcon, T0IF )?  --- answered see below.

*Is there a time penality to using local variables.

=== Optimizations that Seem to Work ===

Declare variables as the simplest type that will work.  Keep it small, keep it unsigned unless you need it otherwise.

=== Optimizations that Seem Not to Work ===

Some of these may not truely attempts at optimization, just different ways of writing code, in andy case we compare them to other presumabably clearer ways of writing the code.

Generally these test were done by writing the code and then examining the casm file.

==== Shift, vs Test ==== 

In interrupts we often see a bit test as 

     if( intcon & (1<<T0IF) )

by which it is meant:

     if( test_bit(  intcon, T0IF) )

Looking at the generated code: it is identical, so why not use the clearer formulation?  { Also looking at boostc.h it seems this is the definition of the expression }

=== "x" vs 'x' ===

Sometimes there is "no difference"  between "x" vs 'x'.  For example serial_printf( '\r' ); and	serial_printf( "\r" );	both print a carriage return.  But the character formulation, '\r', will take less memory and run faster.  Often a function will take either a character or a string, if the string is one character long use the character formulation.

==== More ====

More in process... and soon to be the new home for all [[BoostC Optimizations]]

== Code Snips that may Be Helpful ==


moved to and merged with [[Index of sample code pages]]

== Example Programs and Projects ==

Go to [[PIC Links]] and search ( page search not google ) on "BoostC".

== Getting help ==

Struggling with a new PIC feature? Check out the PIC tutorials at: http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1959 for some useful help on the various PIC peripherals

== Further reading ==

* [[Microcontrollers]] This Wiki's main page on microcontrollers including the PIC.

* [[Playing With PIC Pack]] A user developed package in BoostC for the PIC.

* [[BoostC from the Forum]] Information extracted and summarized from the BoostC Forum. 

* [http://en.wikibooks.org/wiki/C_programming Wikibooks: C programming] is about C programming in general (alas, focuses on programs running on desktop computers, rather than small microcontrollers).

* Gooligum C Tutorials [http://www.gooligum.com.au/tut_midrange_C.html ] C language Tutorials for mid range PICs with extensive examples and detailed explanations.  Written for HITEC and PICC but easily convertable to SourceBoost C.
[[Category:BoostC]][[Category:PIC]]