Update doc

doc/bug-report

@@ -1,60 +0,0 @@
-Bug#:      1584
-Opened:    2007-06-25 23:06 GMT+3
-Reporter:  Robert Schuster <thebohemian [at] gmx.net>
-Summary:   provide system management software under free software licenses
-
-Several applications and libraries found on the N800 internet tablet/IT OS
-2007.10 are distributed under restricted and non-free license terms according
-to the Debian Free Software Guidelines, Open Source Definition and Free
-Software definition.
-
-I hereby politely ask for distributing those components under terms that are
-acceptable to the above mentioned guidelines.
-
-The applications of interest are:
-from the initfs: activate_panel, bt-cal, cal-tool, fb-chaimage, text2screen,
-wlan-cal, wlan-fw-update, retu-time, show_image, dsme, battest, bootstate,
-dsmetool, dspctl, waitfordsme and the script linuxrc
-
-the libraries of interest are:
-libbmeic.so, libcal.so, libdsme.so, libppu.so, libactivitymonitor.so,
-libcalmodule.so, libhwwd.so, libinactivity-blank.so, liblifeguard.so,
-libperipheral.so, libprocesswd.so, libstartup.so, libstate.so,
-libtemperature.so
-
-There may be other software artifacts which are of interest for which I will
-file separate bugreports if there is a need for them.
-
-Rationale:
-When Nokia/Maemo decided to use a variant of the GNU operating system and Linux
-as its kernel for implementing the Internet Tablet OS they profited from a
-wealth of knowledge and work invested in various software projects. With the
-help of free software licensing they were allowed to create a unique software
-environment which exactly implements the Maemo projects' goals. Maemo has
-gained and still gains from those software projects because they are
-independently developed further giving Maemo more possibilities in the future.
-
-One of the key goals of the GNU project is to give its user's the freedom to
-implement their own ideas. This goal is to be reached by writing free software
-and sometimes (in the early days often) replacing proprietary software.
-
-The non-free bits in the core infrastructure of the IT OS 2007 are a road block
-for efforts to create free operating systems/distributions besides IT OS on the
-770/N800.
-
-The reason for why it is helpful to have other operating system/distribution on
-the N800 is simple: There are hundreds of GNU/Linux distributions out there.
-Each one exists because there is a userbase that exactly likes their flavor of
-GNU/Linux.
-
-For the 770/N800 Internet Tablets there exists only one such distribution: The
-Internet Tablet OS. With the sheer amount of GNU/Linux distributions for
-desktops/workstations/servers/routers/PDAs on the one hand and the single OS
-solution for the Internet Tablets on the other I doubt that it can handle all
-the possible uses people have.
-
-By releasing the above mentioned programs/libraries under free software
-licenses people will be given the same possibilities the Maemo project had in
-the first place.
-
-Let us be free.

doc/dumping

@@ -1,16 +1,14 @@
-<b>Dumping the firmware</b>
+Dumping the firmware:
 
 This technique consists on reconstructing a firmware image dumping
 pieces at certains offsets of the device internal memory.
 
-<b></b>
+Technical details:
-
-<b>Technical details:</b>
 
  * The internal flash memory is exposed to the system as MTD devices.
  * Is possible to dump the individual sections of a flashed firmware.
  *
- * READ src/dump.c for detailed information.
+ * READ src/local.c for detailed information.
 
    mtd0 - contains xloader and sencodary pieces of the bootloaders
           0x00000 - xloader.bin    (size is 0x03600)

doc/faq

@@ -1,38 +1,28 @@
-<h2>FAQ</h2>
+FAQ:
 
-<b>*) How can I set my Internet Tablet into RD mode with 0xFFFF?</b>
+*) How can I set my Internet Tablet into RD mode with 0xFFFF?
 
-  Just type '0xFFFF -r 1' as root
+  Just type '0xFFFF -R 1' as root
 
 
-<b>*) How can I unpack a FIASCO firmware?
+*) How can I unpack a FIASCO firmware?
 
-  Just type '0xFFFF -r 1' as root
+  Just type '0xFFFF -M FiascoFirmware.bin -u'
 
 
-<b>*) How can I unpack a FIASCO firmware?</b>
+*) How can I flash a new rootfs?
 
-  Just type '0xFFFF -u FiascoFirmware.bin -e /tmp' as root
+  # 0xFFFF -m rootfs.jffs2 -f
 
 
-<b>*) How can I flash a new rootfs?
+*) How can I flash a full FIASCO image?
 
-  Unpack the pieces from the fiasco firmware (the one distributed by Nokia for example) and then type:
+  # 0xFFFF -M FiascoFirmware.fiasco -f
-
-  # 0xFFFF -R -p rootfs.jffs 
 
 
-<b>*) How can I flash a full FIASCO image?</b>
+Advanced commands:
 
-  It is not recommended to use, it needs more testing, and is more secure to unpack them first manually
+*) How to extract the firmware pieces from a running device?
-  and flash the pieces manually with multiple '-p' flags. If you are brave try:
-
-  # 0xFFFF -F FiascoFirmware.fiasco
-
-
-<h2>Advanced commands</h2>
-
-<b>*) How to extract the firmware pieces from a running device?</b>
 
   It is possible to dump the firmware pieces from the internal MTD to reconstruct a FIASCO image.
   To do this recompile the flasher for ARM and run this command in the device:
@@ -40,10 +30,6 @@
   # mkdir /media/mmc1/backup
   # 0xFFFF -e /media/mmc1/backup
 
+  To dump directly into FIASCO image run:
 
-<b>*) Dumping configuration region</b>
+  # 0xFFFF -E /media/mmc1/backup.fiasco
-
-  There's a hidden mtd partition containing undocumented configuration information. This one can be
-  dumped from the device using the following command:
-
-  # 0xFFFF -x

doc/faq2

@@ -1,9 +1,9 @@
-<b>FAQ</b>
+FAQ2:
 
 This file tries to collect a bunch of common questions/answers about flashing
 
 
-<b>*) Why implement a free software flasher?</b>
+*) Why implement a free software flasher?
 
   The Nokia Internet Tablets are based on Free Software (software libre), but
   not everything included *is* free software, for instance, the firmware flasher
@@ -18,7 +18,7 @@ This file tries to collect a bunch of common questions/answers about flashing
   powerpc, x86, mips, etc...
 
 
-<b>*) Can I brick my device?</b>
+*) Can I brick my device?
 
   Of course! You're free to do what you want with your device :)
 
@@ -30,20 +30,24 @@ This file tries to collect a bunch of common questions/answers about flashing
   use the flasher provided by Nokia, it's better for your heart's health.
 
 
-<b>*) What can I do with 0xFFFF?</b>
+*) What can I do with 0xFFFF?
 
   Actually 0xFFFF allows you to:
-  
+
-  - flash separated pieces of the firmware.
+  - flash separated pieces of the firmware
+  - flash full FIASCO image
+  - load kernel & initfs without flashing
+  - cold-flash bricked device (without NOLO)
   - retrieve information about the device
   - reboot de mother board
-  - extract the current firmware pieces from the device (reverse flash)
+  - extract the current firmware pieces from the device (dump)
   - set the USB host/slave mode
-  - set the R&R mode
+  - set the R&R mode and flags
-  - identify firmware pieces
+  - pack/unpack FIASCO firmwares
+  - automatic piece identifier
 
 
-<b>*) What is NOLO?</b>
+*) What is NOLO?
 
   NOLO is the 'server-side' part of the flasher from Nokia. NOLO means
   NOkia LOader and it's composed by two pieces of the firmware that are
@@ -59,10 +63,10 @@ This file tries to collect a bunch of common questions/answers about flashing
   actions on the device.
 
 
-<b>*) How can I identify my device?</b>
+*) How can I identify my device?
 
   Theorically 770 and n800 have different USB device ID, but this is not
-  true at all. The first series of the n800 comes with the same usb-id 
+  true at all. The first series of the n800 comes with the same usb-id
   than 770. That's weird!
 
   So, the only way to identify the device is by asking nolo for the version
@@ -71,10 +75,6 @@ This file tries to collect a bunch of common questions/answers about flashing
   because it wouldn't work :)
 
 
-<b>*) Can I unpack fiasco blobs?</b>
+*) Can I unpack FIASCO blobs?
 
-  Actually the fiasco format is not yet supported and not planned in
+  Yes, last version of 0xFFFF has full support of FIASCO images.
-  short term. There is no real need for supporting a proprietary
-  format image containing a proprietary system.
-
-  We can just use tarballs containing the desired pieces.

doc/nokia-tips

@@ -1,4 +1,4 @@
-<b>Nokia tips</b>
+Nokia tips:
 
 When developing this tool I've found some bugs and misfeatures that
 should be fixed to make flashing safer and cleaner.
@@ -9,7 +9,7 @@ it's really hard to break the device and it works pretty nice. BTW I
 think that there are some things that should be fixed.
 
 
-<b>*) Flashing at low battery level</b>
+*) Flashing at low battery level
 
   When the device is under a certain limit of battery it will not start,
   this is done by initfs, without any warning message or so, this really
@@ -20,7 +20,7 @@ think that there are some things that should be fixed.
   This is *really* dangerous and not very user friendly.
 
 
-<b>*) Internal nolo state not reset'd</b>
+*) Internal nolo state not reset'd
 
   It's possible to get nolo on a strange state that always returns error
   when flashing pieces, it's mandatory to reboot the device to recover
@@ -29,7 +29,7 @@ think that there are some things that should be fixed.
   This is an strange and not very clear to me.
 
 
-<b>*) Buffer overflows</b>
+*) Buffer overflows
 
   The original nokia flasher has some buffer overflow bugs that should
   be fixed. They're safe for 99.9% of cases, but bofs on critical programs
@@ -40,14 +40,7 @@ think that there are some things that should be fixed.
   than this one.
 
 
-<b>*) Missing stuff</b>
+*) Weird firmware format
-
-  There are some flashing options that are not working like passing arguments
-  to the kernel, set the hw revision or do a cold flash (the most critical
-  part is undocumented).
-
-
-<b>*) Weird firmware format</b>
 
   The (new and old) FIASCO firmware format is not a very clean format, it
   doesn't provide any checksumming facility to ensure that the contents of
@@ -64,7 +57,7 @@ think that there are some things that should be fixed.
   code could be revised and enhaced by zillions of eyes.
 
 
-<b>*) Poor checksumming</b>
+*) Poor checksumming
 
   The only checksum is a 16 bit xor of the whole firmware piece and it's only
   checked after sending the piece to the device.
@@ -73,7 +66,7 @@ think that there are some things that should be fixed.
   algorithm. It currently performs a unique check at the end, it could be
   better to check each data block to avoid errors or invalid flashing, isn't it ?
 
-<b>*) No validation of pieces before flashing</b>
+*) No validation of pieces before flashing
 
   I've implemented a minimal check of the pieces to avoid flashing invalid
   pieces on the wrong place. This is done in fpid.c (firmware piece identifier).
@@ -82,7 +75,7 @@ think that there are some things that should be fixed.
   that can (pseudo)brick the device.
 
 
-<b>*) Reverse flashing</b>
+*) Reverse flashing
 
   If you want to test a new firmware, but you don't want to loose all the
   contents of your device. The only way to do that (afaik) is from the
@@ -94,7 +87,7 @@ think that there are some things that should be fixed.
   case of a wrong checksumming (for example)
 
 
-<b>*) Documentation</b>
+*) Documentation
 
   The nokia flasher comes as is, without documentation. This is not good
   to anybody, because the lack of information is always the root of problems,

doc/pieces

@@ -8,7 +8,7 @@ defined by NOLO on the internal flash memory.
 Nokia provides a blob packed with a proprietary format called 'FIASCO'. This
 blob contains the following pieces:
 
- - omap-nand   -  only flashable via serial jtag
+ - 2nd         -  for Cold Flashing
  - xloader     -  first part of nolo
  - secondary   -  second part of nolo (usb support and launches kernel)
  - kernel      -  the kernel
@@ -18,21 +18,15 @@ blob contains the following pieces:
 Some of these pieces are versioned to match board specific features
 (mostly xloader and secondary ones).
 
-This format is not supported by 0xFFFF at this moment, but there are no
-plans for doing it in short term. This is because we only need to flash
-separated pieces. We can just distribute tarballs containing the pieces
-and meta information with a whole Free OS for the internet tablets.
-
 To flash an initfs partition and reboot:
 
-  $ 0xFFFF -p initfs%initfs.jffs2 -R
+  $ 0xFFFF -m initfs:initfs.jffs2 -f -r
 
-The format of the argument is [piece-type] % [file-name] (% [version-string]).
+The format of the argument is [[[device:[hw-revision:]]verion:]piece-type:]file-name[%layout-file-name]
 
-Pieces can be automatically identified by using the '-I' flag:
+Pieces can be automatically identified by using the '-i' flag:
 
-  $ 0xFFFF -I initfs.jffs2
+  $ 0xFFFF -m initfs.jffs2 -i
-  initfs.jffs2: initfs
 
 You can dump these pieces from the internal memory of the internet
 tablet by using the mtd-utils over /dev/mtd* or just running:

doc/usage

@@ -1,68 +1,88 @@
-<b>Usage guide</b>
+0xFFFF v0.6  // The Free Fiasco Firmware Flasher
 
-0xFFFF is a free software implementation of the flasher for the Nokia Internet
+Operations:
-Tablets (770 and n800).
+ -b [cmdline]    boot default or loaded kernel (default: no cmdline)
- <pre>
+ -b update       boot default or loaded kernel to Update mode
-  - flash separated pieces of the firmware.
+ -r              reboot device
-  - retrieve information about the device
+ -l              load kernel and initfs images to RAM
-  - reboot de mother board
+ -f              flash all specified images
-  - extract the current firmware pieces from the device (dump)
+ -c              cold flash 2nd and secondary image
-  - set the USB host/slave mode
+ -x [/dev/mtd]   check for bad blocks on mtd device (default: all)
-  - pack/unpack fiasco firmwares
+ -E file         dump all device images to one fiasco image, see -t
-  - fine grained R&D flags support
+ -e [dir]        dump all device images to directory, see -t (default: current)
-  - identify firmware pieces
-  - dump mtd partitions (embedded mtd-utils source code)
-  - reconstruct initfs from a dump
-  - dump config partition
-  - automatic piece identifier
-  - console mode (shell like)
-  </pre>
-This is the help message of the tool:
-<pre>
-<b>~$ 0xFFFF -h</b>
-0xFFFF v0.3  // The Free Fiasco Firmware Flasher
- -b [arg]       boots the kernel with arguments
- -c             console prompt mode
- -C [/dev/mtd]  check bad blocks on mtd
- -d [vid:pid]   injects a usb device into the supported list
- -D [0|1|2]     sets the root device to flash (0), mmc (1) or usb (2)
- -e [path]      dump and extract pieces to path
- -f <flags>     set the given RD flags (see '-f help')
- -F [fiasco]    flash a fiasco firmware image
- -h             show this help message
- -H [file]      calculate hash for file
- -i             show device information (let standby mode)
- -I [piece]     identify a firmware piece
- -l, -L         list supported usb device ids
- -p [[p%]file]  piece-of-firmware % file-where-this-piece-is
- -r [0|1]       disable/enable R&D mode
- -R             reboot the omap board
- -s [serial]    serial port console (minicom like terminal)
- -u [fiasco]    unpack target fiasco image
- -U [0|1]       disable/enable the usb host mode
- -v             be verbose and noisy
- -V             show 0xFFFF version information
- -x             extract configuration entries from /dev/mtd1
-Pieces are: xloader secondary kernel initfs rootfs omap-nand 
-</pre>
 
-Before anything we can execute failsafe queries like getting device information:
+Device configuration:
-<pre> <b>~$ 0xFFFF -i</b></pre>
+ -I              identify, show all information about device
-This command will put the bootloader in standby mode, so you can now send other
+ -D 0|1|2        change root device: 0 - flash, 1 - mmc, 2 - usb
-commands without having to reboot the tablet manually. To reboot the mother
+ -U 0|1          disable/enable USB host mode
-board via USB type:
+ -R 0|1          disable/enable R&D mode
-<pre> <b>~$ 0xFFFF -R</b></pre>
+ -F flags        change R&D flags, flags are comma separated list, can be empty
-You can run 'offline' commands to identify the type of the firmware pieces:
+ -H rev          change HW revision
-<pre> <b>~$ 0xFFFF -I zImage -I xloader.bin -I initfs.jffs2.orig</b>
+ -N ver          change NOLO version string
- kernel: zImage
+ -K ver          change kernel version string
- xloader: xloader.bin
+ -T ver          change initfs version string
- initfs: initfs.jffs2.orig</pre>
+ -S ver          change SW release version string
-If you want to backup your device firmware you can crosscompile the 0xFFFF
+ -C ver          change content eMMC version string
-utility and type this on the terminal:
+
-<pre> <b>~$ sudo gainroot</b>
+Input image specification:
- ~# mkdir /media/mmc1/firmware
+ -M file         specify fiasco image
- ~# ./0xFFFF -e /media/mmc1/firmware</pre>
+ -m arg          specify normal image
-Now is time to flash something :) By default the flasher identifies the type
+                 arg is [[[dev:[hw:]]ver:]type:]file[%lay]
-of the piece automatically, but you can force't prefixing the filename with
+                   dev is device name string (default: emtpy)
-the piece-type name. To do this is just as simple as typing:
+                   hw are comma separated list of HW revisions (default: empty)
-<pre> <b>~$ 0xFFFF -p zImage</b></pre>
+                   ver is image version string (default: empty)
+                   type is image type (default: autodetect)
+                   file is image file name
+                   lay is layout file name (default: none)
+
+Image filters:
+ -t types        filter images by type
+ -d dev          filter images by device
+ -w hw           filter images by HW revision
+
+Fiasco image:
+ -u [dir]        unpack fiasco image to directory (default: current)
+ -g file[%sw]    generate fiasco image with SW rel version (default: no version)
+
+Other options:
+ -i              identify images
+ -s              simulate, do not flash or write on disk
+ -n              disable hash, checksum and image type checking
+ -v              be verbose and noisy
+ -h              show this help message
+
+R&D flags:
+  no-omap-wd          disable auto reboot by OMAP watchdog
+  no-ext-wd           disable auto reboot by external watchdog
+  no-lifeguard-reset  disable auto reboot by software lifeguard
+  serial-console      enable serial console
+  no-usb-timeout      disable usb timeout for flashing
+  sti-console         enable sti console
+  no-charging         disable battery charging
+  force-power-key     force omap boot reason to power key
+
+Supported devices:
+  SU-18          Nokia 770
+  RX-34          Nokia N800
+  RX-44          Nokia N810
+  RX-48          Nokia N810 Wimax
+  RX-51          Nokia N900
+
+Supported image types:
+  xloader
+  2nd
+  secondary
+  kernel
+  initfs
+  rootfs
+  mmc
+  cmt-2nd
+  cmt-algo
+  cmt-mcusw
+
+Supported connection protocols:
+  Local on device
+  NOLO via USB
+  Cold flashing via USB
+  Mk II protocol via USB
+  RAW disk via USB