CokeOS v3 external commands

All commands that are not "special" are given as Libcoke c functions. For the exact syntax of the command, look at the header of the source files.

Kernel commands:

cokerr Coke_QueryVersion(char* versionstring)
returns the version string ("Coke vx.xx")

cokerr Coke_Reset()
forces the controller board to reset.
(on the firmware level, the command consists of CMD_Coke_Reset followed by five RESETCHAR characters and a zero byte. No acknowledge is sent; COKE_RESET will be received instead.)

cokerr Coke_ScriptResource(byte rezID)
executes a command script stored as a resource. There is no need for STARTCMD characters -- just command characters and their parameters. The script must end with a zero byte.
Errors: ERROR_Coke_BadResourceID

cokerr Coke_SetScriptTimer(byte rezID, byte timerID, word timeout)
sets a timer to execute a command script periodically, every (timeout * 8) milliseconds. timerID is a number between 0 and 127. If the given timerID is already in use, the old timer is replaced.
Errors: ERROR_Coke_BadResourceID

cokerr Coke_RemoveScriptTimer(byte timerID)
removes the given script timer. Note that this command can be called from within the script itself, for a "one-shot" delayed script.
Errors: ERROR_Coke_BadTimerID

cokerr Coke_ExecCodeResource(byte rezID)
executes the given code resource with the IPC_Coke_Execute message.
Errors: ERROR_Coke_BadResourceID

The following command is not implemented directly in Libcoke, but is used by the Libcoke_LoadModule() function:

special Coke_InitCodeResource (byte rezID, word numRelocs, word[] relocTable)
relocates an executable resource so it will run from wherever in memory it was loaded. numRelocs is the number of entries in the relocation table. Each entry of the table consists of a pointer (lobyte, hibyte), relative to the start of the code, of a hibyte that needs to be adjusted for whatever page the resource loader put it at. Lobytes do not need to be changed because code resources should be loaded with the RFLAG_PAGEALIGN attribute. cokedasm generates the relocation table with the -r option. After relocation, the code is executed with the IPC_Coke_Hello message. This command sets the RFLAG_INITIALIZED attribute of the resource.
Errors: ERROR_Coke_BadResourceID

Resource commands

cokerr Resource_CheckSpace (byte attributes, word length)
verifies that there is enough free memory to upload a resource with the given properties. If there is not enough memory, the command fails.
Errors: ERROR_Coke_NotEnoughMemory

cokerr Resource_QuerySpace (word* freespace)
returns in *freespace the number of free bytes left in memory. Be careful in using this value, because resources that must be page-aligned may take up more memory than expected when uploaded.

cokerr Resource_QueryResources (byte* numResources)
returns in *numResources the number of resources currently uploaded.

The following command's Libcoke c function has a different form than the actual firmware command:

Libcoke function:
cokerr Resource_LoadResource (byte attributes, word length, byte* data, byte* rezID)
uploads a resource to the board. attributes can be the logical OR of any of the following:
RFLAG_PAGEALIGN the resource is to be aligned with a 256-byte page in memory
RFLAG_EXECUTABLE the resource can be executed as code
RFLAG_INITIALIZED set by initialization routines; usually not set explicitly

The resource ID of the new resource is returned in *rezID.

literal firmware command:
special byte Resource_LoadResource (byte attributes, word length, byte[] data, word checksum)
Same as above, except checksum is a 16-bit checksum of all of the data bytes, and the new resource ID is returned as a query. Due to laziness on the part of the implementor, the command does NOT check if enough memory is available for the new resource. Resource_CheckSpace should be called beforehand. The Libcoke function does this for you.
Errors: ERROR_Coke_BadChecksum
  ERROR_Coke_NotEnoughMemory (only from Libcoke c function)

cokerr Resource_FreeResources (byte rezID)
frees all resources after and including the given resource ID. Before an executable resource is freed, it is executed with the IPC_Coke_Goodbye parameter to give it a chance to unload itself.