z80:z80 Basics

There are existing tutorials that can explain this plenty well, so here is a link to some of them:

• Sigma's Learn Assembly in 28 days, day2.
• Iambian's Some (z80) Assembly Required Intro to z80 ASM.

The Bare Bones

Here's the basic template for creating asm programs.

   #include "ti83plus.inc"
   .org $9D93
   .db $BB,$6D ; AsmPrgm
   .define bcall(label) rst $28 \ .dw label
   
   start:
   ; your code goes here

What does each line do? The first line includes the standard definitions for the ti-83 plus, including ROM calls, scan key codes, ram block locations, etc. If you look inside this file, you'll see a lot of .define followed by definitions. These act similarly to the find/replace function on your computer.

The .org $9D93 tells the compiler where to start counting memory addresses from. There is a reason why the compiler starts counting from such an arbitrary number, but for now don't worry about it. It's another one of those things thats required for assembly programs to function properly.

The next line, the .db $BB,$6D inserts the "AsmPrgm" token as the first line of actual code into your program. You can find this token by going into your program catalog and scrolling down to the item that says "AsmPrgm". It basically tells the OS to not allow this program to run unless it is called like an assembly program (using the Asm( command). You can test this by trying to run assembly programs without this command, and it will give a syntax error.

The next line, .define bcall(label) rst $28 \ .dw label, defines a way for us to use ROM calls. It's apart of a quirk when working with the TI's flash ROM and OS implementation, and for the most part, all you need to know is that to call ROM calls, use bcall(label), where you replace label with whatever it is you're trying to call.

   ; calls the _PutS ROM call
   bcall(_PutS)

Special Note:

In the code that is used on this website, I have defined the macro as bcall(). It is also commonly defined as b_call() (note that most z80 compilers are not case sensitive). It doesn't matter which one you use SO LONG AS YOU CONSISTENTLY USE THE ONE YOU DEFINE. Or, alternatively define both:

.define bcall(label) rst $28 \.dw label
.define b_call(label) rst $28 \.dw label

Another possible problem is that bcall has already been defined in ti83plus.inc. Depending on the compiler you have, you will get one of a few different results: the compiler will complain about a re-definition or something similar, or the compiler will change the definition when it reaches the new definition, or it will use the first one encountered. ex.

start:
    ld hl, txtHello
.define text bcall(_PutS)
    text
    bcall(_GetKey)
.define text bcall(_ClrLCDFull)
    ld hl, txtHello
    text
    bcall(_GetKey)
    ret
txtHello:
    .db "Hello",0

On some compilers this code will not compile, on others, it will display Hello, wait for a keypress, clear the screen, wait for another keypress, and quit, and on others still it will display Hello, wait for a keypress, display Hello again, wait for a keypress, and then quit.

Hello World

Let's test out a simple program. If you've ever programmed, you've probably heard of the "Hello World" program. It's a program that displays "Hello World" to the screen and quits. It demonstrates the basic workings of that language's syntax. So, here's the code.

#include "ti83plus.inc"
.org $9D93
.db $BB,$6D ; AsmPrgm
.define bcall(label) rst $28 \ .dw label
   
start:
    ld hl,txtHello
    bcall(_PutS)
    ret
txtHello:
   .db "Hello World"

Conclusion

As you can see, z80 is a slightly complicated language to understand at first. Even the simple Hello World program can seem cryptic. However, as you continue to write code in z80, it will become more familiar, and you'll get better. To expand your knowledge, read the other tutorials in the basic and then the advanced section.