Commit 4f21224d authored by TerryE's avatar TerryE
Browse files

LFS patch updates following review II and testing

parent 4f7af452
......@@ -150,15 +150,19 @@ flash ID (number)
Returns the function reference for a function in the LFS (Lua Flash Store).
#### Syntax
`node.flashindex()`
`node.flashindex(modulename)`
#### Parameters
`modulename` The name of the module to be loaded. If this is `nil` or invalid then an info list is returned
#### Returns
- In the case where the LFS in not loaded, `node.flashindex` evaluates to `nil`, followed by the flash and mapped base addresss of the LFS
- In the case where the LFS in not loaded, `node.flashindex` evaluates to `nil`, followed by the flash and mapped base addresss of the LFS
- If the LFS is loaded and the function is called with the name of a valid module in the LFS, then the function is returned in the same way the `load()` and the other Lua load functions do.
- Otherwise an extended info list is returned: the Unix time of the LFS build, the flash and mapped base addresses of the LFS and its current length, and an array of the valid module names in the LFS.
- Otherwise an extended info list is returned: the Unix time of the LFS build, the flash and mapped base addresses of the LFS and its current length, and an array of the valid module names in the LFS.
#### Example
The `node.flashindex()` is a low level API call that is normally wrapped using standard Lua code to present a simpler application API. See the module `_init.lua` in the `lua_examples/lfs` directory for an example of how to do this.
## node.flashreload()
......
......@@ -241,14 +241,17 @@ SECTIONS
KEEP(*(.lua_rotable))
LONG(0) LONG(0) /* Null-terminate the array */
/* SDK doesn't use libc functions, and are therefore safe to put in flash */
/* SDK doesn't use libc functions, and are therefore safe to put in flash */
*/libc.a:*.o(.text* .literal*)
/* end libc functions */
/* Reserved areas, flash page aligned and last */
. = ALIGN(4096);
KEEP(*(.irom.reserved .irom.reserved.*))
_irom0_text_end = ABSOLUTE(.);
_flash_used_end = ABSOLUTE(.);
} >irom0_0_seg :irom0_0_phdr =0xffffffff
}
/* get ROM code address */
......
--
-- File: _init.lua
--[[
This is a template for the LFS equivalent of the SPIFFS init.lua.
It is a good idea to such an _init.lua module to your LFS and do most of the LFS
module related initialisaion in this. This example uses standard Lua features to
simplify the LFS API.
The first section adds a 'LFS' table to _G and uses the __index metamethod to
resolve functions in the LFS, so you can execute the main function of module
'fred' by executing LFS.fred(params), etc. It also implements some standard
readonly properties:
LFS._time The Unix Timestamp when the luac.cross was executed. This can be
used as a version identifier.
LFS._config This returns a table of useful configuration parameters, hence
print (("0x%6x"):format(LFS._config.lfs_base))
gives you the parameter to use in the luac.cross -a option.
LFS._list This returns a table of the LFS modules, hence
print(table.concat(LFS._list),'\n')
gives you a single column listing of all modules in the LFS.
---------------------------------------------------------------------------------]]
local index = node.flashindex
local lfs_t = {
__index = function(_, name)
local fn_ut, ba, ma, size, modules = index(name)
if not ba then
return fn_ut
elseif name == '_time' then
return fn_ut
elseif name == '_config' then
local fs_ma, fs_size = file.fscfg()
return {lfs_base = ba, lfs_mapped = ma, lfs_size = size,
fs_mapped = fs_ma, fs_size = fs_size}
elseif name == '_list' then
return modules
else
return nil
end
end,
__newindex = function(_, name, value)
error("LFS is readonly. Invalid write to LFS." .. name, 2)
end,
}
local G=getfenv()
G.LFS = setmetatable(lfs_t,lfs_t)
--[[-------------------------------------------------------------------------------
The second section adds the LFS to the require searchlist, so that you can
require a Lua module 'jean' in the LFS by simply doing require "jean". However
note that this is at the search entry following the FS searcher, so if you also
have jean.lc or jean.lua in SPIFFS, then this SPIFFS version will get loaded into
RAM instead of using. (Useful, for development).
Note that if you want LFS to take a higher priority than SPIFFS, the use the [2]
slot for loaders. If you want to reverse these in your init.lua or interactively
for debugging, then use
do local pl = package.loaders; pl[2],pl[4] = pl[4],pl[2]; end
---------------------------------------------------------------------------------]]
package.loaders[4] = function(module) -- loader_flash
local fn, ba = index(module)
return ba and "Module not in LFS" or fn
end
--[[-------------------------------------------------------------------------------
You can add any other initialisation here, for example a couple of the globals
are never used, so setting them to nil saves a couple of global entries
---------------------------------------------------------------------------------]]
G.module = nil -- disable Lua 5.0 style modules to save RAM
package.seeall = nil
--
-- File: LFS_dummy_strings.lua
--[[
luac.cross -f generates a ROM string table which is part of the compiled LFS
image. This table includes all strings referenced in the loaded modules.
If you want to preload other string constants, then one way to achieve this is
to include a dummy module in the LFS that references the strings that you want
to load. You never need to call this module; it's inclusion in the LFS image is
enough to add the strings to the ROM table. Your application can use any strings
in the ROM table without incuring any RAM or Lua Garbage Collector (LGC)
overhead.
The local preload example is a useful starting point. However, if you call the
following code in your application during testing, then this will provide a
listing of the current RAM string table.
do
local a=debug.getstrings'RAM'
for i =1, #a do a[i] = ('%q'):format(a[i]) end
print ('local preload='..table.concat(a,','))
end
This will exclude any strings already in the ROM table, so the output is the list
of putative strings that you should consider adding to LFS ROM table.
---------------------------------------------------------------------------------]]
local preload = "?.lc;?.lua", "/\n;\n?\n!\n-", "@init.lua", "_G", "_LOADED",
"_LOADLIB", "__add", "__call", "__concat", "__div", "__eq", "__gc", "__index",
"__le", "__len", "__lt", "__mod", "__mode", "__mul", "__newindex", "__pow",
"__sub", "__tostring", "__unm", "collectgarbage", "cpath", "debug", "file",
"file.obj", "file.vol", "flash", "getstrings", "index", "ipairs", "list", "loaded",
"loader", "loaders", "loadlib", "module", "net.tcpserver", "net.tcpsocket",
"net.udpsocket", "newproxy", "package", "pairs", "path", "preload", "reload",
"require", "seeall", "wdclr", "not enough memory", "sjson.decoder","sjson.encoder",
"tmr.timer"
......@@ -4,8 +4,12 @@
-- image for the first time bare, that is without either LFS or SPIFFS preloaded
-- then enter the following commands interactively through the UART:
--
local _,mapa,fa=node.flashindex(); return ('0x%x, 0x%x, 0x%x'):format(
mapa,fa,file.fscfg())
do
local _,ma,fa=node.flashindex()
for n,v in pairs{LFS_MAPPED=ma, LFS_BASE=fa, SPIFFS_BASE=sa} do
print(('export %s=""0x%x"'):format(n, v)
end
end
--
-- This will print out 3 hex constants: the absolute address used in the
-- 'luac.cross -a' options and the flash adresses of the LFS and SPIFFS.
......@@ -33,37 +37,6 @@ $ESPTOOL --port $USB --baud 460800 write_flash -fm dio 0x100000 \
# and now you are good to go
]]
-----------------------------------------------------------------------------------
--
-- It is a good idea to add an _init.lua module to your LFS and do most of the
-- LFS module related initialisaion in this. This example uses standard Lua
-- features to simplify the LFS API.
--
-- The first adds a 'LFS' table to _G and uses the __index metamethod to resolve
-- functions in the LFS, so you can execute the main function of module 'fred'
-- by doing LFS.fred(params)
--
-- The second adds the LFS to the require searchlist so that you can require a
-- Lua module 'jean' in the LFS by simply doing require "jean". However not that
-- this is at the search entry following the FS searcher, so if you also have
-- jean.lc or jean.lua in SPIFFS, then this will get preferentially loaded,
-- albeit into RAM. (Useful, for development).
--
do
local index = node.flashindex
local lfs_t = { __index = function(_, name)
local fn, ba = index(name)
if not ba then return fn end -- or return nil implied
end}
getfenv().LFS = setmetatable(lfs_t,lfs_t)
local function loader_flash(module)
local fn, ba = index(module)
return ba and "Module not in LFS" or fn
end
package.loaders[3] = loader_flash
end
-----------------------------------------------------------------------------------
--
......@@ -73,8 +46,9 @@ end
-- module in LFS. Here is an example. It's a good idea either to use a timer
-- delay or a GPIO pin during development, so that you as developer can break into
-- the boot sequence if there is a problem with the _init bootstrap that is causing
-- a panic loop. Here is one example of how you might do this. You have a second to
-- a panic loop. Here is one example of how you might do this. You have a second
-- to inject tmr.stop(0) into UART0. Extend this dealy if your reactions can't
-- meet this.
--
-- You also want to do autoload the LFS, for example by adding the following:
--
......@@ -87,38 +61,3 @@ tmr.alarm(0, 1000, tmr.ALARM_SINGLE,
local fi=node.flashindex; return pcall(fi and fi'_init')
end)
-----------------------------------------------------------------------------------
--
-- The debug.getstrings function can be used to get a listing of the RAM (or ROM
-- if LFS is loaded), as per the following example, so you can do this at the
-- interactive prompt or call it as a debug function during a running application.
--
do
local a=debug.getstrings'RAM'
for i =1, #a do a[i] = ('%q'):format(a[i]) end
print ('local preload='..table.concat(a,','))
end
-----------------------------------------------------------------------------------
--
-- File: LFS_dummy_strings.lua
--
-- luac.cross -f will generate a ROM string table that includes all strings
-- referenced in the loaded modules. If you want to preload other string constants
-- hen the trick is to include a dummy module in the LFS. You never need to call
-- this. It's inclusion is enough to add the strings to the ROM table. Once in
-- the ROM table, then you can use them in your application without incuring any
-- RAM or Lua Garbage Collector (LGC) overhead. Here is a useful starting point,
-- but you can add to this for your application.
--
-- The trick is to build the LFS as normal then run the previous example from your
-- running application and append these lines to this file.
--
local preload = "?.lc;?.lua", "@init.lua", "_G", "_LOADED", "_LOADLIB", "__add",
"__call", "__concat", "__div", "__eq", "__gc", "__index", "__le", "__len", "__lt",
"__mod", "__mode", "__mul", "__newindex", "__pow", "__sub", "__tostring", "__unm",
"collectgarbage", "cpath", "debug", "file", "file.obj", "file.vol", "flash",
"getstrings", "index", "ipairs", "list", "loaded", "loader", "loaders", "loadlib",
"module", "net.tcpserver", "net.tcpsocket", "net.udpsocket", "newproxy", "package",
"pairs", "path", "preload", "reload", "require", "seeall", "wdclr"
......@@ -24,13 +24,16 @@ pages:
- Home: 'en/index.md'
- Building the firmware: 'en/build.md'
- Flashing the firmware: 'en/flash.md'
- Internal filesystem notes: 'en/spiffs.md'
- Filesystem on SD card: 'en/sdcard.md'
- Uploading code: 'en/upload.md'
- FAQs:
- Lua Developer FAQ: 'en/lua-developer-faq.md'
- Extension Developer FAQ: 'en/extn-developer-faq.md'
- Hardware FAQ: 'en/hardware-faq.md'
- Whitepapers:
- Filesystem on SD card: 'en/sdcard.md'
- Internal filesystem notes: 'en/spiffs.md'
- Lua Compact Debug(LCD): 'en/lfs.md'
- Lua Flash Store(LFS): 'en/lcd.md'
- Support: 'en/support.md'
- Modules:
- 'adc': 'en/modules/adc.md'
......
......@@ -61,7 +61,7 @@ spiffsimg: spiffsimg/spiffsimg
@echo Built spiffsimg in spiffsimg/spiffsimg
spiffsimg/spiffsimg:
@$(MAKE) -C spiffsimg CC=$(HOSTCC)
@$(MAKE) -C spiffsimg
spiffsscript: remove-image LFSimage spiffsimg/spiffsimg
rm -f ./spiffsimg/spiffs.lst
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment