-
Notifications
You must be signed in to change notification settings - Fork 16
/
asminfo.html
131 lines (130 loc) · 8.5 KB
/
asminfo.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Information for Assembly Programmers</TITLE>
<STYLE TYPE="TEXT/CSS">
<!--
.IE3-DUMMY { CONT-SIZE: 100%; }
BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.CODE { FONT-FAMILY: Courier New; }
-->
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#E0E0E0">
<FONT SIZE="5"><B>Information for Assembly Programmers</B></FONT>
<HR>
<P>TI's OS for TI-68k calculators, AMS, has a rich set of built-in functions, but unfortunately many
of them are not yet documented by TI. However, some entry points are documented. As many functions
which I defined in this library are just OS calls, the documentation of these functions is also
the documentation of OS calls.
This means that this document documents more than 600 OS calls, so it may be very valuable
for assembly programers. When the function is nothing more than simple OS call, I give to it
either the name used in TI's list of OS entry points, or a name invented by someone. So you can
easily determine which functions are simple OS calls.
<BR><BR>
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:</P>
<UL>
<LI><P>Parameters are pushed onto the stack in reverse order.</P></LI>
<LI><P>"short" types occupy two bytes, and "long" types occupy four bytes. "int" types usually occupy two bytes, except if the user specifies the <B>'-mlong'</B> compiler switch; in such case "int" occupies four bytes.
All pointer types occupy four bytes. A float type occupies ten bytes.</P></LI>
<LI><P>Although the "char" type occupies just one byte, it must be promoted to a word before pushing it on the stack.</P></LI>
<LI><P>To clean up after the function has been called, pop all the values that were pushed. This can be done by adding a value to SP; this value is calculated by summing the sizes of all the parameters that were pushed.</P></LI>
<LI><P>Assume that D0-D2/A0-A1 are destroyed by any given ROM function upon return.</P></LI>
<LI><P>Any function which returns any non-pointer type (char, short, int, long), including not-too-long structures (like <A HREF="vat.html#HSym">HSym</A>), keeps the result in the register D0.</P></LI>
<LI><P>Any function which returns a pointer type keeps the result in the register A0.</P></LI>
<LI><P>All OS functions which return a floating point value (like most functions from <A HREF="timath.html">timath.h</A> header file) expect that before calling A6 points to the byte after the end byte of 10-byte long buffer where the result will be stored (usually this is a preallocated space on the stack frame). Note that this is not the same as GCC convention for returning floating point values: GCC returns floats in a triplet [D0.l;D1.l;D2.w]. That's why implementing floating point routines was not so easy, especially because A6 is a very important register (used in GCC as the frame pointer).</P></LI>
</UL>
<P>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):
<BR><BR>
<B>Example 1:</B>
<BR><BR>
Look at the <A HREF="graph.html#DrawClipEllipse">DrawClipEllipse</A> function from the <A HREF="graph.html">graph.h</A>
header file. It is declared as
<BR><BR><B>
void DrawClipEllipse (short x, short y, short a, short b, const <A HREF="graph.html#ScrRect">ScrRect</A> *clip, short Attr);
</B><BR><BR>
If you want to simulate the following call</P>
<PRE>DrawClipEllipse (100, 50, 30, 20, &(SCR_RECT){{0, 0, 159, 99)}, A_NORMAL);
</PRE>
<P>in the ASM program, you should do the following code (kernel calling convention will be
assumed, due to simplicity):</P>
<PRE> 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
</PRE>
<P>
<B>Example 2:</B>
<BR><BR>
This example will show to you how to use floats in ASM programs. Look at the functions
<A HREF="timath.html#log">log</A>, <A HREF="timath.html#fmul">fmul</A> and
<A HREF="timath.html#trunc">trunc</A> from the <A HREF="timath.html">timath.h</A> header
file. They are declared as
<BR><BR><B>
float log (float x);<BR>
float fmul (float x, float y);<BR>
long trunc (float x);
</B><BR><BR>
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 <A HREF="timath.html#bcd">bcd</A> if you don't know
why). Also, note that <A HREF="timath.html#bcdmul">bcdmul</A> and
<A HREF="timath.html#bcdlong">bcdlong</A> are original OS names for functions aliased as <A HREF="timath.html#fmul">fmul</A> and <A HREF="timath.html#trunc">trunc</A> (don't be misleaded by the fact that the library defines <A HREF="timath.html#fmul">fmul</A> & <A HREF="timath.html#trunc">trunc</A> to work with native <CODE>float</CODE> type and <A HREF="timath.html#bcdmul">bcdmul</A> & <A HREF="timath.html#bcdlong">bcdlong</A> to work with <A HREF="timath.html#bcd">bcd</A> structures; at the fundamental ASM level they are exactly the same routines). Then, this calculation may be performed using the following ASM program:</P>
<PRE> 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: ...
</PRE>
<P>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:</P>
<PRE> 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
</PRE>
<P><B>Note:</B> Some of the information about OS calls given by TI itself on their site is incomplete or even <B>wrong</B>. This document contains more precise information.</P>
<HR>
<H3><A HREF="index.html">Return to the main index</A></H3>
</BODY>
</HTML>