From ST2975@SIUCVMB.SIU.EDU Sun Jan 17 08:02:38 1993
Received: from ns-mx.uiowa.edu by umaxc.weeg.uiowa.edu (5.61.jnf/920629)
	  on Sun, 17 Jan 93 08:02:36 -0600 id AA01465 with SMTP 
Received: from calvin.sfasu.edu by ns-mx.uiowa.edu (5.64.jnf/920408)
	  on Sun, 17 Jan 93 06:01:22 -0600 id AA15889 with SMTP 
Received: from SIUCVMB.SIU.EDU by calvin.sfasu.EDU with SMTP (5.59/25-eef)
	id AA06728; Sun, 17 Jan 93 05:51:03 CST
Return-Path: <ST2975@SIUCVMB.SIU.EDU>
Message-Id: <9301171151.AA06728@calvin.sfasu.EDU>
Received: from SIUCVMB.SIU.EDU by SIUCVMB.SIU.EDU (IBM VM SMTP V2R1)
   with BSMTP id 6764; Sun, 17 Jan 93 05:51:18 CST
Date: Sun, 17 Jan 93 05:21:20 CST
From: ST2975@SIUCVMB.SIU.EDU
To: hyperc-l@calvin.sfasu.edu
Subject: linking binaries to hyperc programs
Status: R

Hi All,

This seems to be a fairly frequent question so I
thought I'd take the time to answer it...

The following is an explanation of how to access
binary modules from your C program.  It explains
how the parameters are passed and how values if
any are returned.

Alternatively, you can even write an assembly
module that can call a C function.  It's a little
harder, but it can be done.

Let's say you want to set the system time in the
ProDOS global page with a C function in your program.
It can just as easily be done in C with anchored
variables, but let's use an assembly module to do
the actual work because we need the screaming speed.

So the C function would look like:

VOID set_time(hour, minute);

hour and minute being byte values and hour and minute were
prevously defined as 8 and 30 respectively.

minute is first pushed on the C stack, and then hour.  The C engine
location sp points to the bottom of the C stack and that's where
we'd find hour.  The next word value on the stack would be minute.
All parameters are guaranteed to be pushed on the stack as 16 bit
values.  Byte values have the high order byte of the word zeroed.

The assembly module would look like:

     .entry _set_time
_set_time:
ldy #0
     lda sp:,y     ; indirect indexed addressing
     sta 0xbf93     ; location of system hour
     iny
     iny            ; increment to next parameter
     lda sp:,y     ; parameter for minute
     sta 0xbf92     ; location of system minute
     rts            ; return, no value needs returning, all work done.

If you wanted to return a value from the function, you would store
the value in the C engine register r1.

My apologies if the indirect indexed addressing looks funky.  I swear
that those are array brackets around sp.

So, if you have assembly modules that you think would be useful in
calling from a C program you're writing, allow the C function to
pass the parameters the assembly module needs, modify the assembly
module to get the parameters it needs from the C stack, and return
anything to the C function in the r1 register defined in regs65.ah.
It's not too difficult to convert another assembler format to what
HyperC's assembler expects, but that depends on how many lines of
code it is.

Andy W.
st2975@siucvmb.siu.edu