Beginners

Starting with assembly programming can be quite a pain. You need to find yourself an assembler, preferably a nice emulator, and lots of documentation. While this wiki provides you with a lot of documentation, and many websites and teams can provide you with links to good tutorials, people keep asking the community how to get started. I hope this will answer their questions once and for all :)

Emulating

Getting a ROM dump

Getting a ROM dump is the essential first step of running a calculator emulator. Because the calculator operating system is intellectual property of Texas Instruments, it is illegal to distribute ROM images, but you can extract your own ROM image from your own calculator under "Fair use" copyright doctrine.

To download your own ROM image from your calculator to your PC you need some software. Your options are:

• Rom8x
• Uhm... need to find some more ;)

Ticalc.org has an excellent howto page on getting a ROM image. Or, you could do a Google search on something like TI83.rom, and see what comes up.

Of course, if you want to develop an operating system yourself (if you're working on Vera for example) you don't need a ROM image.

Choice of Emulator

The second step is selecting an emulator that suits you:

• Virtual TI - Long time favourite, but mostly because it was the only one
• PindurTI - Very basic emulator with very good hardware emulation and animated screenshotting
• WabbitEmu - The newest breed, with a very nice GUI and a port to Mac, Linux is on the way

There are a few more, but these are the most popular. Virtual TI's emulation is quite poor compared to the others, but the others are still under development. It's usually best to have a few around so that in case you run into something unexpected you can get a second opinion from another emulator.

Please read the respective README's on how to get your ROM image running in these emulators.

Assembler

An assembler -- sometimes referred to as "compiler", though formally it is no such thing -- can assemble your source code into binaries for the Z80 processor that runs our calculators.

Choice of assembler

Once again, you'll have to make a choice. A few years ago, things were simple; there was TASM and nothing else, so you'd use TASM. These days we have TASM, Brass and Spasm (and probably a few others), all with subtle little differences and improvements, but the latter two are clearly superior to the old TASM. Brass is written in C# for .NET, and can run under Linux using Mono. Spasm was written in C, and will compile on most systems with the GNU toolchain.

• Brass subforum, website and latest download
• Spasm subforum and latest download

Assembling source to binaries

The syntax for assembling input.asm to either output.8xp or output.83p is:

Brass.exe input.asm output.8?p

or

spasm input.asm output.8?p

Both modern assemblers can output files in TI calculator specific formats, which TASM can not. Some versions of Spasm will do this automatically based on the output file extension, and in the case of Brass you can specify your output format in your source code:

.binarymode TI8X

Include files

Include files contain predefined memory locations, locations of TI-OS calls and macros to make your life easier. Strictly speaking you don't need any, but without them you'll have to type in every address by hand (and either memorize them or look them up each time).

Depending on which calculator model and which shell you want to develop for (Ion, MirageOS, Venus, etc.), you'll need to get some include files. For the sake of demonstration (and because most other shells can run them) we'll be choosing Ion for now. Developing for Ion also has the advantage that your applications can be compiled for TI-83 and TI-83+ (and relatives) without changing the source. Go here and download the zip file, which contains ion.inc. You'll also need the shell itself for testing.

Hello World

Save this file as hello.asm in the same directory as your assembler, for ease of testing:

#define TI83P   ; If you want to compile for TI-83+ family calcs
;#define TI83   ; If you want to compile for TI-83, don't uncomment both!

#include "ion.inc"

; ====
; Start of Ion header

#ifdef TI83P
    .binarymode TI8X   ; only required if you use Brass
    .org progstart-2
    .db $BB,$6D
#else
    .binarymode TI83   ; only required if you use Brass
    .org progstart
#endif
    ret
    jr nc,main
title:
   .db "Hello World Test",0

; End of Ion header
; ====

main:
    ; Program execution starts here:
    bcall(_homeup)
    ld hl,string
    bcall(_puts)
    bcall(_getkey)
    ret

string:
    .db "Hello world!",0

Open a console, cd to your directory and issue:

<your assembler> hello.asm hello.8xp

Now load hello.8xp into your emulator and try to run it with Ion.