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

Robot Minefield C Port

After typing in the BASIC version of Robot Minefield, then porting it to Assembly, I decided to round things out by doing a C version as well. The C version was the fastest to port. I learned a lot doing the assembly version, and had a blast. The assembly was the most fun, but the most frustrating to write. My assembly foo just isn’t very strong at this point. Thinking in assembly still takes a while, but worse is not knowing all those pesky mnemonics!

Continue reading Robot Minefield C Port

Robot Minefield Day 4

It is now day 4 of my Robot Minefield conversion to assembly. Last night was my first night I dreamed in assembly. I remember working on some problem, and assembly was involved. You know you have your head in the game when you dream about it. So far so good. I have the minefield randomly populating with mines and robots, and randomly placing the human somewhere on the field. Steve Bjork was kind enough to provide a random number generator in assembly, which was very easy to adapt. You can run the human around the minefield, and will die if you touch a mine or a robot. I just started working on the robot movement AI. You can view my initial post.

Continue reading Robot Minefield Day 4

Robot Minefield

Robot Minefield is a BASIC game I typed in from Tim Hartnell’s Giant Book Of Computer Games book. Neat game, and a simple enough game I’m using it as an exercise to write it in assembly. The game is a little like Rogue in that the computer doesn’t move until you do. But what’s most interesting about this game, is that it is a remake of a game called Robots and mines on the Commodore PET, and was one of the games that inspired the arcade shooter Robotron 2084.

Continue reading Robot Minefield

Bouncy Ball NG Announcement

Updates:
November 27, 2017: Announcement
December 6, 2017: Progress report 1
December 31, 2017: Progress report 2 Apple TV
January 17, 2018: Progress report 3 the home stretch!
January 24, 2018: Progress report 4 signing the certs!
January 29, 2018: Progress report 5 Submitted to the app store!

I really had an itch to play Bouncy Ball, the Color Computer game I wrote back in 2016. I also needed to learn SpriteKit for iOS and macOS. So I put the two needs together and created Bouncy Ball NextGen for iPad, iPhone and Mac. Everything from the original is intact, only getting an update to the UI, level flow, and sounds.

When playing it on the Coco, I always thought the game worked really well using a joystick. Now on the iPad, touching the left and right side of the screen to make it scroll is a perfect replacement. It just feels right, especially with the buttery smooth scrolling.

I wanted to keep you in the game longer, and not break the action. So progression from level to level, and death no longer requires user input, and just jumps right back into the game.

You can check out my promo video below.

November 27, 2017

Basic Interpreter With Shared Variables

I expanded the BASIC script interpreter in basicscript-03.zip to include an example of how you can share variables between your program and the script. For example, you can set a counter in your program, pass that value to the script, and have the script update the value, and then use the new value in your program. Note that since the make file is for Qt, I suggest you compile with g++ *.cpp -o basicscript.

The example ConsoleBasic class now shares two variables with the script, in addition to the CLS command we added in the previous post. An integer variable counter and a string in name$ are now read and modified in the sharedvariable.b sample script.

Continue reading Basic Interpreter With Shared Variables

Basic interpreter with custom command

I expanded the BASIC script interpreter in http://8bitcoder.com/downloads/basicscript-02.zip to include an example of how you can extend the interpreter and add your own commands to it. Sorry about the Makefile depending on Qt. I’ll create a generic Makefile next version I release.

I created a ConsoleBasic object, then added the cls command. You can see I add it in the constructor, then in execAddonCommand I check the token that is passed in to figure out what command I should execute, which in this case can only be one command, then clear the screen via ANSI escape codes.

Next example will show how to make your C++ variables available to BASIC.

class ConsoleBasic : public SmallBasic
{
private:
    int m_cls;
public:
    ConsoleBasic(const char* pszFilename)
        : SmallBasic(pszFilename),m_cls(0)
    {
        m_cls = addCommand("cls");
    }

    bool execAddonCommand(const int tok)
    {
        if(tok == m_cls)
            printf("\x1b[2J\x1b[0;0H");
        return true;
    }
};

Basic Interpreter for Embedded scripts

I had a few people interested in my BASIC interpreter that I was using as an embedded script interpreter. I had started using it in my MUD but pulled it out and made a stand alone example. It still needs a little cleanup and i still need to create an example of how to add more commands to it. See basicscript-01.zip. You can run the script with “basicscript hello.b“. hello.b uses a few commands and shows how you can use labels instead of line numbers. Line numbers are supported as well. Don’t be too hard on the code, I wrote it back in 2001!

6809 CPU Emulator project started

CpuEmulator is a CPU emulator project that aims to emulate a CPU (the 6809 to start with), it’s registers, and system memory. It will allow you to monitor registers, flags and memory as you step through code. Having done SharpiEmu for the Sharp PC–1360 Pocket Computer, the concept seems pretty simple. The 6809 has a number of addressing modes, and different opcodes for the same mnemonic. So I’m expecting it to be somewhat more of a challenge.

Initial version will emulate the CPU, memory, and text video mode.

Features

  • Emulate 6809 instructions
  • Emulate 32×16 & 80×24 text modes
  • Emulate the Coco3’s MMU
  • 4K all the way up to 512KB memory options
  • Debugger that steps through code, shows current state of registers, selected memory block, and source code from a listing file.
  • Break points. They are remembered between runs.
  • Memory watcher. When memory at a certain addresses are modified, a breakpoint is triggered so you can see what modified it.

Continue reading 6809 CPU Emulator project started

CxxTest for unit testing C++ programs

I just discovered CxxTest, and just had to mention it. Fantastic unit test framework for C++ programs. To brush up on my C++ coding, I decided to write a simple 6809 CPU emulator, with the goal of being able to plug-in other CPU’s. This project really lends itself to the idea of unit tests. It’s very easy to test each part of the emulator, and check the results after an instruction has run.

After reading @noel_llopis‘s article Exploring the C++ Unit Testing Framework Jungle I figured I would check out CppUnit first, since I had seen it mentioned it was the standard on StackExchange.com, or at least widely used. Not sure how that is possible, given the weak documentation and complicated setup. The docs never once tell you what to include and what to link against. 30 minutes later I decided to move onto CxxTest. Glad I did as CxxTest was very simple, and I had unit tests running within 5 minutes. The true mark of a well setup project. My emulator processed it’s first instruction today, LDX #$1234. And the unit tests were right there to validate the results.