Firmware documentation
Overview
There are two classes of firmware. The operating system runs (usually)
out of the onboard EEPROM. It handles communication with the host, command
dispatching, timers, interrupts, and memory management. User modules are
uploaded to the board and run out of RAM. They are usually drivers of some
sort for an external hardware board connected to the controller.
The host sends commands to the system over the serial port. For example,
the host may send a command to display a string on the LED display. The
operating system will dispatch this command to the video driver, which will
modify the video buffer appropriately and then return an acknowledge to
the operating system, which will in turn send an acknowledge over the serial
port. User modules are also allowed to send asynchronous messages to the
host, such as when a button is pressed.
Firmware modules are assembled by cokedasm, which is a version of dasm with
many coke-specific modifications. In addition to standard hex output,
cokedasm can also output files in a relocatable module format (necessary
for uploading to the board), as well as C wrapper functions for module
commands and C header files to define symbols. Because all command-specific
C code (for Libcoke) is automatically generated by cokedasm, the system
is extremely easy to modify. Simply change the assembly source, and Libcoke
changes with it! Here are the specifics on using
cokedasm.
You normally interface with the controller using Libcoke. But if you are
debugging a module or the OS, or you otherwise want to communicate directly
with the controller, you use coketerm. Here are the
specifics on using coketerm.
Operating System
The current operating system is CokeOS v3, which is really, really cool.
The operating system consists of two parts, the kernel and the resource
manager, and implements commands for the external host as well as functions
for user code.
- CokeOS Internal Reference -
if you want to write your own user module, this guide explains how to
use CokeOS from within user code. CokeOS source code is provided.
- CokeOS External Reference -
if you are writing a program to run on the host, this guide documents
the commands that are available
- CokeOS Communication Protocol -
if you are writing a daemon, this guide documents
how CokeOS communicates with the host.
User Modules
Here are the modules that we have so far. These links detail the external
commands provided by the modules, for use from the host. If you want to
write a module, try the
CokeOS Internal Reference.
The commands are written as Libcoke c functions. If you want to see the
exact format of the command, click on the assembly file and read the header.
- Doodad - doodad and clock driver
- Gfx - standard mode LED display driver
- Button - Coke button driver
- Money - coin changer driver
- Audio - audio output driver
- Egfx - enhanced mode graphics driver
- Motor - stepper motor driver
- Program - EEPROM reprogrammer module
Use Egfx! It's really cool! Read the
Beginner's Guide to Egfx to learn how it
works.