source/blog/posts/2011/12/rescueOS/documentation.txt

   1 Documentation of RescueOS
   2 =========================
   3 RescueOS is a rescue solution for the Nokia N900, distributed
   4 as a tarball and as an initrd image. It has several features, most
   5 notable:
   6
   7 mounting maemo /
   8 EMMC access(can mount maemo home and MyDocs partition)
   9 WiFi support
  10 USB mass-storage mode
  11 USB networking
  12 Battery charging
  13
  14 Users must be familiar with the Linux console.
  15
  16 How does it work?
  17 ~~~~~~~~~~~~~~~~~
  18 The flasher utility loads rescueOS. This makes it unnecessary
  19 to modify the bootloader or maemo's /sbin/preinit.
  20
  21 By using the "-l" option, we do not flash the kernel or initrd image.
  22 It only loads the kernel into RAM. No modification on
  23 the NAND or bootloader happens.
  24
  25 Usecases
  26 ~~~~~~~~
  27 In fact, most users do not need it. Either way, possible usecases:
  28
  29 -Changing typos in bootscripts which prevent an operation system
  30 (e.g. maemo) to boot.
  31
  32 -Backuping files prior to a reflash.
  33
  34 -Charging the battery (when maemo is dead).
  35
  36 -Modification of the EMMC partitions and partition table.
  37
  38 -Backup & Restoring maemo rootfs.
  39
  40 -fsck file system checks
  41
  42 -and more...
  43
  44 Installation
  45 ~~~~~~~~~~~~
  46 Only the tarball needs to be "installed"(this means, unpacked).
  47 With the initrd, the flasher tool loads the whole system into RAM,
  48 making a microsd unnecesarry.
  49
  50 So far, only an installation on a Unix system is described. Windows
  51 can't read let alone write to ext filesystems by default.
  52
  53 Tarball:
  54 The installation of the tarball is rather easy. While it is recommended
  55 to create an ext4 partition, the kernel can actually handle ext2 and
  56 ext3. I assume that you only need this if maemo is broken on your device,
  57 therefore I don't want to describe how to install it directly on the N900.
  58
  59 1. Plug your microsd (through an adapter) into your computer. Find the
  60 device node of the first partition. For example, if it is /dev/sdf1,
  61 run mkfs.ext4 /dev/sdf1. WARNING: All data on this partition will be
  62 deleted. It is possible to use a different partition. If you use the
  63 second, replace the "mmcblk0p1" later in the kernel command line
  64 with mmclbk0p2. 40 MB should be sufficient.
  65
  66 2. mount /dev/sdf1 /mnt/
  67 3. tar xfvjp rescueOS-0.X.tar.bz2 -C /mnt/
  68 4. umount /mnt/
  69
  70 Booting the tarball:
  71 --------------------
  72 Put your microsd card back to your N900, close the backcover. Run the
  73 following command as root:
  74
  75 flasher-3.5 -l -k 2.6.37 -b"root=/dev/mmcblk0p1 rootwait rw
  76 console=ttyO2,115200n8 console=tty0 mtdoops.mtddev=2
  77
  78 wait for "suitable device not found..." and connect the N900 to your
  79 Linux box with USB.
  80
  81 -l                                                      = load
  82 -k                                                      = kernel path
  83 -b                                                      = command line for the kernel.
  84 root=/dev/mmcblk0p1             = first sd partition. Inside maemo it is the first EMMC partition.
  85 rootwait                                        = wait until the root partition shows up.
  86 rw                                                      = mounts the root partition read write
  87 console=tty02,115200n8          = set up a console with the given boutrate.
  88 console=tty0                            = console on the first virtual terminal.
  89 mtdoops.mtddev=2                        = Kernel oops (and panics) will be written to the third NAND parition /dev/mtd2
  90
  91 strings /dev/mtd2 to read them.
  92
  93 RescueOS should be booting now.
  94
  95
  96 Booting the initrd
  97 ~~~~~~~~~~~~~~~
  98 The initrd has actually the same features as the tarball.
  99 But you can not store persistent data, e.g. WiFi firmwares from maemo
 100 as everything happens in RAM. This method is sureley still prefered by many people.
 101
 102 flasher-3.5 -k 2.6.37 -n initrd.img -l -b"rootdelay root=/dev/ram0
 103
 104 wait for "suitable device not found..." and connect the N900 to your
 105 Linux box through USB.
 106
 107
 108
 109 ~~~~~~~~~~~~~~~
 110 How to use it
 111 ~~~~~~~~~~~~~~~
 112 The system asks you on the first boot if you want to copy maemo's
 113 firmware files for the wlan card to RescueOS. You won't see this
 114 question on the initrd image.
 115
 116 After that you get a bash shell.
 117
 118 The folder /rescueOS/ contains some scripts for various tasks. Not all of them
 119 are completed yet. They help you with the usual stuff, e.g. mass-storage
 120 mode, maemo root mounting, usbnetworking, WiFi setup etc.
 121
 122 Mounting maemo root
 123 -------------------
 124 /rescueOS/mount-maemo-root.sh
 125 This scripts mounts the maemo root to /mnt/maemo.
 126
 127 /rescueOS/umount-maemo-root.sh
 128
 129 USB Networking
 130 -------------
 131 /rescueOS/usbnetworking-enable.sh
 132 Sets up USB networking in the following way:
 133 ifconfig usb0 192.168.2.15 up
 134 ifconfig usb0 netmask 255.255.255.0
 135 route add 192.168.2.14 usb0
 136
 137 To disable it: /rescueOS/usbnetworking-disable.sh
 138
 139 USB Mass-Storage mode
 140 --------------------
 141 /rescueOS/mass-storage-enable.sh
 142 Makes /dev/mmcblk1p1 and /dev/mmcblk1p2 available for the mass-storage
 143 mode. These are the EMMC home partition and MyDocs in maemo.
 144
 145 /rescueOS/mass-storage-disable.sh: Deactivates mass-storage mode.
 146
 147
 148 WiFi support
 149 ------------
 150 It has wpa_supplicant, but without EAP support. This should be ok for
 151 most home networks which use a PSK.
 152
 153 Give the following a try:
 154
 155 wpa_passphrase [essid] [password] > /wlan.conf
 156 sh /rescueOS/setup-wpa-wifi.sh
 157
 158 For DHCP, use udhcpc -i wlan0.
 159
 160 You need the firmware files of course: /rescueOS/firmware-from-maemo.sh
 161
 162 Shutdown
 163 --------
 164 poweroff
 165
 166 Root password
 167 -------------
 168 rootme
 169
 170
 171 Contributions and suggestions are welcome. Write to me (NIN101 on freenode).
 172
 173
 174
 175
 176
 177
 178