PIC16F87x(A) BOOT LOADER v3.11 Copyright (C)2006 HI-TECH Software.
Freely distributable.

Included in this package is an implementation of a bootloader for
the PIC16 flash devices.

Introduction
############

The Microchip PIC16F87x(A) processors are able to write to their own program 
memory while executing from it. By taking advantage of this fact, a 
bootloader program can be designed to accept new code via the serial 
port (or other method) and re-program itself.

On startup, the bootloader code is the first to execute. The bootloader will
transmit a count-down on the serial port. During this time the bootloader is
awaiting to recieve a response on the serial port. Sending a character to the 
serial port during the count-down will indicate to the device that the user
wishes to engage the bootloader facility and download a new program. If so
a prompt will be displayed and the new program may now be transferred
to the device via the serial connection.

If the user does not respond to the processor before the count-down expires,
the bootloader facility will not be engaged and the processor will begin
to execute a previously downloaded program.

If there has been no response from the user, and the device was previously
unprogrammed, the bootloader countdown will simply restart.

How it Works
############

So as to maximize the amount of available program memory, the bootloader 
has been designed to occupy less than 100H words.

The bootloader code executes before any user program. If it is given a program to
download during its countdown, it will write the program code to the device's flash
memory. It is assumed that the program code being downloaded is an INTEL hex file
which avoids the address ranges occupied by the bootloader (the last 100H
words of program memory).

The hex file is read by the bootloader program and stores the data in the according
memory region: either EEPROM data or flash memory. Configuration and ID
location words are ignored.


Microchip PIC16F87x(A) memory map with the bootloader installed

     Address
        0       |--------------------------|
               	| Reset: jump to bootloader|	
        0004    |--------------------------| 
               	|                          |
               	|                          |
        00FF    |                          |
               	|                          |
               	|                          |
               	|                          |
               	|                          |
               	|      Program space       |
               	|      available for       |	<--- Available space for user programs
               	|   downloaded programs    |
               	|                          |
               	|                          |
               	|                          |
               	|                          |
               	|--------------------------|
               	|       Bootloader         |
        Flash   |                          |
        TOP     |--------------------------|	<--- Top of flash memory is device specific


        0       |--------------------------|
               	|                          |	
               	|       Data EEPROM        |	<--- Data EEPROM size is device specific
        EEPROM  |                          |
        TOP     |--------------------------|



Any program locatations of the downloaded program that would overwrite the
bootloader will be ignored. This is to ensure the integrity of the
bootloader during its execution.

Compiling the Bootloader
#######################

The source code for the bootloader must be compiled prior to download into the
target device. The command lines used to compile the bootloader are:

picc --chip=16f877a bootldr.c --runtime=clib --codeoffset=1F00
or
picc --chip=16f877 bootldr.c --runtime=clib --codeoffset=1F00
or
picc --chip=16f877 bootldr.c --runtime=clib -DVERBOSE --codeoffset=1E80
to put the bootloader in verbose mode - prints a dot for each hex record read.
or
picc --chip=16f877 bootldr.c --runtime=clib -DVERBOSE=2 --codeoffset=1E80
to put the bootloader in a debug mode - all data is echoed back to the terminal

If using the PICC-lite compiler, stay within the bounds of the restricted
memory space. The above examples would translate to:
picl --chip=16f877a bootldr.c --runtime=clib --codeoffset=700
picl --chip=16f877 bootldr.c --runtime=clib --codeoffset=700
picl --chip=16f877 bootldr.c --runtime=clib -DVERBOSE --codeoffset=680
picl --chip=16f877 bootldr.c --runtime=clib -DVERBOSE=2 --codeoffset=680

The bootloader can be put into modes that are more informative if the symbol
VERBOSE is defined when compiling the bootloader source code. However, using the
bootloader in these modes will consume more program memory.

The --codeoffset option causes the bootloader to be linked at the address specified.
Below is a list of addresses to use depending on which processor is being
used and which mode is required:

================================================================================
| Processor    | Compact | Verbose | Vbose 2 | Cmp + ICD | V1 + ICD | V2 + ICD |
================================================================================
| 16F877A      | 1F00 ***| 1E80    | 1E80    | 1E00 ***  | 1D80     | 1D80     |
| 16F876A      |         |         |         |           |          |          |
--------------------------------------------------------------------------------
| 16F877       | 1F00    | 1E80    | 1E80    | 1E00      | 1D80     | 1D80     |
| 16F876       |         |         |         |           |          |          |
--------------------------------------------------------------------------------
| 16F877-lite  | 700 *** | 680     | 680     | 700 ***   | 680      | 680      | **
| 16F877A-lite |         |         |         |           |          |          | **
--------------------------------------------------------------------------------
| 16F874A      | F00     | E80     | E80     | E00       | D80      | D80      |
| 16F873A      |         |         |         |           |          |          |
--------------------------------------------------------------------------------
| 16F874       | F00 *** | E80     | E80     | E00 ***   | D80      | D80      |
| 16F873       |         |         |         |           |          |          |
--------------------------------------------------------------------------------
| 16F871       | 700     | 680     | 680     | 600       | 580      | 580      |
| 16F870       |         |         |         |           |          |          |
================================================================================

 ** Compiling with PICC-Lite requires consideration of memory restrictions.

 *** For loader to fit within this space on these chips, you need to guarentee that
   the hexfiles sent to the bootloader all begin on a word address that is a
   multiple of four AND have a data length that is also a multiple of four. PICC as
   of version 9.60 will generate a hexfile that meets these requirements. Otherwise
   a tool like hexmate can be used to condition the hex file to meet these
   requirements.

The above information can also be obtained from the BOOT_START define
located in the bootloader's header file.

Compiling Programs for Download
############################### 

The following considerations need to be made when compiling the application
for download:
- Compile and link with the --runtime=+download option.

- The program code occupied by the bootloader must be excluded.
   Avoid this location with the compiler switch --rom=0-XXX
   Where XXX is the start of the bootloader (from table above) minus 1.

- If building the bootloader in compact mode for a 16F87xA device and wishing
  to keep program usage to within 100h words, you need to guarentee that the hexfiles
  sent to the bootloader all begin on a word address that is a multiple of four AND
  have a data length that is also a multiple of four. The default output of
  the PICC compiler meets these requirements as of version 9.60.

Downloading Programs
####################

Once the bootloader itself has been downloaded into the processor, there is no
special program required to operate this bootloader. Any basic serial
communications program (such as HyperTerminal) will be sufficient.

By default the data trasfer rate is 9600 Bits per second. This again can be
changed, by modifying the BAUD definition in bootldr.h.

Note: The bootloader uses XON/XOFF software flow control for receiving the
downloaded program. Be sure you have this turned on in your terminal program.

Basic flowchart to describe bootloader operation
################################################

[START]
     |
     v
[init comms and device]
     |
     v
<Wait for user response>----> [EXIT: execute existing code!]
     |responded         no response
     |
     v
[Await incoming hex record] <-------------------------+-------------+
     |                                                |             |
     v                                                |             |
<hex record: EOF?>----> [EXIT:execute new program!]   |             |
     |             yes                                |             |
     | no                                             |             |
     |                                                |             |
     v                                                |             |
[data record]                                         |             |
     |                                                |yes          |
     v                                                |             |
<EEPROM/flash?>----> [select flash]--> <bootloader threatened?>--> [Write!]
     |         flash                                           no   ^
     |EE                                                            |
     |                                                              |
     v                                                              |
  [select EE]-------------------------------------------------------+



