View source for BoostC Explaining Dot H Files

Draft Not quite Ready


This is my [[russ_hensel]] explanation of *.h.  Others are welcome to contribute.  It is a work in progress, and may or may not be correct.

== System.h ==

Should almost always be included in all your files.  It has limited functionality, largely a bridge to other include files.
For the boostC compiler these files are:

*BoostCPic18.h  defines for the 18 series chips
*BoostCPic16.h  defines for the 16 series chips
*Boostc.h		defines and other utility stuff for the compiler.

Apparently the compiler reads the target chip and effectively #defines a value for  _PIC16F722 or whatever for the chip that you have designated the target chip.

Links for the macro processor and related

http://publications.gbdirect.co.uk/c_book/chapter2/textual_program_structure.html  2.3. The Textual Structure of Programs

http://publications.gbdirect.co.uk/c_book/chapter7/ 2.3 The Textual Structure of Programs

== BoostC.h ==

BoostC.h is almost always included, but via System.h, so you may not “see” the include.
The following refers to section within BoostC.h, pull up a copy while you are reading this.

=== Helper macros ===

ex:
     #define clear_bit( reg, bitNumb )	((reg) &= ~(1 << (bitNumb)))

These are inline functions using #defines with arguments. ( see [[]] ) many C programmers use these expressions directly in there code, but using clear_bit instead of equivalent is bothe easier to read and write.  It make the intent of the program cleared, and may make the code easier to port.


=== MAKESHORT ===

     #define MAKESHORT( dst, lobyte, hibyte )	asm movf _##lobyte, W \
    						asm movwf _##dst \
   						asm movf _##hibyte, W \
       						asm movwf _##dst##+1


Again an inline functions using #define with arguments.  There are few other things going on here:

* using the asm keyword to directly code assembler code
* using \ to make the multiline macro be read as a single line
* using ## for Token pasting.


see: [http://publications.gbdirect.co.uk/c_book/chapter7/directives.html 7.3.2.3.Token pasting]


with token pasting when 

    asm movf _##lobyte, W 

is processed in MAKESORHT( A, B, C ) becomes

    asm movf _B, W 

_B in asm represents the addres of the variable B in the C program.

Additionally from reading this macro we can see that BoostC stores the low byte in low memory and the high byte in higher memory.  This is called little-endian.  Useful to know if you want to do byte manipulations on multibyte data.

=== Delay functions generated by linker ===
Not quite sure how the linker generates these, but I do understand that the linker needs to know the clock speed to do it.  This makes it hard to use precompiled libary functions unless a different one was used for clock speed.  Including this allows the compiler to compile what ever call is needed in your C code.


=== Built-in assembly ===

These macros offer a way of using assembler without using the assembler key words _asm or asm.  Using asm makes sure that the compiler will not optimize out the code of the macro.

=== Functions used internally ===

look like multibyte arithmitic, not sure how or why, working on it.

== More Reading ==

see [[BoostC Inline Functions]] for more information on inline functions and #define.


== Other project Files ==

*.cof   binary file, debug information.  

*.stat  text file, purpose: Linker Function Resource Usage Dump

*.obj      binary file, source code compiled into object code 

*.lst     text assembler code ( no ref to source )  output of xx input to yyy

*.csam   mixed source and assembler code   output of xx input to yyy

*.brws   text, symbols etc and their source code reference.

*tree   call tree in text format, display in ide by....

[[category:PIC]][[category:BoostC]]