TI-83/TI-86 Small-C by Chris Dannemiller and Jeremey Scoggins:

Contents
    1.  Forward
    2.  What is new
    3.  Bugs
    4.  Programs
        4.1.  8xcc
        4.2.  go8x
    5.  Functions
    6.  Future of TI-83/TI-86 Small-C
    7.  What you can do to help me
    8.  TI-83 Considerations
    9.  Making functions for C in Z80 Assembly
    10. Notes to all programmers
    11. Credits

1. Forward:

    This program was originally written for me because of how much I hated
to code in Assembly.  I decided to release it to the public and the rest is
history.

    A couple of weeks before the release of Beta-3 I went of the my friends
house and we got the compiler to work the with the TI-83.

    The changes between programming your C programs in 83 to 86 or 86 to 83
should be minimal. Take not of the TI-83's FastCopy routine.  The TI-86
does this automatically with does cause flicker on the TI-86.

    E-mail Chris Dannemiller for all TI-86 releted questions. E-mail Jeremy
Scoggins for all TI-83 releated questions.  For genral Compiler/Assembler
questions E-mail Chris Dannemiller.

    You can download the most up-to-date version of this documention off
my web page.  This version is ussally newwer then the one that you download
with the Small-C Package.

2. What is new:

  Beta-5: (25/08/99)
    Speed ups/Size Srinkage to CTYPE.C
    Converted even more C code to assembly
    Added Following Funtions to the libary:
        assert, exit, abort, isalnum
    The puts function supports '\n'. Make sure to use this becuse it will
        save program space.
    Fixed a problem that would not all usage of more then one sprite funtion
      in a program
    More samples (mainly of new C-Functions)
    Cleaned up the ASM directory by merging files
    Made compiled code a couple of bytes smaller
    Made a SRC directory and put all source code their to make things
      eaiser to find
    When go8x runs if a program fails it will return that error code and
      quits compiling process at that point.
    This may be the last release :(
  Beta-4: (08/03/99)
    Added the long awaited sprite routines to the libary.
    Fixed the Switch/Case bug.
    Fixed Mouse83.c program should now compile.
    Made GO8X smaller and eat up less memory.
    Much better lights out example includes all 50-levels for TI-86 only.
      Check back at our web page for the TI-83 version when it is done.
    Graphics functions should now work with the TI-83!
  Beta-3: (05/03/99)
    TI-83 Support (CD/JS)
    Ported all of the graphics routines to TI-83 (JS)
    Ported lights out example to TI-83 (JS)
    Added a smart Compiler that does works like go.bat but much better.
      this code was written from scratch so it could have bugs.(CD)
    Documentation Rewrite (CD)
    limits.h implementation (CD)
    Re-directing .h Files (CD)
    Some functions re-written to assembly (CD)
    Uses the Faster Find Pixel Routine for the TI-86 (CD)
    Downloaded and incorporated a updated TASM80.TAB File (CD)
    Function Descriptions (CD)
  Beta-2: (??/12/97)
    My home page now allows you to download and get info on this program (CD)
    Added Beta Optimizer (CD)
    Speedup Line, Pixel Routines (CD)
    Added Pixel, Line, Box Change Pixel Routine (CD)
    Added Several New routines (CD)
    Made the Lights out example more complete (CD)
    Add more of the base functions in ti86.h (CD)
  Beta-1: (??/??/??)
    Initial Release. (CD)

CD denotes that Chris Dannemiller worked on this portion
JS denotes that Jememy Scoggins worked on this portion
If neither dentotion is given Chris Dannemiller worked on it

3. Bugs:

    If you find any bug in this software package please e-mail the bug report
to: dannemiller@hotmail.com (Subject: TI-83/TI-86 Small C Bug Report). I will
try to address the bug and fix it by the next version.

4. Programs:

    This section tries to give you information about programs that are
contained within this package.

    Not all programs are listed here yet because I wanted to get this program
out.

    4.1. 8xcc

    This file was ported for the scc and re-written for TI-83 and TI-86
support by Chris Dannemiller. The following is the command line information:

usage: 8xcc [-tcsax] [-dSYM[=VALUE]] -m[TI83 or TI86] files

    -tcsa Not sure what these do please e-mail me if you do
    -x Frame IX to sp... Does not work with the TI-86 wonder why?
    -y Frame IY to sp... Just somthing I tried left in for acdemic purposes
    -d Defines the SYM(symbol) as the (value) if no value is given it simply
       defines the value.
    -m Specifies the TI-8? mode. The valid values are TI83 for TI-83
       calculators and TI86 for TI-86 calculators. The macro __mode__ is
       defined. Where mode is the mode given with the -m parameter. This value
       is required. So if the value TI83 is given the macro __TI83__ is given.
    files: Files to be compiled.

    4.2. GO8X

    This program was designed to make your job eaiser when trying to compile
a .c program file.  It was orginally a batch file that was very limited in
power but now you have this wonder program to do the job for you!

GO8X -cxx [options] file

  -c is the calculator mode.  Valid values are 83 for TI-83 and 86 for TI-86

  -Ipath  = The location of the include path
  -Lpath  = The location of the Library path (NOT USED)
  -Epath  = The location of the Executables (8xcc, dcpp, copt)
  -Apath  = The location of the Assembler   (tasm)
  -nologo = Do not print logo (GO8X Program Only)
  -compile= Compile to (.OPT or .ASM) only
  -noopt  = Do not use COPT to optimize program
  -keep   = Do not delete intermediate files (useful for debugging)
  -ifile  = INI File name (default: GO8X.INI)

5. Functions

Function:     abs(int num)
Parameters:   num - Number to take the absolute value of
Returns:      Absolute value of number
Include File: ABS.C
Description:  Returns the absolute value of 'num'

Function:     atoi(char *s)
Parameters:   s - String to convert to a number
Returns:      Converted number
Include File: ATOI.C
Description:  Converts the string 's' to a number

Function:     box(char x1, char y1, char x2, char y2, char color)
Parameters:   x1 - x coordinate of the top left corner of the box
              y1 - y coordinate of the top left corner of the box
              x2 - x coordinate of the bottom right corner of the box
              y2 - y coordinate of the bottom right corner of the box
              color - color of the box. See Color table(Function pixel())
Returns:      Nothing
Include File: BOX.C
Description:  Draws a box on the screen with given parameters

Function:     delay(int n)
Parameters:   n - Amount to delay (n/200ths of a second)
Returns:      Nothing
Include File: DELAY.C
Description:  Delays the calculator of n/200ths of a second. Might work
              differently on the TI-83 if so e-mail me for its clocking.

Function:     FastCopy(void)
Parameters:   None
Returns:      Nothing
Include File: FASTCOPY.H
Description:  Copies the TI-83 Screen buffer to the TI-83 screen. For use with
              the TI-83 Only

Function:     getkey()
Parameters:   None
Returns:      int, Key pressed
Include File: TI.H
Description:  Depending on the calculator mode determines how this function is
              handled. It returns the k* state. In TI-86 mode it waits for
              a key press. In TI-83 mode it does not.

Function:     isalpha(char c)
Parameters:   c - Charter to check
Returns:      1 if charter is a letter, 0 if not
Include File: CTYPE.C
Description:  Returns whether or not given charter is a letter

Function:     isdigit(char c)
Parameters:   c - Charter to check
Returns:      1 if charter is a number, 0 if not
Include File: CTYPE.C 
Description:  Returns whether or not given charter is a number

Function:     islower(char c)
Parameters:   c - Charter to check
Returns:      1 if charter is a lowercase letter, 0 if not
Include File: CTYPE.C
Description:  Returns whether or not given charter is a lowercase letter

Function:     isspace(char c)
Parameters:   c - Charter to check
Returns:      1 if charter is a space, tab, or new line. 0 If not.
Include File: CTYPE.H
Description:  Returns whether or not given charter is one of the following:
              space, tab, and newline.

Function:     isupper(char c)
Parameters:   c - Charter to check
Returns:      1 if charter is a uppercase letter, 0 if not
Include File: CTYPE.C
Description:  Returns whether or not given charter is a uppercase letter

Function:     itoa(char* str, int num)
Parameters:   char *str - Pointer to store number string into
              int num   - Number to convert
Returns:      Returns str;
Include File: ITOA.C
Description:  Converts number 'num' to a string array at memory location given
              by 'str'.

Function:     line(char x1, char y1, char x2, char y2, char c)
Parameters:   x1 - x coordinate of the top left corner of the line
              y1 - y coordinate of the top left corner of the line
              x2 - x coordinate of the bottom right corner of the line
              y2 - y coordinate of the bottom right corner of the line
              c  - color of the line. See Color table(Function pixel())
Returns:      Nothing
Include File: LINE.C
Description:  Draws a line for (x1,y1)-(x2,y2) with color 'c'.

Function:     pixel(char x, char y, char c)
Parameters:   x - x coordinate to draw pixel
              y - y coordinate to draw pixel
              c - Color
              PT_ON     - Turns pixel on
              PT_OFF    - Turns pixel off
              PT_CHG    - Changes pixel state
Returns:      Nothing
Include File: PIXEL.C
Description:  Draws a pixel at (x,y) with color 'c'.

Function:     putc(c)
Parameters:   char c - Charter to print to screen
Returns:      Nothing
Include File: TI.H
Description:  Displays charter 'c' at current cursor location and moves cursor.

Function:     putm(c)
Parameters:   char c - Charter to print to screen
Returns:      Nothing
Include File: TI.H
Description:  Displays charter 'c' at current cursor location and does not
              move the cursor.

Function:     puts(str)
Parameters:   char *str - string to display to screen.
Returns:      Nothing
Include File: TI.H
Description:  Displays the string 'str' at current cursor location and moves
              cursor to the end of the string

Function:     sprite(ptr, x, y, width, height)
Parameters:   char *ptr - pointer to memory where sprite is
              char x - x coordinate of the upper left hand corner of the sprite
              char y - y coordinate of the upper left hand corner of the sprite
              char width - width of the sprite must be less then 8.
              char height - heigt of the sprite
Returns:      Nothing
Include File: SPRITE.C
Description:  Draws a sprite at (x,y) with size (width,heigt).  Draws 1's as
              black and 0's as white

Function:     sprite_tran(ptr, x, y, width, height)
Parameters:   char *ptr - pointer to memory where sprite is
              char x - x coordinate of the upper left hand corner of the sprite
              char y - y coordinate of the upper left hand corner of the sprite
              char width - width of the sprite must be less then 8.
              char height - heigt of the sprite
Returns:      Nothing
Include File: SPRITE_T.C
Description:  Draws a sprite at (x,y) with size (width,heigt).  Draws 1's as
              black and skips 0's

Function:     sprite_xor(ptr, x, y, width, height)
Parameters:   char *ptr - pointer to memory where sprite is
              char x - x coordinate of the upper left hand corner of the sprite
              char y - y coordinate of the upper left hand corner of the sprite
              char width - width of the sprite must be less then 8.
              char height - heigt of the sprite
Returns:      Nothing
Include File: SPRITE_X.C
Description:  Draws a sprite at (x,y) with size (width,heigt).  Changes pixels
              that are 1's and skips 0's


Function:     setxy(x, y)
Parameters:   char x - x location to set cursor
              char y - y location to set cursor
Returns:      Nothing
Include File: TI.H
Description:  Moves the text-cursor to given location.

Function:     strcat(char *s1, char *s2)
Parameters:   s1 - destination string
              s2 - source string
Returns:      value of s1
Include File: STRCAT.C
Description:  Attaches string 's2' to string 's1'

Function:     strcmp(char *s1, char *s2)
Parameters:   s1 - string one
              s2 - string two
Returns:      0 If strings the same. Otherwise non-0
Include File: STRCMP.C
Description:  Compares a string 's1' with another string 's2'.

Function:     strcpy(char *s1, char *s2)
Parameters:   s1 - String destination
              s2 - String Source
Returns:      value of s1
Include File: STRCPY.C
Description:  Copies a string 's2' to another string 's1'

Function:     strlen(char *s)
Parameters:   s - String to check the length of
Returns:      Length of string s
Include File: STRLEN.C
Description:  Returns the length of a string 's'.

Function:     tolower(char c)
Parameters:   c - Charter to make lowercase
Returns:      If charter is uppercase it returns it uppercase complement
              otherwise it just returns 'c'
Include File: CTYPE.C
Description:  Returns the lowercase complement of a uppercase letter

Function:     toupper(char c)
Parameters:   c - Charter to make uppercase
Returns:      If charter is lowercase it returns its uppercase complement
              otherwise it returns just c
Include File: CTYPE.C
Description:  Returns the uppercase complement of a lowercase letter

6. Future of TI-83/TI-86 Small-C

    - I need more calculators to test code with
          (I CAN'T EMPHISEZE THIS ENOUGH)! If you are intrested in donating
          me a calculator please E-Mail me right away!

    - First I need a good emulator to test code on. Once I crashed my
      TI-86 so bad that the BIOS got corrupted. I ended up replacing the
      calculator.

    - I working on a Visual interface Like Visual Studio for the TI-83/TI-86
      Compiler.  I heard there is a way you can distribute the Studio editor
      only with your software, does any know about this.

    - I messing around with a more sophisticated C compiler. Its
      called LCC.  But I having some trouble with it because of the way it
      works.

    - I hope to add Library support to it.

    - I hope to add DLL type files for it so that if you have more then
      one program on the TI-83/TI-86 made with TI-83/TI-86 small C.  This
      will make the overall Memory requirements less.

    - A compressor for the code.  This is a big one because of how
      little space there is on the calculator.

    - Eventually design the code in such a way so you can write to the
      TI-82,83,85, and TI-86 Calculators.  Not the TI-89 and TI-92 right away
      because it uses a different chip set the the other calculators.

    - Probably in the distant future a debugger for the calculator but
      that will be real hard because I absolutely no idea on how to do this.

    - A ton of more functions like: Using the serial port, etc.

    - A HTML Version of this document

7. What you can do to help me

    - Any fixes and speedups will be appreciated especially on the routines that
      are right now in C. If you could convert these into z80 assembly please
      do.

    - I would like you to add any functions please do!

    - Not all functions in the include library have been tested.

    - If you know how to get .OBJ to merge in tasm please e-mail me.

    - I am sure there are more optimizations that can be done if you know of
      any add them to the INCLUDE\RULES file. For a decription on this file
      read PHO\COPT.1

    - Any Optimizations to 0crt83.asm/0crt86.asm would be appreciated.

    - I cant write documents very well and I need help with this and the
      rest of the documentation if interested in working on the
      documentation e-mail me.

    - I really need a malloc() and free() routines for the TI-83/TI-86

    - Lights out really needs some speedups!

    - Any help you give me will be mentioned in this document if this program
      benefits form that assistance.

8. TI-83 Considerations

    When you want to finally draw the commands you have put to the calculator
with graphics commands (box, line, and pixel) you will need to call the
FastCopy routine.

    You can only run these programs with AShell and SOS Shell.

    You can define the description of the program that AShell and SOS uses
with the #name directive in your program.  This directive can be put anyway in
your code. If it is not given the name defualts to "TI-83C Program". This
dirctives text must be enclosed in ""'s. I.E. The following:

#name "Windows 83"
#name "Baba Boiy"

    The getkey() routine runs differntly on the TI-83 then it does on the
TI-86.  The getkey() routine on the TI-86 waits for the user to press a key
the TI-83 function does not it will return a 0 if no key was pressed at the
time the function was called.

9.  Making functions for C in Z80 Assembly

    By writting functions in Z80 Assembly that can be called by your C program
will allow your programs to be smaller and faster if properlly written.

    There are two things you have to understand if you plan to write C
functions in Z80 Assebly:

    1. Reading the parameterts of the stack and into registers
    2. Returning a value

    1. Reading the parameterts of the stack and into registers

    You do this by reading values from the stack and placing them into
registers.  The parematers are placed in the stack right-to-left each
parameter takes up two bytes.

    Reading a char:

some_func(a) char a; {
#asm
    ld  hl,2            ; 2 is the offest of the last parameter
    add hl,sp           ; Add the stack offest
    ld  b,(hl)          ; Set b=(hl) where (hl) is the value of the item
    ...
    ; Asm function
    ...
#endasm
}

    In this example the value of the parameter 'a' was placed in the register
 'b'.  You can set char values to any 8-bit register.

    Reading non Chars:

some_func(a) char *a; {
#asm
    ld  hl,2        ; 2 is the offset of the last parameter
    add hl,sp       ; Add the stack to offset
    ld  b,(hl)      ; set b to the high byte of the pointer location
    inc hl          ; Next value
    ld  c,(hl)      ; set c to the low byte of the pointer location
    ...
    ; Asm function
    ...
#endasm
}

    You can use this process for all pointers, integer, and all other 2-byte
storage types.

    Reading more then one parameter:

some_func(a, b, c) char a,b,c; {
    ld  hl,2        ; 2 is the offset of the last parameter
    add hl,sp       ; Add the stack to the offset
    ld  d,(hl)      ; set Register d = c

    inc hl          ; Move to next register use one inc for pointer style
    inc hl

    ld  c,(hl)      ; set Register c = b

    inc hl
    inc hl

    ld  b,(hl)      ; set Register b = a
    ...
    ; Asm code
    ...
#endasm
}

    As you can see setting values is fairly striagt forward.

    2. Returning a value

    You return values with the register HL. if you are retring a char you have
to set the Register H to 0 and the register L to the value.  So if you want
to return the register b use somting like the following

some_func() {
#asm
    ...
    ; Asm code
    ...
    ld  l, b
    xor a       ; set a to 0
    ld  h, a    ; set h to 0
#endasm
}

    I hope that this answers all your questions about programming C functions
in Z80 assembly.

10. Notes to all programmers

    It has come to my attion that there are sevral questions about certian things
in moving from a C compiler that you may be used to and this Small-C compiler.

    1. Makeing funtions

    This program does not require a prototype it just assumes that you have
put the right varibles into the funtion. This is one of many things I dont like
to much about the SmallC compiler interface I use.

    You also have to name you functions in the following fashion(NOTE: The
orgnal C docs had you name functions like this):

    somefunc(a, b) int a; char *b; {
    /* Your code */
    }

    As you can see you dont put the varible types inside the brackets but
instead on the outside.

    2. Commenting

    The C++ standard allows you to make single like comments in the following
fashion:

    // Comment

    However, the small-C compiler does not allow for this you will have
to use the other style of comments as follows:

   /* Comment */

   If there are any other issues you feel should be here please E-Mail me.
11. Credits

Lead Programmer, TI-86 Programming, and Z80 general coding:
    Christopher Dannemiller
Assitant Programmer and TI-83 Proramming:
    Jeremy Scoggins

E-Mail Chris Dannemiler at dannemiller@hotmail.com
E-Mail Jeremy Scoggins at  jscoggin@hotmail.com

Homepage:

www.geocities.com/SiliconValley/Vista/1143
www.geocities.com/SiliconValley/Vista/1143/ti86cc.html

Version Number: Beta-5

Augest '99
