[SerialICE] Getting started with new SerialICE scripts

[Kyösti Mälkki]

Hello all SerialICE folks !


You may have noticed the new filter system Simba has been merged for
SerialICE. Written in LUA, as its predecessor, the new scripting system
has greatly improved in terms of the log readability.

I am sort of hoping someone of the few people recently playing around
with the updated SerialICE would give a helping hand here and coordinate
what to do with the existing documentation at serialice.org.
Also don't destroy your existing logs, I could probably use some more
nice sample runs.


This is a very very brief introduction, I hope this answers some of the
questions that have come up on #coreboot. Maybe SerialICE wiki is the
way to go? 


1. Target system setup

People have contributed some new boards but essentially nothing has
changed here. There is a menuconfig option to set the size of the Flash
chip you are going to use, this information wasn't on the website
"Getting Started" section.

You should try with picocom/minicom that your target responses with a
single SerialICE prompt. If you get many, there might be some watchdog
that repeatedly triggers reset on the target.


2. Host system setup

You need to build Qemu from the SerialICE git tree. Take note that LUA
library version >= 5.2 must be installed.

To run Qemu session on a 32bit host, you will need to build LUA from
source with the patches under serialice/SerialICE/patches applied.
The patch is to extend LUA's (signed) integer to 64bits, since we need
to handle addresses close to 2^32.

Fetch source... 

  ~$ git clone http://review.coreboot.org/p/serialice

and build:

  ~$ cd serialice/qemu-0.15.x
  ~serialice/qemu-0.15.x$ . ./build.sh

To contribute to project, same guidelines apply to SerialICE as to
coreboot.


3. Firing up SerialICE session

The commandline to invoke a SerialICE session should look something like
this:

  ~/serialice/qemu-0.15.x/i386-softmmu/qemu -machine serialice --serialice /dev/ttyUSB0 -L ./mb_vendor_bios/

You should then see the serialice output start rolling on your console.


4. The mainboard script

In contrary to the single-file filter script "serialice.lua" the new
filter implementation is split to several files under SerialICE/simba/.

This new file layout does not even try to be an all-in-one filter
supporting every existing mainboard --- you need to add a file that
describes the chipset on your target mainboard. This 'mainboard script'
file has a pre-defined name and you see it printed at the beginning of
the console output when SerialICE session is started.

A SerialICE session can run without a mainboard script file, but it can
decode only those IO operations that have "default" or "semi-standard"
locations in x86 architecture.

To get started, you could copy some of the existing mainboard files as
the basis for your setup. Further development besides selecting from the
already implemented chipset parts takes more in-depth understanding of
the filter setup.


5. Filter stack in brief

An IO/MEM operation will first match a filter that claims the particular
IO/MEM region. Active filters/regions are listed as RESOURCE lines in
the log. Writes to PCI config space BAR registers will activate new
RESOURCE entries.

A filter claiming the IO/MEM operation decides if the operation executes
on the real target hardware, the QEMU platform, or neither. A filter
optionally appends and/or removes lines in the output log. 

What is said about IO/MEM operations here also applies to CPUID,
RDMSR/WRMSR and PCI config space accesses.



Any comments are welcome. I'll continue with writing a tutorial that
should explain the filter anatomy and how it is supposed to work.

Regards,

Kyösti