Syslinux LUA User Guide
=======================
Marcel Ritter <Marcel.Ritter@rrze.uni-erlangen.de>

Invocation
----------

Running +lua.c32+ only results in an interactive shell.
......................................................
KERNEL lua.c32
......................................................

By using the +APPEND+ parameter you can specify a lua
script to be executed:
......................................................
KERNEL lua.c32
APPEND /testit.lua
......................................................

Modules
-------

Modules must be explicitly loaded into the namespace
before use, for example:
......................................................
local sl = require "syslinux"
......................................................
Using +local+, as above, is good practice in scripts, but it must be
omitted when working interactively.

SYSLINUX
~~~~~~~~

version()::
Return the Syslinux version string.

derivative()::
Return the running Syslinux derivative
(the string +ISOLINUX+, +PXELINUX+ or +SYSLINUX+).

sleep(s)::
Sleep for +s+ seconds.

msleep(ms)::
Sleep for +ms+ milliseconds.

run_command(command)::
Execute syslinux command line +command+.
+
_Example_:
......................................................
local sl = require "syslinux"
sl.run_command "memdisk initrd=/dos/BIOS/FSC-P7935-108.img raw"
......................................................

run_default()::
Execute the default command in the configuration.

local_boot(type)::
Do a local boot. The +type+ values are described in the documentation
of the LOCALBOOT configuration item.

final_cleanup(flags)::
Restore sane hardware and software status before booting.  If +flags+
is 3, keep the PXE and UNDI stacks in memory (see the _keeppxe_ option).
Only needed in special circumstances.

boot_linux(kernel[,cmdline])::
Load and boot the Linux kernel at path +kernel+.  Initramfs images are
loaded according to the +initrd+ option in +cmdline+.  The
+BOOT_IMAGE+ parameter is added to the command line with the value of
+kernel+.

IMAGE_TYPE::
A table mapping the various kernel type strings to the integer +type+
parameter of +run_kernel_image()+.

run_kernel_image(kernel, cmdline, ipappend_flags, type)::
Load the specified +kernel+ and run it with +cmdline+.  See also the
documentation of the IPAPPEND configuration item; +type+ is one of
the values of the +IMAGE_TYPE+ table.

loadfile(filename)::
Return a _file_ object with the contents of file +filename+ loaded.
Its methods are:

size():::
Return the size of a loaded _file_.

name():::
Return the name of a loaded _file_.

initramfs()::
Return an empty _initramfs_ object.  Its methods are:

load(filename):::
Load contents of +filename+ into an _initramfs_ and return the
extended object.

add_file(filename[,data[,do_mkdir[,mode]]]):::
Add +filename+ of +mode+ containing +data+ to an _initramfs_ and
return the extended object.
If +do_mkdir+, create parent directories, too.  +mode+ defaults
to 7*64+5*8+5 (which is 0755 in octal).

size():::
Returns the current size of an _initramfs_.

boot_it(kernel[,initramfs,[cmdline]])::
Boot the loaded +kernel+ (a _file_ object) with an optional
+initramfs+ (an _initramfs_ object or +nil+) and +cmdline+.

_Example_:
......................................................
local sl = require "syslinux"

kernel = sl.loadfile "/SuSE-11.1/x86_64/linux"
print("File name: " .. kernel:name() .. " size: " .. kernel:size())

initrd1 = "/SuSE-11.1/x86_64/initrd"

initrd = sl.initramfs()
initrd:load(initrd1)
print ("File name: " .. initrd1 .. " size: " .. initrd:size())

sl.boot_it(kernel, initrd, "init=/bin/bash")
......................................................

KEY::
Table containing the return values of +get_key()+ for special (eg. function)
keys.

KEY_CTRL(key)::
Return the code for the Ctrl-modified version of the given ASCII code.

get_key(timeout)::
Wait at most +timeout+ ms for a key press.
Return the ASCII code of the pressed key, some other value of the +KEY+
table, or +KEY.NONE+ on timeout.

config_file()::
Return the path of the current config file.

ipappend_strs()::
Return the table of SYSAPPEND (formerly IPAPPEND) strings.  See also
the documentation of those configuration items.

reboot([warm_boot])::
Reboot.  If +warm_boot+ is nonzero, perform a warm reboot.


DMI
~~~

supported()::
Return true if DMI is supported on machine, false otherwise.

gettable()::
Return DMI info as a nested table.

_Example_:
......................................................
local sl = require "syslinux"
local dmi = require "dmi"

if (dmi.supported()) then

  dmitable = dmi.gettable()

  for k,v in pairs(dmitable) do
    print(k, v)
  end

  print(dmitable.system.manufacturer)
  print(dmitable.system.product_name)
  print(dmitable.bios.bios_revision)

  if ( string.match(dmitable.system.product_name, "ESPRIMO P7935") ) then
    print("Matches")
    sl.run_command("memdisk initrd=/dos/BIOS/FSC-P7935-108.img raw")
  else
    print("Does not match")
    sl.run_command("memdisk initrd=/dos/BIOS/FSC-P7935-108.img raw")
  end

end
......................................................


PCI
~~~

getinfo()::
Return the table of all PCI devices, keyed by the device index.
Each device is described by a table of its properties.

getidlist(filename)::
Load a tab separated list of PCI IDs and their description. 
Sample files can be found here: http://pciids.sourceforge.net/

_Example_:
......................................................
local pci = require "pci"

pciids = pci.getidlist("/pci.ids")

for dind, device in pairs (pci.getinfo()) do
  local vendor = string.format ("%04x", device.vendor)
  local main_id = vendor .. string.format ("%04x", device.product)
  local sub_id =  string.format ("%04x%04x", device.sub_vendor, device.sub_product)
  io.write (string.format ("%s:%s = %s %s (%s)\n", main_id, sub_id, pciids[vendor],
                           pciids[main_id], pciids[main_id .. sub_id] or "unknown subdevice"))
end
......................................................


VESA
~~~~

getmodes()::
Return list of available VESA modes.
+
_Example_:
......................................................
local vesa = require "vesa"

for mind,mode in pairs(vesa.getmodes()) do
   print (string.format ("%04x: %dx%dx%d", mode.mode, mode.hres, mode.vres, mode.bpp))
end
......................................................

setmode()::
Set the 640x480 VESA mode.

load_background(filename)::
Load +filename+ (a PNG, JPEG or LSS-16 format image), and tile it as
background image.  The text already present is not erased.

_Example_:
......................................................
local sl = require "syslinux"
local vesa = require "vesa"

vesa.setmode()
vesa.load_background "sample2.jpg"

for c in string.gmatch ("Hello World! - VESA mode", ".") do
    io.write (c)
    sl.msleep(200)
end

vesa.load_background "PXE-RRZE_small.jpg"
sl.sleep(3)
......................................................