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.
Original Micromite CFunction Tutorials
Here is a list of @matherp's (old but essential reading) tutorials for CFunctions (for Micromites! on PIC32 chips.):
CFunctions - learning by example (1)
CFunctions - learning by example (2)
CFunctions - learning by example (3)
CFunctions - learning by example (4)
The CFunction.h File
The header file cfunctions.h provides interworking between MMBasic and CSubs/CFunctions. Basically there are 3 categories of interfaces to the MMBasic firmware available
- MMBasic firmware routines that can be called from CFunctions/CSubs
- Definitions that allow CFunctions to use MMBasic firmware data
- Definitions that allow the MMBasic firmware to call CFunction/CSub routines
Cfunctions.h facilities
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.
CSubs and CFunctions on the ARM Chips
The Armmites, CMM2 and Picomites are based on the ARM processor. There are some differences compared with the CFunctions on the PIC32 chips. The post below identifies most of them.
ArmmiteF4 CSUBs and LCD drivers
TBS Threads detailing CSUB creation
ArmmiteF4 CSUBs and LCD drivers
CMM2: V5.05.04b3a: CSUBs - not for the faint hearted!!!!
PicoMite V5.07.01b16: Breaking changes and CSUBs
writing_csubs_for_mmbasic_picomite.pdf (Included in Picomite Firmware Download)
Picomite CSubs: A new (easier) approach !!!
Some background Information and documents
When You Might Use -lgcc
You would typically encounter or need to manually use the -lgcc option in specific, advanced scenarios,such as when you use -nostdlib or -nodefaultlibs: These options prevent the automatic inclusion of standard libraries, including libgcc. In suchcases, you must explicitly add -lgcc (and potentially other libraries like -lc for the standard C library) to your link command. Important: RP2040 lacks hardware 64-bit multiply, so you must link with -lgcc to include the __aeabi_lmul helper function. Libraries: The -nostartfiles option only affects the startup files. Standard system libraries (like libc and libgcc) are still used normally unless you also specify other flags like -nostdlib or -nodefaultlibs.
Some CSub examples on TBS
Some Links for later
These three links are useful reading.
Understanding parsing of complex C declarations
C Declaration Primer
Reading C Declarations
Passing parameters to CSubs
csub and array - help please (pointers and passing parameters)
CFunction return value
The Micromites, Armmite F4, Armmite H7 and CMM2 (6.00.00 onward) 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:Picomites and CMM2 have a two byte token for commands i.e. 16 bit tokens for commands. e.g “Hello World” | 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.
An online C compiler
This
online C compiler might be useful to test some
simple C code.
TBS link where it was used by @matherp