diff --git a/build_elua.lua b/build_elua.lua index e2d30d1c..0eb2ebfe 100755 --- a/build_elua.lua +++ b/build_elua.lua @@ -160,7 +160,7 @@ print( utils.col_blue( "[CONFIG] Found board description file at " .. bfname ) ) local bdata, err = bconf.compile_board( bfname, comp.board ) if not bdata then print( utils.col_red( "[CONFIG] Error compiling board description file: " .. err ) ) - do return end + return end -- Check if the file has changed. If not, do not rewrite it. This keeps the compilation time sane. local bhname = utils.concat_path( { board_base_dir, "headers", "board_" .. comp.board:lower() .. ".h" } ) diff --git a/config/components.lua b/config/components.lua index d2003752..f67b1ae5 100644 --- a/config/components.lua +++ b/config/components.lua @@ -66,6 +66,8 @@ function init() } -- Shell components.shell = { macro = 'BUILD_SHELL' } + -- Advanced shell + components.advanced_shell = { macro = 'BUILD_ADVANCED_SHELL', autoenable = 'shell' } -- Term components.term = { macro = 'BUILD_TERM', @@ -155,9 +157,7 @@ function init() components.adc = { macro = 'BUILD_ADC', attrs = { - buf_size = at.make_optional( at.int_log2_attr( 'ADC_BUF_SIZE' ) ), - first_timer = at.make_optional( at.int_attr( 'ADC_TIMER_FIRST_ID' ) ), - num_timers = at.make_optional( at.int_attr( 'ADC_NUM_TIMERS' ) ) + buf_size = at.make_optional( at.int_log2_attr( 'ADC_BUF_SIZE' ) ) } } -- DNS client diff --git a/config/config.lua b/config/config.lua index aef1d951..ec8327f8 100644 --- a/config/config.lua +++ b/config/config.lua @@ -147,6 +147,10 @@ local sanity_code = [[ #define CON_TIMER_ID PLATFORM_TIMER_SYS_ID #endif +#ifndef RFS_FLOW_TYPE +#define RFS_FLOW_TYPE PLATFORM_UART_FLOW_NONE +#endif + #ifdef ELUA_BOOT_RPC #ifndef RPC_UART_ID #define RPC_UART_ID CON_UART_ID @@ -206,6 +210,9 @@ function compile_board( fname, boardname ) -- Check CPU local cpulist = bd.get_all_cpus() if not utils.array_element_index( cpulist, desc.cpu:upper() ) then + io.write( utils.col_red( "[CONFIG] Allowed CPUS: " ) ) + for i = 1, #cpulist do io.write( utils.col_red( cpu_list[ i ] .. " " ) ) end + print "" return false, sf( "unknown cpu '%s'", desc.cpu ) end diff --git a/config/modules.lua b/config/modules.lua index 044565db..1df23f92 100644 --- a/config/modules.lua +++ b/config/modules.lua @@ -228,7 +228,7 @@ function gen_module_list( desc, plconf, platform, boardname ) -- Not quite ready yet. We still need to generate the list of generic modules -- that can't be completely ROM'd by the LTR patch in a separate macro that will be -- handled by linit.c - local noltr = "#define LUA_LIBS_NOLTR\\\n", found + local noltr, found = "#define LUA_LIBS_NOLTR\\\n", false for m, _ in pairs( gen_list_generic ) do if get_map_name( m ) == "" then noltr = noltr .. sf( " { %s, %s },\\\n", get_auxlib( m ), get_openf_name( m ) ) diff --git a/config/sections.lua b/config/sections.lua index 1d90c3c9..5641bbd4 100644 --- a/config/sections.lua +++ b/config/sections.lua @@ -57,6 +57,15 @@ end function configure_section( section, sectname, data ) conf, enabled, required = {}, {}, {} + -- Check if any part of the section needs to be automatically enabled + for elname, elval in pairs( data ) do + if elval and section[ elname ] and section[ elname ].autoenable then + local auto = section[ elname ].autoenable + local t = type( auto ) == "table" and auto or { auto } + for _, v in pairs( t ) do data[ v ] = true end + end + end + -- Configure each element in turn, doing validation if required for elname, elval in pairs( data ) do if not section[ elname ] then return nil, sf( "unknown element '%s' in section '%s'", elname, sectname ) end diff --git a/doc/css/style1.css b/doc/css/style1.css index 456bb295..9198c184 100644 --- a/doc/css/style1.css +++ b/doc/css/style1.css @@ -302,6 +302,10 @@ code{font-size:14px;} padding: 2px; } +.grey-background { + background: silver; +} + #interna_2 #article .section_conteudo{width:auto;float:left;margin:10px 10px 0px 0;padding:10px;text-align:normal;} #interna_2 #article .section_size{width:700px;} #interna_2 #article .section_conteudo h1{font-size:25px;font-family:'fonte_chamada', Helvetica, Arial, sans-serif;text-align:bold;margin-bottom:10px;} diff --git a/doc/docdata.lua b/doc/docdata.lua index 85352918..5ffd6269 100644 --- a/doc/docdata.lua +++ b/doc/docdata.lua @@ -153,6 +153,13 @@ local menu = }, { { "Building eLua", "Build de eLua" }, "building.html", { + { "Configuring the image", "configurator.html", + { + { "CPU", "configurator.html#config_cpu" }, + { "Components", "configurator.html#config_components" }, + { "Configuration", "configurator.html#config_config" }, + }, + }, { "Building eLua in Linux", "building_unix.html" }, { "Building eLua in Windows", "building_win.html" }, }, diff --git a/doc/en/asciidoc.conf b/doc/en/asciidoc.conf index a4815aef..0295b575 100644 --- a/doc/en/asciidoc.conf +++ b/doc/en/asciidoc.conf @@ -22,6 +22,8 @@ monospacedwords= [tabledef-default] orange-style=tags="orange" graybg-style=tags="graybg" +noboldgraybg-style=tags="noboldgraybg" +bluebg-style=tags="bluebg" [tabletags-orange] bodydata=| @@ -29,6 +31,12 @@ bodydata=| [tabletags-graybg] bodydata=| +[tabletags-noboldgraybg] +bodydata=| + +[tabletags-bluebg] +bodydata=| + [replacements] # Status images _sok=image:images/stat_ok.png[Status: OK] diff --git a/doc/en/building.txt b/doc/en/building.txt index ae508177..f1484d74 100644 --- a/doc/en/building.txt +++ b/doc/en/building.txt @@ -381,11 +381,12 @@ Your build target is specified by *board*. The other options are as follows: * **romfs_dir=**: the directory with the link:arch_romfs.html[romfs] files. The default is "romfs". -* **board_config_file=**: the configuration file for the board. This will ignore the configuration file generated by the Lua configurator and use the user-specified one instead. For more details +* **board_config_file=**: the configuration file for the board. The builder will not search the board configuration file in the standard paths, using the user-specified one instead. For more details about the configurator, see link:configurator.html[this link]. * **skip_conf=true | false**: don't call the Lua configurator at all, use whatever configuration file is present in the system instead. This can be used for manually editing the configuration file: run - the build normally (with skip_conf=false) once, edit the generated configuration header file, then run the build again with skip_conf=true. + the build normally (with skip_conf=false) once, edit the generated configuration header file, then run the build again with skip_conf=true. For more details about the configurator, see + link:configurator.html[this link]. * **-E | -S**: see the link:#singlefile[single file compilation] section below. @@ -436,7 +437,7 @@ $ lua build_elua.lua board=mbed -E src/main.c Preprocess src/main.c, using 'mbed' as the target board. --------------------------------------------- -$ lua build_elua.lua board=mbed -E src/main.c +$ lua build_elua.lua board=mbed -S src/main.c --------------------------------------------- Generate the assembler source file for src/main.c, using 'mbed' as the target board. diff --git a/doc/en/configurator.txt b/doc/en/configurator.txt new file mode 100644 index 00000000..d311a2fb --- /dev/null +++ b/doc/en/configurator.txt @@ -0,0 +1,251 @@ +// $$HEADER$$ +The eLua configurator +--------------------- +*(new in 0.10)* The configurator is used to configure your eLua image by specifying the various modules and components that will be part of the eLua firmware image, +as well as their specific parameters. It replaces the old configuration mechanism (based on editing platform_conf.h files) with a number of improvements: + +* the configuration is specified using Lua files, with a simple to understand syntax +* configuration consistency checks are build in the configurator +* better module selection system +* easier customization + +The configurator works by reading a Lua based board configuration file and generating the corresponding C header file (which for the most part has the same role +as the platform_conf.h file that was used before the configurator). The board name is given by the _board_ argument to build_elua (see link:building.html#buildoptions[this link] +for more details about building your eLua image). The configurator looks for a file named _.lua_ in two locations: + +* *boards/known* is searched first. It contains the configuration of the boards on which eLua is known to run properly. The files under this directory are part of + the eLua source tree. +* *boards/custom* is searched if _.lua_ is not found in _boards/known_. The files under this directory are not part of the eLua source tree, so this is the place + where you can add configuration files for your custom board or customize the configuration for one of the standard boards (see link:#changecustom[here] for more details + about this). + +After finding _.lua_ in one of these locations, the configurator runs and generates the corresponding header file in __boards/headers/board_.h__. The files +under _boards/headers_ are also not part of the eLua source tree, so they can be edited manually if needed (see link:#manualedit[here] for more details). After this, the +configurator is done and the build process continues with the usual steps (compiling and linking the source files). + +[[config_overview]] +Configuring the build +~~~~~~~~~~~~~~~~~~~~~ +The build is configured using a Lua file. The Lua file contains code that must return the board configuration as a regular Lua table. An example for the +_mbed board is given below: + +[source,lua] +----------------------------------------------------------- +-- MBED build configuration + +return { + cpu = 'lpc1768', + components = { + sercon = { uart = 0, speed = 115200 }, + romfs = true, + shell = true, + term = { lines = 25, cols = 80 }, + linenoise = { shell_lines = 10, lua_lines = 50 }, + rpc = { uart = 0, speed = 115200 }, + adc = { buf_size = 4, first_timer = 0, num_timers = 4 }, + xmodem = true, + lpc17xx_semifs = true + }, + config = { + egc = { mode = "alloc" }, + ram = { internal_rams = 2 } + }, + modules = { + generic = { 'all', "-spi", "-can", "-i2c", "-net" }, + platform = 'all', + } +} +----------------------------------------------------------- + +As can be seen, a configuration for a board contains a number of sections: + +* **cpu**: the CPU of the board +* **components**: the components and their configuration +* **config**: other configuration items +* **modules**: list of Lua modules that will be part of the build + +The next section will explain each of the above items (and some that are not present in the above _mbed configuration file) in detail. Please keep in mind that the best way to understand +the configurator (besides reading this document) is to look at the existing configurations in *board/known*. + +[[config_cpu]] +Configuring the CPU +~~~~~~~~~~~~~~~~~~~ +The CPU is given by the *cpu* key in the configuration table. The CPU must be already known to the build system. A list of the known CPUs can be found in the *build_data.lua* file in the +__platform_list__ table. + +[[config_components]] +Configuring the components +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The various components that will be part of the eLua firmware image are given as a table under the *components* section in the main configurator table. The list of components known to the configurator, +as well as their configuration parameters are listed in the table below. Some parameters have default values; if this is the case, the default values are written in *bold*. Also, some parameters are +required, others are optional. Optional parameters are written over a [grey-background]#grey background#. All the required timer ID attributes that are not specified in the configuration default to the +link:arch_platform_timers.html#the_system_timer[system timer ID]. + +.Generic components +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +|romfs |None (true or false) |Enable the link:arch_romfs.html[ROMFS] file system +|wofs |None (true or false) |Enable the link:arch_wofs.html[WOFS] file system +|shell |None (true or false) |Enable link:simple_shell.html[the simple shell] +|advanced_shell |None (true or false) |Enable link:advanced_shell.html[the advanced shell] +.6+^.^|sercon 2+|*link:using.html#uart[Serial console] (console over UART)* + |uart |Serial console UART ID + |speed |Serial port speed + n|timer (*systimer*) |ID of the timer used by the serial console subsystem + n|flow (*none*,rts,cts,rtscts) |Flow control on the console UART + n|buf_size |Buffer size of the console UART. Must be a power of 2. +.6+^.^|xmodem 2+|*link:simple_shell.html#cmd_recv[XMODEM support]* + |uart |XMODEM UART ID (*same as sercon.uart*) + |speed |XMODEM UART speed (*same as sercon.speed*) + n|timer (*systimer*) |XMODEM timer ID (*same as sercon.timer*) + n|flow (*none*,rts,cts,rtscts) |Flow control on the XMODEM UART (*same as sercon.flow*) + n|buf_size |Buffer size of the XMODEM UART (*same as sercon.buf_size*) +.8+^.^|term 2+|*link:arch_con_term.html[ANSI terminal support]* + |uart |Term UART ID (*same as sercon.uart*) + |speed |Term UART speed (*same as sercon.speed*) + n|timer (*systimer*) |Term timer ID (*same as sercon.timer*) + n|flow (*none*,rts,cts,rtscts) |Flow control on the term UART (*same as sercon.flow*) + n|buf_size |Buffer size of the term UART (*same as sercon.buf_size*) + |lines |Number of lines in the terminal + |cols |Number of columns in the terminal +|cints |None (true or false) |Enable support for link:inthandlers.html[eLua generic interrupts] in C +.2+^.^|luaints 2+|*Enable support for link:inthandlers.html[eLua generic interrupts] in Lua* + n|queue_size (*32*) |Size of Lua interrupt queue. Must be a power of 2. +.5+^.^|tcip 2+|*link:arch_tcpip.html[TCP/IP support]* + |ip |IP of the board (for static IP configuration) + |netmask |Network mask (for static IP configuration) + |gw |Default gateway (for static IP configuration) + |dns |Name server address (for static IP configuration) +|dns |None (true or false) |DNS resolver support +|dhcp |None (true or false) |Enable the DHCP client (dynamic IP configuration) +|tcpipcon |None (true or false) |Enable the link:arch_using.html#tcpip[telnet client] +.4+^.^|linenoise 2+|*link:linenoise.html[Lua and command line history]* + |shell_lines |Number of lines from shell kept in history + |lua_lines |Number of lines from Lua kept in history + n|autosave_file |After the Lua shell exits, the Lua history buffer will be automatically saved in the file with this name +.7+^.^|rfs 2+|*Enable the link:arch_rfs.html[remote file system].* + |uart |RFS UART ID + |speed |RFS UART speed + n|timer (*systimer*) |ID of the timer used by the RFS implementation + n|flow (*none*,rts,cts,rtscts) |Flow control on the RFS UART + |buf_size |Buffer size of the RFS UART. Must be a power of 2. + n|timeout (usecs,*100000*) |Timeout for RFS operations +.4+^.^|mmcfs 2+|*Enable the link:arch_fatfs.html[MMC file system].* + |spi |ID of the SPI interface used by the SD card + |cs_port |Port number of the SD card /CS line + |cs_pin |Pin number of the SD card /CS line +.4+^.^|rpc 2+|*Enable the link:using.html#rpc[remote procedure call] subsystem.* The parameters are only required when booting in RPC server mode. + |uart |RPC UART ID + |speed |RPC UART speed + n|timer (*systimer*) |ID of the timer used by the RPC implementation +.5+^.^|sermux 2+|*Enable the link:sermux.html[serial multiplexer]* + |uart |ID of the serial multiplexer physical UART + |speed |Speed of the serial multiplexer physical UART + |flow |Flow control on the serial multiplexer physical UART + |buf_sizes (array) |Buffer sizes for virtual UARTs. Each size must be a power of 2. +.2+^.^|adc 2+|*Enable link:refman_gen_adc.html[ADC] support in eLua* + n|buf_size |ADC sample buffer size. Must be a power of 2. +|=================================================================== + +As can be seen in the table above, some of the parameters are common to more than one component. For example, *CON_UART_ID* is shared between +*sercon*, *xmodem* and *term*. It is enough to define a shared attribute only once (in one of the components). For example: + +[source,lua] +------------------------------------- +sercon = { uart = 0, speed = 115200 } +term = { lines = 25, cols = 80 } +xmodem = true +------------------------------------- + +If you were to redefine a shared attribute to a different value: + +[source,lua] +------------------------------------- +sercon = { uart = 0, speed = 115200 } +term = { lines = 25, cols = 80, uart = 1 } +xmodem = true +------------------------------------- + +you'd get a warning from the configurator: + +---------------------------------- +[CONFIG] WARNING: overriding value of attribute 'uart' in element 'term' from '0' to '1' in section 'components' +---------------------------------- + +Besides the generic components in the table above, each platform can specify its own list of platform-specific components: + +.LM3S specific components +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +|cdc |None (true or false) |Enable UART over CDC (USB to serial) +|lm3s_pio |None (true or false) |Enable the LM3S platform specific PIO support +|lm3s_disp |None (true or false) |Enable support for the LCD display on _EK-LM3S1968, _EK-LM3S6965 or _EK-LM3S8962 +|=================================================================== + +.STM32 specific components +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +|stm32_enc |None (true or false) |Enable support for the STM32 timer encoder module +|=================================================================== + +.LPC17xx specific components +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +|lpc17xx_semifs |None (true or false) |Enable support for the semifs file system (_mbed only) +|=================================================================== + +.AVR32 specific components +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +|cdc |None (true or false) |Enable UART over CDC (USB to serial) +|avr32_rtc |None (true or false) |Enable the AVR32 platform specific RTC module +|avr32_lcd |None (true or false) |Enable the AVR32 character display module (_Mizar32) +|=================================================================== + +[[config_config]] +Configuration data +~~~~~~~~~~~~~~~~~~ +The *config* section contains various build time configuration data. The list of the known configuration data items, as well as their parameters are listed in the table below. +Some parameters have default values; if this is the case, the default values are written in *bold*. Also, some parameters are required, others are optional. Optional parameters +are written over a [grey-background]#grey background#. + +.Generic configuration data +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +.3+^.^|vtmr 2+|*Enable support for link:arch_platform_timers.html#virtual_timers[virtual timers]* + |num (*0*) |Number of virtual timers + |freq (Hz, *1*) |Virtual timer frequency +.3+^.^|egc 2+|Configure the link:elua_egc.html[emergency garbage collector] + |mode (*disable*, alloc, limit, always) |EGC activation mode + |limit (bytes) |EGC activation memory limit +.4+^.^|ram 2+|Memory allocator configuration (RAM data) + n|internal_rams (*1*) |Number of MCU non-contiguous RAM areas + n|ext_start (array of integers) |Array of starting addresses for external RAM areas + n|ext_size (array of integers) |Array of sizes sof external RAM areas +|=================================================================== + +Besides the generic configuration items in the table above, each platform can specify its own list of platform-specific configuration items: + +.LM3S specific configuration data +[width="99%", cols="<3,<5,<10", options="header"] +|=================================================================== +^|Key ^|Parameters ^|Meaning +.3+^.^|lm3s_adc_timers 2+|Timer configuration for the link:refman_gen_adc.html[ADC subsystem]. + |first_timer (*0*) |ID of the first timer used by the ADC subsystem + |num_timers (*NUM_TIMER*) |Total number of timers used by the ADC subsystem +|=================================================================== + +TODO: manualedit + +TODO: changecustom + +TODO: add support for multiple SD cards (as in master) + +// $$FOOTER$$ + diff --git a/doc/en/using.txt b/doc/en/using.txt index 79aadf1d..67b98b7a 100644 --- a/doc/en/using.txt +++ b/doc/en/using.txt @@ -58,7 +58,7 @@ The eLua shell -------------- No matter what's your physical connection (serial, TCP/IP or you PC's monitor after booting eLua), after you setup the PC-eLua board connection and press the "RESET" button on your board or simply press ENTER if you're using the serial connection, -you should see the eLua< shell prompt (if you enabled the shell in your build, as described link:building.html[here]). The shell +you should see the eLua shell prompt (if you enabled the shell in your build, as described link:building.html[here]). The shell is a simple interactive command interpreter that allows you to: - get help on shell usage with the help command, diff --git a/src/platform/lm3s/build_config.lua b/src/platform/lm3s/build_config.lua index d1111275..11438dab 100644 --- a/src/platform/lm3s/build_config.lua +++ b/src/platform/lm3s/build_config.lua @@ -3,6 +3,7 @@ module( ..., package.seeall ) local comps = require "components" +local at = require "attributes" -- Add specific components to the 'components' table function add_platform_components( t, board, cpu ) @@ -16,6 +17,13 @@ end -- Add specific configuration to the 'configs' table function add_platform_configs( t, board, cpu ) + t.lm3s_adc_timers = { + attrs = { + first_timer = at.int_attr( 'ADC_TIMER_FIRST_ID', 0 ), + num_timers = at.int_attr( 'ADC_NUM_TIMERS', 0 ) + }, + required = { first_timer = 0, num_timers = "NUM_TIMER" } + } end -- Return an array of all the available platform modules for the given cpu