Information for Assembly Programmers

The TIOS has a very rich set of built-in functions, but unfortunately they are not yet documented by TI. However, entry points are documented. As nearly 80% of functions which I defined in this library are just TIOS calls (either direct or indirect, depending of whether the compile mode is "Doors" or "nostub"), the documentation of these functions are also the documentation of TIOS calls. This means that this document documents about 600 TIOS calls, so it may be very valuable for assembly programers. When the function is nothing more than simple TIOS call, I give to it the name which is exactly the same as the name used in TI list of TIOS entry points. So you can easily determine which functions are simple TIOS calls.

Of course, function parameters are listed using the C language calling convention, because this is a library for C programing. If you are an assembly programmer, you need to know the following:

Many users ask me for examples, especially about the usage of floating point functions in ASM programs. I expected that everything I wrote is so clear (for anybody who knows C syntax), but it seems that it is not. OK. I will give two examples (the second one deals with floats):

Example 1:

Look at the DrawClipEllipse function from the graph.h header file. It is declared as

void DrawClipEllipse (short x, short y, short a, short b, const ScrRect *clip, short Attr);

If you want to simulate the following call

DrawClipEllipse (100, 50, 30, 20, &(SCR_RECT){{0, 0, 159, 99)}, A_NORMAL);

in the ASM program, you should do the following code (Doors calling convention will be assumed, due to simplicity):

       move.w #1,-(sp)
       pea    clip(pc)
       move.w #20,-(sp)            ; Using move.l #$1E0014,-(sp) you can pack
       move.w #30,-(sp)            ;  these two ASM instructions into one
       move.w #50,-(sp)
       move.w #20,-(sp)
       jsr    tios::DrawClipEllipse
       lea    (sp,14),sp           ; The same as add.l #14,sp but shorter
clip:  dc.b   0,0,159,99           ; Components of SCR_RECT structure are bytes

Example 2:

This example will show to you how to use floats in ASM programs. Look at the functions log, fmul and trunc from the timath.h header file. They are declared as

float log (float x);
float fmul (float x, float y);
long trunc (float x);

Suppose that you want to calculate the integer part of 2.34*log(342.1178). First, you need to know that hexadecimal representations for 2.34 and 342.1178 are $40002340000000000000 and $40023421178000000000 (see bcd if you don't know why). Also, note that bcdmul and bcdlong are original TIOS names for functions aliased as fmul and trunc (don't be misleaded by the fact that the library defines fmul & trunc to work with native float type and bcdmul & bcdlong to work with bcd structures; at the fundamental ASM level they are exactly the same routines). Then, this calculation may be performed using the following ASM program:

       lea    after(pc),a6         ; Prepare a6 for storing results
       clr.l  -(sp)                ; Push 342.1178
       move.l #$34211780,-(sp)
       move.w #$4002,-(sp)
       jsr    tios::log            ; The result is now in "temp"
       move.l (a6,-4),-(sp)        ; Push the result
       move.l (a6,-8),-(sp)
       move.w (a6,-10),-(sp)
       clr.l  -(sp)                ; Push 2.34
       clr.w  -(sp)
       move.l #$40002340,-(sp)
       jsr    tios::bcdmul         ; The result is again in "temp"
       move.l (a6,-4),-(sp)        ; Push the result again
       move.l (a6,-8),-(sp)
       move.w (a6,-10),-(sp)
       jsr    tios::bcdlong        ; The final result is now in d0
       lea    (sp,40),sp           ; Clean up the stack
temp:  ds.b   10                   ; Ten-byte buffer
after: ...

This program may be much more optimized if you know how to use stack frames properly (this technic is so popular in high-level language compilers, but quite unpopular in ASM programs; this example shows that stack frames may be very useful). The optimized version of the same program follows:

       link   a6,#-10              ; Create 10-bytes long space on the stack
       clr.l  -(sp)                ; Push 342.1178
       move.l #$34211780,-(sp)
       move.w #$4002,-(sp)
       jsr    tios::log            ; The result is on the stack frame
       addq.l #6,sp                ; Adjust the stack pointer
       clr.l  (sp)                 ; Push 2.34
       clr.w  -(sp)
       move.l #$40002340,-(sp)
       jsr    tios::bcdmul         ; The result is again on the stack frame
       lea    (sp,10),sp           ; Adjust the stack pointer again
       jsr    tios:bcdlong         ; The final result is now in d0
       unlk   a6                   ; Remove the stack frame

Note: Some of the information about TIOS calls given by TI itself on their site is incomplete or even wrong. This document contains more precise information.

Return to the main index