diff --git a/doc/en/arch_con_term.html b/doc/en/arch_con_term.html new file mode 100644 index 00000000..04959c53 --- /dev/null +++ b/doc/en/arch_con_term.html @@ -0,0 +1,89 @@ + + + +eLua consoles and terminals + + + +

eLua consoles and terminals

+

In eLua, a console and a terminal serve two related, but different purposes: +

+

Both components can be enabled and disabled as needed (they don't rely on each other). See building eLua for details on how to enable and disable components.

+

Serial consoles

+

The serial console input/output is handled by a generic layer (src/newlib/genstd.c) that can be used to easily adapt the console subsystem to a variety of input/output devices. + It needs just two functions, one for displaying characters and another one for receiving input with timeout:

+

// Send/receive function types
+typedef void ( *p_std_send_char )( int fd, char c );
+typedef int ( *p_std_get_char )( s32 to );
+

+

(the send faction gets an additional fd parameter that you can use to differentiate between the standard C stdout and stderr output streams).

+

To set them, use std_set_send_func and std_set_get_func, both defined in inc/newlib/getstd.h. Usually they are called from src/common.c and configured to work + over UART by default:

+

// *****************************************************************************
+// std functions and platform initialization
+
+static void uart_send( int fd, char c )
+{
+  fd = fd;
+  platform_uart_send( CON_UART_ID, c );
+}
+
+static int uart_recv( s32 to )
+{
+  return platform_uart_recv( CON_UART_ID, TERM_TIMER_ID, to );
+}
+
+void cmn_platform_init()
+{
+  // Set the send/recv functions                          
+  std_set_send_func( uart_send );
+  std_set_get_func( uart_recv );  
+}
+

+

If you need another type of serial console device (for example a dedicated console running over a SPI connection) just call std_set_send_func/std_set_get_func with the appropriate + function pointers.

+

To enable serial consoles, define the BUILD_CON_GENERIC macro in your platform's platform_conf.h file.

+

TCP/IP consoles

+

TCP/IP consoles have the same functionality as serial consoles, but they work over a TCP/IP connection using the telnet protocol. As they integrate directly with the TCP/IP subsystem, + they don't have the same generic function based mechanism as serial consoles. To enable TCP/IP consoles, define the BUILD_CON_TCP macro in your platform's platform_conf.h file.

+

Terminals

+

Besides standard stdio/stdout/stderr support provided by consoles, eLua uses the "term" module to access ANSI compatible terminal emulators. It is designed to be as flexible as + possible, thus allowing a large number of terminal emulators to be used. To enable terminal support, add BUILD_TERM in your platform's platform_conf.h file. To use it, initialize + it with a call to term_init: +

...........................
+// Terminal output function
+typedef void ( *p_term_out )( u8 );
+// Terminal input function
+typedef int ( *p_term_in )( int );
+// Terminal translate input function
+typedef int ( *p_term_translate )( u8 );
+...........................
+// Terminal initialization
+void term_init( unsigned lines, unsigned cols, p_term_out term_out_func, 
+                p_term_in term_in_func, p_term_translate term_translate_func );
+

+

The initialization function takes the physical size of the terminal emulator window (usually 80 lines and 25 cols) and three function pointers: +

+

For an example, see src/main.c, where these functions are implemented for an UART connection with a terminal emulator program running on PC.

+

eLua also provides a Lua module (called term) that can be used to access ANSI terminal. See the term module API for a full description of this module.

+ diff --git a/doc/en/arch_romfs.html b/doc/en/arch_romfs.html new file mode 100644 index 00000000..8a8bcfa5 --- /dev/null +++ b/doc/en/arch_romfs.html @@ -0,0 +1,62 @@ + + + +The ROM file system + + + +

The ROM file system

+

The ROM file system (ROMFS) is a small, read-only file system built for eLua. It is integrated with the C + library, so you can use standard POSIX calls (fopen/fread/fwrite...) to access it. It is also accessible directly from Lua via the io module. + The files in the file system are part of the eLua binary image, thus they can't be modified after the image is + built. For the seame reason, you can't add/delete files after the image is built. ROMFS doesn't support directories.

+

ROMFS is integrated with the build system for maximum flexibility on various platforms. As a result, you can select the ROMFS contents for each board on which + eLua runs. Moreover, you can specify what applications (instead of individual files) go to the file system, as a real application might need more than a single Lua program + to run (for example a HTTP page with all its dependencies).

+

Using ROMFS

+

To use ROMFS, you have to copy the required files to the romfs/ directory. Keep in mind that the maximum file name of a ROMFS file is 14 characters, including the dot between the file + name and its extension. Make sure that the file names from romfs/ follow this rule. Then edit the main build script (SConstruct) to add a new application/modify an existing one. + All the applications that can be included in ROMFS are defined in the romfs array in SConstruct. Each application in the romfs array lists its files, as shown below + (note that ltthpd, tvbgone and pong applications require more than one file in order to run):

+

romfs = { 
+    'bisect' : [ 'bisect.lua' ],
+    'hangman' : [ 'hangman.lua' ],
+    'lhttpd' : [ 'index.pht', 'lhttpd.lua', 'test.lua' ],
+    'pong' : [ 'pong.lua', 'LM3S.lua' ],
+    'led' : [ 'led.lua' ],
+    'piano' : [ 'piano.lua' ],
+    'pwmled' : [ 'pwmled.lua' ],
+    'tvbgone' : [ 'tvbgone.lua', 'codes.bin' ],
+    'hello' : [ 'hello.lua' ],
+    'info' : [ 'info.lua' ],
+    'morse' : [ 'morse.lua' ],
+    'dualpwm' : [ 'dualpwm.lua' ],
+    'adcscope' : [ 'adcscope.lua' ],
+    'life' : [ 'life.lua' ]
+}

+

After this, you need to decide the application-to-board mapping. This is defined in another array in SConsctruct, named file_list. The definition of this array is shown below, + the format is self-explanatory:

+

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' ],
+    'STR9-COMSTICK' : [ 'bisect', 'hangman', 'led', 'hello', 'info' ],
+    'PC' : [ 'bisect', 'hello', 'info', 'life' ],
+    'LPC-H2888' : [ 'bisect', 'hangman', 'led', 'hello', 'info' ],
+    'MOD711' : [ 'bisect', 'hangman', 'led', 'hello', 'info', 'dualpwm' ],
+    'STM3210E-EVAL' : [ 'bisect', 'hello', 'info' ],
+    'ATEVK1100' : [ 'bisect', 'hangman', 'led', 'hello', 'info' ],
+    'ET-STM32' : [ 'hello', 'hangman', 'info', 'bisect' ],
+    'EAGLE-100' : [ 'bisect', 'hangman', 'lhttpd', 'led', 'hello', 'info' ]              
+}
+

+

What's left to do is biuld eLua. As part of the build process, mkfs.py will be called, which will read the contents of the romfs/ directory and + output a C header file that contains a binary description of the file system. To use ROMFS from C code, whevener you want to access a file, prefix its name with /rom/. For example, + if you want to open the a.txt file in ROMFS, you should call fopen like this:

+

f = fopen( "/rom/a.txt", "rb" )

+

If you want to execute one file from the ROM file system with Lua, simply do this from the shell:

+ 

eLua# lua /rom/bisect.lua

+

Or directly from Lua:

+ 

> dofile "/rom/bisect.lua"

+ + diff --git a/doc/en/building.html b/doc/en/building.html index 2935f67d..89e72ac2 100644 --- a/doc/en/building.html +++ b/doc/en/building.html @@ -19,7 +19,7 @@ package manager you'll need to translate the "apt-get" calls to your specific distribution.
  • you have a toolchain (compiler, linker, assembler and -standard C libraries) for your target. Check ##the toolchains page for +standard C libraries) for your target. Check the toolchains page for toolchain instructions. Please note that even if you already have a compiled toolchain, the differences in the Newlib configure flags (mainly the --disable-newlib-supplied-syscalls flags) might prevent eLua @@ -89,7 +89,7 @@ started on the target. BUILD_ROMFS Enable the eLua read-only -filesystem. See the ##ROMFS +filesystem. See the ROMFS documentation for details about using the ROM file system. diff --git a/doc/en/using.html b/doc/en/using.html index c0773ecc..d71671b4 100644 --- a/doc/en/using.html +++ b/doc/en/using.html @@ -91,25 +91,25 @@ restrictions:

    +Hello,World

    • If you want to execute a file from the ##ROM file system, remember to prefix it with /rom. For example, to execute hello.lua, do this:

    $ lua /rom/hello.lua

    ls or dir

    Shows a list of all the files in the filesystems used by eLua (currently only the ROM file system), as well as their size and the total size of the given file system.

    exit

    Exits the shell. This only makes sense if eLua is compiled with terminal support over TCP/IP , as it closes the telnet session to the eLua board. Otherwise it just - terminates the shell and blocks forever until you reset your board. + terminates the shell and blocks forever until you reset your board.

    Cross-compiling your eLua programs

    Cross-compilation is the process of compiling a program on one hardware platform for a different hardware platform. For example, the process of compiling the eLua binary image on @@ -126,7 +126,7 @@ board you have some important advantages: might be able to overcome this by compiling the Lua program on the PC and running the bytecode instead. Also, compiling large Lua programs on your eLua board can lead to stack overflows, which in turn leads to very - hard to find errors. + hard to find errors.

    In order to use cross-compilation, the two Lua targets (in this case your desktop PC and your eLua board) must be compatible (they should have the same data types, with the same size and the same memory @@ -204,7 +204,7 @@ Available options are: You can omit the -s (strip) parameter from compilation, but this will result in larger bytecode files (as the debug information is not stripped if you don't use -s).

    You can use your bytecode file in two ways:

    diff --git a/doc/wb/wb_usr.lua b/doc/wb/wb_usr.lua index e0e8c951..8b952f89 100755 --- a/doc/wb/wb_usr.lua +++ b/doc/wb/wb_usr.lua @@ -218,6 +218,9 @@ wb_usr.tree = { name = { en = "Modules and LTR", pt = "##Module and LTR" }, link = "arch_ltr.html", }, + { name = { en = "Consoles and terminals", pt = "##Consoles and terminals" }, + link = "arch_con_term.html", + }, { name = { en = "eLua coding style", pt = "##eLua coding style" }, link = "arch_coding.html", }, diff --git a/doc/wb_search_en.txt b/doc/wb_search_en.txt index 5910333e..fa98068d 100644 --- a/doc/wb_search_en.txt +++ b/doc/wb_search_en.txt @@ -3,7 +3,7 @@ en/tut_bootstick.html en/dl_binaries.html en/arch_overview.html en/status.html -en/comunity.html +en/arch_con_term.html en/installing_lm3s.html en/tut_bootpc.html en/news.html @@ -17,22 +17,23 @@ en/tutorials.html en/arch_coding.html en/tut_openocd.html en/refman.html -en/arch_romfs.html en/doc.html +en/arch_romfs.html en/net_ref.html +en/arch_newport.html en/arch_ltr.html en/installing_avr32.html en/installing_str7.html en/installing_at91sam7x.html en/installing.html -en/arch_newport.html +en/tc_arm.html en/using.html en/versionhistory.html en/toolchains.html en/dl_old.html en/examples.html -en/tc_arm.html en/tchainbuild.html +en/comunity.html en/installing_str9.html en/installing_stm32.html en/arch.html diff --git a/doc/wb_search_pt.txt b/doc/wb_search_pt.txt index 8219019c..b0a237e1 100644 --- a/doc/wb_search_pt.txt +++ b/doc/wb_search_pt.txt @@ -3,7 +3,7 @@ pt/tut_bootstick.html pt/dl_binaries.html pt/arch_overview.html pt/status.html -pt/comunity.html +pt/arch_con_term.html pt/installing_lm3s.html pt/tut_bootpc.html pt/news.html @@ -17,22 +17,23 @@ pt/tutorials.html pt/arch_coding.html pt/tut_openocd.html pt/refman.html -pt/arch_romfs.html pt/doc.html +pt/arch_romfs.html pt/net_ref.html +pt/arch_newport.html pt/arch_ltr.html pt/installing_avr32.html pt/installing_str7.html pt/installing_at91sam7x.html pt/installing.html -pt/arch_newport.html +pt/tc_arm.html pt/using.html pt/versionhistory.html pt/toolchains.html pt/dl_old.html pt/examples.html -pt/tc_arm.html pt/tchainbuild.html +pt/comunity.html pt/installing_str9.html pt/installing_stm32.html pt/arch.html diff --git a/doc/wb_tree_en.html b/doc/wb_tree_en.html index d2e81396..91a2be69 100644 --- a/doc/wb_tree_en.html +++ b/doc/wb_tree_en.html @@ -273,177 +273,178 @@

    ROM file system

    Adding a new port

    Modules and LTR

    -

    eLua coding style

    +

    Consoles and terminals

    +

    eLua coding style

    -

    Examples

    +

    Examples

    -

    hello.lua

    -

    info.lua

    -

    led.lua

    -

    hangman.lua

    -

    pwmled.lua

    -

    tvbgone.lua

    -

    piano.lua

    -

    bisect.lua

    -

    morse.lua

    -

    lhttpd.lua

    +

    hello.lua

    +

    info.lua

    +

    led.lua

    +

    hangman.lua

    +

    pwmled.lua

    +

    tvbgone.lua

    +

    piano.lua

    +

    bisect.lua

    +

    morse.lua

    +

    lhttpd.lua

    -

    Tutorials

    +

    Tutorials

    -

    Booting on a PC

    -

    Booting from a Pendrive

    -

    Toolchain Building

    +

    Booting on a PC

    +

    Booting from a Pendrive

    +

    Toolchain Building

    -

    Using OpenOCD

    +

    Using OpenOCD

    -

    Version History

    +

    Version History

    -

    v 0.4

    -

    v 0.5

    -

    v 0.6

    +

    v 0.4

    +

    v 0.5

    +

    v 0.6

    -

    Reference Manual

    +

    Reference Manual

    -

    Generic Modules

    +

    Generic Modules

    -

    Platform Dependent Modules

    +

    Platform Dependent Modules

    -

    Downloads

    +

    Downloads

    -

    Binaries

    -

    Source Code

    +

    Binaries

    +

    Source Code

    -

    Old Versions

    +

    Old Versions

    Free Hit Counter

    diff --git a/doc/wb_tree_pt.html b/doc/wb_tree_pt.html index 986777f0..44dd91da 100644 --- a/doc/wb_tree_pt.html +++ b/doc/wb_tree_pt.html @@ -219,231 +219,232 @@

    eLua

    -

    Apresentação

    +

    Apresentação

    -

    Comunidade

    +

    Comunidade

    -

    Notícias

    -

    Status

    +

    Notícias

    +

    Status

    -

    Documentação

    +

    Documentação

    -

    Manual de Referência

    +

    Manual de Referência

    -

    Módulos Genéricos

    +

    Módulos Genéricos

    -

    Dependentes de Plataforma

    +

    Dependentes de Plataforma

    -

    Downloads

    +

    Downloads

    Free Hit Counter