Augmenting the Freeware SDK

This document describes how to perform a "home update" on your Avigo Freeware SDK.

Intro

Since TI will not release information on the Avigo's internals, Freeware SDK developers must rely upon the sleuth work of folks who know Z80 assembly language. Deciphering API entrypoints from assembly is slow and tedious work, and so at this time only a fraction of the system functions have been uncovered. But from time to time new discoveries are made. They are usually announced on the Onelist Avigo mailing list, or published on Hans Pufal's web site. When such an event occurs, you might like to add this new function to your freeware SDK so you can call it using C syntax in your programs. This document intends to explain how.

Instructions

This first example shows how to add the standard C library function strlen to your SDK. strlen returns the length of a string (if you didn't already know that you should probably stop reading this and go read a book on C). Adding strlen is something of a special case because the address of the function is already defined in avsdk\lib\syscall.asm. In that file you will find a line that looks like this: 
strlen	=	0x00f6
That says that the strlen function is located at address 0x00f6. Since it is already there the only files you will need modify are: In the general case you would also have to add the new entrypoint to syscall.asm.

Add the following line to sdk.asm: 

         .globl  _strlen
Just add it amongst the other lines that start with ".globl" near the top of the file.

Next add the following lines somewhere near the middle of the file: 

_strlen:
         call    pop1
         .dw     strlen
For instance you could insert them just before the "_strstr:" line.

Next you need to add the function to avsys.h. Add this line: 

extern short strlen(unsigned char* s1);

Finally remake the library by typing avmake in the avsdk\lib directory. This compiles sdk.asm in to sdk.rel and creates a new crt.rel by appending the new sdk.rel to startup.rel. You can now call strlen from all your C programs that include avsys.h!

Adding other functions

Sure you can add strlen, but what about other functions? It's basically the same deal. When someone discovers a new entrypoint, add its name and address to syscall.asm and then do basically the same thing you did with strlen above. There will be a slight differenct in what you add to sdk.asm depending upon the number of arguments the function takes.
No arguments 
_funcname = funcname
One argument 
_funcname:
	call	pop1
	.dw	funcname
Two or more arguments 
_funcname:
	call	pop2
	.dw	funcname
Always add the ".globl _funcname" line.

So what is all this pop1 and pop2 stuff? Gerard explains as follows:

The Avocet compiler passes the first (16-bit) function argument in HL, and the second (16-bit) function argument in DE. The remaining arguments are stored on the stack. The Freeware c compiler pushes all the arguments on the stack, before calling a function. To accomodate for this, I wrote some 'stub code' to call the system functions. Here is how it works:

system call with no arguments: just call the function directly
system call with one argument: pop the first argument into HL and call the function system call with two or more arguments: pop the first argument into HL, the second one into DE and call the function.

This is what the functions 'pop1' and 'pop2' do.

There seems to be a bit of overhead, but the system call functions are usually slow anyway. The total stubbing code costs about 100 bytes, so no bother here either. I compared assembler listings generated by the Avocet compiler and the freeware compiler. The freeware compiler does a pretty good job (if not better), especially on calling functions and integer math. It generates a bit more code for char datatype operations.

And that's all there is to it.

Alternatives

The alternative to modifying your SDK is to use inline assembly. Thomas Chapman's IRdraw program uses this approach for adding the infra-red communications APIs that were discovered some time after the Freeware SDK 0.91 beta release. Check out his source code to see how that works.

Return to Avigo Agora Main Page

Bill Baxter (Send mail)
Last updated: 15-Oct-1998