Table of Contents
CSUBs & CFUNCTIONS - Creation
Creating CSubs and CFunctions
There is currently no comprehensive guide to creating CSUBs however there are a number of TBS posts that give enough information to get you started. It is hoped that this page can eventually be developed into a comprehensive guide. In the mean time here are the TBS threads that can get you started.
TBS Threads detailing CSUB creation
CMM2: V5.05.04b3a: CSUBs - not for the faint hearted!!!!
PicoMite V5.07.01b16: Breaking changes and CSUBs
ArmmiteF4 CSUBs and LCD drivers
csub and array - help please (pointers and passing parameters)
Note: Ensure you use an updated CFunctions.h header file from the latest release of the firmware for your device. The header file must match the firmware you are using if you make use of any calls to MMBasic functions.
Some CSub examples on TBS
Passing parameters to CSubs
CFunction return value
The Micromites ,Armmite F4 and Armmite H7 also support CFunctions. These are essentially the same as CSubs but return a value. ( A CSub can adjust the called parameters and returns results by doing that)
Specifying the type of the CSUB parameters
MMBasic will use these types to either issue an error message if the wrong type of variable is
supplied as a parameter or to convert a parameter if it can. For example, if a parameter is specified
as an integer and a float is provided MMBasic will convert the float to an integer before passing its
address to the C routine.
How CSubs are stored (background info)
| Program as Viewed in Editor ——————————————————————- | Program as saved in Flash |
|---|---|
| DIM a$=”ABCDEF” DIM b$ PRINT “HELLO WORLD” REVSTR a$,b$ CSUB STRREV(STRING,STRING) 00000000 B085B480 6078AF00 687B6039 60BB781B … 1AD368FB 687A3301 6839441A 440B68FB … D3EC429A BF00BF00 46BD3714 7B04F85D … END CSUB |  a$=”ABCDEF” b$ “HELLO WORLD”REVSTR a$,b$  REVSTR(STRING,STRING)00000000 B085B480 6078AF00 687B6039 60BB781B … 1AD368FB 687A3301 6839441A 440B68FB … D3EC429A BF00BF00 46BD3714 7B04F85D …  00000000 FFFFFFFF (end of program marker) binary/machine code) |
| Note 1: The binary code of the CSUB is never in the editor. You only ever seen the Hexidecimal source for the binary. MMBasic can be used to edit and save this hexidecimal version of the CSUB, however the ARM or PIC processor used to make the MMBasic device cannot use or understand a hexidecimal coded CSUB. It is only for humans! Note 2: When an MMBasic program is run the Hexidecimal coded CSUB is skipped over, MMBasic will make no attempt to use/decipher it. When a CSUB is called in the program, MMBasic will instead look for the binary copy of the CSUB and point the ARM/PIC processor to that location to process the machine code and wait for it to (hopefully) return. Note 3: When the code in the editor is saved to flash all MMBasic keywords e.g. PRINT are saved as their individual unique 8 bit single character token e.g. These tokens all have BIT 7 set to 1. | Note 4: When the file in the Editor is saved to flash, MMBasic will also produce and append a binary copy of the CSUB after the saved program. This is actual machine code that can be understood /run by the ARM or PIC processor. It is around half the size of the Hexidecimal version of the CSUB when saved. AUTOSAVE and XMODEM as methods of loading a program will also do this step of converting any Hexidecimal coded CSUBs to binary and appending them after the the program code. Note5: When the EDIT command is used the program in program flash is loaded into ram, all tokens are translated back to their expanded MMBasic keyword, the Hexidecimal coded CSUB is loaded with the rest of the program, however the binary/machine code copy of the CSUB is not loaded into the editor. When the code in the editor is saved the binary/machine code is deleted and a new copy of the binary/machine code CSUB is generated again and appended. |
Placing CSubs in the Library (background info)
When a CSub is saved to the library only binary/machine code is saved. The hexidecimal version of the CSub is discarded, so that program space is recovered. You will need to ensure you have a separate copy of it if you need to modify it.