all code that is platform-independent is common code and it should be written in ANSI C as much as possible, this makes it highly portable among different architectures and compilers, just like Lua itself.

all the code that can’t possibly be generic (mostly peripheral and CPU specific code) must still be made as portable as possible by using a common interface that must be implemented by all platforms on which eLua runs. This interface is called platform interface and is discussed in detail here (but please see also the platform interface paragraph in this document).

all platforms (and their peripherals) are not created equal and vary greatly in capabilities. As already mentioned, the platform interface tries to group only common attributes of different platforms. If one needs to access the specific functionality on a given platform, it can do so by using a platform module. These are of course platform specific, and their goal is to fill the gap between the platform interface and the full set of features provided by a platform.

the Lua code itself plus the LTR patch.

all the components in eLua (like the ROM file system, the XMODEM code, the eLua shell, the TCP/IP stack and others).

all the generic modules, which are Lua modules used to expose the functionality of the platform to Lua.

generic peripheral support code, like the ADC support code (src/common/elua_adc.c) that is independent of the actual ADC hardware.

libc code (for example allocators and Newlib stubs).

if you want to add a new file system to eLua, this should definitely be generic code. It’s likely that this kind of code will have dependencies related to the physical medium on which this file system resides. If you’re lucky, you can solve these dependencies using only the functions defined in the platform interface (this would make sense if you’re using a SD card controlled over SPI, since the platform interface already has a SPI layer). If not, you should group the platform specific functions in a separate interface that will be implemented by all platform that want to use your new file system. This gives the code maximum portability.

if you want to add a driver for a specific ADC chip that works over SPI, the same observations apply: write it as common code as much as you can and use the platform interface for the specific SPI functions you need.

a port isn’t required to implement all the platform interface functions, just the ones it needs. As explained here, the user must have full control over what’s getting built into this eLua image. If you don’t need the SPI module, for example, you don’t need to implement its platform interface.

a part of the platform interface is implemented (at least partially) in a file that is common for all the platforms (src/common.c). It eases the implementation of some modules (such as the timer module) and also implements common features that are tied to the platform interface, but have a common behaviour on all platforms (for example virtual timers, here for details). You probably won’t need to modify it if you’re writing platform specific code, but it’s best to keep in mind what it does.

if implementing new functionality on the UART module of the LM3S platform, the corresponding module should be called lm3s.uart.

if implementing a peripheral driver that for some reason should be specific to the platform on the LPC2888 platform, for example its dual audio DAC, give it a meaningful name, for example lpc288x.audiodac.

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.lua: this is the platform specific build configuration file, used by the build system for a number of purposes:

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: this is the platform configuration file, used to give information about both the platform itself and the build configuration for the platform. This file includes information about the CPU used by the eLua hardware, as well as build configuration data (the list of components, modules and the static configuration data, see here for more information about how to configure your build). Each CPU used by eLua needs a CPU definition file in its respective platform. For example, this is the CPU definition file for STR711FR2 in the _str7 platform (src/platform/str7/cpu_str711fr2.h):

// STR711FR2 CPU description

#ifndef __CPU_STR711FR2_H__
#define __CPU_STR711FR2_H__

#include "stacks.h"

// Number of resources (0 if not available/not implemented)
#define NUM_PIO               2
#define NUM_SPI               0
#define NUM_UART              4
#define NUM_TIMER             4
#define NUM_PWM               3
#define NUM_ADC               0
#define NUM_CAN               0

// CPU frequency (needed by the CPU module and MMCFS code, 0 if not used)
#define CPU_FREQUENCY         0

// PIO prefix ('0' for P0, P1, ... or 'A' for PA, PB, ...)
#define PIO_PREFIX            '0'
// Pins per port configuration:
// #define PIO_PINS_PER_PORT (n) if each port has the same number of pins, or
// #define PIO_PIN_ARRAY { n1, n2, ... } to define pins per port in an array
// Use #define PIO_PINS_PER_PORT 0 if this isn't needed
#define PIO_PINS_PER_PORT     16

#define SRAM_ORIGIN           0x20000000
#define SRAM_SIZE             0x10000
#define INTERNAL_RAM1_FIRST_FREE end
#define INTERNAL_RAM1_LAST_FREE  ( SRAM_ORIGIN + SRAM_SIZE - STACK_SIZE_TOTAL - 1 )

#endif // #ifndef __CPU_STR711FR2_H__

networking configuration: if you need TCP/IP on your board, you need to add networking support to eLua (see building for a list of configuration options related to TCP/IP). You also need to have another file, called uip-conf.h that configures uIP (the TCP/IP stack in <b>eLua</b>) for your specific architecture. See TCP/IP in eLua for details.

a "startup sequence, generally written in assembler, that does very low level intialization, sets the stack pointer, zeroes the BSS section, copies ROM to RAM for the DATA section and then jumps to main.

a linker command file.

the CPU support package generally comes from the CPU manufacturer and includes code for accessing peripherals, configuring the core, setting up interrupts and so on.