From 1e84b07b393c8efedf2f594641e7736749e680dc Mon Sep 17 00:00:00 2001 From: Pali Rohár Date: Sun, 25 Nov 2012 22:57:04 +0100 Subject: Update doc --- doc/bug-report | 60 ----------------------- doc/dumping | 8 ++- doc/faq | 40 +++++---------- doc/faq2 | 36 +++++++------- doc/nokia-tips | 25 ++++------ doc/pieces | 16 ++---- doc/usage | 152 ++++++++++++++++++++++++++++++++------------------------- 7 files changed, 134 insertions(+), 203 deletions(-) delete mode 100644 doc/bug-report (limited to 'doc') diff --git a/doc/bug-report b/doc/bug-report deleted file mode 100644 index 6955f69..0000000 --- a/doc/bug-report +++ /dev/null @@ -1,60 +0,0 @@ -Bug#: 1584 -Opened: 2007-06-25 23:06 GMT+3 -Reporter: Robert Schuster -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. diff --git a/doc/dumping b/doc/dumping index f0441b5..bbddc89 100644 --- a/doc/dumping +++ b/doc/dumping @@ -1,16 +1,14 @@ -Dumping the firmware +Dumping the firmware: This technique consists on reconstructing a firmware image dumping pieces at certains offsets of the device internal memory. - - -Technical details: +Technical details: * 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) diff --git a/doc/faq b/doc/faq index 5a5ec7a..2087a56 100644 --- a/doc/faq +++ b/doc/faq @@ -1,38 +1,28 @@ -

FAQ

+FAQ: -*) How can I set my Internet Tablet into RD mode with 0xFFFF? +*) 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 -*) 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' -*) How can I unpack a FIASCO firmware? +*) How can I flash a new rootfs? - Just type '0xFFFF -u FiascoFirmware.bin -e /tmp' as root + # 0xFFFF -m rootfs.jffs2 -f -*) 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 +Advanced commands: -*) How can I flash a full FIASCO image? - - It is not recommended to use, it needs more testing, and is more secure to unpack them first manually - and flash the pieces manually with multiple '-p' flags. If you are brave try: - - # 0xFFFF -F FiascoFirmware.fiasco - - -

Advanced commands

- -*) How to extract the firmware pieces from a running device? +*) How to extract the firmware pieces from a running device? 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: -*) Dumping configuration region - - There's a hidden mtd partition containing undocumented configuration information. This one can be - dumped from the device using the following command: - - # 0xFFFF -x + # 0xFFFF -E /media/mmc1/backup.fiasco diff --git a/doc/faq2 b/doc/faq2 index 26a7f99..d89e952 100644 --- a/doc/faq2 +++ b/doc/faq2 @@ -1,9 +1,9 @@ -FAQ +FAQ2: This file tries to collect a bunch of common questions/answers about flashing -*) Why implement a free software flasher? +*) 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... -*) Can I brick my device? +*) 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. -*) What can I do with 0xFFFF? +*) 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 - - identify firmware pieces + - set the R&R mode and flags + - pack/unpack FIASCO firmwares + - automatic piece identifier -*) What is NOLO? +*) 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. -*) How can I identify my device? +*) 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 :) -*) Can I unpack fiasco blobs? - - Actually the fiasco format is not yet supported and not planned in - short term. There is no real need for supporting a proprietary - format image containing a proprietary system. +*) Can I unpack FIASCO blobs? - We can just use tarballs containing the desired pieces. + Yes, last version of 0xFFFF has full support of FIASCO images. diff --git a/doc/nokia-tips b/doc/nokia-tips index 468c1a1..579d97b 100644 --- a/doc/nokia-tips +++ b/doc/nokia-tips @@ -1,4 +1,4 @@ -Nokia tips +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. -*) Flashing at low battery level +*) 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. -*) Internal nolo state not reset'd +*) 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. -*) Buffer overflows +*) 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. -*) Missing stuff - - 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). - - -*) Weird firmware format +*) Weird firmware format 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. -*) Poor checksumming +*) 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 ? -*) No validation of pieces before flashing +*) 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. -*) Reverse flashing +*) 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) -*) Documentation +*) 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, diff --git a/doc/pieces b/doc/pieces index 3e32f2a..d33b43c 100644 --- a/doc/pieces +++ b/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 - initfs.jffs2: initfs + $ 0xFFFF -m initfs.jffs2 -i You can dump these pieces from the internal memory of the internet tablet by using the mtd-utils over /dev/mtd* or just running: diff --git a/doc/usage b/doc/usage index d27e671..db50633 100644 --- a/doc/usage +++ b/doc/usage @@ -1,68 +1,88 @@ -Usage guide +0xFFFF v0.6 // The Free Fiasco Firmware Flasher -0xFFFF is a free software implementation of the flasher for the Nokia Internet -Tablets (770 and n800). - 
-  - flash separated pieces of the firmware.
-  - retrieve information about the device
-  - reboot de mother board
-  - extract the current firmware pieces from the device (dump)
-  - set the USB host/slave mode
-  - pack/unpack fiasco firmwares
-  - fine grained R&D flags support
-  - 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)
-
-This is the help message of the tool: -
-~$ 0xFFFF -h
-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      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 
-
+Operations: + -b [cmdline] boot default or loaded kernel (default: no cmdline) + -b update boot default or loaded kernel to Update mode + -r reboot device + -l load kernel and initfs images to RAM + -f flash all specified images + -c cold flash 2nd and secondary image + -x [/dev/mtd] check for bad blocks on mtd device (default: all) + -E file dump all device images to one fiasco image, see -t + -e [dir] dump all device images to directory, see -t (default: current) -Before anything we can execute failsafe queries like getting device information: -
 ~$ 0xFFFF -i
-This command will put the bootloader in standby mode, so you can now send other -commands without having to reboot the tablet manually. To reboot the mother -board via USB type: -
 ~$ 0xFFFF -R
-You can run 'offline' commands to identify the type of the firmware pieces: -
 ~$ 0xFFFF -I zImage -I xloader.bin -I initfs.jffs2.orig
- kernel: zImage
- xloader: xloader.bin
- initfs: initfs.jffs2.orig
-If you want to backup your device firmware you can crosscompile the 0xFFFF -utility and type this on the terminal: -
 ~$ sudo gainroot
- ~# mkdir /media/mmc1/firmware
- ~# ./0xFFFF -e /media/mmc1/firmware
-Now is time to flash something :) By default the flasher identifies the type -of the piece automatically, but you can force't prefixing the filename with -the piece-type name. To do this is just as simple as typing: -
 ~$ 0xFFFF -p zImage
+Device configuration: + -I identify, show all information about device + -D 0|1|2 change root device: 0 - flash, 1 - mmc, 2 - usb + -U 0|1 disable/enable USB host mode + -R 0|1 disable/enable R&D mode + -F flags change R&D flags, flags are comma separated list, can be empty + -H rev change HW revision + -N ver change NOLO version string + -K ver change kernel version string + -T ver change initfs version string + -S ver change SW release version string + -C ver change content eMMC version string + +Input image specification: + -M file specify fiasco image + -m arg specify normal image + arg is [[[dev:[hw:]]ver:]type:]file[%lay] + dev is device name string (default: emtpy) + hw are comma separated list of HW revisions (default: empty) + 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 -- cgit v1.2.3