Qi

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Speed up resume)
Line 45: Line 45:
 
: make Qi skip this partition
 
: make Qi skip this partition
  
Note that setting the loglevel some low value (must be >=1, though!) makes resume about 3 seconds faster than it is without: Without setting this parameter the kernel produces loads of log information on resume which is output on a console with very slow scrolling.  
+
===Speed up kernel resume for SHR===
 +
Since SHR (and perhaps other distributions as well) ouput log messages during resume which slow down the resume process by ca. 3 seconds it make sense there to append the following settings to /boot/append-GTA0[123]:
 +
: loglevel=1 quiet
 +
The disadvantage of this speedup is that you won't see any lifesign of your phone until it starts the graphical user interface after adding these files, though.
 
===Boot Order===
 
===Boot Order===
 
[[image:Qi-drawings-bootsequence.png|frame|Qi GTA02 Booting order]]
 
[[image:Qi-drawings-bootsequence.png|frame|Qi GTA02 Booting order]]

Revision as of 18:43, 14 March 2009

Qi Boot messages
Qi ( [ ] ) is a lightweight replacement for the uBoot bootloader with everything that doesn't assist "loading" and "booting" Linux stripped out.

Its advantages comparing to u-boot are:

  • actively developed (u-boot on GTA02 is deprecated)
  • easier configuration, more robust and predictable
  • SD and SDHC cards supported properly with partitions of any size
  • kernel size is detected by checking the start of the kernel image, so large (>2M) kernels are supported without tweaking or loading more than needed
  • Very fast, simple boot direct to Linux

Contents

About Qi

Requirements

There is a GTA01 build of Qi, but using it without a debug board is not recommended because Qi itself does not support DFU, so updating or going back to U-Boot is a difficult process.

GTA02 Hardware has NOR U-Boot always available to update Qi so it's safe to try it out.

Features

  • booting from primary SD partitions (1st, 2nd or 3rd) in /boot directory
  • booting from NAND (compatible with U-Boot's dynparts scheme)
  • configuration per rootfs, by files in /boot in the rootfs
  • automatically choose correct kernel for device hardware so rootfs can be used on multiple device types
  • automatically tell kernel correct root= for rootfs kernel image came from, simplifying update
  • ext2/3 are supported
  • symlinks are supported
  • parses identity partition and appends kernel commandline with device identity information
  • zero "environment" or private persistent state - operation is completely deterministic

Limitations

  • no DFU-Mode - USB is not initialized at all
  • no boot menu
  • FAT partitions are ignored

Both the lack of DFU and the boot menu are planned to be addressed by the backup / recovery rootfs.

FAT is not supported because it can't provide a rootfs, and Qi wants the kernel to come from the rootfs.

Defaults

If the kernel is found on uSD, Qi assumes the rootfs to be on the same partition as the kernel. In case of boot from NAND, it assumes that rootfs is also on NAND (just as u-boot does). See below for help with an extra /boot-partition. The default rootdelay is 1 second.

Files

/boot/uImage-GTA0[123].bin
Kernel images, Qi will look for (can be in either uImage (u-boot image) or zImage format, file name should still be uImage-GTA0[123].bin)
/boot/append-GTA0[123]
Additional kernel arguments. All arguments should be on the first and the only line separated by spaces, for example: "loglevel=8 rootdelay=5 " . Make sure you have an extra space after the last argument (space is no longer needed if the version is from 31 Jan or older)!
/boot/noboot-GTA0[123]
make Qi skip this partition

Speed up kernel resume for SHR

Since SHR (and perhaps other distributions as well) ouput log messages during resume which slow down the resume process by ca. 3 seconds it make sense there to append the following settings to /boot/append-GTA0[123]:

loglevel=1 quiet

The disadvantage of this speedup is that you won't see any lifesign of your phone until it starts the graphical user interface after adding these files, though.

Boot Order

Qi GTA02 Booting order
  1. SD Partition 1
  2. SD Partition 2
  3. SD Partition 3
  4. NAND
  5. Memory Test

Qi will try to mount each SD partition as ext2 / 3, if that succeeds it will look for the kernel as /boot/uImage-GTA02.bin. If that is found, it'll be fetched, its CRC is checked and then it's booted into with a generated kernel commandline.

Kernel Commandline Generation

Qi commandline composition

Because Qi has no private stored state, it infers and composes a suitable kernel commandline on each boot.

One of its tasks is to scan NAND memory using the U-Boot dynparts rules to determine the start offset of the NAND partitions on this device, from that it forms the mtdparts kernel parameter that sets Linux's view of NAND partitioning.

The other thing it does is mount the "identity" partition and get from there the globally unique MAC address for the USB over Ethernet function instead of the random one that is otherwise used.

LED and Vibrator Signals

  • AUX LED is turned on either on:
    • Successful partition mount
    • Successful kernel pull
    • Successful initramfs pull
  • AUX LED is turned off and vibrator runs briefly either on:
    • Fail of kernel pull
    • Fail of initramfs pull
    • Fail of mount partition
    • Skipping of current boot possibility
  • AUX LED is turned off either on:
    • Start of the kernel
    • Start of the mem test
    • Start of the kernel pull
    • Start of the initramfs pull
  • One Blue shine every ~10 second: did not find any valid kernel to boot
  • About four RED shines per second: kernel panic.

Booting

A short press on the power button is enough to make Qi start booting. In a few seconds the backlight will be lit, but the kernel will not spew any console messages unless something is wrong. It may take up to 2 minutes (depends on distribution) until X is started during which there will be no visual feedback. Please be patient.

You can force debug messages on the LCM console by holding in the power button before Linux starts.

Choosing a Kernel

If a user presses the AUX button after successful partition mount and before start of the kernel pull (that is, while the red LED is on), this boot possibility is skipped (and GTA02 owners can feel vibration).

On versions newer than Jan 18 if a user holds the POWER button just before start of the kernel, debugging parameters are added to the kernel command line and a lot of information is output to the screen.

Boot Menu

Qi's concept is to leave everything possible to Linux, that includes even the video init. Therefore Qi does NOT provide a boot menu. This should rather be implemented by a minimal Kernel, initramfs and menu system. It may be more comfortable for some users and may get them to switch from uboot to Qi. This does not exist yet (it's already implemented for some Angstrom-supported devices and for Zaurus, so porting should be relatively easy).

Download and installation

The daily download is a qi-s3cXXXX-andy_somenumber.udfu file at http://people.openmoko.org/andy/ . Use the file appropriate to your device:

  • GTA01 -> qi-s3c2410
  • GTA02 -> qi-s3c2442
  • GTA03 -> qi-s3c6410

The installation should be flashing like (do it in DFU mode of NOR u-boot):

# dfu-util -a u-boot -R -D qi-s3c6410-andy_8589b40295653557.udfu

Source code

git://git.openmoko.org/git/qi.git , http://git.openmoko.org/?p=qi.git;a=summary . One can also just use strings(1) on the .udfu file to get an idea of where Qi currently looks for files.

README

The latest README file can be found in the git as well:http://git.openmoko.org/?p=qi.git;a=blob;f=README;hb=HEAD

Tips, Tricks, Tweaks

General troubleshooting

Qi does not bring up the LCD backlight. If the backlight is lit, it means you have succeeded to boot into Linux.

If nothing else is happening or there is a panic, enable debugging messages as described below.

Enabling console messages

You can just hold in the power button, this automatically appends verbose debugging to the kernel commandline (loglevel=8).

If you always want verbose "dmesg" type debugging messages, you can do it like this:

[1] If it's SD Card boot, just create a text file, e.g., for a GTA02 use

/boot/append-GTA02

on the rootfs in question, put in there

loglevel=8

and you'll see the messages on boot. If it's NAND right now you need to edit the default commandline in Qi for gta02.

/boot-Partition

If you have a separate partition for /boot, so that your kernel and rootfs are not in fact on the same partition, you will need to append a root= entry on the kernel commandline to override the default action of trying to use the partition where the kernel came from as the rootfs.

Add this in /boot/append-GTA0[123]:

root=/dev/mmcblk0p2

for a rootfs on the second partition.

Note that a default Debian installation puts the kernel straight in the root of /dev/mmcblk0p1, not in a boot subdirectory, expecting u-boot to mount it as /boot. In order for Qi to recognise this, create a boot subdirectory with a symlink to the kernel.

SD Initialisation

If you don't specify loglevel=8 in append-GTAXX, and booting fails with a "VFS: Cannot open root device "mmcblk0p1" or unknown-block(2,0)", the SD card needs a little bit more time to initialise.

Put a "rootdelay=5" in append-GTAXX like so:

rootdelay=5

Testing speed improvements

Stopwatch results on Qi (error is approx ±1/2 second):

Booting SHR image with uBoot:

  • 0:00 power button held down
  • 0:07 splash screen appears
  • 0:15 drops to console showing kernel messages scrolling by for ~1 minute
  • 1:18 Openmoko 'please wait' splash
  • 1:31 desktop animated splash
  • 2:38 finished booting

Booting identical setup with Qi flashed over uBoot:

  • 0:00 power button held down
  • 0:06 backlit black
  • 0:13 please wait booting... (only this text on console for next 38 seconds)
  • 0:51 Angstrom console message (at the end of kernel output with uBoot, but ONLY text display to appear throughout this stage with Qi)
  • 0:54 Openmoko 'please wait' splash
  • 1:05 desktop animated splash
  • 1:54 finished booting

So for this particular configuration, it reduced time-to-desktop by about 28%, about 44 seconds. Surprisingly, the later segments of booting (desktop) were also noticeably faster than with uBoot - One would have expected just the fist stages up until init (kernel finished establishing itself) to be faster.

Personal tools
Qi Boot messages
Qi ( [ ] ) is a lightweight replacement for the uBoot bootloader with everything that doesn't assist "loading" and "booting" Linux stripped out.

Its advantages comparing to u-boot are:

  • actively developed (u-boot on GTA02 is deprecated)
  • easier configuration, more robust and predictable
  • SD and SDHC cards supported properly with partitions of any size
  • kernel size is detected by checking the start of the kernel image, so large (>2M) kernels are supported without tweaking or loading more than needed
  • Very fast, simple boot direct to Linux

About Qi

Requirements

There is a GTA01 build of Qi, but using it without a debug board is not recommended because Qi itself does not support DFU, so updating or going back to U-Boot is a difficult process.

GTA02 Hardware has NOR U-Boot always available to update Qi so it's safe to try it out.

Features

  • booting from primary SD partitions (1st, 2nd or 3rd) in /boot directory
  • booting from NAND (compatible with U-Boot's dynparts scheme)
  • configuration per rootfs, by files in /boot in the rootfs
  • automatically choose correct kernel for device hardware so rootfs can be used on multiple device types
  • automatically tell kernel correct root= for rootfs kernel image came from, simplifying update
  • ext2/3 are supported
  • symlinks are supported
  • parses identity partition and appends kernel commandline with device identity information
  • zero "environment" or private persistent state - operation is completely deterministic

Limitations

  • no DFU-Mode - USB is not initialized at all
  • no boot menu
  • FAT partitions are ignored

Both the lack of DFU and the boot menu are planned to be addressed by the backup / recovery rootfs.

FAT is not supported because it can't provide a rootfs, and Qi wants the kernel to come from the rootfs.

Defaults

If the kernel is found on uSD, Qi assumes the rootfs to be on the same partition as the kernel. In case of boot from NAND, it assumes that rootfs is also on NAND (just as u-boot does). See below for help with an extra /boot-partition. The default rootdelay is 1 second.

Files

/boot/uImage-GTA0[123].bin
Kernel images, Qi will look for (can be in either uImage (u-boot image) or zImage format, file name should still be uImage-GTA0[123].bin)
/boot/append-GTA0[123]
Additional kernel arguments. All arguments should be on the first and the only line separated by spaces, for example: "loglevel=8 rootdelay=5 " . Make sure you have an extra space after the last argument (space is no longer needed if the version is from 31 Jan or older)!
/boot/noboot-GTA0[123]
make Qi skip this partition

Speed up kernel resume for SHR

Since SHR (and perhaps other distributions as well) ouput log messages during resume which slow down the resume process by ca. 3 seconds it make sense there to append the following settings to /boot/append-GTA0[123]:

loglevel=1 quiet

The disadvantage of this speedup is that you won't see any lifesign of your phone until it starts the graphical user interface after adding these files, though.

Boot Order

Qi GTA02 Booting order
  1. SD Partition 1
  2. SD Partition 2
  3. SD Partition 3
  4. NAND
  5. Memory Test

Qi will try to mount each SD partition as ext2 / 3, if that succeeds it will look for the kernel as /boot/uImage-GTA02.bin. If that is found, it'll be fetched, its CRC is checked and then it's booted into with a generated kernel commandline.

Kernel Commandline Generation

Qi commandline composition

Because Qi has no private stored state, it infers and composes a suitable kernel commandline on each boot.

One of its tasks is to scan NAND memory using the U-Boot dynparts rules to determine the start offset of the NAND partitions on this device, from that it forms the mtdparts kernel parameter that sets Linux's view of NAND partitioning.

The other thing it does is mount the "identity" partition and get from there the globally unique MAC address for the USB over Ethernet function instead of the random one that is otherwise used.

LED and Vibrator Signals

  • AUX LED is turned on either on:
    • Successful partition mount
    • Successful kernel pull
    • Successful initramfs pull
  • AUX LED is turned off and vibrator runs briefly either on:
    • Fail of kernel pull
    • Fail of initramfs pull
    • Fail of mount partition
    • Skipping of current boot possibility
  • AUX LED is turned off either on:
    • Start of the kernel
    • Start of the mem test
    • Start of the kernel pull
    • Start of the initramfs pull
  • One Blue shine every ~10 second: did not find any valid kernel to boot
  • About four RED shines per second: kernel panic.

Booting

A short press on the power button is enough to make Qi start booting. In a few seconds the backlight will be lit, but the kernel will not spew any console messages unless something is wrong. It may take up to 2 minutes (depends on distribution) until X is started during which there will be no visual feedback. Please be patient.

You can force debug messages on the LCM console by holding in the power button before Linux starts.

Choosing a Kernel

If a user presses the AUX button after successful partition mount and before start of the kernel pull (that is, while the red LED is on), this boot possibility is skipped (and GTA02 owners can feel vibration).

On versions newer than Jan 18 if a user holds the POWER button just before start of the kernel, debugging parameters are added to the kernel command line and a lot of information is output to the screen.

Boot Menu

Qi's concept is to leave everything possible to Linux, that includes even the video init. Therefore Qi does NOT provide a boot menu. This should rather be implemented by a minimal Kernel, initramfs and menu system. It may be more comfortable for some users and may get them to switch from uboot to Qi. This does not exist yet (it's already implemented for some Angstrom-supported devices and for Zaurus, so porting should be relatively easy).

Download and installation

The daily download is a qi-s3cXXXX-andy_somenumber.udfu file at http://people.openmoko.org/andy/ . Use the file appropriate to your device:

  • GTA01 -> qi-s3c2410
  • GTA02 -> qi-s3c2442
  • GTA03 -> qi-s3c6410

The installation should be flashing like (do it in DFU mode of NOR u-boot):

# dfu-util -a u-boot -R -D qi-s3c6410-andy_8589b40295653557.udfu

Source code

git://git.openmoko.org/git/qi.git , http://git.openmoko.org/?p=qi.git;a=summary . One can also just use strings(1) on the .udfu file to get an idea of where Qi currently looks for files.

README

The latest README file can be found in the git as well:http://git.openmoko.org/?p=qi.git;a=blob;f=README;hb=HEAD

Tips, Tricks, Tweaks

General troubleshooting

Qi does not bring up the LCD backlight. If the backlight is lit, it means you have succeeded to boot into Linux.

If nothing else is happening or there is a panic, enable debugging messages as described below.

Enabling console messages

You can just hold in the power button, this automatically appends verbose debugging to the kernel commandline (loglevel=8).

If you always want verbose "dmesg" type debugging messages, you can do it like this:

[1] If it's SD Card boot, just create a text file, e.g., for a GTA02 use

/boot/append-GTA02

on the rootfs in question, put in there

loglevel=8

and you'll see the messages on boot. If it's NAND right now you need to edit the default commandline in Qi for gta02.

/boot-Partition

If you have a separate partition for /boot, so that your kernel and rootfs are not in fact on the same partition, you will need to append a root= entry on the kernel commandline to override the default action of trying to use the partition where the kernel came from as the rootfs.

Add this in /boot/append-GTA0[123]:

root=/dev/mmcblk0p2

for a rootfs on the second partition.

Note that a default Debian installation puts the kernel straight in the root of /dev/mmcblk0p1, not in a boot subdirectory, expecting u-boot to mount it as /boot. In order for Qi to recognise this, create a boot subdirectory with a symlink to the kernel.

SD Initialisation

If you don't specify loglevel=8 in append-GTAXX, and booting fails with a "VFS: Cannot open root device "mmcblk0p1" or unknown-block(2,0)", the SD card needs a little bit more time to initialise.

Put a "rootdelay=5" in append-GTAXX like so:

rootdelay=5

Testing speed improvements

Stopwatch results on Qi (error is approx ±1/2 second):

Booting SHR image with uBoot:

  • 0:00 power button held down
  • 0:07 splash screen appears
  • 0:15 drops to console showing kernel messages scrolling by for ~1 minute
  • 1:18 Openmoko 'please wait' splash
  • 1:31 desktop animated splash
  • 2:38 finished booting

Booting identical setup with Qi flashed over uBoot:

  • 0:00 power button held down
  • 0:06 backlit black
  • 0:13 please wait booting... (only this text on console for next 38 seconds)
  • 0:51 Angstrom console message (at the end of kernel output with uBoot, but ONLY text display to appear throughout this stage with Qi)
  • 0:54 Openmoko 'please wait' splash
  • 1:05 desktop animated splash
  • 1:54 finished booting

So for this particular configuration, it reduced time-to-desktop by about 28%, about 44 seconds. Surprisingly, the later segments of booting (desktop) were also noticeably faster than with uBoot - One would have expected just the fist stages up until init (kernel finished establishing itself) to be faster.