OpenCellular/scripts/newbitmaps/README

This directory contains the sources for the new-style BIOS bitmaps, and a
simple (and ugly) tool to view the configuration file that describes how
each screen is displayed.

Note:

Due to continuing improvements and tweaks, there have been several different
formats used for the BIOS bitmaps.

Because the bitmap images and display code is part of the Read-Only BIOS,
back-porting any new bitmaps to older devices is not possible.


Old-style, unversioned bitmaps. Used in Mario / Cr-48.

In the Cr-48 BIOS there are four BIOS screens that may be presented to the
user. Each contains a graphic, a URL, and some informative text. The screens
are single bitmap images, hardcoded in read-only BIOS (because they have to
display even when the R/W BIOS and SSD are both completely erased). They can
be replaced at manufacturing time, but creating the screens is difficult.
The format is a compressed EFI firmware volume that is generated when the
BIOS is compiled. The result is an opaque blob that cannot be viewed or
edited with linux-based tools.


Version 1.0, new-style bitmaps. Used in Alex / Samsung Series 5.

The BIOS continues to display the same basic screens, but it uses a
different format internally (which we call the bmpblock). Each screen has
separate bitmaps for the basic graphic, the URL, and the informative text,
and the screen is displayed by rendering each component in order. This
allows us to modify and replace any bitmap (most frequently the HWID), using
standard command-line linux tools such as imagemagick. Compositing each
screen in this way also means that we can easily provide localized BIOS
screens or custom messages. The BIOS rotates through the localizations by
pressing the arrow keys when any screen is displayed.


Version 1.1. Used in ZGB / Acer AC700.

This is essentially the same as version 1.0, except that the ASCII HWID
string can be rendered directly by the BIOS instead of as a bitmap. In the
screen description, the magic image name "$HWID" (or "$HWID.rtol" for a
right-justified placement) indicates that the ASCII HWID value should be
displayed at the given coordinates instead of a bitmap image. This means
that we only need to generate one bmpblock for all locales, since the ASCII
HWID string can be changed at the factory using "gbb_utility". The
last-displayed locale is stored in nvram, so it's sticky across reboots. The
factory process sets the default locale to the appropriate region.


Version 1.2. Used by any BIOS that uses "vboot_api.h"

The "vboot wrapper" is a refactoring of the vboot_reference library to
isolate our verified boot stuff from the underlying BIOS. Among other
things, it places the burden of displaying the ASCII HWID value on the
vboot_reference library, which means the bmpblock must contain a "font" to
translate the ASCII characters in the HWID into graphical images. The yaml
file must now specify a font file for the $HWID (and $HWID.rtol, if used)
image name. For example:

  bmpblock: 1.2
  images:
    $HWID: font.bin            # THIS IS NOW REQUIRED WHEN USING $HWID
  screens:
    scr_0_0:
     - [ 0, 0, $HWID]
  localizations:
    - [ scr_0_0, scr_0_0, scr_0_0, scr_0_0 ]
  locale_index:
    en

The old v1.1 bmpblock will be accepted by the vboot wrapper, but a $HWID
screen without a corresponding font will be silently ignored.



Instructions:

The bmpblk_utility reads a config file and produces a binary bmpblock. The
config file lists the individual bitmaps and describes where to place each
one when displaying each screen. The bmpblock is then written into the BIOS
image with the gbb_utility. The bitmap_viewer program lets you view the
composited screens as described by the config file.

* First, get the bitmap_viewer working. This is best done OUTSIDE of the
  chroot. Test it by changing to the scripts/newbitmaps/images/16x9_generic
  directory and running "../../bitmap_viewer DEFAULT.yaml". You may
  need to install some additional packages. For example, on Ubuntu you'll
  probably need to install the "python-yaml" and "python-wxgtk2.8" packages.

* Now make changes to the DEFAULT.yaml config file, and use bitmap_viewer to
  see how the layout looks. Hit Ctrl-R in the small window to reload the
  config file without restarting.

* The bitmap_viewer tool can display images in several different formats,
  but the BIOS is very limited (and may differ between x86 and ARM). For
  x86, ensure that you're using the proper format by converting any new
  bitmaps with a command like this:

    convert IN.bmp -colors 256 -compress none -alpha off OUT.bmp

* When you have the screens tweaked to your satisfaction, generate the
  binary bmpblock to embed into the BIOS.

    bmpblk_utility -c DEFAULT.yaml bmpblock.bin

* Use the gbb_utility to modify the BIOS to contain this new set of bitmaps.

  NOTE: These commands are run (as root) on the device under test!

  NOTE: This will only work if the BIOS write-protection is disabled!

  Copy our new bmpblock over.

    cd /mnt/stateful_partition
    scp USER@SOMEHOST:/SOMEPATH/bmpblock.bin .

  Get a copy of the current BIOS.

    flashrom -p internal:bus=spi -r bios.bin

  Put the new bmpblock in the copy of the BIOS

    gbb_utility -s -b bmpblock.bin bios.bin

  Reflash the BIOS with the new content

    flashrom -p internal:bus=spi -w bios.bin

* Reboot. You should see your new bitmaps appear whenever the BIOS screens
  are displayed. If you have more than one localization, you should be able
  to cycle among them with the arrow keys.

* If you want to examine a binary bmpblock that you've pulled from a BIOS
  image, the bmpblk_utility has options to display or unpack the binary.

    bmpblk_utility bmpblock.bin

    bmpblk_utility -y bmpblock.bin

    bmpblk_utility -x -d /SOME/SCRATCH/DIR bmpblock.bin

 Once you've unpacked it you can use the bitmap_viewer on the unpacked yaml
 file to see what it looks like. There's not (yet) a single tool that
 directly displays the raw binary.