Using lua script

[Morten Bruun]

Hi,

I have been writing a small Lua script to be run before updating with a .swu file. The page here https://sbabic.github.io/swupdate/swupdate-best-practise.html has the following phrase, but I cannot find any documentation of what functions/methods I can call on the swupdate object:

See SWUpdate documentation for a complete list of functions exported by SWUpdate that can be used in Lua. An embedded Lua script must just start with

require ('swupdate')

to make use of them.

Do anyone know where to find this documentaion?

Kind regards Morten 

[Stefano Babic]

Hi Morten,

On 17.11.23 12:49, Morten Bruun wrote:
> Hi,
>
> I have been writing a small Lua script to be run before updating with a
> .swu file. The page
> here https://sbabic.github.io/swupdate/swupdate-best-practise.html has
> the following phrase, but I cannot find any documentation of what
> functions/methods I can call on the swupdate object:
>

The poage shows the good will of the maintainer to write this
documentation, but this was rather not yet done.

> See SWUpdate documentation for a complete list of functions exported by
> SWUpdate that can be used in Lua. An embedded Lua script must just start
> with
>
> require ('swupdate')
>
> to make use of them.
>
> Do anyone know where to find this documentaion?
>

There is not yet done. Function can be foiund into the lua_interface.c file.

Best regards,
Stefano Babic

[Storm, Christian]

Hi,

>> I have been writing a small Lua script to be run before updating with a .swu file. The page here https://sbabic.github.io/swupdate/swupdate-best-practise.html has the following phrase, but I cannot find any documentation of what functions/methods I can call on the swupdate object:
>
> The poage shows the good will of the maintainer to write this documentation, but this was rather not yet done.
>
>> See SWUpdate documentation for a complete list of functions exported by SWUpdate that can be used in Lua. An embedded Lua script must just start with
>> require ('swupdate')
>> to make use of them.
>> Do anyone know where to find this documentaion?

The superset (swupdate module for handlers) is specified in handlers/swupdate.lua.
So, this ― minus stuff you need for writing handlers in Lua ― gives you what's exposed by SWUpdate to the Lua realm for your use case I guess. It's actually Lua code with EmmyLua (or rather Lua LSP) annotations that you can directly code against or use in completion or whatever...

> There is not yet done. Function can be foiund into the lua_interface.c file.

Good point, maybe we should split handlers/swupdate.lua into a "generic" Lua swupdate module (as used in sw-description) and a specific one for handlers that extends this generic module....



Kind regards,
Christian

--
Dr. Christian Storm
Siemens AG, Technology, T CED SES-DE
Otto-Hahn-Ring 6, 81739 Munich, Germany

[Morten Bruun]

Thanks a lot, I found the functions in lua_interface.c and also dumped the functions and data from my script:

{
["ROOT_DEVICE"] = { ["PARTLABEL"] = 3.0, ["UUID"] = 1.0, ["PATH"] = 0.0, ["PARTUUID"] = 2.0,} ,
["RECOVERY_STATUS"] = { ["IDLE"] = 0.0,["SUBPROCESS"] = 7.0,["FAILURE"] = 4.0,["DONE"] = 6.0,["PROGRESS"] = 8.0,["DOWNLOAD"] = 5.0,["START"] = 1.0,["SUCCESS"] = 3.0,["RUN"] = 2.0,} ,

["getversion"] = function: 0x491825,
["progress"] = function: 0x4b22bb,
["mount"] = function: 0x491c59,
["getroot"] = function: 0x4919e9,
["umount"] = function: 0x491b4d,
["trace"] = function: 0x4b236b,
["debug"] = function: 0x4b2383,
["warn"] = function: 0x4b237d,
["error"] = function: 0x4b2371,
["notify"] = function: 0x4b230f,
["info"] = function: 0x4b2377,
}

Thanks again!

Morten

[Stefano Babic]

Hi Christian,

I am asking myself if it makes a lot of sense to have a hard split
between Lua handlers and generic Lua code (Lua scripts or embedded Lua
in sw-description). I have already dropped "CONFIG_LUA_HANDLERS. Frankly
speaking, it adds some hurdles without addinf benefits. There is no
changes in dependencies or footprint if CONFIG_LUA is set and
CONFIG_LUA_HANDLERS not, and it forbids to add in future a Lua handler
if the switch was not yet on, for example on the SWUpdate version
running in field.

Doing this, I am also thinking about some extension and changes on how
Lua code is evaluated. Currently, there is a global Lua context (for
handlers), and a specific Lua context for each code snippet. That is,
for a script, a Lua context is created before the script is started and
destroyed after its completion.

I am thinking about if it is not much better to have a Lua context for
install request: the context is instantiated when parser runs and
destroyed when the install (with success or failure) completes. Even if
having a Lua context for each script reduces dependencies, having a Lua
context for install request allows some more fancy stuff, like calling
from a later script a function defined previously (in embedded-script or
in a previous loaded code). It could be also extended to add runtime
hooks (we have just hooks at parsing time), and also a "failure-hook" in
case the install of a single artifact fails and some housekeeping should
be done. What do you mind ? Does it make sense in your opinion ?

Best regards,
Stefano

[Storm, Christian]

Hi Stefano,

>>>> I have been writing a small Lua script to be run before updating with a .swu file. The page here https://sbabic.github.io/swupdate/swupdate-best-practise.html has the following phrase, but I cannot find any documentation of what functions/methods I can call on the swupdate object:
>>>
>>> The poage shows the good will of the maintainer to write this documentation, but this was rather not yet done.
>>>
>>>> See SWUpdate documentation for a complete list of functions exported by SWUpdate that can be used in Lua. An embedded Lua script must just start with
>>>> require ('swupdate')
>>>> to make use of them.
>>>> Do anyone know where to find this documentaion?
>> The superset (swupdate module for handlers) is specified in handlers/swupdate.lua.
>> So, this ― minus stuff you need for writing handlers in Lua ― gives you what's exposed by SWUpdate to the Lua realm for your use case I guess. It's actually Lua code with EmmyLua (or rather Lua LSP) annotations that you can directly code against or use in completion or whatever...
>>> There is not yet done. Function can be foiund into the lua_interface.c file.
>> Good point, maybe we should split handlers/swupdate.lua into a "generic" Lua swupdate module (as used in sw-description) and a specific one for handlers that extends this generic module....
>
> I am asking myself if it makes a lot of sense to have a hard split between Lua handlers and generic Lua code (Lua scripts or embedded Lua in sw-description). I have already dropped "CONFIG_LUA_HANDLERS. Frankly speaking, it adds some hurdles without addinf benefits. There is no changes in dependencies or footprint if CONFIG_LUA is set and CONFIG_LUA_HANDLERS not, and it forbids to add in future a Lua handler if the switch was not yet on, for example on the SWUpdate version running in field.

That's true. The reason back then I guess was that, e.g., embedded Lua scripts shouldn't have some functionality available that Lua handler implementations need. This can be overcome and implemented in one Lua state if you "prime" it prior to executing a Lua chunk: Set a global (hidden) variable in the Lua state which is read-only and hardly visible from within Lua. Then, check on each function exposed to the Lua realm if that function is eligible in this context, i.e., the global read-only variable has the right value.

> Doing this, I am also thinking about some extension and changes on how Lua code is evaluated. Currently, there is a global Lua context (for handlers), and a specific Lua context for each code snippet. That is, for a script, a Lua context is created before the script is started and destroyed after its completion.
>
> I am thinking about if it is not much better to have a Lua context for install request: the context is instantiated when parser runs and destroyed when the install (with success or failure) completes. Even if having a Lua context for each script reduces dependencies, having a Lua context for install request allows some more fancy stuff, like calling from a later script a function defined previously (in embedded-script or in a previous loaded code). It could be also extended to add runtime hooks (we have just hooks at parsing time), and also a "failure-hook" in case the install of a single artifact fails and some housekeeping should be done. What do you mind ? Does it make sense in your opinion ?

That absolutely makes sense! We then do have separate Lua states: handlers, suricatta/lua, and one per installation transaction. This makes sense for isolation so to not leak or interfere with others.
But for one installation transaction, a single Lua stack that convoys with the installation definitely has its benefits that IMO outweigh the isolation benefit.