In the previous lesson you wrote your first program, and now you will learn some more things about the structure of a program.

Structure | Header files | Program itsself | Assembler Directives

The basic structure of Ash and CrASH programs is slightly different, because of some other definitions in the header files. The inside of the programs is almost identical.

#include "TI82.H"
#include "KEYS.INC"

.ORG START_ADDR
.DB "Title",0

 <Here comes the program>

 RET

 <Here comes the data (sprites, strings, ...)>

.END

 

#include "CRASH82.INC"
.DB "Title",0

 <Here comes the program>

 RET

 <Here comes the data (sprites, strings, ...)>

.END
 

The first lines of the program contain the commands to include the header files. These header files are some files containing a lot of usefull definitions that make programming easier. This files are called includes, which means that they are read by the assembler and are treated as like they were a part of the source file itsself.

The TI82.H file contains definitions needed for Ash, e.g. the START_ADDR constant that is used later in the sourcecode.

The KEYS.INC file contains the key definitions for call GET_KEY and ROM_CALL(KEY_HAND) calls. (Note: ROM_CALL, GET_KEY and KEY_HAND are also definitions defined in ti82.h)

The .org START_ADDR part tells the assembler that the program will be run from that address and that all the addresses of labels are relative to that address. The Ash shell always relocates the program to the START_ADDR address. This address is $9104 as defined in ti82.h

All these first lines (until .org START_ADDR) won't be translated to machine language by the assembler. The first line that will have output in the final .82P file is the title line. The command .db is an assembler directive and tells the assembler to write bytes to the output file. .db means Define Byte.
This way, a titlestring will be placed in the beginning of the program. This is the title that will appear in the Ash menu. The title is a zero terminated string, i.e. that it ends with a zero byte ($00)

This is an example of how an actual program will look like. This example doesn't really do anything, it just jumps and calls

 call Subroutine
 call AnotherSubroutine
 jp AddressToJumpTo
AddressToJumpTo:
 ret

AnotherSubroutine:
 <Subroutine code>
Subroutine:
 <Subroutine code>
 ret
 

AddressToJumpTo, Subroutine and AnotherSubroutine are 3 labels. They can be used for making calls or jumps.

call Subroutine is a call. When this instruction is encountered, a call is made to the label Subroutine and the code there is executed until a ret (return) instruction occurs. After that, the program returns to the place where the call was made. The ret instruction does not necessary has to be in the same subroutine. e.g. : The AnotherSubroutine call also loops through the Subroutine call before returning.

A jump is similar to a call. The only difference is that you can not return to the place where you made the jump.

You can find more information about Labels, Jumps and Calls in lesson 6.

Below is a little list of the most used assembler directives. You can find more in the TASM documentation.

TASM Directives
Directive	Explanation
.DB $AA .BYTE $0A .DB "String",0 .DB 1,3,$50,"A"	Define one or more bytes. Bytes are separated by a comma.
.DW $ABCD .DW $800C,$800D	Define one or more words. Words will be written with the low byte first, so .DW $ABCD is the same as .DB $CD,$AB. These bytes or words will be included directly into the runnable code.
.INCLUDE "file.ext"	Include a file
.ORG $ABCD	Organize from address. This will make your program updated in this way that it will run without any problems when it is loaded from memory address $ABCD.
.DS 10	Define storage (here: 10 bytes) This will reserve some memory locations where you will be able to store your data in
.END	End of program

Previous lesson | Contents | Next lesson