manual/advanced_topics/archos-flashing.tex

   1 \section{\label{ref:Rockboxinflash}Rockbox in flash}
   2 \fixme{These instructions are outdated!!. This section is a copy of the wikipage FlashingRockbox revision r.1.19.}
   3
   4 \warn{Flashing Rockbox is optional. It is not required for using Rockbox on your
   5   \playername. Please read the whole section thoroughly before flashing.
   6 }
   7
   8 \subsection{Introduction}
   9 Flashing in the sense used here and elsewhere in regard to Rockbox means
  10 reprogramming the flash memory of the \playerman\ unit.
  11
  12 When you bought your \playerman, it came with the \playerman\ firmware flashed.
  13 Now, you can add Rockbox to the built-in software.
  14
  15 \subsection{Terminology}
  16 \begin{description}
  17 \item[Firmware: ] The flash ROM content as a whole.
  18 \item[Image: ] Means one operating software started from there
  19 \end{description}
  20
  21 By reprogramming the firmware, we can boot much faster. \playerman\ has an
  22 unnecessary slow boot loader, versus the boot time for Rockbox is much faster
  23 than the disk spin-up, in fact it has to wait for the disk. Your boot time will
  24 be as quick as a disk spin-up (e.g. 4 seconds from power-up until resuming
  25 playback).
  26
  27 \subsection{Method}
  28
  29 The replaced firmware will host a boot loader and 2 images. This is possible by
  30 compression. The first is the \emph{permanent} backup, not to be changed any
  31 more.The second is the default one to be started, the first is only used when
  32 you hold the \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} -key during start. Like supplied here, the first image
  33 is the original Archos firmware, the second is empty, left for you to program
  34 and update. It can contain anything you like. If you prefer, you can program
  35 the Archos firmware to there, too.
  36
  37 \note{For now, the binary contained in the brand new player flash package does
  38 contain Rockbox built from current CVS in the second image slot. This is to
  39 lower the risk of flashing (at least one of the images will hopefully work) in
  40 case you don't program a second image yourself in the first step. Of course the
  41 second image can be replaced like with the other models.}
  42
  43 There are two programming tools supplied:
  44
  45 \begin{itemize}
  46 \item The first one is called \fname{firmware\_flash.rock} and is used to
  47   program the whole flash with a new content. You can also use it to revert
  48   back to the original firmware you've hopefully backup-ed. In the ideal case,
  49   you'll need this tool only once. You can view this as "formatting" the flash
  50   with the desired image structure.
  51 \item The second one is called \fname{rockbox\_flash.rock} and is used to
  52   reprogram only the second image. It won't touch any other byte, should be
  53   safe to fool around with. If the programmed firmware is in-operational, you
  54   can still use the \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} start with the Archos firmware and Rockbox booted
  55   from disk to try better.
  56 \end{itemize}
  57
  58 The non-user tools are in the \fname{flash} subdirectory of the CVS source
  59 files. There's an authoring tool which composed the firmware file with the
  60 boot loader and the 2 images. The boot loader project, a firmware extraction
  61 tool, the plugin sources, and the tools for the UART boot feature: a monitor
  62 program for the box and a PC tool to drive it. Feel free to review the sources
  63 for all of it, but be careful when fooling around with powerful toys!
  64
  65 \subsection{Risks}
  66 Well, is it dangerous? Yes, certainly, like programming a mainboard
  67 \emph{BIOS}, \emph{CD/DVD} drive firmware, mobile phone, etc. If the power
  68 fails, your chip breaks while programming or most of all the programming
  69 software malfunctions, you'll have a dead box. We take no responsibility of any
  70 kind, you do that at your own risk. However, we tried as carefully as possible
  71 to bulletproof this code. The new firmware file is completely read before it
  72 starts programming, there are a lot of sanity checks. If any fails, it will not
  73 program. Before releasing this, we have checked the flow with exactly these
  74 files supplied here, starting from the original firmware in flash. It worked
  75 reliably, there's no reason why such low level code should behave different on
  76 your box.
  77
  78 \opt{player}{
  79   \warn{The risk is slightly higher for player flashing, because:
  80     \begin{itemize}
  81       \item This is brand new
  82       \item It could not be tested with all hardware versions.
  83     \end{itemize}
  84     Refer to this e-mail:
  85     \url{http://www.rockbox.org/mail/archive/rockbox-archive-2004-12/0245.shtml}
  86   }
  87 }
  88
  89 There's one ultimate safety net to bring back boxes with even completely
  90 garbled flash content: the \emph{UART} boot mod, which in turn requires the
  91 serial mod. It can bring the dead back to life, with that it's possible to
  92 re-flash independently from the outside, even if the flash is completely erased.
  93 It has been used that during development, else Rockbox in flash wouldn't have
  94 been possible. Extensive development effort went into the exploitation of the
  95 UART boot mod. Mechanically adept users with good soldering skills can easily
  96 perform these mods. Others may feel uncomfortable using the first tool
  97 (\fname{firmware\_flash.rock}) for re-flashing the firmware.
  98
  99
 100 To comfort you a bit again: If you are starting with a known-good image, you
 101 are unlikely to experience problems. The flash tools have been stable for quite
 102 a while. Several users have used them extensively, even flashing while playing!
 103 Although it worked, it's not the recommended method.
 104
 105 About the safety of operation: Since we have dual boot, you're not giving up
 106 the Archos firmware. It's still there when you hold
 107 \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} during startup. So even if Rockbox from flash is not 100\% stable for
 108 everyone, you can still use the box, re-flash the second image with an updated
 109 Rockbox copy, etc.
 110
 111 The flash chip being used by Archos is specified for 100,000 cycles, so you don't need to worry about that wearing out.
 112
 113 \subsection{Requirements}
 114 You need two things:
 115 \begin{itemize}
 116 \item The first is a \playername. Be sure you're using the correct package,
 117   they are different!
 118 \item Second, you need an in-circuit programmable flash. \opt{recorder,recorderv2fm,player}{The older chips are not flashable.}\opt{ondio}{This should always
 119   be flashable on Ondios, because Archos does itself provide flash updates for
 120   these.} You can find out via Rockbox (\setting{Info $\rightarrow$ Debug $\rightarrow$ Hardware Info}). If the flash info gives you question marks (Flash M=?? D=??),
 121   you're out of luck. The only chance then is to solder in the right chip
 122   (SST39VF020), at best with the firmware already in. If the chip is blank,
 123   you'll need the UART boot mod as well.
 124 \end{itemize}
 125
 126 \subsection{Flashing procedure}
 127 Short explanation: copy the \fname{firmware\_*.bin} files for your model from the
 128 distribution to the root directory of your \dap, then run the
 129 \fname{firmware\_flash.rock} plugin.
 130 Long version, step by step procedure:
 131 \begin{enumerate}
 132 \item Completely install the Rockbox version you want to have in flash, from a
 133   full \fname{.zip} distribution, including all the plugins, etc.
 134 \item Back up the current firmware, using the first option of the debug menu
 135   (\setting{Info $\rightarrow$ Debug $\rightarrow$ Dump ROM Contents}).
 136   This creates 2 files in the root directory, which you may not immediately see
 137   in the Rockbox browser. The 256kB-sized \fname{internal\_rom\_2000000-203FFFF.bin} one is your present firmware. Back  both up to your PC. You will need them if
 138   you want to restore the flash contents.
 139 \item Download the correct package for you model. Copy one or two files of it to
 140   your box: \fname{firmware\_*.bin} (name depends on your model) into the root
 141   directory (the initial firmware for your model, with the boot loader and the
 142   Archos image). There now is also a \_norom variant, copy both, the plugin will
 143   decide which one is required for your box.
 144 \item Enter the debug menu and select the hardware info screen. Check your flash
 145   IDs (bottom line), and please make a note about your \opt{recorder,recorderv2fm,ondio}{hardware mask value}\opt{player}{ROM version}. The latter is just for our
 146   curiosity, not needed for the flow. If the flash info shows question  marks,
 147   you can stop here, sorry.
 148 \item Use the \opt{recorder,recorderv2fm}{\ButtonFTwo\ settings or }the menu (\setting{General settings $\rightarrow$ File view $\rightarrow$ Show files}) to
 149   configure seeing all files within the browser.
 150 \item Connect the charger and make sure your batteries are also in good shape.
 151   That's just for security reasons, it's not that flashing needs more power.
 152 \item Run the \fname{firmware\_flash.rock} plugin. It again tells you about your
 153   flash and the file it's gonna program. After \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} it checks the file. Your
 154   hardware mask value will be kept, it won't overwrite it. Hitting \opt{recorder,recorderv2fm}{\ButtonFTwo}\opt{ondio}{\ButtonUp}\opt{player}{\ButtonOn} gives you
 155   a big warning. If we still didn't manage to scare you off, you can hit\opt{recorder,recorderv2fm}{\ButtonFThree}\opt{ondio}{\ButtonRight}\opt{player}{\ButtonRight} to actually program and verify. The programming takes just a few seconds. If
 156   the sanity check fails, you have the wrong kind of boot ROM and are out of luck
 157   by now, sorry.
 158 \item In the unlikely event that the programming should give you any error, don't
 159   switch off the box! Otherwise you'll have seen it working for the last time.
 160   While Rockbox is still in DRAM and operational, we could upgrade the plugin via
 161   USB and try again. If you switch it off, it's gone.
 162 \end{enumerate}
 163
 164 \nopt{player}{
 165 Now the initial procedure is done. Since the second half of the flash is still
 166 empty, there is ``just'' the Archos image starting when you reboot now. Not much
 167 has changed yet. The Archos software starts a bit quicker than usual, then loads
 168 Rockbox from disk. The fun really starts when you add Rockbox to the flash, as
 169 described in the next section.
 170 }
 171
 172 \note{You may delete the \fname{.bin} files now.}
 173
 174 \subsection{Bringing in a Rockbox build}
 175 Short version: very easy, just play an \fname{.ucl} file like
 176 \fname{rockbox.ucl} from a release or build:
 177
 178 \begin{itemize}
 179 \item Make sure you are running the same version that you are trying to flash:
 180   play the \fname{ajbrec.ajz} file.
 181 \item  Enter the \fname{.rockbox} directory in the file browser (you might need
 182   to set the \setting{File View} option to \setting{All Files}).
 183 \item Play the \fname{rockbox.ucl} file (or \fname{rombox.ucl} if you want to
 184   flash ROMBox)
 185 \end{itemize}
 186
 187 Long version:
 188
 189 The second image is the working copy, the \fname{rockbox\_flash.rock} plugin from
 190 this package re-programs it. The plugins needs to be consistent with the Rockbox
 191 plugin API version, otherwise it will detect mismatch and won't run.
 192
 193 It requires an exotic input, a UCL-compressed image, because that's the internal
 194 format. UCL is a nice open-source compression library. The decompression is very
 195 fast and less than a page of C-code. The efficiency is even better than Zip with
 196 maximum compression, reduces file size to about 58\% of the original size. For
 197 details on UCL, see \url{http://www.oberhumer.com/opensource/ucl/}.
 198
 199 Rockbox developers using Linux will have to download it from there and compile
 200 it. For Win32 and Cygwin the executables are next to the packages. The sample
 201 program from that download is called \fname{uclpack}. We'll use that to compress
 202 \fname{rockbox.bin} which is the result of the compilation. This is a part of the
 203 build process meanwhile. If you compile Rockbox yourself, you should copy
 204 \fname{uclpack} to a directory which is in the path, we recommend placing it in
 205 the same directory as SH compiler.
 206
 207
 208 Here are the steps:
 209
 210 \begin{enumerate}
 211 \item Normally, you'll simply download a \fname{.zip} distribution. Copy all the
 212   content to the USB drive, replacing the old.
 213 \item Force a disk boot by holding \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} during power-up, or at least rolo into
 214   the new Rockbox version by \emph{Playing} the \fname{ajbrec.ajz}/fname{archos.mod} file. This may not always be necessary, but it's better to first run the
 215   version you're about to flash. It is required if you are currently running
 216   RomBox.
 217 \item Just \emph{play} the \fname{.ucl} file in the \fname{.rockbox} directory,
 218   this will kick off the \fname{rockbox\_flash.rock} plugin. It's a bit similar
 219   to the other one, but it's made different to make the user aware. It will check
 220   the file, available size, etc. With \opt{recorder,recorderv2fm}{\ButtonFTwo}\opt{ondio}{\ButtonUp}\opt{player}{\ButtonOn} it's being programmed. No need for
 221   warning this time. If it goes wrong, you'll still have the permanent image.
 222 \item When done, you can restart the box and hopefully your new Rockbox image.
 223 \end{enumerate}
 224
 225 You may find two \fname{.ucl} files in the \fname{.rockbox} folder. The
 226 classical, compressed one is \fname{rockbox.ucl}. If your model has enough flash
 227 space left, there may be an additional \fname{rombox.ucl}, which is uncompressed
 228 and can run directly from flash ROM, saving some RAM. The second way is the newer
 229 and now preferred one. Use this if available.
 230
 231 If you like or have to, you can also flash the Archos image as the second one.
 232 E.g. in case Rockbox from flash doesn't work for you. This way you keep the dual
 233 boot loader and you can easily try different later. The \fname{.ucl} of the Archos
 234 firmware is included in the package.
 235
 236 \subsection{Restoring the original firmware}
 237 If you'd like to revert to the original firmware, you can do like you did when
 238 you flashed Rockbox for the first time. You simply use the backup files you saved
 239 when flashing Rockbox for the first time and rename \fname{internal\_rom\_2000000-203FFFF.bin} to \fname{firmware\_*.bin} (name varies per model, use the filename that \fname{firmware\_flash.rock} asks for) and put it in the root.
 240
 241 \subsection{Known issues and limitations}
 242 Rockbox has a charging screen, but it is not 100\% perfect. You'll get it when
 243 the unit is off and you plug in the charger. The Rockbox charging algorithm is
 244 first measuring the battery voltage for about 40 seconds, after that it only
 245 starts charging when the capacity is below 85\%.
 246 \opt{recorder,recorderv2fm}{You can use the Archos charging (which always tops off) by holding \ButtonFOne\  while plugging in.}\opt{recorderv2fm}{Some FM users reported charging problems even with  \ButtonFOne, they had to revert to the original flash content.}
 247
 248 If the plugin API is changed, new builds may render the plugins incompatible.
 249 When updating, make sure you grab those too, and ROLO or \opt{recorder,recorderv2fm}{\ButtonFOne}\opt{ondio}{\ButtonLeft}\opt{player}{\ButtonLeft} boot into the
 250 new version before flashing it.
 251
 252 There are two variants of how the boxes starts, therefore the normal and the
 253 \_norom firmware files. The vast majority of the \daps\ all have the same boot
 254 ROM content, differentiation comes later by flash content. Rockbox identifies
 255 this boot ROM with a CRC value of 0x222F in the hardware info screen. \opt{recorder,recorderv2fm}{Some recorders have the boot ROM disabled (it might be unprogrammed) and start directly from a flash mirror at address zero. They need the new
 256   \_norom firmware that has a slightly different boot loader.}
 257 Without a boot ROM  there is no UART boot safety net. To compensate for that as
 258 much as possible the MiniMon monitor is included, it starts with \opt{recorder,recorderv2fm}{\ButtonFThree+\ButtonOn}\opt{ondio}{\ButtonRight+\ButtonOff}\opt{player}{\ButtonRight+\ButtonOn}.
 259 Using that the box can be reprogrammed via serial if the first 2000 bytes of the
 260 flash are OK.
 261
 262 \subsection{Download the new flash content file to your box}
 263 \fixme{These links are not valid. Refer to the wikipage BootBox for further
 264   instructions}
 265 Jens Arnold hosts flash content for download. Use the following url:
 266 \opt{player}{\url{http://www.jens-arnold.net/Rockbox/flash\_player.zip}}
 267 \opt{recorder}{\url{http://www.jens-arnold.net/Rockbox/flash\_rec.zip}}
 268 \opt{recorderv2fm}{\url{http://www.jens-arnold.net/Rockbox/flash\_fm.zip},
 269   \url{http://www.jens-arnold.net/Rockbox/flash\_v2.zip}}
 270 \opt{ondiofm}{\url{http://www.jens-arnold.net/Rockbox/flash\_ondiofm.zip}}
 271 \opt{ondiosp}{\url{http://www.jens-arnold.net/Rockbox/flash\_ondiosp.zip}}