Editing BoostC Explaining Dot H Files

Change Name to BoostC System Header Files



Draft Not 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 bigendien or the reverse, I need to look it up.  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 inline functions for more information on inline functions and #define.
@@ Line 1: / Line 1: @@
-Draft Not quite Ready
+Change Name to BoostC System Header Files
+Draft Not Ready
@@ Line 22: / Line 26: @@
 == BoostC.h ==
 BoostC.h is almost always included, but via System.h, so you may not “see” the include.
@@ Line 62: / Line 68: @@
 _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.
+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 bigendien or the reverse, I need to look it up.  Useful to know if you want to do byte manipulations on multibyte data.
 === Delay functions generated by linker ===
@@ Line 78: / Line 84: @@
 == More Reading ==
-see [[BoostC Inline Functions]] for more information on inline functions and #define.
+see 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]]