The Assembly Programming Language

This article is under construction and needs to be completed. You can help by expanding it.

Besides TI-Basic, assembly is the other primary programming language available for the TI-83 series calculators. Unlike TI-Basic, which uses commands and functions that are easy to understand, assembly is programmed in the calculator's own machine language. Thus, it is much harder to program in and read.

This lack of usability, however, is more than made up for when you consider the fact that assembly is much faster and more feature rich than TI-Basic. Games that normally can't be done (or, if they can be done, they aren't done very well) in TI-Basic are just considered average in assembly.

At the same time, there aren't as many assembly programmers compared to TI-Basic programmers.

(For more on assembly, visit z80 Heaven and WikiTI.)

The Introduction of Assembly

The TI community developed the first assembly shell, ZShell, for the TI-85 in mid 1994. Although the TI graphing calculators provided built-in programming support in the form of TI-Basic, the language was rather restricted in its capabilities and speed, thus limiting the quality of programs. Subsequently, programmers wanted to use assembly, as it provided low-level access to the calculator and its hardware, and allowed the creation of much more powerful and feature-rich programs.

zshell.gif

There were several programmers — Dan Eble, David Boozer, Magnus Hagander, Rob Taylor, Mel Tsai, to name a few — working together to figure out the ROM code and internal structure of the memory, and it was through the documenting process that they stumbled upon the custom menu pointer loophole that was used to allow execution of assembly language. Although this was a rather arduous and lengthy process, it was hastened by the TI community working together in cooperation and sharing information and resources on the Calc-TI mailing list.

fargo.gif

The TI community was forced to come up with an alternate method of executing assembly on the TI-92, as the calculator used a different processor chip (the Motorola 68000) and Texas Instruments patched the loophole used on the TI-85. The method that Dan Eble and David Ellsworth came up with, and that was used by the first assembly shell Fargo, also used a memory backup like ZShell.

After they discovered that sending an oversized memory backup to the calculator would cause the excess information to overflow into other areas of memory, they deduced the correct amount of overflowing and placed pointers at the specific locations to execute assembly. Assembly language support was achieved for the TI-82 in Summer of 1997 with the release of OShell-82 (OS-82) by Jason Todd. Just like with the TI-85, the TI-82 uses a buffer table that points to the next routine that will be called when a key is pressed. The pointer is intercepted by way of a dummy variable, which instead points to a location in RAM where assembly code is stored.

os-82.gif

Texas Instruments eventually caught on to the fact that the TI community interest in assembly programming was not going away, and they decided to provide built-in support for assembly programming. The first graphing calculator to receive native assembly support was the TI-83 released in August 1996, and it was made possible using hexadecimal code (i.e., hexcode) and executing the programs using the Send(9prgmNAME) format. TI also provided assembly programming documentation on their website, detailing the underlying ROM code and internal structures of the TI-83.

Some of the Texas Instruments programmers responsible for writing the TI-83 ROM code would also regularly provide assembly help and assistance on the Calc-TI mailing list. In addition, Pat Milheron also wrote two useful assembly programs, Zasmload and Squish, that squished the assembly hexcode to make the programs smaller. TI later provided actual built-in assembly commands — Asm(, AsmComp(, and AsmPrgm — with the release of the TI-86 in June 1997, and which subsequent graphing calculators also received, until the release of the TI-Nspire in 2007.

Rather ironically, although the TI-81 was the first TI graphing calculator to be released, programming and development for it was quite limited as it lacked the linkport needed to send and receive programs. It was not until almost twenty years later in 2010 that it was eventually hacked by Randy Compton to allow for assembly programming via a custom interrupt routine.

Assembly Calculator Hacks

From the release of the first TI graphing calculator in 1990 (the TI-81), the TI community has battled Texas Instruments in trying to hack the TI graphing calculators to allow for features and functionality that TI never meant them to have. The release of the first three graphing calculators — TI-81, TI-85, and TI-82 — did not provide access to the built-in assembly language and ROM code that powered the calculators, so the TI community had to figure out the underlying code and internal structures of the calculator on their own. Although this was a rather arduous and lengthy process, it was hastened by the TI community working together in cooperation and sharing information and resources on the Calc-TI mailing list.

Rather ironically, although the TI-81 was the first TI graphing calculator to be released, programming and development for it was quite limited as it lacked the linkport needed to send and receive programs. It was not until twenty years later in 2010 that it was eventually hacked to allow for assembly programming. The TI-85 was actually the first TI graphing calculator to be hacked by the TI community to allow for assembly programming by exploiting a flaw in the custom menu, and the TI-82 followed suit using a similar memory hack.

TI eventually caught on to the fact that the TI community enthusiasm and exuberance for assembly programming was not going away, and they decided to provide built-in support for assembly programming on the TI graphing calculators. The first calculator to receive native assembly programming was the TI-83 released in 1998, and it was made possible using three assembly commands; a person needed to compile hexadecimal code using AsmComp( and then use Asm(9ProgName) to execute the program. TI also provided programming documentation on their website, detailing the underlying code and internal structures of the TI-83.

One of the problems that the TI community has had to deal with is when TI updates the ROM code for a graphing calculator. As all of the assembly programs are written using the specific ROM calls and memory addresses, when those things change the programs cease working. The assembly programs then need to be updated to use the new ROM calls and memory addresses, but this is only possible if the accompanying sourcecode for the programs is included; unfortunately, there are many programs that don't have the sourcecode, and thus the programs become obsolete as they no longer work on the calculator.

ZShell History

zshell.gif

Programmability has always been a great strength of Texas Instruments Graphics Calculators. In the original TI-81 and all models following this programmability has manifested itself in the form of TI-BASIC. TI-BASIC benefits from relative ease-of-use and power, however, it is very slow. Quickly, programmers wanted to use Assembly language on their calculator, because it would allow them to create much quicker programs. Unfortunately, TI had designed its calculators originally not to allow this. This didn't deter the developers of ZShell.

The first release of ZShell was in 1994. It was a lot simpler than most shells that are in use today, but the important part was that it worked. It was a marvelous hack that was used to make it. Many people who had played with the TI-85, realized that it had a custom menu. Upon further examination, they discovered that the custom menu stored pointers for the items that you put on it. These pointers were generally to ROM routines, but they could be edited to point to a piece of memory where ZShell was located. Once the processor control came into ZShell's control any other program could be run. The early versions of ZShell were written by Dan Eble.

The last version of ZShell to be produced was written mainly by Magnus Hagander. It was version 4.0. It is still a popular shell for the TI-85, and it enjoys stability and basic functionality. Today, the TI-85 and ZShell are all but forgotten, but it is this humble start that led to all the Assembly developments we enjoy today.

Fargo History

fargo.gif

With the TI-92's release, there was a lot of excitement. Not only was the TI-92 going to have symbolic algebra capabilities, but it was also using the 68000 chip, an assembly programmer's dream chip. Interest in programming on it was great. Unfortunately, TI wasn't going to make it as easy as before to create programs in assembly. This did not deter Dan Eble and David Ellsworth.

The problems they faced creating an assembler shell for the TI-92 were great. First of all, it was a whole new chip, so the old ideas were pretty much out the window. Additionally, TI fixed the loophole they left with the TI-92, and now the Custom menu was used parsed symbols opposed to hard coded pointers. This meant that the old trick couldn't work anymore. Fortunately, ingenuity prevailed.

The method finally decided for the TI-92 was to take a backup of the TI-92. Then you add a little bit more onto the backup so that it was slightly too big. When you sent it back to the calculator, the memory overflowed and the remaining part got put at the beginning. By no coincidence, at the beginning memory is what is known as the interrupt vector. This is a table that contains all the pointers to what you call interrupts, things that interrupt the CPU to do other things. One example of an interrupt is the keyboard handler. This extra code at the end of the backup rewrote the vector table to include Fargo locations.

Fargo was released slightly early. Its first release was an unofficial beta that was "leaked." David Ellsworth continued to develop Fargo. The newest version is known as Fargo II. Fargo marked a remarkable "hack." Despite the nature, it was very cleanly implemented. It contained libraries. It will definitely be remembered as a great achievement of the TI world.

TI-89 Assembly

zshell.gif

TI released the 89 in August 1998. It was snatched up by many students taking precalculus and calculus, and it was hailed as a great alternative to the large, unwieldy TI-92 Plus. It was also touted as lacking a QWERTY keyboard, so it could be used on standardized tests. The 89 also had an interesting new feature - FLASH upgrade-ability. FLASH could be used to upgrade the ROM version or to add new programs to the 89's wide range of abilities. Since then, two new ROM versions - 1.05 and 2.03 - have been released by TI. Both of these have caused much unrest in assembly coders because their games were rendered incompatible. Fortunately, a patching utility has been written for AMS v1.05 that fixes most problems in that ROM version. 2.03, being a very new ROM version, has had lackluster support at press time. Also of note was the new hardware version that TI released for the 89, called Hardware v2.00. This caused major problems with grayscale games. Scott Noveck of ACZ and Niklas Brunlid have released patching utilities that help to fix this, but a great deal of flickering still results. Several programmers are working to fix the bugs inflicted in their games by the new ROM and hardware versions. The Doors team has released DoorsOS II, a shell designed to work on AMS v2.03. Many new developments are being released, so stay tuned!

Assembly Language Programming

When the TI-85 was released, a loophole was found that made it possible to run machine code on the calculator's 6 MHz Z80 processor, bypassing the usual interface. Such programs were smaller, faster, and more graphical than TI-BASIC programs could ever hope to be, and assembly language programs became very popular. After the TI-92 became available, another loophole was found, allowing even more powerful programs on its 68000 processor. Finally recognizing customer demand for assembly support, TI built assembly ability into its recent TI-83 and TI-86 calculators. However, the TI-82 was still left in the dust until recently, when yet another loophole was discovered. It is now possible to program in assembly on any TI graphing calculator with linking capabilities.

As mentioned, the TI-83 and TI-86 feature documented assembly language ability. However, in TI's earlier calculators, such functionality was obtained "the hard way." Following is a chronological history of how these discoveries were made on the various calculators.

TI-85 (ZShell, Usgard, Rigel, PhatOS): An analysis of memory backups sent to a computer showed that items in the CUSTOM menu were represented in the backup as pointers to memory locations. Assembly code was stored in a string variable and sent to the calculator in a fixed position - the first variable sent after a memory erasure - and its memory address was found after another backup to the computer. This address was placed in a CUSTOM menu entry field in the backup file, the file was sent back to the calculator, and when the CUSTOM entry was selected, it executed the new assembly code.

TI-92 (Fargo): It was discovered that sending a memory backup from the computer to the calculator with excess information would cause an overflow into other areas of memory. The correct amount of overflowing data was deduced, and placed in such a position that it would overwrite the 68000's vector table, which points to routines that the processor calls to handle certain events. These routine pointers were modified to point to machine code in RAM. (Note: this explanation is included solely for historical purposes. A better method was discovered later; it does not require an oversized backup file.)

TI-82 (Ash, CrASH, OS-82): The TI-82 was a mystery for a long time. People passed the idea of assembly language support off as a joke, saying it was impossible. Finally, in the middle of 1997, a shell was produced. This first shell was called OShell-82 (later renamed to OS-82), and it was followed shortly by Ash. These both use a similar approach. The TI-82 uses a buffer (as does the TI-85) that points to the next routine that needs to be called when a key is pressed. When the pointer is changed and a key is pressed we can execute assembly. A dummy variable is used that points to a location in RAM where assembly code is stored.

TI-83 ASM

ion.gif

Shells include Ashell83, SOS, Ion, and ZeS. Ion is the most commonly used TI-83 shell.

TI-83 Flash family ASM

mirageos.gif

The 83 Flash family won't run 83 assembly programs. The 83 Plus Silver Edition is generally compatible with 83 Plus assembly programs, although speed issues often cause separate versions to be produced. Presumably whatever works on the 83 Plus Silver Edition will be okay on the 84 Plus and 84 Plus Silver Edition, but it's too early to say for sure. The first shell out for the 83 Plus was Ion, which has a version for both the 83 and 83 Plus. Programs written for Ion require it to run. Other shells include Ice, Inferno, Izzard, CrunchyOS, GlobalOS, Doorways Pro, Plasma, PSE, and NimbusOS. Most if not all of them are Ion-compatible. MirageOS is a Flash application shell, it is also Ion-compatible. Ion seems to be the de facto standard for TI-83 Flash family assembly, the only attempt at an alternative that I am aware of is TSE. MirageOS is the most commonly used TI-83 Flash family shell. There's a nice comparison of several shells here. To run assembly programs that do not require a shell (if there are any) from the home screen, use the following syntax: Asm(NAME .

TI-86 ASM

rascall.gif

The TI-86 has the distinction of being the only calculator for which assembly programs are regularly written based around the calculator's native assembly functions and not any specific shell. Shells for the 86 are there mostly to provide program menus and other assorted goodies. Shells include ASE, Anaconda, Rascall, Byronic Shell, Mini-Shell, Micro Shell, Omega Shell, Iridus, YAS, Zap-2000, and Ion86 (Ion emulation). Shells from the 85 won't run on the 86, but a few of the 86 shell do provide ZShell emulation for running 85 assembly programs on the 86.. To run assembly programs from the home screen, use the following syntax: Asm(NAME . The Asm( command is found only in the catalog, but it can be placed in the custom menu for quick access.

TI-89 Flash family ASM

The 89 Flash family contains built in assembly abilities like the 83 and 86, however programming using shells and/or kernels remains popular, and they must be used for many assembly programs. Available shells and kernels for the 89/92+/V200 include Doors OS, TEOS, VisualOS, Prosit, PreOS, ProShell, Universal OS, and LexOS. (The shells provide a menu list of available programs, but you can also run them from the command line like Basic program as long as the kernel is installed.) These shells often make use of external library files that are required to run certain games. DoorsOS was once the most popular, but it has fallen into disuse. Universal OS and PreOS are the most commonly used kernels for the 89/92+/V200.

The TI-89 Titanium, as with most new models, sent programmers scrambling to update the kernels. Iceberg can be used in concert with the HW3 patch and older 89 Flash family programs that have been patched using GhostBuster. The latest version of PreOS also supports the 89Ti. As to which is better to use, it's all still so new that opinions have yet to emerge.

Note that the shells and programs written for the 89 Flash family are made for specific ROM (AMS) versions. If you Flash upgrade beyond the version the shell was designed under, it will probably not function. If you have already done this, you can e-mail TI for the old ROM (provided your e-mail provider can accept file attachments that large). Also note that if your calculator came with AMS 1.05 or higher, that means you have Hardware Version 2.00 and cannot downgrade to AMS version 1.00. Of course at this point, if the shell you have won't work with at least AMS 2.05, it's so outdated you probably shouldn't be using it anyway.

There is also the issue of the hardware version. Program size limits imposed by TI in Hardware Version 2 and various other complicated things that the programmers don't like having to deal with are defeated by applying a patch file to the AMS. Part of what the patch does is to make the AMS allow TSR hooks for the purpose of enabling memory resident programs and a few other things which are not allowed by the OS by default. The HW2 patch can be found at ticalc.org. The HW2 patch is not needed when using the PreOS kernel. There's also a HW3 patch for the TI-89 Titanium (it works in place of the HW2 patch on the earlier calculators as well). If the appropriate patch or kernel is not installed, the size limit manifests itself as the error message "Error: ASAP or Exec string too long".

Assembly programs termed nostub tend to work across a wider variety of AMS versions as they are, and they generally do not require a shell or kernel at all unless it is to avoid the size limit. Many 89 Flash family owners only use assembly programs that are nostub, and their popularity has increased while the disadvantages and difficulties of using shells have remained. The TI Chess Team has developed a nostub Start Utility that is intended to defeat the size limit for nostub programs without using a shell or the HW2 patch. KerNO is another program for nostub users, it provides features that kernels do while remaining nostub.

TI-82 ASM

ash.gif

Ash, CrASH, and OS-82 are 82 ASM shells.

TI-85 ASM

usgard.gif

There are several 85 assembly shells out there, ZShell is the most widespread as it was the first one. However, all subsequent 85 ASM shells have retained ZShell compatibility. ZShell was developed by hackers and likely is the reason it occurred to TI to build ASM capability into the calculators starting with the 83. TI does not support or acknowledge the existence of ZShell or other hacker made programs. It works because the hackers messed with an 85 computer backup and stuck a command in the custom menu pointing to a place in memory that gave them access to the Z-80 processor functions. ZShell and the other TI-85 shells can only be installed by backup from a computer or another 85 because the command can't be put in the custom menu from the calculator. If the command is erased from the menu, the ZShell backup must be reloaded. Other 85 ASM shells include Usgard (probably the most popular after ZShell), SuperNova, Rigel, PhatOS, CShell-NT, Menu Independent SHell, OS/7, OS-85, and Summit.

TI-92 ASM

Only one shell was ever made for the original TI-92, Fargo. Fargo II updated the original Fargo, though a program module is available that allows Fargo II to run programs written for the original Fargo. Be sure to read the fargo.txt file that comes with the Fargo program files for instructions on installing Fargo to your TI-92. A TI-92 with the Plus Module will use its own ASM capability, without need for Fargo.

Fargo and Fargo II utilize add-on files called libraries which contain common routines for use by programs. Most programs require a specific set of library files to run. This is done to save space (instead of each program having a copy of a routine, they share a single copy), however it has been known to cause confusion.

Interestingly enough, years after the original 92 has faded from most people's memory, it seems the TIGCC folks are experimenting with allowing one to make Fargo programs using TIGCC.

Sources

  • Ticalc.org Assembly page
  • TechniCalc TIFAQ — http://technicalc.org/tifaq/
  • The TI-89 Flash family section of Patrick Davidson's FAQ