$$HEADER$$

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 or board 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 is available 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).
you have a platform library (it usually comes from the CPU manufacturer) that you can use to implement (at least part of) the platform interface. It's also highly recommended to gain at least a basic understanding of your platform, it will help a lot while writing the port.

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. If, on the other hand, you're good to go, please take a bit of time and read this section first, as it details the structure of a port and might simplify your work quite a bit.

Adding a new board

If all you need is to add a new board that uses a CPU already supported by eLua (check here for a complete list), it's fairly easy to accomplish this:

choose a good name for your board :)

edit SConstruct and add your board to the board_list dictionary, specifying its CPU. A part of the definition of board_list is given below:

# List of board/CPU combinations
board_list = { 'SAM7-EX256' : [ 'AT91SAM7X256', 'AT91SAM7X512' ],
               'EK-LM3S8962' : [ 'LM3S8962' ],
               'EK-LM3S6965' : [ 'LM3S6965' ],
               ..............................
            }

also edit the file_list dictionary in SConstruct to specify the list of ROMFS files that will be compiled for your board (see the ROMFS section for details). A part of the definition of file_list is given below:

# List of board/romfs data combinations
file_list = { 'SAM7-EX256' : [ 'bisect', 'hangman' , 'led', 'piano', 'hello', 'info', 'morse' ],
              'EK-LM3S8962' : [ 'bisect', 'hangman', 'lhttpd', 'pong', 'led', 'piano', 'pwmled', 'tvbgone', 'hello', 'info', 'morse', 'adcscope' ],
              'EK-LM3S6965' : [ 'bisect', 'hangman', 'lhttpd', 'pong', 'led', 'piano', 'pwmled', 'tvbgone', 'hello', 'info', 'morse', 'adcscope' ],
              ...............................
            }

if your board has external memory, you'll probably want to use the "multiple" allocator by default to take advantage of that (see building) for details. If so, you need to modify the CPU/allocator mapping code from SConstruct:

# CPU/allocator mapping (if allocator not specified)
if allocator == '':
  if boardname == 'LPC-H2888' or boardname == 'ATEVK1100':
    allocator = 'multiple'
  else:
    allocator = 'newlib'
elif allocator not in [ 'newlib', 'multiple', 'simple' ]:
  print "Unknown allocator", allocator
  print "Allocator can be either 'newlib', 'multiple' or 'simple'"
  sys.exit( -1 )

customize the eLua image for this new board. You can use the variable boardname in conf.py to define new preprocessor macros specifically for your board (that you can use later in platform_conf.h, for example), or to include or exclude certain files from the build, or change the build flags and so on. An example taken from the lm3s port is given below (part of conf.py):

if boardname == 'EK-LM3S6965' or boardname == 'EK-LM3S8962':
  specific_files = specific_files + " rit128x96x4.c disp.c"
  cdefs = cdefs + " -DENABLE_DISP"

# The default for the Eagle 100 board is to start the image at 0x2000,
# so that the built in Ethernet boot loader can be used to upload it
if boardname == 'EAGLE-100':
  linkopts = "-Wl,-Ttext,0x2000"
else:
  linkopts = ""

After you edit all the relevant source files, all you have to do is to execute scons board=<boardname> and you'll have eLua compiled for your board.

Adding a new CPU

If you want to add a new CPU to eLua and the new CPU happens to be supported by a platform on which eLua already runs (see here for a full list), your task is still quite easy. Follow the steps below:

edit SConstruct and add your new CPU to the platform_list dictionary. Use the "official" name of the CPU (as it appears in its datasheet). An example is given below:

# List of platform/CPU/toolchains combinations
# The first toolchain in the toolchains list is the default one
# (the one that will be used if none is specified)
platform_list = {
  'at91sam7x' : { 'cpus' : [ 'AT91SAM7X256', 'AT91SAM7X512' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  'lm3s' : { 'cpus' : [ 'LM3S8962', 'LM3S6965', 'LM3S6918' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  'str9' : { 'cpus' : [ 'STR912FAW44' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  ..................
}

you also need to add a new board to eLua (which makes sense, since you're most likely going to run eLua on a board built around the CPU of your choice, not only on the CPU itself). So follow the instruction from the previous paragraph to add your new board.
customize the eLua image for this new CPU. You can use the variable cputype in conf.py to define new preprocessor macros specifically for your CPU (that you can use later in platform_conf.h, for example), or to include or exclude certain files from the build, or change the build flags and so on. An example taken from the at91sam7x port is given below (part of conf.py):
```
if cputype == 'AT91SAM7X256':
  ldscript = "flash256.lds"
  cdefs = cdefs + " -Dat91sam7x256"
elif cputype == 'AT91SAM7X512':
  ldscript = "flash512.lds"
  cdefs = cdefs + " -Dat91sam7x512"
else:
  print "Invalid AT91SAM7X CPU %s" % cputype
  sys.exit( -1 ) 
```

After you edit all the relevant source files, all you have to do is to execute scons board=<boardname> and you'll have eLua compiled for your board (and implicitly for your new CPU).

Adding a new platform

If you want to add a new CPU to eLua and the new CPU is not supported by a platform on which eLua already runs (see here for a full list), you have to go the whole way and add a completely new platform to eLua. This is certainly more difficult than the previous cases, but still not that hard. Remember to start small (implement only minimal support at first) and don't write everything from scratch, start from an already existing platform implementation and work your way up from there. The i386 port is the simplest, but also a bit different from the embedded ports. Another port that is quite simple at this point is the lpc2888 port, you might take a look at that too. After you "get a feeling" of how a port should look like, and after you read about the architecture of eLua and the structure of a port here, follow the steps below:

choose the name of your new platform. It should be an easy, descriptive name. For example, all the CPUs from the LM3S series are grouped inside a platform called lm3s.
create the src/platform/<name> directory, and add all your platform-specific files here. Check here for specific details.
use the instructions from the previous paragraph to add your new CPU and board to eLua.
implement as much as you need from the platform interface.
if your new platform uses a toolchain that wasn't previously configured in eLua, add it now (see here for more details about toolchains).

let SConstruct know about your new platform by modifying the platform_list variable to add information about the CPU(s) available for your platform and about its toolchains. An example is given below:

# List of platform/CPU/toolchains combinations
# The first toolchain in the toolchains list is the default one
# (the one that will be used if none is specified)
platform_list = {
  'at91sam7x' : { 'cpus' : [ 'AT91SAM7X256', 'AT91SAM7X512' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  'lm3s' : { 'cpus' : [ 'LM3S8962', 'LM3S6965', 'LM3S6918' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  'str9' : { 'cpus' : [ 'STR912FAW44' ], 'toolchains' : [ 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' ] },
  ..................
}

After you edit all the relevant source files, all you have to do is to execute scons board=<boardname> and you'll have eLua compiled for your board (and implicitly for your new CPU).

$$FOOTER$$