BASIC Instinct

As I was working on implementing a CoCo API comparable to what Color BASIC provides, I had a couple of realizations.  The first was that while such an API might be superficially familiar to some CoCo programmers, it wouldn't necessarily be a good API for anyone to use.  The other was that an API implementation wasn't actually as interesting as some other aspects of the project!

So for now, I'll leave the remainder of the API library work undone.  I may return to expanding the library later, but for now I want to hit a few more objectives.  In this episode, we will look at interfacing C programs to Color BASIC...

CLEAR Some Space

Once again we come to the problem of where to put a program in the CoCo's memory space.  This is similar to what we faced before, except that now we have to share the available memory with a BASIC program at the same time.  What needs to happen is for BASIC to give us some space to live and for it then to leave us alone.

Color BASIC is ready for us.  The CLEAR command allows us to influence how BASIC allocates memory, including the ability to set a limit on the highest address BASIC will use for its programs.  This allows a BASIC program to make room for us before loading and executing our program.

Corresponding to that, I created options in the startup code to allow the C programmer to specify what CLEAR value is being used.  This causes the C program to be compiled to run in the proper space and to allocate memory appropriately.  More importantly, it provides us an open field in which to run without worrying that we might trample on something important to our BASIC program.

For Argument's Sake

CoCo programs that don't interact with BASIC don't have any way to accept anything like a 'command-line argument', so there has been no need to worry about that until now.  BASIC doesn't offer C programs a command-line either, but there are ways to pass information to our C program if we so desire.  In fact, perusal of the Color BASIC documentation reveals that there are a variety of options for passing information both into and out of C programs.

Lacking a single path to follow, I implemented a variety of options in the startup code.  These correspond to the documented options for Color BASIC to pass information to a 6809 machine language program, and they require certain variations to the 'main' declaration in the C program.  Some of those options require data structures that are foreign to anything resembling standard C, so I also knocked together a header file to describe the various data structures involved.  I posted that header file and some sample prefix files that set options for the startup code, if anyone is interested.

Stacking Things Up

The Color BASIC documentation had another interesting point -- the stack provided by Color BASIC is only good for about 30 bytes of usage.  It wouldn't take many levels of function calls with arguments pushed onto the stack to burn-up that little amount of space!  Not only that, but the Micro-C library's implementation of malloc presumes that the stack is at a higher address than the heap.  The memory provided by the CLEAR command is at a higher address than the Color BASIC stack, so malloc won't work with it.

The answer is simple enough -- allocate a new stack at the top of RAM.  Of course, in order to return to the calling BASIC program the Color BASIC stack pointer has to be saved at program entry and restored at program exit.  A few more simple modifications to the library startup code accomplished this task without incident.

So, now we can produce CoCo programs written in C that either stand alone or which can fully cooperate with programs written in BASIC.  Things are coming together nicely!  There is only a little more than a week left in the Summer 2013 Retrochallenge event.  Do you want to see what comes next?  Then I guess you'll have to stay tuned!