$Id: design.txt,v 1.8 2001/08/28 22:36:50 rwuest Exp $

BIG FAT WARNING: Some of this doesn't work, this is a design document, not
a user's guide.  There is no users guide, yet.  Some of it's even out of
date :)

*************************************
The Idea:

Spgmr08 is a Linux software package for use in software development on the
Motorola Mc68HC908GP32 microcontroller.  The package consists of two programs:
spgmr is the main program that communicates with the 'GP32 and tkpgmr is a
GUI wrapper, written in Tcl/Tk (version 8.3 required).

Spgmr has three modes of operation: command line, interactive, and server.
The command line mode allows the program to be used from within makefiles
or other tools to automate programming operations.  The interactive and
server modes are very similar.  There is a command processor that accepts
commands and performs some action.  In interactive mode, this is console
input; in server mode it is through pipes or fifos.  The server mode is
mainly to support the GUI program, tkspgmr.


Spgmr communicates with a 'GP32 in an SPGMR08/ICD08GP20 through the
Monitor ROM interface.  It can read an S19 format data file and program
that data into a 'GP32.  It can also read the current contents to an S19
file.  It can erase the chip.  All actions can operate over the whole
memory range or specified portions.  A reset and Run feature can be used
to test the code.

There is minimal support for debugging.


*************************************
The command line (Don't count on any of this yet)

-aaddress_spec  --address address_spec
All actions take optional -a address range specifiers.  Multiple specifiers may
be given:

-astartadd:endadd
  or
-astart+count

The default address is all memory.  In the case of an erase command, the default
action is to bulk erase the part.


-C cpu

Specify which cpu is target.  Currently must be one of "gp32" or "ab32"

-p  --program [filename]
To program a file into the chip:
      spgmr [-a] -p file
If filename is omitted then stdin is assumed.


-r  --read [filename]
To read the chip's memory to an S19 format file:
      spgmr [-a] -r file
If filename is omitted the data is written in s19 format to the standard
output.

-e  --erase
To erase the chip:
      spgmr [-a] -e

-R --run [address]
To reset and run at an optional address:
      spgmr -R startadd
      spgmr --run startadd
If the start address is omitted then the user reset vector is used.

The order in which command line actions are taken is important.  The order
on the command line itself is not important.  If an erase option is given,
the chip will first be erased.  If a program option is given, the part
will then be programmed.  If an read option is given, the part will be
read.  Finally, if the run opttion is given, it will be processed.  So it
is prossible to run the program with a command like this:

      spgmr -e -p s1file.s19 -r verify.s19 -R startadd

This command willl erase the part, program it with the contents of
s1file.s19, read the device back into verify.s19 then reset and run the
program.

-P  --port devname
This specifies which serial port to use.  The default is:
      spgmr -P /dev/ttyS0

-G  --progress
Spgmr will produce hash marks and messages to the standard as it
progresses.  This likely will change to -v  --verbose.



*************************************
Environment variables

Some things, such as processor module locations can be specified in the
environment.  Eventually, a default libray for modules will be compiled
in, probably /usr/local/lib/spgmr08 by default.  This may be overriden
with the SPGMR08="baseDirectory" environment



*************************************
Interactive mode

Starting spgmr with no options or the -i option will enter an interactive
session.
The command line is built with the readline and history libraries, so it
supports full command line editing and history retrieval.  History is
saved in the current directory


Useful Interactive Commands

read address_exp
read address_exp to "s19file"
write address value
write from s19file
erase
program from filename
verify from filename
scodes from filename
wcodes from filename
wcodes blank
debug (on|off)
debug serial (on | off)
debug monitor (on|off)
debug fileinfo
source filename

See the grammar.txt file for EBNF details of the grammar.

An address expression is just ike on the command line.  There are two
forms, start:end and start+count.  For exammple "read 0+2" will read 2
bytes: 0 and 1, "read 0:2" will read 3 bytes, 0, 1, and 2.

Filenames with spaces _must_ be quoted.

Need to add symols and symbol file support, like in disasm09, and address
experssions should accept symbolic names. Later.


*************************************
Server mode

There is a server mode to support the TclTk GUI, tkspgmr.  The client must
open a couple of pipe channels (pipe twice to get two inodes), and dup
stdin and stdout, before fork-and-exec'ing.  If the stdin is not a tty
(and the -i option is not given), it enters the server mode.
[maybe should do all three standard channels]

This mode uses the command interpreter to perform its work.  The only
differences are that the prompt has the final space replaced with a
newline to permit easy synchronization and errors go out stdout.

The -i option is there to allow you to force interactive mode, even if the
input file is not a tty, such as inside an IDE.

TODO: return errors up the pipe.
Maybe prepend the string with "error:<num>:text". <- done


*************************************
Security codes

The security codes used to fully enable the 'GP32's read memory access
are stored in a file in the users home directory, ~/.spgmr08rc.  Currently, this
is all that is stored in this file, a list of up to 10 security codes, tried in
order.  When a file is programmed, it's security code is written to the top of
the list and the last one is removed (when the number of codes reaches 10).

The security code is the bytes in locations $FFF6$FFFD.

The security codes file may be specified on the command line with the -S
option:

 -S filename

 -C  --sec-code	filename
Displays the security codes in an S19 file.

Notes on code management.

After a reset, codes need to be sent
After a program operation, codes need to be copied to sec_codes[0]
After an erase, sec_codes[0] need to be set to 0xff's
wcodes needs to accept 8 values to use
wcodes needs to accept a single value which is a sec_codes index

Security code commands

scodes from filename
   read scodes from file and push on scode stack

scodes integer
   show codes (-1 -> 9 )



wcodes
   send to target the scodes at top of stack

wcodes from filename
   read scodes from file and send to target

wcodes integer
   send scodes to target, integer is stack location (0 to SECCMAX)


New scodes syntax:
scodes send from filename
scodes send as int int int int int int int int
scodes send int

scodes show all
scodes show int
scodes show from filename

scodes set from file name
scodes set int as int int int int int int int int

scodes push int as int int int int int int int int
scodes push from filename

scodes try from filename
scodes try int
scodes try all
scodes try blank


*************************************
MC68HC08 Functions

Two 68HC08 modules are used to support erasing and programming/verifying
of the target.  These currently must be in the current directory.

The first module is erase_gp32.s19.  Source is in erase_gp32.s.  This
module loads at address $100 (also the entry point) and performs a mass
erase, if the accumulator is 0 on entry.  Other codes will be used for
erasing specific pages.

The second module is program_gp32.s19.  Source is in program_gp32.s.  This
module supports buffer loading, flash memory programming and verify
operations.  The load address and entry point is $100.  The accumulator is
used to control the function and the H:X registers are used for other
parameters.  If the accumulator is 0, X is byte count of data to read to
the bufffer.  If the accumulator is non-zero, it is a byte count to either
program or verify (add 128 to the byte count to verify).  H:X contains the
destination address (which better line up on a page ).

These are written using the asl assembler.  ASL is here:
http://john.ccac.rwth-aachen.de:8000/as/



*************************************
Supporting More than just the GP32

There are a number of parameters that must be definable to support
multiple processors.  Here's a list

Processor name
Program / module name (external '08 code)
Program / algorith function (internal function, talks to above)
Erase module name
FLASH address ranges
EEPROM address ranges
Security code accepted location:bit
Do they all use the same security code scheme?
DO I need row and page sizes



*************************************
CPU Management (NEW STUUF - MULTIPLE CPU TYPES)

The oerations on the various types of CPU's is abstracted in a
struct target_operations (defined in ops.h).  This is typedef'd to CPU and
all operations are through functions taking a CPU *, similar in concept
to the stream  I/O FILE*.  To use a cpu, you must first open it with
CPU *cpu_open(char *cputype).  Further operations, such as erase or
program are through functions taking a CPU*: erase(CPU*),
program_flash(CPU*,char *filename).  The cpu type maybe changed without
restarting by a call to close_cpu(CPU*), then another cpu_open(char *type);

Adding new cpu types should be fairly straightforward now.  See the
source in ops.c and ops_gp32.c and ops.h. Should be renamed
cpu_blahblahblah.

The cli interface maintains a single cpu.  The cli script language
supports "cpu", which returns the current name, and "cpu type",
where currently, type can be one of gp32 or ab32.

The transition to this interface is not complete, although the main
operations have been rewritten and the two types of cpus appear to
function properly.








*************************************
Miscellaneous notes

Name serial interface lin_serial in case someone wants to port this to a
broken OS.
Allow baud rate control to talk to non-standard systems.  Virtually any
baud rate is possible.
There are 6 programming languages used in this project:
   C
   PCCTS
   spgmr script
   monitor commands
   68HC08 assembly
   Tcl/Tk
   (HTML, making 7, if I add a webite.  Do manpages count?)

GUI could add pink highlight to messages.
"return" messages could be boldened.  Like "Program OK" an "Erased" and
"Passed".

Display the spgmr prompt.  Leave the cursor at the end and when output is
send, append it.  WIll look just like the console mode.  Bind enter so the
line the cursor is on is sent as a command.  Remove the command line at
the buttom.  (Get crazy and use a history, maybe arrows could be done to
use history in the server!)

Need to send the cpu in start (?and highlight the message)
Need a better name: how about mcps, the master chip programming system.


