Timer for PBP code

This allows for the timing of how long PBP code routines take to execute for the PIC18 series.
CodeTimer.bas
Author : Steve Burrow
Date : 09/13/2006
Version: 1.2.3d
Notes : There are two methods of use. One simply times any
block of code (or multiple blocks of code). The other uses
PIC BASIC Pro's built in DEBUG function to time individual
PBP commands.

(Although not tested, it will probably work with PIC16s.)If this is not desirable, the HSEROUT commands
could be replaced by another more appropriate
command. Such as SEROUT Pin, Mode,[]. No
changes should be made to the code inside the
brackets of the HSEROUT commands.

IMPORTANT NOTES ABOUT THE CODE TIMER:

* There will sometimes be unavoidable rounding errors (like with OSC
values 12, 24, 33 and 48) in calculating the period of each timer-
tick. The routines have been designed to help minimize these
errors as much as possible.

* Steps 3) and 4) below can be used multiple times to time any
number of code sections, outputing the results for each.

* Code Timer will increase the code size of your project

* If an overflow of the timer occurs (indicated by a 1 in the
output text "Overflow:") the timing result will not be valid.
Select a higher prescale value.

* The higher the prescale, the less accurate the timing will be.
So select the smallest prescale possible that will not overflow.

* Due to the nature of PBP commands, there is the possibility that
some of the commands will not alway use the same number of
instruction cycles to complete a task. So, You are likely to see
some variablility, and should keep this in mind if trying to do
anything which relies on critical timing (which should probably
be handled in an interrupt).1) Add an INCLUDE statement for this file

INCLUDE "CodeTimer.bas"

2) Setup the timer with the following statement syntax:

@ SETUP_CODE_TIMER tmr, ps

Where tmr = Timer number (0-3)
ps = Valid Prescale Value (see below)
Timer0: 1,2,4,8,16,32,64,128,256
Timer1: 1,2,4,8
Timer2: 1,4,16
Timer3: 1,2,4,8

Examples:
@ SETUP_CODE_TIMER 0, 128 ; Timer0, Prescale 1:128

@ SETUP_CODE_TIMER 3, 1, ; Timer3, Prescale 1:1

2b) If you have a separate clock source for the timer, you
can use the following DEFINE to set it fo
This must be typed exactly as shown. Add the appropriate
value in MHz.

DEFINE CODETIMER_EXTCLK 10 ;10MHz clock for Timer

3) Place the following statement just PRIOR to the section of
code you want to time:

@ START_CODE_TIMER

4) Place the following statement just AFTER to the section of
code you want to time:

@ STOP_CODE_TIMER
You will end up with output similar to:

--------------------------
Time: 15.0276 msec
Tick Period: 0.4 usec
Timer Ticks: 37569
OSC Freq: 40 Mhz
Prescale: 4
Overflow: 0
--------------------------1) Add an INCLUDE statement for this file

INCLUDE "CodeTimer.bas"

2) Setup the timer with the following statement syntax:

@ SETUP_CODE_TIMER_DEBUG trm

Where tmr = Timer number (0-3)

Examples:
@ SETUP_CODE_TIMER_DEBUG 0, ; Timer0

@ SETUP_CODE_TIMER_DEBUG 3, ; Timer3

3) Place the following statement just PRIOR to the section of
code you want to time:

@ START_CODE_TIMER_DEBUG
ENABLE DEBUG

4) Place the following statement just AFTER to the section of
code you want to time:

@ STOP_CODE_TIMER_DEBUG
DISABLE DEBUG

You will end up with output similar to:

-------------------------
Debug Addr: $5444
Time: .0404 msec
Tick Period: 0.1 usec
Timer Ticks: 404
OSC Freq: 40 Mhz
Prescale: 1
Overflow: 0
-------------------------
-------------------------
Debug Addr: $547A
Time: .0012 msec
Tick Period: 0.1 usec
Timer Ticks: 12
OSC Freq: 40 Mhz
Prescale: 1
Overflow: 0
-------------------------
-------------------------
Debug Addr: $548A
Time: .0006 msec
Tick Period: 0.1 usec
Timer Ticks: 6
OSC Freq: 40 Mhz
Prescale: 1
Overflow: 0
-------------------------
Total Ticks: 422
Time: .0422 msec
^^^^^^^^^^^^^^^^^^^^^^^^^

This shows the timing results for 3 PBP commands. The starting
address for these commands is shown as "Debug Addr." At the
bottom, if the number of timer ticks was less than 65536, then it
will give you the Total Time of all the instructions. Otherwise,
it will only give the total number of timer ticks

IMPORTANT NOTES ABOUT USING DEBUG:
* This code timer will not work with a prescale
or external timer clock.

* Since PBP's DEBUG function add additional assembly instructions to
code, code size will increase, so it's advised to use only with
a small number of instructions.

* There is some likelyhood the the number of ticks could actually be
slightly less than reported. This is due to PBP adding code for
the debug functions and it is not possible to predetermine the
exact number of instructions added.

Special thanks to Darrel Taylor (www.darreltaylor.com). It was his
code that was the seed for this project. He also provided important
answers and help directly. Additionally, it was through careful study
of his projects that I was able to learn what I needed to put this
together.