Porting eLua

So, you realized how cool eLua is :), and you'd like to give it a try. Unfortunately, eLua doesn't have a port on your CPU of choice. The solution is simple: write the port yourself. This might seem as a daunting task at first, but it's actually easier than it sounds. eLua was designed to make the task of implementing new ports as easy and intuitive as possible. This section gives an overview of the porting process. It's not an exhaustive guide, but it should be enough to point you in the right direction. Before diving into this, it's highly recommended that you take a look at the eLua architecture page.

Prerequisites

Before starting to work on the port, make sure that:

• your CPU has enough resources to run eLua. A very rough estimation (based on ARM Thumb code only) is that you'd need at least 256k of program memory and 32k of RAM for a complete eLua image, and 128k of program memory for a basic image. It's possible to run eLua in less than 32k of RAM (especially when LTR is enabled), but you'll probably run out of memory fast. 64k of RAM (or more) is recommended.
• Newlib can be compiled for your CPU. eLua depends on Newlib currently (although this limitation will be eliminated in a future version), so if Newlib is not available for your CPU, you're out of luck.
• you have a C compiler for your target. Ideally you'd use GCC, but if this isn't possible other compilers might work as well. Keep in mind that LTR needs a C99 C compiler (or at least a partially C99 compliant C compiler than supports C99-style union initialization).

If all of the above are true, you should continue reading this document to bring your port to life. If not, we're sorry, but (at least at this point) eLua can't be ported to your CPU.

Overall structure of a port

eLua uses the notion of platform to denote a group of CPUs that share the same core structure, although their specific silicon implementation might differ in terms of intergrated peripherals, internal memory and other such attributes. An eLua port implements one or more CPUs from a given platform. For example, the lm3s port of eLua runs on LM3S8962, LM3S6965 and LM3S6918 CPUs, all of them part of the lm3s platform (reffer to the status page for a full list of platforms and CPUs on which eLua runs).

All the source files specific to a platform/port reside in a subdirectory of src/platform that has the same name as the platform (for lm3s it would be src/platform/lm3s, for example). Each such platform-specific subdirectory must contain at least these files:

• type.h: this defines the "specific data types", which are integer types with a specific size (see coding style for details. An example from the i386 platform:

  typedef unsigned char u8;
  typedef signed char s8;
  typedef unsigned short u16;
  typedef signed short s16;
  typedef unsigned long u32;
  typedef signed long s32;
  typedef unsigned long long u64;
  typedef signed long long s64;

• conf.py: this is the platform specific build configuration file, used by the build system for a number of purposes:
  • to get the list of platform-specific files that will be compiled in the eLua image. They are exported in the specific_files string, separated by spaces, and must be prepended with the relative path to the platform subdirectory. An example from the i386 platform:

    specific_files = "boot.s common.c descriptor_tables.c gdt.s interrupt.s isr.c kb.c  monitor.c timer.c platform.c"
    # Prepend with path
    specific_files = " ".join( [ "src/platform/%s/%s" % ( platform, f ) for f in specific_files.split() ] )

  • to get the full command lines of the different toolchain utilities (linker, assembler, compiler) used to compile eLua. They must be declared inside the tools variable, in a separate dictinoary which key is the same as the platform name, and with specific names for each tool in turn: cccom for the compiler, linkcom for the linker and ascom for the assembler. For example, this is how the tools variable is defined for the i386 platform:

    # Toolset data
     tools[ 'i386' ] = {}
     tools[ 'i386' ][ 'cccom' ] = "%s %s %s -march=i386 -mfpmath=387 -m32 -ffunction-sections -fdata-sections -fno-builtin -fno-stack-protector %s -Wall -c $SOURCE -o $TARGET" % ( toolset[ 'compile' ], opt, local_include, cdefs )
     tools[ 'i386' ][ 'linkcom' ] = "%s -nostartfiles -nostdlib -march=i386 -mfpmath=387 -m32 -T %s -Wl,--gc-sections -Wl,-e,start -Wl,--allow-multiple-definition -o $TARGET $SOURCES -lc -lgcc -lm %s" % ( toolset[ 'compile' ], ldscript, local_libs )
     tools[ 'i386' ][ 'ascom' ] = "%s -felf $SOURCE" % toolset[ 'asm' ]

    Note how the definition of tools uses the definition of toolset, a dictionary with the names of the tools in the current toolchain. This is also part of the eLua build system and is documented here.
  • to get the name of a programmning function which receives the name of the eLua executable file (the result of the build step) and produces a file suitable for programming on the corresponding hardware platform. The name of this function should also be set in the tools dictionary, as shown below (example taken from the str7 platform):

    # Programming function for STR7
     def progfunc_str7( target, source, env ):
       outname = output + ".elf"
       os.system( "%s %s" % ( toolset[ 'size' ], outname ) )
       print "Generating binary image..."
       os.system( "%s -O binary %s %s.bin" % ( toolset[ 'bin' ], outname, output ) )
               
       tools[ 'str7' ][ 'progfunc' ] = progfunc_str7

    Note, once again, how this function uses the same toolset variable mentioned in the previous paragraph.
• stacks.h: by convention, the stack(s) size(s) used in the system are declared in this file. An example taken from the at91sam7x platform is given below:

  #define  STACK_SIZE_USR   2048
  #define  STACK_SIZE_IRQ   64
  #define  STACK_SIZE_TOTAL ( STACK_SIZE_USR + STACK_SIZE_IRQ )

• platform.c: by convention, the ##platform interface is implemented in this file. It also contains the platform-specific initialization function (platform_init, see the description of the eLua boot process for details).
• platform_conf.h

Prerequisites

The very first thing to do before starting a new port is to verify if you can use one of the already existing platforms. A platform groups CPUs that share the same core structure, although their specific silicon implementation might differ in terms of integrated peripherals, internal memory, package size and other such attributes. For a list of ports currently supported by eLua check the status page. If you find