
      Ash version 3.0 (C) 1997 by Mattias Lindqvist & Dines Justesen


Table of contence

 What is Ash?
 Addresses
 Files included
 Requirements
 Installing Ash
 Using Ash
 Programming for Ash
 Credits
 Legal notice
 History

What is Ash ?


Ash is program which allows you to use programs written in assembler on your
TI82. Ash works like a shell in the way that it presents a list with all
assembler programs currently availble, and then lets you run them. If you have
used ZShell for the TI85 you know what it is like.

Addresses


If you like to contact one of the developers of Ash use the adresses below.

Dines Justesen at c958362@student.dtu.dk or
Mattias Lindqvist at ml@df.lth.se

(Mattias is currently very hard to get a hold of, so if you want your answer
fast, write to Dines)

You can always find the newest version of Ash at one of the locations below.

http://www.gbar.dtu.dk/~c958362/ash/
http://www.ticalc.org/

Files included


ASH.TXT    This file
ASH.82B    Backup containing Ash
PRGM82.EXE Program to convert OBJ files to 82P files
TI82.H     Header file for use with TASM
ASM.BAT    Batch file to assemble files and convert them to program files

Requirements


Ash version 3.0 works with the following rom versions : 16,17,18 and 19. To
check what ROM version your TI82 has got, press the following key sequence:
[MODE] [ALPHA] [S]. You will be presented with a screen telling you your ROM
version and a prompt asking if you want to start the selftest. DON'T PRESS
ENTER at this prompt unless you want your calculator to go through a memory
resetting selftest procedure. If you have a TI82 with another rom version,
contact Dines Justesen, and we will try to include your rom version in the
next release.

Installing Ash


To install Ash on your calculator you need a link cable, so you can transfer
the backup file to your calc. To install Ash send the backup file to your
calc. If you do not have a link cable you can get Ash by getting a backup
from another calc which has Ash installed.

Using Ash


To start Ash, execute the program called ASH like a normal basic program.
After pressing ENTER once you will be presented with a list of all the valid
asm programs on your calc. If there are no valid asm programs on the calc you
will see the text "NO PROGRAMS" on the display.

To chose a program press UP/DOWN to select the program you want. If you have
more than 8 programs press RIGHT to see the next programs. To start a program
press ENTER.

Inside the shell you can change the contrast by pressing 2nd UP/DOWN. Ash
also supports APD, so if you leave your calc on it will automaticly turn off
if no keys are pressed. Pressing 2nd ON will turn off the calc, when you
turn it on again you will be placed at the homescreen. If you press ON the
calc will be turned off, and it will still be in Ash when you turn it on.

To exit the Ash press MODE. Pressing LINK will exit Ash and goto the link
menu.

Please note that Ash programs written for version 1.0, 1.1 or 2.0 will not
show up in the shell, they have to be recompiled to work with Ash 3.0. 

Instead of starting a program from Ash, some Ash programs can be started like
basic programs (with the prgm command). Wether or not a program supports this
is decided by the author, so refere to the readme file for the program to see
if it supports it. You can also check this you self, try to run the program
if this is not supported nothing will happen.

Programming for Ash


Because there are some many programmers out there who are used to programming
for ZShell, we have tried to make programming for Ash very similar. We hope
that this will make it easier for people who are used to ZShell to program
for Ash. Since Ash supports relocation, some part will be rather different,
but it should make programming easier when you get used to it.

The calculator is always moving the variables around in memory, therfore you
never know at which address you program will be placed when it is executed.
To solve this problem Ash moves the program to the start of the user mem
before executing it. This means that you can use normal calls and jumps
without problem.

The relocation also means that it is to acces data stored within your own
program. For exampel the following code will load HL with a pointer to the
string called Str1.

        LD HL,Str1

This requires that you start your program with the directive .ORG START_ADDR.

There are several places where you can store temporary data, one of them is
the text memory. Ash always initializes the text mem to zeros before starting
a program, so if you place your data here you do not have to do that. If that
is enough memory backup buffer used for APD is another good place to use if
you program is not using APD. Also the graph mem and OP1..Op6 can be used if
these are not needed for other things.

Another problem is that some functions are placed in different location in the
different rom versions. To make it easy for the programmer Ash includes a
functions which takes care of this for you, you can use it by calling the
function using the macro ROM_CALL. The functions is made so that it supports
all functions in the rom placed from 2EA0 to 39EC (this is where most of the
useful functions are placed). Just call the function (using ROM_CALL), with
the adress in rom version 18 or the adresse in rom version 19 minus 1Ah. Some
of the functions in the begining of the rom are placed in the same locations in
all rom versions, you can call these directly by using call. In TI82.H you
can find a list of commenly used functions, and it also tells you how to
call it. 

To convert the OBJ files produced by the assembler to the 82P files which
the link program handles, use the program PRGM82 (which is included in the
Ash zip file). Included is also a small batch file to assemble a program and
convert it to a 82P file. Please note that this is a newer version of the
program, than the one which came with Ash 1.0, 1.1 and 2.0, do not use the
old one. If you wish to make it possible to start your program like basic
ones, use PRGM instead of PRGM82. This will add a header to the file which
is app. 45 bytes, and that is all which is needed (no extra programming).

In the Ash zip file two extra header files (OLDCALL.H and KEYS.INC) are
included. These files are intended to hwlp you programming for Ash. KEYS.INC
hold a list of key for both the TI82 keyboard handlers, so you can use the
names instead of the numbers. 

To help people who have written programs for Ash 2.0 to convert them so they
work with Ash 3.0 we have included OLDCALL.H which includes some useful 
definitions. If you include OLDCALL.H in your Ash 2.0 program you should be
able to compile it right away, but it will not run as fast as if you removed
all lines dealing with PROGRAM_ADDR. If you have written a program for an older
version of Ash and have problems getting it to work with Ash 3.0, feel free to
mail Dines Justesen.

Below is a list of text files to help you program for Ash.

82RAM.TXT    Lists useful addresses in the system part of the ram
82ROM.TXT    A list of functions in the rom
82PORTS.TXT  Explains what the ports are used for
82VAR.TXT    Varius information about the TI82

All documents are written by Mattias Lindqvist and Dines Justesen. If you
need help, you should be able to find it at one of existing mailing lists.
You can find a list of them at http://www.ticalc.org. If you have any
questions on programming for Ash or general Z80 programming questions feel
free to mail Dines. Also Dines' Homepage (http://www.gbar.dtu.dk/~c958362/)
contains a list of Z80 books, which you might find useful.

Credits


Thanks to the beat testers of Ash 3.0 :
    Andrew Von Dollen
    Brian Ryner
    Dave Jaklitsch
    Sam Davies
    Scoobie

To David Endahl for reporting the minor bug in version 1.0.
To Scoobie for making the Ash 3.0 poll,
and to Dominic Cooney for making me include the PRGM feature.

Legal notice


All the files included in the Ash zip file is our work. You are welcome to
distribute the files as long as they are kept together in an unmodified
form. If you do decide to put Ash on your www page, please notify one of
the developers.

If the your calc locks or frezzes ... the developers can in no way be
responsible for it.

YOU ARE IN NO WAY ALLOWED TO DISTRIBUTE MODIFIED VERSIONS OF ANY OF THE FILES
WITHOUT PRIOR APPROVAL FROM THE AUTHORS.


History


June 1997 : Version 1.0
            First version released.

June 1997 : Version 1.1
            When the first version was released the wrong backup file was 
            included, therefore a new version was released. 

June 1997 : Version 2.0
            Ash now supports other rom versions than 19.
            ID bytes in programs changed so old programs wont show up in the
            shell.

August 1997 : Version 3.0
              Simpel relocation added. Keys changed according to the users
              whises. Powerdown and acces to the linkmenu added. Support for
              write protected programs added. Ash now uses ZShell like
              descriebtions instead for variable names. It is now possible to
              start Ash program using the prgm command. 
            
