Difference between revisions of "Programming cross z80 calculators"

From WikiTI
Jump to: navigation, search
(added prgm asm template)
m (→‎General Advices: formatting)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{stub}}
 
 
== Introduction ==
 
== Introduction ==
 
It is a nice feature to do in your games and other programs to be able to use them across all the z80 calculators.
 
It is a nice feature to do in your games and other programs to be able to use them across all the z80 calculators.
 +
Or this topic will help you in porting some programs to your calculator.
  
−
The difficulty to port depends on every case. In some games, it is enough changes in some graphics, safe rams and b_calls to make it work.
+
The difficulty to port depends on every case. In some games, it is enough changes in some graphics routines, safe ram locations and to bcalls to make it work.
 
Some cases might be a nightmare (in practical too difficult) or simply impossible.
 
Some cases might be a nightmare (in practical too difficult) or simply impossible.
  
−
== General Advices ==
+
== Calculators Series Current Interest ==
−
* Avoid b_calls
+
−
* use a assembler that supports #if #else #endif directives (give a example on how to use)
+
−
* use a linker capable of all z80 calculators format
+
−
* See in Z80 Routines a set of graphic routines to all calculators
+
  
−
== Help Documentation ==
+
Note that the TI-83+ series (TI-83+, TI-83+SE, TI-84+, TI-84+SE) are the most common worldwide. Most development is done to this series. Most times ports were done to this series.
 +
 
 +
The newer Nspire calculators are getting popularity but z80 developers will keep their audience because Nspire (non CAS) has a TI-84+SE emulator and in the future it will probably get released a 3rd party TI-84+SE emulator for Nspire CAS.
 +
 
 +
There are in less number TI-82 and TI-83 (Regular) users. They will rejoice with a build for them. And note TI-83 is the easiest to port from TI-83+ source code.
 +
 
 +
TI-85 and TI-86 are no longer produced, long discontinued, there is few visible development and very few interest on them. TI-86 has TI-85 compatibility, but not sure about ASM.
 +
 
 +
By any means feel unmotivated or constricted by the current interest, there are still old calculator enthusiasts who enjoy new stuff for their legacy calculator. And assembling for more models can be an important feature.
 +
 
 +
== Porting Help ==
 +
 
 +
=== General Advices ===
 +
 
 +
TI-83+ will almost certainly work on TI-83+SE and TI-84+ and SE. The easiest ports you will probably do will be between TI-83 and TI-83+, it is not that hard.
 +
TI-83 OS is similar to what you know on TI-83+, except the bcall.
 +
 
 +
TI-82 is like a somewhat ancient version of TI-83.
 +
For the TI-85 and TI-86, much of the TI-OS changes (especially memory management). The screen resolution is different, so you need to change the graphics accordingly.
 +
 
 +
 
 +
List of things to keep in mind while programming for multiple z80 calculators:
 +
* avoid b_calls (wherever possible)
 +
* use a assembler that supports #if #else #endif directives (give a example on how to use)
 +
* use a linker capable to output all z80 calculators format (notably SPASM)
 +
* See in Z80 Routines a set of graphic routines to all calculators (not right now...) (changes are due TI-85/86 screen resolution is different)
 +
* If you need memory in assembly programs in RAM, place variables in the program
 +
* Avoid self modifying code
  
 
=== Safe Rams ===
 
=== Safe Rams ===
−
Safe ram is simply some portions of fixed ram usable to the programmer without any worry to the TI-OS.
+
Safe ram is simply some portions of fixed ram (re)usable to programmers without any conflict to the TI-OS.
−
But it depends from calculator to calculator.
+
But their location and existence depend from calculator to calculator model. Because of this may be preferable to keep variables inside your program. The obvious disadvantage is your program will take more space.
−
Here is a table to illustrate what is available or not across the z80 calculators:
+
 
−
{{stub}}
+
This table illustrates what safe ram locations are available in the various calculator models.
 +
 
 +
{| class="wikitable" border="1"
 +
|-
 +
!  Safe Ram Name
 +
!  Size
 +
!  TI-82
 +
!  TI-83
 +
!  TI-83+/84+/SE
 +
!  TI-85
 +
!  TI-86
 +
!  Use it?
 +
|-
 +
|  APD_BUF (savesscreen)
 +
|  768
 +
|  Available (with CrASH, after disabling interrupts) ($8228)
 +
|  Available ($8265)
 +
|  Available ($86EC)
 +
|  ???
 +
|  ???
 +
|  ???
 +
|-
 +
|  TEXT_MEM (textshadow)
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  OPs
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  cmdShadow / TEXT_MEM2
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  StatRam
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  imathptrs
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  appBackupScreen
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|-
 +
|  tempSwapArea
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
| 
 +
|}
 +
 
 +
The conclusion is using APD_BUF (savesscreen) because it has a good size, is present in all calculators and doesn't need to be restored after use.
 +
 
 +
=== bcalls, icalls (system calls) ===
 +
 
 +
There are two suggested ways here to solve the bcalls across calculators:
 +
- first, simply do not use bcalls (or just a few)
 +
- use complete include files with bcall macros for each calculator model and #ifdef directives when bcall names differs.
 +
 
 +
The system calls definition changes in different calculator models series:
 +
* TI-82 - icall(xxxx) = call xxxx
 +
* TI-83 - call xxxx
 +
* TI-83+ - bcall(xxxx) = rst 28h \ .dw xxxx
 +
* TI-85/86 - ???
 +
 
 +
=== Shells ===
 +
 
 +
While TI-83+ series run assembly programs without shells (called no-stub) all others require some shell or exploit to run assembly code. So knowing the shells is important for testing on emulator and release to public.
 +
 
 +
TI-73 only shell is Mallard
 +
TI-82, there is ash and CRASH
 +
TI-83, has Ion v1.6, Venus, AShell83 v1.0 and SOS v2.0. (ZShell compatibles?)
 +
TI-83+/84+/SE - Ion and Ion compatible shells (MirageOS, DoorCS, CrunchyOS)
 +
TI-85 AShell and Usgard
 +
TI-86 AShell v1.1, Rascall v0.9, and Yet Another Shell 2.21
 +
 
 +
I suggest Ion for 83 and 83+ series because is popular and has a nice set of routines (mainly for games).
 +
For TI-86 most people do no-stub (no shell, just from the TI-OS).
 +
 
 +
 
 +
=== Assemblers and Linkers ===
 +
 
 +
I strongly suggest SPASM because it outputs all program file types.
 +
For TI-83+ linker there is DEVPAC8X.
 +
 
 +
Use the assembler #ifdef, #ifndef and #endif directives. For example if you want specific code for TI-83:
 +
<nowiki>
 +
#ifdef TI83
 +
;this code will only be assembled when TI83 define is defined.
 +
;so define TI83 to assemble for TI83 and the code inside the #ifdef only gets assembled for TI83
 +
xor a
 +
#endif
 +
</nowiki>
 +
 
 +
Also writing your shell scripts (batch or bash) or using an IDE can help assembling program files for all calculator models.
 +
A example of a batch for SPASM:
 +
<nowiki>
 +
spasm -DTI83 source.asm output.83p
 +
spasm -DTI83P source.asm output.8xp
 +
 
 +
</nowiki>
 +
Just copy the text and save in a name.bat file, this for Windows users. Now to assemble for TI-83 and TI-83+ just double click the batch file and see it assembling. If you want to see assemble errors, edit the name.bat and put "pause" in the last line.
 +
 
 +
If you do not use SPASM, see your assembler manual for information.
 +
 
 +
 
 +
== Calculator Differences Resume/Reference ==
  
−
== Specific calculator info ==
+
Here you have the important aspects of z80 calculators, mostly hardware and OS differences.
  
−
Here you have important aspects of calculators (mostly hardware related).
+
All calculators have a 96x64 pixels screen except TI-85 and TI-86 which have 128x64 pixels.
  
 
=== TI-73 ===
 
=== TI-73 ===
 
* just APPS programming (?)
 
* just APPS programming (?)
 +
 +
=== TI-81 ===
 +
* unfriendly calculator to code (no emulator, code must be typed on the calculator, hard to hack)
 +
* note that few people own one, very few use it and even less hacked it (can be counted by your fingers?)
  
 
=== TI-82 ===
 
=== TI-82 ===
 +
* Needs a shell (to be hacked)
 +
* Lack of documentation (few OS system calls documented, etc.)
 
* No Hooks
 
* No Hooks
  
 
=== TI-85 ===
 
=== TI-85 ===
 
* memory mapped LCD (great but others don't)
 
* memory mapped LCD (great but others don't)
 +
* needs a shell (to be hacked)
 +
* lack of documentation (few OS system calls documented, etc.)
  
 
=== TI-86 ===
 
=== TI-86 ===
 
* memory mapped LCD (great but others don't)
 
* memory mapped LCD (great but others don't)
 +
* assembly execution supported
 +
* some documentation does exist
  
 
=== TI-83 ===
 
=== TI-83 ===
 
* Link port is different from TI-83+
 
* Link port is different from TI-83+
 +
* No Flash Memory for user storage (no APPS and AppsVars and no archived vars)
 +
* there is no bcalls, just normal calls
  
 
=== TI-83+ ===
 
=== TI-83+ ===
−
* (most usual z80 platform)
+
* Most usual z80 platform, compatible with TI-83+SE and TI-84+ calculators
 +
* APPS programming
 +
* Well documented
  
−
=== TI-84+ ===
+
=== TI-83+SE ===
−
* CPU is around 3x faster (good but not always)
+
* CPU is around 3x faster (16 MHz) (good but not always)
−
* Some bad LCD can screw your beautiful graphics
+
* time crystals
 +
* APPS programming
  
 +
=== TI-84+/84+SE ===
 +
* CPU is around 3x faster (16 MHz) (good but not always)
 +
* time crystals
 +
* APPS programming
 +
* Some bad LCD can screw your beautiful graphics, use a [[safefastcopy]] routine
 +
* Newer calculators do not have most of the extra RAM pages
  
−
== Program in RAM template ==
+
=== Emulated TI-84+SE by Nspire ===
 +
* Does not support any undocumented z80 instructions
 +
* USB software is not correctly emulated (USB8X should fail)
 +
* extra RAM pages not emulated (?)
 +
(until a better 3rd party emulator is released, you have to make to mind this)
 +
 
 +
== Useful Tools and Utilities ==
 +
 
 +
=== Various ===
 +
 
 +
* SPASM
 +
* Dwedit's large include file
 +
* this set of most complete include files
 +
* WikiTI routines
 +
 
 +
=== Source Code Template Program in RAM template ===
 +
 
 +
This has probably wrong headers, but is a start for someone.
  
 
  <nowiki>
 
  <nowiki>
 
#ifdef TI73
 
#ifdef TI73
 +
#include ti73.inc
 
;TI73 asm execution normally is on a APPS
 
;TI73 asm execution normally is on a APPS
 
#endif
 
#endif
 +
 
#ifdef TI82
 
#ifdef TI82
 
;#include ti82.inc
 
;#include ti82.inc
 
;depends on shell (?)
 
;depends on shell (?)
 
#endif
 
#endif
 +
 
#ifdef TI83
 
#ifdef TI83
 
#include ti83.inc
 
#include ti83.inc
 
  .org userMem
 
  .org userMem
 
#endif
 
#endif
 +
 
#ifdef TI83P
 
#ifdef TI83P
 
#include ti83plus.inc
 
#include ti83plus.inc
Line 66: Line 272:
 
  .db t2ByteTok,tAsmCmp  ; .db $BB,$6D tokens for ASM program
 
  .db t2ByteTok,tAsmCmp  ; .db $BB,$6D tokens for ASM program
 
#endif
 
#endif
 +
 
#ifdef TI85
 
#ifdef TI85
 
;#include ti85.inc
 
;#include ti85.inc
Line 75: Line 282:
 
  .dw tTitle ;no idea of what this is
 
  .dw tTitle ;no idea of what this is
 
#endif
 
#endif
 +
 
#ifdef TI86
 
#ifdef TI86
 
;#include ti86.inc
 
;#include ti86.inc
Line 84: Line 292:
 
  .dw tTitle
 
  .dw tTitle
 
#endif
 
#endif
 +
  
 
Start:
 
Start:
Line 95: Line 304:
 
End:
 
End:
 
  </nowiki>
 
  </nowiki>
 +
 +
=== Source Code Template APPS template ===
 +
 +
<nowiki>
 +
.org $4000
 +
 +
;Free APPS header
 +
 +
Begin:
 +
 +
 +
 +
Exit:
 +
bjump(_JForceCmdNoChar)
 +
</nowiki>
 +
 +
== Related Topics and sources of info ==
 +
* THE TI-82/83(+) UNIFICATION FAQ by Guillaume Hoffmann
 +
* UTI topic about shells http://www.unitedti.org/forum/index.php?showtopic=3702
 +
* ticalc articles

Latest revision as of 12:58, 20 April 2010

Introduction

It is a nice feature to do in your games and other programs to be able to use them across all the z80 calculators. Or this topic will help you in porting some programs to your calculator.

The difficulty to port depends on every case. In some games, it is enough changes in some graphics routines, safe ram locations and to bcalls to make it work. Some cases might be a nightmare (in practical too difficult) or simply impossible.

Calculators Series Current Interest

Note that the TI-83+ series (TI-83+, TI-83+SE, TI-84+, TI-84+SE) are the most common worldwide. Most development is done to this series. Most times ports were done to this series.

The newer Nspire calculators are getting popularity but z80 developers will keep their audience because Nspire (non CAS) has a TI-84+SE emulator and in the future it will probably get released a 3rd party TI-84+SE emulator for Nspire CAS.

There are in less number TI-82 and TI-83 (Regular) users. They will rejoice with a build for them. And note TI-83 is the easiest to port from TI-83+ source code.

TI-85 and TI-86 are no longer produced, long discontinued, there is few visible development and very few interest on them. TI-86 has TI-85 compatibility, but not sure about ASM.

By any means feel unmotivated or constricted by the current interest, there are still old calculator enthusiasts who enjoy new stuff for their legacy calculator. And assembling for more models can be an important feature.

Porting Help

General Advices

TI-83+ will almost certainly work on TI-83+SE and TI-84+ and SE. The easiest ports you will probably do will be between TI-83 and TI-83+, it is not that hard. TI-83 OS is similar to what you know on TI-83+, except the bcall.

TI-82 is like a somewhat ancient version of TI-83. For the TI-85 and TI-86, much of the TI-OS changes (especially memory management). The screen resolution is different, so you need to change the graphics accordingly.


List of things to keep in mind while programming for multiple z80 calculators:

  • avoid b_calls (wherever possible)
  • use a assembler that supports #if #else #endif directives (give a example on how to use)
  • use a linker capable to output all z80 calculators format (notably SPASM)
  • See in Z80 Routines a set of graphic routines to all calculators (not right now...) (changes are due TI-85/86 screen resolution is different)
  • If you need memory in assembly programs in RAM, place variables in the program
  • Avoid self modifying code

Safe Rams

Safe ram is simply some portions of fixed ram (re)usable to programmers without any conflict to the TI-OS. But their location and existence depend from calculator to calculator model. Because of this may be preferable to keep variables inside your program. The obvious disadvantage is your program will take more space.

This table illustrates what safe ram locations are available in the various calculator models.

Safe Ram Name Size TI-82 TI-83 TI-83+/84+/SE TI-85 TI-86 Use it?
APD_BUF (savesscreen) 768 Available (with CrASH, after disabling interrupts) ($8228) Available ($8265) Available ($86EC)  ???  ???  ???
TEXT_MEM (textshadow)
OPs
cmdShadow / TEXT_MEM2
StatRam
imathptrs
appBackupScreen
tempSwapArea

The conclusion is using APD_BUF (savesscreen) because it has a good size, is present in all calculators and doesn't need to be restored after use.

bcalls, icalls (system calls)

There are two suggested ways here to solve the bcalls across calculators: - first, simply do not use bcalls (or just a few) - use complete include files with bcall macros for each calculator model and #ifdef directives when bcall names differs.

The system calls definition changes in different calculator models series:

  • TI-82 - icall(xxxx) = call xxxx
  • TI-83 - call xxxx
  • TI-83+ - bcall(xxxx) = rst 28h \ .dw xxxx
  • TI-85/86 - ???

Shells

While TI-83+ series run assembly programs without shells (called no-stub) all others require some shell or exploit to run assembly code. So knowing the shells is important for testing on emulator and release to public.

TI-73 only shell is Mallard TI-82, there is ash and CRASH TI-83, has Ion v1.6, Venus, AShell83 v1.0 and SOS v2.0. (ZShell compatibles?) TI-83+/84+/SE - Ion and Ion compatible shells (MirageOS, DoorCS, CrunchyOS) TI-85 AShell and Usgard TI-86 AShell v1.1, Rascall v0.9, and Yet Another Shell 2.21

I suggest Ion for 83 and 83+ series because is popular and has a nice set of routines (mainly for games). For TI-86 most people do no-stub (no shell, just from the TI-OS).


Assemblers and Linkers

I strongly suggest SPASM because it outputs all program file types. For TI-83+ linker there is DEVPAC8X.

Use the assembler #ifdef, #ifndef and #endif directives. For example if you want specific code for TI-83: 

 #ifdef TI83
 ;this code will only be assembled when TI83 define is defined.
 ;so define TI83 to assemble for TI83 and the code inside the #ifdef only gets assembled for TI83
 xor a
 #endif

Also writing your shell scripts (batch or bash) or using an IDE can help assembling program files for all calculator models. A example of a batch for SPASM: 

spasm -DTI83 source.asm output.83p
spasm -DTI83P source.asm output.8xp

Just copy the text and save in a name.bat file, this for Windows users. Now to assemble for TI-83 and TI-83+ just double click the batch file and see it assembling. If you want to see assemble errors, edit the name.bat and put "pause" in the last line.

If you do not use SPASM, see your assembler manual for information.


Calculator Differences Resume/Reference

Here you have the important aspects of z80 calculators, mostly hardware and OS differences.

All calculators have a 96x64 pixels screen except TI-85 and TI-86 which have 128x64 pixels.

TI-73

  • just APPS programming (?)

TI-81

  • unfriendly calculator to code (no emulator, code must be typed on the calculator, hard to hack)
  • note that few people own one, very few use it and even less hacked it (can be counted by your fingers?)

TI-82

  • Needs a shell (to be hacked)
  • Lack of documentation (few OS system calls documented, etc.)
  • No Hooks

TI-85

  • memory mapped LCD (great but others don't)
  • needs a shell (to be hacked)
  • lack of documentation (few OS system calls documented, etc.)

TI-86

  • memory mapped LCD (great but others don't)
  • assembly execution supported
  • some documentation does exist

TI-83

  • Link port is different from TI-83+
  • No Flash Memory for user storage (no APPS and AppsVars and no archived vars)
  • there is no bcalls, just normal calls

TI-83+

  • Most usual z80 platform, compatible with TI-83+SE and TI-84+ calculators
  • APPS programming
  • Well documented

TI-83+SE

  • CPU is around 3x faster (16 MHz) (good but not always)
  • time crystals
  • APPS programming

TI-84+/84+SE

  • CPU is around 3x faster (16 MHz) (good but not always)
  • time crystals
  • APPS programming
  • Some bad LCD can screw your beautiful graphics, use a safefastcopy routine
  • Newer calculators do not have most of the extra RAM pages

Emulated TI-84+SE by Nspire

  • Does not support any undocumented z80 instructions
  • USB software is not correctly emulated (USB8X should fail)
  • extra RAM pages not emulated (?)

(until a better 3rd party emulator is released, you have to make to mind this)

Useful Tools and Utilities

Various

  • SPASM
  • Dwedit's large include file
  • this set of most complete include files
  • WikiTI routines

Source Code Template Program in RAM template

This has probably wrong headers, but is a start for someone. 

#ifdef TI73
#include ti73.inc
;TI73 asm execution normally is on a APPS
#endif

#ifdef TI82
;#include ti82.inc
;depends on shell (?)
#endif

#ifdef TI83
#include ti83.inc
 .org userMem
#endif

#ifdef TI83P
#include	ti83plus.inc
 .org userMem-2
 .db t2ByteTok,tAsmCmp   ; .db $BB,$6D tokens for ASM program
#endif

#ifdef TI85
;#include ti85.inc
.org asm_exec_ram-2
 .db $8E,$28
 nop
 jp lblStart
 .dw 0
 .dw tTitle ;no idea of what this is
#endif

#ifdef TI86
;#include ti86.inc
.org asm_exec_ram-2
 .db $8E,$28 ;no idea of what this is
 nop
 jp lblStart
 .dw 0
 .dw tTitle
#endif


Start:
#ifdef TI83P
	b_call(_RunIndicOff)
	b_call(_GrBufClr)
#endif
	
	
	ret
End:

Source Code Template APPS template

 .org $4000

;Free APPS header

Begin:
	
	
	
Exit:
	bjump(_JForceCmdNoChar)

Related Topics and sources of info

Retrieved from "https://wikiti.brandonw.net/index.php?title=Programming_cross_z80_calculators&oldid=9136"