
DOWNLOADER AND RT-MONITOR
-------------------------

CONTENTS:
- Copyright and Usage Terms
- Introduction
- Practical Issues
- Monitor/Downloader Usage
- RT-Monitor Commands
- Downloader
- Baud Rate Calculation
- Error Flag Bits
- Changes in version 2



****************************************************************
COPYRIGHT AND USAGE TERMS

Copyright (c) B Knudsen Data 1999-2002, Trondheim - Norway.

This code can be used FREE for all kinds of testing and debugging of
PICmicro programs. This also includes permission to modify and
extend the source code for the purpose of such testing and
debugging.

Permanently including the binary code in a commercial product
requires a license of the CC5X compiler.

Resale and redistribution of the possibly modified monitor source
code will require written permission from B Knudsen Data.

B Knudsen Data assumes no responsibility for errors or defects in
the software or in the documentation supplied. Any use of this
software implies the acceptance of this condition.



****************************************************************
INTRODUCTION:

Developed for use on the PIC16F870/871/873/874/876/877 and the
PIC16F873A/874A/876A/877A devices. Can be adapted to other PICmicro
flash devices.

The code has been strongly optimized for size and low memory usage.
Also the call level usage is kept low to enable calls from the
application program.

NOTE that the 16F87XA needs in general around 100 more code words
than the 16F87X, and use a few more RAM locations.

* general features:
    * terminal ASCII interface
    * accepts CR or LF or both for line termination
    * starts on device reset and/or can be called from user program
    * only around 650 code words (52 byte RAM) for ALL features
        * including 50 words for (minimal) help info
    * 580 code words (49 byte RAM) for Downloader & RT-monitor
    * requires 3 stack levels (can be reduced to 2)

* rt-monitor features:
    * size: 408 code words (standalone), RAM around 22 bytes
    * display and change RAM, PROGRAM code and EEPROM memory
    * uses hexadecimal numbers only

* downloader features:
    * size: 434 code words (standalone), RAM around 43 bytes
    * automatic downloading (no command required)
        * detects ':' and turns off echo
    * automatic program start after programming (eof-record)
    * downloads ASCII file, INTEL HEX FORMAT (INHX8M)
        * INHX32 is optional
    * skips programming of program memory words that are unchanged
    * program EEPROM data
        * address 0x2100-0x217F/0x21FF
    * comprehensive error detection
        * detects many kinds of errors that may occur during
          downloading
        * test program word after writing
        * set error flag if location was not programmed correctly
    * uses XOFF and XON to stop data stream while programming
    * enables long distance (modem) programming by using a buffer
    * avoid data for device fuse registers (0x2007)
    * protection on overwriting downloader code



****************************************************************
PRACTICAL ISSUES:

Communication:

    The monitor/downloader use the USART for communication with the
    external world.

       RC6/TX pin : output serial data from PICmicro device

       RC7/RC pin : input serial data to PICmicro device

    Note that the signal levels needs to be adapted to a standard,
    i.e., RS-232 or RS422. How to do this is not described in
    this documentation.

    The serial data format is (unless changed in the source code):

      * one start bit
      * 8 data bits, bit 0 first
      * one stop bit
      * baud rate is selectable by changing 'monitor.h'


WRT: Flash Program Memory Write Enable
    The WRT bit need to be set to 1 to enable FLASH programming
    from application/downloader program.
    WRT: bit 9 of the Configuration Word (address 0x2007).
    More documentation is found by reading section 'Special Features'
    of the Microchip PDF manual for the particular device.

NOTE that the Configuration word (0x2007) can NOT be reprogrammed
from the downloader/monitor!


Interrupt:

    The monitor/downloader does not use interrupt. The user
    application may contain an interrupt routine if needed. However,
    if interrupts need to be enabled when entering the monitor, some
    monitor source modification may be required. Just search for GIE
    in 'monitor.c' and change the code as required. Just remember
    that interrupt must be DISABLED during FLASH/EEPROM programming,
    and also that USART interrupt must be disabled until the monitor
    exits.

    In file 'monitor.h' there is a macro 'RESTORE_GIE' which should
    be defined if GIE should be restored on return from the
    monitor. This is useful only when RTMONITOR is defined.


Monitor activation:

    DEMO.c :  demo application that includes the loader/monitor code
    DEMO1.c : demo application to be loaded using the loader/monitor
    DEMO2.c : demo application with hardcoded breakpoints and testpoints

    Program 'demo.c' show how to embed the monitor/downloader into
    an user program. By defining:

      #define START_MONITOR_ON_RESET

    the monitor/downloader will be started instead of the application.
    The startup sequence is found in 'rtmon.h'.

    NOTE: START_MONITOR_ON_RESET must be used consistently,
    i.e. not changed on later compilations/downloads.

    It is possible to add code that will test the state of an input
    pin, and starting the application or the monitor depending on
    the state of this pin. This code can be inserted both in
    routine monitor(); or in the user application.

    Note that RTMONITOR need to be defined in order the get a RETURN
    when routine monitor(0) finishes. If RTMONITOR is not defined, a
    restart will occur. Using monitor(1) will always give a restart.


Features enabled: defined in 'monitor.h'

    The start address of the monitor/downloader utility can be
    adjusted (file 'rtmon.h') according to the features enabled. No
    user program can exceed the LOADER_START address.




****************************************************************
MONITOR/DOWNLOADER USAGE:

1. The monitor can be started in the user program, for example after
   checking an input pin in the initialization sequence or in the
   main program loop. Note that 3 stack levels must be available.
   The start-vector is normally set to address 0 (no call to the
   monitor at startup). The monitor will use some RAM (at high
   addresses) for temporary storage. The application can use this
   RAM between calls to the monitor.

2. An optional way of activating the monitor/downloader is to start
   it at device reset. This is done by inserting:

     #define START_MONITOR_ON_RESET

   before the #include "rtmon.h" statement. Assembly users should
   add similar code as shown in this file at address 0-2 and put the
   start-vector at address 3. That is all. User code can not
   overwrite the downloader code (protected). All RAM memory can be
   used in the application.

The use of the downloader can be redefined at each program download.
The restriction is that the reserved downloader code area can not
be programmed, and the application resetVector must not be changed.

The monitor/downloader RAM area can be used in the application
code. Note that these location can change when using calls to
the monitor.

3. The RT-monitor can included in non-flash devices also. Some
   editing is required to remove the programming feature. The
   available features will be inspect/change RAM, execute
   function, application supported breakpoints and testpoints.


****************************************************************
RT-MONITOR COMMANDS:


NOTE: all values are HEXadecimal

    M<adr>     : show RAM, 16 lines of 16 values, from address <adr>
    M<adr>+<n> : show <n> RAM values, from address <adr>
    M<adr>=<v> : change RAM, single address
    M          : show RAM, 16 lines of 16 values, from address 0
    M+<n>      : show <n> RAM values, from address 0

    C<adr>     : show CODE/EEPROM, 16 lines of 8 values, from address <adr>
    C<adr>+<n> : show <n> CODE/EEPROM values, from address <adr>
    C<adr>=<v> : change CODE/EEPROM, single address
    C          : show CODE/EEPROM, 16 lines of 8 values, from address 0
    C+<n>      : show <n> CODE/EEPROM values, from address 0

    G       : go (start/restart/continue)
    F<adr>  : execute function (bank bits are set to 0 before call)
    R       : reset program (enable restart)

    <cr>    : continue if call (not startup)

    H       : help


Example commands:

    M20+10<cr>  : show 0x10 bytes of RAM, from address 0x20
    M20=FF<cr>  : set RAM address 0x20 equal to 0xFF
    C100<cr>    : show program code from address 0x100



****************************************************************
DOWNLOADER:


Uses INTEL HEX format: INHX8M

8 bits format:
    :BBaaaaTT112233...CC
    BB   - number of 8 bit data bytes, up to 16
    aaaa - hexadesimal address (byte-address)
    TT   - type :
            00 : normal
            01 : end-of-file   (:00000001FF)
    11   - 8 bits data byte
    CC   - checksum: adding all bytes must be 0



****************************************************************
BAUD RATE CALCULATION:

async low speed: baudrate = Fosc/(64(X+1))
async high speed: baudrate = Fosc/(16(X+1))

  X = value in SPBRG (0-255)

  X+1 = Fosc / 16 / baudrate / (1 + 3 * !BRGH)

Examples

   X+1       Error   Fosc     baudrate  BRGH
   26.04166  0.16%  16000000   9600      0   (64)
   13.02083  0.16%  16000000  19200      0   (64)
   13.02083  0.16%   8000000   9600      0   (64)

  104.16666  0.16%  16000000   9600      1   (16)
   65.10417  0.16%  20000000  19200      1   (16)
   52.08333  0.16%  16000000  19200      1   (16)
 --34.72222  2.12%  16000000  28800      1   (16)
   26.04166  0.16%  16000000  38400      1   (16)
 --17.36111  2.12%  16000000  57600      1   (16)
   52.08333  0.16%   8000000   9600      1   (16)
   26.04166  0.16%   8000000  19200      1   (16)
 --17.36111  2.12%   8000000  28800      1   (16)
   13.02083  0.16%   8000000  38400      1   (16)
   26.04166  0.16%   4000000   9600      1   (16)
   13.02083  0.16%   4000000  19200      1   (16)



****************************************************************
ERROR FLAG BITS:

  After finishing receiving an INHX8M file, the downloader will
  return some information

   #1233:03 /00

    #<number-of-words-programmed-in-hex>
    :<extra-buffer-space-needed-after-XOFF-in-hex>
    /<error-bits>

  BIT error:
   0  lineOverflow        - too long single line (skipped)
   1  dataLost            - too small xtra buffer or no response to XOFF
   2  framingOrOverflow   - single character error (stopbit etc)
   3  RecordFramingError  - data record not correct
   4  ChecksumError       - checksum wrong
   5  RecordTypeError     - third byte not 0 on non-eof, or odd address
   6  programmingFailed   - unable to program location
   7  downloaderOverwrite - attempt to overwrite downloader/monitor code



****************************************************************
CHANGES IN VERSION 2


  1) When AUTOSTART is defined, there will always be a full restart
     of the application when the EOF record is detected during
     download, independent of the parameter used when calling the
     monitor routine.

  2) The prompt is displayed on various record errors during
     downloading. This ensures that the prompt ('>') is not lost if
     the download fails for some reason.

  3) The display command of RAM/SFR locations above address 0x100 is
     corrected.

  4) Corrected bug for execute single functions (F<a>). Also, the
     bank selection bits are set to 0 before the call.

  5) Support for the 16F87xA devices is added. Because these devices
     requires 4 program words to be programmed at once, the code
     size increases by about 100 words.

  6) Two additional demo programs are added to make it clearer how
     to use the monitor/downloader.

  7) Corrected bug to enable EEPROM contents to be included in a
     downloaded hex file.

  8) Optional support for INHX32 records.

  9) Optional support for WATCHDOG.

