Calling libraries from C

This article explains how to compile and link a C program with an Assembly library, and why you might want to do this in the first place.

Writing game logic in a high level language is easier, quicker, and less error prone then it would be in Assembly. Since most game logic doesn’t really take all that much CPU power, there isn’t much need for the raw speed you get with Assembly. In the case of the Color Computer, C is great high level (or some would say middle level) language to use. It’s fast, very easy to talk directly to the hardware, and is easy to integrate with Assembly.

Writing graphics routines in a high level language would be pretty slow. It is here that Assembly really shines. Squeeze all the speed out of your CPU by using assembly.

The other point I want to mention is that I want to build one set of libraries that can be used by both C and Assembly. Build once, and use many times. This way I can write a game in C using the libraries, or if I wanted to write it completely in Assembly, I can use the same libraries that I know to work.

In this article I will be talking about building a graphics library. However the practice can be used for any project that requires libraries in assembly.

Inline assembly

I just wanted to quickly talk about inline assembly. Inline assembly is a way to embed assembly code in your C program. For example, I used both C and assembly in a function here (C was just setting up variables for the asm section):

void showLevelSection(int offset)
{
    //pdisp is the destination, the double buffer or display
    //plevel contains bytes, each byte being a block type in the level
    //each block is an index into the block colors
    //the block color is then output to the dest buffer
    //we are only blitting a screen full from the level

    byte* pbuffer = doubleBuffer;                 //needed for asm to see a byte* correctly
    byte* plevel = level->data+offset;
    asm
    {
        ldx     plevel
        ldy     pbuffer
        ldb     #BLIT_HEIGHT
        
loop:
        lda     ,x+             read from level
        cmpa    #INVISIBLE      should this be drawn?
        bne     drawfromlevel   not invisible, draw using level data
        lda     #BLACK          replace color with black tile
drawfromlevel:
        sta     ,y+             blit to buffer
        dec     xcount
        bne     loop
        
        leax    49,x            point to next line in level
        lda     #DISP_WIDTH     reset x counter
        sta     xcount
        decb                    height loop counter...
        bne     loop            ...keep going
        bra     done
xcount  fcb     32
done:
    }
}

Inline will work great for specific applications. But two important things to consider:

  1. You can’t use the routines from assembly. Well, that’s not entirely true. You can, if you modularize your code properly.
  2. Your app logic will not be portable.

So we are going to toss out inline for this discussion.

Creating the library

Let’s create a library that will have two functions. One returns a number, the other adds the number with itself and returns the result.

Note that when you define a function in assembly that C calls, you have to put an underscore in front of it, ie: _addNum.

All source is at the end of this article.

Not using library

First, examples of compiling without creating a library.

C calling C functions

Note, I use cnumber.c so we don’t clobber assembly example.

cmoc greet1.c cnumber.c

C calling assembly functions

cmoc greet1.c number.asm

Assembly calling assembly functions

Creates greet2.bin

lwasm -9 -b -f obj -o number.o number.asm 
lwasm -9 -b -f obj -o greet2.o greet2.asm
lwlink -o greet2.bin -b -f decb greet2.o number.o

Compiling and using library

Examples of compiling library code, then compiling and linking with the library.

Create a C library

cmoc -c cnumber.c
lwar -c libcnumber.a cnumber.o

Create an assembly library

lwasm -9 -b -f obj -o number.o number.asm
lwar -c libnumber.a number.o

Link to the library and run

Note I haven’t got the syntax write when linking assembly to a library.

Compile and link to C lib and assembly lib.

cmoc -o greet1c.bin greet1.c -L. -lcnumber
cmoc -o greet1.bin greet1.c -L. -lnumber

Compile assembly calling assembly.

lwasm -9 -b -f obj -o number.o number.asm
lwasm -9 -b -f obj -o greet2.o greet2.asm
lwlink -o greet2.bin -b -f decb greet2.o number.o

Toss bin files onto a disk image.

writecocofile -b casm.dsk greet1.bin
writecocofile -b casm.dsk greet1c.bin
writecocofile -b casm.dsk greet2.bin


Source

greet1.c

#ifndef _COCO_BASIC_
#error This program must be compiled for a CoCo Disk Basic environment.
#endif

#include "coco.h"
#include "stdarg.h"

//external function
int getNum();       //function with no params
int addNum(int a);  //function with a param

int main() {
    int a = getNum();
    int b = addNum(a);
    printf("NUMBER=%d ADDNUM=%d\n",a,b);
    return 0;
}

cnumber.c

int getNum() {
    return 5;
}

int addNum(int n) {
    return n+n;
}

number.asm

_getNum EXPORT
_addNum EXPORT

    SECTION     code
    
_getNum ldd #42
    rts

num equ 2   ; where on the stack the number will be
_addNum ldd num,s
    addd    num,s
    rts

    ENDSECTION

greet2.asm

printm          macro                           ; define the macro
                pshs            d,x,y,u
                ldx             \1
                jsr             print
                puls            u,y,x,b,a
                endm

                org             $5800
_getNum         IMPORT
_addNum         IMPORT 

num             equ             42

                SECTION         code
start           printm          #helloworld

                lbsr            _getNum         ;call _getNum, D will contain the return value
                
                bsr             printnum        ;now to print the value, call routine to print value in D to screen
                lda             #' '            ;space out the output so we can print more test results
                jsr             [cbchrout]      ;print char using stdout hook

                ; call _addNum(42)
                ldd             #num            ;value to pass
                pshs            b,a             ;push value onto stack, which _addNum uses
                lbsr            _addNum         ;make the call
                leas            2,s             ;pop param off the stack, we don't need it anymore

                bsr             printnum        ;now to print the value, call routine to print value in D to screen
                lda             #' '            ;space out the output so we can print more test results
                jsr             [cbchrout]      ;print char using stdout hook
                
                ; call _addNum(temp) where temp is a 'variable' in assembly, pointer to memory
                ldd             temp            ;grab temp value
                pshs            b,a             ;put D on stack
                lbsr            _addNum         ;make the call, D will have return value
                leas            2,s             ;pop params
                bsr             printnum        ;now to print the value, call routine to print value in D to screen
                lda             #' '            ;space out the output so we can print more test results
                jsr             [cbchrout]      ;print char using stdout hook
                
                rts

*******************************************************************************
* Display 2's complement number in D.
* All registers are saved and restored
*******************************************************************************
printnum        pshs            u,y,x,d
                jsr             cbprintnum
                puls            d,x,y,u
                rts
*******************************************************************************
* Display a null terminated string using the stdout hook.
* Modifies A,X. Maybe others in teh CHROUT BASIC routine.
*******************************************************************************
print           lda             ,x+             ;grab a character from string
                beq             doneloop@       ;null at end of string?
                jsr             [cbchrout]      ;print char using stdout hook
                bra             print           ;keep printing
doneloop@       rts                             ;return to caller

cbprintstring   jsr             $b99c
                rts
                                
temp            fdb             255
helloworld      fcc             "HELLO WORLD"
                fcb             13,0

                                
                ENDSECTION

cbchrout        equ             $a002
cbprintnum      equ             $bdcc

                end

Orchestra 90 CC Stereo Music Synthesizer

Radio Shack Catalog Number 26–3143. The Orchestra–90 CC is a stereo 8-bit audio player for the Color Computer. It works by mapping two addresses in the Coco’s address space to two 8-bit DACs. $FF7A is for left, and $FF7B is for the right. This is the first time I have been able to use this cart, never mind program it! So far, it’s pretty easy to program.

Continue reading Orchestra 90 CC Stereo Music Synthesizer

Optimizing an Imaginary Sprite

There was an interesting thread on Facebook this week that was talking about optimization. They took an imaginary sprite routine and optimized the crap out of it. In this article I’m going walk through the various stages of optimization and provide my own analysis of why the changes were made, and why (or if) the optimization was any good.

I’m going to assume you know how, or are familiar with some arcane programming language, and are either somewhat familiar with assembly or enjoy punishing your brain.

You might be surprised with the results of version 5 and 5p. Sometimes less instructions doesn’t always mean faster.

Continue reading Optimizing an Imaginary Sprite

Optimization, inside the mind of a mad man

In this article I talk about optimizing the level rendering routine for my game Bouncy Ball for the Color Computer. With the help of the mad man Simon Jonassen, I was able to take the render routine from 7 fps to 50 fps! I was quite surprised at the results. I made a video at the end of this article, and explain things in detail here. I also list a couple resources you might want to have in your back pocket.

Continue reading Optimization, inside the mind of a mad man

Gomoku BASIC ported to C

I have been thinking about game AI the last couple weeks, and since I’ve been working on a retro themed game for a retro Coco 3, an old book on BASIC games came to mind; Tim Hartnell’s Giant Book Of Computer Games. Tim was a self taught programmer and the author of several successful books on computer programming.

A few nights back I couldn’t sleep, so I decided it would be relaxing to type in a program from Tim’s book. My first choice was Reversi, but there was either an error in the printed source, or I miss-typed something and the program just wouldn’t run. My second choice was Gomoku, which ran the first time I typed RUN. The game has a strong defensive AI, but not much on the offensive side. I’m thinking it would be fun to work on that part of the AI. But that’s for another post.

Continue reading Gomoku BASIC ported to C