mmb2csub - turn an MMBasic SUB or FUNCTION into a CSUB
=====================================================

Read docs/mmb2csub.pdf (or the same thing as docs/mmb2csub.md). Section 2 is
the setup; everything below is only the short version of it.

WHAT IS IN HERE
  user-tools/mmb2csub.py    the converter - this is what you run
  user-tools/mmcsub.h       the runtime the generated CSUB compiles against
  user-tools/armcfgen.py    turns the compiled object into a CSUB hex block
  user-tools/mmb2c.py       the MMBasic-to-C translator that does the
                            MMBasic-to-C half of the job
  user-tools/xsend.py       optional: sends a program to the board by XMODEM
  PicoCFunctions.h          the firmware's CSUB header
  docs/                     this tool's manual, and the one for writing a
                            CSUB by hand
  examples/                 two programs to try it on

WHAT IS NOT, AND YOU MUST INSTALL
  1. Python 3.6 or later.
  2. The Arm GNU toolchain - arm-none-eabi-gcc - on your PATH. This is the
     only large download, and if you have ever built the firmware you have it
     already.
  3. pyelftools:   pip install pyelftools
  4. pyserial, ONLY if you want xsend.py:   pip install pyserial

KEEP THE LAYOUT
  mmb2csub.py finds PicoCFunctions.h and mmcsub.h relative to its own
  location, so there is nothing to configure - but it does mean you should
  unpack the whole folder and leave user-tools/ where it is.

CHECK IT WORKS
  cd user-tools
  python mmb2csub.py ../examples/julia.bas --list

  That changes nothing. It compiles and links every routine in the program
  and reports what can be converted and what each would cost. A listing means
  the whole chain works.

THE BOARD NEEDS FIRMWARE 6.03.02b9 OR LATER
  Check with:  ? MM.VER     which must read 6.030209 or higher.

  Nothing on your PC can check this for you. A CSUB is built without knowing
  what it will run on, so on older firmware it does not fail to build - it
  calls a CallTable entry that does not exist yet, and the board crashes with
  no message. If a CSUB that built cleanly misbehaves from its very first
  call, check this first.
